XEmacs 21.4.15

diff --git a/ChangeLog b/ChangeLog
index 15489a2..807f735 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,79 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+
+2004-01-30  Vin Shelton  <acs@xemacs.org>
+
+       * etc/OXYMORONS: Inserted "Corporate Culture" for 21.4.15.
+
+2004-01-25  Steve Youngs  <youngs@xemacs.org>
+
+       * etc/package-index.LATEST.gpg: New, replaces
+       `package-index.LATEST.pgp'. 
+
+       * etc/package-index.LATEST.pgp: Removed, replaced with
+       `package-index.LATEST.gpg'. 
+
+2004-01-20  Jerry James  <james@xemacs.org>
+
+       * configure.in: The icc compiler pretends to be gcc.  It isn't.
+
+2003-11-28  Norbert Koch  <viteno@xemacs.org>
+
+       * etc/PACKAGES (ERC): new.
+
+2003-11-19  Vin Shelton  <acs@xemacs.org>
+
+       * configure.usage (--with-widgets): widgets now defaults to
+       --with-widgets=no.  Patch inspired by Jim Schumacher.
+
+2003-10-25  Norbert Koch  <viteno@xemacs.org>
+
+       * etc/PACKAGES (riece): New package.
+       * etc/PACKAGES (liece): Mark as deprecated.
+
+2003-10-26  Vin Shelton  <acs@xemacs.org>
+
+       * configure.in: Add Intel C++ compiler detection to compiler
+       version reporting.
+
+2003-10-16  Valdis Kletnieks <valdis.kletnieks@vt.edu>
+       * configure.in: record additional info about compiler and libc
+       versions, to assist in debugging.
+
+2003-08-28  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * configure.in (line 3573):
+       (Mule input methods):
+       Deprecate Motif for Linux.
+       (Installation): Report when LessTif is used.
+
+2003-10-11  Jerry James  <james@xemacs.org>
+
+       * configure.in: installexe.sh is under srcdir, not blddir.
+
+2003-10-16  Jerry James  <james@xemacs.org>
+       * aclocal.m4: Add icc (Intel compiler) support.
+       * configure.in: Ditto.
+
+2003-09-13  Martin Buchholz  <martin@xemacs.org>
+
+       * configure.in (OS_RELEASE): Add support for SunOS 5.10.
+       On current OSes produced by Sun, `uname -r' prints "5.9".
+       It seems likely that on future OSes, `uname -r' will print "5.10".
+       We need to accept multi-digit release numbers.
+
+2003-09-12  Rodney Sparapani <rsparapa@mcw.edu>
+
+       * PROBLEMS: Propose bash as an alternative to buggy Solaris
+       /bin/sh.
+
+2003-09-10  Martin Buchholz  <martin@xemacs.org>
+
+       * configure.in: XEmacs failed to build on Solaris9.
+       Solaris9 comes with /usr/demo/SOUND, but no headers or libraries
+       therein.
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/PROBLEMS b/PROBLEMS
index 7dca91c..93f8825 100644 (file)
--- a/PROBLEMS
+++ b/PROBLEMS
@@ -445,7 +445,14 @@ for just those modules.  (Or use gcc).
 
 This only occurs if you have LANG != C.  This is a known bug with
 /bin/sh fixed by installing Patch-ID# 101613-01.  Or, you can use
 
 This only occurs if you have LANG != C.  This is a known bug with
 /bin/sh fixed by installing Patch-ID# 101613-01.  Or, you can use

-bash, as a workaround.
+bash by setting the environment variable CONFIG_SHELL to /bin/bash
+
+*** Solaris 2.x configure fails: ./config.status: test: argument expected
+
+This is a known bug with /bin/sh and /bin/test, i.e. they do not
+support the XPG4 standard.  You can use bash as a workaround or an
+XPG4-compliant Bourne shell such as the Sun-supplied /usr/xpg4/bin/sh
+by setting the environment variable CONFIG_SHELL to /usr/xpg4/bin/sh

 
 *** On SunOS, you get linker errors
     ld: Undefined symbol
 
 *** On SunOS, you get linker errors
     ld: Undefined symbol

diff --git a/aclocal.m4 b/aclocal.m4
index 08c81c1..0dcfd2e 100644 (file)
--- a/aclocal.m4
+++ b/aclocal.m4
@@ -84,7 +84,7 @@ AC_MSG_CHECKING(how to produce PIC code)
 wl=
 
 can_build_shared=yes
 wl=
 
 can_build_shared=yes

-if test "$XEGCC" = yes; then
+if test "$XEGCC" = yes -o "$__ICC" = yes; then

   wl='-Wl,'
 
   case "$xehost_os" in
   wl='-Wl,'
 
   case "$xehost_os" in

@@ -243,7 +243,7 @@ cc_produces_so=no
 xldf=
 xcldf=
 AC_MSG_CHECKING(if C compiler can produce shared libraries)
 xldf=
 xcldf=
 AC_MSG_CHECKING(if C compiler can produce shared libraries)

-if test "$XEGCC" = yes; then
+if test "$XEGCC" = yes -o "$__ICC" = yes; then

   xcldf="-shared"
   xldf="-shared"
 else # Not using GCC
   xcldf="-shared"
   xldf="-shared"
 else # Not using GCC

diff --git a/configure b/configure
index 5df785f..3e6058c 100755 (executable)
--- a/configure
+++ b/configure
@@ -1423,9 +1423,14 @@ case "$canonical" in
     esac
 
     case "$canonical" in
     esac
 
     case "$canonical" in

-      *-solaris*         )
+      *-solaris* )

        opsys=sol2
        opsys=sol2

-       os_release=`uname -r | sed -e 's/^\([0-9]\)\.\([0-9]\).*/\1\2/'`
+       os_release_major=`uname -r | sed -e 's/^\([0-9]\{1,\}\)\.\([0-9]\{1,\}\).*/\1/'`
+       os_release_minor=`uname -r | sed -e 's/^\([0-9]\{1,\}\)\.\([0-9]\{1,\}\).*/\2/'`
+       case "$os_release_minor" in [0-9])
+         os_release_minor="0${os_release_minor}";;
+       esac
+       os_release="${os_release_major}${os_release_minor}"

        { test "$extra_verbose" = "yes" && cat << EOF
     Defining OS_RELEASE = $os_release
 EOF
        { test "$extra_verbose" = "yes" && cat << EOF
     Defining OS_RELEASE = $os_release
 EOF

@@ -1649,7 +1654,7 @@ xe_save_CFLAGS="$CFLAGS"
 # 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
 # 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:1653: checking for $ac_word" >&5
+echo "configure:1658: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -1676,7 +1681,7 @@ if test -z "$CC"; then
   # 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
   # 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:1680: checking for $ac_word" >&5
+echo "configure:1685: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -1724,7 +1729,7 @@ fi
       # 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
       # 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:1728: checking for $ac_word" >&5
+echo "configure:1733: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -1753,7 +1758,7 @@ fi
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6

-echo "configure:1757: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
+echo "configure:1762: 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'
 
 ac_ext=c
 xe_cppflags='$CPPFLAGS $c_switch_site $c_switch_machine $c_switch_system $c_switch_x_site $X_CFLAGS'

@@ -1766,12 +1771,12 @@ cross_compiling=no
 
 cat > conftest.$ac_ext << EOF
 
 
 cat > conftest.$ac_ext << EOF
 

-#line 1770 "configure"
+#line 1775 "configure"

 #include "confdefs.h"
 
 main(){return(0);}
 EOF
 #include "confdefs.h"
 
 main(){return(0);}
 EOF

-if { (eval echo configure:1775: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:1780: \"$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
   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

@@ -1799,19 +1804,19 @@ if test $ac_cv_prog_cc_works = no; then
   { 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: 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:1803: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
+echo "configure:1808: 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 "$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:1808: checking whether we are using GNU C" >&5
+echo "configure:1813: checking whether we are using GNU C" >&5

 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF
 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF

-if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:1815: \"$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:1820: \"$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
   ac_cv_prog_gcc=yes
 else
   ac_cv_prog_gcc=no

@@ -1829,7 +1834,7 @@ ac_test_CFLAGS="${CFLAGS+set}"
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6

-echo "configure:1833: checking whether ${CC-cc} accepts -g" >&5
+echo "configure:1838: checking whether ${CC-cc} accepts -g" >&5

 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then
 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then

@@ -1862,7 +1867,7 @@ if   test "$with_gcc" = "no"  -a "$GCC" = "yes"; then
   # 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
   # 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:1866: checking for $ac_word" >&5
+echo "configure:1871: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -1889,7 +1894,7 @@ if test -z "$CC"; then
   # 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
   # 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:1893: checking for $ac_word" >&5
+echo "configure:1898: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -1937,7 +1942,7 @@ fi
       # 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
       # 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:1941: checking for $ac_word" >&5
+echo "configure:1946: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -1966,7 +1971,7 @@ fi
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6

-echo "configure:1970: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
+echo "configure:1975: 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'
 
 ac_ext=c
 xe_cppflags='$CPPFLAGS $c_switch_site $c_switch_machine $c_switch_system $c_switch_x_site $X_CFLAGS'

@@ -1979,12 +1984,12 @@ cross_compiling=no
 
 cat > conftest.$ac_ext << EOF
 
 
 cat > conftest.$ac_ext << EOF
 

-#line 1983 "configure"
+#line 1988 "configure"

 #include "confdefs.h"
 
 main(){return(0);}
 EOF
 #include "confdefs.h"
 
 main(){return(0);}
 EOF

-if { (eval echo configure:1988: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:1993: \"$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
   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

@@ -2012,19 +2017,19 @@ if test $ac_cv_prog_cc_works = no; then
   { 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: 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:2016: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
+echo "configure:2021: 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 "$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:2021: checking whether we are using GNU C" >&5
+echo "configure:2026: checking whether we are using GNU C" >&5

 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF
 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF

-if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:2028: \"$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:2033: \"$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
   ac_cv_prog_gcc=yes
 else
   ac_cv_prog_gcc=no

@@ -2042,7 +2047,7 @@ ac_test_CFLAGS="${CFLAGS+set}"
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6

-echo "configure:2046: checking whether ${CC-cc} accepts -g" >&5
+echo "configure:2051: checking whether ${CC-cc} accepts -g" >&5

 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then
 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then

@@ -2075,7 +2080,7 @@ elif test "$with_gcc" = "yes" -a "$GCC" != "yes" ; then
   # 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
   # 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:2079: checking for $ac_word" >&5
+echo "configure:2084: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -2102,7 +2107,7 @@ if test -z "$CC"; then
   # 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
   # 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:2106: checking for $ac_word" >&5
+echo "configure:2111: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -2150,7 +2155,7 @@ fi
       # 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
       # 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:2154: checking for $ac_word" >&5
+echo "configure:2159: checking for $ac_word" >&5

 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.

@@ -2179,7 +2184,7 @@ fi
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6

-echo "configure:2183: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
+echo "configure:2188: 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'
 
 ac_ext=c
 xe_cppflags='$CPPFLAGS $c_switch_site $c_switch_machine $c_switch_system $c_switch_x_site $X_CFLAGS'

@@ -2192,12 +2197,12 @@ cross_compiling=no
 
 cat > conftest.$ac_ext << EOF
 
 
 cat > conftest.$ac_ext << EOF
 

-#line 2196 "configure"
+#line 2201 "configure"

 #include "confdefs.h"
 
 main(){return(0);}
 EOF
 #include "confdefs.h"
 
 main(){return(0);}
 EOF

-if { (eval echo configure:2201: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2206: \"$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
   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

@@ -2225,19 +2230,19 @@ if test $ac_cv_prog_cc_works = no; then
   { 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: 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:2229: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
+echo "configure:2234: 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 "$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:2234: checking whether we are using GNU C" >&5
+echo "configure:2239: checking whether we are using GNU C" >&5

 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF
 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF

-if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:2241: \"$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:2246: \"$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
   ac_cv_prog_gcc=yes
 else
   ac_cv_prog_gcc=no

@@ -2255,7 +2260,7 @@ ac_test_CFLAGS="${CFLAGS+set}"
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6

-echo "configure:2259: checking whether ${CC-cc} accepts -g" >&5
+echo "configure:2264: checking whether ${CC-cc} accepts -g" >&5

 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then
 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then

@@ -2292,7 +2297,7 @@ test -n "$CPP" -a -d "$CPP" && CPP=
 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
 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:2296: checking how to run the C preprocessor" >&5
+echo "configure:2301: checking how to run the C preprocessor" >&5

 # On Suns, sometimes $CPP names a directory.
 if test -n "$CPP" && test -d "$CPP"; then
   CPP=
 # On Suns, sometimes $CPP names a directory.
 if test -n "$CPP" && test -d "$CPP"; then
   CPP=

@@ -2305,13 +2310,13 @@ if test -z "$CPP"; then
   # On the NeXT, cc -E runs the code through the compiler's parser,
   # not just through cpp.
   cat > conftest.$ac_ext <<EOF
   # On the NeXT, cc -E runs the code through the compiler's parser,
   # not just through cpp.
   cat > conftest.$ac_ext <<EOF

-#line 2309 "configure"
+#line 2314 "configure"

 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:2315: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:2320: \"$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
   :
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   :

@@ -2322,13 +2327,13 @@ else
   rm -rf conftest*
   CPP="${CC-cc} -E -traditional-cpp"
   cat > conftest.$ac_ext <<EOF
   rm -rf conftest*
   CPP="${CC-cc} -E -traditional-cpp"
   cat > conftest.$ac_ext <<EOF

-#line 2326 "configure"
+#line 2331 "configure"

 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:2332: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:2337: \"$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
   :
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   :

@@ -2339,13 +2344,13 @@ else
   rm -rf conftest*
   CPP="${CC-cc} -nologo -E"
   cat > conftest.$ac_ext <<EOF
   rm -rf conftest*
   CPP="${CC-cc} -nologo -E"
   cat > conftest.$ac_ext <<EOF

-#line 2343 "configure"
+#line 2348 "configure"

 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:2349: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:2354: \"$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
   :
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   :

@@ -2371,9 +2376,9 @@ echo "$ac_t""$CPP" 1>&6
 
 
 echo $ac_n "checking for AIX""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for AIX""... $ac_c" 1>&6

-echo "configure:2375: checking for AIX" >&5
+echo "configure:2380: checking for AIX" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 2377 "configure"
+#line 2382 "configure"

 #include "confdefs.h"
 #ifdef _AIX
   yes
 #include "confdefs.h"
 #ifdef _AIX
   yes

@@ -2400,9 +2405,9 @@ rm -f conftest*
  
 
 echo $ac_n "checking for GNU libc""... $ac_c" 1>&6
  
 
 echo $ac_n "checking for GNU libc""... $ac_c" 1>&6

-echo "configure:2404: checking for GNU libc" >&5
+echo "configure:2409: checking for GNU libc" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 2406 "configure"
+#line 2411 "configure"

 #include "confdefs.h"
 #include <features.h>
 int main() {
 #include "confdefs.h"
 #include <features.h>
 int main() {

@@ -2414,7 +2419,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:2418: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:2423: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   have_glibc=yes
 else
   rm -rf conftest*
   have_glibc=yes
 else

@@ -2444,7 +2449,7 @@ cat >> confdefs.h <<\EOF
 EOF
 }
 
 EOF
 }
 

-      if test "$os_release" -ge 55; then
+      if test "$os_release" -ge 505; then

      { test "$extra_verbose" = "yes" && cat << \EOF
     Defining _XOPEN_SOURCE = 500
 EOF
      { test "$extra_verbose" = "yes" && cat << \EOF
     Defining _XOPEN_SOURCE = 500
 EOF

@@ -2491,7 +2496,7 @@ EOF
 esac
 
 cat > conftest.$ac_ext <<EOF
 esac
 
 cat > conftest.$ac_ext <<EOF

-#line 2495 "configure"
+#line 2500 "configure"

 #include "confdefs.h"
 int main () {
 #if defined __SUNPRO_C
 #include "confdefs.h"
 int main () {
 #if defined __SUNPRO_C

@@ -2500,12 +2505,14 @@ return 11;
 return 12;
 #elif defined __USLC__ && defined __SCO_VERSION__
 return 13;
 return 12;
 #elif defined __USLC__ && defined __SCO_VERSION__
 return 13;

+#elif defined __INTEL_COMPILER
+return 14;

 #else
 return 0;
 #endif
 }
 EOF
 #else
 return 0;
 #endif
 }
 EOF

-if { (eval echo configure:2509: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:2516: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   :
 else
 then
   :
 else

@@ -2514,9 +2521,11 @@ else
   cat conftest.$ac_ext >&5
   rm -fr conftest*
   case "$conftest_rc" in
   cat conftest.$ac_ext >&5
   rm -fr conftest*
   case "$conftest_rc" in

-  11) echo "You appear to be using the SunPro C compiler."; __SUNPRO_C=yes ;;
-  12) echo "You appear to be using the DEC C compiler."   ; __DECC=yes ;;
-  13) echo "You appear to be using the SCO C compiler."   ; __USLC__=yes ;;
+  11) echo "You appear to be using the SunPro C compiler." ; __SUNPRO_C=yes ;;
+  12) echo "You appear to be using the DEC C compiler."    ; __DECC=yes ;;
+  13) echo "You appear to be using the SCO C compiler."    ; __USLC__=yes ;;
+  14) echo "You appear to be using the Intel C++ compiler."; __ICC=yes
+            GCC=no ;;

 esac
 fi
 rm -fr conftest*
 esac
 fi
 rm -fr conftest*

@@ -2739,17 +2748,17 @@ test "$__DECC" = "yes" && c_switch_site="$c_switch_site -std1" &&  if test "$ext
 
 if test "$__USLC__" = yes; then
   echo $ac_n "checking for whether the -Kalloca compiler flag is needed""... $ac_c" 1>&6
 
 if test "$__USLC__" = yes; then
   echo $ac_n "checking for whether the -Kalloca compiler flag is needed""... $ac_c" 1>&6

-echo "configure:2743: checking for whether the -Kalloca compiler flag is needed" >&5
+echo "configure:2752: checking for whether the -Kalloca compiler flag is needed" >&5

   need_kalloca=no
   cat > conftest.$ac_ext <<EOF
   need_kalloca=no
   cat > conftest.$ac_ext <<EOF

-#line 2746 "configure"
+#line 2755 "configure"

 #include "confdefs.h"
 
 int main() {
 void *x = alloca(4);
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 void *x = alloca(4);
 ; return 0; }
 EOF

-if { (eval echo configure:2753: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2762: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   :
 else
   rm -rf conftest*
   :
 else

@@ -2760,14 +2769,14 @@ else
     xe_save_c_switch_system="$c_switch_system"
     c_switch_system="$c_switch_system -Kalloca"
     cat > conftest.$ac_ext <<EOF
     xe_save_c_switch_system="$c_switch_system"
     c_switch_system="$c_switch_system -Kalloca"
     cat > conftest.$ac_ext <<EOF

-#line 2764 "configure"
+#line 2773 "configure"

 #include "confdefs.h"
 
 int main() {
 void *x = alloca(4);
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 void *x = alloca(4);
 ; return 0; }
 EOF

-if { (eval echo configure:2771: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2780: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
    need_kalloca=yes 
 else
   rm -rf conftest*
    need_kalloca=yes 
 else

@@ -2802,13 +2811,15 @@ if test "$cflags_specified" = "no"; then
     CFLAGS="-O3"
   elif test "$CC" = "xlc"; then
     CFLAGS="-g -O3 -qstrict -qnoansialias -qlibansi -qinfo -qro -qmaxmem=20000"
     CFLAGS="-O3"
   elif test "$CC" = "xlc"; then
     CFLAGS="-g -O3 -qstrict -qnoansialias -qlibansi -qinfo -qro -qmaxmem=20000"

+  elif test "$__ICC" = "yes"; then
+    CFLAGS="-g -O3 -Ob2 -Wall -W1"

     else
     CFLAGS="-O" ;  fi
 fi
 
 if test "$GCC" = "yes"; then
 echo $ac_n "checking for buggy gcc versions""... $ac_c" 1>&6
     else
     CFLAGS="-O" ;  fi
 fi
 
 if test "$GCC" = "yes"; then
 echo $ac_n "checking for buggy gcc versions""... $ac_c" 1>&6

-echo "configure:2812: checking for buggy gcc versions" >&5
+echo "configure:2823: 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.*)
 GCC_VERSION=`$CC --version`
 case `uname -s`:`uname -m`:$GCC_VERSION in
                    *:sun4*:2.8.1|*:sun4*:egcs-2.90.*)

@@ -2866,7 +2877,7 @@ fi
 
 if test "$pdump" != "yes"; then
   echo $ac_n "checking for \"-z nocombreloc\" linker flag""... $ac_c" 1>&6
 
 if test "$pdump" != "yes"; then
   echo $ac_n "checking for \"-z nocombreloc\" linker flag""... $ac_c" 1>&6

-echo "configure:2870: checking for \"-z nocombreloc\" linker flag" >&5
+echo "configure:2881: checking for \"-z nocombreloc\" linker flag" >&5

   case "`ld --help 2>&1`" in
     *-z\ nocombreloc* ) echo "$ac_t""yes" 1>&6
       ld_switch_site="-z nocombreloc $ld_switch_site" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-z nocombreloc\" to \$ld_switch_site"; fi ;;
   case "`ld --help 2>&1`" in
     *-z\ nocombreloc* ) echo "$ac_t""yes" 1>&6
       ld_switch_site="-z nocombreloc $ld_switch_site" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-z nocombreloc\" to \$ld_switch_site"; fi ;;

@@ -2955,7 +2966,7 @@ test "$pdump" = "yes" && extra_objs="$extra_objs dumper.o" &&  if test "$extra_v
  fi
 
 echo $ac_n "checking for dynodump""... $ac_c" 1>&6
  fi
 
 echo $ac_n "checking for dynodump""... $ac_c" 1>&6

-echo "configure:2959: checking for dynodump" >&5
+echo "configure:2970: checking for dynodump" >&5

 if test "$unexec" != "unexsol2.o"; then
   echo "$ac_t""no" 1>&6
 else
 if test "$unexec" != "unexsol2.o"; then
   echo "$ac_t""no" 1>&6
 else

@@ -2993,12 +3004,12 @@ if test "$unexec" = "unexaix.o"; then
   done
   
 echo $ac_n "checking for terminateAndUnload in -lC""... $ac_c" 1>&6
   done
   
 echo $ac_n "checking for terminateAndUnload in -lC""... $ac_c" 1>&6

-echo "configure:2997: checking for terminateAndUnload in -lC" >&5
+echo "configure:3008: checking for terminateAndUnload in -lC" >&5

 ac_lib_var=`echo C'_'terminateAndUnload | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lC "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo C'_'terminateAndUnload | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lC "
 cat > conftest.$ac_ext <<EOF

-#line 3002 "configure"
+#line 3013 "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
 #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

@@ -3009,7 +3020,7 @@ int main() {
 terminateAndUnload()
 ; return 0; }
 EOF
 terminateAndUnload()
 ; return 0; }
 EOF

-if { (eval echo configure:3013: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3024: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -3117,7 +3128,7 @@ fi
 
 if test "$add_runtime_path" = "yes"; then
       echo $ac_n "checking "for runtime libraries flag"""... $ac_c" 1>&6
 
 if test "$add_runtime_path" = "yes"; then
       echo $ac_n "checking "for runtime libraries flag"""... $ac_c" 1>&6

-echo "configure:3121: checking "for runtime libraries flag"" >&5
+echo "configure:3132: checking "for runtime libraries flag"" >&5

   case "$opsys" in
     sol2 ) dash_r="-R" ;;
     decosf* | linux* | irix*) dash_r="-rpath " ;;
   case "$opsys" in
     sol2 ) dash_r="-R" ;;
     decosf* | linux* | irix*) dash_r="-rpath " ;;

@@ -3139,14 +3150,14 @@ if test "$GCC" = "yes"; then
   done
 fi
         cat > conftest.$ac_ext <<EOF
   done
 fi
         cat > conftest.$ac_ext <<EOF

-#line 3143 "configure"
+#line 3154 "configure"

 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF

-if { (eval echo configure:3150: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3161: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   dash_r="$try_dash_r"
 else
   rm -rf conftest*
   dash_r="$try_dash_r"
 else

@@ -3213,7 +3224,7 @@ xe_runpath_dir=`echo '' "$arg" | sed -e 's:^ ::' -e 's/^-L//'`
   eval "$xe_add_unique_runpath_dir"
 };; esac
     done
   eval "$xe_add_unique_runpath_dir"
 };; esac
     done

-        if test "$opsys $need_motif" = "sol2 yes"; then
+            if test "$opsys $need_motif" = "sol2 yes"; then

       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     fi
       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     fi

@@ -3247,10 +3258,10 @@ else
 fi
 after_morecore_hook_exists=yes
 echo $ac_n "checking for malloc_set_state""... $ac_c" 1>&6
 fi
 after_morecore_hook_exists=yes
 echo $ac_n "checking for malloc_set_state""... $ac_c" 1>&6

-echo "configure:3251: checking for malloc_set_state" >&5
+echo "configure:3262: checking for malloc_set_state" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3254 "configure"
+#line 3265 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char malloc_set_state(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char malloc_set_state(); below.  */

@@ -3273,7 +3284,7 @@ malloc_set_state();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:3277: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3288: \"$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
   rm -rf conftest*
   eval "ac_cv_func_malloc_set_state=yes"
 else

@@ -3293,16 +3304,16 @@ doug_lea_malloc=no
 fi
 
 echo $ac_n "checking whether __after_morecore_hook exists""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking whether __after_morecore_hook exists""... $ac_c" 1>&6

-echo "configure:3297: checking whether __after_morecore_hook exists" >&5
+echo "configure:3308: checking whether __after_morecore_hook exists" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 3299 "configure"
+#line 3310 "configure"

 #include "confdefs.h"
 extern void (* __after_morecore_hook)();
 int main() {
 __after_morecore_hook = 0
 ; return 0; }
 EOF
 #include "confdefs.h"
 extern void (* __after_morecore_hook)();
 int main() {
 __after_morecore_hook = 0
 ; return 0; }
 EOF

-if { (eval echo configure:3306: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3317: \"$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
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else

@@ -3358,7 +3369,7 @@ fi
 # 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
 # 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:3362: checking for $ac_word" >&5
+echo "configure:3373: checking for $ac_word" >&5

 
 if test -n "$RANLIB"; then
   ac_cv_prog_RANLIB="$RANLIB" # Let the user override the test.
 
 if test -n "$RANLIB"; then
   ac_cv_prog_RANLIB="$RANLIB" # Let the user override the test.

@@ -3413,7 +3424,7 @@ ac_configure=$ac_aux_dir/configure # This should be Cygnus configure.
 # 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
 # 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:3417: checking for a BSD compatible install" >&5
+echo "configure:3428: checking for a BSD compatible install" >&5

 if test -z "$INSTALL"; then
 
   IFS="${IFS=  }"; ac_save_IFS="$IFS"; IFS=":"
 if test -z "$INSTALL"; then
 
   IFS="${IFS=  }"; ac_save_IFS="$IFS"; IFS=":"

@@ -3467,7 +3478,7 @@ do
 # 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
 # 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:3471: checking for $ac_word" >&5
+echo "configure:3482: checking for $ac_word" >&5

 
 if test -n "$YACC"; then
   ac_cv_prog_YACC="$YACC" # Let the user override the test.
 
 if test -n "$YACC"; then
   ac_cv_prog_YACC="$YACC" # Let the user override the test.

@@ -3499,15 +3510,15 @@ for ac_hdr in   a.out.h   elf.h   cygwin/version.h   fcntl.h   inttypes.h   libg
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:3503: checking for $ac_hdr" >&5
+echo "configure:3514: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3506 "configure"
+#line 3517 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:3511: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:3522: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -3537,10 +3548,10 @@ fi
 done
 
 echo $ac_n "checking for sys/wait.h that is POSIX.1 compatible""... $ac_c" 1>&6
 done
 
 echo $ac_n "checking for sys/wait.h that is POSIX.1 compatible""... $ac_c" 1>&6

-echo "configure:3541: checking for sys/wait.h that is POSIX.1 compatible" >&5
+echo "configure:3552: checking for sys/wait.h that is POSIX.1 compatible" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3544 "configure"
+#line 3555 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/wait.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/wait.h>

@@ -3556,7 +3567,7 @@ wait (&s);
 s = WIFEXITED (s) ? WEXITSTATUS (s) : 1;
 ; return 0; }
 EOF
 s = WIFEXITED (s) ? WEXITSTATUS (s) : 1;
 ; return 0; }
 EOF

-if { (eval echo configure:3560: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3571: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_header_sys_wait_h=yes
 else
   rm -rf conftest*
   ac_cv_header_sys_wait_h=yes
 else

@@ -3580,10 +3591,10 @@ EOF
 fi
 
 echo $ac_n "checking for ANSI C header files""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for ANSI C header files""... $ac_c" 1>&6

-echo "configure:3584: checking for ANSI C header files" >&5
+echo "configure:3595: checking for ANSI C header files" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3587 "configure"
+#line 3598 "configure"

 #include "confdefs.h"
 #include <stdlib.h>
 #include <stdarg.h>
 #include "confdefs.h"
 #include <stdlib.h>
 #include <stdarg.h>

@@ -3591,7 +3602,7 @@ cat > conftest.$ac_ext <<EOF
 #include <float.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include <float.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:3595: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:3606: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -3608,7 +3619,7 @@ rm -f conftest*
 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
 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 3612 "configure"
+#line 3623 "configure"

 #include "confdefs.h"
 #include <string.h>
 EOF
 #include "confdefs.h"
 #include <string.h>
 EOF

@@ -3626,7 +3637,7 @@ fi
 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
 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 3630 "configure"
+#line 3641 "configure"

 #include "confdefs.h"
 #include <stdlib.h>
 EOF
 #include "confdefs.h"
 #include <stdlib.h>
 EOF

@@ -3644,7 +3655,7 @@ fi
 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
 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 3648 "configure"
+#line 3659 "configure"

 #include "confdefs.h"
 #include <ctype.h>
 #define ISLOWER(c) ('a' <= (c) && (c) <= 'z')
 #include "confdefs.h"
 #include <ctype.h>
 #define ISLOWER(c) ('a' <= (c) && (c) <= 'z')

@@ -3655,7 +3666,7 @@ if (XOR (islower (i), ISLOWER (i)) || toupper (i) != TOUPPER (i)) exit(2);
 exit (0); }
 
 EOF
 exit (0); }
 
 EOF

-if { (eval echo configure:3659: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:3670: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   :
 else
 then
   :
 else

@@ -3681,10 +3692,10 @@ EOF
 fi
 
 echo $ac_n "checking whether time.h and sys/time.h may both be included""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking whether time.h and sys/time.h may both be included""... $ac_c" 1>&6

-echo "configure:3685: checking whether time.h and sys/time.h may both be included" >&5
+echo "configure:3696: checking whether time.h and sys/time.h may both be included" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3688 "configure"
+#line 3699 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/time.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/time.h>

@@ -3693,7 +3704,7 @@ int main() {
 struct tm *tp;
 ; return 0; }
 EOF
 struct tm *tp;
 ; return 0; }
 EOF

-if { (eval echo configure:3697: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3708: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_header_time=yes
 else
   rm -rf conftest*
   ac_cv_header_time=yes
 else

@@ -3717,10 +3728,10 @@ EOF
 fi
 
 echo $ac_n "checking for sys_siglist declaration in signal.h or unistd.h""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for sys_siglist declaration in signal.h or unistd.h""... $ac_c" 1>&6

-echo "configure:3721: checking for sys_siglist declaration in signal.h or unistd.h" >&5
+echo "configure:3732: checking for sys_siglist declaration in signal.h or unistd.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3724 "configure"
+#line 3735 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <signal.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <signal.h>

@@ -3732,7 +3743,7 @@ int main() {
 char *msg = *(sys_siglist + 1);
 ; return 0; }
 EOF
 char *msg = *(sys_siglist + 1);
 ; return 0; }
 EOF

-if { (eval echo configure:3736: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3747: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_decl_sys_siglist=yes
 else
   rm -rf conftest*
   ac_cv_decl_sys_siglist=yes
 else

@@ -3758,9 +3769,9 @@ fi
 
 
 echo $ac_n "checking for utime""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for utime""... $ac_c" 1>&6

-echo "configure:3762: checking for utime" >&5
+echo "configure:3773: checking for utime" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 3764 "configure"
+#line 3775 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <utime.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <utime.h>

@@ -3768,7 +3779,7 @@ int main() {
 struct utimbuf x; x.actime = x.modtime = 0; utime ("/", &x);
 ; return 0; }
 EOF
 struct utimbuf x; x.actime = x.modtime = 0; utime ("/", &x);
 ; return 0; }
 EOF

-if { (eval echo configure:3772: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3783: \"$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
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
    { test "$extra_verbose" = "yes" && cat << \EOF

@@ -3787,10 +3798,10 @@ else
       for ac_func in utimes
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
       for ac_func in utimes
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:3791: checking for $ac_func" >&5
+echo "configure:3802: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3794 "configure"
+#line 3805 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -3813,7 +3824,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:3817: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3828: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -3845,10 +3856,10 @@ rm -f conftest*
 
 
 echo $ac_n "checking return type of signal handlers""... $ac_c" 1>&6
 
 
 echo $ac_n "checking return type of signal handlers""... $ac_c" 1>&6

-echo "configure:3849: checking return type of signal handlers" >&5
+echo "configure:3860: checking return type of signal handlers" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3852 "configure"
+#line 3863 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <signal.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <signal.h>

@@ -3865,7 +3876,7 @@ int main() {
 int i;
 ; return 0; }
 EOF
 int i;
 ; return 0; }
 EOF

-if { (eval echo configure:3869: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3880: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_type_signal=void
 else
   rm -rf conftest*
   ac_cv_type_signal=void
 else

@@ -3887,10 +3898,10 @@ EOF
 
 
 echo $ac_n "checking for size_t""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for size_t""... $ac_c" 1>&6

-echo "configure:3891: checking for size_t" >&5
+echo "configure:3902: checking for size_t" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3894 "configure"
+#line 3905 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS

@@ -3921,10 +3932,10 @@ EOF
 fi
 
 echo $ac_n "checking for pid_t""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for pid_t""... $ac_c" 1>&6

-echo "configure:3925: checking for pid_t" >&5
+echo "configure:3936: checking for pid_t" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3928 "configure"
+#line 3939 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS

@@ -3955,10 +3966,10 @@ EOF
 fi
 
 echo $ac_n "checking for uid_t in sys/types.h""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for uid_t in sys/types.h""... $ac_c" 1>&6

-echo "configure:3959: checking for uid_t in sys/types.h" >&5
+echo "configure:3970: checking for uid_t in sys/types.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 3962 "configure"
+#line 3973 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 EOF
 #include "confdefs.h"
 #include <sys/types.h>
 EOF

@@ -3994,10 +4005,10 @@ EOF
 fi
 
 echo $ac_n "checking for mode_t""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for mode_t""... $ac_c" 1>&6

-echo "configure:3998: checking for mode_t" >&5
+echo "configure:4009: checking for mode_t" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4001 "configure"
+#line 4012 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS

@@ -4028,10 +4039,10 @@ EOF
 fi
 
 echo $ac_n "checking for off_t""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for off_t""... $ac_c" 1>&6

-echo "configure:4032: checking for off_t" >&5
+echo "configure:4043: checking for off_t" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4035 "configure"
+#line 4046 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS

@@ -4062,10 +4073,10 @@ EOF
 fi
 
 echo $ac_n "checking for ssize_t""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for ssize_t""... $ac_c" 1>&6

-echo "configure:4066: checking for ssize_t" >&5
+echo "configure:4077: checking for ssize_t" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4069 "configure"
+#line 4080 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS

@@ -4097,9 +4108,9 @@ fi
 
 
 echo $ac_n "checking for socklen_t""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for socklen_t""... $ac_c" 1>&6

-echo "configure:4101: checking for socklen_t" >&5
+echo "configure:4112: checking for socklen_t" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 4103 "configure"
+#line 4114 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/socket.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/socket.h>

@@ -4109,7 +4120,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:4113: \"$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
 else
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else

@@ -4118,7 +4129,7 @@ else
   rm -rf conftest*
   
 cat > conftest.$ac_ext <<EOF
   rm -rf conftest*
   
 cat > conftest.$ac_ext <<EOF

-#line 4122 "configure"
+#line 4133 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/socket.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/socket.h>

@@ -4128,7 +4139,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:4132: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4143: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   
 echo "$ac_t""size_t" 1>&6
   rm -rf conftest*
   
 echo "$ac_t""size_t" 1>&6

@@ -4160,9 +4171,9 @@ fi
 rm -f conftest*
 
 echo $ac_n "checking for struct timeval""... $ac_c" 1>&6
 rm -f conftest*
 
 echo $ac_n "checking for struct timeval""... $ac_c" 1>&6

-echo "configure:4164: checking for struct timeval" >&5
+echo "configure:4175: checking for struct timeval" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 4166 "configure"
+#line 4177 "configure"

 #include "confdefs.h"
 #ifdef TIME_WITH_SYS_TIME
 #include <sys/time.h>
 #include "confdefs.h"
 #ifdef TIME_WITH_SYS_TIME
 #include <sys/time.h>

@@ -4178,7 +4189,7 @@ int main() {
 static struct timeval x; x.tv_sec = x.tv_usec;
 ; return 0; }
 EOF
 static struct timeval x; x.tv_sec = x.tv_usec;
 ; return 0; }
 EOF

-if { (eval echo configure:4182: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4193: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
   HAVE_TIMEVAL=yes
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
   HAVE_TIMEVAL=yes

@@ -4200,10 +4211,10 @@ fi
 rm -f conftest*
 
 echo $ac_n "checking whether struct tm is in sys/time.h or time.h""... $ac_c" 1>&6
 rm -f conftest*
 
 echo $ac_n "checking whether struct tm is in sys/time.h or time.h""... $ac_c" 1>&6

-echo "configure:4204: checking whether struct tm is in sys/time.h or time.h" >&5
+echo "configure:4215: checking whether struct tm is in sys/time.h or time.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4207 "configure"
+#line 4218 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <time.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <time.h>

@@ -4211,7 +4222,7 @@ int main() {
 struct tm *tp; tp->tm_sec;
 ; return 0; }
 EOF
 struct tm *tp; tp->tm_sec;
 ; return 0; }
 EOF

-if { (eval echo configure:4215: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4226: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_struct_tm=time.h
 else
   rm -rf conftest*
   ac_cv_struct_tm=time.h
 else

@@ -4235,10 +4246,10 @@ EOF
 fi
 
 echo $ac_n "checking for tm_zone in struct tm""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for tm_zone in struct tm""... $ac_c" 1>&6

-echo "configure:4239: checking for tm_zone in struct tm" >&5
+echo "configure:4250: checking for tm_zone in struct tm" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4242 "configure"
+#line 4253 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <$ac_cv_struct_tm>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <$ac_cv_struct_tm>

@@ -4246,7 +4257,7 @@ int main() {
 struct tm tm; tm.tm_zone;
 ; return 0; }
 EOF
 struct tm tm; tm.tm_zone;
 ; return 0; }
 EOF

-if { (eval echo configure:4250: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4261: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_struct_tm_zone=yes
 else
   rm -rf conftest*
   ac_cv_struct_tm_zone=yes
 else

@@ -4269,10 +4280,10 @@ EOF
 
 else
   echo $ac_n "checking for tzname""... $ac_c" 1>&6
 
 else
   echo $ac_n "checking for tzname""... $ac_c" 1>&6

-echo "configure:4273: checking for tzname" >&5
+echo "configure:4284: checking for tzname" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4276 "configure"
+#line 4287 "configure"

 #include "confdefs.h"
 #include <time.h>
 #ifndef tzname /* For SGI.  */
 #include "confdefs.h"
 #include <time.h>
 #ifndef tzname /* For SGI.  */

@@ -4282,7 +4293,7 @@ int main() {
 atoi(*tzname);
 ; return 0; }
 EOF
 atoi(*tzname);
 ; return 0; }
 EOF

-if { (eval echo configure:4286: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4297: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   ac_cv_var_tzname=yes
 else
   rm -rf conftest*
   ac_cv_var_tzname=yes
 else

@@ -4308,10 +4319,10 @@ fi
 
 
 echo $ac_n "checking for working const""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for working const""... $ac_c" 1>&6

-echo "configure:4312: checking for working const" >&5
+echo "configure:4323: checking for working const" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4315 "configure"
+#line 4326 "configure"

 #include "confdefs.h"
 
 int main() {
 #include "confdefs.h"
 
 int main() {

@@ -4360,7 +4371,7 @@ ccp = (char const *const *) p;
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:4364: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4375: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_c_const=yes
 else
   rm -rf conftest*
   ac_cv_c_const=yes
 else

@@ -4385,7 +4396,7 @@ fi
 
 
 echo $ac_n "checking whether ${MAKE-make} sets \${MAKE}""... $ac_c" 1>&6
 
 
 echo $ac_n "checking whether ${MAKE-make} sets \${MAKE}""... $ac_c" 1>&6

-echo "configure:4389: checking whether ${MAKE-make} sets \${MAKE}" >&5
+echo "configure:4400: checking whether ${MAKE-make} sets \${MAKE}" >&5

 set dummy ${MAKE-make}; ac_make=`echo "$2" | sed 'y%./+-%__p_%'`
 
 cat > conftestmake <<\EOF
 set dummy ${MAKE-make}; ac_make=`echo "$2" | sed 'y%./+-%__p_%'`
 
 cat > conftestmake <<\EOF

@@ -4410,12 +4421,12 @@ fi
 
 
 echo $ac_n "checking whether byte ordering is bigendian""... $ac_c" 1>&6
 
 
 echo $ac_n "checking whether byte ordering is bigendian""... $ac_c" 1>&6

-echo "configure:4414: checking whether byte ordering is bigendian" >&5
+echo "configure:4425: 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
 
 ac_cv_c_bigendian=unknown
 # See if sys/param.h defines the BYTE_ORDER macro.
 cat > conftest.$ac_ext <<EOF

-#line 4419 "configure"
+#line 4430 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/param.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/param.h>

@@ -4426,11 +4437,11 @@ int main() {
 #endif
 ; return 0; }
 EOF
 #endif
 ; return 0; }
 EOF

-if { (eval echo configure:4430: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4441: \"$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
   rm -rf conftest*
   # It does; now see whether it defined to BIG_ENDIAN or not.
 cat > conftest.$ac_ext <<EOF

-#line 4434 "configure"
+#line 4445 "configure"

 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/param.h>
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/param.h>

@@ -4441,7 +4452,7 @@ int main() {
 #endif
 ; return 0; }
 EOF
 #endif
 ; return 0; }
 EOF

-if { (eval echo configure:4445: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4456: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_c_bigendian=yes
 else
   rm -rf conftest*
   ac_cv_c_bigendian=yes
 else

@@ -4458,7 +4469,7 @@ fi
 rm -f conftest*
 if test $ac_cv_c_bigendian = unknown; then
 cat > conftest.$ac_ext <<EOF
 rm -f conftest*
 if test $ac_cv_c_bigendian = unknown; then
 cat > conftest.$ac_ext <<EOF

-#line 4462 "configure"
+#line 4473 "configure"

 #include "confdefs.h"
 main () {
   /* Are we little or big endian?  From Harbison&Steele.  */
 #include "confdefs.h"
 main () {
   /* Are we little or big endian?  From Harbison&Steele.  */

@@ -4471,7 +4482,7 @@ main () {
   exit (u.c[sizeof (long) - 1] == 1);
 }
 EOF
   exit (u.c[sizeof (long) - 1] == 1);
 }
 EOF

-if { (eval echo configure:4475: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4486: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_c_bigendian=no
 else
 then
   ac_cv_c_bigendian=no
 else

@@ -4498,10 +4509,10 @@ fi
 
 
 echo $ac_n "checking size of short""... $ac_c" 1>&6
 
 
 echo $ac_n "checking size of short""... $ac_c" 1>&6

-echo "configure:4502: checking size of short" >&5
+echo "configure:4513: checking size of short" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4505 "configure"
+#line 4516 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 main()
 #include "confdefs.h"
 #include <stdio.h>
 main()

@@ -4512,7 +4523,7 @@ main()
   exit(0);
 }
 EOF
   exit(0);
 }
 EOF

-if { (eval echo configure:4516: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4527: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_sizeof_short=`cat conftestval`
 else
 then
   ac_cv_sizeof_short=`cat conftestval`
 else

@@ -4540,10 +4551,10 @@ if test "$ac_cv_sizeof_short" = 0; then
   exit 1
 fi
 echo $ac_n "checking size of int""... $ac_c" 1>&6
   exit 1
 fi
 echo $ac_n "checking size of int""... $ac_c" 1>&6

-echo "configure:4544: checking size of int" >&5
+echo "configure:4555: checking size of int" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4547 "configure"
+#line 4558 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 main()
 #include "confdefs.h"
 #include <stdio.h>
 main()

@@ -4554,7 +4565,7 @@ main()
   exit(0);
 }
 EOF
   exit(0);
 }
 EOF

-if { (eval echo configure:4558: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4569: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_sizeof_int=`cat conftestval`
 else
 then
   ac_cv_sizeof_int=`cat conftestval`
 else

@@ -4576,10 +4587,10 @@ EOF
 
 
 echo $ac_n "checking size of long""... $ac_c" 1>&6
 
 
 echo $ac_n "checking size of long""... $ac_c" 1>&6

-echo "configure:4580: checking size of long" >&5
+echo "configure:4591: checking size of long" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4583 "configure"
+#line 4594 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 main()
 #include "confdefs.h"
 #include <stdio.h>
 main()

@@ -4590,7 +4601,7 @@ main()
   exit(0);
 }
 EOF
   exit(0);
 }
 EOF

-if { (eval echo configure:4594: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4605: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_sizeof_long=`cat conftestval`
 else
 then
   ac_cv_sizeof_long=`cat conftestval`
 else

@@ -4612,10 +4623,10 @@ EOF
 
 
 echo $ac_n "checking size of long long""... $ac_c" 1>&6
 
 
 echo $ac_n "checking size of long long""... $ac_c" 1>&6

-echo "configure:4616: checking size of long long" >&5
+echo "configure:4627: checking size of long long" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4619 "configure"
+#line 4630 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 main()
 #include "confdefs.h"
 #include <stdio.h>
 main()

@@ -4626,7 +4637,7 @@ main()
   exit(0);
 }
 EOF
   exit(0);
 }
 EOF

-if { (eval echo configure:4630: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4641: \"$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
 then
   ac_cv_sizeof_long_long=`cat conftestval`
 else

@@ -4648,10 +4659,10 @@ EOF
 
 
 echo $ac_n "checking size of void *""... $ac_c" 1>&6
 
 
 echo $ac_n "checking size of void *""... $ac_c" 1>&6

-echo "configure:4652: checking size of void *" >&5
+echo "configure:4663: checking size of void *" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4655 "configure"
+#line 4666 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 main()
 #include "confdefs.h"
 #include <stdio.h>
 main()

@@ -4662,7 +4673,7 @@ main()
   exit(0);
 }
 EOF
   exit(0);
 }
 EOF

-if { (eval echo configure:4666: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4677: \"$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
 then
   ac_cv_sizeof_void_p=`cat conftestval`
 else

@@ -4686,7 +4697,7 @@ EOF
 
 case $opsys in
   cygwin* ) cat > conftest.$ac_ext <<EOF
 
 case $opsys in
   cygwin* ) cat > conftest.$ac_ext <<EOF

-#line 4690 "configure"
+#line 4701 "configure"

 #include "confdefs.h"
 #include <cygwin/types.h>
 EOF
 #include "confdefs.h"
 #include <cygwin/types.h>
 EOF

@@ -4711,7 +4722,7 @@ rm -f conftest*
 esac
 
 echo $ac_n "checking for long file names""... $ac_c" 1>&6
 esac
 
 echo $ac_n "checking for long file names""... $ac_c" 1>&6

-echo "configure:4715: checking for long file names" >&5
+echo "configure:4726: 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:
 
 ac_cv_sys_long_file_names=yes
 # Test for long file names in all the places we know might matter:

@@ -4757,10 +4768,10 @@ fi
 
 
 echo $ac_n "checking for sin""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for sin""... $ac_c" 1>&6

-echo "configure:4761: checking for sin" >&5
+echo "configure:4772: checking for sin" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4764 "configure"
+#line 4775 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char sin(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char sin(); below.  */

@@ -4783,7 +4794,7 @@ sin();
 
 ; return 0; }
 EOF
 
 ; 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:4798: \"$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
   rm -rf conftest*
   eval "ac_cv_func_sin=yes"
 else

@@ -4801,12 +4812,12 @@ else
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for sin in -lm""... $ac_c" 1>&6
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for sin in -lm""... $ac_c" 1>&6

-echo "configure:4805: checking for sin in -lm" >&5
+echo "configure:4816: checking for sin in -lm" >&5

 ac_lib_var=`echo m'_'sin | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lm "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo m'_'sin | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lm "
 cat > conftest.$ac_ext <<EOF

-#line 4810 "configure"
+#line 4821 "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
 #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

@@ -4817,7 +4828,7 @@ int main() {
 sin()
 ; return 0; }
 EOF
 sin()
 ; return 0; }
 EOF

-if { (eval echo configure:4821: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4832: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -4861,14 +4872,14 @@ EOF
 
 
 cat > conftest.$ac_ext <<EOF
 
 
 cat > conftest.$ac_ext <<EOF

-#line 4865 "configure"
+#line 4876 "configure"

 #include "confdefs.h"
 #include <math.h>
 int main() {
 return atanh(1.0) + asinh(1.0) + acosh(1.0); 
 ; return 0; }
 EOF
 #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:4872: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4883: \"$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
   rm -rf conftest*
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_INVERSE_HYPERBOLIC

@@ -4885,14 +4896,14 @@ fi
 rm -f conftest*
 
 echo "checking type of mail spool file locking" 1>&6
 rm -f conftest*
 
 echo "checking type of mail spool file locking" 1>&6

-echo "configure:4889: checking type of mail spool file locking" >&5
+echo "configure:4900: 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
 for ac_func in lockf flock
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:4893: checking for $ac_func" >&5
+echo "configure:4904: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 4896 "configure"
+#line 4907 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -4915,7 +4926,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:4919: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4930: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -4997,12 +5008,12 @@ test "$mail_locking" = "locking" -a "$ac_cv_func_locking" != "yes" && \
 case "$opsys" in decosf*)
   
 echo $ac_n "checking for cma_open in -lpthreads""... $ac_c" 1>&6
 case "$opsys" in decosf*)
   
 echo $ac_n "checking for cma_open in -lpthreads""... $ac_c" 1>&6

-echo "configure:5001: checking for cma_open in -lpthreads" >&5
+echo "configure:5012: 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
 ac_lib_var=`echo pthreads'_'cma_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpthreads "
 cat > conftest.$ac_ext <<EOF

-#line 5006 "configure"
+#line 5017 "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
 #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

@@ -5013,7 +5024,7 @@ int main() {
 cma_open()
 ; return 0; }
 EOF
 cma_open()
 ; return 0; }
 EOF

-if { (eval echo configure:5017: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5028: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5050,7 +5061,7 @@ esac
 
 
 echo $ac_n "checking whether the -xildoff compiler flag is required""... $ac_c" 1>&6
 
 
 echo $ac_n "checking whether the -xildoff compiler flag is required""... $ac_c" 1>&6

-echo "configure:5054: checking whether the -xildoff compiler flag is required" >&5
+echo "configure:5065: 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;
 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;

@@ -5060,9 +5071,9 @@ if   ${CC-cc} '-###' -xildon  no_such_file.c 2>&1 | grep '^[^ ]*/ild ' > /dev/nu
 fi
 
 if test "$opsys" = "sol2"; then
 fi
 
 if test "$opsys" = "sol2"; then

-  if test "$os_release" -ge 56; then
+  if test "$os_release" -ge 506; then

     echo $ac_n "checking for \"-z ignore\" linker flag""... $ac_c" 1>&6
     echo $ac_n "checking for \"-z ignore\" linker flag""... $ac_c" 1>&6

-echo "configure:5066: checking for \"-z ignore\" linker flag" >&5
+echo "configure:5077: 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 ;;
     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 ;;

@@ -5073,7 +5084,7 @@ fi
 
 
 echo "checking "for specified window system"" 1>&6
 
 
 echo "checking "for specified window system"" 1>&6

-echo "configure:5077: checking "for specified window system"" >&5
+echo "configure:5088: checking "for specified window system"" >&5

 
 
 GNOME_CONFIG=no
 
 
 GNOME_CONFIG=no

@@ -5081,7 +5092,7 @@ GTK_CONFIG=no
 
 if test "$with_gnome" != "no"; then
    echo $ac_n "checking for GNOME configuration script""... $ac_c" 1>&6
 
 if test "$with_gnome" != "no"; then
    echo $ac_n "checking for GNOME configuration script""... $ac_c" 1>&6

-echo "configure:5085: checking for GNOME configuration script" >&5
+echo "configure:5096: checking for GNOME configuration script" >&5

    for possible in gnome-config
    do
       possible_version=`${possible} --version 2> /dev/null`
    for possible in gnome-config
    do
       possible_version=`${possible} --version 2> /dev/null`

@@ -5112,7 +5123,7 @@ fi
 
 if test "$with_gtk" != "no";then
    echo $ac_n "checking for GTK configuration script""... $ac_c" 1>&6
 
 if test "$with_gtk" != "no";then
    echo $ac_n "checking for GTK configuration script""... $ac_c" 1>&6

-echo "configure:5116: checking for GTK configuration script" >&5
+echo "configure:5127: checking for GTK configuration script" >&5

    for possible in gtk12-config gtk14-config gtk-config
    do
       possible_version=`${possible} --version 2> /dev/null`
    for possible in gtk12-config gtk14-config gtk-config
    do
       possible_version=`${possible} --version 2> /dev/null`

@@ -5134,18 +5145,18 @@ fi
 
 if test "${GTK_CONFIG}" != "no"; then
       echo $ac_n "checking gtk version""... $ac_c" 1>&6
 
 if test "${GTK_CONFIG}" != "no"; then
       echo $ac_n "checking gtk version""... $ac_c" 1>&6

-echo "configure:5138: checking gtk version" >&5
+echo "configure:5149: 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
       GTK_VERSION=`${GTK_CONFIG} --version`
       echo "$ac_t""${GTK_VERSION}" 1>&6
 
       echo $ac_n "checking gtk libs""... $ac_c" 1>&6

-echo "configure:5143: checking gtk libs" >&5
+echo "configure:5154: 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
       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:5149: checking gtk cflags" >&5
+echo "configure:5160: checking gtk cflags" >&5

       GTK_CFLAGS=`${GTK_CONFIG} --cflags`
       if test "$GCC" = "yes"; then
        GTK_CFLAGS="${GTK_CFLAGS} -Wno-shadow"
       GTK_CFLAGS=`${GTK_CONFIG} --cflags`
       if test "$GCC" = "yes"; then
        GTK_CFLAGS="${GTK_CFLAGS} -Wno-shadow"

@@ -5155,19 +5166,19 @@ echo "configure:5149: checking gtk cflags" >&5
 
       
 echo $ac_n "checking for main in -lgdk_imlib""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for main in -lgdk_imlib""... $ac_c" 1>&6

-echo "configure:5159: checking for main in -lgdk_imlib" >&5
+echo "configure:5170: 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
 ac_lib_var=`echo gdk_imlib'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdk_imlib "
 cat > conftest.$ac_ext <<EOF

-#line 5164 "configure"
+#line 5175 "configure"

 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF

-if { (eval echo configure:5171: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5182: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5189,12 +5200,12 @@ fi
 
       
 echo $ac_n "checking for Imlib_init in -lImlib""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for Imlib_init in -lImlib""... $ac_c" 1>&6

-echo "configure:5193: checking for Imlib_init in -lImlib" >&5
+echo "configure:5204: 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
 ac_lib_var=`echo Imlib'_'Imlib_init | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lImlib "
 cat > conftest.$ac_ext <<EOF

-#line 5198 "configure"
+#line 5209 "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
 #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

@@ -5205,7 +5216,7 @@ int main() {
 Imlib_init()
 ; return 0; }
 EOF
 Imlib_init()
 ; return 0; }
 EOF

-if { (eval echo configure:5209: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5220: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5228,10 +5239,10 @@ fi
       for ac_func in gdk_imlib_init
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
       for ac_func in gdk_imlib_init
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:5232: checking for $ac_func" >&5
+echo "configure:5243: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 5235 "configure"
+#line 5246 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -5254,7 +5265,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:5258: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5269: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -5333,15 +5344,15 @@ EOF
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:5337: checking for $ac_hdr" >&5
+echo "configure:5348: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 5340 "configure"
+#line 5351 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:5345: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:5356: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -5372,19 +5383,19 @@ done
 
       
 echo $ac_n "checking for main in -lxml""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for main in -lxml""... $ac_c" 1>&6

-echo "configure:5376: checking for main in -lxml" >&5
+echo "configure:5387: checking for main in -lxml" >&5

 ac_lib_var=`echo xml'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lxml "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo xml'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lxml "
 cat > conftest.$ac_ext <<EOF

-#line 5381 "configure"
+#line 5392 "configure"

 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF

-if { (eval echo configure:5388: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5399: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5406,19 +5417,19 @@ fi
 
       
 echo $ac_n "checking for main in -lglade""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for main in -lglade""... $ac_c" 1>&6

-echo "configure:5410: checking for main in -lglade" >&5
+echo "configure:5421: checking for main in -lglade" >&5

 ac_lib_var=`echo glade'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lglade "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo glade'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lglade "
 cat > conftest.$ac_ext <<EOF

-#line 5415 "configure"
+#line 5426 "configure"

 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF

-if { (eval echo configure:5422: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5433: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5440,19 +5451,19 @@ fi
 
       
 echo $ac_n "checking for main in -lglade-gnome""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for main in -lglade-gnome""... $ac_c" 1>&6

-echo "configure:5444: checking for main in -lglade-gnome" >&5
+echo "configure:5455: 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
 ac_lib_var=`echo glade-gnome'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lglade-gnome "
 cat > conftest.$ac_ext <<EOF

-#line 5449 "configure"
+#line 5460 "configure"

 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF

-if { (eval echo configure:5456: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5467: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5473,7 +5484,7 @@ fi
 
 
       cat > conftest.$ac_ext <<EOF
 
 
       cat > conftest.$ac_ext <<EOF

-#line 5477 "configure"
+#line 5488 "configure"

 #include "confdefs.h"
 #include <glade/glade-xml.h>
 EOF
 #include "confdefs.h"
 #include <glade/glade-xml.h>
 EOF

@@ -5532,7 +5543,7 @@ if test "$with_x11" != "no"; then
 # 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
 # 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:5536: checking for X" >&5
+echo "configure:5547: checking for X" >&5

 
 # Check whether --with-x or --without-x was given.
 if test "${with_x+set}" = set; then
 
 # Check whether --with-x or --without-x was given.
 if test "${with_x+set}" = set; then

@@ -5592,12 +5603,12 @@ if test "$ac_x_includes" = NO; then
 
   # First, try using that file with no special directory specified.
 cat > conftest.$ac_ext <<EOF
 
   # First, try using that file with no special directory specified.
 cat > conftest.$ac_ext <<EOF

-#line 5596 "configure"
+#line 5607 "configure"

 #include "confdefs.h"
 #include <$x_direct_test_include>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$x_direct_test_include>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:5601: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:5612: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -5666,14 +5677,14 @@ if test "$ac_x_libraries" = NO; then
   ac_save_LIBS="$LIBS"
   LIBS="-l$x_direct_test_library $LIBS"
 cat > conftest.$ac_ext <<EOF
   ac_save_LIBS="$LIBS"
   LIBS="-l$x_direct_test_library $LIBS"
 cat > conftest.$ac_ext <<EOF

-#line 5670 "configure"
+#line 5681 "configure"

 #include "confdefs.h"
 
 int main() {
 ${x_direct_test_function}()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 ${x_direct_test_function}()
 ; return 0; }
 EOF

-if { (eval echo configure:5677: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5688: \"$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.
   rm -rf conftest*
   LIBS="$ac_save_LIBS"
 # We can link X programs with no special library path.

@@ -5782,17 +5793,17 @@ else
     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
     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:5786: checking whether -R must be followed by a space" >&5
+echo "configure:5797: checking whether -R must be followed by a space" >&5

       ac_xsave_LIBS="$LIBS"; LIBS="$LIBS -R$x_libraries"
       cat > conftest.$ac_ext <<EOF
       ac_xsave_LIBS="$LIBS"; LIBS="$LIBS -R$x_libraries"
       cat > conftest.$ac_ext <<EOF

-#line 5789 "configure"
+#line 5800 "configure"

 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF

-if { (eval echo configure:5796: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5807: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   ac_R_nospace=yes
 else
   rm -rf conftest*
   ac_R_nospace=yes
 else

@@ -5808,14 +5819,14 @@ rm -f conftest*
       else
        LIBS="$ac_xsave_LIBS -R $x_libraries"
        cat > conftest.$ac_ext <<EOF
       else
        LIBS="$ac_xsave_LIBS -R $x_libraries"
        cat > conftest.$ac_ext <<EOF

-#line 5812 "configure"
+#line 5823 "configure"

 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 
 ; 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:5830: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   ac_R_space=yes
 else
   rm -rf conftest*
   ac_R_space=yes
 else

@@ -5851,12 +5862,12 @@ ac_cv_lib_dnet_dnet_ntoa=no
 else
 
 echo $ac_n "checking for dnet_ntoa in -ldnet""... $ac_c" 1>&6
 else
 
 echo $ac_n "checking for dnet_ntoa in -ldnet""... $ac_c" 1>&6

-echo "configure:5855: checking for dnet_ntoa in -ldnet" >&5
+echo "configure:5866: 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
 ac_lib_var=`echo dnet'_'dnet_ntoa | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldnet "
 cat > conftest.$ac_ext <<EOF

-#line 5860 "configure"
+#line 5871 "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
 #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

@@ -5867,7 +5878,7 @@ int main() {
 dnet_ntoa()
 ; return 0; }
 EOF
 dnet_ntoa()
 ; return 0; }
 EOF

-if { (eval echo configure:5871: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5882: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5891,12 +5902,12 @@ fi
     if test $ac_cv_lib_dnet_dnet_ntoa = no; then
       
 echo $ac_n "checking for dnet_ntoa in -ldnet_stub""... $ac_c" 1>&6
     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:5895: checking for dnet_ntoa in -ldnet_stub" >&5
+echo "configure:5906: 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
 ac_lib_var=`echo dnet_stub'_'dnet_ntoa | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldnet_stub "
 cat > conftest.$ac_ext <<EOF

-#line 5900 "configure"
+#line 5911 "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
 #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 +5918,7 @@ int main() {
 dnet_ntoa()
 ; return 0; }
 EOF
 dnet_ntoa()
 ; 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:5922: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -5936,10 +5947,10 @@ fi
     # 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
     # 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:5940: checking for gethostbyname" >&5
+echo "configure:5951: checking for gethostbyname" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 5943 "configure"
+#line 5954 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char gethostbyname(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char gethostbyname(); below.  */

@@ -5962,7 +5973,7 @@ gethostbyname();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:5966: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5977: \"$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
   rm -rf conftest*
   eval "ac_cv_func_gethostbyname=yes"
 else

@@ -5983,12 +5994,12 @@ fi
     if test $ac_cv_func_gethostbyname = no; then
       
 echo $ac_n "checking for gethostbyname in -lnsl""... $ac_c" 1>&6
     if test $ac_cv_func_gethostbyname = no; then
       
 echo $ac_n "checking for gethostbyname in -lnsl""... $ac_c" 1>&6

-echo "configure:5987: checking for gethostbyname in -lnsl" >&5
+echo "configure:5998: checking for gethostbyname in -lnsl" >&5

 ac_lib_var=`echo nsl'_'gethostbyname | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lnsl "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo nsl'_'gethostbyname | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lnsl "
 cat > conftest.$ac_ext <<EOF

-#line 5992 "configure"
+#line 6003 "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
 #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

@@ -5999,7 +6010,7 @@ int main() {
 gethostbyname()
 ; return 0; }
 EOF
 gethostbyname()
 ; return 0; }
 EOF

-if { (eval echo configure:6003: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6014: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6029,10 +6040,10 @@ fi
     # -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
     # -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:6033: checking for connect" >&5
+echo "configure:6044: checking for connect" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6036 "configure"
+#line 6047 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char connect(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char connect(); below.  */

@@ -6055,7 +6066,7 @@ connect();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:6059: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6070: \"$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
   rm -rf conftest*
   eval "ac_cv_func_connect=yes"
 else

@@ -6078,12 +6089,12 @@ fi
 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
 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:6082: checking "$xe_msg_checking"" >&5
+echo "configure:6093: 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
 ac_lib_var=`echo socket'_'connect | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lsocket $X_EXTRA_LIBS"
 cat > conftest.$ac_ext <<EOF

-#line 6087 "configure"
+#line 6098 "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
 #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

@@ -6094,7 +6105,7 @@ int main() {
 connect()
 ; return 0; }
 EOF
 connect()
 ; return 0; }
 EOF

-if { (eval echo configure:6098: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6109: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6118,10 +6129,10 @@ fi
 
     # gomez@mi.uni-erlangen.de says -lposix is necessary on A/UX.
     echo $ac_n "checking for remove""... $ac_c" 1>&6
 
     # gomez@mi.uni-erlangen.de says -lposix is necessary on A/UX.
     echo $ac_n "checking for remove""... $ac_c" 1>&6

-echo "configure:6122: checking for remove" >&5
+echo "configure:6133: checking for remove" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6125 "configure"
+#line 6136 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char remove(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char remove(); below.  */

@@ -6144,7 +6155,7 @@ remove();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:6148: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6159: \"$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
   rm -rf conftest*
   eval "ac_cv_func_remove=yes"
 else

@@ -6165,12 +6176,12 @@ fi
     if test $ac_cv_func_remove = no; then
       
 echo $ac_n "checking for remove in -lposix""... $ac_c" 1>&6
     if test $ac_cv_func_remove = no; then
       
 echo $ac_n "checking for remove in -lposix""... $ac_c" 1>&6

-echo "configure:6169: checking for remove in -lposix" >&5
+echo "configure:6180: checking for remove in -lposix" >&5

 ac_lib_var=`echo posix'_'remove | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lposix "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo posix'_'remove | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lposix "
 cat > conftest.$ac_ext <<EOF

-#line 6174 "configure"
+#line 6185 "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
 #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

@@ -6181,7 +6192,7 @@ int main() {
 remove()
 ; return 0; }
 EOF
 remove()
 ; return 0; }
 EOF

-if { (eval echo configure:6185: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6196: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6205,10 +6216,10 @@ fi
 
     # BSDI BSD/OS 2.1 needs -lipc for XOpenDisplay.
     echo $ac_n "checking for shmat""... $ac_c" 1>&6
 
     # BSDI BSD/OS 2.1 needs -lipc for XOpenDisplay.
     echo $ac_n "checking for shmat""... $ac_c" 1>&6

-echo "configure:6209: checking for shmat" >&5
+echo "configure:6220: checking for shmat" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6212 "configure"
+#line 6223 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char shmat(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char shmat(); below.  */

@@ -6231,7 +6242,7 @@ shmat();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:6235: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6246: \"$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
   rm -rf conftest*
   eval "ac_cv_func_shmat=yes"
 else

@@ -6252,12 +6263,12 @@ fi
     if test $ac_cv_func_shmat = no; then
       
 echo $ac_n "checking for shmat in -lipc""... $ac_c" 1>&6
     if test $ac_cv_func_shmat = no; then
       
 echo $ac_n "checking for shmat in -lipc""... $ac_c" 1>&6

-echo "configure:6256: checking for shmat in -lipc" >&5
+echo "configure:6267: checking for shmat in -lipc" >&5

 ac_lib_var=`echo ipc'_'shmat | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lipc "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo ipc'_'shmat | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lipc "
 cat > conftest.$ac_ext <<EOF

-#line 6261 "configure"
+#line 6272 "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
 #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

@@ -6268,7 +6279,7 @@ int main() {
 shmat()
 ; return 0; }
 EOF
 shmat()
 ; return 0; }
 EOF

-if { (eval echo configure:6272: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6283: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6304,12 +6315,12 @@ fi
 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
 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:6308: checking "$xe_msg_checking"" >&5
+echo "configure:6319: 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
 ac_lib_var=`echo ICE'_'IceConnectionNumber | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lICE $X_EXTRA_LIBS"
 cat > conftest.$ac_ext <<EOF

-#line 6313 "configure"
+#line 6324 "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
 #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

@@ -6320,7 +6331,7 @@ int main() {
 IceConnectionNumber()
 ; return 0; }
 EOF
 IceConnectionNumber()
 ; return 0; }
 EOF

-if { (eval echo configure:6324: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6335: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6366,15 +6377,15 @@ EOF
 
     ac_safe=`echo "Xm/Xm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xm/Xm.h""... $ac_c" 1>&6
 
     ac_safe=`echo "Xm/Xm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xm/Xm.h""... $ac_c" 1>&6

-echo "configure:6370: checking for Xm/Xm.h" >&5
+echo "configure:6381: checking for Xm/Xm.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6373 "configure"
+#line 6384 "configure"

 #include "confdefs.h"
 #include <Xm/Xm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <Xm/Xm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:6378: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:6389: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -6391,12 +6402,12 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   echo "$ac_t""yes" 1>&6
   
 echo $ac_n "checking for XmStringFree in -lXm""... $ac_c" 1>&6
   echo "$ac_t""yes" 1>&6
   
 echo $ac_n "checking for XmStringFree in -lXm""... $ac_c" 1>&6

-echo "configure:6395: checking for XmStringFree in -lXm" >&5
+echo "configure:6406: checking for XmStringFree in -lXm" >&5

 ac_lib_var=`echo Xm'_'XmStringFree | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xm'_'XmStringFree | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF

-#line 6400 "configure"
+#line 6411 "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
 #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

@@ -6407,7 +6418,7 @@ int main() {
 XmStringFree()
 ; return 0; }
 EOF
 XmStringFree()
 ; return 0; }
 EOF

-if { (eval echo configure:6411: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6422: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6506,7 +6517,7 @@ xe_runpath_dir=`echo '' "$arg" | sed -e 's:^ ::' -e 's/^-L//'`
   eval "$xe_add_unique_runpath_dir"
 };; esac
     done
   eval "$xe_add_unique_runpath_dir"
 };; esac
     done

-        if test "$opsys $need_motif" = "sol2 yes"; then
+            if test "$opsys $need_motif" = "sol2 yes"; then

       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     fi
       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     fi

@@ -6559,7 +6570,7 @@ EOF
 
 
     echo "checking for X defines extracted by xmkmf" 1>&6
 
 
     echo "checking for X defines extracted by xmkmf" 1>&6

-echo "configure:6563: checking for X defines extracted by xmkmf" >&5
+echo "configure:6574: checking for X defines extracted by xmkmf" >&5

   rm -fr conftestdir
   if mkdir conftestdir; then
     cd conftestdir
   rm -fr conftestdir
   if mkdir conftestdir; then
     cd conftestdir

@@ -6608,15 +6619,15 @@ EOF
 
     ac_safe=`echo "X11/Intrinsic.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Intrinsic.h""... $ac_c" 1>&6
 
     ac_safe=`echo "X11/Intrinsic.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Intrinsic.h""... $ac_c" 1>&6

-echo "configure:6612: checking for X11/Intrinsic.h" >&5
+echo "configure:6623: checking for X11/Intrinsic.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6615 "configure"
+#line 6626 "configure"

 #include "confdefs.h"
 #include <X11/Intrinsic.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Intrinsic.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:6620: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:6631: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -6640,12 +6651,12 @@ fi
 
       
 echo $ac_n "checking for XOpenDisplay in -lX11""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for XOpenDisplay in -lX11""... $ac_c" 1>&6

-echo "configure:6644: checking for XOpenDisplay in -lX11" >&5
+echo "configure:6655: checking for XOpenDisplay in -lX11" >&5

 ac_lib_var=`echo X11'_'XOpenDisplay | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo X11'_'XOpenDisplay | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF

-#line 6649 "configure"
+#line 6660 "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
 #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

@@ -6656,7 +6667,7 @@ int main() {
 XOpenDisplay()
 ; return 0; }
 EOF
 XOpenDisplay()
 ; return 0; }
 EOF

-if { (eval echo configure:6660: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6671: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6681,12 +6692,12 @@ fi
 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
 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:6685: checking "$xe_msg_checking"" >&5
+echo "configure:6696: 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
 ac_lib_var=`echo X11'_'XGetFontProperty | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 -b i486-linuxaout"
 cat > conftest.$ac_ext <<EOF

-#line 6690 "configure"
+#line 6701 "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
 #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

@@ -6697,7 +6708,7 @@ int main() {
 XGetFontProperty()
 ; return 0; }
 EOF
 XGetFontProperty()
 ; return 0; }
 EOF

-if { (eval echo configure:6701: \"$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_lib_$ac_lib_var=yes"
 else
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6724,12 +6735,12 @@ fi
 
     
 echo $ac_n "checking for XShapeSelectInput in -lXext""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for XShapeSelectInput in -lXext""... $ac_c" 1>&6

-echo "configure:6728: checking for XShapeSelectInput in -lXext" >&5
+echo "configure:6739: checking for XShapeSelectInput in -lXext" >&5

 ac_lib_var=`echo Xext'_'XShapeSelectInput | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXext "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xext'_'XShapeSelectInput | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXext "
 cat > conftest.$ac_ext <<EOF

-#line 6733 "configure"
+#line 6744 "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
 #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

@@ -6740,7 +6751,7 @@ int main() {
 XShapeSelectInput()
 ; return 0; }
 EOF
 XShapeSelectInput()
 ; return 0; }
 EOF

-if { (eval echo configure:6744: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6755: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6763,12 +6774,12 @@ fi
 
     
 echo $ac_n "checking for XtOpenDisplay in -lXt""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for XtOpenDisplay in -lXt""... $ac_c" 1>&6

-echo "configure:6767: checking for XtOpenDisplay in -lXt" >&5
+echo "configure:6778: checking for XtOpenDisplay in -lXt" >&5

 ac_lib_var=`echo Xt'_'XtOpenDisplay | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXt "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xt'_'XtOpenDisplay | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXt "
 cat > conftest.$ac_ext <<EOF

-#line 6772 "configure"
+#line 6783 "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
 #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

@@ -6779,7 +6790,7 @@ int main() {
 XtOpenDisplay()
 ; return 0; }
 EOF
 XtOpenDisplay()
 ; return 0; }
 EOF

-if { (eval echo configure:6783: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6794: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -6802,14 +6813,14 @@ fi
 
 
   echo $ac_n "checking the version of X11 being used""... $ac_c" 1>&6
 
 
   echo $ac_n "checking the version of X11 being used""... $ac_c" 1>&6

-echo "configure:6806: checking the version of X11 being used" >&5
+echo "configure:6817: checking the version of X11 being used" >&5

   cat > conftest.$ac_ext <<EOF
   cat > conftest.$ac_ext <<EOF

-#line 6808 "configure"
+#line 6819 "configure"

 #include "confdefs.h"
 #include <X11/Intrinsic.h>
     int main(int c, char *v[]) { return c>1 ? XlibSpecificationRelease : 0; }
 EOF
 #include "confdefs.h"
 #include <X11/Intrinsic.h>
     int main(int c, char *v[]) { return c>1 ? XlibSpecificationRelease : 0; }
 EOF

-if { (eval echo configure:6813: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:6824: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ./conftest foobar; x11_release=$?
 else
 then
   ./conftest foobar; x11_release=$?
 else

@@ -6840,10 +6851,10 @@ EOF
   for ac_func in XConvertCase
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
   for ac_func in XConvertCase
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:6844: checking for $ac_func" >&5
+echo "configure:6855: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6847 "configure"
+#line 6858 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -6866,7 +6877,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:6870: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6881: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -6898,15 +6909,15 @@ done
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:6902: checking for $ac_hdr" >&5
+echo "configure:6913: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6905 "configure"
+#line 6916 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:6910: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:6921: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -6939,10 +6950,10 @@ done
     for ac_func in XRegisterIMInstantiateCallback
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
     for ac_func in XRegisterIMInstantiateCallback
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:6943: checking for $ac_func" >&5
+echo "configure:6954: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 6946 "configure"
+#line 6957 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -6965,7 +6976,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:6969: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6980: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -6993,9 +7004,9 @@ fi
 done
 
   echo $ac_n "checking for standard XRegisterIMInstantiateCallback prototype""... $ac_c" 1>&6
 done
 
   echo $ac_n "checking for standard XRegisterIMInstantiateCallback prototype""... $ac_c" 1>&6

-echo "configure:6997: checking for standard XRegisterIMInstantiateCallback prototype" >&5
+echo "configure:7008: checking for standard XRegisterIMInstantiateCallback prototype" >&5

   cat > conftest.$ac_ext <<EOF
   cat > conftest.$ac_ext <<EOF

-#line 6999 "configure"
+#line 7010 "configure"

 #include "confdefs.h"
 
 #define NeedFunctionPrototypes 1
 #include "confdefs.h"
 
 #define NeedFunctionPrototypes 1

@@ -7007,7 +7018,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:7011: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:7022: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else

@@ -7028,12 +7039,12 @@ rm -f conftest*
 
     test -z "$with_xmu" && { 
 echo $ac_n "checking for XmuReadBitmapDataFromFile in -lXmu""... $ac_c" 1>&6
 
     test -z "$with_xmu" && { 
 echo $ac_n "checking for XmuReadBitmapDataFromFile in -lXmu""... $ac_c" 1>&6

-echo "configure:7032: checking for XmuReadBitmapDataFromFile in -lXmu" >&5
+echo "configure:7043: checking for XmuReadBitmapDataFromFile in -lXmu" >&5

 ac_lib_var=`echo Xmu'_'XmuReadBitmapDataFromFile | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXmu "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xmu'_'XmuReadBitmapDataFromFile | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXmu "
 cat > conftest.$ac_ext <<EOF

-#line 7037 "configure"
+#line 7048 "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
 #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

@@ -7044,7 +7055,7 @@ int main() {
 XmuReadBitmapDataFromFile()
 ; return 0; }
 EOF
 XmuReadBitmapDataFromFile()
 ; return 0; }
 EOF

-if { (eval echo configure:7048: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7059: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7083,19 +7094,19 @@ EOF
 
       
 echo $ac_n "checking for main in -lXbsd""... $ac_c" 1>&6
 
       
 echo $ac_n "checking for main in -lXbsd""... $ac_c" 1>&6

-echo "configure:7087: checking for main in -lXbsd" >&5
+echo "configure:7098: checking for main in -lXbsd" >&5

 ac_lib_var=`echo Xbsd'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXbsd "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xbsd'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXbsd "
 cat > conftest.$ac_ext <<EOF

-#line 7092 "configure"
+#line 7103 "configure"

 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF

-if { (eval echo configure:7099: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7110: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7119,7 +7130,7 @@ fi
     if test "$unexec" = "unexaix.o" -a "$x11_release" = "6"; then
         if test "$GCC" = "yes"; then
                   echo $ac_n "checking for name of AIX gcc threads option""... $ac_c" 1>&6
     if test "$unexec" = "unexaix.o" -a "$x11_release" = "6"; then
         if test "$GCC" = "yes"; then
                   echo $ac_n "checking for name of AIX gcc threads option""... $ac_c" 1>&6

-echo "configure:7123: checking for name of AIX gcc threads option" >&5
+echo "configure:7134: checking for name of AIX gcc threads option" >&5

       case `$CC -v --help 2>&1` in
         *-mthreads*) aix_threads=-mthreads ;;
                   *) aix_threads=-pthread  ;;
       case `$CC -v --help 2>&1` in
         *-mthreads*) aix_threads=-mthreads ;;
                   *) aix_threads=-pthread  ;;

@@ -7133,10 +7144,10 @@ echo "configure:7123: checking for name of AIX gcc threads option" >&5
          xe_save_CC="$CC"
          CC="${CC}_r"
          echo $ac_n "checking size of short""... $ac_c" 1>&6
          xe_save_CC="$CC"
          CC="${CC}_r"
          echo $ac_n "checking size of short""... $ac_c" 1>&6

-echo "configure:7137: checking size of short" >&5
+echo "configure:7148: checking size of short" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7140 "configure"
+#line 7151 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 main()
 #include "confdefs.h"
 #include <stdio.h>
 main()

@@ -7147,7 +7158,7 @@ main()
   exit(0);
 }
 EOF
   exit(0);
 }
 EOF

-if { (eval echo configure:7151: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:7162: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_sizeof_short=`cat conftestval`
 else
 then
   ac_cv_sizeof_short=`cat conftestval`
 else

@@ -7176,22 +7187,22 @@ EOF
 fi 
 if test "$with_msw" != "no"; then
   echo "checking for MS-Windows" 1>&6
 fi 
 if test "$with_msw" != "no"; then
   echo "checking for MS-Windows" 1>&6

-echo "configure:7180: checking for MS-Windows" >&5
+echo "configure:7191: checking for MS-Windows" >&5

   
 echo $ac_n "checking for main in -lgdi32""... $ac_c" 1>&6
   
 echo $ac_n "checking for main in -lgdi32""... $ac_c" 1>&6

-echo "configure:7183: checking for main in -lgdi32" >&5
+echo "configure:7194: checking for main in -lgdi32" >&5

 ac_lib_var=`echo gdi32'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdi32 "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo gdi32'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdi32 "
 cat > conftest.$ac_ext <<EOF

-#line 7188 "configure"
+#line 7199 "configure"

 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF

-if { (eval echo configure:7195: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7206: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7227,7 +7238,7 @@ EOF
       INSTALL_ARCH_DEP_SUBDIR="$INSTALL_ARCH_DEP_SUBDIR netinstall" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"netinstall\" to \$INSTALL_ARCH_DEP_SUBDIR"; fi
     fi
 
       INSTALL_ARCH_DEP_SUBDIR="$INSTALL_ARCH_DEP_SUBDIR netinstall" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"netinstall\" to \$INSTALL_ARCH_DEP_SUBDIR"; fi
     fi
 

-    install_pp="$blddir/lib-src/installexe.sh"
+    install_pp="$srcdir/lib-src/installexe.sh"

     libs_system="$libs_system -lshell32 -lgdi32 -luser32 -lcomdlg32 -lcomctl32 -lkernel32 -lwinspool" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"-lshell32 -lgdi32 -luser32 -lcomdlg32 -lcomctl32 -lkernel32 -lwinspool\" to \$libs_system"; fi
     test "$with_dragndrop" != no && dragndrop_proto="$dragndrop_proto msw" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"msw\" to \$dragndrop_proto"; fi
     if test "$window_system" != x11; then
     libs_system="$libs_system -lshell32 -lgdi32 -luser32 -lcomdlg32 -lcomctl32 -lkernel32 -lwinspool" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"-lshell32 -lgdi32 -luser32 -lcomdlg32 -lcomctl32 -lkernel32 -lwinspool\" to \$libs_system"; fi
     test "$with_dragndrop" != no && dragndrop_proto="$dragndrop_proto msw" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"msw\" to \$dragndrop_proto"; fi
     if test "$window_system" != x11; then

@@ -7264,12 +7275,12 @@ EOF
  fi
     fi
         cat > conftest.$ac_ext <<EOF
  fi
     fi
         cat > conftest.$ac_ext <<EOF

-#line 7268 "configure"
+#line 7279 "configure"

 #include "confdefs.h"
 #include <fcntl.h>
     int main() { return (open("/dev/windows", O_RDONLY, 0) > 0)? 0 : 1; }
 EOF
 #include "confdefs.h"
 #include <fcntl.h>
     int main() { return (open("/dev/windows", O_RDONLY, 0) > 0)? 0 : 1; }
 EOF

-if { (eval echo configure:7273: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:7284: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   need_event_unixoid=yes; { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_MSG_SELECT
 then
   need_event_unixoid=yes; { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_MSG_SELECT

@@ -7333,15 +7344,15 @@ fi
 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
 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:7337: checking for X11/extensions/shape.h" >&5
+echo "configure:7348: checking for X11/extensions/shape.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7340 "configure"
+#line 7351 "configure"

 #include "confdefs.h"
 #include <X11/extensions/shape.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/extensions/shape.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:7345: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7356: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -7393,7 +7404,7 @@ case "$x_libraries" in *X11R4* )
 esac
 
 echo "checking for WM_COMMAND option" 1>&6
 esac
 
 echo "checking for WM_COMMAND option" 1>&6

-echo "configure:7397: checking for WM_COMMAND option" >&5;
+echo "configure:7408: checking for WM_COMMAND option" >&5;

 if test "$with_wmcommand" != "no"; then
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_WMCOMMAND
 if test "$with_wmcommand" != "no"; then
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_WMCOMMAND

@@ -7408,15 +7419,15 @@ fi
 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
 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:7412: checking for X11/Xauth.h" >&5
+echo "configure:7423: checking for X11/Xauth.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7415 "configure"
+#line 7426 "configure"

 #include "confdefs.h"
 #include <X11/Xauth.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Xauth.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:7420: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7431: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -7439,12 +7450,12 @@ fi
  }
 test -z "$with_xauth" && { 
 echo $ac_n "checking for XauGetAuthByAddr in -lXau""... $ac_c" 1>&6
  }
 test -z "$with_xauth" && { 
 echo $ac_n "checking for XauGetAuthByAddr in -lXau""... $ac_c" 1>&6

-echo "configure:7443: checking for XauGetAuthByAddr in -lXau" >&5
+echo "configure:7454: checking for XauGetAuthByAddr in -lXau" >&5

 ac_lib_var=`echo Xau'_'XauGetAuthByAddr | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXau "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xau'_'XauGetAuthByAddr | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXau "
 cat > conftest.$ac_ext <<EOF

-#line 7448 "configure"
+#line 7459 "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
 #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

@@ -7455,7 +7466,7 @@ int main() {
 XauGetAuthByAddr()
 ; return 0; }
 EOF
 XauGetAuthByAddr()
 ; return 0; }
 EOF

-if { (eval echo configure:7459: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7470: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7500,15 +7511,15 @@ if test "$with_tooltalk" != "no" ; then
       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
       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:7504: checking for ${dir}tt_c.h" >&5
+echo "configure:7515: checking for ${dir}tt_c.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7507 "configure"
+#line 7518 "configure"

 #include "confdefs.h"
 #include <${dir}tt_c.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <${dir}tt_c.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:7512: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7523: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -7544,12 +7555,12 @@ if test "$with_tooltalk" != "no" ; then
 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
 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:7548: checking "$xe_msg_checking"" >&5
+echo "configure:7559: 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
 ac_lib_var=`echo tt'_'tt_message_create | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltt $extra_libs"
 cat > conftest.$ac_ext <<EOF

-#line 7553 "configure"
+#line 7564 "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
 #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

@@ -7560,7 +7571,7 @@ int main() {
 tt_message_create()
 ; return 0; }
 EOF
 tt_message_create()
 ; return 0; }
 EOF

-if { (eval echo configure:7564: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7575: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7617,15 +7628,15 @@ fi
 
 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
 
 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:7621: checking for Dt/Dt.h" >&5
+echo "configure:7632: checking for Dt/Dt.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7624 "configure"
+#line 7635 "configure"

 #include "confdefs.h"
 #include <Dt/Dt.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <Dt/Dt.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:7629: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7640: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -7648,12 +7659,12 @@ fi
  }
 test -z "$with_cde" && { 
 echo $ac_n "checking for DtDndDragStart in -lDtSvc""... $ac_c" 1>&6
  }
 test -z "$with_cde" && { 
 echo $ac_n "checking for DtDndDragStart in -lDtSvc""... $ac_c" 1>&6

-echo "configure:7652: checking for DtDndDragStart in -lDtSvc" >&5
+echo "configure:7663: checking for DtDndDragStart in -lDtSvc" >&5

 ac_lib_var=`echo DtSvc'_'DtDndDragStart | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lDtSvc "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo DtSvc'_'DtDndDragStart | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lDtSvc "
 cat > conftest.$ac_ext <<EOF

-#line 7657 "configure"
+#line 7668 "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
 #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

@@ -7664,7 +7675,7 @@ int main() {
 DtDndDragStart()
 ; return 0; }
 EOF
 DtDndDragStart()
 ; return 0; }
 EOF

-if { (eval echo configure:7668: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7679: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7737,7 +7748,7 @@ fi
 
 if test "$with_dragndrop" != "no" ; then
   echo $ac_n "checking if drag and drop API is needed""... $ac_c" 1>&6
 
 if test "$with_dragndrop" != "no" ; then
   echo $ac_n "checking if drag and drop API is needed""... $ac_c" 1>&6

-echo "configure:7741: checking if drag and drop API is needed" >&5
+echo "configure:7752: 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
   if test -n "$dragndrop_proto" ; then
     with_dragndrop=yes
     echo "$ac_t""yes (${dragndrop_proto} )" 1>&6

@@ -7757,18 +7768,18 @@ EOF
 fi
 
 echo "checking for LDAP" 1>&6
 fi
 
 echo "checking for LDAP" 1>&6

-echo "configure:7761: checking for LDAP" >&5
+echo "configure:7772: 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
 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:7764: checking for ldap.h" >&5
+echo "configure:7775: checking for ldap.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7767 "configure"
+#line 7778 "configure"

 #include "confdefs.h"
 #include <ldap.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <ldap.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:7772: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7783: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -7791,15 +7802,15 @@ fi
  }
 test -z "$with_ldap" && { ac_safe=`echo "lber.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for lber.h""... $ac_c" 1>&6
  }
 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:7795: checking for lber.h" >&5
+echo "configure:7806: checking for lber.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 7798 "configure"
+#line 7809 "configure"

 #include "confdefs.h"
 #include <lber.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <lber.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:7803: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7814: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -7823,12 +7834,12 @@ fi
 if test "$with_ldap" != "no"; then
   
 echo $ac_n "checking for ldap_search in -lldap""... $ac_c" 1>&6
 if test "$with_ldap" != "no"; then
   
 echo $ac_n "checking for ldap_search in -lldap""... $ac_c" 1>&6

-echo "configure:7827: checking for ldap_search in -lldap" >&5
+echo "configure:7838: 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
 ac_lib_var=`echo ldap'_'ldap_search | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap "
 cat > conftest.$ac_ext <<EOF

-#line 7832 "configure"
+#line 7843 "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
 #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

@@ -7839,7 +7850,7 @@ int main() {
 ldap_search()
 ; return 0; }
 EOF
 ldap_search()
 ; return 0; }
 EOF

-if { (eval echo configure:7843: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7854: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7864,12 +7875,12 @@ fi
 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
 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:7868: checking "$xe_msg_checking"" >&5
+echo "configure:7879: 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
 ac_lib_var=`echo ldap'_'ldap_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap -llber"
 cat > conftest.$ac_ext <<EOF

-#line 7873 "configure"
+#line 7884 "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
 #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

@@ -7880,7 +7891,7 @@ int main() {
 ldap_open()
 ; return 0; }
 EOF
 ldap_open()
 ; return 0; }
 EOF

-if { (eval echo configure:7884: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7895: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7905,12 +7916,12 @@ fi
 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
 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:7909: checking "$xe_msg_checking"" >&5
+echo "configure:7920: 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
 ac_lib_var=`echo ldap'_'ldap_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap -llber -lkrb"
 cat > conftest.$ac_ext <<EOF

-#line 7914 "configure"
+#line 7925 "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
 #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

@@ -7921,7 +7932,7 @@ int main() {
 ldap_open()
 ; return 0; }
 EOF
 ldap_open()
 ; return 0; }
 EOF

-if { (eval echo configure:7925: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7936: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -7946,12 +7957,12 @@ fi
 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
 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:7950: checking "$xe_msg_checking"" >&5
+echo "configure:7961: 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
 ac_lib_var=`echo ldap'_'ldap_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap -llber -lkrb -ldes"
 cat > conftest.$ac_ext <<EOF

-#line 7955 "configure"
+#line 7966 "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
 #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

@@ -7962,7 +7973,7 @@ int main() {
 ldap_open()
 ; return 0; }
 EOF
 ldap_open()
 ; return 0; }
 EOF

-if { (eval echo configure:7966: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7977: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8013,10 +8024,10 @@ EOF
   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
   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:8017: checking for $ac_func" >&5
+echo "configure:8028: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8020 "configure"
+#line 8031 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -8039,7 +8050,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:8043: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8054: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -8070,20 +8081,20 @@ fi
 
 if test "$with_postgresql" != "no"; then
   echo "checking for PostgreSQL" 1>&6
 
 if test "$with_postgresql" != "no"; then
   echo "checking for PostgreSQL" 1>&6

-echo "configure:8074: checking for PostgreSQL" >&5
+echo "configure:8085: 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
 
   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:8079: checking for ${header_dir}libpq-fe.h" >&5
+echo "configure:8090: checking for ${header_dir}libpq-fe.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8082 "configure"
+#line 8093 "configure"

 #include "confdefs.h"
 #include <${header_dir}libpq-fe.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #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:8087: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8098: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -8107,12 +8118,12 @@ fi
 
   test -n "$libpq_fe_h_file" && { 
 echo $ac_n "checking for PQconnectdb in -lpq""... $ac_c" 1>&6
 
   test -n "$libpq_fe_h_file" && { 
 echo $ac_n "checking for PQconnectdb in -lpq""... $ac_c" 1>&6

-echo "configure:8111: checking for PQconnectdb in -lpq" >&5
+echo "configure:8122: checking for PQconnectdb in -lpq" >&5

 ac_lib_var=`echo pq'_'PQconnectdb | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpq "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo pq'_'PQconnectdb | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpq "
 cat > conftest.$ac_ext <<EOF

-#line 8116 "configure"
+#line 8127 "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
 #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

@@ -8123,7 +8134,7 @@ int main() {
 PQconnectdb()
 ; return 0; }
 EOF
 PQconnectdb()
 ; return 0; }
 EOF

-if { (eval echo configure:8127: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8138: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8156,12 +8167,12 @@ EOF
 
     
 echo $ac_n "checking for PQconnectStart in -lpq""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for PQconnectStart in -lpq""... $ac_c" 1>&6

-echo "configure:8160: checking for PQconnectStart in -lpq" >&5
+echo "configure:8171: checking for PQconnectStart in -lpq" >&5

 ac_lib_var=`echo pq'_'PQconnectStart | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpq "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo pq'_'PQconnectStart | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpq "
 cat > conftest.$ac_ext <<EOF

-#line 8165 "configure"
+#line 8176 "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
 #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

@@ -8172,7 +8183,7 @@ int main() {
 PQconnectStart()
 ; return 0; }
 EOF
 PQconnectStart()
 ; return 0; }
 EOF

-if { (eval echo configure:8176: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8187: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8220,7 +8231,7 @@ fi
 
 if test "$window_system" != "none"; then
   echo "checking for graphics libraries" 1>&6
 
 if test "$window_system" != "none"; then
   echo "checking for graphics libraries" 1>&6

-echo "configure:8224: checking for graphics libraries" >&5
+echo "configure:8235: checking for graphics libraries" >&5

 
       libpath_xpm=
   incpath_xpm=
 
       libpath_xpm=
   incpath_xpm=

@@ -8246,10 +8257,10 @@ echo "configure:8224: checking for graphics libraries" >&5
     CFLAGS=""$incpath_xpm" $CFLAGS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \""$incpath_xpm"\" to \$CFLAGS"; fi
     LDFLAGS=""$libpath_xpm" $LDFLAGS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \""$libpath_xpm"\" to \$LDFLAGS"; fi
     echo $ac_n "checking for Xpm - no older than 3.4f""... $ac_c" 1>&6
     CFLAGS=""$incpath_xpm" $CFLAGS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \""$incpath_xpm"\" to \$CFLAGS"; fi
     LDFLAGS=""$libpath_xpm" $LDFLAGS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \""$libpath_xpm"\" to \$LDFLAGS"; fi
     echo $ac_n "checking for Xpm - no older than 3.4f""... $ac_c" 1>&6

-echo "configure:8250: checking for Xpm - no older than 3.4f" >&5
+echo "configure:8261: checking for Xpm - no older than 3.4f" >&5

     xe_check_libs=-lXpm
     cat > conftest.$ac_ext <<EOF
     xe_check_libs=-lXpm
     cat > conftest.$ac_ext <<EOF

-#line 8253 "configure"
+#line 8264 "configure"

 #include "confdefs.h"
 #define XPM_NUMBERS
 #include <X11/xpm.h>
 #include "confdefs.h"
 #define XPM_NUMBERS
 #include <X11/xpm.h>

@@ -8258,7 +8269,7 @@ echo "configure:8250: checking for Xpm - no older than 3.4f" >&5
       XpmIncludeVersion != XpmLibraryVersion() ? 1 :
       XpmIncludeVersion < 30406 ? 2 : 0 ;}
 EOF
       XpmIncludeVersion != XpmLibraryVersion() ? 1 :
       XpmIncludeVersion < 30406 ? 2 : 0 ;}
 EOF

-if { (eval echo configure:8262: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:8273: \"$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
 then
   ./conftest dummy_arg; xpm_status=$?;
       if test "$xpm_status" = "0"; then

@@ -8302,17 +8313,17 @@ EOF
     libs_x="-lXpm $libs_x" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-lXpm\" to \$libs_x"; fi
     CFLAGS=""$incpath_xpm" $CFLAGS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \""$incpath_xpm"\" to \$CFLAGS"; fi
     echo $ac_n "checking for \"FOR_MSW\" xpm""... $ac_c" 1>&6
     libs_x="-lXpm $libs_x" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-lXpm\" to \$libs_x"; fi
     CFLAGS=""$incpath_xpm" $CFLAGS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \""$incpath_xpm"\" to \$CFLAGS"; fi
     echo $ac_n "checking for \"FOR_MSW\" xpm""... $ac_c" 1>&6

-echo "configure:8306: checking for \"FOR_MSW\" xpm" >&5
+echo "configure:8317: checking for \"FOR_MSW\" xpm" >&5

     xe_check_libs=-lXpm
     cat > conftest.$ac_ext <<EOF
     xe_check_libs=-lXpm
     cat > conftest.$ac_ext <<EOF

-#line 8309 "configure"
+#line 8320 "configure"

 #include "confdefs.h"
 
 int main() {
 XpmCreatePixmapFromData()
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 XpmCreatePixmapFromData()
 ; return 0; }
 EOF

-if { (eval echo configure:8316: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8327: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   xpm_for_msw=no
 else
   rm -rf conftest*
   xpm_for_msw=no
 else

@@ -8338,15 +8349,15 @@ EOF
 
     test -z "$with_xface" && { ac_safe=`echo "compface.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for compface.h""... $ac_c" 1>&6
 
     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:8342: checking for compface.h" >&5
+echo "configure:8353: checking for compface.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8345 "configure"
+#line 8356 "configure"

 #include "confdefs.h"
 #include <compface.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <compface.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:8350: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8361: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -8369,12 +8380,12 @@ fi
  }
   test -z "$with_xface" && { 
 echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6
  }
   test -z "$with_xface" && { 
 echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6

-echo "configure:8373: checking for UnGenFace in -lcompface" >&5
+echo "configure:8384: checking for UnGenFace in -lcompface" >&5

 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcompface "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcompface "
 cat > conftest.$ac_ext <<EOF

-#line 8378 "configure"
+#line 8389 "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
 #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

@@ -8385,7 +8396,7 @@ int main() {
 UnGenFace()
 ; return 0; }
 EOF
 UnGenFace()
 ; return 0; }
 EOF

-if { (eval echo configure:8389: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8400: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8437,12 +8448,12 @@ EOF
       if test "$with_png $with_tiff" != "no no"; then
     
 echo $ac_n "checking for inflate in -lc""... $ac_c" 1>&6
       if test "$with_png $with_tiff" != "no no"; then
     
 echo $ac_n "checking for inflate in -lc""... $ac_c" 1>&6

-echo "configure:8441: checking for inflate in -lc" >&5
+echo "configure:8452: checking for inflate in -lc" >&5

 ac_lib_var=`echo c'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lc "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo c'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lc "
 cat > conftest.$ac_ext <<EOF

-#line 8446 "configure"
+#line 8457 "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
 #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

@@ -8453,7 +8464,7 @@ int main() {
 inflate()
 ; return 0; }
 EOF
 inflate()
 ; return 0; }
 EOF

-if { (eval echo configure:8457: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8468: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8472,12 +8483,12 @@ else
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for inflate in -lz""... $ac_c" 1>&6
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for inflate in -lz""... $ac_c" 1>&6

-echo "configure:8476: checking for inflate in -lz" >&5
+echo "configure:8487: checking for inflate in -lz" >&5

 ac_lib_var=`echo z'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lz "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo z'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lz "
 cat > conftest.$ac_ext <<EOF

-#line 8481 "configure"
+#line 8492 "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
 #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

@@ -8488,7 +8499,7 @@ int main() {
 inflate()
 ; return 0; }
 EOF
 inflate()
 ; return 0; }
 EOF

-if { (eval echo configure:8492: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8503: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8507,12 +8518,12 @@ else
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for inflate in -lgz""... $ac_c" 1>&6
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for inflate in -lgz""... $ac_c" 1>&6

-echo "configure:8511: checking for inflate in -lgz" >&5
+echo "configure:8522: checking for inflate in -lgz" >&5

 ac_lib_var=`echo gz'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgz "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo gz'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgz "
 cat > conftest.$ac_ext <<EOF

-#line 8516 "configure"
+#line 8527 "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
 #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

@@ -8523,7 +8534,7 @@ int main() {
 inflate()
 ; return 0; }
 EOF
 inflate()
 ; return 0; }
 EOF

-if { (eval echo configure:8527: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8538: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8553,15 +8564,15 @@ fi
 
     test -z "$with_jpeg" && { ac_safe=`echo "jpeglib.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for jpeglib.h""... $ac_c" 1>&6
 
     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:8557: checking for jpeglib.h" >&5
+echo "configure:8568: checking for jpeglib.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8560 "configure"
+#line 8571 "configure"

 #include "confdefs.h"
 #include <jpeglib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <jpeglib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:8565: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8576: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -8584,12 +8595,12 @@ fi
  }
   test -z "$with_jpeg" && { 
 echo $ac_n "checking for jpeg_destroy_decompress in -ljpeg""... $ac_c" 1>&6
  }
   test -z "$with_jpeg" && { 
 echo $ac_n "checking for jpeg_destroy_decompress in -ljpeg""... $ac_c" 1>&6

-echo "configure:8588: checking for jpeg_destroy_decompress in -ljpeg" >&5
+echo "configure:8599: 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
 ac_lib_var=`echo jpeg'_'jpeg_destroy_decompress | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ljpeg "
 cat > conftest.$ac_ext <<EOF

-#line 8593 "configure"
+#line 8604 "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
 #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

@@ -8600,7 +8611,7 @@ int main() {
 jpeg_destroy_decompress()
 ; return 0; }
 EOF
 jpeg_destroy_decompress()
 ; return 0; }
 EOF

-if { (eval echo configure:8604: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8615: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8636,10 +8647,10 @@ EOF
 
     png_problem=""
   test -z "$with_png" && { echo $ac_n "checking for pow""... $ac_c" 1>&6
 
     png_problem=""
   test -z "$with_png" && { echo $ac_n "checking for pow""... $ac_c" 1>&6

-echo "configure:8640: checking for pow" >&5
+echo "configure:8651: checking for pow" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8643 "configure"
+#line 8654 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char pow(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char pow(); below.  */

@@ -8662,7 +8673,7 @@ pow();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:8666: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8677: \"$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
   rm -rf conftest*
   eval "ac_cv_func_pow=yes"
 else

@@ -8683,15 +8694,15 @@ fi
  }
   test -z "$with_png" && { ac_safe=`echo "png.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for png.h""... $ac_c" 1>&6
  }
   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:8687: checking for png.h" >&5
+echo "configure:8698: checking for png.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8690 "configure"
+#line 8701 "configure"

 #include "confdefs.h"
 #include <png.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <png.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:8695: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8706: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -8714,12 +8725,12 @@ fi
  }
   test -z "$with_png" && { 
 echo $ac_n "checking for png_read_image in -lpng""... $ac_c" 1>&6
  }
   test -z "$with_png" && { 
 echo $ac_n "checking for png_read_image in -lpng""... $ac_c" 1>&6

-echo "configure:8718: checking for png_read_image in -lpng" >&5
+echo "configure:8729: 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
 ac_lib_var=`echo png'_'png_read_image | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpng "
 cat > conftest.$ac_ext <<EOF

-#line 8723 "configure"
+#line 8734 "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
 #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

@@ -8730,7 +8741,7 @@ int main() {
 png_read_image()
 ; return 0; }
 EOF
 png_read_image()
 ; return 0; }
 EOF

-if { (eval echo configure:8734: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8745: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8753,10 +8764,10 @@ fi
  }
   if test -z "$with_png"; then
     echo $ac_n "checking for workable png version information""... $ac_c" 1>&6
  }
   if test -z "$with_png"; then
     echo $ac_n "checking for workable png version information""... $ac_c" 1>&6

-echo "configure:8757: checking for workable png version information" >&5
+echo "configure:8768: checking for workable png version information" >&5

     xe_check_libs="-lpng -lz"
     cat > conftest.$ac_ext <<EOF
     xe_check_libs="-lpng -lz"
     cat > conftest.$ac_ext <<EOF

-#line 8760 "configure"
+#line 8771 "configure"

 #include "confdefs.h"
 #include <png.h>
     int main(int c, char **v) {
 #include "confdefs.h"
 #include <png.h>
     int main(int c, char **v) {

@@ -8764,7 +8775,7 @@ echo "configure:8757: checking for workable png version information" >&5
     if (strcmp(png_libpng_ver, PNG_LIBPNG_VER_STRING) != 0) return 1;
     return (PNG_LIBPNG_VER < 10002) ? 2 : 0 ;}
 EOF
     if (strcmp(png_libpng_ver, PNG_LIBPNG_VER_STRING) != 0) return 1;
     return (PNG_LIBPNG_VER < 10002) ? 2 : 0 ;}
 EOF

-if { (eval echo configure:8768: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:8779: \"$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
 then
   ./conftest dummy_arg; png_status=$?;
       if test "$png_status" = "0"; then

@@ -8807,15 +8818,15 @@ EOF
 
     test -z "$with_tiff" && { ac_safe=`echo "tiffio.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for tiffio.h""... $ac_c" 1>&6
 
     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:8811: checking for tiffio.h" >&5
+echo "configure:8822: checking for tiffio.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8814 "configure"
+#line 8825 "configure"

 #include "confdefs.h"
 #include <tiffio.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <tiffio.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:8819: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8830: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -8838,12 +8849,12 @@ fi
  }
   test -z "$with_tiff" && { 
 echo $ac_n "checking for TIFFClientOpen in -ltiff""... $ac_c" 1>&6
  }
   test -z "$with_tiff" && { 
 echo $ac_n "checking for TIFFClientOpen in -ltiff""... $ac_c" 1>&6

-echo "configure:8842: checking for TIFFClientOpen in -ltiff" >&5
+echo "configure:8853: checking for TIFFClientOpen in -ltiff" >&5

 ac_lib_var=`echo tiff'_'TIFFClientOpen | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltiff "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo tiff'_'TIFFClientOpen | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltiff "
 cat > conftest.$ac_ext <<EOF

-#line 8847 "configure"
+#line 8858 "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
 #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

@@ -8854,7 +8865,7 @@ int main() {
 TIFFClientOpen()
 ; return 0; }
 EOF
 TIFFClientOpen()
 ; return 0; }
 EOF

-if { (eval echo configure:8858: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8869: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8893,15 +8904,15 @@ fi
 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
 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:8897: checking for compface.h" >&5
+echo "configure:8908: checking for compface.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 8900 "configure"
+#line 8911 "configure"

 #include "confdefs.h"
 #include <compface.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <compface.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:8905: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8916: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -8924,12 +8935,12 @@ fi
  }
   test -z "$with_xface" && { 
 echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6
  }
   test -z "$with_xface" && { 
 echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6

-echo "configure:8928: checking for UnGenFace in -lcompface" >&5
+echo "configure:8939: checking for UnGenFace in -lcompface" >&5

 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcompface "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcompface "
 cat > conftest.$ac_ext <<EOF

-#line 8933 "configure"
+#line 8944 "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
 #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

@@ -8940,7 +8951,7 @@ int main() {
 UnGenFace()
 ; return 0; }
 EOF
 UnGenFace()
 ; return 0; }
 EOF

-if { (eval echo configure:8944: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8955: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -8979,12 +8990,12 @@ fi
 
 if test "$with_x11" = "yes"; then
   echo "checking for X11 graphics libraries" 1>&6
 
 if test "$with_x11" = "yes"; then
   echo "checking for X11 graphics libraries" 1>&6

-echo "configure:8983: checking for X11 graphics libraries" >&5
+echo "configure:8994: checking for X11 graphics libraries" >&5

 fi
 
 if test "$with_x11" = "yes"; then
   echo "checking for the Athena widgets" 1>&6
 fi
 
 if test "$with_x11" = "yes"; then
   echo "checking for the Athena widgets" 1>&6

-echo "configure:8988: checking for the Athena widgets" >&5
+echo "configure:8999: checking for the Athena widgets" >&5

 
     case "$with_athena" in
         "xaw" | "")    athena_variant=Xaw      athena_3d=no  ;;
 
     case "$with_athena" in
         "xaw" | "")    athena_variant=Xaw      athena_3d=no  ;;

@@ -9000,12 +9011,12 @@ echo "configure:8988: checking for the Athena widgets" >&5
     if test "$athena_3d" = "no"; then
     
 echo $ac_n "checking for XawScrollbarSetThumb in -l$athena_variant""... $ac_c" 1>&6
     if test "$athena_3d" = "no"; then
     
 echo $ac_n "checking for XawScrollbarSetThumb in -l$athena_variant""... $ac_c" 1>&6

-echo "configure:9004: checking for XawScrollbarSetThumb in -l$athena_variant" >&5
+echo "configure:9015: 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
 ac_lib_var=`echo $athena_variant'_'XawScrollbarSetThumb | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF

-#line 9009 "configure"
+#line 9020 "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
 #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

@@ -9016,7 +9027,7 @@ int main() {
 XawScrollbarSetThumb()
 ; return 0; }
 EOF
 XawScrollbarSetThumb()
 ; return 0; }
 EOF

-if { (eval echo configure:9020: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9031: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -9032,12 +9043,12 @@ if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
   echo "$ac_t""yes" 1>&6
           
 echo $ac_n "checking for $athena_3d_function in -l$athena_variant""... $ac_c" 1>&6
   echo "$ac_t""yes" 1>&6
           
 echo $ac_n "checking for $athena_3d_function in -l$athena_variant""... $ac_c" 1>&6

-echo "configure:9036: checking for $athena_3d_function in -l$athena_variant" >&5
+echo "configure:9047: checking for $athena_3d_function in -l$athena_variant" >&5

 ac_lib_var=`echo $athena_variant'_'$athena_3d_function | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo $athena_variant'_'$athena_3d_function | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF

-#line 9041 "configure"
+#line 9052 "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
 #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

@@ -9048,7 +9059,7 @@ int main() {
 $athena_3d_function()
 ; return 0; }
 EOF
 $athena_3d_function()
 ; return 0; }
 EOF

-if { (eval echo configure:9052: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9063: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -9079,12 +9090,12 @@ fi
   else
         
 echo $ac_n "checking for $athena_3d_function in -l$athena_variant""... $ac_c" 1>&6
   else
         
 echo $ac_n "checking for $athena_3d_function in -l$athena_variant""... $ac_c" 1>&6

-echo "configure:9083: checking for $athena_3d_function in -l$athena_variant" >&5
+echo "configure:9094: checking for $athena_3d_function in -l$athena_variant" >&5

 ac_lib_var=`echo $athena_variant'_'$athena_3d_function | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo $athena_variant'_'$athena_3d_function | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF

-#line 9088 "configure"
+#line 9099 "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
 #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

@@ -9095,7 +9106,7 @@ int main() {
 $athena_3d_function()
 ; return 0; }
 EOF
 $athena_3d_function()
 ; return 0; }
 EOF

-if { (eval echo configure:9099: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9110: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -9113,12 +9124,12 @@ if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for $athena_3d_function in -lXaw""... $ac_c" 1>&6
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for $athena_3d_function in -lXaw""... $ac_c" 1>&6

-echo "configure:9117: checking for $athena_3d_function in -lXaw" >&5
+echo "configure:9128: checking for $athena_3d_function in -lXaw" >&5

 ac_lib_var=`echo Xaw'_'$athena_3d_function | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXaw "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xaw'_'$athena_3d_function | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXaw "
 cat > conftest.$ac_ext <<EOF

-#line 9122 "configure"
+#line 9133 "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
 #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

@@ -9129,7 +9140,7 @@ int main() {
 $athena_3d_function()
 ; return 0; }
 EOF
 $athena_3d_function()
 ; return 0; }
 EOF

-if { (eval echo configure:9133: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9144: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -9160,15 +9171,15 @@ fi
     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
     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:9164: checking for X11/Xaw/ThreeD.h" >&5
+echo "configure:9175: checking for X11/Xaw/ThreeD.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9167 "configure"
+#line 9178 "configure"

 #include "confdefs.h"
 #include <X11/Xaw/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Xaw/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9172: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9183: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9188,15 +9199,15 @@ else
   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 "$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:9192: checking for X11/Xaw/XawInit.h" >&5
+echo "configure:9203: checking for X11/Xaw/XawInit.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9195 "configure"
+#line 9206 "configure"

 #include "confdefs.h"
 #include <X11/Xaw/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Xaw/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9200: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9211: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9222,15 +9233,15 @@ fi
   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
   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:9226: checking for X11/$athena_variant/XawInit.h" >&5
+echo "configure:9237: checking for X11/$athena_variant/XawInit.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9229 "configure"
+#line 9240 "configure"

 #include "confdefs.h"
 #include <X11/$athena_variant/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #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:9234: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9245: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9247,15 +9258,15 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   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 "$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:9251: checking for X11/$athena_variant/ThreeD.h" >&5
+echo "configure:9262: checking for X11/$athena_variant/ThreeD.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9254 "configure"
+#line 9265 "configure"

 #include "confdefs.h"
 #include <X11/$athena_variant/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #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:9259: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9270: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9283,15 +9294,15 @@ fi
         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
         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:9287: checking for $athena_variant/XawInit.h" >&5
+echo "configure:9298: checking for $athena_variant/XawInit.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9290 "configure"
+#line 9301 "configure"

 #include "confdefs.h"
 #include <$athena_variant/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$athena_variant/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9295: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9306: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9308,15 +9319,15 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   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 "$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:9312: checking for $athena_variant/ThreeD.h" >&5
+echo "configure:9323: checking for $athena_variant/ThreeD.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9315 "configure"
+#line 9326 "configure"

 #include "confdefs.h"
 #include <$athena_variant/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$athena_variant/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9320: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9331: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9345,15 +9356,15 @@ fi
         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
         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:9349: checking for X11/Xaw3d/XawInit.h" >&5
+echo "configure:9360: checking for X11/Xaw3d/XawInit.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9352 "configure"
+#line 9363 "configure"

 #include "confdefs.h"
 #include <X11/Xaw3d/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Xaw3d/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9357: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9368: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9370,15 +9381,15 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   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 "$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:9374: checking for X11/Xaw3d/ThreeD.h" >&5
+echo "configure:9385: checking for X11/Xaw3d/ThreeD.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9377 "configure"
+#line 9388 "configure"

 #include "confdefs.h"
 #include <X11/Xaw3d/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Xaw3d/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9382: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9393: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9410,15 +9421,15 @@ fi
         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
         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:9414: checking for Xaw3d/XawInit.h" >&5
+echo "configure:9425: checking for Xaw3d/XawInit.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9417 "configure"
+#line 9428 "configure"

 #include "confdefs.h"
 #include <Xaw3d/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <Xaw3d/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9422: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9433: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9435,15 +9446,15 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   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 "$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:9439: checking for Xaw3d/ThreeD.h" >&5
+echo "configure:9450: checking for Xaw3d/ThreeD.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9442 "configure"
+#line 9453 "configure"

 #include "confdefs.h"
 #include <Xaw3d/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <Xaw3d/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9447: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9458: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9475,15 +9486,15 @@ fi
             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
             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:9479: checking for X11/Xaw/ThreeD.h" >&5
+echo "configure:9490: checking for X11/Xaw/ThreeD.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9482 "configure"
+#line 9493 "configure"

 #include "confdefs.h"
 #include <X11/Xaw/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <X11/Xaw/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9487: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9498: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9522,15 +9533,15 @@ fi
 if test "$with_x11" = "yes"; then
     ac_safe=`echo "Xm/Xm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xm/Xm.h""... $ac_c" 1>&6
 if test "$with_x11" = "yes"; then
     ac_safe=`echo "Xm/Xm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xm/Xm.h""... $ac_c" 1>&6

-echo "configure:9526: checking for Xm/Xm.h" >&5
+echo "configure:9537: checking for Xm/Xm.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 9529 "configure"
+#line 9540 "configure"

 #include "confdefs.h"
 #include <Xm/Xm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <Xm/Xm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:9534: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9545: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -9547,12 +9558,12 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   echo "$ac_t""yes" 1>&6
   
 echo $ac_n "checking for XmStringFree in -lXm""... $ac_c" 1>&6
   echo "$ac_t""yes" 1>&6
   
 echo $ac_n "checking for XmStringFree in -lXm""... $ac_c" 1>&6

-echo "configure:9551: checking for XmStringFree in -lXm" >&5
+echo "configure:9562: checking for XmStringFree in -lXm" >&5

 ac_lib_var=`echo Xm'_'XmStringFree | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xm'_'XmStringFree | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF

-#line 9556 "configure"
+#line 9567 "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
 #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

@@ -9563,7 +9574,7 @@ int main() {
 XmStringFree()
 ; return 0; }
 EOF
 XmStringFree()
 ; return 0; }
 EOF

-if { (eval echo configure:9567: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9578: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -9592,9 +9603,9 @@ fi
 
   if test "$have_motif" = "yes"; then
         echo $ac_n "checking for Lesstif""... $ac_c" 1>&6
 
   if test "$have_motif" = "yes"; then
         echo $ac_n "checking for Lesstif""... $ac_c" 1>&6

-echo "configure:9596: checking for Lesstif" >&5
+echo "configure:9607: checking for Lesstif" >&5

     cat > conftest.$ac_ext <<EOF
     cat > conftest.$ac_ext <<EOF

-#line 9598 "configure"
+#line 9609 "configure"

 #include "confdefs.h"
 #include <Xm/Xm.h>
 #ifdef LESSTIF_VERSION
 #include "confdefs.h"
 #include <Xm/Xm.h>
 #ifdef LESSTIF_VERSION

@@ -9617,13 +9628,25 @@ rm -f conftest*
 
 fi 
 
 
 fi 
 

+case "$opsys" in
+  *linux* )  lucid_prefers_motif = "no"  ;;
+  * )        lucid_prefers_motif = "yes" ;;
+esac
+

 case "$with_menubars" in "" | "yes" | "athena" )
   with_menubars="lucid" ;;
 esac
 case "$with_dialogs" in "" | "yes" | "lucid" )
 case "$with_menubars" in "" | "yes" | "athena" )
   with_menubars="lucid" ;;
 esac
 case "$with_dialogs" in "" | "yes" | "lucid" )

-  if   test "$have_motif"     = "yes"; then with_dialogs="motif"
-  elif test "$have_xaw"       = "yes"; then with_dialogs="athena"
-  else with_dialogs=no
+  if test "$lucid_prefers_motif" = "yes"; then
+    if   test "$have_motif"     = "yes"; then with_dialogs="motif"
+    elif test "$have_xaw"       = "yes"; then with_dialogs="athena"
+    else with_dialogs=no
+    fi
+  else
+    if   test "$have_xaw"       = "yes"; then with_dialogs="athena"
+    elif test "$have_motif"     = "yes"; then with_dialogs="motif"
+    else with_dialogs=no
+    fi

   fi ;;
 esac
 case "$with_scrollbars" in "" | "yes" )
   fi ;;
 esac
 case "$with_scrollbars" in "" | "yes" )

@@ -9631,9 +9654,16 @@ case "$with_scrollbars" in "" | "yes" )
 esac
 case "$with_widgets" in
   "yes" | "lucid")
 esac
 case "$with_widgets" in
   "yes" | "lucid")

-    if   test "$have_motif" = "yes"; then with_widgets="motif"
-    elif test "$have_xaw"   = "yes"; then with_widgets="athena"
-    else with_widgets=no
+    if test "$lucid_prefers_motif" = "yes"; then
+      if   test "$have_motif" = "yes"; then with_widgets="motif"
+      elif test "$have_xaw"   = "yes"; then with_widgets="athena"
+      else with_widgets=no
+      fi
+    else
+      if   test "$have_xaw"   = "yes"; then with_widgets="athena"
+      elif test "$have_motif" = "yes"; then with_widgets="motif"
+      else with_widgets=no
+      fi

     fi ;;
   "" )
     with_widgets=no ;;
     fi ;;
   "" )
     with_widgets=no ;;

@@ -10021,7 +10051,7 @@ fi
 
 if test "$with_mule" = "yes" ; then
   echo "checking for Mule-related features" 1>&6
 
 if test "$with_mule" = "yes" ; then
   echo "checking for Mule-related features" 1>&6

-echo "configure:10025: checking for Mule-related features" >&5
+echo "configure:10055: checking for Mule-related features" >&5

   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining MULE
 EOF
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining MULE
 EOF

@@ -10046,15 +10076,15 @@ EOF
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:10050: checking for $ac_hdr" >&5
+echo "configure:10080: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10053 "configure"
+#line 10083 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:10058: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10088: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -10085,12 +10115,12 @@ done
 
   
 echo $ac_n "checking for strerror in -lintl""... $ac_c" 1>&6
 
   
 echo $ac_n "checking for strerror in -lintl""... $ac_c" 1>&6

-echo "configure:10089: checking for strerror in -lintl" >&5
+echo "configure:10119: checking for strerror in -lintl" >&5

 ac_lib_var=`echo intl'_'strerror | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lintl "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo intl'_'strerror | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lintl "
 cat > conftest.$ac_ext <<EOF

-#line 10094 "configure"
+#line 10124 "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
 #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

@@ -10101,7 +10131,7 @@ int main() {
 strerror()
 ; return 0; }
 EOF
 strerror()
 ; return 0; }
 EOF

-if { (eval echo configure:10105: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10135: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10134,18 +10164,18 @@ fi
 
 
   echo "checking for Mule input methods" 1>&6
 
 
   echo "checking for Mule input methods" 1>&6

-echo "configure:10138: checking for Mule input methods" >&5
+echo "configure:10168: checking for Mule input methods" >&5

         case "$with_xim" in "" | "yes" )
     echo "checking for XIM" 1>&6
         case "$with_xim" in "" | "yes" )
     echo "checking for XIM" 1>&6

-echo "configure:10141: checking for XIM" >&5
+echo "configure:10171: checking for XIM" >&5

     
 echo $ac_n "checking for XOpenIM in -lX11""... $ac_c" 1>&6
     
 echo $ac_n "checking for XOpenIM in -lX11""... $ac_c" 1>&6

-echo "configure:10144: checking for XOpenIM in -lX11" >&5
+echo "configure:10174: checking for XOpenIM in -lX11" >&5

 ac_lib_var=`echo X11'_'XOpenIM | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo X11'_'XOpenIM | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF

-#line 10149 "configure"
+#line 10179 "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
 #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

@@ -10156,7 +10186,7 @@ int main() {
 XOpenIM()
 ; return 0; }
 EOF
 XOpenIM()
 ; return 0; }
 EOF

-if { (eval echo configure:10160: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10190: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10177,15 +10207,54 @@ with_xim=no
 fi
 
 
 fi
 
 

-        if test "$have_motif $have_lesstif" = "yes no"; then
+            if test "$need_motif $have_lesstif" = "yes no"; then
+      
+echo $ac_n "checking for XmImMbLookupString in -lXm""... $ac_c" 1>&6
+echo "configure:10214: 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 10219 "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
+    builtin and then its argument prototype would still apply.  */
+char XmImMbLookupString();
+
+int main() {
+XmImMbLookupString()
+; return 0; }
+EOF
+if { (eval echo configure:10230: \"$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
+  echo "configure: failed program was:" >&5
+  cat conftest.$ac_ext >&5
+  rm -rf conftest*
+  eval "ac_cv_lib_$ac_lib_var=no"
+fi
+rm -f conftest*
+xe_check_libs=""
+
+if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
+  echo "$ac_t""yes" 1>&6
+  with_xim=motif
+else
+  echo "$ac_t""no" 1>&6
+fi
+
+
+    elif test "$have_motif $have_lesstif $with_xim" = "yes no no"; then

       
 echo $ac_n "checking for XmImMbLookupString in -lXm""... $ac_c" 1>&6
       
 echo $ac_n "checking for XmImMbLookupString in -lXm""... $ac_c" 1>&6

-echo "configure:10184: checking for XmImMbLookupString in -lXm" >&5
+echo "configure:10253: checking for XmImMbLookupString in -lXm" >&5

 ac_lib_var=`echo Xm'_'XmImMbLookupString | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Xm'_'XmImMbLookupString | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF

-#line 10189 "configure"
+#line 10258 "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
 #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

@@ -10196,7 +10265,7 @@ int main() {
 XmImMbLookupString()
 ; return 0; }
 EOF
 XmImMbLookupString()
 ; return 0; }
 EOF

-if { (eval echo configure:10200: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10269: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10261,15 +10330,15 @@ EOF
 
     if test "$with_xfs" = "yes" ; then
     echo "checking for XFontSet" 1>&6
 
     if test "$with_xfs" = "yes" ; then
     echo "checking for XFontSet" 1>&6

-echo "configure:10265: checking for XFontSet" >&5
+echo "configure:10334: checking for XFontSet" >&5

     
 echo $ac_n "checking for XmbDrawString in -lX11""... $ac_c" 1>&6
     
 echo $ac_n "checking for XmbDrawString in -lX11""... $ac_c" 1>&6

-echo "configure:10268: checking for XmbDrawString in -lX11" >&5
+echo "configure:10337: checking for XmbDrawString in -lX11" >&5

 ac_lib_var=`echo X11'_'XmbDrawString | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo X11'_'XmbDrawString | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF

-#line 10273 "configure"
+#line 10342 "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
 #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

@@ -10280,7 +10349,7 @@ int main() {
 XmbDrawString()
 ; return 0; }
 EOF
 XmbDrawString()
 ; return 0; }
 EOF

-if { (eval echo configure:10284: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10353: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10320,15 +10389,15 @@ EOF
     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
     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:10324: checking for wnn/jllib.h" >&5
+echo "configure:10393: checking for wnn/jllib.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10327 "configure"
+#line 10396 "configure"

 #include "confdefs.h"
 #include <wnn/jllib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <wnn/jllib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:10332: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10401: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -10351,15 +10420,15 @@ fi
  }
     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
  }
     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:10355: checking for wnn/commonhd.h" >&5
+echo "configure:10424: checking for wnn/commonhd.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10358 "configure"
+#line 10427 "configure"

 #include "confdefs.h"
 #include <wnn/commonhd.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <wnn/commonhd.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:10363: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10432: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -10384,10 +10453,10 @@ fi
     for ac_func in crypt
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
     for ac_func in crypt
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:10388: checking for $ac_func" >&5
+echo "configure:10457: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10391 "configure"
+#line 10460 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -10410,7 +10479,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:10414: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10483: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -10439,12 +10508,12 @@ done
 
     test "$ac_cv_func_crypt" != "yes" && { 
 echo $ac_n "checking for crypt in -lcrypt""... $ac_c" 1>&6
 
     test "$ac_cv_func_crypt" != "yes" && { 
 echo $ac_n "checking for crypt in -lcrypt""... $ac_c" 1>&6

-echo "configure:10443: checking for crypt in -lcrypt" >&5
+echo "configure:10512: checking for crypt in -lcrypt" >&5

 ac_lib_var=`echo crypt'_'crypt | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcrypt "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo crypt'_'crypt | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcrypt "
 cat > conftest.$ac_ext <<EOF

-#line 10448 "configure"
+#line 10517 "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
 #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

@@ -10455,7 +10524,7 @@ int main() {
 crypt()
 ; return 0; }
 EOF
 crypt()
 ; return 0; }
 EOF

-if { (eval echo configure:10459: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10528: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10490,12 +10559,12 @@ fi
     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
     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:10494: checking for jl_dic_list_e in -lwnn" >&5
+echo "configure:10563: 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
 ac_lib_var=`echo wnn'_'jl_dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn "
 cat > conftest.$ac_ext <<EOF

-#line 10499 "configure"
+#line 10568 "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
 #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

@@ -10506,7 +10575,7 @@ int main() {
 jl_dic_list_e()
 ; return 0; }
 EOF
 jl_dic_list_e()
 ; return 0; }
 EOF

-if { (eval echo configure:10510: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10579: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10524,12 +10593,12 @@ if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for jl_dic_list_e in -lwnn4""... $ac_c" 1>&6
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for jl_dic_list_e in -lwnn4""... $ac_c" 1>&6

-echo "configure:10528: checking for jl_dic_list_e in -lwnn4" >&5
+echo "configure:10597: 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
 ac_lib_var=`echo wnn4'_'jl_dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn4 "
 cat > conftest.$ac_ext <<EOF

-#line 10533 "configure"
+#line 10602 "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
 #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

@@ -10540,7 +10609,7 @@ int main() {
 jl_dic_list_e()
 ; return 0; }
 EOF
 jl_dic_list_e()
 ; return 0; }
 EOF

-if { (eval echo configure:10544: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10613: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10558,12 +10627,12 @@ if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for jl_dic_list_e in -lwnn6""... $ac_c" 1>&6
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for jl_dic_list_e in -lwnn6""... $ac_c" 1>&6

-echo "configure:10562: checking for jl_dic_list_e in -lwnn6" >&5
+echo "configure:10631: 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
 ac_lib_var=`echo wnn6'_'jl_dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn6 "
 cat > conftest.$ac_ext <<EOF

-#line 10567 "configure"
+#line 10636 "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
 #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

@@ -10574,7 +10643,7 @@ int main() {
 jl_dic_list_e()
 ; return 0; }
 EOF
 jl_dic_list_e()
 ; return 0; }
 EOF

-if { (eval echo configure:10578: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10647: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10592,12 +10661,12 @@ if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for dic_list_e in -lwnn6_fromsrc""... $ac_c" 1>&6
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for dic_list_e in -lwnn6_fromsrc""... $ac_c" 1>&6

-echo "configure:10596: checking for dic_list_e in -lwnn6_fromsrc" >&5
+echo "configure:10665: 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
 ac_lib_var=`echo wnn6_fromsrc'_'dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn6_fromsrc "
 cat > conftest.$ac_ext <<EOF

-#line 10601 "configure"
+#line 10670 "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
 #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

@@ -10608,7 +10677,7 @@ int main() {
 dic_list_e()
 ; return 0; }
 EOF
 dic_list_e()
 ; return 0; }
 EOF

-if { (eval echo configure:10612: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10681: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10656,12 +10725,12 @@ EOF
     if test "$with_wnn6" != "no"; then
       
 echo $ac_n "checking for jl_fi_dic_list in -l$libwnn""... $ac_c" 1>&6
     if test "$with_wnn6" != "no"; then
       
 echo $ac_n "checking for jl_fi_dic_list in -l$libwnn""... $ac_c" 1>&6

-echo "configure:10660: checking for jl_fi_dic_list in -l$libwnn" >&5
+echo "configure:10729: 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
 ac_lib_var=`echo $libwnn'_'jl_fi_dic_list | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$libwnn "
 cat > conftest.$ac_ext <<EOF

-#line 10665 "configure"
+#line 10734 "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
 #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

@@ -10672,7 +10741,7 @@ int main() {
 jl_fi_dic_list()
 ; return 0; }
 EOF
 jl_fi_dic_list()
 ; return 0; }
 EOF

-if { (eval echo configure:10676: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10745: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10707,15 +10776,15 @@ EOF
   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
   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:10711: checking for canna/jrkanji.h" >&5
+echo "configure:10780: checking for canna/jrkanji.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10714 "configure"
+#line 10783 "configure"

 #include "confdefs.h"
 #include <canna/jrkanji.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <canna/jrkanji.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:10719: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10788: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -10742,15 +10811,15 @@ fi
     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
     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:10746: checking for canna/jrkanji.h" >&5
+echo "configure:10815: checking for canna/jrkanji.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10749 "configure"
+#line 10818 "configure"

 #include "confdefs.h"
 #include <canna/jrkanji.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <canna/jrkanji.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:10754: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10823: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -10778,15 +10847,15 @@ fi
 
   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
 
   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:10782: checking for canna/RK.h" >&5
+echo "configure:10851: checking for canna/RK.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 10785 "configure"
+#line 10854 "configure"

 #include "confdefs.h"
 #include <canna/RK.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <canna/RK.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:10790: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10859: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -10809,12 +10878,12 @@ fi
  }
   test -z "$with_canna" && { 
 echo $ac_n "checking for RkBgnBun in -lRKC""... $ac_c" 1>&6
  }
   test -z "$with_canna" && { 
 echo $ac_n "checking for RkBgnBun in -lRKC""... $ac_c" 1>&6

-echo "configure:10813: checking for RkBgnBun in -lRKC" >&5
+echo "configure:10882: checking for RkBgnBun in -lRKC" >&5

 ac_lib_var=`echo RKC'_'RkBgnBun | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lRKC "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo RKC'_'RkBgnBun | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lRKC "
 cat > conftest.$ac_ext <<EOF

-#line 10818 "configure"
+#line 10887 "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
 #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

@@ -10825,7 +10894,7 @@ int main() {
 RkBgnBun()
 ; return 0; }
 EOF
 RkBgnBun()
 ; return 0; }
 EOF

-if { (eval echo configure:10829: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10898: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10848,12 +10917,12 @@ fi
  }
   test -z "$with_canna" && { 
 echo $ac_n "checking for jrKanjiControl in -lcanna""... $ac_c" 1>&6
  }
   test -z "$with_canna" && { 
 echo $ac_n "checking for jrKanjiControl in -lcanna""... $ac_c" 1>&6

-echo "configure:10852: checking for jrKanjiControl in -lcanna" >&5
+echo "configure:10921: checking for jrKanjiControl in -lcanna" >&5

 ac_lib_var=`echo canna'_'jrKanjiControl | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcanna "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo canna'_'jrKanjiControl | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcanna "
 cat > conftest.$ac_ext <<EOF

-#line 10857 "configure"
+#line 10926 "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
 #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

@@ -10864,7 +10933,7 @@ int main() {
 jrKanjiControl()
 ; return 0; }
 EOF
 jrKanjiControl()
 ; return 0; }
 EOF

-if { (eval echo configure:10868: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10937: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10913,12 +10982,12 @@ if test "$need_motif" = "yes" ; then
   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
   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:10917: checking for layout_object_getvalue in -li18n" >&5
+echo "configure:10986: 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
 ac_lib_var=`echo i18n'_'layout_object_getvalue | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -li18n "
 cat > conftest.$ac_ext <<EOF

-#line 10922 "configure"
+#line 10991 "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
 #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

@@ -10929,7 +10998,7 @@ int main() {
 layout_object_getvalue()
 ; return 0; }
 EOF
 layout_object_getvalue()
 ; return 0; }
 EOF

-if { (eval echo configure:10933: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11002: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -10986,7 +11055,7 @@ xe_runpath_dir=`echo '' "$arg" | sed -e 's:^ ::' -e 's/^-L//'`
   eval "$xe_add_unique_runpath_dir"
 };; esac
     done
   eval "$xe_add_unique_runpath_dir"
 };; esac
     done

-        if test "$opsys $need_motif" = "sol2 yes"; then
+            if test "$opsys $need_motif" = "sol2 yes"; then

       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     fi
       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     fi

@@ -11016,10 +11085,10 @@ fi
 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
 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:11020: checking for $ac_func" >&5
+echo "configure:11089: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11023 "configure"
+#line 11092 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -11042,7 +11111,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:11046: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11115: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -11083,10 +11152,10 @@ fi
 for ac_func in getpt _getpty grantpt unlockpt ptsname killpg tcgetpgrp
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
 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:11087: checking for $ac_func" >&5
+echo "configure:11156: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11090 "configure"
+#line 11159 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -11109,7 +11178,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:11113: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11182: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -11138,10 +11207,10 @@ done
 
 
 echo $ac_n "checking for openpty""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for openpty""... $ac_c" 1>&6

-echo "configure:11142: checking for openpty" >&5
+echo "configure:11211: checking for openpty" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11145 "configure"
+#line 11214 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char openpty(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char openpty(); below.  */

@@ -11164,7 +11233,7 @@ openpty();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:11168: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11237: \"$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
   rm -rf conftest*
   eval "ac_cv_func_openpty=yes"
 else

@@ -11183,12 +11252,12 @@ else
 
   
 echo $ac_n "checking for openpty in -lutil""... $ac_c" 1>&6
 
   
 echo $ac_n "checking for openpty in -lutil""... $ac_c" 1>&6

-echo "configure:11187: checking for openpty in -lutil" >&5
+echo "configure:11256: checking for openpty in -lutil" >&5

 ac_lib_var=`echo util'_'openpty | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lutil "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo util'_'openpty | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lutil "
 cat > conftest.$ac_ext <<EOF

-#line 11192 "configure"
+#line 11261 "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
 #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

@@ -11199,7 +11268,7 @@ int main() {
 openpty()
 ; return 0; }
 EOF
 openpty()
 ; return 0; }
 EOF

-if { (eval echo configure:11203: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11272: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -11234,15 +11303,15 @@ EOF
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:11238: checking for $ac_hdr" >&5
+echo "configure:11307: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11241 "configure"
+#line 11310 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:11246: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11315: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -11278,15 +11347,15 @@ for ac_hdr in stropts.h
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:11282: checking for $ac_hdr" >&5
+echo "configure:11351: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11285 "configure"
+#line 11354 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:11290: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11359: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -11319,10 +11388,10 @@ if test "$ac_cv_header_stropts_h" = "yes"; then
   for ac_func in isastream
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
   for ac_func in isastream
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:11323: checking for $ac_func" >&5
+echo "configure:11392: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11326 "configure"
+#line 11395 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -11345,7 +11414,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:11349: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11418: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -11376,15 +11445,15 @@ done
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:11380: checking for $ac_hdr" >&5
+echo "configure:11449: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11383 "configure"
+#line 11452 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:11388: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11457: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -11421,10 +11490,10 @@ extra_objs="$extra_objs realpath.o" &&  if test "$extra_verbose" = "yes"; then
 for ac_func in getloadavg
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
 for ac_func in getloadavg
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:11425: checking for $ac_func" >&5
+echo "configure:11494: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11428 "configure"
+#line 11497 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -11447,7 +11516,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:11451: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11520: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -11480,15 +11549,15 @@ if test "$ac_cv_func_getloadavg" = "yes"; then
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:11484: checking for $ac_hdr" >&5
+echo "configure:11553: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11487 "configure"
+#line 11556 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:11492: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11561: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -11524,12 +11593,12 @@ else
 
     
 echo $ac_n "checking for kstat_open in -lkstat""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for kstat_open in -lkstat""... $ac_c" 1>&6

-echo "configure:11528: checking for kstat_open in -lkstat" >&5
+echo "configure:11597: 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
 ac_lib_var=`echo kstat'_'kstat_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lkstat "
 cat > conftest.$ac_ext <<EOF

-#line 11533 "configure"
+#line 11602 "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
 #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

@@ -11540,7 +11609,7 @@ int main() {
 kstat_open()
 ; return 0; }
 EOF
 kstat_open()
 ; return 0; }
 EOF

-if { (eval echo configure:11544: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11613: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -11575,15 +11644,15 @@ fi
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6

-echo "configure:11579: checking for $ac_hdr" >&5
+echo "configure:11648: checking for $ac_hdr" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11582 "configure"
+#line 11651 "configure"

 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:11587: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11656: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -11615,12 +11684,12 @@ done
 
     
 echo $ac_n "checking for kvm_read in -lkvm""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for kvm_read in -lkvm""... $ac_c" 1>&6

-echo "configure:11619: checking for kvm_read in -lkvm" >&5
+echo "configure:11688: 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
 ac_lib_var=`echo kvm'_'kvm_read | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lkvm "
 cat > conftest.$ac_ext <<EOF

-#line 11624 "configure"
+#line 11693 "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
 #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

@@ -11631,7 +11700,7 @@ int main() {
 kvm_read()
 ; return 0; }
 EOF
 kvm_read()
 ; return 0; }
 EOF

-if { (eval echo configure:11635: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11704: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -11665,16 +11734,16 @@ fi
 fi
 
 echo $ac_n "checking whether netdb declares h_errno""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking whether netdb declares h_errno""... $ac_c" 1>&6

-echo "configure:11669: checking whether netdb declares h_errno" >&5
+echo "configure:11738: checking whether netdb declares h_errno" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 11671 "configure"
+#line 11740 "configure"

 #include "confdefs.h"
 #include <netdb.h>
 int main() {
 return h_errno;
 ; return 0; }
 EOF
 #include "confdefs.h"
 #include <netdb.h>
 int main() {
 return h_errno;
 ; return 0; }
 EOF

-if { (eval echo configure:11678: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11747: \"$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
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
    { test "$extra_verbose" = "yes" && cat << \EOF

@@ -11694,16 +11763,16 @@ fi
 rm -f conftest*
 
 echo $ac_n "checking for sigsetjmp""... $ac_c" 1>&6
 rm -f conftest*
 
 echo $ac_n "checking for sigsetjmp""... $ac_c" 1>&6

-echo "configure:11698: checking for sigsetjmp" >&5
+echo "configure:11767: checking for sigsetjmp" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 11700 "configure"
+#line 11769 "configure"

 #include "confdefs.h"
 #include <setjmp.h>
 int main() {
 sigjmp_buf bar; sigsetjmp (bar, 0);
 ; return 0; }
 EOF
 #include "confdefs.h"
 #include <setjmp.h>
 int main() {
 sigjmp_buf bar; sigsetjmp (bar, 0);
 ; return 0; }
 EOF

-if { (eval echo configure:11707: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:11776: \"$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
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
    { test "$extra_verbose" = "yes" && cat << \EOF

@@ -11723,11 +11792,11 @@ fi
 rm -f conftest*
 
 echo $ac_n "checking whether localtime caches TZ""... $ac_c" 1>&6
 rm -f conftest*
 
 echo $ac_n "checking whether localtime caches TZ""... $ac_c" 1>&6

-echo "configure:11727: checking whether localtime caches TZ" >&5
+echo "configure:11796: checking whether localtime caches TZ" >&5

 
 if test "$ac_cv_func_tzset" = "yes"; then
 cat > conftest.$ac_ext <<EOF
 
 if test "$ac_cv_func_tzset" = "yes"; then
 cat > conftest.$ac_ext <<EOF

-#line 11731 "configure"
+#line 11800 "configure"

 #include "confdefs.h"
 #include <time.h>
 #if STDC_HEADERS
 #include "confdefs.h"
 #include <time.h>
 #if STDC_HEADERS

@@ -11762,7 +11831,7 @@ main()
   exit (0);
 }
 EOF
   exit (0);
 }
 EOF

-if { (eval echo configure:11766: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:11835: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   emacs_cv_localtime_cache=no
 else
 then
   emacs_cv_localtime_cache=no
 else

@@ -11792,9 +11861,9 @@ fi
 
 if test "$HAVE_TIMEVAL" = "yes"; then
 echo $ac_n "checking whether gettimeofday accepts one or two arguments""... $ac_c" 1>&6
 
 if test "$HAVE_TIMEVAL" = "yes"; then
 echo $ac_n "checking whether gettimeofday accepts one or two arguments""... $ac_c" 1>&6

-echo "configure:11796: checking whether gettimeofday accepts one or two arguments" >&5
+echo "configure:11865: checking whether gettimeofday accepts one or two arguments" >&5

 cat > conftest.$ac_ext <<EOF
 cat > conftest.$ac_ext <<EOF

-#line 11798 "configure"
+#line 11867 "configure"

 #include "confdefs.h"
 
 #ifdef TIME_WITH_SYS_TIME
 #include "confdefs.h"
 
 #ifdef TIME_WITH_SYS_TIME

@@ -11815,7 +11884,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:11819: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11888: \"$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
   rm -rf conftest*
   echo "$ac_t""two" 1>&6
 else

@@ -11837,19 +11906,19 @@ fi
 
 
 echo $ac_n "checking for inline""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for inline""... $ac_c" 1>&6

-echo "configure:11841: checking for inline" >&5
+echo "configure:11910: checking for inline" >&5

 
 ac_cv_c_inline=no
 for ac_kw in inline __inline__ __inline; do
   cat > conftest.$ac_ext <<EOF
 
 ac_cv_c_inline=no
 for ac_kw in inline __inline__ __inline; do
   cat > conftest.$ac_ext <<EOF

-#line 11846 "configure"
+#line 11915 "configure"

 #include "confdefs.h"
 
 int main() {
 } $ac_kw foo() {
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 } $ac_kw foo() {
 ; return 0; }
 EOF

-if { (eval echo configure:11853: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:11922: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   ac_cv_c_inline=$ac_kw; break
 else
   rm -rf conftest*
   ac_cv_c_inline=$ac_kw; break
 else

@@ -11890,17 +11959,17 @@ if test "$__DECC" != "yes"; then
   # 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
   # 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:11894: checking for working alloca.h" >&5
+echo "configure:11963: checking for working alloca.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11897 "configure"
+#line 11966 "configure"

 #include "confdefs.h"
 #include <alloca.h>
 int main() {
 char *p = alloca(2 * sizeof(int));
 ; return 0; }
 EOF
 #include "confdefs.h"
 #include <alloca.h>
 int main() {
 char *p = alloca(2 * sizeof(int));
 ; return 0; }
 EOF

-if { (eval echo configure:11904: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11973: \"$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
   rm -rf conftest*
   ac_cv_header_alloca_h=yes
 else

@@ -11924,10 +11993,10 @@ EOF
 fi
 
 echo $ac_n "checking for alloca""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for alloca""... $ac_c" 1>&6

-echo "configure:11928: checking for alloca" >&5
+echo "configure:11997: checking for alloca" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 11931 "configure"
+#line 12000 "configure"

 #include "confdefs.h"
 
 #ifdef __GNUC__
 #include "confdefs.h"
 
 #ifdef __GNUC__

@@ -11955,7 +12024,7 @@ int main() {
 char *p = (char *) alloca(1);
 ; return 0; }
 EOF
 char *p = (char *) alloca(1);
 ; return 0; }
 EOF

-if { (eval echo configure:11959: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12028: \"$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
   rm -rf conftest*
   ac_cv_func_alloca_works=yes
 else

@@ -11994,10 +12063,10 @@ EOF
 
 
 echo $ac_n "checking whether alloca needs Cray hooks""... $ac_c" 1>&6
 
 
 echo $ac_n "checking whether alloca needs Cray hooks""... $ac_c" 1>&6

-echo "configure:11998: checking whether alloca needs Cray hooks" >&5
+echo "configure:12067: checking whether alloca needs Cray hooks" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12001 "configure"
+#line 12070 "configure"

 #include "confdefs.h"
 #if defined(CRAY) && ! defined(CRAY2)
 webecray
 #include "confdefs.h"
 #if defined(CRAY) && ! defined(CRAY2)
 webecray

@@ -12021,10 +12090,10 @@ echo "$ac_t""$ac_cv_os_cray" 1>&6
 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
 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:12025: checking for $ac_func" >&5
+echo "configure:12094: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12028 "configure"
+#line 12097 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -12047,7 +12116,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:12051: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12120: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -12077,10 +12146,10 @@ done
 fi
 
 echo $ac_n "checking stack direction for C alloca""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking stack direction for C alloca""... $ac_c" 1>&6

-echo "configure:12081: checking stack direction for C alloca" >&5
+echo "configure:12150: checking stack direction for C alloca" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12084 "configure"
+#line 12153 "configure"

 #include "confdefs.h"
 find_stack_direction ()
 {
 #include "confdefs.h"
 find_stack_direction ()
 {

@@ -12099,7 +12168,7 @@ main ()
   exit (find_stack_direction() < 0);
 }
 EOF
   exit (find_stack_direction() < 0);
 }
 EOF

-if { (eval echo configure:12103: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12172: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_c_stack_direction=1
 else
 then
   ac_cv_c_stack_direction=1
 else

@@ -12129,15 +12198,15 @@ fi
 
 ac_safe=`echo "vfork.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for vfork.h""... $ac_c" 1>&6
 
 ac_safe=`echo "vfork.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for vfork.h""... $ac_c" 1>&6

-echo "configure:12133: checking for vfork.h" >&5
+echo "configure:12202: checking for vfork.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12136 "configure"
+#line 12205 "configure"

 #include "confdefs.h"
 #include <vfork.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <vfork.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12141: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12210: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12165,10 +12234,10 @@ else
 fi
 
 echo $ac_n "checking for working vfork""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking for working vfork""... $ac_c" 1>&6

-echo "configure:12169: checking for working vfork" >&5
+echo "configure:12238: checking for working vfork" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12172 "configure"
+#line 12241 "configure"

 #include "confdefs.h"
 /* Thanks to Paul Eggert for this test.  */
 #include <stdio.h>
 #include "confdefs.h"
 /* Thanks to Paul Eggert for this test.  */
 #include <stdio.h>

@@ -12263,7 +12332,7 @@ main() {
   }
 }
 EOF
   }
 }
 EOF

-if { (eval echo configure:12267: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12336: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_func_vfork_works=yes
 else
 then
   ac_cv_func_vfork_works=yes
 else

@@ -12289,10 +12358,10 @@ fi
 
 
 echo $ac_n "checking for working strcoll""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for working strcoll""... $ac_c" 1>&6

-echo "configure:12293: checking for working strcoll" >&5
+echo "configure:12362: checking for working strcoll" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12296 "configure"
+#line 12365 "configure"

 #include "confdefs.h"
 #include <string.h>
 main ()
 #include "confdefs.h"
 #include <string.h>
 main ()

@@ -12302,7 +12371,7 @@ main ()
        strcoll ("123", "456") >= 0);
 }
 EOF
        strcoll ("123", "456") >= 0);
 }
 EOF

-if { (eval echo configure:12306: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12375: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_func_strcoll_works=yes
 else
 then
   ac_cv_func_strcoll_works=yes
 else

@@ -12330,10 +12399,10 @@ fi
 for ac_func in getpgrp
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
 for ac_func in getpgrp
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:12334: checking for $ac_func" >&5
+echo "configure:12403: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12337 "configure"
+#line 12406 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -12356,7 +12425,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:12360: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12429: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -12384,10 +12453,10 @@ fi
 done
 
 echo $ac_n "checking whether getpgrp takes no argument""... $ac_c" 1>&6
 done
 
 echo $ac_n "checking whether getpgrp takes no argument""... $ac_c" 1>&6

-echo "configure:12388: checking whether getpgrp takes no argument" >&5
+echo "configure:12457: checking whether getpgrp takes no argument" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12391 "configure"
+#line 12460 "configure"

 #include "confdefs.h"
 
 /*
 #include "confdefs.h"
 
 /*

@@ -12442,7 +12511,7 @@ main()
 }
 
 EOF
 }
 
 EOF

-if { (eval echo configure:12446: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12515: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   ac_cv_func_getpgrp_void=yes
 else
 then
   ac_cv_func_getpgrp_void=yes
 else

@@ -12469,10 +12538,10 @@ fi
 
 
 echo $ac_n "checking for working mmap""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for working mmap""... $ac_c" 1>&6

-echo "configure:12473: checking for working mmap" >&5
+echo "configure:12542: checking for working mmap" >&5

 case "$opsys" in ultrix* ) have_mmap=no ;; *)
 cat > conftest.$ac_ext <<EOF
 case "$opsys" in ultrix* ) have_mmap=no ;; *)
 cat > conftest.$ac_ext <<EOF

-#line 12476 "configure"
+#line 12545 "configure"

 #include "confdefs.h"
 #include <stdio.h>
 #include <unistd.h>
 #include "confdefs.h"
 #include <stdio.h>
 #include <unistd.h>

@@ -12505,7 +12574,7 @@ int main (int argc, char *argv[])
   return 1;
 }
 EOF
   return 1;
 }
 EOF

-if { (eval echo configure:12509: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12578: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   have_mmap=yes
 else
 then
   have_mmap=yes
 else

@@ -12534,9 +12603,9 @@ test "$GNU_MALLOC" != "yes" -a "$have_mmap" != "yes" && rel_alloc=no
 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
 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:12538: checking for M_MMAP_THRESHOLD" >&5
+echo "configure:12607: checking for M_MMAP_THRESHOLD" >&5

     cat > conftest.$ac_ext <<EOF
     cat > conftest.$ac_ext <<EOF

-#line 12540 "configure"
+#line 12609 "configure"

 #include "confdefs.h"
 #include <malloc.h>
 int main() {
 #include "confdefs.h"
 #include <malloc.h>
 int main() {

@@ -12548,7 +12617,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:12552: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:12621: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   rel_alloc=no; echo "$ac_t""yes" 1>&6;
 else
   rm -rf conftest*
   rel_alloc=no; echo "$ac_t""yes" 1>&6;
 else

@@ -12573,15 +12642,15 @@ EOF
 
 ac_safe=`echo "termios.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for termios.h""... $ac_c" 1>&6
 
 ac_safe=`echo "termios.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for termios.h""... $ac_c" 1>&6

-echo "configure:12577: checking for termios.h" >&5
+echo "configure:12646: checking for termios.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12580 "configure"
+#line 12649 "configure"

 #include "confdefs.h"
 #include <termios.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <termios.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12585: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12654: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12624,15 +12693,15 @@ else
   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 "$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:12628: checking for termio.h" >&5
+echo "configure:12697: checking for termio.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12631 "configure"
+#line 12700 "configure"

 #include "confdefs.h"
 #include <termio.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <termio.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12636: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12705: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12664,10 +12733,10 @@ fi
 
 
 echo $ac_n "checking for socket""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for socket""... $ac_c" 1>&6

-echo "configure:12668: checking for socket" >&5
+echo "configure:12737: checking for socket" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12671 "configure"
+#line 12740 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char socket(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char socket(); below.  */

@@ -12690,7 +12759,7 @@ socket();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:12694: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12763: \"$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
   rm -rf conftest*
   eval "ac_cv_func_socket=yes"
 else

@@ -12705,15 +12774,15 @@ if eval "test \"`echo '$ac_cv_func_'socket`\" = yes"; then
   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 "$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:12709: checking for netinet/in.h" >&5
+echo "configure:12778: checking for netinet/in.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12712 "configure"
+#line 12781 "configure"

 #include "confdefs.h"
 #include <netinet/in.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <netinet/in.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12717: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12786: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12730,15 +12799,15 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   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 "$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:12734: checking for arpa/inet.h" >&5
+echo "configure:12803: checking for arpa/inet.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12737 "configure"
+#line 12806 "configure"

 #include "confdefs.h"
 #include <arpa/inet.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <arpa/inet.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12742: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12811: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12763,9 +12832,9 @@ EOF
 }
 
       echo $ac_n "checking "for sun_len member in struct sockaddr_un"""... $ac_c" 1>&6
 }
 
       echo $ac_n "checking "for sun_len member in struct sockaddr_un"""... $ac_c" 1>&6

-echo "configure:12767: checking "for sun_len member in struct sockaddr_un"" >&5
+echo "configure:12836: checking "for sun_len member in struct sockaddr_un"" >&5

       cat > conftest.$ac_ext <<EOF
       cat > conftest.$ac_ext <<EOF

-#line 12769 "configure"
+#line 12838 "configure"

 #include "confdefs.h"
 
 #include <sys/types.h>
 #include "confdefs.h"
 
 #include <sys/types.h>

@@ -12776,7 +12845,7 @@ int main() {
 static struct sockaddr_un x; x.sun_len = 1;
 ; return 0; }
 EOF
 static struct sockaddr_un x; x.sun_len = 1;
 ; return 0; }
 EOF

-if { (eval echo configure:12780: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12849: \"$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
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6; { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_SOCKADDR_SUN_LEN

@@ -12794,9 +12863,9 @@ else
 fi
 rm -f conftest*
       echo $ac_n "checking "for ip_mreq struct in netinet/in.h"""... $ac_c" 1>&6
 fi
 rm -f conftest*
       echo $ac_n "checking "for ip_mreq struct in netinet/in.h"""... $ac_c" 1>&6

-echo "configure:12798: checking "for ip_mreq struct in netinet/in.h"" >&5
+echo "configure:12867: checking "for ip_mreq struct in netinet/in.h"" >&5

       cat > conftest.$ac_ext <<EOF
       cat > conftest.$ac_ext <<EOF

-#line 12800 "configure"
+#line 12869 "configure"

 #include "confdefs.h"
 
 #include <sys/types.h>
 #include "confdefs.h"
 
 #include <sys/types.h>

@@ -12806,7 +12875,7 @@ int main() {
 static struct ip_mreq x;
 ; return 0; }
 EOF
 static struct ip_mreq x;
 ; return 0; }
 EOF

-if { (eval echo configure:12810: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12879: \"$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
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6; { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_MULTICAST

@@ -12837,10 +12906,10 @@ fi
 
 
 echo $ac_n "checking for msgget""... $ac_c" 1>&6
 
 
 echo $ac_n "checking for msgget""... $ac_c" 1>&6

-echo "configure:12841: checking for msgget" >&5
+echo "configure:12910: checking for msgget" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12844 "configure"
+#line 12913 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char msgget(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char msgget(); below.  */

@@ -12863,7 +12932,7 @@ msgget();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:12867: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12936: \"$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
   rm -rf conftest*
   eval "ac_cv_func_msgget=yes"
 else

@@ -12878,15 +12947,15 @@ if eval "test \"`echo '$ac_cv_func_'msgget`\" = yes"; then
   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 "$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:12882: checking for sys/ipc.h" >&5
+echo "configure:12951: checking for sys/ipc.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12885 "configure"
+#line 12954 "configure"

 #include "confdefs.h"
 #include <sys/ipc.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <sys/ipc.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12890: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12959: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12903,15 +12972,15 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   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 "$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:12907: checking for sys/msg.h" >&5
+echo "configure:12976: checking for sys/msg.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12910 "configure"
+#line 12979 "configure"

 #include "confdefs.h"
 #include <sys/msg.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <sys/msg.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12915: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12984: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12949,15 +13018,15 @@ fi
 
 ac_safe=`echo "dirent.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for dirent.h""... $ac_c" 1>&6
 
 ac_safe=`echo "dirent.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for dirent.h""... $ac_c" 1>&6

-echo "configure:12953: checking for dirent.h" >&5
+echo "configure:13022: checking for dirent.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12956 "configure"
+#line 13025 "configure"

 #include "confdefs.h"
 #include <dirent.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <dirent.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12961: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13030: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -12984,15 +13053,15 @@ else
   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 "$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:12988: checking for sys/dir.h" >&5
+echo "configure:13057: checking for sys/dir.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 12991 "configure"
+#line 13060 "configure"

 #include "confdefs.h"
 #include <sys/dir.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <sys/dir.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:12996: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13065: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13025,15 +13094,15 @@ fi
 
 ac_safe=`echo "nlist.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for nlist.h""... $ac_c" 1>&6
 
 ac_safe=`echo "nlist.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for nlist.h""... $ac_c" 1>&6

-echo "configure:13029: checking for nlist.h" >&5
+echo "configure:13098: checking for nlist.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13032 "configure"
+#line 13101 "configure"

 #include "confdefs.h"
 #include <nlist.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <nlist.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13037: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13106: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13063,22 +13132,22 @@ fi
 
 
 echo "checking "for sound support"" 1>&6
 
 
 echo "checking "for sound support"" 1>&6

-echo "configure:13067: checking "for sound support"" >&5
+echo "configure:13136: 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
 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:13074: checking for multimedia/audio_device.h" >&5
+echo "configure:13143: checking for multimedia/audio_device.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13077 "configure"
+#line 13146 "configure"

 #include "confdefs.h"
 #include <multimedia/audio_device.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <multimedia/audio_device.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13082: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13151: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13104,19 +13173,27 @@ fi
   fi
 
     if test -z "$sound_found" -a -d "/usr/demo/SOUND"; then
   fi
 
     if test -z "$sound_found" -a -d "/usr/demo/SOUND"; then

-    sound_found=yes
-    extra_objs="$extra_objs sunplay.o" &&  if test "$extra_verbose" = "yes"; then
+    if test -d "/usr/demo/SOUND/include/multimedia"; then
+      sun_sound_cflags="-I/usr/demo/SOUND/include"
+    elif test -d "/usr/demo/SOUND/multimedia"; then
+      sun_sound_cflags="-I/usr/demo/SOUND"
+    fi
+
+    if test -n "$native_sound_lib"; then
+      sun_sound_lib="$native_sound_lib"
+    elif test -r "/usr/demo/SOUND/lib/libaudio.a"; then
+      sun_sound_lib="/usr/demo/SOUND/lib/libaudio.a"
+    elif test -r "/usr/demo/SOUND/libaudio.a"; then
+      sun_sound_lib="/usr/demo/SOUND/libaudio.a"
+    fi
+
+    if test -n "$sun_sound_cflags" -a -n "$sun_sound_lib"; then
+      native_sound_lib="$sun_sound_lib"
+      sound_cflags="$sun_sound_cflags"
+      sound_found=yes
+      extra_objs="$extra_objs sunplay.o" &&  if test "$extra_verbose" = "yes"; then

    echo "    xemacs will be linked with \"sunplay.o\""
  fi
    echo "    xemacs will be linked with \"sunplay.o\""
  fi

-    if test -d "/usr/demo/SOUND/include"
-      then sound_cflags="-I/usr/demo/SOUND/include"
-      else sound_cflags="-I/usr/demo/SOUND"
-    fi
-    if test -z "$native_sound_lib" ; then
-      if test -r "/usr/demo/SOUND/lib/libaudio.a"
-        then native_sound_lib="/usr/demo/SOUND/lib/libaudio.a"
-        else native_sound_lib="/usr/demo/SOUND/libaudio.a"
-      fi

     fi
   fi
 
     fi
   fi
 

@@ -13126,12 +13203,12 @@ fi
       if test -z "$native_sound_lib"; then
         
 echo $ac_n "checking for ALopenport in -laudio""... $ac_c" 1>&6
       if test -z "$native_sound_lib"; then
         
 echo $ac_n "checking for ALopenport in -laudio""... $ac_c" 1>&6

-echo "configure:13130: checking for ALopenport in -laudio" >&5
+echo "configure:13207: checking for ALopenport in -laudio" >&5

 ac_lib_var=`echo audio'_'ALopenport | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -laudio "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo audio'_'ALopenport | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -laudio "
 cat > conftest.$ac_ext <<EOF

-#line 13135 "configure"
+#line 13212 "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
 #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

@@ -13142,7 +13219,7 @@ int main() {
 ALopenport()
 ; return 0; }
 EOF
 ALopenport()
 ; return 0; }
 EOF

-if { (eval echo configure:13146: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13223: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13173,12 +13250,12 @@ fi
       if test -z "$native_sound_lib"; then
        
 echo $ac_n "checking for AOpenAudio in -lAlib""... $ac_c" 1>&6
       if test -z "$native_sound_lib"; then
        
 echo $ac_n "checking for AOpenAudio in -lAlib""... $ac_c" 1>&6

-echo "configure:13177: checking for AOpenAudio in -lAlib" >&5
+echo "configure:13254: checking for AOpenAudio in -lAlib" >&5

 ac_lib_var=`echo Alib'_'AOpenAudio | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lAlib "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo Alib'_'AOpenAudio | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lAlib "
 cat > conftest.$ac_ext <<EOF

-#line 13182 "configure"
+#line 13259 "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
 #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

@@ -13189,7 +13266,7 @@ int main() {
 AOpenAudio()
 ; return 0; }
 EOF
 AOpenAudio()
 ; return 0; }
 EOF

-if { (eval echo configure:13193: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13270: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13234,15 +13311,15 @@ fi
     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
     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:13238: checking for ${dir}/soundcard.h" >&5
+echo "configure:13315: checking for ${dir}/soundcard.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13241 "configure"
+#line 13318 "configure"

 #include "confdefs.h"
 #include <${dir}/soundcard.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <${dir}/soundcard.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13246: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13323: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13296,15 +13373,15 @@ fi
 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
 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:13300: checking for audio/audiolib.h" >&5
+echo "configure:13377: checking for audio/audiolib.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13303 "configure"
+#line 13380 "configure"

 #include "confdefs.h"
 #include <audio/audiolib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <audio/audiolib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13308: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13385: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13322,12 +13399,12 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   
     
 echo $ac_n "checking for AuOpenServer in -laudio""... $ac_c" 1>&6
   
     
 echo $ac_n "checking for AuOpenServer in -laudio""... $ac_c" 1>&6

-echo "configure:13326: checking for AuOpenServer in -laudio" >&5
+echo "configure:13403: checking for AuOpenServer in -laudio" >&5

 ac_lib_var=`echo audio'_'AuOpenServer | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -laudio "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo audio'_'AuOpenServer | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -laudio "
 cat > conftest.$ac_ext <<EOF

-#line 13331 "configure"
+#line 13408 "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
 #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

@@ -13338,7 +13415,7 @@ int main() {
 AuOpenServer()
 ; return 0; }
 EOF
 AuOpenServer()
 ; return 0; }
 EOF

-if { (eval echo configure:13342: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13419: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13377,7 +13454,7 @@ EOF
  fi
     libs_x="-laudio $libs_x" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-laudio\" to \$libs_x"; fi
             cat > conftest.$ac_ext <<EOF
  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 13381 "configure"
+#line 13458 "configure"

 #include "confdefs.h"
 #include <audio/Xtutil.h>
 EOF
 #include "confdefs.h"
 #include <audio/Xtutil.h>
 EOF

@@ -13408,7 +13485,7 @@ if test "$with_esd_sound" != "no"; then
   # 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
   # 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:13412: checking for $ac_word" >&5
+echo "configure:13489: 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.
 
 if test -n "$have_esd_config"; then
   ac_cv_prog_have_esd_config="$have_esd_config" # Let the user override the test.

@@ -13437,10 +13514,10 @@ fi
     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
     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:13441: checking for esd_play_stream" >&5
+echo "configure:13518: checking for esd_play_stream" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13444 "configure"
+#line 13521 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char esd_play_stream(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char esd_play_stream(); below.  */

@@ -13463,7 +13540,7 @@ esd_play_stream();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:13467: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13544: \"$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
   rm -rf conftest*
   eval "ac_cv_func_esd_play_stream=yes"
 else

@@ -13514,7 +13591,7 @@ test -z "$with_tty" && with_tty=yes
 
 if test "$with_tty" = "yes"  ; then
   echo "checking for TTY-related features" 1>&6
 
 if test "$with_tty" = "yes"  ; then
   echo "checking for TTY-related features" 1>&6

-echo "configure:13518: checking for TTY-related features" >&5
+echo "configure:13595: checking for TTY-related features" >&5

   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_TTY
 EOF
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_TTY
 EOF

@@ -13530,12 +13607,12 @@ EOF
     if test -z "$with_ncurses"; then
     
 echo $ac_n "checking for tgetent in -lncurses""... $ac_c" 1>&6
     if test -z "$with_ncurses"; then
     
 echo $ac_n "checking for tgetent in -lncurses""... $ac_c" 1>&6

-echo "configure:13534: checking for tgetent in -lncurses" >&5
+echo "configure:13611: checking for tgetent in -lncurses" >&5

 ac_lib_var=`echo ncurses'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lncurses "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo ncurses'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lncurses "
 cat > conftest.$ac_ext <<EOF

-#line 13539 "configure"
+#line 13616 "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
 #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

@@ -13546,7 +13623,7 @@ int main() {
 tgetent()
 ; return 0; }
 EOF
 tgetent()
 ; return 0; }
 EOF

-if { (eval echo configure:13550: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13627: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13579,15 +13656,15 @@ EOF
 
     ac_safe=`echo "ncurses/curses.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/curses.h""... $ac_c" 1>&6
 
     ac_safe=`echo "ncurses/curses.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/curses.h""... $ac_c" 1>&6

-echo "configure:13583: checking for ncurses/curses.h" >&5
+echo "configure:13660: checking for ncurses/curses.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13586 "configure"
+#line 13663 "configure"

 #include "confdefs.h"
 #include <ncurses/curses.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <ncurses/curses.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13591: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13668: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13609,15 +13686,15 @@ fi
 
     ac_safe=`echo "ncurses/term.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/term.h""... $ac_c" 1>&6
 
     ac_safe=`echo "ncurses/term.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/term.h""... $ac_c" 1>&6

-echo "configure:13613: checking for ncurses/term.h" >&5
+echo "configure:13690: checking for ncurses/term.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13616 "configure"
+#line 13693 "configure"

 #include "confdefs.h"
 #include <ncurses/term.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <ncurses/term.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13621: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13698: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13647,15 +13724,15 @@ fi
       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
       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:13651: checking for ncurses/curses.h" >&5
+echo "configure:13728: checking for ncurses/curses.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13654 "configure"
+#line 13731 "configure"

 #include "confdefs.h"
 #include <ncurses/curses.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <ncurses/curses.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13659: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13736: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13690,12 +13767,12 @@ fi
        for lib in curses termlib termcap; do
          
 echo $ac_n "checking for tgetent in -l$lib""... $ac_c" 1>&6
        for lib in curses termlib termcap; do
          
 echo $ac_n "checking for tgetent in -l$lib""... $ac_c" 1>&6

-echo "configure:13694: checking for tgetent in -l$lib" >&5
+echo "configure:13771: 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
 ac_lib_var=`echo $lib'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$lib "
 cat > conftest.$ac_ext <<EOF

-#line 13699 "configure"
+#line 13776 "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
 #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

@@ -13706,7 +13783,7 @@ int main() {
 tgetent()
 ; return 0; }
 EOF
 tgetent()
 ; return 0; }
 EOF

-if { (eval echo configure:13710: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13787: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13731,12 +13808,12 @@ fi
     else       if test -n "$libs_termcap" -a "$opsys" = "openbsd"; then
                                 
 echo $ac_n "checking for tgoto in -ltermcap""... $ac_c" 1>&6
     else       if test -n "$libs_termcap" -a "$opsys" = "openbsd"; then
                                 
 echo $ac_n "checking for tgoto in -ltermcap""... $ac_c" 1>&6

-echo "configure:13735: checking for tgoto in -ltermcap" >&5
+echo "configure:13812: checking for tgoto in -ltermcap" >&5

 ac_lib_var=`echo termcap'_'tgoto | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltermcap "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo termcap'_'tgoto | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltermcap "
 cat > conftest.$ac_ext <<EOF

-#line 13740 "configure"
+#line 13817 "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
 #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

@@ -13747,7 +13824,7 @@ int main() {
 tgoto()
 ; return 0; }
 EOF
 tgoto()
 ; return 0; }
 EOF

-if { (eval echo configure:13751: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13828: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13792,12 +13869,12 @@ fi
       else
        
 echo $ac_n "checking for tgetent in -lcurses""... $ac_c" 1>&6
       else
        
 echo $ac_n "checking for tgetent in -lcurses""... $ac_c" 1>&6

-echo "configure:13796: checking for tgetent in -lcurses" >&5
+echo "configure:13873: checking for tgetent in -lcurses" >&5

 ac_lib_var=`echo curses'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcurses "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo curses'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcurses "
 cat > conftest.$ac_ext <<EOF

-#line 13801 "configure"
+#line 13878 "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
 #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

@@ -13808,7 +13885,7 @@ int main() {
 tgetent()
 ; return 0; }
 EOF
 tgetent()
 ; return 0; }
 EOF

-if { (eval echo configure:13812: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13889: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13826,12 +13903,12 @@ if eval "test \"`echo '$ac_cv_lib_'$ac_lib_var`\" = yes" ; then
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for tgetent in -ltermcap""... $ac_c" 1>&6
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for tgetent in -ltermcap""... $ac_c" 1>&6

-echo "configure:13830: checking for tgetent in -ltermcap" >&5
+echo "configure:13907: checking for tgetent in -ltermcap" >&5

 ac_lib_var=`echo termcap'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltermcap "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo termcap'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltermcap "
 cat > conftest.$ac_ext <<EOF

-#line 13835 "configure"
+#line 13912 "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
 #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

@@ -13842,7 +13919,7 @@ int main() {
 tgetent()
 ; return 0; }
 EOF
 tgetent()
 ; return 0; }
 EOF

-if { (eval echo configure:13846: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13923: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13890,15 +13967,15 @@ EOF
 
     test -z "$with_gpm" && { ac_safe=`echo "gpm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for gpm.h""... $ac_c" 1>&6
 
     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:13894: checking for gpm.h" >&5
+echo "configure:13971: checking for gpm.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13897 "configure"
+#line 13974 "configure"

 #include "confdefs.h"
 #include <gpm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <gpm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:13902: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13979: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -13921,12 +13998,12 @@ fi
  }
   test -z "$with_gpm" && { 
 echo $ac_n "checking for Gpm_Open in -lgpm""... $ac_c" 1>&6
  }
   test -z "$with_gpm" && { 
 echo $ac_n "checking for Gpm_Open in -lgpm""... $ac_c" 1>&6

-echo "configure:13925: checking for Gpm_Open in -lgpm" >&5
+echo "configure:14002: 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
 ac_lib_var=`echo gpm'_'Gpm_Open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgpm "
 cat > conftest.$ac_ext <<EOF

-#line 13930 "configure"
+#line 14007 "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
 #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

@@ -13937,7 +14014,7 @@ int main() {
 Gpm_Open()
 ; return 0; }
 EOF
 Gpm_Open()
 ; return 0; }
 EOF

-if { (eval echo configure:13941: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14018: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -13987,20 +14064,20 @@ test "$with_x11" = "yes" -o "$with_tty" = "yes" -o "$need_event_unixoid" = "yes"
 
 test "$with_database_gdbm $with_database_dbm $with_database_berkdb" \
   != "no no no" && echo "checking for database support" 1>&6
 
 test "$with_database_gdbm $with_database_dbm $with_database_berkdb" \
   != "no no no" && echo "checking for database support" 1>&6

-echo "configure:13991: checking for database support" >&5
+echo "configure:14068: 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
 
 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:13996: checking for ndbm.h" >&5
+echo "configure:14073: checking for ndbm.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 13999 "configure"
+#line 14076 "configure"

 #include "confdefs.h"
 #include <ndbm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <ndbm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:14004: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:14081: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -14030,12 +14107,12 @@ fi
 if test "$with_database_gdbm" != "no"; then
   
 echo $ac_n "checking for dbm_open in -lgdbm""... $ac_c" 1>&6
 if test "$with_database_gdbm" != "no"; then
   
 echo $ac_n "checking for dbm_open in -lgdbm""... $ac_c" 1>&6

-echo "configure:14034: checking for dbm_open in -lgdbm" >&5
+echo "configure:14111: 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
 ac_lib_var=`echo gdbm'_'dbm_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdbm "
 cat > conftest.$ac_ext <<EOF

-#line 14039 "configure"
+#line 14116 "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
 #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

@@ -14046,7 +14123,7 @@ int main() {
 dbm_open()
 ; return 0; }
 EOF
 dbm_open()
 ; return 0; }
 EOF

-if { (eval echo configure:14050: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14127: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -14074,10 +14151,10 @@ fi
 
 if test "$with_database_dbm" != "no"; then
   echo $ac_n "checking for dbm_open""... $ac_c" 1>&6
 
 if test "$with_database_dbm" != "no"; then
   echo $ac_n "checking for dbm_open""... $ac_c" 1>&6

-echo "configure:14078: checking for dbm_open" >&5
+echo "configure:14155: checking for dbm_open" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 14081 "configure"
+#line 14158 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char dbm_open(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char dbm_open(); below.  */

@@ -14100,7 +14177,7 @@ dbm_open();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:14104: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14181: \"$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
   rm -rf conftest*
   eval "ac_cv_func_dbm_open=yes"
 else

@@ -14119,12 +14196,12 @@ else
 
     
 echo $ac_n "checking for dbm_open in -ldbm""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for dbm_open in -ldbm""... $ac_c" 1>&6

-echo "configure:14123: checking for dbm_open in -ldbm" >&5
+echo "configure:14200: 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
 ac_lib_var=`echo dbm'_'dbm_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldbm "
 cat > conftest.$ac_ext <<EOF

-#line 14128 "configure"
+#line 14205 "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
 #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

@@ -14135,7 +14212,7 @@ int main() {
 dbm_open()
 ; return 0; }
 EOF
 dbm_open()
 ; return 0; }
 EOF

-if { (eval echo configure:14139: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14216: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -14176,12 +14253,12 @@ EOF
 
 if test "$with_database_berkdb" != "no"; then
   echo $ac_n "checking for Berkeley db.h""... $ac_c" 1>&6
 
 if test "$with_database_berkdb" != "no"; then
   echo $ac_n "checking for Berkeley db.h""... $ac_c" 1>&6

-echo "configure:14180: checking for Berkeley db.h" >&5
+echo "configure:14257: checking for Berkeley db.h" >&5

   for header in "db/db.h" "db.h"; do
     case "$opsys" in
         *freebsd*)
     cat > conftest.$ac_ext <<EOF
   for header in "db/db.h" "db.h"; do
     case "$opsys" in
         *freebsd*)
     cat > conftest.$ac_ext <<EOF

-#line 14185 "configure"
+#line 14262 "configure"

 #include "confdefs.h"
 
 #include <stdlib.h>
 #include "confdefs.h"
 
 #include <stdlib.h>

@@ -14197,7 +14274,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:14201: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:14278: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   db_h_file="$header"; break
 else
   rm -rf conftest*
   db_h_file="$header"; break
 else

@@ -14208,7 +14285,7 @@ rm -f conftest*
         ;;
         *)
     cat > conftest.$ac_ext <<EOF
         ;;
         *)
     cat > conftest.$ac_ext <<EOF

-#line 14212 "configure"
+#line 14289 "configure"

 #include "confdefs.h"
 
 #include <stdlib.h>
 #include "confdefs.h"
 
 #include <stdlib.h>

@@ -14230,7 +14307,7 @@ int main() {
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:14234: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:14311: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then

   rm -rf conftest*
   db_h_file="$header"; break
 else
   rm -rf conftest*
   db_h_file="$header"; break
 else

@@ -14248,9 +14325,9 @@ rm -f conftest*
 
   if test "$with_database_berkdb" != "no"; then
     echo $ac_n "checking for Berkeley DB version""... $ac_c" 1>&6
 
   if test "$with_database_berkdb" != "no"; then
     echo $ac_n "checking for Berkeley DB version""... $ac_c" 1>&6

-echo "configure:14252: checking for Berkeley DB version" >&5
+echo "configure:14329: checking for Berkeley DB version" >&5

     cat > conftest.$ac_ext <<EOF
     cat > conftest.$ac_ext <<EOF

-#line 14254 "configure"
+#line 14331 "configure"

 #include "confdefs.h"
 #include <$db_h_file>
 #if DB_VERSION_MAJOR > 1
 #include "confdefs.h"
 #include <$db_h_file>
 #if DB_VERSION_MAJOR > 1

@@ -14262,7 +14339,7 @@ if (eval "$ac_cpp conftest.$ac_ext") 2>&5 |
   egrep "yes" >/dev/null 2>&1; then
   rm -rf conftest*
   cat > conftest.$ac_ext <<EOF
   egrep "yes" >/dev/null 2>&1; then
   rm -rf conftest*
   cat > conftest.$ac_ext <<EOF

-#line 14266 "configure"
+#line 14343 "configure"

 #include "confdefs.h"
 #include <$db_h_file>
 #if DB_VERSION_MAJOR > 2
 #include "confdefs.h"
 #include <$db_h_file>
 #if DB_VERSION_MAJOR > 2

@@ -14289,10 +14366,10 @@ fi
 rm -f conftest*
 
     echo $ac_n "checking for $dbfunc""... $ac_c" 1>&6
 rm -f conftest*
 
     echo $ac_n "checking for $dbfunc""... $ac_c" 1>&6

-echo "configure:14293: checking for $dbfunc" >&5
+echo "configure:14370: checking for $dbfunc" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 14296 "configure"
+#line 14373 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $dbfunc(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $dbfunc(); below.  */

@@ -14315,7 +14392,7 @@ $dbfunc();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:14319: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14396: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$dbfunc=yes"
 else

@@ -14334,12 +14411,12 @@ else
 
     
 echo $ac_n "checking for $dbfunc in -ldb""... $ac_c" 1>&6
 
     
 echo $ac_n "checking for $dbfunc in -ldb""... $ac_c" 1>&6

-echo "configure:14338: checking for $dbfunc in -ldb" >&5
+echo "configure:14415: checking for $dbfunc in -ldb" >&5

 ac_lib_var=`echo db'_'$dbfunc | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldb "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo db'_'$dbfunc | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldb "
 cat > conftest.$ac_ext <<EOF

-#line 14343 "configure"
+#line 14420 "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
 #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

@@ -14350,7 +14427,7 @@ int main() {
 $dbfunc()
 ; return 0; }
 EOF
 $dbfunc()
 ; return 0; }
 EOF

-if { (eval echo configure:14354: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14431: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -14414,12 +14491,12 @@ fi
 if test "$with_socks" = "yes"; then
   
 echo $ac_n "checking for SOCKSinit in -lsocks""... $ac_c" 1>&6
 if test "$with_socks" = "yes"; then
   
 echo $ac_n "checking for SOCKSinit in -lsocks""... $ac_c" 1>&6

-echo "configure:14418: checking for SOCKSinit in -lsocks" >&5
+echo "configure:14495: checking for SOCKSinit in -lsocks" >&5

 ac_lib_var=`echo socks'_'SOCKSinit | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lsocks "
 cat > conftest.$ac_ext <<EOF
 ac_lib_var=`echo socks'_'SOCKSinit | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lsocks "
 cat > conftest.$ac_ext <<EOF

-#line 14423 "configure"
+#line 14500 "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
 #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

@@ -14430,7 +14507,7 @@ int main() {
 SOCKSinit()
 ; return 0; }
 EOF
 SOCKSinit()
 ; return 0; }
 EOF

-if { (eval echo configure:14434: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14511: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -14485,7 +14562,7 @@ fi
 
 if test "$with_modules" != "no"; then
   echo "checking for module support" 1>&6
 
 if test "$with_modules" != "no"; then
   echo "checking for module support" 1>&6

-echo "configure:14489: checking for module support" >&5
+echo "configure:14566: checking for module support" >&5

 
     if test "$with_msw" = "yes"; then
     have_dl=yes;
 
     if test "$with_msw" = "yes"; then
     have_dl=yes;

@@ -14501,15 +14578,15 @@ EOF
  ;;
       *)          ac_safe=`echo "dlfcn.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for dlfcn.h""... $ac_c" 1>&6
  ;;
       *)          ac_safe=`echo "dlfcn.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for dlfcn.h""... $ac_c" 1>&6

-echo "configure:14505: checking for dlfcn.h" >&5
+echo "configure:14582: checking for dlfcn.h" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 14508 "configure"
+#line 14585 "configure"

 #include "confdefs.h"
 #include <dlfcn.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
 #include "confdefs.h"
 #include <dlfcn.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"

-{ (eval echo configure:14513: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:14590: \"$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*
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*

@@ -14526,16 +14603,16 @@ if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
   echo "$ac_t""yes" 1>&6
   
            echo $ac_n "checking for dlopen in -lc""... $ac_c" 1>&6
   echo "$ac_t""yes" 1>&6
   
            echo $ac_n "checking for dlopen in -lc""... $ac_c" 1>&6

-echo "configure:14530: checking for dlopen in -lc" >&5
+echo "configure:14607: checking for dlopen in -lc" >&5

            cat > conftest.$ac_ext <<EOF
            cat > conftest.$ac_ext <<EOF

-#line 14532 "configure"
+#line 14609 "configure"

 #include "confdefs.h"
 #include <dlfcn.h>
 int main() {
              dlopen ("", 0);
 ; return 0; }
 EOF
 #include "confdefs.h"
 #include <dlfcn.h>
 int main() {
              dlopen ("", 0);
 ; return 0; }
 EOF

-if { (eval echo configure:14539: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14616: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
    have_dl=yes 
 else
   rm -rf conftest*
    have_dl=yes 
 else

@@ -14544,18 +14621,18 @@ else
   rm -rf conftest*
   
                echo $ac_n "checking for dlopen in -ldl""... $ac_c" 1>&6
   rm -rf conftest*
   
                echo $ac_n "checking for dlopen in -ldl""... $ac_c" 1>&6

-echo "configure:14548: checking for dlopen in -ldl" >&5
+echo "configure:14625: checking for dlopen in -ldl" >&5

                ac_save_LIBS="$LIBS"
                LIBS="-ldl $LIBS"
                cat > conftest.$ac_ext <<EOF
                ac_save_LIBS="$LIBS"
                LIBS="-ldl $LIBS"
                cat > conftest.$ac_ext <<EOF

-#line 14552 "configure"
+#line 14629 "configure"

 #include "confdefs.h"
 #include <dlfcn.h>
 int main() {
                 dlopen ("", 0);
 ; return 0; }
 EOF
 #include "confdefs.h"
 #include <dlfcn.h>
 int main() {
                 dlopen ("", 0);
 ; return 0; }
 EOF

-if { (eval echo configure:14559: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14636: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
    have_dl=yes 
 else
   rm -rf conftest*
    have_dl=yes 
 else

@@ -14584,12 +14661,12 @@ EOF
         else
            
 echo $ac_n "checking for shl_load in -ldld""... $ac_c" 1>&6
         else
            
 echo $ac_n "checking for shl_load in -ldld""... $ac_c" 1>&6

-echo "configure:14588: checking for shl_load in -ldld" >&5
+echo "configure:14665: 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
 ac_lib_var=`echo dld'_'shl_load | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldld "
 cat > conftest.$ac_ext <<EOF

-#line 14593 "configure"
+#line 14670 "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
 #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

@@ -14600,7 +14677,7 @@ int main() {
 shl_load()
 ; return 0; }
 EOF
 shl_load()
 ; return 0; }
 EOF

-if { (eval echo configure:14604: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14681: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -14627,12 +14704,12 @@ else
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for dld_init in -ldld""... $ac_c" 1>&6
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for dld_init in -ldld""... $ac_c" 1>&6

-echo "configure:14631: checking for dld_init in -ldld" >&5
+echo "configure:14708: 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
 ac_lib_var=`echo dld'_'dld_init | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldld "
 cat > conftest.$ac_ext <<EOF

-#line 14636 "configure"
+#line 14713 "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
 #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

@@ -14643,7 +14720,7 @@ int main() {
 dld_init()
 ; return 0; }
 EOF
 dld_init()
 ; return 0; }
 EOF

-if { (eval echo configure:14647: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14724: \"$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
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else

@@ -14690,7 +14767,7 @@ xehost=$canonical
 xealias=$internal_configuration
 
 echo "checking how to build dynamic libraries for ${xehost}" 1>&6
 xealias=$internal_configuration
 
 echo "checking how to build dynamic libraries for ${xehost}" 1>&6

-echo "configure:14694: checking how to build dynamic libraries for ${xehost}" >&5
+echo "configure:14771: checking how to build dynamic libraries for ${xehost}" >&5

 # Transform *-*-linux* to *-*-linux-gnu*, to support old configure scripts.
 case "$xehost" in
 *-*-linux-gnu*) ;;
 # Transform *-*-linux* to *-*-linux-gnu*, to support old configure scripts.
 case "$xehost" in
 *-*-linux-gnu*) ;;

@@ -14718,9 +14795,9 @@ if test "$GCC" = "yes"; then
   XEGCC=yes
 else
   echo $ac_n "checking checking whether we are using GNU C""... $ac_c" 1>&6
   XEGCC=yes
 else
   echo $ac_n "checking checking whether we are using GNU C""... $ac_c" 1>&6

-echo "configure:14722: checking checking whether we are using GNU C" >&5
+echo "configure:14799: checking checking whether we are using GNU C" >&5

   cat > conftest.$ac_ext <<EOF
   cat > conftest.$ac_ext <<EOF

-#line 14724 "configure"
+#line 14801 "configure"

 #include "confdefs.h"
 
 #ifdef __GNUC__
 #include "confdefs.h"
 
 #ifdef __GNUC__

@@ -14742,11 +14819,11 @@ rm -f conftest*
 fi
 
 echo $ac_n "checking how to produce PIC code""... $ac_c" 1>&6
 fi
 
 echo $ac_n "checking how to produce PIC code""... $ac_c" 1>&6

-echo "configure:14746: checking how to produce PIC code" >&5
+echo "configure:14823: checking how to produce PIC code" >&5

 wl=
 
 can_build_shared=yes
 wl=
 
 can_build_shared=yes

-if test "$XEGCC" = yes; then
+if test "$XEGCC" = yes -o "$__ICC" = yes; then

   wl='-Wl,'
 
   case "$xehost_os" in
   wl='-Wl,'
 
   case "$xehost_os" in

@@ -14843,18 +14920,18 @@ if test -n "$dll_cflags"; then
 
   # Check to make sure the dll_cflags actually works.
   echo $ac_n "checking if PIC flag ${dll_cflags} really works""... $ac_c" 1>&6
 
   # 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:14847: checking if PIC flag ${dll_cflags} really works" >&5
+echo "configure:14924: checking if PIC flag ${dll_cflags} really works" >&5

   save_CFLAGS="$CFLAGS"
   CFLAGS="$CFLAGS $dll_cflags -DPIC"
   cat > conftest.$ac_ext <<EOF
   save_CFLAGS="$CFLAGS"
   CFLAGS="$CFLAGS $dll_cflags -DPIC"
   cat > conftest.$ac_ext <<EOF

-#line 14851 "configure"
+#line 14928 "configure"

 #include "confdefs.h"
 
 int main() {
 int x=0;
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 int x=0;
 ; return 0; }
 EOF

-if { (eval echo configure:14858: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:14935: \"$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
   rm -rf conftest*
   
     # On HP-UX, the stripped-down bundled CC doesn't accept +Z, but also

@@ -14885,8 +14962,8 @@ cc_produces_so=no
 xldf=
 xcldf=
 echo $ac_n "checking if C compiler can produce shared libraries""... $ac_c" 1>&6
 xldf=
 xcldf=
 echo $ac_n "checking if C compiler can produce shared libraries""... $ac_c" 1>&6

-echo "configure:14889: checking if C compiler can produce shared libraries" >&5
-if test "$XEGCC" = yes; then
+echo "configure:14966: checking if C compiler can produce shared libraries" >&5
+if test "$XEGCC" = yes -o "$__ICC" = yes; then

   xcldf="-shared"
   xldf="-shared"
 else # Not using GCC
   xcldf="-shared"
   xldf="-shared"
 else # Not using GCC

@@ -14936,14 +15013,14 @@ if test -n "$xcldf"; then
   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
   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 14940 "configure"
+#line 15017 "configure"

 #include "confdefs.h"
 
 int main() {
 int x=0;
 ; return 0; }
 EOF
 #include "confdefs.h"
 
 int main() {
 int x=0;
 ; return 0; }
 EOF

-if { (eval echo configure:14947: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:15024: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then

   rm -rf conftest*
   cc_produces_so=yes
 else
   rm -rf conftest*
   cc_produces_so=yes
 else

@@ -14968,7 +15045,7 @@ if test -z "$LTLD"; then
   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
   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:14972: checking for ld used by GCC" >&5
+echo "configure:15049: checking for ld used by GCC" >&5

     ac_prog=`($CC -print-prog-name=ld) 2>&5`
     case "$ac_prog" in
     # Accept absolute paths.
     ac_prog=`($CC -print-prog-name=ld) 2>&5`
     case "$ac_prog" in
     # Accept absolute paths.

@@ -14994,7 +15071,7 @@ echo "configure:14972: checking for ld used by GCC" >&5
     esac
   else
     echo $ac_n "checking for GNU ld""... $ac_c" 1>&6
     esac
   else
     echo $ac_n "checking for GNU ld""... $ac_c" 1>&6

-echo "configure:14998: checking for GNU ld" >&5
+echo "configure:15075: checking for GNU ld" >&5

   fi
 
   if test -z "$LTLD"; then
   fi
 
   if test -z "$LTLD"; then

@@ -15032,7 +15109,7 @@ ld_dynamic_link_flags=
 
 # 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
 
 # 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:15036: checking if the linker is GNU ld" >&5
+echo "configure:15113: 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
 # 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

@@ -15060,7 +15137,7 @@ else
   # 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
   # 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:15064: checking whether the linker supports shared libraries" >&5
+echo "configure:15141: checking whether the linker supports shared libraries" >&5

   dll_ld=$CC
   dll_ldflags=$LDFLAGS
   ld_shlibs=yes
   dll_ld=$CC
   dll_ldflags=$LDFLAGS
   ld_shlibs=yes

@@ -15271,10 +15348,10 @@ EOF
     for ac_func in dlerror _dlerror
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
     for ac_func in dlerror _dlerror
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6

-echo "configure:15275: checking for $ac_func" >&5
+echo "configure:15352: checking for $ac_func" >&5

 
 cat > conftest.$ac_ext <<EOF
 
 cat > conftest.$ac_ext <<EOF

-#line 15278 "configure"
+#line 15355 "configure"

 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */

@@ -15297,7 +15374,7 @@ $ac_func();
 
 ; return 0; }
 EOF
 
 ; return 0; }
 EOF

-if { (eval echo configure:15301: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:15378: \"$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
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else

@@ -15336,11 +15413,11 @@ done
 fi
 
 cat > conftest.$ac_ext <<EOF
 fi
 
 cat > conftest.$ac_ext <<EOF

-#line 15340 "configure"
+#line 15417 "configure"

 #include "confdefs.h"
 int main(int c,char *v[]){return 0;}
 EOF
 #include "confdefs.h"
 int main(int c,char *v[]){return 0;}
 EOF

-if { (eval echo configure:15344: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:15421: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5

 then
   :
 else
 then
   :
 else

@@ -15980,6 +16057,66 @@ else echo "  Not using any machine description file"
 fi
 
 echo "  Compiler:                          $CC $CFLAGS"
 fi
 
 echo "  Compiler:                          $CC $CFLAGS"

+case "$CC" in
+  gcc*)        echo "  Compiler version:                  `$CC --version | head -1`"
+        echo "  Compiler specs file:               `$CC -v 2>&1 | sed 's/.* \([^ ]\)/\1/' | head -1`"
+       ;;
+  *) case "$canonical" in
+       *-*-aix*   ) 
+                 realcc=`which $CC`
+                 if test -L $realcc ; then
+           ccdir=`dirname $realcc`
+           ccprog=`/bin/ls -l $realcc | sed 's/.* \([^ ]\)/\1/'`
+                   case $ccprog in
+               */*) realcc=$ccprog;;
+               *) realcc=$ccdir/$ccprog;;
+           esac
+         fi
+         lpp=`lslpp -wqc $realcc | cut -f2 -d:`
+         if test ! -z "$lpp" ; then
+           lppstr=`lslpp -Lqc $lpp`
+           lpplev=`echo "$lppstr" | cut -f3 -d:`
+           lppdesc=`echo "$lppstr" | cut -f8 -d:`
+         fi
+         if test ! -z "$lpplev" ; then
+           echo "  Compiler version:                  $lpp $lpplev - $lppdesc"
+         else
+           echo "  Compiler version:                  (unknown version)"
+         fi
+       ;;
+       
+       *-*-solaris*)
+         ccvers=`$CC -V 2>&1 | head -1`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+
+       alpha*-dec-osf*)
+         ccvers=`$CC -V | tr '\n' ' '`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+
+       mips-sgi-irix*)
+         ccvers=`$CC -version`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+
+               i[3-9]86-pc-linux)
+         ccvers=`$CC -V 2>&1 | sed -n 's@^Intel.*Version @@'p`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+         
+       *) echo "  Compiler version:                  $CC on $canonical";;
+  esac
+esac
+

 echo "  Relocating allocator for buffers:  $rel_alloc"
 echo "  GNU version of malloc:             ${GNU_MALLOC}${GNU_MALLOC_reason}"
 case "$ld_switch_site" in
 echo "  Relocating allocator for buffers:  $rel_alloc"
 echo "  GNU version of malloc:             ${GNU_MALLOC}${GNU_MALLOC_reason}"
 case "$ld_switch_site" in

@@ -15987,6 +16124,42 @@ case "$ld_switch_site" in
     - Consider configuring with --pdump." ;;
 esac
 
     - Consider configuring with --pdump." ;;
 esac
 

+case "$canonical" in
+       *-*-linux*) 
+         if test -f /etc/redhat-release ; then
+           echo "  libc:                              `rpm -q glibc`";
+          else
+           echo "Need to guess glibc1/2/etc here";
+          fi
+       ;;
+
+       *-*-aix*) 
+         echo "  libc:                              bos.rte.libc `lslpp -Lqc bos.rte.libc | cut -f3 -d:`" 
+       ;;
+
+       *-*-solaris*)
+         libc=`pkginfo -l SUNWcsl | grep VERSION: | awk '{print $2}'`
+         echo "  libc:                              SUNWcsl $libc"
+
+       ;;
+
+       mips-sgi-irix*)
+         echo "  IRIX version:                      `uname -sRm`'"
+       ;;
+         
+
+       alpha*-dec-osf*)
+                 (cd /usr/.smdb.;
+               libc=` grep -h libc.so *.inv | awk '$9 == "f" {print $12}' | tr '\n' ','`
+               echo "  libc:                              $libc"
+               
+         )
+       ;;
+
+       *) echo "  libc:                              system-provided libc on $canonical" ;;
+esac
+
+

 echo "
 Window System:"
 if test "$with_msw" = "yes"; then
 echo "
 Window System:"
 if test "$with_msw" = "yes"; then

@@ -16008,6 +16181,9 @@ if test "$with_x11" = "yes"; then
 fi
 if test "$need_motif" = "yes" ; then
   echo "  Compiling in support for Motif."
 fi
 if test "$need_motif" = "yes" ; then
   echo "  Compiling in support for Motif."

+  if test "$have_lesstif" = "yes"; then
+    echo "    - Using LessTif implementation."
+  fi

   echo "  *WARNING*  Many versions of Motif are buggy, requiring workarounds."
   echo "             You are likely to experience slow redisplay."
   echo "             You may need to install vendor patches to Motif."
   echo "  *WARNING*  Many versions of Motif are buggy, requiring workarounds."
   echo "             You are likely to experience slow redisplay."
   echo "             You may need to install vendor patches to Motif."

diff --git a/configure.in b/configure.in
index 4135e38..8904f22 100644 (file)
--- a/configure.in
+++ b/configure.in
@@ -348,6 +348,7 @@ with_site_lisp='no'
 with_site_modules='yes'
 with_menubars=''
 with_scrollbars=''
 with_site_modules='yes'
 with_menubars=''
 with_scrollbars=''

+dnl can't turn off widgets here because of systems where they are demanded

 with_widgets=''
 with_dialogs=''
 with_file_coding=''
 with_widgets=''
 with_dialogs=''
 with_file_coding=''

@@ -1451,9 +1452,14 @@ case "$canonical" in
     esac
 
     case "$canonical" in
     esac
 
     case "$canonical" in

-      *-solaris*         )
+      *-solaris* )

        opsys=sol2
        opsys=sol2

-       os_release=`uname -r | sed -e 's/^\([[0-9]]\)\.\([[0-9]]\).*/\1\2/'`
+       os_release_major=`uname -r | sed -e 's/^\([[0-9]]\{1,\}\)\.\([[0-9]]\{1,\}\).*/\1/'`
+       os_release_minor=`uname -r | sed -e 's/^\([[0-9]]\{1,\}\)\.\([[0-9]]\{1,\}\).*/\2/'`
+       case "$os_release_minor" in [[0-9]])
+         os_release_minor="0${os_release_minor}";;
+       esac
+       os_release="${os_release_major}${os_release_minor}"

        AC_DEFINE_UNQUOTED(OS_RELEASE, $os_release) ;;
 
       dnl The last Sun386 ran 4.0.
        AC_DEFINE_UNQUOTED(OS_RELEASE, $os_release) ;;
 
       dnl The last Sun386 ran 4.0.

@@ -1703,7 +1709,7 @@ case "$opsys" in
   sol2)
    AC_DEFINE(__EXTENSIONS__)
    dnl Solaris 2 before 2.5 had some bugs with feature test macro interaction.
   sol2)
    AC_DEFINE(__EXTENSIONS__)
    dnl Solaris 2 before 2.5 had some bugs with feature test macro interaction.

-   if test "$os_release" -ge 55; then
+   if test "$os_release" -ge 505; then

      AC_DEFINE(_XOPEN_SOURCE,500)
      AC_DEFINE(_XOPEN_SOURCE_EXTENDED)
    fi ;;
      AC_DEFINE(_XOPEN_SOURCE,500)
      AC_DEFINE(_XOPEN_SOURCE_EXTENDED)
    fi ;;

@@ -1724,14 +1730,19 @@ return 11;
 return 12;
 #elif defined __USLC__ && defined __SCO_VERSION__
 return 13;
 return 12;
 #elif defined __USLC__ && defined __SCO_VERSION__
 return 13;

+#elif defined __INTEL_COMPILER
+return 14;

 #else
 return 0;
 #endif
 }], [],
 [case "$conftest_rc" in
 #else
 return 0;
 #endif
 }], [],
 [case "$conftest_rc" in

-  11) echo "You appear to be using the SunPro C compiler."; __SUNPRO_C=yes ;;
-  12) echo "You appear to be using the DEC C compiler."   ; __DECC=yes ;;
-  13) echo "You appear to be using the SCO C compiler."   ; __USLC__=yes ;;
+  11) echo "You appear to be using the SunPro C compiler." ; __SUNPRO_C=yes ;;
+  12) echo "You appear to be using the DEC C compiler."    ; __DECC=yes ;;
+  13) echo "You appear to be using the SCO C compiler."    ; __USLC__=yes ;;
+  14) echo "You appear to be using the Intel C++ compiler."; __ICC=yes
+      dnl Newer versions of icc claim to be GCC
+      GCC=no ;;

 esac])
 
 
 esac])
 
 

@@ -1950,6 +1961,8 @@ if test "$cflags_specified" = "no"; then
     CFLAGS="-O3"
   elif test "$CC" = "xlc"; then
     CFLAGS="-g -O3 -qstrict -qnoansialias -qlibansi -qinfo -qro -qmaxmem=20000"
     CFLAGS="-O3"
   elif test "$CC" = "xlc"; then
     CFLAGS="-g -O3 -qstrict -qnoansialias -qlibansi -qinfo -qro -qmaxmem=20000"

+  elif test "$__ICC" = "yes"; then
+    CFLAGS="-g -O3 -Ob2 -Wall -W1"

   dnl ### Add optimal CFLAGS support for other compilers HERE!
   else
     CFLAGS="-O" ;dnl The only POSIX-approved flag
   dnl ### Add optimal CFLAGS support for other compilers HERE!
   else
     CFLAGS="-O" ;dnl The only POSIX-approved flag

@@ -2301,6 +2314,7 @@ if test "$add_runtime_path" = "yes" -a -n "$dash_r"; then
       case "$arg" in -L*) XE_ADD_RUNPATH_DIR(`echo '' "$arg" | sed -e 's:^ ::' -e 's/^-L//'`);; esac
     done
     dnl Sometimes /opt/SUNWdt/lib is the only installed Motif available
       case "$arg" in -L*) XE_ADD_RUNPATH_DIR(`echo '' "$arg" | sed -e 's:^ ::' -e 's/^-L//'`);; esac
     done
     dnl Sometimes /opt/SUNWdt/lib is the only installed Motif available

+    dnl #### this test always fails here as need_motif is null

     if test "$opsys $need_motif" = "sol2 yes"; then
       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";
     if test "$opsys $need_motif" = "sol2 yes"; then
       xe_runpath_dir="/opt/SUNWdt/lib";
       eval "$xe_add_unique_runpath_dir";

@@ -2563,7 +2577,7 @@ fi
 
 dnl Link with "-z ignore" on Solaris if supported
 if test "$opsys" = "sol2"; then
 
 dnl Link with "-z ignore" on Solaris if supported
 if test "$opsys" = "sol2"; then

-  if test "$os_release" -ge 56; then
+  if test "$os_release" -ge 506; then

     AC_MSG_CHECKING(for \"-z ignore\" linker flag)
     case "`ld -h 2>&1`" in
       *-z\ ignore\|record* ) AC_MSG_RESULT(yes)
     AC_MSG_CHECKING(for \"-z ignore\" linker flag)
     case "`ld -h 2>&1`" in
       *-z\ ignore\|record* ) AC_MSG_RESULT(yes)

@@ -2968,7 +2982,7 @@ if test "$with_msw" != "no"; then
       XE_APPEND(netinstall, INSTALL_ARCH_DEP_SUBDIR)
     fi
 
       XE_APPEND(netinstall, INSTALL_ARCH_DEP_SUBDIR)
     fi
 

-    install_pp="$blddir/lib-src/installexe.sh"
+    install_pp="$srcdir/lib-src/installexe.sh"

     XE_APPEND(-lshell32 -lgdi32 -luser32 -lcomdlg32 -lcomctl32 -lkernel32 -lwinspool, libs_system)
     test "$with_dragndrop" != no && XE_APPEND(msw, dragndrop_proto)
     if test "$window_system" != x11; then
     XE_APPEND(-lshell32 -lgdi32 -luser32 -lcomdlg32 -lcomctl32 -lkernel32 -lwinspool, libs_system)
     test "$with_dragndrop" != no && XE_APPEND(msw, dragndrop_proto)
     if test "$window_system" != x11; then

@@ -3570,15 +3584,27 @@ fi dnl "$with_x11" = "yes"
 
 dnl Finish ensuring that we have values for the various toolkit items.
 dnl Not all toolkits support all widgets
 
 dnl Finish ensuring that we have values for the various toolkit items.
 dnl Not all toolkits support all widgets

-dnl if Motif is available we use it for the dialog boxes.
+
+dnl Avoid using Motif :-(
+case "$opsys" in
+  *linux* )  lucid_prefers_motif = "no"  ;;
+  * )        lucid_prefers_motif = "yes" ;;
+esac

 
 case "$with_menubars" in "" | "yes" | "athena" )
   with_menubars="lucid" ;;
 esac
 case "$with_dialogs" in "" | "yes" | "lucid" )
 
 case "$with_menubars" in "" | "yes" | "athena" )
   with_menubars="lucid" ;;
 esac
 case "$with_dialogs" in "" | "yes" | "lucid" )

-  if   test "$have_motif"     = "yes"; then with_dialogs="motif"
-  elif test "$have_xaw"       = "yes"; then with_dialogs="athena"
-  else with_dialogs=no
+  if test "$lucid_prefers_motif" = "yes"; then
+    if   test "$have_motif"     = "yes"; then with_dialogs="motif"
+    elif test "$have_xaw"       = "yes"; then with_dialogs="athena"
+    else with_dialogs=no
+    fi
+  else
+    if   test "$have_xaw"       = "yes"; then with_dialogs="athena"
+    elif test "$have_motif"     = "yes"; then with_dialogs="motif"
+    else with_dialogs=no
+    fi

   fi ;;
 esac
 case "$with_scrollbars" in "" | "yes" )
   fi ;;
 esac
 case "$with_scrollbars" in "" | "yes" )

@@ -3586,9 +3612,16 @@ case "$with_scrollbars" in "" | "yes" )
 esac
 case "$with_widgets" in
   "yes" | "lucid")
 esac
 case "$with_widgets" in
   "yes" | "lucid")

-    if   test "$have_motif" = "yes"; then with_widgets="motif"
-    elif test "$have_xaw"   = "yes"; then with_widgets="athena"
-    else with_widgets=no
+    if test "$lucid_prefers_motif" = "yes"; then
+      if   test "$have_motif" = "yes"; then with_widgets="motif"
+      elif test "$have_xaw"   = "yes"; then with_widgets="athena"
+      else with_widgets=no
+      fi
+    else
+      if   test "$have_xaw"   = "yes"; then with_widgets="athena"
+      elif test "$have_motif" = "yes"; then with_widgets="motif"
+      else with_widgets=no
+      fi

     fi ;;
   "" )
     with_widgets=no ;;
     fi ;;
   "" )
     with_widgets=no ;;

@@ -3739,7 +3772,10 @@ if test "$with_mule" = "yes" ; then
     AC_CHECKING(for XIM)
     AC_CHECK_LIB(X11, XOpenIM, with_xim=xlib, with_xim=no)
     dnl XIM + Lesstif is not (yet?) usable
     AC_CHECKING(for XIM)
     AC_CHECK_LIB(X11, XOpenIM, with_xim=xlib, with_xim=no)
     dnl XIM + Lesstif is not (yet?) usable

-    if test "$have_motif $have_lesstif" = "yes no"; then
+    dnl Only use Motif if linking Motif anyway, or don't have xlib XIM
+    if test "$need_motif $have_lesstif" = "yes no"; then
+      AC_CHECK_LIB(Xm, XmImMbLookupString, with_xim=motif)
+    elif test "$have_motif $have_lesstif $with_xim" = "yes no no"; then

       AC_CHECK_LIB(Xm, XmImMbLookupString, with_xim=motif)
     fi ;;
   esac
       AC_CHECK_LIB(Xm, XmImMbLookupString, with_xim=motif)
     fi ;;
   esac

@@ -4150,17 +4186,25 @@ if test "$with_native_sound" != "no"; then
 
   dnl Autodetect Sun native sound from SUNWaudmo package
   if test -z "$sound_found" -a -d "/usr/demo/SOUND"; then
 
   dnl Autodetect Sun native sound from SUNWaudmo package
   if test -z "$sound_found" -a -d "/usr/demo/SOUND"; then

-    sound_found=yes
-    XE_ADD_OBJS(sunplay.o)
-    if test -d "/usr/demo/SOUND/include"
-      then sound_cflags="-I/usr/demo/SOUND/include"
-      else sound_cflags="-I/usr/demo/SOUND"
+    if test -d "/usr/demo/SOUND/include/multimedia"; then
+      sun_sound_cflags="-I/usr/demo/SOUND/include"
+    elif test -d "/usr/demo/SOUND/multimedia"; then
+      sun_sound_cflags="-I/usr/demo/SOUND"

     fi
     fi

-    if test -z "$native_sound_lib" ; then
-      if test -r "/usr/demo/SOUND/lib/libaudio.a"
-        then native_sound_lib="/usr/demo/SOUND/lib/libaudio.a"
-        else native_sound_lib="/usr/demo/SOUND/libaudio.a"
-      fi
+
+    if test -n "$native_sound_lib"; then
+      sun_sound_lib="$native_sound_lib"
+    elif test -r "/usr/demo/SOUND/lib/libaudio.a"; then
+      sun_sound_lib="/usr/demo/SOUND/lib/libaudio.a"
+    elif test -r "/usr/demo/SOUND/libaudio.a"; then
+      sun_sound_lib="/usr/demo/SOUND/libaudio.a"
+    fi
+
+    if test -n "$sun_sound_cflags" -a -n "$sun_sound_lib"; then
+      native_sound_lib="$sun_sound_lib"
+      sound_cflags="$sun_sound_cflags"
+      sound_found=yes
+      XE_ADD_OBJS(sunplay.o)

     fi
   fi
 
     fi
   fi
 

@@ -4970,6 +5014,73 @@ else echo "  Not using any machine description file"
 fi
 
 echo "  Compiler:                          $CC $CFLAGS"
 fi
 
 echo "  Compiler:                          $CC $CFLAGS"

+dnl Let's save some helpful-for-debugging info like compiler and libc versions..
+dnl First, see if it's gcc - the same check works everyplace...
+case "$CC" in
+  gcc*)        echo "  Compiler version:                  `$CC --version | head -1`"
+        echo "  Compiler specs file:               `$CC -v 2>&1 | sed 's/.* \([[^ ]]\)/\1/' | head -1`"
+       ;;
+dnl non-gcc machine-specific magic - contributions welcome
+  *) case "$canonical" in
+       *-*-aix*   ) 
+          dnl Yes, it's this ugly for AIX...
+         realcc=`which $CC`
+         dnl Might be a symlink created by replaceCset command
+         if test -L $realcc ; then
+           ccdir=`dirname $realcc`
+           ccprog=`/bin/ls -l $realcc | sed 's/.* \([[^ ]]\)/\1/'`
+           dnl This doesn't handle ../../xlc type stuff, but I've not seen one...
+           case $ccprog in
+               */*) realcc=$ccprog;;
+               *) realcc=$ccdir/$ccprog;;
+           esac
+         fi
+         lpp=`lslpp -wqc $realcc | cut -f2 -d:`
+         if test ! -z "$lpp" ; then
+           lppstr=`lslpp -Lqc $lpp`
+           lpplev=`echo "$lppstr" | cut -f3 -d:`
+           lppdesc=`echo "$lppstr" | cut -f8 -d:`
+         fi
+         if test ! -z "$lpplev" ; then
+           echo "  Compiler version:                  $lpp $lpplev - $lppdesc"
+         else
+           echo "  Compiler version:                  (unknown version)"
+         fi
+       ;;
+       
+       *-*-solaris*)
+         ccvers=`$CC -V 2>&1 | head -1`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+
+       alpha*-dec-osf*)
+         ccvers=`$CC -V | tr '\n' ' '`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+
+       mips-sgi-irix*)
+         ccvers=`$CC -version`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+
+       dnl Intel C++ Compiler on Linux
+       i[[3-9]]86-pc-linux)
+         ccvers=`$CC -V 2>&1 | sed -n 's@^Intel.*Version @@'p`
+         if test ! -z "$ccvers" ; then
+           echo "  Compiler version:                  $ccvers"
+         fi
+       ;;
+         
+       *) echo "  Compiler version:                  $CC on $canonical";;
+  esac
+esac
+

 echo "  Relocating allocator for buffers:  $rel_alloc"
 echo "  GNU version of malloc:             ${GNU_MALLOC}${GNU_MALLOC_reason}"
 case "$ld_switch_site" in
 echo "  Relocating allocator for buffers:  $rel_alloc"
 echo "  GNU version of malloc:             ${GNU_MALLOC}${GNU_MALLOC_reason}"
 case "$ld_switch_site" in

@@ -4977,6 +5088,45 @@ case "$ld_switch_site" in
     - Consider configuring with --pdump." ;;
 esac
 
     - Consider configuring with --pdump." ;;
 esac
 

+dnl Now get the libc version - contributions welcome
+case "$canonical" in
+       *-*-linux*) 
+         if test -f /etc/redhat-release ; then
+           echo "  libc:                              `rpm -q glibc`";
+dnl need a Debian and Suse check here...
+          else
+           echo "Need to guess glibc1/2/etc here";
+          fi
+       ;;
+
+       *-*-aix*) 
+         echo "  libc:                              bos.rte.libc `lslpp -Lqc bos.rte.libc | cut -f3 -d:`" 
+       ;;
+
+       *-*-solaris*)
+         libc=`pkginfo -l SUNWcsl | grep VERSION: | awk '{print $2}'`
+         echo "  libc:                              SUNWcsl $libc"
+
+       ;;
+
+       mips-sgi-irix*)
+         echo "  IRIX version:                      `uname -sRm`'"
+       ;;
+         
+
+       alpha*-dec-osf*)
+       dnl Another ugly case
+         (cd /usr/.smdb.;
+               libc=` grep -h libc.so *.inv | awk '$9 == "f" {print $12}' | tr '\n' ','`
+               echo "  libc:                              $libc"
+               
+         )
+       ;;
+
+       *) echo "  libc:                              system-provided libc on $canonical" ;;
+esac
+
+

 echo "
 Window System:"
 if test "$with_msw" = "yes"; then
 echo "
 Window System:"
 if test "$with_msw" = "yes"; then

@@ -4998,6 +5148,9 @@ if test "$with_x11" = "yes"; then
 fi
 if test "$need_motif" = "yes" ; then
   echo "  Compiling in support for Motif."
 fi
 if test "$need_motif" = "yes" ; then
   echo "  Compiling in support for Motif."

+  if test "$have_lesstif" = "yes"; then
+    echo "    - Using LessTif implementation."
+  fi

   echo "  *WARNING*  Many versions of Motif are buggy, requiring workarounds."
   echo "             You are likely to experience slow redisplay."
   echo "             You may need to install vendor patches to Motif."
   echo "  *WARNING*  Many versions of Motif are buggy, requiring workarounds."
   echo "             You are likely to experience slow redisplay."
   echo "             You may need to install vendor patches to Motif."

diff --git a/configure.usage b/configure.usage
index 0983d73..2647128 100644 (file)
--- a/configure.usage
+++ b/configure.usage
@@ -139,7 +139,7 @@ explicitly specify which library to link against.
                         *WARNING*  The Motif menubar is currently broken.
 --with-scrollbars=TYPE  (Enum) Types: `lucid'(*), `motif', `athena', or `no'.
 --with-dialogs=TYPE     (Enum) Types: `lucid'(*), `motif', `athena', or `no'.
                         *WARNING*  The Motif menubar is currently broken.
 --with-scrollbars=TYPE  (Enum) Types: `lucid'(*), `motif', `athena', or `no'.
 --with-dialogs=TYPE     (Enum) Types: `lucid'(*), `motif', `athena', or `no'.

---with-widgets=TYPE     (Enum) Types: `lucid'(*), `motif', `athena', or `no'.
+--with-widgets=TYPE     (Enum) Types: `lucid', `motif', `athena', or `no'(*).

 --with-athena=TYPE      (Enum) Link with the TYPE Athena library.  Types:
                         `xaw' [flat], `3d', `next', `95', or `xpm'.
 --with-dragndrop (*)    Support generic drag and drop API. (EXPERIMENTAL)
 --with-athena=TYPE      (Enum) Link with the TYPE Athena library.  Types:
                         `xaw' [flat], `3d', `next', `95', or `xpm'.
 --with-dragndrop (*)    Support generic drag and drop API. (EXPERIMENTAL)

diff --git a/etc/OXYMORONS b/etc/OXYMORONS
index b54c142..6eaad69 100644 (file)
--- a/etc/OXYMORONS
+++ b/etc/OXYMORONS
@@ -36,14 +36,15 @@ theme for the releases following the promotion of 21.4 from "gamma" to
 21.4.13: Rational FORTRAN
 21.4.14: Reasonable Discussion
 21.4.15: Security Through Obscurity
 21.4.13: Rational FORTRAN
 21.4.14: Reasonable Discussion
 21.4.15: Security Through Obscurity

-21.4.16: Social Property
-21.4.17: Stable Release Maintainer
-21.4.18: Standard C
-21.4.19: Successful IPO
-21.4.20: Sufficiently Smart Compiler
-21.4.21: The Gift Economy
-21.4.22: Too Much Mozart
-21.4.23: UTF-8 BOM
+21.4.16: Corporate Culture
+21.4.17: Social Property
+21.4.18: Stable Release Maintainer
+21.4.19: Standard C
+21.4.20: Successful IPO
+21.4.21: Sufficiently Smart Compiler
+21.4.22: The Gift Economy
+21.4.23: Too Much Mozart
+21.4.24: UTF-8 BOM

 
 N.B.  Only incredibly redeeming suggestions can be accepted now.
 
 
 N.B.  Only incredibly redeeming suggestions can be accepted now.
 

diff --git a/etc/PACKAGES b/etc/PACKAGES
index fddf29b..5d30487 100644 (file)
--- a/etc/PACKAGES
+++ b/etc/PACKAGES
@@ -97,6 +97,9 @@ Portable Emacs Lisp utilities library.
 *** emerge
 Another interface over GNU patch.
 
 *** emerge
 Another interface over GNU patch.
 

+*** erc
+ERC is an Emacs InternetRelayChat client.
+

 *** eshell
 Command shell implemented entirely in Emacs Lisp.
 
 *** eshell
 Command shell implemented entirely in Emacs Lisp.
 

@@ -161,7 +164,8 @@ Spell-checking with GNU ispell.
 Integrated Development Environment for Java.
 
 *** liece
 Integrated Development Environment for Java.
 
 *** liece

-IRC (Internet Relay Chat) client for Emacs.
+IRC (Internet Relay Chat) client for Emacs.  Note, this package is
+deprecated and will be removed, use riece instead.

 
 *** mail-lib
 Fundamental lisp files for providing email support.
 
 *** mail-lib
 Fundamental lisp files for providing email support.

@@ -173,7 +177,7 @@ Support for messaging encryption with PGP.
 Messaging in an Emacs World.
 
 *** mh-e
 Messaging in an Emacs World.
 
 *** mh-e

-Front end support for MH.
+The XEmacs Interface to the MH Mail System.

 
 *** mine
 Minehunt Game.
 
 *** mine
 Minehunt Game.

@@ -230,6 +234,9 @@ Python support.
 *** reftex
 Emacs support for LaTeX cross-references, citations.
 
 *** reftex
 Emacs support for LaTeX cross-references, citations.
 

+*** riece
+IRC (Internet Relay Chat) client for Emacs.
+

 *** rmail
 An obsolete Emacs mailer.  If you do not already use it don't start.
 
 *** rmail
 An obsolete Emacs mailer.  If you do not already use it don't start.
 

diff --git a/etc/package-index.LATEST.gpg b/etc/package-index.LATEST.gpg
new file mode 100644 (file)
index 0000000..40ff6d3
--- /dev/null
+++ b/etc/package-index.LATEST.gpg
@@ -0,0 +1,2611 @@
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA1
+
+;; Package Index file -- Do not edit manually.
+;;;@@@
+(package-get-update-base-entry (quote
+(general-docs
+  (standards-version 1.1
+   version "1.01"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "General XEmacs documentation."
+   filename "general-docs-1.01-pkg.tar.gz"
+   md5sum "06c3e4e0aeddd995f2697c91a6b8cc00"
+   size 1435
+   provides ()
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(riece
+  (standards-version 1.1
+   version "1.12"
+   author-version "0.1.5"
+   date "2003-10-29"
+   build-date "2003-10-29"
+   maintainer "Daiki Ueno <ueno@unixuser.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "IRC (Internet Relay Chat) client for Emacs."
+   filename "riece-1.12-pkg.tar.gz"
+   md5sum "8859cfde4a93a31407e29c35a35e9669"
+   size 106360
+   provides (riece-compat riece-xemacs riece-globals riece-options riece-version riece-coding riece-complete riece-identity riece-channel riece-user riece-misc riece-layout riece-display riece-server riece-naming riece-message riece-filter riece-handle riece-000 riece-200 riece-300 riece-400 riece-500 riece-commands riece riece-ctcp riece-highlight riece-log riece-mini riece-rdcc riece-url riece-unread riece-doctor riece-alias riece-guess riece-history riece-button riece-keyword riece-menu riece-icon)
+   requires (xemacs-base mail-lib)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(oo-browser
+  (standards-version 1.1
+   version "1.04"
+   author-version "4.08"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Jake Colman <jake.colman@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "OO-Browser: The Multi-Language Object-Oriented Code Browser"
+   filename "oo-browser-1.04-pkg.tar.gz"
+   md5sum "72cb3bbfbe985d8989c564ca53cffe3c"
+   size 515713
+   provides (c++-browse clos-browse eif-browse hasht hmouse-br info-browse java-brows objc-brows pyth-brows smt-browse)
+   requires (xemacs-base hyperbole)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(hyperbole
+  (standards-version 1.0
+   version "1.13"
+   author-version "4.18"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Mats Lidell <matsl@xemacs.org>"
+   distribution stable
+   priority high
+   category "standard"
+   dump nil
+   description "Hyperbole: The Everyday Info Manager"
+   filename "hyperbole-1.13-pkg.tar.gz"
+   md5sum "fed416810d33560f433c4ad0bef605bc"
+   size 634192
+   provides (hact hactypes hargs hbdata hbmap hbut hgnus hhist hib-doc-id hib-kbd hibtypes hinit hlvar hmail hmh hmoccur hmous-info hmouse-drv hmouse-key hmouse-mod hmouse-tag hpath hrmail hsite hsmail hsys-w3 hsys-wais htz hui-menu hui-mini hui-mouse hui-window hui-xe-but hui hvar hversion hvm hypb hyperbole set wconfig wrolo-logic wrolo-menu wrolo)
+   requires (xemacs-base mail-lib calendar vm text-modes gnus mh-e rmail apel tm sh-script net-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ecb
+  (standards-version 1.1
+   version "1.13"
+   author-version "1.96"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Klaus Berndl <klaus.berndl@sdm.de>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Emacs source code browser."
+   filename "ecb-1.13-pkg.tar.gz"
+   md5sum "dbbc4f68db8f2f294b89f0ee11ae6156"
+   size 525836
+   provides (ecb-buffertab ecb-compilation ecb-create-layout ecb-cycle ecb ecb-eshell ecb-examples ecb-face ecb-help ecb-layout ecb-layout-defs ecb-mode-line ecb-navigate ecb-speedbar ecb-tod ecb-autogen ecb-jde ecb-upgrade ecb-util ecb-winman-support silentcomp tree-buffer)
+   requires (xemacs-base semantic eieio fsf-compat edit-utils jde mail-lib eshell ediff xemacs-devel speedbar c-support)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(pgg
+  (standards-version 1.1
+   version "1.04"
+   author-version "0.1"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Simon Josefsson <simon@josefsson.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Emacs interface to various PGP implementations."
+   filename "pgg-1.04-pkg.tar.gz"
+   md5sum "8f4d77a0e99edbd3040c8d3988109ee8"
+   size 31307
+   provides (pgg pgg-def pgg-parse pgg-gpg pgg-pgp pgg-pgp5)
+   requires (xemacs-base fsf-compat edebug)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(perl-modes
+  (standards-version 1.1
+   version "1.05"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Perl support."
+   filename "perl-modes-1.05-pkg.tar.gz"
+   md5sum "cbfc241502bb708e878bcb2d587a78b1"
+   size 161184
+   provides (cperl-mode perl-mode)
+   requires (xemacs-base ispell ps-print edit-utils fsf-compat)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(python-modes
+  (standards-version 1.1
+   version "1.03"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Python support."
+   filename "python-modes-1.03-pkg.tar.gz"
+   md5sum "537b318e5901cfc95ba7dfcce32d24bf"
+   size 82105
+   provides (pydoc python-mode)
+   requires (xemacs-base mail-lib)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ruby-modes
+  (standards-version 1.1
+   version "1.02"
+   author-version "1.6.8"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Ruby support."
+   filename "ruby-modes-1.02-pkg.tar.gz"
+   md5sum "d2a1ca596592bafba72c76158d26747b"
+   size 21889
+   provides (inf-ruby ruby-mode rubydb)
+   requires (xemacs-base debug)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(fortran-modes
+  (standards-version 1.1
+   version "1.03"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Fortran support."
+   filename "fortran-modes-1.03-pkg.tar.gz"
+   md5sum "413d2f5ea1497c29b436fee52073563b"
+   size 66719
+   provides (f90 fortran)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(psgml-dtds
+  (standards-version 1.1
+   version "1.03"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Deprecated collection of DTDs for psgml."
+   filename "psgml-dtds-1.03-pkg.tar.gz"
+   md5sum "6d2d68e928a540581ef564d1111fcbf2"
+   size 367476
+   provides ()
+   requires (xemacs-base psgml edit-utils mail-lib fsf-compat eterm sh-script)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(docbookide
+  (standards-version 1.1
+   version "0.07"
+   author-version "0.1"
+   date "2003-10-28"
+   build-date "2003-10-28"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "DocBook editing support."
+   filename "docbookide-0.07-pkg.tar.gz"
+   md5sum "2e83cb54d4c0d9fd4b22a81d8792e9e6"
+   size 32091
+   provides (dbide-abbrev dbide-data dbide-font dbide-process docbookide)
+   requires (xemacs-base ispell mail-lib)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ecrypto
+  (standards-version 1.1
+   version "0.14"
+   author-version "2.0"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Simon Josefsson <simon@josefsson.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Crypto functionality in Emacs Lisp."
+   filename "ecrypto-0.14-pkg.tar.gz"
+   md5sum "59207e5f5a5300ccf0d21f27b018de91"
+   size 68741
+   provides (ascii-armor blowfish des hex-util md4 md5-dl md5-el md5 paranoid rander rc16 rijndael sha1-dl sha1-el sha1)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ocaml
+  (standards-version 1.1
+   version "0.05"
+   author-version "3.06"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Objective Caml editing support."
+   filename "ocaml-0.05-pkg.tar.gz"
+   md5sum "2ca033386cade4dbdb05abe2e6f324f4"
+   size 64887
+   provides (caml-compat camldebug caml caml-font caml-help inf-caml)
+   requires (xemacs-base fsf-compat)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sasl
+  (standards-version 1.1
+   version "1.14"
+   author-version "1.14.4"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Simon Josefsson <simon@josefsson.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Simple Authentication and Security Layer (SASL) library."
+   filename "sasl-1.14-pkg.tar.gz"
+   md5sum "a00a2f0e7e6f1614ae95cdbef50e333e"
+   size 27045
+   provides (hmac-def hmac-md5 hmac-sha1 ntlm sasl sasl-cram sasl-digest sasl-ntlm sasl-plain sasl-login sasl-anonymous)
+   requires (ecrypto)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sml-mode
+  (standards-version 1.1
+   version "0.10"
+   author-version "3.9.5"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "SML editing support."
+   filename "sml-mode-0.10-pkg.tar.gz"
+   md5sum "87914cf428610799a98815b17393f6e0"
+   size 81763
+   provides (sml-compat sml-defs sml-mode sml-move sml-proc sml-util)
+   requires (xemacs-base edebug fsf-compat)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ess
+  (standards-version 1.1
+   version "1.06"
+   author-version "5.1.21"
+   date "2003-11-10"
+   build-date "2003-11-10"
+   maintainer "A.J. Rossini <rossini@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "ESS: Emacs Speaks Statistics."
+   filename "ess-1.06-pkg.tar.gz"
+   md5sum "46e105b2fd715790f6358d9f637cdf32"
+   size 445788
+   provides (ess-batch ess-comp ess-cust ess-dump ess-emcs ess-font-lock ess-help ess-inf ess-iw32 ess-latex-mode ess-menu ess-mode ess-mous ess-noweb ess-site ess-sysdp ess-utils ess-vars ess essa-r essa-sas essd-arc essd-els essd-r essd-omg essd-r essd-s3 essd-s4 essd-sas essd-sp3 essd-sp4 essd-sp5 essd-sp6 essd-sta essd-vst essd-xls essddr essdsp6w essl-bug essl-lsp essl-omg essl-py essl-s essl-sas essl-sta make-regexp mouseme msdos noweb-font-lock-mode noweb-mode)
+   requires (xemacs-base mail-lib fsf-compat edit-utils speedbar sh-script eterm)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(haskell-mode
+  (standards-version 1.1
+   version "1.06"
+   author-version "1.44"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Haskell editing support."
+   filename "haskell-mode-1.06-pkg.tar.gz"
+   md5sum "75c3dcb6fbe0a8824c865d8b989866cc"
+   size 94315
+   provides (haskell-decl-scan haskell-doc haskell-font-lock haskell-indent haskell-mode haskell-simple-indent)
+   requires (dired mail-lib xemacs-base edit-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(xslide
+  (standards-version 1.1
+   version "1.09"
+   author-version "0.2.2"
+   date "2003-10-28"
+   build-date "2003-10-28"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "XSL editing support."
+   filename "xslide-1.09-pkg.tar.gz"
+   md5sum "998f787ea80d98cdd7ca06c25ae96647"
+   size 39199
+   provides (xslide-abbrev xslide-data xslide-font xslide-process xslide)
+   requires (ispell mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(liece
+  (standards-version 1.1
+   version "1.12"
+   author-version "1.4.9"
+   date "2003-04-22"
+   build-date "2003-04-22"
+   maintainer "Daiki Ueno <ueno@unixuser.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "IRC (Internet Relay Chat) client for Emacs."
+   filename "liece-1.12-pkg.tar.gz"
+   md5sum "c7f2aab45f8ada9398d4b0807e80433a"
+   size 199275
+   provides (liece-xemacs gettext liece-clfns liece-handler liece-compat liece-version liece-vars liece-globals liece-inlines liece-filter liece-coding liece-dcc liece-menu liece-000 liece-200 liece-300 liece-400 liece-500 liece-nick liece-channel liece-commands liece-ctcp liece-q-el liece-message liece-handle liece-hilit liece-intl liece-mail liece-minibuf liece-misc liece-tcp liece-url liece-x-face liece-window liece)
+   requires (apel mail-lib fsf-compat xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(latin-unity
+  (standards-version 1.1
+   version "1.09"
+   author-version "1.09"
+   date "2003-11-09"
+   build-date "2003-11-09"
+   maintainer "Stephen J. Turnbull <stephen@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: find single ISO 8859 character set to encode a buffer."
+   filename "latin-unity-1.09-pkg.tar.gz"
+   md5sum "83b7fd603ad7cd5d9c459a0035501cac"
+   size 106267
+   provides (latin-unity latin-unity-tables latin-unity-utils)
+   requires (mule-base mule-ucs leim fsf-compat dired)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mmm-mode
+  (standards-version 1.1
+   version "1.01"
+   author-version "0.4.7"
+   date "2003-10-29"
+   build-date "2003-10-29"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Multiple major modes in a single buffer"
+   filename "mmm-mode-1.01-pkg.tar.gz"
+   md5sum "28cf0136d0d8e59e74a464074a98ef4b"
+   size 175927
+   provides (mmm-auto mmm-class mmm-cmds mmm-compat mmm-mason mmm-mode mmm-region mmm-rpm mmm-sample mmm-univ mmm-utils mmm-vars)
+   requires (xemacs-base fsf-compat )
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ibuffer
+  (standards-version 1.1
+   version "1.09"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "John Paul Wallington <jpw@shootybangbang.com>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Advanced replacement for buffer-menu"
+   filename "ibuffer-1.09-pkg.tar.gz"
+   md5sum "5132ee34ac4640fdb7a53706ee928e33"
+   size 89926
+   provides (ibuf-ext ibuf-macs ibuffer)
+   requires (ibuffer xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(xemacs-base
+  (standards-version 1.1
+   version "1.82"
+   author-version "No-Upstream-Ver"
+   date "2003-10-29"
+   build-date "2003-10-29"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "Fundamental XEmacs support, you almost certainly need this."
+   filename "xemacs-base-1.82-pkg.tar.gz"
+   md5sum "7ba84839d26de61e4cb62741531d59ba"
+   size 472771
+   provides (add-log advice-preload advice annotations assoc case-table chistory comint-xemacs comint compile debug ebuff-menu echistory edmacro ehelp electric enriched env facemenu ffap helper imenu iso-syntax macros novice outline passwd pp regexp-opt regi ring shell skeleton sort thing time-stamp timezone tq xbm-button xpm-button)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(tramp
+  (standards-version 1.1
+   version "1.16"
+   author-version "2.0.35"
+   date "2003-07-21"
+   build-date "2003-07-21"
+   maintainer "Kai Großjohann <kai.grossjohann@gmx.net>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Remote shell-based file editing."
+   filename "tramp-1.16-pkg.tar.gz"
+   md5sum "ec5a21c4462d48ebe8dc01ea0e32373c"
+   size 251091
+   provides (tramp tramp-efs tramp-ftp tramp-smb tramp-util tramp-uu
+             tramp-vc trampcache)
+   requires (tramp xemacs-base vc fsf-compat efs dired mail-lib gnus ediff)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(text-modes
+  (standards-version 1.1
+   version "1.71"
+   author-version "No-Upstream-Ver"
+   date "2003-11-13"
+   build-date "2003-11-13"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "Miscellaneous support for editing text files."
+   filename "text-modes-1.71-pkg.tar.gz"
+   md5sum "39be167962dc1a547a13f8bb1788327f"
+   size 377506
+   provides (ansi-color autoinsert crontab-edit desktop-entry-mode filladapt flyspell folding fold-isearch hexl htmlize image-mode iso-acc iso-ascii iso-cvt iso-insert iso-swed rtf-support swedish tabify whitespace-mode winmgr-mode xpm-mode xrdb-mode apache-mode po-mode po-compat css-mode)
+   requires (ispell fsf-compat xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(pcl-cvs
+  (standards-version 1.1
+   version "1.65"
+   author-version "R-2_9_9"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "CVS frontend."
+   filename "pcl-cvs-1.65-pkg.tar.gz"
+   md5sum "53b8cbd4d0b7709cfaf9d51e11888324"
+   size 161016
+   provides (cvs-compat cvs-edit cvs-log cvs-status easy-mmode pcl-cvs-defs pcl-cvs-info pcl-cvs-parse pcl-cvs-util pcl-cvs)
+   requires (xemacs-base elib vc dired edebug ediff edit-utils mail-lib prog-modes)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mail-lib
+  (standards-version 1.1
+   version "1.63"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Simon Josefsson <simon@josefsson.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Fundamental lisp files for providing email support."
+   filename "mail-lib-1.63-pkg.tar.gz"
+   md5sum "99b3f341e8c29ad2dc3fec5196e32549"
+   size 198134
+   provides (base64 browse-url-xemacs browse-url highlight-headers mail-abbrevs mail-extr mail-utils mailheader netrc pop3 reporter rfc2104 rfc822 rmail rmail-mini rmailout sendmail smtpmail starttls tls)
+   requires (eterm xemacs-base fsf-compat sh-script ecrypto)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(jde
+  (standards-version 1.1
+   version "1.46"
+   author-version "2.3.2"
+   date "2003-10-08"
+   build-date "2003-10-08"
+   maintainer "Andy Piper <andy@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Integrated Development Environment for Java."
+   filename "jde-1.46-pkg.tar.gz"
+   md5sum "60f5d299a53be811f6ef6006f2566c20"
+   size 2403395
+   provides (beanshell efc jde-ant jde-bug jde-checkstyle jde-compat jde-compile jde-complete jde-db jde-dbo jde-dbs jde-ejb jde-gen jde-help jde-imenu jde-import jde-java-font-lock jde-java-grammar jde-javadoc-gen jde-javadoc jde-jdb jde-make jde-open-source jde-package jde-parse-class jde-parse jde-run jde-setnu jde-stat jde-util jde-which-method jde-widgets jde-wiz jde-xref jde tree-widget)
+   requires (jde cc-mode semantic debug speedbar edit-utils eterm mail-lib xemacs-base xemacs-devel eieio elib sh-script fsf-compat)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(fsf-compat
+  (standards-version 1.1
+   version "1.13"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "FSF Emacs compatibility files."
+   filename "fsf-compat-1.13-pkg.tar.gz"
+   md5sum "270a9deea6166bb38ac00f6191c7e8c0"
+   size 21687
+   provides (overlay thingatpt timer x-popup-menu goto-addr)
+   requires (xemacs-base)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(edit-utils
+  (standards-version 1.1
+   version "2.10"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "Miscellaneous editor extensions, you probably need this."
+   filename "edit-utils-2.10-pkg.tar.gz"
+   md5sum "8d3c77a3ae8fb443a608a148e32e0d48"
+   size 925330
+   provides (abbrevlist after-save-commands atomic-extents avoid backup-dir balloon-help big-menubar blink-cursor blink-paren bookmark compare-w completion dabbrev desktop detached-minibuf edit-toolbar fast-lock file-part floating-toolbar flow-ctrl foldout func-menu hippie-exp icomplete id-select info-look iswitchb lazy-lock lazy-shot live-icon makesum man mic-paren paren mode-motion+ outl-mouse outln-18 page-ext blink-paren paren permanent-buffers popper power-macros recent-files redo reportmail resume rsz-minibuf saveconf savehist saveplace scroll-in-place setnu shell-font tempo toolbar-utils tree-menu uniquify vertical-mode where-was-i-db winring autorevert align allout outline narrow-stack highline)
+   requires (xemacs-base xemacs-devel fsf-compat dired mail-lib)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(skk
+  (standards-version 1.1
+   version "1.23"
+   author-version "10.62a"
+   date "2002-09-25"
+   build-date "2002-09-25"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution mule
+   priority medium
+   category "mule"
+   dump nil
+   description "MULE: Japanese Language Input Method."
+   filename "skk-1.23-pkg.tar.gz"
+   md5sum "dc35f20896a56c8cf2e7ba16b15e453b"
+   size 1506691
+   provides (skk-auto skk-comp skk-cursor skk-develop skk-foreword skk-gadget skk-isearch skk-kakasi skk-kcode skk-leim skk-look skk-num skk-obsolete skk-server skk-tut skk-vars skk-viper skk vip)
+   requires (viper mule-base elib xemacs-base apel)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ps-print
+  (standards-version 1.1
+   version "1.09"
+   author-version "6.5.6"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Printing functions and utilities"
+   filename "ps-print-1.09-pkg.tar.gz"
+   md5sum "9055fe7244e253e2a12cc7e4d69df041"
+   size 155737
+   provides (lpr ps-bdf ps-mule ps-print)
+   requires (text-modes)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sieve
+  (standards-version 1.1
+   version "1.14"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Simon Josefsson <simon@josefsson.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Manage Sieve email filtering scripts."
+   filename "sieve-1.14-pkg.tar.gz"
+   md5sum "6a9234ad3e59c485869db92a3637d91f"
+   size 25677
+   provides (sieve sieve-mode sieve-manage)
+   requires (xemacs-base mail-lib cc-mode sasl)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mule-ucs
+  (standards-version 1.1
+   version "1.05"
+   author-version "0.84"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Stephen J. Turnbull <stephen@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: Extended coding systems (including Unicode) for XEmacs."
+   filename "mule-ucs-1.05-pkg.tar.gz"
+   md5sum "772c06a697d0b3b4d7b78e8df76c019c"
+   size 1314530
+   provides (mccl-font mucs-ccl mucs-error mucs-type mucs mule-uni tae tbl-mg trans-util txt-tbl un-data un-define un-supple un-tools un-trbase unicode unidata utf u-cns-1 u-cns-2 u-cns-3 u-cns-4 u-cns-5 u-cns-6 u-cns-7 uascii ubig5 uetiopic ugb2312 uipa uiscii uiso8859-1 uiso8859-14 uiso8859-15 uiso8859-2 uiso8859-3 uiso8859-4 uiso8859-5 uiso8859-6 uiso8859-7 uiso8859-8 uiso8859-9 ujisx0201 ujisx0208 ujisx0212 uksc5601 usisheng usupple utibetan utis620 uviscii)
+   requires (mule-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(clearcase
+  (standards-version 1.0
+   version "1.08"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Michael Diers <mdiers@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "New Clearcase Version Control for XEmacs (UNIX, Windows)."
+   filename "clearcase-1.08-pkg.tar.gz"
+   md5sum "6fedc7464137eae08c25517276f8a7ab"
+   size 94543
+   provides (clearcase)
+   requires (dired fsf-compat mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(dictionary
+  (standards-version 1.1
+   version "1.12"
+   author-version "1.8"
+   date "2003-06-22"
+   build-date "2003-06-22"
+   maintainer "Torsten Hilbrich <dictionary@myrkr.in-berlin.de>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Interface to RFC2229 dictionary servers."
+   filename "dictionary-1.12-pkg.tar.gz"
+   md5sum "717517bbad4e241f18941fd6c289b868"
+   size 39658
+   provides (dictionary connection link)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(build
+  (standards-version 1.0
+   version "1.14"
+   author-version "2.02"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Adrian Aichner <adrian@xemacs.org>"
+   distribution stable
+   priority low
+   category "standard"
+   dump nil
+   description "Build XEmacs from within (UNIX, Windows)."
+   filename "build-1.14-pkg.tar.gz"
+   md5sum "927263daa5b6d8097b916f0be5887a62"
+   size 49484
+   provides (build)
+   requires (xemacs-base pcl-cvs dired w3 prog-modes)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(xslt-process
+  (standards-version 1.0
+   version "1.11"
+   author-version "1.2.1"
+   date "2002-10-08"
+   build-date "2002-10-08"
+   maintainer "Ovidiu Predescu <ovidiu@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "XSLT processing support."
+   filename "xslt-process-1.11-pkg.tar.gz"
+   md5sum "30273cbe2e90ae703ea410879412e68b"
+   size 199873
+   provides (xslt-process)
+   requires (jde cc-mode semantic debug speedbar edit-utils eterm mail-lib xemacs-base elib eieio sh-script fsf-compat xemacs-devel)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(eieio
+  (standards-version 1.1
+   version "1.05"
+   author-version "0.17"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Eric Ludlam <zappo@gnu.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Enhanced Implementation of Emacs Interpreted Objects"
+   filename "eieio-1.05-pkg.tar.gz"
+   md5sum "b31f8f71fc5afa41196954f04f955654"
+   size 165803
+   provides (call-tree chart compare-strings eieio-base eieio-comp eieio-custom eieio-doc eieio-opt eieio-speedbar eieio-tests eieio linemark tree)
+   requires (speedbar xemacs-base edebug)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(egg-its
+  (standards-version 1.1
+   version "1.27"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: Wnn (4.2 and 6) support.  SJ3 support."
+   filename "egg-its-1.27-pkg.tar.gz"
+   md5sum "6027d90327043f918d8a4ea3143ae7d2"
+   size 261339
+   provides (egg-cnpinyin egg-cnzhuyin egg-cwnn-leim egg-jisx0201 egg-jsymbol egg-kwnn-leim egg-leim egg-sj3-client egg-sj3-leim egg-sj3 egg-wnn egg)
+   requires (leim mule-base fsf-compat xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(edict
+  (standards-version 1.1
+   version "1.16"
+   author-version "0.9.9"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Stephen J. Turnbull <stephen@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: Lisp Interface to EDICT, Kanji Dictionary."
+   filename "edict-1.16-pkg.tar.gz"
+   md5sum "406e55fda150ec0ea22b79580279be95"
+   size 96111
+   provides (dui-registry dui edict-edit edict-english edict-japanese edict-morphology edict-test edict ts-mode)
+   requires (mule-base xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(lookup
+  (standards-version 1.1
+   version "1.14"
+   author-version "1.0"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: Dictionary support"
+   filename "lookup-1.14-pkg.tar.gz"
+   md5sum "f48776563d7fbd0852ad73ac9c513260"
+   size 225996
+   provides (evi-mule evi lookup-content lookup-defs lookup-entry lookup-select lookup-package lookup-select lookup-types lookup-utils lookup-vars lookup-vse lookup ndcookie ndeb ndic ndict ndkks ndmisc ndnmz ndspell ndsrd ndtp sdicf stem)
+   requires (mule-base cookie lookup)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(leim
+  (standards-version 1.1
+   version "1.22"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution mule
+   priority medium
+   category "mule"
+   dump nil
+   description "MULE: Quail.  All non-English and non-Japanese language support."
+   filename "leim-1.22-pkg.tar.gz"
+   md5sum "942fbcd4d56eb59529bbd15c3b6c0b3b"
+   size 1708319
+   provides ()
+   requires (leim mule-base fsf-compat xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(locale
+  (standards-version 1.1
+   version "1.21"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: Localized menubars and localized splash screens."
+   filename "locale-1.21-pkg.tar.gz"
+   md5sum "2256243bb8cdd282af7b40bc2cf30018"
+   size 36961
+   provides ()
+   requires (mule-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mule-base
+  (standards-version 1.1
+   version "1.44"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution mule
+   priority high
+   category "mule"
+   dump nil
+   description "MULE: Basic Mule support, required for building with Mule."
+   filename "mule-base-1.44-pkg.tar.gz"
+   md5sum "9eaa93208008617bd8f0d34448dcfaa3"
+   size 444749
+   provides (canna-leim canna char-table china-util cyril-util isearch-ext japan-util ccl can-n-egg mule-help)
+   requires (fsf-compat xemacs-base apel)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(strokes
+  (standards-version 1.1
+   version "1.10"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Mouse enhancement utility."
+   filename "strokes-1.10-pkg.tar.gz"
+   md5sum "946a6e0bb3e9384a94a79ecdffdd85d8"
+   size 43728
+   provides (strokes)
+   requires (text-modes edit-utils mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(time
+  (standards-version 1.1
+   version "1.14"
+   author-version "1.17"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Display time & date on the modeline."
+   filename "time-1.14-pkg.tar.gz"
+   md5sum "8956073a18694a8ad91a52c7374c3d66"
+   size 20431
+   provides (time)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(slider
+  (standards-version 1.1
+   version "1.15"
+   author-version "0.3x1"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "User interface tool."
+   filename "slider-1.15-pkg.tar.gz"
+   md5sum "00bb43e4f3997c0c493cb7f29a75494b"
+   size 12516
+   provides (slider color-selector)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sgml
+  (standards-version 1.1
+   version "1.10"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "SGML/Linuxdoc-SGML editing."
+   filename "sgml-1.10-pkg.tar.gz"
+   md5sum "ab80262877e3547dfb97e80a0a778e09"
+   size 27462
+   provides (sgml linuxdoc-sgml)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(psgml
+  (standards-version 1.1
+   version "1.41"
+   author-version "1.3.1"
+   date "2003-08-29"
+   build-date "2003-08-29"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Validated HTML/SGML editing."
+   filename "psgml-1.41-pkg.tar.gz"
+   md5sum "33baca4b85d3d9c48df682b748c9a273"
+   size 301000
+   provides (iso-sgml psgml-api psgml-charent psgml-debug psgml-dtd psgml-edit psgml-fs psgml-html psgml-info psgml-parse psgml-sysdep psgml-xemacs psgml sgml-mode)
+   requires (xemacs-base edit-utils edebug xemacs-devel mail-lib fsf-compat eterm sh-script ps-print)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(pc
+  (standards-version 1.1
+   version "1.26"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "PC style interface emulation."
+   filename "pc-1.26-pkg.tar.gz"
+   md5sum "47189d077b363012c4b17f527eef2ec7"
+   size 17611
+   provides (delbs fusion pc-select pending-del s-region)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ispell
+  (standards-version 1.1
+   version "1.26"
+   author-version "3.3"
+   date "2003-11-02"
+   build-date "2003-11-02"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Spell-checking with GNU ispell."
+   filename "ispell-1.26-pkg.tar.gz"
+   md5sum "85a9da0fe8ed41199388b5f41a0f7769"
+   size 72869
+   provides (ispell)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(hm--html-menus
+  (standards-version 1.1
+   version "1.23"
+   author-version "5.9"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "HTML editing."
+   filename "hm--html-menus-1.23-pkg.tar.gz"
+   md5sum "c625e8070a7abfed6fb1f13d04a38e51"
+   size 179091
+   provides (adapt hm--date hm--html-configuration hm--html-drag-and-drop hm--html-indentation hm--html-keys hm--html-menu hm--html-mode hm--html-not-standard hm--html html-view internal-drag-and-drop tmpl-minor-mode)
+   requires (dired xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(frame-icon
+  (standards-version 1.1
+   version "1.11"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Set up mode-specific icons for each frame under XEmacs"
+   filename "frame-icon-1.11-pkg.tar.gz"
+   md5sum "6fbd58bc7f37328aaf31b420c9a2891f"
+   size 33800
+   provides (forms forms-mode)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(forms
+  (standards-version 1.1
+   version "1.15"
+   author-version "2.37"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Forms editing support (obsolete, use Widget instead)."
+   filename "forms-1.15-pkg.tar.gz"
+   md5sum "5f5cc842399040018bab20f776cf1cf8"
+   size 48747
+   provides (forms forms-mode)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(calendar
+  (standards-version 1.1
+   version "1.22"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Calendar and diary support."
+   filename "calendar-1.22-pkg.tar.gz"
+   md5sum "c9f0bdbcb3cbbb9eff338e4edd9d7f95"
+   size 253996
+   provides (appt cal-china cal-coptic cal-dst cal-french cal-hebrew cal-islam cal-iso cal-japanese cal-julian cal-mayan cal-move cal-persia cal-tex cal-x cal-xemacs calendar diary-lib holidays lunar solar)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(calc
+  (standards-version 1.1
+   version "1.24"
+   author-version "2.02fX3"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Emacs calculator"
+   filename "calc-1.24-pkg.tar.gz"
+   md5sum "61fa56abe04492e448a8549b5978ca3a"
+   size 1600141
+   provides (calc-ext calc-macs calc)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(speedbar
+  (standards-version 1.1
+   version "1.27"
+   author-version "0.14beta4"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Eric M. Ludlam <zappo@gnu.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Provides a separate frame with convenient references."
+   filename "speedbar-1.27-pkg.tar.gz"
+   md5sum "4df8d109364493dca814ef7429d560d2"
+   size 163245
+   provides (bigclock dframe rpm sb-ant sb-gud sb-html sb-image sb-info sb-rmail sb-texinfo sb-w3 speedbar)
+   requires (xemacs-base edebug)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(pcomplete
+  (standards-version 1.1
+   version "1.03"
+   author-version "1.1.6"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "John Wiegley <johnw@gnu.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Provides programmatic completion."
+   filename "pcomplete-1.03-pkg.tar.gz"
+   md5sum "43bad91be873dd6ae2f9483e90c42226"
+   size 37443
+   provides (pcomplete)
+   requires (sh-script xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(eshell
+  (standards-version 1.1
+   version "1.06"
+   author-version "2.4.1"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "John Wiegley <johnw@gnu.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Command shell implemented entirely in Emacs Lisp"
+   filename "eshell-1.06-pkg.tar.gz"
+   md5sum "737f4d5caed7ffe8cb987f0e2459d6e8"
+   size 232041
+   provides (em-alias em-banner em-basic em-cmpl em-dirs em-glob em-hist em-ls em-pred em-prompt em-rebind em-script em-smart em-term em-unix em-xtra esh-arg esh-cmd esh-ext esh-io esh-maint esh-mode esh-module esh-opt esh-proc esh-test esh-toggle esh-util esh-var eshell)
+   requires (xemacs-base eterm)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(view-process
+  (standards-version 1.1
+   version "1.13"
+   author-version "2.4"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "A Unix process browsing tool."
+   filename "view-process-1.13-pkg.tar.gz"
+   md5sum "05eca7ec61259b47f2a741fc30dcc65f"
+   size 60814
+   provides (view-process-mode)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(os-utils
+  (standards-version 1.1
+   version "1.34"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Miscellaneous O/S utilities."
+   filename "os-utils-1.34-pkg.tar.gz"
+   md5sum "98fa67e0d1b89febd16bfc952d552171"
+   size 225849
+   provides (archive-mode background crypt++ crypt ftelnet inf-lisp jka-compr mchat rlogin ssh tar-mode telnet terminal uncompress)
+   requires (xemacs-base)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ilisp
+  (standards-version 1.1
+   version "1.33"
+   author-version "5.12.0"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "ilisp Maintainers <ilisp@cons.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Front-end for Inferior Lisp."
+   filename "ilisp-1.33-pkg.tar.gz"
+   md5sum "a0edbe80726e199f3cfc7a367c3fd772"
+   size 344245
+   provides (bridge comint-ipc completer ilcompat compat-fsf18 compat-fsf-19 compat-fsf-20 ilisp-chs ilisp-cl-easy-menu ilisp-ext ilisp-lw ilisp-key ilisp-menu ilisp-mnb ilisp-scheme-easy-menu ilisp il-luc19 il-luc19)
+   requires (xemacs-base mail-lib fsf-compat eterm sh-script)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(igrep
+  (standards-version 1.1
+   version "1.12"
+   author-version "2.95"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Enhanced front-end for Grep."
+   filename "igrep-1.12-pkg.tar.gz"
+   md5sum "a46e749b903ad526dad1a898496e9812"
+   size 17316
+   provides (igrep)
+   requires (dired xemacs-base efs)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(eterm
+  (standards-version 1.1
+   version "1.15"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Terminal emulation."
+   filename "eterm-1.15-pkg.tar.gz"
+   md5sum "4821611600abfb6f7e6d2d91b361e5dc"
+   size 109135
+   provides (eterm)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(viper
+  (standards-version 1.1
+   version "1.37"
+   author-version "3.09"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Michael Kifer <kifer@cs.sunysb.edu>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "VI emulation support."
+   filename "viper-1.37-pkg.tar.gz"
+   md5sum "5bd6157ea98d1cc9399e91eb3b684c8c"
+   size 327719
+   provides (viper-cmd viper-ex viper-init viper-keym viper-macs viper-mous viper-util viper)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(tpu
+  (standards-version 1.1
+   version "1.14"
+   author-version "4.2X"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Kevin Oberman <oberman@es.net>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "DEC EDIT/TPU support."
+   filename "tpu-1.14-pkg.tar.gz"
+   md5sum "f3f5ef913e958e5532a2a682288eac05"
+   size 59529
+   provides (tpu)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(textools
+  (standards-version 1.1
+   version "1.15"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Miscellaneous TeX support."
+   filename "textools-1.15-pkg.tar.gz"
+   md5sum "43d33c2e35569a434e7787e7ded2eade"
+   size 79966
+   provides (bib-mode bibtex refer-to-bibtex)
+   requires (xemacs-base)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(texinfo
+  (standards-version 1.1
+   version "1.25"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "XEmacs TeXinfo support."
+   filename "texinfo-1.25-pkg.tar.gz"
+   md5sum "a2755f74e1f4c76ba36d844abc718d3a"
+   size 133884
+   provides (makeinfo tex-mode texinfmt texinfo texnfo-tex texnfo-upd)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(reftex
+  (standards-version 1.1
+   version "1.33"
+   author-version "4.21"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Carsten Dominik <dominik@science.uva.nl>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Emacs support for LaTeX cross-references, citations.."
+   filename "reftex-1.33-pkg.tar.gz"
+   md5sum "4d9a603199ad55c5d3f3cd31413a56de"
+   size 352053
+   provides (reftex-auc reftex-cite reftex-dcr reftex-vcr reftex-global reftex-index reftex-parse reftex-ref reftex-sel reftex-toc reftex-vars reftex)
+   requires (fsf-compat xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(edt
+  (standards-version 1.1
+   version "1.13"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "DEC EDIT/EDT emulation."
+   filename "edt-1.13-pkg.tar.gz"
+   md5sum "1ca337b8b41799394068717d8d716516"
+   size 62754
+   provides (edt)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(crisp
+  (standards-version 1.1
+   version "1.14"
+   author-version "1.34"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Crisp/Brief emulation."
+   filename "crisp-1.14-pkg.tar.gz"
+   md5sum "ba1bbc29153b1849e71d123b9f2021b1"
+   size 10361
+   provides (crisp scroll-lock)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(auctex
+  (standards-version 1.1
+   version "1.35"
+   author-version "11.13"
+   date "2003-01-03"
+   build-date "2003-01-03"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Basic TeX/LaTeX support."
+   filename "auctex-1.35-pkg.tar.gz"
+   md5sum "168e82155e152dab8c7c913bc9a4788b"
+   size 406466
+   provides (auc-old auc-tex bib-cite font-latex latex multi-prompt tex-buf tex-info tex-jp tex-mik tex-site tex texmathp)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(vhdl
+  (standards-version 1.1
+   version "1.18"
+   author-version "3.31.20"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Support for VHDL."
+   filename "vhdl-1.18-pkg.tar.gz"
+   md5sum "6a38f9e4428754114593b94089c71943"
+   size 273202
+   provides (vhdl-mode)
+   requires (xemacs-base edit-utils c-support speedbar ps-print os-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(x-symbol
+  (standards-version 1.1
+   version "1.07"
+   author-version "4.5.1"
+   date "2003-10-26"
+   build-date "2003-10-26"
+   maintainer "Steve Youngs <sryoungs@bigpond.net.au>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts."
+   filename "x-symbol-1.07-pkg.tar.gz"
+   md5sum "c4a1cfc1318d5eb87eb186f0972abad6"
+   size 679781
+   provides (x-symbol-bib x-symbol-hooks x-symbol-image x-symbol-macs x-symbol-mule x-symbol-nomule x-symbol-sgml x-symbol-tex x-symbol-texi x-symbol-vars x-symbol-xmacs x-symbol)
+   requires (x-symbol xemacs-base auctex mail-lib)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(vc
+  (standards-version 1.1
+   version "1.38"
+   author-version "No-Upstream-Ver"
+   date "2003-10-27"
+   build-date "2003-10-27"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Version Control for Free systems."
+   filename "vc-1.38-pkg.tar.gz"
+   md5sum "b19fa9b253ec9335829c3289ea1b046b"
+   size 93835
+   provides (vc vc-hooks)
+   requires (dired xemacs-base vc mail-lib ediff)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(vc-cc
+  (standards-version 1.1
+   version "1.22"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Version Control for ClearCase (UnFree) systems."
+   filename "vc-cc-1.22-pkg.tar.gz"
+   md5sum "ee4ce6853773d36dd92b53ce2513fd73"
+   size 95028
+   provides (vc-cc vc-cc-hooks)
+   requires (dired xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sh-script
+  (standards-version 1.1
+   version "1.18"
+   author-version "2.0e"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Support for editing shell scripts."
+   filename "sh-script-1.18-pkg.tar.gz"
+   md5sum "4a0e2de6d1006c987dfd9e861b8562cd"
+   size 37055
+   provides (sh-script executable)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(scheme
+  (standards-version 1.1
+   version "1.14"
+   author-version "No-Upstream-Ver"
+   date "2003-10-28"
+   build-date "2003-10-28"
+   maintainer "Karl M. Hegbloom <karlheg@bittersweet.inetarena.com>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Front-end support for Inferior Scheme."
+   filename "scheme-1.14-pkg.tar.gz"
+   md5sum "0d64efd541819d9ba12cdafa9036edc7"
+   size 37770
+   provides (scheme xscheme cmuscheme cmuscheme48)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(prog-modes
+  (standards-version 1.1
+   version "1.91"
+   author-version "No-Upstream-Ver"
+   date "2003-10-29"
+   build-date "2003-10-29"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Support for various programming languages."
+   filename "prog-modes-1.91-pkg.tar.gz"
+   md5sum "b0203d7e022fdf730845ffbceaf41bf0"
+   size 715961
+   provides (autoconf-mode awk-mode c-mode cvs diff-mode eiffel-mode icon javascript-mode ksh-mode m4-mode make-mode makefile mode-compile mode-compile-kill modula2 p4 php-mode postscript rexx-mode rpm-spec-mode simula-mode sql tcl teco uil-mode verilog-mode)
+   requires (mail-lib xemacs-devel xemacs-base cc-mode fsf-compat edit-utils ediff emerge efs vc speedbar dired ilisp sh-script)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(idlwave
+  (standards-version 1.1
+   version "1.31"
+   author-version "5.1"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Carsten Dominik <dominik@astro.uva.nl>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Editing and Shell mode for the Interactive Data Language"
+   filename "idlwave-1.31-pkg.tar.gz"
+   md5sum "c5e8e00757efddd5d83d9acb31247102"
+   size 520952
+   provides (idlw-rinfo idlwave-rinfo idlw-shell idlwave-shell idlw-toolbar idlwave-toolbar idlwave)
+   requires (fsf-compat xemacs-base mail-lib)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(emerge
+  (standards-version 1.1
+   version "1.11"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Another interface over GNU patch."
+   filename "emerge-1.11-pkg.tar.gz"
+   md5sum "f47b98cdf120c123bee14ff9d1ff0862"
+   size 61367
+   provides (emerge)
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ediff
+  (standards-version 1.1
+   version "1.49"
+   author-version "2.75"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Michael Kifer <kifer@cs.sunysb.edu>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Interface over GNU patch."
+   filename "ediff-1.49-pkg.tar.gz"
+   md5sum "de66f77ac38f2df7dd4c5a94d9582f55"
+   size 305252
+   provides (ediff-diff ediff-help ediff-hook ediff-init ediff-merg ediff-mult ediff-ptch ediff-tbar ediff-util ediff-vers ediff-wind ediff)
+   requires (pcl-cvs elib dired xemacs-base edebug prog-modes)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(debug
+  (standards-version 1.1
+   version "1.17"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "GUD, gdb, dbx debugging support."
+   filename "debug-1.17-pkg.tar.gz"
+   md5sum "e45715132f64e4dbc7f14a22128b9279"
+   size 108073
+   provides (dbx debug-toolbar gdb-highlight gdb gdbsrc gud history)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(c-support
+  (standards-version 1.1
+   version "1.18"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Basic single-file add-ons for editing C code."
+   filename "c-support-1.18-pkg.tar.gz"
+   md5sum "950c5d610fb614bd418863075cde1c4c"
+   size 70705
+   provides (c-comment-edit cmacexp ctypes hideif hideshow)
+   requires (cc-mode xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(ada
+  (standards-version 1.1
+   version "1.14"
+   author-version "2.27"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Ada language support."
+   filename "ada-1.14-pkg.tar.gz"
+   md5sum "f2635d2b432f2a7cd456df760d622e3c"
+   size 55836
+   provides (ada-mode ada-stmt)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(cc-mode
+  (standards-version 1.1
+   version "1.41"
+   author-version "5.30.7"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Martin Stjernholm <bug-cc-mode@gnu.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "C, C++, Objective-C, Java, CORBA IDL, Pike and AWK language support."
+   filename "cc-mode-1.41-pkg.tar.gz"
+   md5sum "31b9f8e38d95e6b5dd079c14f88ef360"
+   size 513369
+   provides (cc-align cc-awk cc-bytecomp cc-cmds cc-compat cc-defs cc-engine cc-fix cc-fonts cc-guess cc-langs cc-lobotomy cc-menus cc-mode cc-styles cc-vars)
+   requires (xemacs-base mail-lib)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(semantic
+  (standards-version 1.1
+   version "1.18"
+   author-version "1.4.2"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Eric M. Ludlam <zappo@gnu.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Semantic bovinator (Yacc/Lex for XEmacs). Includes Senator."
+   filename "semantic-1.18-pkg.tar.gz"
+   md5sum "bb333c47f371748a1e923893c98d7b3f"
+   size 443092
+   provides (document-vars document semantic-analyze semantic-bnf semantic-c semantic-cb semantic-chart semantic-ctxt semantic-el semantic-example semantic-ia-sb semantic-ia semantic-imenu semantic-java semantic-load semantic-make semantic-sb semantic-scm semantic-skel semantic-texi semantic-util-modes semantic-util semantic semanticdb senator sformat working)
+   requires (eieio xemacs-base xemacs-devel edit-utils speedbar texinfo fsf-compat cc-mode edebug)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(misc-games
+  (standards-version 1.1
+   version "1.18"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Other amusements and diversions."
+   filename "misc-games-1.18-pkg.tar.gz"
+   md5sum "c68c91ee7eb296669388645c467fdede"
+   size 166817
+   provides (decipher gomoku hanoi life morse rot13)
+   requires (xemacs-base)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mine
+  (standards-version 1.1
+   version "1.16"
+   author-version "1.9"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Minehunt Game."
+   filename "mine-1.16-pkg.tar.gz"
+   md5sum "3875c5eb3c58306db3c875a18ba56ff6"
+   size 67161
+   provides (xmine)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(games
+  (standards-version 1.1
+   version "1.15"
+   author-version "1.04"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Glynn Clements <glynn@sensei.co.uk>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Tetris, Sokoban, and Snake."
+   filename "games-1.15-pkg.tar.gz"
+   md5sum "e50c1cd9ae0e9d32a022f52e795119b4"
+   size 37242
+   provides (gamegrid snake tetris sokoban)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(cookie
+  (standards-version 1.1
+   version "1.15"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Spook and Yow (Zippy quotes)."
+   filename "cookie-1.15-pkg.tar.gz"
+   md5sum "70b4bde06580ec71df2a23aa95808bb7"
+   size 35035
+   provides (cookie1 yow)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(bbdb
+  (standards-version 1.1
+   version "1.24"
+   author-version "2.34"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Ronan Waide <waider@waider.ie>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "The Big Brother Data Base"
+   filename "bbdb-1.24-pkg.tar.gz"
+   md5sum "bb9a7c33c742e28076643be7fda317ed"
+   size 373736
+   provides (bbdb-com bbdb-ftp bbdb-gnus bbdb-gui bbdb-hooks bbdb-merge bbdb-mhe bbdb-migrate bbdb-print bbdb-reportmail bbdb-rmail bbdb-sc bbdb-snarf bbdb-srv bbdb-vm bbdb-w3 bbdb-whois bbdb-xemacs bbdb)
+   requires (bbdb edit-utils gnus mh-e rmail supercite vm tm apel mail-lib xemacs-base w3 fsf-compat eterm sh-script net-utils os-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(zenirc
+  (standards-version 1.1
+   version "1.14"
+   author-version "2.112"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "ZENIRC IRC Client."
+   filename "zenirc-1.14-pkg.tar.gz"
+   md5sum "9e40efa659a867dae6aac4673b474322"
+   size 277304
+   provides (zenirc-18 zenirc-8ball zenirc-away zenirc-bork zenirc-color zenirc-command-queue zenirc-complete zenirc-ctcp-flood zenirc-dcc zenirc-doto zenirc-fill zenirc-finnish zenirc-format zenirc-fortran zenirc-french zenirc-history zenirc-ignore zenirc-iwantop zenirc-klingon zenirc-latin zenirc-meditate zenirc-netsplit zenirc-notify zenirc-oink zenirc-ojnk zenirc-pjg zenirc-popup zenirc-random-away zenirc-random-nick zenirc-signal zenirc-stamp zenirc-swedish zenirc-trigger zenirc-yow-filter zenirc-yow zenirc)
+   requires (zenirc)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mew
+  (standards-version 1.1
+   version "1.18"
+   author-version "1.94.2"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Messaging in an Emacs World."
+   filename "mew-1.18-pkg.tar.gz"
+   md5sum "09533ddf67f0948c6b4a40b996d82fbd"
+   size 745829
+   provides (mew-addrbook mew-attach mew-bq mew-cache mew-complete mew-decode mew-demo mew-draft mew-encode mew-env mew-ext mew-fib mew-func mew-header mew-highlight mew-lang-jp mew-mark mew-message mew-mime mew-minibuf mew-mule mew-mule0 mew-mule2 mew-mule3 mew-os2 mew-pgp mew-pick mew-refile mew-scan mew-sort mew-summary mew-syntax mew-temacs mew-unix mew-vars mew-virtual mew-win32 mew-xemacs mew)
+   requires (mew w3 efs mail-lib xemacs-base fsf-compat)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(tm
+  (standards-version 1.1
+   version "1.37"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Emacs MIME support. Not needed for gnus >= 5.8.0"
+   filename "tm-1.37-pkg.tar.gz"
+   md5sum "9cd28b13243debe9a986dcbd332f1ccd"
+   size 334179
+   provides (char-util cless gnus-art-mime gnus-charset gnus-mime gnus-sum-mime latex-math-symbol mel-b mel-g mel-q mel-u mel message-mime mime-setup mu-bbdb mu-cite range sc-setup signature texi-util tl-atype tl-list tl-misc tl-num tl-seq tl-str tm-bbdb tm-def tm-edit-mc tm-edit tm-ew-d tm-ew-e tm-file tm-ftp tm-html tm-image tm-latex tm-mail tm-mh-e tm-parse tm-partial tm-pgp tm-play tm-rmail tm-setup tm-tar tm-text tm-view tm-vm tmh-comp)
+   requires (gnus mh-e rmail vm mailcrypt mail-lib apel xemacs-base fsf-compat sh-script net-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(gnus
+  (standards-version 1.1
+   version "1.73"
+   author-version "5.10.2"
+   date "2003-10-13"
+   build-date "2003-10-13"
+   maintainer "Steve Youngs <sryoungs@bigpond.net.au>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "The Gnus Newsreader and Mailreader."
+   filename "gnus-1.73-pkg.tar.gz"
+   md5sum "a1259caa28482a71bc4dfa1e434f9511"
+   size 3245188
+   provides (binhex canlock compface deuglify earcon flow-fill format-spec gnus-agent gnus-art gnus-async gnus-audio gnus-bcklg gnus-cache gnus-cite gnus-cus gnus-delay gnus-demon gnus-diary gnus-dired gnus-draft gnus-dup gnus-eform gnus-ems gnus-fun gnus-gl gnus-group gnus-int gnus-kill gnus-logic gnus-mh gnus-ml gnus-mlspl gnus-move gnus-msg gnus-nocem gnus-picon gnus-range gnus-registry gnus-salt gnus-score gnus-setup gnus-sieve gnus-soup gnus-spec gnus-srvr gnus-start gnus-sum gnus-topic gnus-undo gnus-util gnus-uu gnus-vm gnus-win gnus-xmas gnus ietf-drums imap mail-parse mail-prsvr mail-source mailcap message messagexmas messcompat mm-bodies mm-decode mm-encode mm-extern mm-partial mm-url mm-util mm-uu mm-view mml-sec mml-smime mml mml1991 mml2015 nnagent nnbabyl nndb nndiary nndir nndoc nndraft nneething nnfolder nngateway nnheader nnheaderxm nnimap nnkiboze nnlistserv nnmail nnmaildir nnmbox nnmh nnml nnnil nnoo nnrss nnslashdot nnsoup nnspool nntp nnultimate nnvirtual nnwarchive nnweb nnwfm parse-time qp rfc1843 rfc2045 rfc2047 rfc2231 score-mode smiley smime spam-report spam-stat spam time-date utf7 uudecode webmail yenc gnus-idna gpg-ring gpg hashcash vcard)
+   requires (gnus w3 mh-e mailcrypt rmail eterm mail-lib xemacs-base fsf-compat ecrypto tm apel pgg net-utils sh-script os-utils dired sieve sasl)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(rmail
+  (standards-version 1.1
+   version "1.14"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "An obsolete Emacs mailer."
+   filename "rmail-1.14-pkg.tar.gz"
+   md5sum "4409fc7ff5134ff562ff1357a014a41b"
+   size 96995
+   provides (rmail-kill rmail-xemacs rmail rmailsort)
+   requires (tm apel mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mailcrypt
+  (standards-version 1.1
+   version "2.13"
+   author-version "3.5.8"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Support for messaging encryption with PGP."
+   filename "mailcrypt-2.13-pkg.tar.gz"
+   md5sum "efe51870b559239cf48a102ea8a89e2f"
+   size 154111
+   provides (expect mailcrypt)
+   requires (mail-lib fsf-compat xemacs-base cookie gnus mh-e rmail vm)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(supercite
+  (standards-version 1.1
+   version "1.20"
+   author-version "3.55x3"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "An Emacs citation tool for News & Mail messages."
+   filename "supercite-1.20-pkg.tar.gz"
+   md5sum "277fb688d3765c0434e34013e811e94d"
+   size 100553
+   provides (supercite)
+   requires (mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(mh-e
+  (standards-version 1.1
+   version "1.27"
+   author-version "7.4.2"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Steve Youngs <mh-e-devel@lists.sf.net>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Front end support for MH."
+   filename "mh-e-1.27-pkg.tar.gz"
+   md5sum "5b886efc6e93f97a61237dade2f360ee"
+   size 577724
+   provides (mh-alias mh-comp mh-customize mh-e mh-funcs mh-gnus mh-identity mh-inc mh-index mh-junk mh-loaddefs mh-mime mh-pick mh-seq mh-speed mh-unit mh-utils mh-xemacs-compat mh-xemacs-icons)
+   requires (gnus mail-lib xemacs-base speedbar rmail tm apel sh-script fsf-compat xemacs-devel net-utils eterm os-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(gnats
+  (standards-version 1.1
+   version "1.16"
+   author-version "3.101"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "XEmacs bug reports."
+   filename "gnats-1.16-pkg.tar.gz"
+   md5sum "678c190f7cd184426dcccc0f3a6d10b2"
+   size 188963
+   provides (gnats gnats-admin send-pr)
+   requires (mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(footnote
+  (standards-version 1.1
+   version "1.16"
+   author-version "0.18x"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "SL Baur <steve@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Footnoting in mail message editing modes."
+   filename "footnote-1.16-pkg.tar.gz"
+   md5sum "79dc557f3be890dc6f3e7793fef6f1b6"
+   size 22152
+   provides (footnote-cyrillic footnote-greek footnote-han footnote-hebrew footnote-kana footnote)
+   requires (mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(eudc
+  (standards-version 1.1
+   version "1.39"
+   author-version "1.32"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Oscar Figueiredo <oscar@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Emacs Unified Directory Client (LDAP, PH)."
+   filename "eudc-1.39-pkg.tar.gz"
+   md5sum "1c725e74136dc51c02f4e7b7642140a7"
+   size 79488
+   provides (eudc eudc-vars eudc-hotlist eudc-export eudc-bob eudcb-ldap eudcb-ph eudcb-bbdb)
+   requires (fsf-compat xemacs-base bbdb mail-lib gnus rmail tm apel eterm sh-script net-utils)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(net-utils
+  (standards-version 1.1
+   version "1.33"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Miscellaneous Networking Utilities."
+   filename "net-utils-1.33-pkg.tar.gz"
+   md5sum "9470e0dc21c8dd3c1d859ce7541f31c0"
+   size 137514
+   provides (ilisp-browse-cltl2 xemacsbug feedmail metamail net-utils rcompile shadowfile webjump webster-www dig dns xml)
+   requires (bbdb w3 efs mail-lib xemacs-base fsf-compat eterm sh-script gnus rmail tm apel)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(w3
+  (standards-version 1.1
+   version "1.29"
+   author-version "4.0pre47"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "A Web browser."
+   filename "w3-1.29-pkg.tar.gz"
+   md5sum "088e276b855e95b2032aa58160ffeba2"
+   size 694178
+   provides (css devices w3-auto dsssl-flow dsssl font images mm mule-sysdp socks ssl urlauth url-cache url-cookie url-file url-gopher url-gw url-http url-ldap url-mail url-misc url-news url-ns url-parse url-vars url w3-about w3-auto w3-cfg w3-cus w3-display w3-emacs19 w3-e19 w3-e20 w3-elisp w3-emulate w3-forms w3-hot w3-hotindex w3-imap w3-java w3-jscript w3-keyword w3-latex w3-menu w3-mouse w3-parse w3-print w3-props w3-script w3-structure w3-speak w3-style w3-sysdp w3-toolbar w3-vars w3-widget w3-xemacs w3-xemac w3)
+   requires (w3 mail-lib xemacs-base ecrypto)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(vm
+  (standards-version 1.1
+   version "7.18"
+   author-version "7.17"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Kyle Jones <kyle_jones@wonderworks.com>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "An Emacs mailer."
+   filename "vm-7.18-pkg.tar.gz"
+   md5sum "25a353d78f64c2dd2e1001719158a315"
+   size 812340
+   provides (tapestry vm-byteopts vm-delete vm-digest vm-easymenu vm-edit vm-folder vm-imap vm-license vm-macro vm-mark vm-menu vm-message vm-mime vm-minibuf vm-misc vm-motion vm-mouse vm-page vm-pop vm-reply vm-save vm-search vm-sort vm-startup vm-summary vm-thread vm-toolbar vm-undo vm-user vm-vars vm vm-version vm-virtual vm-window)
+   requires (mail-lib xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sounds-wav
+  (standards-version 1.1
+   version "1.12"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "XEmacs Microsoft sound files."
+   filename "sounds-wav-1.12-pkg.tar.gz"
+   md5sum "3045a90ca53b22ebb7aa52f611bafcd3"
+   size 149624
+   provides ()
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(sounds-au
+  (standards-version 1.1
+   version "1.12"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "XEmacs Sun sound files."
+   filename "sounds-au-1.12-pkg.tar.gz"
+   md5sum "9bf0b5a2ac38a4fe2d710063ddcaadd3"
+   size 126817
+   provides ()
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(xemacs-devel
+  (standards-version 1.1
+   version "1.60"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority medium
+   category "standard"
+   dump nil
+   description "Emacs Lisp developer support."
+   filename "xemacs-devel-1.60-pkg.tar.gz"
+   md5sum "db789317a15bf3a73bacd7b337ec7a34"
+   size 232116
+   provides (checkdoc docref eldoc elp eval-expr find-func hide-copyleft ielm patcher pp trace patch-keywords)
+   requires (xemacs-base ispell mail-lib gnus rmail tm apel sh-script net-utils eterm)
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(tooltalk
+  (standards-version 1.1
+   version "1.15"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Support for building with Tooltalk."
+   filename "tooltalk-1.15-pkg.tar.gz"
+   md5sum "3d1a4ddbd0da23033a6dc8a8c90849e2"
+   size 9749
+   provides ()
+   requires ()
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(elib
+  (standards-version 1.1
+   version "1.11"
+   author-version "1.0"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "Portable Emacs Lisp utilities library."
+   filename "elib-1.11-pkg.tar.gz"
+   md5sum "914b735704c60f7d534398025ae725db"
+   size 73387
+   provides (avltree bintree cookie dll elib-node queue-f queue-m read stack-f stack-m string)
+   requires ()
+   type single
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(edebug
+  (standards-version 1.1
+   version "1.20"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "An Emacs Lisp debugger."
+   filename "edebug-1.20-pkg.tar.gz"
+   md5sum "ff397fa7dba09ab0a52a83649b8a14d8"
+   size 115244
+   provides (edebug cl-read cust-print eval-reg cl-specs)
+   requires (xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(Sun
+  (standards-version 1.1
+   version "1.15"
+   author-version "No-Upstream-Ver"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority low
+   category "standard"
+   dump nil
+   description "Support for Sparcworks."
+   filename "Sun-1.15-pkg.tar.gz"
+   md5sum "ac4b09817681596ba032cf868c7c6dac"
+   size 64660
+   provides (sccs eos-browser eos-common eos-debugger eos-debugger eos-editor eos-init eos-load eos-menubar eos-toolbar sunpro)
+   requires (cc-mode xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(apel
+  (standards-version 1.1
+   version "1.27"
+   author-version "10.2"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "XEmacs Development Team <xemacs-beta@xemacs.org>"
+   distribution xemacs
+   priority high
+   category "standard"
+   dump nil
+   description "A Portable Emacs Library.  Used by XEmacs MIME support."
+   filename "apel-1.27-pkg.tar.gz"
+   md5sum "2f35080836afe0730b2fe664f90b01be"
+   size 108585
+   provides (atype emu-20 emu-e19 emu-x20 emu-xemacs emu file-detect filename install mule-caesar path-util richtext std11-parse std11 tinyrich)
+   requires (fsf-compat xemacs-base)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(efs
+  (standards-version 1.0
+   version "1.32"
+   author-version "1.22"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Mike Sperber <sperber@informatik.uni-tuebingen.de>"
+   distribution stable
+   priority medium
+   category "standard"
+   dump nil
+   description "Treat files on remote systems the same as local files."
+   filename "efs-1.32-pkg.tar.gz"
+   md5sum "6123c11bc7a9c993429e9976f7bf42c4"
+   size 375800
+   provides (efs)
+   requires (xemacs-base dired)
+   type regular
+))
+))
+;;;@@@
+(package-get-update-base-entry (quote
+(dired
+  (standards-version 1.0
+   version "1.15"
+   author-version "7.11"
+   date "2003-10-31"
+   build-date "2003-10-31"
+   maintainer "Mike Sperber <sperber@informatik.uni-tuebingen.de>"
+   distribution stable
+   priority medium
+   category "standard"
+   dump nil
+   description "Manage file systems."
+   filename "dired-1.15-pkg.tar.gz"
+   md5sum "3bd864d76ba88c2a8a42772222a2743f"
+   size 198282
+   provides (diff dired)
+   requires (xemacs-base prog-modes)
+   type regular
+))
+))
+;;;@@@
+;; Package Index file ends here
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.2.3 (FreeBSD)
+Comment: The XEmacs Development Team
+
+iD4DBQE/s2HKgu3ywdHdhM0RAsIRAJiVkwgHSIPBMZBJlZdA06kOtKV2AKCqhmSb
+/TUbeZRrIemjq9es9VqYJg==
+=n9fY
+-----END PGP SIGNATURE-----

diff --git a/info/cl.info b/info/cl.info
index 2715500..5c36018 100644 (file)
--- a/info/cl.info
+++ b/info/cl.info
@@ -1,4 +1,4 @@
-This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+This is ../info/cl.info, produced by makeinfo version 4.6 from cl.texi.

 
 INFO-DIR-SECTION XEmacs Editor
 START-INFO-DIR-ENTRY
 
 INFO-DIR-SECTION XEmacs Editor
 START-INFO-DIR-ENTRY

@@ -27,16 +27,5041 @@ may be included in a translation approved by the author instead of in
 the original English.
 
 \1f
 the original English.
 
 \1f

-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
+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::
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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--))
+
+\1f
+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'.
+
+\1f
+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'
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'
+
+\1f
+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'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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*'.
+
+\1f
+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.)
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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)'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+

 \1f
 Tag Table:
 \1f
 Tag Table:

-(Indirect)

 Node: Top\7f1164
 Node: Overview\7f2716
 Node: Usage\7f4995
 Node: Top\7f1164
 Node: Overview\7f2716
 Node: Usage\7f4995

diff --git a/info/custom.info b/info/custom.info
index 0a0b284..62ed588 100644 (file)
--- a/info/custom.info
+++ b/info/custom.info
@@ -1,4 +1,4 @@
-This is ../info/custom.info, produced by makeinfo version 4.0 from
+This is ../info/custom.info, produced by makeinfo version 4.6 from

 custom.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 custom.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -12,7 +12,7 @@ File: custom.info,  Node: Top,  Next: Declaring Groups,  Prev: (dir),  Up: (dir)
 The Customization Library
 *************************
 
 The Customization Library
 *************************
 

-   This manual describes how to declare customization groups, variables,
+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.
 
 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.
 

@@ -56,7 +56,7 @@ File: custom.info,  Node: Declaring Groups,  Next: Declaring Variables,  Prev: T
 Declaring Groups
 ================
 
 Declaring Groups
 ================
 

-   Use `defgroup' to declare new customization groups.
+Use `defgroup' to declare new customization groups.

 
  - Function: defgroup symbol members doc [keyword value]...
      Declare SYMBOL as a customization group containing MEMBERS.
 
  - Function: defgroup symbol members doc [keyword value]...
      Declare SYMBOL as a customization group containing MEMBERS.

@@ -87,7 +87,7 @@ File: custom.info,  Node: Declaring Variables,  Next: Declaring Faces,  Prev: De
 Declaring Variables
 ===================
 
 Declaring Variables
 ===================
 

-   Use `defcustom' to declare user editable 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.
 
  - Function: defcustom symbol value doc [keyword value]...
      Declare SYMBOL as a customizable variable that defaults to VALUE.

@@ -145,6 +145,7 @@ Declaring Variables
           required when the `defcustom' is evaluated, or when Emacs is
           started if the user has saved this option.
 
           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.
 
      *Note Sexp Types: (widget)Sexp Types, for information about
      widgets to use together with the `:type' keyword.
 

@@ -168,7 +169,7 @@ File: custom.info,  Node: Declaring Faces,  Next: Usage for Package Authors,  Pr
 Declaring Faces
 ===============
 
 Declaring Faces
 ===============
 

-   Faces are declared with `defface'.
+Faces are declared with `defface'.

 
  - Function: defface face spec doc [keyword value]...
      Declare FACE as a customizable face that defaults to SPEC.  FACE
 
  - Function: defface face spec doc [keyword value]...
      Declare FACE as a customizable face that defaults to SPEC.  FACE

@@ -217,11 +218,11 @@ File: custom.info,  Node: Usage for Package Authors,  Next: Utilities,  Prev: De
 Usage for Package Authors
 =========================
 
 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 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
 
    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

@@ -234,7 +235,7 @@ File: custom.info,  Node: Utilities,  Next: The Init File,  Prev: Usage for Pack
 Utilities
 =========
 
 Utilities
 =========
 

-   These utilities can come in handy when adding customization support.
+These utilities can come in handy when adding customization support.

 
  - Widget: custom-manual
      Widget type for specifying the info manual entry for a
 
  - Widget: custom-manual
      Widget type for specifying the info manual entry for a

@@ -263,11 +264,24 @@ File: custom.info,  Node: The Init File,  Next: Wishlist,  Prev: Utilities,  Up:
 The Init File
 =============
 
 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.
+Customizations are saved to the file specified by `custom-file', as
+calls to `custom-set-variables' and `custom-set-faces'.
+
+   When you save customizations, the current implementation removes the
+calls to `custom-set-variables' and `custom-set-faces', and replaces
+them with code generated on the basis of the current customization
+state in Emacs.
+
+   By default `custom-file' is your `.emacs' file (for GNU Emacs and
+older XEmacs) and is `custom.el' in the same directory as `init.el' (in
+XEmacs 21.4 and later).  If you use another file, you must explicitly
+load it yourself.
+
+   As of XEmacs 21.4.7, when `custom-file' is present, it is loaded
+_after_ `init.el'.  This is likely to change in the future, because (1)
+actions in `init.el' often would like to depend on customizations for
+consistent appearance and (2) Custom is quite brutal about enforcing
+its idea of the correct values at initialization.

 
 \1f
 File: custom.info,  Node: Wishlist,  Prev: The Init File,  Up: Top
 
 \1f
 File: custom.info,  Node: Wishlist,  Prev: The Init File,  Up: Top

@@ -382,12 +396,12 @@ Wishlist
 \1f
 Tag Table:
 Node: Top\7f204
 \1f
 Tag Table:
 Node: Top\7f204

-Node: Declaring Groups\7f1625
-Node: Declaring Variables\7f2726
-Node: Declaring Faces\7f5817
-Node: Usage for Package Authors\7f7515
-Node: Utilities\7f8294
-Node: The Init File\7f9378
-Node: Wishlist\7f9830
+Node: Declaring Groups\7f1622
+Node: Declaring Variables\7f2720
+Node: Declaring Faces\7f5809
+Node: Usage for Package Authors\7f7504
+Node: Utilities\7f8280
+Node: The Init File\7f9361
+Node: Wishlist\7f10388

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

diff --git a/info/emodules.info b/info/emodules.info
index c527ed0..ac1d26b 100644 (file)
--- a/info/emodules.info
+++ b/info/emodules.info
@@ -1,4 +1,4 @@
-This is ../info/emodules.info, produced by makeinfo version 4.0 from
+This is ../info/emodules.info, produced by makeinfo version 4.6 from

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

@@ -75,7 +75,7 @@ File: emodules.info,  Node: Introduction,  Next: Anatomy of a Module,  Prev: Top
 Introduction
 ************
 
 Introduction
 ************
 

-   XEmacs is a powerful, extensible editor.  The traditional way of
+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
 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

@@ -159,8 +159,8 @@ File: emodules.info,  Node: Anatomy of a Module,  Next: Using ellcc,  Prev: Intr
 Anatomy of a Module
 *******************
 
 Anatomy of a Module
 *******************
 

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

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

@@ -179,14 +179,14 @@ File: emodules.info,  Node: Required Header File,  Next: Required Functions,  Pr
 Required Header File
 ====================
 
 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.
+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
 
    Depending on exactly what your module will be doing, you will
 probably need to include one or more of the XEmacs internal header

@@ -228,7 +228,7 @@ File: emodules.info,  Node: Required Functions,  Next: Required Variables,  Prev
 Required Functions
 ==================
 
 Required Functions
 ==================
 

-   Every module requires several initialization functions.  It is the
+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
 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

@@ -280,7 +280,7 @@ File: emodules.info,  Node: Required Variables,  Next: Loading other Modules,  P
 Required Variables
 ==================
 
 Required Variables
 ==================
 

-   Not only does a module need to declare the initialization functions
+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
 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

@@ -334,12 +334,11 @@ File: emodules.info,  Node: Loading other Modules,  Prev: Required Variables,  U
 Loading other Modules
 =====================
 
 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':
+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,
 
      int emodules_load (const char *module,
                         const char *modname,

@@ -371,15 +370,29 @@ 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.
 
 their parents will also fail to load.  This does not include previous
 successful calls to `emodules_load' at the top level.
 

+   *Warning:* Modules are _not_ loaded with the `RTLD_GLOBAL' flag.
+The practical upshot is that individual modules do not have access to
+each other's C symbols.  One module cannot make a C function call to a
+function defined in another module, nor can it read or set a C variable
+in another module.  All interaction between modules must, therefore,
+take place at the Lisp level.  This is by design.  Other projects have
+attempted to use `RTLD_GLOBAL', only to find that spurious symbol name
+clashes were the result.  Helper functions often have simple names,
+increasing the probability of such a clash.  If you really need to
+share symbols between modules, create a shared library containing those
+symbols, and link your modules with that library.  Otherwise,
+interactions between modules must take place via Lisp function calls
+and Lisp variables accesses.
+

 \1f
 File: emodules.info,  Node: Using ellcc,  Next: Defining Functions,  Prev: Anatomy of a Module,  Up: Top
 
 Using `ellcc'
 *************
 
 \1f
 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
+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.
 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.

@@ -415,10 +428,10 @@ File: emodules.info,  Node: Compile Mode,  Next: Initialization Mode,  Prev: Usi
 Compile Mode
 ============
 
 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
+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
 `ellcc'.
 
    In this mode, `ellcc' is simply a front-end to the same C compiler

@@ -449,7 +462,7 @@ File: emodules.info,  Node: Initialization Mode,  Next: Link Mode,  Prev: Compil
 Initialization Mode
 ===================
 
 Initialization Mode
 ===================
 

-   XEmacs uses a rather bizarre way of documenting variables and
+XEmacs uses a rather bizarre way of documenting variables and

 functions.  Rather than have the documentation for compiled functions
 and variables passed as static strings in the source code, the
 documentation is included as a C comment.  A special program, called
 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

@@ -540,7 +553,7 @@ required to populate the `docs_of_module' function.  Below is a sample
 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
 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
+directory is automatically searched 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
 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

@@ -557,7 +570,7 @@ File: emodules.info,  Node: Link Mode,  Next: Other ellcc options,  Prev: Initia
 Link Mode
 =========
 
 Link Mode
 =========
 

-   Once all of your source code files have been compiled (including the
+Once all of your source code files have been compiled (including the

 generated init file) you need to link them all together to 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
 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

@@ -581,7 +594,7 @@ File: emodules.info,  Node: Other ellcc options,  Next: Environment Variables,
 Other `ellcc' options
 =====================
 
 Other `ellcc' options
 =====================
 

-   Aside from the three main `ellcc' modes described above, `ellcc' can
+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
 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

@@ -649,11 +662,11 @@ File: emodules.info,  Node: Environment Variables,  Prev: Other ellcc options,
 Environment Variables
 =====================
 
 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'
+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'
 recognizes.
 
 `ELLCC'

@@ -696,8 +709,8 @@ File: emodules.info,  Node: Defining Functions,  Next: Defining Variables,  Prev
 Defining Functions
 ******************
 
 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
+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
 "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

@@ -736,8 +749,8 @@ File: emodules.info,  Node: Using DEFUN,  Next: Declaring Functions,  Prev: Defi
 Using `DEFUN'
 =============
 
 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
+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:
 
 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:
 

@@ -779,7 +792,7 @@ File: emodules.info,  Node: Declaring Functions,  Prev: Using DEFUN,  Up: Defini
 Declaring Functions
 ===================
 
 Declaring Functions
 ===================
 

-   Simply writing the code for a function is not enough to make it
+Simply writing the code for a function is not enough to make it

 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
 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

@@ -810,7 +823,7 @@ File: emodules.info,  Node: Defining Variables,  Next: Index,  Prev: Defining Fu
 Defining Variables
 ******************
 
 Defining Variables
 ******************
 

-   Rarely will you write a module that only contains functions.  It is
+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
 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

@@ -939,21 +952,21 @@ Index
 Tag Table:
 Node: Top\7f1536
 Node: Introduction\7f2883
 Tag Table:
 Node: Top\7f1536
 Node: Introduction\7f2883

-Node: Anatomy of a Module\7f7391
-Node: Required Header File\7f8205
-Node: Required Functions\7f10124
-Node: Required Variables\7f12848
-Node: Loading other Modules\7f15534
-Node: Using ellcc\7f17591
-Node: Compile Mode\7f19385
-Node: Initialization Mode\7f20753
-Node: Link Mode\7f25787
-Node: Other ellcc options\7f26932
-Node: Environment Variables\7f29511
-Node: Defining Functions\7f31202
-Node: Using DEFUN\7f33213
-Node: Declaring Functions\7f34924
-Node: Defining Variables\7f36267
-Node: Index\7f38510
+Node: Anatomy of a Module\7f7388
+Node: Required Header File\7f8199
+Node: Required Functions\7f10115
+Node: Required Variables\7f12836
+Node: Loading other Modules\7f15519
+Node: Using ellcc\7f18432
+Node: Compile Mode\7f20223
+Node: Initialization Mode\7f21588
+Node: Link Mode\7f26615
+Node: Other ellcc options\7f27757
+Node: Environment Variables\7f30333
+Node: Defining Functions\7f32022
+Node: Using DEFUN\7f34030
+Node: Declaring Functions\7f35738
+Node: Defining Variables\7f37078
+Node: Index\7f39318

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

diff --git a/info/external-widget.info b/info/external-widget.info
index e7ebc60..e003b3a 100644 (file)
--- a/info/external-widget.info
+++ b/info/external-widget.info
@@ -1,4 +1,4 @@
-This is ../info/external-widget.info, produced by makeinfo version 4.0
+This is ../info/external-widget.info, produced by makeinfo version 4.6

 from external-widget.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 from external-widget.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -18,6 +18,7 @@ powerful replacement for standard text widgets.
 * Using an External Client Widget::
 * External Client Widget Resource Settings::
 * Motif-Specific Info About the External Client Widget::
 * Using an External Client Widget::
 * External Client Widget Resource Settings::
 * Motif-Specific Info About the External Client Widget::

+* External Client Widget Internals::

 
 \1f
 File: external-widget.info,  Node: Using an External Client Widget,  Next: External Client Widget Resource Settings,  Prev: Top,  Up: Top
 
 \1f
 File: external-widget.info,  Node: Using an External Client Widget,  Next: External Client Widget Resource Settings,  Prev: Top,  Up: Top

@@ -25,10 +26,10 @@ File: external-widget.info,  Node: Using an External Client Widget,  Next: Exter
 Using an External Client Widget
 *******************************
 
 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
+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
 `-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

@@ -59,9 +60,9 @@ File: external-widget.info,  Node: External Client Widget Resource Settings,  Ne
 External Client Widget Resource Settings
 ****************************************
 
 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:
+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
 
 `deadShell (class DeadShell)'
      A boolean resource indicating whether the last request to the

@@ -110,12 +111,12 @@ are primarily for handling query-geometry and geometry-manager requests
 made by parent or child widgets.
 
 \1f
 made by parent or child widgets.
 
 \1f

-File: external-widget.info,  Node: Motif-Specific Info About the External Client Widget,  Prev: External Client Widget Resource Settings,  Up: Top
+File: external-widget.info,  Node: Motif-Specific Info About the External Client Widget,  Next: External Client Widget Internals,  Prev: External Client Widget Resource Settings,  Up: Top

 
 Motif-Specific Info About the External Client Widget
 ****************************************************
 
 
 Motif-Specific Info About the External Client Widget
 ****************************************************
 

-   By default, the external client widget has navigation type
+By default, the external client widget has navigation type

 `XmTAB_GROUP'.
 
    The widget traversal keystrokes are modified slightly from the
 `XmTAB_GROUP'.
 
    The widget traversal keystrokes are modified slightly from the

@@ -126,12 +127,121 @@ 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.
 
 `Shift-<TAB>' are silently filtered by the external client widget and
 are not seen by Emacs.
 

+\1f
+File: external-widget.info,  Node: External Client Widget Internals,  Prev: Motif-Specific Info About the External Client Widget,  Up: Top
+
+External Client Widget Internals
+********************************
+
+The following text is lifted verbatim from Ben Wing's comments in
+`ExternalShell.c'.
+
+   This is a special Shell that is designed to use an externally-
+provided window created by someone else (possibly another process).
+That other window should have an associated widget of class
+ExternalClient.  The two widgets communicate with each other using
+ClientMessage events and properties on the external window.
+
+   Ideally this feature should be independent of Emacs.  Unfortunately
+there are lots and lots of specifics that need to be dealt with for
+this to work properly, and some of them can't conveniently be handled
+within the widget's methods.  Some day the code may be rewritten so
+that the embedded-widget feature can be used by any application, with
+appropriate entry points that are called at specific points within the
+application.
+
+   This feature is similar to the OLE (Object Linking & Embedding)
+feature provided by MS Windows.
+
+   Communication between this shell and the client widget:
+
+   Communication is through ClientMessage events with message_type
+EXTW_NOTIFY and format 32.  Both the shell and the client widget
+communicate with each other by sending the message to the same window
+(the "external window" below), and the data.l[0] value is used to
+determine who sent the message.
+
+   The data is formatted as follows:
+
+   data.l[0] = who sent this message: external_shell_send (0) or
+    external_client_send (1) data.l[1] = message type (see enum
+en_extw_notify below) data.l[2-4] = data associated with this message
+
+   EventHandler() handles messages from the other side.
+
+   extw_send_notify_3() sends a message to the other side.
+
+   extw_send_geometry_value() is used when an XtWidgetGeometry structure
+  needs to be sent.  This is too much data to fit into a
+ClientMessage, so the data is stored in a property and then
+extw_send_notify_3() is called.
+
+   extw_get_geometry_value() receives an XtWidgetGeometry structure
+from a    property.
+
+   extw_wait_for_response() is used when a response to a sent message
+is expected.  It looks for a matching event within a    particular
+timeout.
+
+   The particular message types are as follows:
+
+   1) extw_notify_init (event_window, event_mask)
+
+   This is sent from the shell to the client after the shell realizes
+its EmacsFrame widget on the client's "external window".  This tells
+the client that it should start passing along events of the types
+specified in event_mask.  event_window specifies the window of the
+EmacsFrame widget, which is a child of the client's external window.
+
+   extw_notify_init (client_type)
+
+   When the client receives an extw_notify_init message from the shell,
+it sends back a message of the same sort specifying the type of the
+toolkit used by the client (Motif, generic Xt, or Xlib).
+
+   2) extw_notify_end ()
+
+   This is sent from the shell to the client when the shell's
+EmacsFrame widget is destroyed, and tells the client to stop passing
+events along.
+
+   3) extw_notify_qg (result)
+
+   This is sent from the client to the shell when a QueryGeometry
+request is received on the client.  The XtWidgetGeometry structure
+specified in the QueryGeometry request is passed on in the
+EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the
+external window.  result is unused.
+
+   In response, the shell passes the QueryGeometry request down the
+widget tree, and when a response is received, sends a message of type
+extw_notify_qg back to the client, with result specifying the
+GeometryResult value.  If this value is XtGeometryAlmost, the returned
+XtWidgetGeometry structure is stored into the same property as above.
+[BPW is there a possible race condition here?]
+
+   4) extw_notify_gm (result)
+
+   A very similar procedure to that for extw_notify_qg is followed when
+the shell's RootGeometryManager method is called, indicating that a
+child widget wishes to change the shell's geometry.  The
+XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER
+property.
+
+   5) extw_notify_focus_in (), extw_notify_focus_out ()
+
+   These are sent from the client to the shell when the client gains or
+loses the keyboard focus.  It is done this way because Xt maintains its
+own concept of keyboard focus and only the client knows this
+information.
+

 
 \1f
 Tag Table:
 Node: Top\7f232
 
 \1f
 Tag Table:
 Node: Top\7f232

-Node: Using an External Client Widget\7f662
-Node: External Client Widget Resource Settings\7f2377
-Node: Motif-Specific Info About the External Client Widget\7f5120
+Node: Using an External Client Widget\7f699
+Node: External Client Widget Resource Settings\7f2410
+Node: Motif-Specific Info About the External Client Widget\7f5150
+Node: External Client Widget Internals\7f5961

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

diff --git a/info/info.info b/info/info.info
index 9e504e6..47f47a4 100644 (file)
--- a/info/info.info
+++ b/info/info.info
@@ -1,4 +1,4 @@
-This is ../info/info.info, produced by makeinfo version 4.0 from
+This is ../info/info.info, produced by makeinfo version 4.6 from

 info.texi.
 
 INFO-DIR-SECTION Texinfo documentation system
 info.texi.
 
 INFO-DIR-SECTION Texinfo documentation system

@@ -31,7 +31,7 @@ File: info.info,  Node: Top,  Next: Getting Started,  Up: (dir)
 Info: An Introduction
 *********************
 
 Info: An Introduction
 *********************
 

-   Info is a program for reading documentation, which you might be using
+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
 now to read this.
 
    To learn how to use Info, type the command `h' while using the Info

@@ -49,7 +49,7 @@ File: info.info,  Node: Getting Started,  Next: Advanced Info,  Prev: Top,  Up:
 Getting Started
 ***************
 
 Getting Started
 ***************
 

-   This first part of the Info manual describes how to get around inside
+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.
 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.

@@ -70,7 +70,7 @@ File: info.info,  Node: Help-Small-Screen,  Next: Help,  Up: Getting Started
 Starting Info on a Small Screen
 ===============================
 
 Starting Info on a Small Screen
 ===============================
 

-   Since your terminal has an unusually small number of lines on its
+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
 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

@@ -134,7 +134,7 @@ File: info.info,  Node: Help,  Next: Help-P,  Prev: Help-Small-Screen,  Up: Gett
 How to use Info
 ===============
 
 How to use Info
 ===============
 

-   You are talking to the program Info, for reading documentation.
+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
 
    Right now you are looking at one "Node" of Information.  A node
 contains text describing a specific topic at a specific level of

@@ -161,7 +161,7 @@ File: info.info,  Node: Help-P,  Next: Help-^L,  Prev: Help,  Up: Getting Starte
 Returning to the Previous node
 ==============================
 
 Returning to the Previous node
 ==============================
 

-   This node is called `Help-P'.  The `Previous' node, as you see, is
+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'.
 
 `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'.
 

@@ -182,7 +182,7 @@ File: info.info,  Node: Help-^L,  Next: Help-M,  Prev: Help-P,  Up: Getting Star
 The Space, Delete, B and ^L commands.
 =====================================
 
 The Space, Delete, B and ^L commands.
 =====================================
 

-   This node's header tells you that you are now at node `Help-^L', and
+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).
 
 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).
 

@@ -246,7 +246,7 @@ File: info.info,  Node: Help-M,  Next: Help-Adv,  Prev: Help-^L,  Up: Getting St
 Menus
 =====
 
 Menus
 =====
 

-   Menus and the `m' command
+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
 
    With only the `n' and `p' commands for moving between nodes, nodes
 are restricted to a linear sequence.  Menus allow a branching

@@ -382,12 +382,12 @@ File: info.info,  Node: Help-FOO,  Up: Help-M
 The `u' command
 ---------------
 
 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"
+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 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

@@ -401,7 +401,7 @@ File: info.info,  Node: Help-Adv,  Next: Help-Q,  Prev: Help-M,  Up: Getting Sta
 Some advanced Info commands
 ===========================
 
 Some advanced Info commands
 ===========================
 

-   The course is almost over, so please stick with it to the end.
+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
 
    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

@@ -465,7 +465,7 @@ File: info.info,  Node: Help-Cross,  Up: Help-Adv
 The node reached by the cross reference in Info
 -----------------------------------------------
 
 The node reached by the cross reference in Info
 -----------------------------------------------
 

-   This is the node reached by the cross reference named `Cross'.
+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
 
    While this node is specifically intended to be reached by a cross
 reference, most cross references lead to nodes that "belong" someplace

@@ -482,7 +482,7 @@ File: info.info,  Node: Help-Q,  Prev: Help-Adv,  Up: Getting Started
 Quitting Info
 =============
 
 Quitting Info
 =============
 

-   To get out of Info, back to what you were doing before, type `q' for
+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
 "Quit".
 
    This is the end of the course on using Info.  There are some other

@@ -501,9 +501,9 @@ File: info.info,  Node: Advanced Info,  Next: Creating an Info File,  Prev: Gett
 Info for Experts
 ****************
 
 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
+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.)
 
 generate an Info file and to make a printed manual.  *Note Overview of
 Texinfo: (texinfo)Top.)
 

@@ -524,7 +524,7 @@ File: info.info,  Node: Expert,  Next: Add,  Up: Advanced Info
 Advanced Info Commands
 ======================
 
 Advanced Info Commands
 ======================
 

-   `g', `s', `1', - `9', and `e'
+`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
 
    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

@@ -579,7 +579,7 @@ File: info.info,  Node: Add,  Next: Menus,  Prev: Expert,  Up: Advanced Info
 Adding a new node to Info
 =========================
 
 Adding a new node to Info
 =========================
 

-   To add a new topic to the list in the Info directory, you must:
+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.
   1. Create some nodes, in some file, to document that topic.
 
   2. Put that topic in the menu in the directory.  *Note Menu: Menus.

@@ -646,7 +646,7 @@ File: info.info,  Node: Menus,  Next: Cross-refs,  Prev: Add,  Up: Advanced Info
 How to Create Menus
 ===================
 
 How to Create Menus
 ===================
 

-   Any node in the Info hierarchy may have a "menu"--a list of subnodes.
+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.
 
 The `m' command searches the current node's menu for the topic which it
 reads from the terminal.
 

@@ -701,7 +701,7 @@ File: info.info,  Node: Cross-refs,  Next: Tags,  Prev: Menus,  Up: Advanced Inf
 Creating Cross References
 =========================
 
 Creating Cross References
 =========================
 

-   A cross reference can be placed anywhere in the text, unlike a menu
+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
 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

@@ -720,9 +720,9 @@ File: info.info,  Node: Tags,  Next: Checking,  Prev: Cross-refs,  Up: Advanced
 Tag Tables for Info Files
 =========================
 
 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
+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
 whenever Info reads in the file.
 
    To make a tag table, go to a node in the file using Emacs Info mode

@@ -756,10 +756,10 @@ File: info.info,  Node: Checking,  Next: Emacs Info Variables,  Prev: Tags,  Up:
 Checking an Info File
 =====================
 
 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
+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,
 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,

@@ -776,10 +776,10 @@ File: info.info,  Node: Emacs Info Variables,  Prev: Checking,  Up: Advanced Inf
 Emacs Info-mode Variables
 =========================
 
 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.
+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'
 
 `Info-enable-edit'
      Set to `nil', disables the `e' (`Info-edit') command.  A non-`nil'

@@ -804,7 +804,7 @@ File: info.info,  Node: Creating an Info File,  Prev: Advanced Info,  Up: Top
 Creating an Info File
 *********************
 
 Creating an Info File
 *********************
 

-   *Note Overview of Texinfo: (texinfo)Top, to learn how to write a
+*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
 Texinfo file.
 
    *Note Creating an Info File: (texinfo)Create an Info File, to learn

@@ -817,24 +817,24 @@ learn how to install an Info file after you have created one.
 \1f
 Tag Table:
 Node: Top\7f1067
 \1f
 Tag Table:
 Node: Top\7f1067

-Node: Getting Started\7f1612
-Node: Help-Small-Screen\7f2360
-Node: Help\7f4109
-Node: Help-P\7f5139
-Node: Help-^L\7f6001
-Node: Help-M\7f8879
-Node: Help-FOO\7f14859
-Node: Help-Adv\7f15597
-Node: Help-Cross\7f18272
-Node: Help-Q\7f18918
-Node: Advanced Info\7f19545
-Node: Expert\7f20523
-Node: Add\7f23037
-Node: Menus\7f26397
-Node: Cross-refs\7f29271
-Node: Tags\7f29973
-Node: Checking\7f31275
-Node: Emacs Info Variables\7f32228
-Node: Creating an Info File\7f33217
+Node: Getting Started\7f1609
+Node: Help-Small-Screen\7f2354
+Node: Help\7f4100
+Node: Help-P\7f5127
+Node: Help-^L\7f5986
+Node: Help-M\7f8861
+Node: Help-FOO\7f14838
+Node: Help-Adv\7f15574
+Node: Help-Cross\7f18246
+Node: Help-Q\7f18889
+Node: Advanced Info\7f19513
+Node: Expert\7f20488
+Node: Add\7f22999
+Node: Menus\7f26356
+Node: Cross-refs\7f29227
+Node: Tags\7f29926
+Node: Checking\7f31225
+Node: Emacs Info Variables\7f32175
+Node: Creating an Info File\7f33161

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

diff --git a/info/internals.info b/info/internals.info
index 028eea0..5ac1c97 100644 (file)
--- a/info/internals.info
+++ b/info/internals.info
@@ -1,4 +1,4 @@
-This is ../info/internals.info, produced by makeinfo version 4.0 from
+This is ../info/internals.info, produced by makeinfo version 4.6 from

 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -7,8 +7,9 @@ START-INFO-DIR-ENTRY
 END-INFO-DIR-ENTRY
 
    Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
 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.
+Microsystems.  Copyright (C) 1994 - 1998, 2002, 2003 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
 
    Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are

@@ -39,161 +40,157 @@ Foundation instead of in the original English.
 
 \1f
 Indirect:
 
 \1f
 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
+internals.info-1: 1789
+internals.info-2: 301402

 \1f
 Tag Table:
 (Indirect)
 \1f
 Tag Table:
 (Indirect)

-Node: Top\7f1776
-Node: A History of Emacs\7f7052
-Node: Through Version 18\7f8577
-Node: Lucid Emacs\7f11998
-Node: GNU Emacs 19\7f16042
-Node: GNU Emacs 20\7f18225
-Node: XEmacs\7f18652
-Node: XEmacs From the Outside\7f25764
-Node: The Lisp Language\7f27531
-Node: XEmacs From the Perspective of Building\7f37074
-Node: XEmacs From the Inside\7f43199
-Node: The XEmacs Object System (Abstractly Speaking)\7f51581
-Node: How Lisp Objects Are Represented in C\7f65667
-Node: Rules When Writing New C Code\7f70344
-Node: General Coding Rules\7f71207
-Node: Writing Lisp Primitives\7f76979
-Node: Writing Good Comments\7f88141
-Node: Adding Global Lisp Variables\7f91680
-Node: Proper Use of Unsigned Types\7f95329
-Node: Coding for Mule\7f96579
-Node: Character-Related Data Types\7f97558
-Node: Working With Character and Byte Positions\7f100531
-Node: Conversion to and from External Data\7f104296
-Node: General Guidelines for Writing Mule-Aware Code\7f110437
-Node: An Example of Mule-Aware Code\7f113125
-Node: Techniques for XEmacs Developers\7f115106
-Node: A Summary of the Various XEmacs Modules\7f123053
-Node: Low-Level Modules\7f123873
-Node: Basic Lisp Modules\7f131286
-Node: Modules for Standard Editing Operations\7f137880
-Node: Editor-Level Control Flow Modules\7f143768
-Node: Modules for the Basic Displayable Lisp Objects\7f147279
-Node: Modules for other Display-Related Lisp Objects\7f150232
-Node: Modules for the Redisplay Mechanism\7f151573
-Node: Modules for Interfacing with the File System\7f153945
-Node: Modules for Other Aspects of the Lisp Interpreter and Object System\7f157643
-Node: Modules for Interfacing with the Operating System\7f163096
-Node: Modules for Interfacing with X Windows\7f170652
-Node: Modules for Internationalization\7f174135
-Node: Allocation of Objects in XEmacs Lisp\7f176772
-Node: Introduction to Allocation\7f177293
-Node: Garbage Collection\7f180934
-Node: GCPROing\7f182090
-Node: Garbage Collection - Step by Step\7f189094
-Node: Invocation\7f189486
-Node: garbage_collect_1\7f192457
-Node: mark_object\7f201939
-Node: gc_sweep\7f203751
-Node: sweep_lcrecords_1\7f208814
-Node: compact_string_chars\7f209809
-Node: sweep_strings\7f211989
-Node: sweep_bit_vectors_1\7f212954
-Node: Integers and Characters\7f213630
-Node: Allocation from Frob Blocks\7f214382
-Node: lrecords\7f215986
-Node: Low-level allocation\7f228212
-Node: Cons\7f232319
-Node: Vector\7f233045
-Node: Bit Vector\7f233622
-Node: Symbol\7f234115
-Node: Marker\7f234469
-Node: String\7f235024
-Node: Compiled Function\7f238637
-Node: Dumping\7f238806
-Node: Overview\7f241027
-Node: Data descriptions\7f241581
-Node: Dumping phase\7f243586
-Node: Object inventory\7f243989
-Node: Address allocation\7f246903
-Node: The header\7f248292
-Node: Data dumping\7f248737
-Node: Pointers dumping\7f249398
-Node: Reloading phase\7f250788
-Node: Remaining issues\7f252342
-Node: Events and the Event Loop\7f253303
-Node: Introduction to Events\7f253753
-Node: Main Loop\7f255668
-Node: Specifics of the Event Gathering Mechanism\7f259243
-Node: Specifics About the Emacs Event\7f271696
-Node: The Event Stream Callback Routines\7f271951
-Node: Other Event Loop Functions\7f272196
-Node: Converting Events\7f273336
-Node: Dispatching Events; The Command Builder\7f273945
-Node: Evaluation; Stack Frames; Bindings\7f274180
-Node: Evaluation\7f274522
-Node: Dynamic Binding; The specbinding Stack; Unwind-Protects\7f281034
-Node: Simple Special Forms\7f283418
-Node: Catch and Throw\7f284201
-Node: Symbols and Variables\7f286776
-Node: Introduction to Symbols\7f287040
-Node: Obarrays\7f288078
-Node: Symbol Values\7f291611
-Node: Buffers and Textual Representation\7f293899
-Node: Introduction to Buffers\7f294557
-Node: The Text in a Buffer\7f297220
-Node: Buffer Lists\7f304370
-Node: Markers and Extents\7f306321
-Node: Bufbytes and Emchars\7f308586
-Node: The Buffer Object\7f308801
-Node: MULE Character Sets and Encodings\7f312281
-Node: Character Sets\7f313343
-Node: Encodings\7f316786
-Node: Japanese EUC (Extended Unix Code)\7f317853
-Node: JIS7\7f318667
-Node: Internal Mule Encodings\7f320017
-Node: Internal String Encoding\7f321847
-Node: Internal Character Encoding\7f323960
-Node: CCL\7f325684
-Node: The Lisp Reader and Compiler\7f332437
-Node: Lstreams\7f332650
-Node: Creating an Lstream\7f333681
-Node: Lstream Types\7f334891
-Node: Lstream Functions\7f335143
-Node: Lstream Methods\7f338709
-Node: Consoles; Devices; Frames; Windows\7f341851
-Node: Introduction to Consoles; Devices; Frames; Windows\7f342166
-Node: Point\7f344656
-Node: Window Hierarchy\7f345935
-Node: The Window Object\7f350387
-Node: The Redisplay Mechanism\7f353824
-Node: Critical Redisplay Sections\7f354616
-Node: Line Start Cache\7f355571
-Node: Redisplay Piece by Piece\7f358807
-Node: Extents\7f360844
-Node: Introduction to Extents\7f361378
-Node: Extent Ordering\7f362504
-Node: Format of the Extent Info\7f363745
-Node: Zero-Length Extents\7f365632
-Node: Mathematics of Extent Ordering\7f367032
-Node: Extent Fragments\7f371789
-Node: Faces\7f372875
-Node: Glyphs\7f372991
-Node: Specifiers\7f379624
-Node: Menus\7f379753
-Node: Subprocesses\7f382011
-Node: Interface to the X Window System\7f383997
-Node: Lucid Widget Library\7f384278
-Node: Generic Widget Interface\7f385569
-Node: Scrollbars\7f389128
-Node: Menubars\7f389271
-Node: Checkboxes and Radio Buttons\7f389414
-Node: Progress Bars\7f389600
-Node: Tab Controls\7f389760
-Node: Index\7f389881
+Node: Top\7f1789
+Node: A History of Emacs\7f7157
+Node: Through Version 18\7f8679
+Node: Lucid Emacs\7f12097
+Node: GNU Emacs 19\7f16138
+Node: GNU Emacs 20\7f18317
+Node: XEmacs\7f18741
+Node: XEmacs From the Outside\7f25850
+Node: The Lisp Language\7f27614
+Node: XEmacs From the Perspective of Building\7f37154
+Node: XEmacs From the Inside\7f43276
+Node: The XEmacs Object System (Abstractly Speaking)\7f51650
+Node: How Lisp Objects Are Represented in C\7f65733
+Node: Rules When Writing New C Code\7f71819
+Node: A Reader's Guide to XEmacs Coding Conventions\7f72715
+Node: General Coding Rules\7f77555
+Node: Writing Lisp Primitives\7f83378
+Node: Writing Good Comments\7f94538
+Node: Adding Global Lisp Variables\7f98074
+Node: Proper Use of Unsigned Types\7f102002
+Node: Coding for Mule\7f103249
+Node: Character-Related Data Types\7f104225
+Node: Working With Character and Byte Positions\7f107195
+Node: Conversion to and from External Data\7f110957
+Node: General Guidelines for Writing Mule-Aware Code\7f117095
+Node: An Example of Mule-Aware Code\7f119780
+Node: Techniques for XEmacs Developers\7f121758
+Node: Regression Testing XEmacs\7f130591
+Node: A Summary of the Various XEmacs Modules\7f135037
+Node: Low-Level Modules\7f135885
+Node: Basic Lisp Modules\7f143298
+Node: Modules for Standard Editing Operations\7f149892
+Node: Editor-Level Control Flow Modules\7f155780
+Node: Modules for the Basic Displayable Lisp Objects\7f159291
+Node: Modules for other Display-Related Lisp Objects\7f162244
+Node: Modules for the Redisplay Mechanism\7f163919
+Node: Modules for Interfacing with the File System\7f166291
+Node: Modules for Other Aspects of the Lisp Interpreter and Object System\7f169989
+Node: Modules for Interfacing with the Operating System\7f176696
+Node: Modules for Interfacing with X Windows\7f184252
+Node: Modules for Internationalization\7f187735
+Node: Modules for Regression Testing\7f190413
+Node: Allocation of Objects in XEmacs Lisp\7f191113
+Node: Introduction to Allocation\7f191634
+Node: Garbage Collection\7f195272
+Node: GCPROing\7f196426
+Node: Garbage Collection - Step by Step\7f203584
+Node: Invocation\7f203976
+Node: garbage_collect_1\7f206944
+Node: mark_object\7f216423
+Node: gc_sweep\7f218232
+Node: sweep_lcrecords_1\7f223293
+Node: compact_string_chars\7f224285
+Node: sweep_strings\7f226462
+Node: sweep_bit_vectors_1\7f227424
+Node: Integers and Characters\7f228097
+Node: Allocation from Frob Blocks\7f228846
+Node: lrecords\7f230447
+Node: Low-level allocation\7f242670
+Node: Cons\7f246774
+Node: Vector\7f247497
+Node: Bit Vector\7f248072
+Node: Symbol\7f248562
+Node: Marker\7f248913
+Node: String\7f249465
+Node: Compiled Function\7f253074
+Node: Dumping\7f253240
+Node: Overview\7f255458
+Node: Data descriptions\7f256009
+Node: Dumping phase\7f258011
+Node: Object inventory\7f258411
+Node: Address allocation\7f261322
+Node: The header\7f262708
+Node: Data dumping\7f263150
+Node: Pointers dumping\7f263808
+Node: Reloading phase\7f265195
+Node: Remaining issues\7f266731
+Node: Events and the Event Loop\7f267689
+Node: Introduction to Events\7f268139
+Node: Main Loop\7f270051
+Node: Specifics of the Event Gathering Mechanism\7f273623
+Node: Specifics About the Emacs Event\7f286073
+Node: The Event Stream Callback Routines\7f286328
+Node: Other Event Loop Functions\7f286573
+Node: Converting Events\7f287710
+Node: Dispatching Events; The Command Builder\7f288316
+Node: Evaluation; Stack Frames; Bindings\7f288548
+Node: Evaluation\7f288890
+Node: Dynamic Binding; The specbinding Stack; Unwind-Protects\7f295399
+Node: Simple Special Forms\7f297783
+Node: Catch and Throw\7f298563
+Node: Symbols and Variables\7f301138
+Node: Introduction to Symbols\7f301402
+Node: Obarrays\7f302437
+Node: Symbol Values\7f305967
+Node: Buffers and Textual Representation\7f308252
+Node: Introduction to Buffers\7f308910
+Node: The Text in a Buffer\7f311570
+Node: Buffer Lists\7f318716
+Node: Markers and Extents\7f320664
+Node: Bufbytes and Emchars\7f322926
+Node: The Buffer Object\7f323138
+Node: MULE Character Sets and Encodings\7f326613
+Node: Character Sets\7f327672
+Node: Encodings\7f331112
+Node: Japanese EUC (Extended Unix Code)\7f332176
+Node: JIS7\7f332987
+Node: Internal Mule Encodings\7f334334
+Node: Internal String Encoding\7f336162
+Node: Internal Character Encoding\7f338273
+Node: CCL\7f339994
+Node: The Lisp Reader and Compiler\7f346747
+Node: Lstreams\7f346957
+Node: Creating an Lstream\7f347985
+Node: Lstream Types\7f349192
+Node: Lstream Functions\7f349445
+Node: Lstream Methods\7f353011
+Node: Consoles; Devices; Frames; Windows\7f356153
+Node: Introduction to Consoles; Devices; Frames; Windows\7f356468
+Node: Point\7f358955
+Node: Window Hierarchy\7f360231
+Node: The Window Object\7f364680
+Node: The Redisplay Mechanism\7f368114
+Node: Critical Redisplay Sections\7f368903
+Node: Line Start Cache\7f369855
+Node: Redisplay Piece by Piece\7f373088
+Node: Extents\7f375122
+Node: Introduction to Extents\7f375656
+Node: Extent Ordering\7f376779
+Node: Format of the Extent Info\7f378017
+Node: Zero-Length Extents\7f379901
+Node: Mathematics of Extent Ordering\7f381297
+Node: Extent Fragments\7f386052
+Node: Faces\7f387135
+Node: Glyphs\7f387248
+Node: Specifiers\7f393869
+Node: Menus\7f393995
+Node: Subprocesses\7f396250
+Node: Interface to the X Window System\7f398233
+Node: Lucid Widget Library\7f398511
+Node: Generic Widget Interface\7f399799
+Node: Scrollbars\7f403355
+Node: Menubars\7f403498
+Node: Checkboxes and Radio Buttons\7f403641
+Node: Progress Bars\7f403827
+Node: Tab Controls\7f403987
+Node: Index\7f404108

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

diff --git a/info/internals.info-1 b/info/internals.info-1
index 7a33f6b..06a85c5 100644 (file)
--- a/info/internals.info-1
+++ b/info/internals.info-1
@@ -1,4 +1,4 @@
-This is ../info/internals.info, produced by makeinfo version 4.0 from
+This is ../info/internals.info, produced by makeinfo version 4.6 from

 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -7,8 +7,9 @@ START-INFO-DIR-ENTRY
 END-INFO-DIR-ENTRY
 
    Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
 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.
+Microsystems.  Copyright (C) 1994 - 1998, 2002, 2003 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
 
    Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are

@@ -53,6 +54,7 @@ File: internals.info,  Node: Top,  Next: A History of Emacs,  Prev: (dir),  Up:
 * The XEmacs Object System (Abstractly Speaking)::
 * How Lisp Objects Are Represented in C::
 * Rules When Writing New C Code::
 * The XEmacs Object System (Abstractly Speaking)::
 * How Lisp Objects Are Represented in C::
 * Rules When Writing New C Code::

+* Regression Testing XEmacs::

 * A Summary of the Various XEmacs Modules::
 * Allocation of Objects in XEmacs Lisp::
 * Dumping::
 * A Summary of the Various XEmacs Modules::
 * Allocation of Objects in XEmacs Lisp::
 * Dumping::

@@ -101,6 +103,8 @@ Coding for Mule
 * General Guidelines for Writing Mule-Aware Code::
 * An Example of Mule-Aware Code::
 
 * General Guidelines for Writing Mule-Aware Code::
 * An Example of Mule-Aware Code::
 

+Regression Testing XEmacs
+

 A Summary of the Various XEmacs Modules
 
 * Low-Level Modules::
 A Summary of the Various XEmacs Modules
 
 * Low-Level Modules::

@@ -115,6 +119,7 @@ A Summary of the Various XEmacs Modules
 * Modules for Interfacing with the Operating System::
 * Modules for Interfacing with X Windows::
 * Modules for Internationalization::
 * Modules for Interfacing with the Operating System::
 * Modules for Interfacing with X Windows::
 * Modules for Internationalization::

+* Modules for Regression Testing::

 
 Allocation of Objects in XEmacs Lisp
 
 
 Allocation of Objects in XEmacs Lisp
 

@@ -245,7 +250,7 @@ File: internals.info,  Node: A History of Emacs,  Next: XEmacs From the Outside,
 A History of Emacs
 ******************
 
 A History of Emacs
 ******************
 

-   XEmacs is a powerful, customizable text editor and development
+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
 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

@@ -276,8 +281,8 @@ File: internals.info,  Node: Through Version 18,  Next: Lucid Emacs,  Up: A Hist
 Through Version 18
 ==================
 
 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:
+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
 
    * 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

@@ -388,7 +393,7 @@ File: internals.info,  Node: Lucid Emacs,  Next: GNU Emacs 19,  Prev: Through Ve
 Lucid Emacs
 ===========
 
 Lucid Emacs
 ===========
 

-   Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of
+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
 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

@@ -501,11 +506,11 @@ File: internals.info,  Node: GNU Emacs 19,  Next: GNU Emacs 20,  Prev: Lucid Ema
 GNU Emacs 19
 ============
 
 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
+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.8 (beta) released May 27, 1993.
 

@@ -575,7 +580,7 @@ File: internals.info,  Node: GNU Emacs 20,  Next: XEmacs,  Prev: GNU Emacs 19,
 GNU Emacs 20
 ============
 
 GNU Emacs 20
 ============
 

-   On February 2, 1997 work began on GNU Emacs to integrate Mule.  The
+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
 first release was made in September of that year.
 
    A timeline for Emacs 20 is

@@ -592,7 +597,7 @@ File: internals.info,  Node: XEmacs,  Prev: GNU Emacs 20,  Up: A History of Emac
 XEmacs
 ======
 
 XEmacs
 ======
 

-   Around the time that Lucid was developing Energize, Sun Microsystems
+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
 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

@@ -798,7 +803,7 @@ File: internals.info,  Node: XEmacs From the Outside,  Next: The Lisp Language,
 XEmacs From the Outside
 ***********************
 
 XEmacs From the Outside
 ***********************
 

-   XEmacs appears to the outside world as an editor, but it is really a
+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.
 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.

@@ -836,7 +841,7 @@ File: internals.info,  Node: The Lisp Language,  Next: XEmacs From the Perspecti
 The Lisp Language
 *****************
 
 The Lisp Language
 *****************
 

-   Lisp is a general-purpose language that is higher-level than C and in
+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
 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

@@ -1027,7 +1032,7 @@ File: internals.info,  Node: XEmacs From the Perspective of Building,  Next: XEm
 XEmacs From the Perspective of Building
 ***************************************
 
 XEmacs From the Perspective of Building
 ***************************************
 

-   The heart of XEmacs is the Lisp environment, which is written in C.
+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
 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

@@ -1136,7 +1141,7 @@ File: internals.info,  Node: XEmacs From the Inside,  Next: The XEmacs Object Sy
 XEmacs From the Inside
 **********************
 
 XEmacs From the Inside
 **********************
 

-   Internally, XEmacs is quite complex, and can be very confusing.  To
+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
 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

@@ -1176,14 +1181,14 @@ always triggered by the event loop.  For example:
      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
      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.
+     make sure 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
 
    * The Lisp engine is responsible for executing the Lisp code in
      which most user commands are written.  It is entered through a

@@ -1282,3 +1287,5490 @@ 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.
 
 of obscure and unwanted interactions occurring than if they were to
 change the C code.
 

+\1f
+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.
+
+\1f
+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).  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'.
+
+   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 _static_ type
+checking.  Places where a `Lisp_Object' is mistakenly passed to a
+routine expecting an `int' (or vice-versa), or a check is written `if
+(foo)' (instead of `if (!NILP (foo))', will be flagged as errors.  None
+of these lead to the expected results!  `Qnil' is not represented as 0
+(so `if (foo)' will *ALWAYS* be true for a `Lisp_Object'), and the
+representation of an integer as a `Lisp_Object' is not just the
+integer's numeric value, but usually 2x the integer +/- 1.)
+
+   There used to be a claim that the union type simplified debugging.
+There may have been a grain of truth to this pre-19.8, when there was no
+`lrecord' type and all objects had a separate type appearing in the
+tag.  Nowadays, however, there is no debugging gain, and in fact
+frequent debugging *_loss_*, since many debuggers don't handle unions
+very well, and usually there is no way to directly specify a union from
+a debugging prompt.
+
+   Furthermore, release builds should *_not_* be done with union type
+because (a) you may get less efficiency, with compilers that can't
+figure out how to optimize the union into a machine word; (b) even
+worse, the union type often triggers miscompilation, especially when
+combined with Mule and error-checking.  This has been the case at
+various times when using GCC and MS VC, at least with `--pdump'.
+Therefore, be warned!
+
+   As of 2002 4Q, miscompilation is known to happen with current
+versions of *Microsoft VC++* and *GCC in combination with Mule, pdump,
+and KKCC* (no error checking).
+
+   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.
+
+\1f
+File: internals.info,  Node: Rules When Writing New C Code,  Next: Regression Testing XEmacs,  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:
+
+* A Reader's Guide to XEmacs Coding Conventions::
+* 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::
+
+\1f
+File: internals.info,  Node: A Reader's Guide to XEmacs Coding Conventions,  Next: General Coding Rules,  Up: Rules When Writing New C Code
+
+A Reader's Guide to XEmacs Coding Conventions
+=============================================
+
+Of course the low-level implementation language of XEmacs is C, but much
+of that uses the Lisp engine to do its work.  However, because the code
+is "inside" of the protective containment shell around the "reactor
+core," you'll see lots of complex "plumbing" needed to do the work and
+"safety mechanisms," whose failure results in a meltdown.  This section
+provides a quick overview (or review) of the various components of the
+implementation of Lisp objects.
+
+   Two typographic conventions help to identify C objects that implement
+Lisp objects.  The first is that capitalized identifiers, especially
+beginning with the letters `Q', `V', `F', and `S', for C variables and
+functions, and C macros with beginning with the letter `X', are used to
+implement Lisp.  The second is that where Lisp uses the hyphen `-' in
+symbol names, the corresponding C identifiers use the underscore `_'.
+Of course, since XEmacs Lisp contains interfaces to many external
+libraries, those external names will follow the coding conventions
+their authors chose, and may overlap the "XEmacs name space."  However
+these cases are usually pretty obvious.
+
+   All Lisp objects are handled indirectly.  The `Lisp_Object' type is
+usually a pointer to a structure, except for a very small number of
+types with immediate representations (currently characters and
+integers).  However, these types cannot be directly operated on in C
+code, either, so they can also be considered indirect.  Types that do
+not have an immediate representation always have a C typedef
+`Lisp_TYPE' for a corresponding structure.
+
+   In older code, it was common practice to pass around pointers to
+`Lisp_TYPE', but this is now deprecated in favor of using `Lisp_Object'
+for all function arguments and return values that are Lisp objects.
+The `XTYPE' macro is used to extract the pointer and cast it to
+`(Lisp_TYPE *)' for the desired type.
+
+   *Convention*: macros whose names begin with `X' operate on
+`Lisp_Object's and do no type-checking.  Many such macros are type
+extractors, but others implement Lisp operations in C (_e.g._, `XCAR'
+implements the Lisp `car' function).  These are unsafe, and must only
+be used where types of all data have already been checked.  Such macros
+are only applied to `Lisp_Object's.  In internal implementations where
+the pointer has already been converted, the structure is operated on
+directly using the C `->' member access operator.
+
+   The `TYPEP', `CHECK_TYPE', and `CONCHECK_TYPE' macros are used to
+test types.  The first returns a Boolean value, and the latter signal
+errors.  (The `CONCHECK' variety allows execution to be CONtinued under
+some circumstances, thus the name.)  Functions which expect to be
+passed user data invariably call `CHECK' macros on arguments.
+
+   There are many types of specialized Lisp objects implemented in C,
+but the most pervasive type is the "symbol".  Symbols are used as
+identifiers, variables, and functions.
+
+   *Convention*: Global variables whose names begin with `Q' are
+constants whose value is a symbol.  The name of the variable should be
+derived from the name of the symbol using the same rules as for Lisp
+primitives.  Such variables allow the C code to check whether a
+particular `Lisp_Object' is equal to a given symbol.  Symbols are Lisp
+objects, so these variables may be passed to Lisp primitives.  (An
+alternative to the use of `Q...' variables is to call the `intern'
+function at initialization in the `vars_of_MODULE' function, which is
+hardly less efficient.)
+
+   *Convention*: 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 no others do
+(not even integer and boolean variables that have Lisp equivalents).
+Most of the time, these variables have equivalents in Lisp, which are
+defined via the `DEFVAR' family of macros, but some don't.  Since the
+variable's value is a `Lisp_Object', it can be passed to Lisp
+primitives.
+
+   The implementation of Lisp primitives is more complex.
+*Convention*: Global variables with names beginning with `S' contain a
+structure that allows the Lisp engine to identify and call a C
+function.  In modern versions of XEmacs, these identifiers are almost
+always completely hidden in the `DEFUN' and `SUBR' macros, but you will
+encounter them if you look at very old versions of XEmacs or at GNU
+Emacs.  *Convention*: Functions with names beginning with `F' implement
+Lisp primitives.  Of course all their arguments and their return values
+must be Lisp_Objects.  (This is hidden in the `DEFUN' macro.)
+
+\1f
+File: internals.info,  Node: General Coding Rules,  Next: Writing Lisp Primitives,  Prev: A Reader's Guide to XEmacs Coding Conventions,  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.
+
+\1f
+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.
+
+\1f
+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.
+`####'.
+
+\1f
+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 file `general-slots.h'.  The "-slots" suffix indicates that this
+is a file that is included multiple times in `general.c'.  Redefinition
+of preprocessor macros allows the effects to be different in each
+context, so this is actually more convenient and less error-prone than
+doing it in your module.
+
+   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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+File: internals.info,  Node: Working With Character and Byte Positions,  Next: Conversion to and from External Data,  Prev: Character-Related Data Types,  Up: Coding for Mule
+
+Working With Character and Byte Positions
+-----------------------------------------
+
+Now that we have defined the basic character-related types, we can look
+at the macros and functions designed for work with them and for
+conversion between them.  Most of these macros are defined in
+`buffer.h', and we don't discuss all of them here, but only the most
+important ones.  Examining the existing code is the best way to learn
+about them.
+
+`MAX_EMCHAR_LEN'
+     This preprocessor constant is the maximum number of buffer bytes 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);
+
+\1f
+File: internals.info,  Node: Conversion to and from External Data,  Next: General Guidelines for Writing Mule-Aware Code,  Prev: Working With Character and Byte Positions,  Up: Coding for Mule
+
+Conversion to and from External Data
+------------------------------------
+
+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.
+
+\1f
+File: internals.info,  Node: General Guidelines for Writing Mule-Aware Code,  Next: An Example of Mule-Aware Code,  Prev: Conversion to and from External Data,  Up: Coding for Mule
+
+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.
+
+\1f
+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.
+
+\1f
+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.  In many cases you can localize the
+problem (because a particular new feature or even a single patch
+elicited it).  Don't hesitate to use brute force techniques like a
+global counter incremented at strategic places, especially in
+combination with other performance indications (_e.g._, degree of
+buffer fragmentation into extents).
+
+   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.  It was suggested that "maybe moving
+     some of the syntax highlighting capabilities into C would make a
+     difference."  Wrong idea, I think.  When processing one large file
+     a particular low-level routine was being called 40 _million_ times
+     simply for _one_ call to `newline-and-indent'.  Syntax
+     highlighting needs to be rewritten to use a reliable, fast parser,
+     then to trust the pre-parsed structure, and only do
+     re-highlighting locally to a text change.  Modern machines are
+     fast enough to implement such parsers in Lisp; but no machine will
+     ever be fast enough to deal with quadratic (or worse) algorithms!
+
+   * 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 --use-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'
+
+\1f
+File: internals.info,  Node: Regression Testing XEmacs,  Next: A Summary of the Various XEmacs Modules,  Prev: Rules When Writing New C Code,  Up: Top
+
+Regression Testing XEmacs
+*************************
+
+The source directory `tests/automated' contains XEmacs' automated test
+suite.  The usual way of running all the tests is running `make check'
+from the top-level source directory.
+
+   The test suite is unfinished and it's still lacking some essential
+features.  It is nevertheless recommended that you run the tests to
+confirm that XEmacs behaves correctly.
+
+   If you want to run a specific test case, you can do it from the
+command-line like this:
+
+     $ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE
+
+   If something goes wrong, you can run the test suite interactively by
+loading `test-harness.el' into a running XEmacs and typing `M-x
+test-emacs-test-file RET <filename> RET'.  You will see a log of passed
+and failed tests, which should allow you to investigate the source of
+the error and ultimately fix the bug.
+
+   Adding a new test file is trivial: just create a new file here and it
+will be run.  There is no need to byte-compile any of the files in this
+directory--the test-harness will take care of any necessary
+byte-compilation.
+
+   Look at the existing test cases for the examples of coding test
+cases.  It all boils down to your imagination and judicious use of the
+macros `Assert', `Check-Error', `Check-Error-Message', and
+`Check-Message'.
+
+   Here's a simple example checking case-sensitive and case-insensitive
+comparisons from `case-tests.el'.
+
+     (with-temp-buffer
+       (insert "Test Buffer")
+       (let ((case-fold-search t))
+         (goto-char (point-min))
+         (Assert (eq (search-forward "test buffer" nil t) 12))
+         (goto-char (point-min))
+         (Assert (eq (search-forward "Test buffer" nil t) 12))
+         (goto-char (point-min))
+         (Assert (eq (search-forward "Test Buffer" nil t) 12))
+     
+         (setq case-fold-search nil)
+         (goto-char (point-min))
+         (Assert (not (search-forward "test buffer" nil t)))
+         (goto-char (point-min))
+         (Assert (not (search-forward "Test buffer" nil t)))
+         (goto-char (point-min))
+         (Assert (eq (search-forward "Test Buffer" nil t) 12))))
+
+   This example could be inserted in a file in `tests/automated', and
+it would be a complete test, automatically executed when you run `make
+check' after building XEmacs.  More complex tests may require
+substantial temporary scaffolding to create the environment that elicits
+the bugs, but the top-level Makefile and `test-harness.el' handle the
+running and collection of results from the `Assert', `Check-Error',
+`Check-Error-Message', and `Check-Message' macros.
+
+   In general, you should avoid using functionality from packages in
+your tests, because you can't be sure that everyone will have the
+required package.  However, if you've got a test that works, by all
+means add it.  Simply wrap the test in an appropriate test, add a
+notice that the test was skipped, and update the `skipped-test-reasons'
+hashtable.  Here's an example from `syntax-tests.el':
+
+     ;; Test forward-comment at buffer boundaries
+     (with-temp-buffer
+     
+       ;; try to use exactly what you need: featurep, boundp, fboundp
+       (if (not (fboundp 'c-mode))
+     
+           ;; We should provide a standard function for this boilerplate,
+           ;; probably called `Skip-Test' -- check for that API with C-h f
+           (let* ((reason "c-mode unavailable")
+            (count (gethash reason skipped-test-reasons)))
+       (puthash reason (if (null count) 1 (1+ count))
+                skipped-test-reasons)
+       (Print-Skip "comment and parse-partial-sexp tests" reason))
+     
+         ;; and here's the test code
+         (c-mode)
+         (insert "// comment\n")
+         (forward-comment -2)
+         (Assert (eq (point) (point-min)))
+         (let ((point (point)))
+           (insert "/* comment */")
+           (goto-char point)
+           (forward-comment 2)
+           (Assert (eq (point) (point-max)))
+           (parse-partial-sexp point (point-max)))))
+
+   `Skip-Test' is intended for use with features that are normally
+present in typical configurations.  For truly optional features, or
+tests that apply to one of several alternative implementations (eg, to
+GTK widgets, but not Athena, Motif, MS Windows, or Carbon), simply
+silently omit the test.
+
+\1f
+File: internals.info,  Node: A Summary of the Various XEmacs Modules,  Next: Allocation of Objects in XEmacs Lisp,  Prev: Regression Testing XEmacs,  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::
+* Modules for Regression Testing::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+   As of 21.4.10, bugs introduced at the very end of the 21.2 series in
+the "syntax properties" code were fixed, and highlighting is acceptably
+quick again.  However, presumably more improvements are possible, and
+the places to look are probably here, in the defun-traversing code, and
+in `syntax.c', in the comment-traversing code.
+
+     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.
+
+\1f
+File: internals.info,  Node: Modules for the Redisplay Mechanism,  Next: Modules for Interfacing with the File System,  Prev: Modules for other Display-Related Lisp Objects,  Up: A Summary of the Various XEmacs Modules
+
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+   Syntax codes are implemented as bitfields in an int.  Bits 0-6
+contain the syntax code itself, bit 7 is a special prefix flag used for
+Lisp, and bits 16-23 contain comment syntax flags.  From the Lisp
+programmer's point of view, there are 11 flags: 2 styles X 2 characters
+X {start, end} flags for two-character comment delimiters, 2 style
+flags for one-character comment delimiters, and the prefix flag.
+
+   Internally, however, the characters used in multi-character
+delimiters will have non-comment-character syntax classes (_e.g._, the
+`/' in C's `/*' comment-start delimiter has "punctuation" (here meaning
+"operator-like") class in C modes).  Thus in a mixed comment style,
+such as C++'s `//' to end of line, is represented by giving `/' the
+"punctuation" class and the "style b first character of start sequence"
+and "style b second character of start sequence" flags.  The fact that
+class is _not_ punctuation allows the syntax scanner to recognize that
+this is a multi-character delimiter.  The `newline' character is given
+(single-character) "comment-end" _class_ and the "style b first
+character of end sequence" _flag_.  The "comment-end" class allows the
+scanner to determine that no second character is needed to terminate
+the comment.
+
+     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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: internals.info,  Node: Modules for Internationalization,  Next: Modules for Regression Testing,  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.
+
+\1f
+File: internals.info,  Node: Modules for Regression Testing,  Prev: Modules for Internationalization,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Regression Testing
+==============================
+
+     test-harness.el
+     base64-tests.el
+     byte-compiler-tests.el
+     case-tests.el
+     ccl-tests.el
+     c-tests.el
+     database-tests.el
+     extent-tests.el
+     hash-table-tests.el
+     lisp-tests.el
+     md5-tests.el
+     mule-tests.el
+     regexp-tests.el
+     symbol-tests.el
+     syntax-tests.el
+
+   `test-harness.el' defines the macros `Assert', `Check-Error',
+`Check-Error-Message', and `Check-Message'.  The other files are test
+files, testing various XEmacs modules.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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').
+
+\1f
+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.
+
+   If you don't understand whether to `GCPRO' in a particular instance,
+ask on the mailing lists.  A general hint is that `prog1' is the
+canonical example.
+
+   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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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,
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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".)
+
+\1f
+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.
+
+\1f
+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()'.
+
+\1f
+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.
+
+\1f
+File: internals.info,  Node: Compiled Function,  Prev: String,  Up: Allocation of Objects in XEmacs Lisp
+
+Compiled Function
+=================
+
+Not yet documented.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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()'.
+
+\1f
+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'
+
+\1f
+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
+===============================
+
+\1f
+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
+==================================
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+

diff --git a/info/internals.info-2 b/info/internals.info-2
index 805e7ef..41bd915 100644 (file)
--- a/info/internals.info-2
+++ b/info/internals.info-2
@@ -1,4 +1,4 @@
-This is ../info/internals.info, produced by makeinfo version 4.0 from
+This is ../info/internals.info, produced by makeinfo version 4.6 from

 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -7,8 +7,9 @@ START-INFO-DIR-ENTRY
 END-INFO-DIR-ENTRY
 
    Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
 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.
+Microsystems.  Copyright (C) 1994 - 1998, 2002, 2003 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
 
    Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are

@@ -38,1052 +39,2819 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-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:
+File: internals.info,  Node: Introduction to Symbols,  Next: Obarrays,  Up: Symbols and Variables

 
 

-`buffer'
-     Stores text like a string, but is optimized for insertion and
-     deletion and has certain other properties that can be set.
+Introduction to Symbols
+=======================

 
 

-`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.
+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.

 
 

-   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.)
+\1f
+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.

 
 

-   The read syntax
+\1f
+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'.

 
 

-     17297
+\1f
+File: internals.info,  Node: Buffers and Textual Representation,  Next: MULE Character Sets and Encodings,  Prev: Symbols and Variables,  Up: Top

 
 

-   converts to an integer whose value is 17297.
+Buffers and Textual Representation
+**********************************

 
 

-     1.983e-4
+* Menu:

 
 

-   converts to a float whose value is 1.983e-4, or .0001983.
+* 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.

 
 

-     ?b
+\1f
+File: internals.info,  Node: Introduction to Buffers,  Next: The Text in a Buffer,  Up: Buffers and Textual Representation

 
 

-   converts to a char that represents the lowercase letter b.
+Introduction to Buffers
+=======================

 
 

-     ?^[$(B#&^[(B
+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.)

 
 

-   (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.)
+\1f
+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.).

 
 

-     "foobar"
+\1f
+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'.
+
+\1f
+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.

 
 

-   converts to a string.
+\1f
+File: internals.info,  Node: Bufbytes and Emchars,  Next: The Buffer Object,  Prev: Markers and Extents,  Up: Buffers and Textual Representation

 
 

-     foobar
+Bufbytes and Emchars
+====================

 
 

-   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.
+Not yet documented.

 
 

-     (foo . bar)
+\1f
+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'.

 
 

-   converts to a cons cell containing the symbols `foo' and `bar'.
+\1f
+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.

 
 

-     (1 a 2.5)
+* Menu:

 
 

-   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).
+* Character Sets::
+* Encodings::
+* Internal Mule Encodings::
+* CCL::

 
 

-     [1 a 2.5]
+\1f
+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.

 
 

-   converts to a three-element vector containing the specified objects.
+\1f
+File: internals.info,  Node: Encodings,  Next: Internal Mule Encodings,  Prev: Character Sets,  Up: MULE Character Sets and Encodings

 
 

-     #[... ... ... ...]
+Encodings
+=========

 
 

-   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).
+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.

 
 

-     #*01110110
+   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.

 
 

-   converts to a bit-vector.
+   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").

 
 

-     #s(hash-table ... ...)
+   Here are descriptions of a couple of common encodings:

 
 

-   converts to a hash table (the actual contents are not shown).
+* Menu:

 
 

-     #s(range-table ... ...)
+* Japanese EUC (Extended Unix Code)::
+* JIS7::

 
 

-   converts to a range table (the actual contents are not shown).
+\1f
+File: internals.info,  Node: Japanese EUC (Extended Unix Code),  Next: JIS7,  Up: Encodings

 
 

-     #s(char-table ... ...)
+Japanese EUC (Extended Unix Code)
+---------------------------------

 
 

-   converts to a char table (the actual contents are not shown).
+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 the `#s()' syntax is the general syntax for structures,
-which are not really implemented in XEmacs Lisp but should be.
+   Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character
+charsets, while Japanese-JISX0208 is a 94x94-character charset.

 
 

-   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 encoding is as follows:

 
 

-   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.
+     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

 
 \1f
 
 \1f

-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
+File: internals.info,  Node: JIS7,  Prev: Japanese EUC (Extended Unix Code),  Up: Encodings
+
+JIS7
+----

 
 

-How Lisp Objects Are Represented in C
-*************************************
+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.

 
 

-   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:
+   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.

 
 

-      [ 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 ]
+   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
+     

      
      

-        <---------------------------------------------------------> <->
-                 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.
+     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.

 
 \1f
 
 \1f

-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
+File: internals.info,  Node: Internal Mule Encodings,  Next: CCL,  Prev: Encodings,  Up: MULE Character Sets and Encodings

 
 

-Rules When Writing New C Code
-*****************************
+Internal Mule Encodings
+=======================

 
 

-   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.
+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:
 
 
 * 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::
+* Internal String Encoding::
+* Internal Character Encoding::

 
 \1f
 
 \1f

-File: internals.info,  Node: General Coding Rules,  Next: Writing Lisp Primitives,  Up: Rules When Writing New C Code
+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.)

 
 

-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.
+\1f
+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.

 
 \1f
 
 \1f

-File: internals.info,  Node: Writing Lisp Primitives,  Next: Writing Good Comments,  Prev: General Coding Rules,  Up: Rules When Writing New C Code
+File: internals.info,  Node: CCL,  Prev: Internal Mule Encodings,  Up: MULE Character Sets and Encodings

 
 

-Writing Lisp Primitives
-=======================
+CCL
+===

 
 

-   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;
+     CCL PROGRAM SYNTAX:
+          CCL_PROGRAM := (CCL_MAIN_BLOCK
+                          [ CCL_EOF_BLOCK ])

      
      

-       val = Feval (XCAR (args));
+          CCL_MAIN_BLOCK := CCL_BLOCK
+          CCL_EOF_BLOCK := CCL_BLOCK

      
      

-       GCPRO1 (val);
+          CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...])
+          STATEMENT :=
+                  SET | IF | BRANCH | LOOP | REPEAT | BREAK
+                  | READ | WRITE

      
      

-       LIST_LOOP_3 (form, XCDR (args), tail)
-         Feval (form);
+          SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION)
+                 | INT-OR-CHAR

      
      

-       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.
+          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

 
 \1f
 
 \1f

-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: The Lisp Reader and Compiler,  Next: Lstreams,  Prev: MULE Character Sets and Encodings,  Up: Top
+
+The Lisp Reader and Compiler
+****************************
+
+Not yet documented.

 
 \1f
 
 \1f

-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: 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.
+
+\1f
+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.

 
 \1f
 
 \1f

-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
+File: internals.info,  Node: Lstream Types,  Next: Lstream Functions,  Prev: Creating an Lstream,  Up: Lstreams
+
+Lstream Types
+=============
+
+stdio
+
+filedesc

 
 

-Proper Use of Unsigned Types
-============================
+lisp-string

 
 

-   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
+fixed-buffer

 
 

-  1. When there's a reasonable possibility you will actually need all
-     32 or 64 bits to store the quantity.
+resizing-buffer

 
 

-  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.
+dynarr

 
 

-  3. In existing code that you don't want to modify because you don't
-     maintain it.
+lisp-buffer

 
 

-  4. In bit-field structures.
+print

 
 

-   Other reasonable uses of `unsigned int' and `unsigned long' are
-representing non-quantities - e.g. bit-oriented flags and such.
+decoding
+
+encoding
+
+\1f
+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.

 
 \1f
 
 \1f

-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
+File: internals.info,  Node: Lstream Methods,  Prev: Lstream Functions,  Up: Lstreams

 
 

-Coding for Mule
+Lstream Methods

 ===============
 
 ===============
 

-   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.
+ - 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'.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.)
+
+\1f
+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'.
+
+\1f
+File: internals.info,  Node: The Redisplay Mechanism,  Next: Extents,  Prev: Consoles; Devices; Frames; Windows,  Up: Top

 
 

-   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.
+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:
 
 
 * 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::
+* Critical Redisplay Sections::
+* Line Start Cache::
+* Redisplay Piece by Piece::

 
 \1f
 
 \1f

-File: internals.info,  Node: Character-Related Data Types,  Next: Working With Character and Byte Positions,  Up: Coding for Mule
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.

 
 

-Character-Related Data Types
+   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.)
+
+\1f
+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".
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: internals.info,  Node: Faces,  Next: Glyphs,  Prev: Extents,  Up: Top
+
+Faces
+*****
+
+Not yet documented.
+
+\1f
+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.
+
+\1f
+File: internals.info,  Node: Specifiers,  Next: Menus,  Prev: Glyphs,  Up: Top
+
+Specifiers
+**********
+
+Not yet documented.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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
+
+\1f
+File: internals.info,  Node: Scrollbars,  Next: Menubars,  Prev: Generic Widget Interface,  Up: Lucid Widget Library
+
+Scrollbars
+----------
+
+\1f
+File: internals.info,  Node: Menubars,  Next: Checkboxes and Radio Buttons,  Prev: Scrollbars,  Up: Lucid Widget Library
+
+Menubars
+--------
+
+\1f
+File: internals.info,  Node: Checkboxes and Radio Buttons,  Next: Progress Bars,  Prev: Menubars,  Up: Lucid Widget Library
+
+Checkboxes and Radio Buttons

 ----------------------------
 
 ----------------------------
 

-   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.
+\1f
+File: internals.info,  Node: Progress Bars,  Next: Tab Controls,  Prev: Checkboxes and Radio Buttons,  Up: Lucid Widget Library
+
+Progress Bars
+-------------
+
+\1f
+File: internals.info,  Node: Tab Controls,  Prev: Progress Bars,  Up: Lucid Widget Library
+
+Tab Controls
+------------
+
+\1f
+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 conventions:                    A Reader's Guide to XEmacs Coding Conventions.
+* coding for Mule:                       Coding for Mule.
+* coding rules, general:                 General Coding Rules.
+* coding rules, naming:                  A Reader's Guide to XEmacs Coding Conventions.
+* 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 regression testing:        Modules for Regression Testing.
+* 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.
+* reader's guide:                        A Reader's Guide to XEmacs Coding Conventions.
+* 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.
+* regression testing, modules for:       Modules for Regression Testing.
+* 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).
+* testing, regression:                   Regression Testing XEmacs.
+* 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 --git a/info/lispref.info b/info/lispref.info
index afa0020..774cfdb 100644 (file)
--- a/info/lispref.info
+++ b/info/lispref.info
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -52,868 +52,849 @@ Foundation instead of in the original English.
 \1f
 Indirect:
 lispref.info-1: 2366
 \1f
 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
+lispref.info-2: 299153
+lispref.info-3: 596434
+lispref.info-4: 894447
+lispref.info-5: 1194382
+lispref.info-6: 1492927
+lispref.info-7: 1792530
+lispref.info-8: 2092512
+lispref.info-9: 2304231

 \1f
 Tag Table:
 (Indirect)
 Node: Top\7f2366
 \1f
 Tag Table:
 (Indirect)
 Node: Top\7f2366

-Node: Copying\7f49116
-Node: Introduction\7f68274
-Node: Caveats\7f69865
-Node: Lisp History\7f71544
-Node: Conventions\7f72800
-Node: Some Terms\7f73615
-Node: nil and t\7f74336
-Node: Evaluation Notation\7f76013
-Node: Printing Notation\7f76926
-Node: Error Messages\7f77800
-Node: Buffer Text Notation\7f78241
-Node: Format of Descriptions\7f79116
-Node: A Sample Function Description\7f79970
-Node: A Sample Variable Description\7f83956
-Node: Acknowledgements\7f84864
-Node: Lisp Data Types\7f86842
-Node: Printed Representation\7f89397
-Node: Comments\7f91439
-Node: Primitive Types\7f92336
-Node: Programming Types\7f93995
-Node: Integer Type\7f95947
-Node: Floating Point Type\7f96984
-Node: Character Type\7f97603
-Node: Symbol Type\7f105507
-Node: Sequence Type\7f108202
-Node: Cons Cell Type\7f109721
-Node: Dotted Pair Notation\7f114205
-Node: Association List Type\7f116326
-Node: Array Type\7f117209
-Node: String Type\7f118675
-Node: Vector Type\7f121356
-Node: Bit Vector Type\7f122128
-Node: Function Type\7f122990
-Node: Macro Type\7f124103
-Node: Primitive Function Type\7f124800
-Node: Compiled-Function Type\7f126326
-Node: Autoload Type\7f126880
-Node: Char Table Type\7f127894
-Node: Hash Table Type\7f128068
-Node: Range Table Type\7f129223
-Node: Weak List Type\7f130076
-Node: Editing Types\7f130226
-Node: Buffer Type\7f131853
-Node: Marker Type\7f133880
-Node: Extent Type\7f134604
-Node: Window Type\7f135872
-Node: Frame Type\7f137283
-Node: Device Type\7f138078
-Node: Console Type\7f138904
-Node: Window Configuration Type\7f140105
-Node: Event Type\7f140803
-Node: Process Type\7f140967
-Node: Stream Type\7f142002
-Node: Keymap Type\7f143125
-Node: Syntax Table Type\7f143663
-Node: Display Table Type\7f144686
-Node: Database Type\7f145125
-Node: Charset Type\7f145291
-Node: Coding System Type\7f145455
-Node: ToolTalk Message Type\7f145639
-Node: ToolTalk Pattern Type\7f145838
-Node: Window-System Types\7f146010
-Node: Face Type\7f147156
-Node: Glyph Type\7f147287
-Node: Specifier Type\7f147443
-Node: Font Instance Type\7f147616
-Node: Color Instance Type\7f147806
-Node: Image Instance Type\7f148003
-Node: Toolbar Button Type\7f148201
-Node: Subwindow Type\7f148394
-Node: X Resource Type\7f148573
-Node: Type Predicates\7f148726
-Node: Equality Predicates\7f157855
-Node: Numbers\7f162666
-Node: Integer Basics\7f164121
-Node: Float Basics\7f166470
-Node: Predicates on Numbers\7f168212
-Node: Comparison of Numbers\7f169845
-Node: Numeric Conversions\7f173666
-Node: Arithmetic Operations\7f175132
-Node: Rounding Operations\7f181271
-Node: Bitwise Operations\7f182384
-Node: Math Functions\7f191430
-Node: Random Numbers\7f193963
-Node: Strings and Characters\7f195729
-Node: String Basics\7f197182
-Node: Predicates for Strings\7f199600
-Node: Creating Strings\7f200363
-Node: Predicates for Characters\7f205704
-Node: Character Codes\7f206775
-Node: Text Comparison\7f208195
-Node: String Conversion\7f211640
-Node: Modifying Strings\7f215310
-Node: String Properties\7f215951
-Node: Formatting Strings\7f216596
-Node: Character Case\7f226214
-Node: Case Tables\7f229768
-Node: Char Tables\7f233739
-Node: Char Table Types\7f235131
-Node: Working With Char Tables\7f236716
-Node: Lists\7f238733
-Node: Cons Cells\7f239856
-Node: Lists as Boxes\7f241192
-Node: List-related Predicates\7f243834
-Node: List Elements\7f245536
-Node: Building Lists\7f250565
-Node: Modifying Lists\7f256557
-Node: Setcar\7f257369
-Node: Setcdr\7f259800
-Node: Rearrangement\7f262321
-Node: Sets And Lists\7f267907
-Node: Association Lists\7f272135
-Ref: Association Lists-Footnote-1\7f281426
-Node: Property Lists\7f281631
-Node: Working With Normal Plists\7f283179
-Node: Working With Lax Plists\7f285516
-Node: Converting Plists To/From Alists\7f287796
-Node: Weak Lists\7f289144
-Node: Sequences Arrays Vectors\7f291307
-Node: Sequence Functions\7f293943
-Node: Arrays\7f297602
-Node: Array Functions\7f300666
-Node: Vectors\7f303199
-Node: Vector Functions\7f304697
-Node: Bit Vectors\7f307268
-Node: Bit Vector Functions\7f308113
-Node: Symbols\7f310412
-Node: Symbol Components\7f311461
-Node: Definitions\7f315644
-Node: Creating Symbols\7f317869
-Node: Symbol Properties\7f324903
-Node: Plists and Alists\7f326430
-Node: Object Plists\7f328179
-Node: Other Plists\7f330939
-Node: Evaluation\7f332738
-Node: Intro Eval\7f333543
-Ref: Intro Eval-Footnote-1\7f336896
-Node: Eval\7f337031
-Node: Forms\7f341450
-Node: Self-Evaluating Forms\7f342609
-Node: Symbol Forms\7f344122
-Node: Classifying Lists\7f345039
-Node: Function Indirection\7f345795
-Node: Function Forms\7f348894
-Node: Macro Forms\7f349891
-Node: Special Forms\7f351491
-Node: Autoloading\7f353800
-Node: Quoting\7f354298
-Node: Control Structures\7f355659
-Node: Sequencing\7f357279
-Node: Conditionals\7f360144
-Node: Combining Conditions\7f363567
-Node: Iteration\7f366837
-Node: Nonlocal Exits\7f368616
-Node: Catch and Throw\7f369318
-Node: Examples of Catch\7f373157
-Node: Errors\7f375176
-Node: Signaling Errors\7f376665
-Node: Processing of Errors\7f385412
-Node: Handling Errors\7f387691
-Node: Error Symbols\7f394932
-Node: Cleanups\7f398888
-Node: Variables\7f402666
-Node: Global Variables\7f404435
-Node: Constant Variables\7f405511
-Node: Local Variables\7f406137
-Node: Void Variables\7f411075
-Node: Defining Variables\7f414591
-Node: Accessing Variables\7f421755
-Node: Setting Variables\7f423180
-Node: Variable Scoping\7f427699
-Node: Scope\7f429298
-Node: Extent\7f430823
-Node: Impl of Scope\7f432302
-Node: Using Scoping\7f434265
-Node: Buffer-Local Variables\7f435787
-Node: Intro to Buffer-Local\7f436623
-Node: Creating Buffer-Local\7f439166
-Node: Default Value\7f445065
-Node: Variable Aliases\7f448208
-Node: Functions\7f450059
-Node: What Is a Function\7f451153
-Node: Lambda Expressions\7f455199
-Node: Lambda Components\7f456109
-Node: Simple Lambda\7f457941
-Node: Argument List\7f459598
-Node: Function Documentation\7f463326
-Node: Function Names\7f465268
-Node: Defining Functions\7f467841
-Node: Calling Functions\7f470881
-Node: Mapping Functions\7f474729
-Node: Anonymous Functions\7f477417
-Node: Function Cells\7f480662
-Node: Inline Functions\7f485480
-Node: Related Topics\7f487290
-Node: Macros\7f488343
-Node: Simple Macro\7f489627
-Node: Expansion\7f490362
-Node: Compiling Macros\7f493366
-Node: Defining Macros\7f495202
-Node: Backquote\7f496519
-Node: Problems with Macros\7f498916
-Node: Argument Evaluation\7f499611
-Node: Surprising Local Vars\7f502526
-Node: Eval During Expansion\7f504594
-Node: Repeated Expansion\7f506287
-Node: Customization\7f508203
-Node: Common Keywords\7f508672
-Node: Group Definitions\7f511517
-Node: Variable Definitions\7f513709
-Node: Customization Types\7f518699
-Node: Simple Types\7f520134
-Node: Composite Types\7f522291
-Node: Splicing into Lists\7f526981
-Node: Type Keywords\7f528816
-Node: Loading\7f532336
-Node: How Programs Do Loading\7f534011
-Node: Autoload\7f543137
-Node: Repeated Loading\7f549207
-Node: Named Features\7f551320
-Node: Unloading\7f557750
-Node: Hooks for Loading\7f559906
-Node: Byte Compilation\7f560623
-Node: Speed of Byte-Code\7f562616
-Node: Compilation Functions\7f563823
-Node: Docs and Compilation\7f570480
-Node: Dynamic Loading\7f573133
-Node: Eval During Compile\7f575497
-Node: Compiled-Function Objects\7f576762
-Node: Disassembly\7f581563
-Node: Different Behavior\7f588844
-Node: Debugging\7f590189
-Node: Debugger\7f591601
-Node: Error Debugging\7f592746
-Node: Infinite Loops\7f595499
-Node: Function Debugging\7f596743
-Node: Explicit Debug\7f599543
-Node: Using Debugger\7f600314
-Node: Debugger Commands\7f602176
-Node: Invoking the Debugger\7f606493
-Node: Internals of Debugger\7f610408
-Node: Syntax Errors\7f615295
-Node: Excess Open\7f616543
-Node: Excess Close\7f618418
-Node: Compilation Errors\7f619839
-Node: Edebug\7f621127
-Node: Using Edebug\7f623235
-Node: Instrumenting\7f625932
-Node: Edebug Execution Modes\7f629421
-Node: Jumping\7f632531
-Node: Edebug Misc\7f634874
-Node: Breakpoints\7f636263
-Node: Global Break Condition\7f639069
-Node: Embedded Breakpoints\7f640024
-Node: Trapping Errors\7f640979
-Node: Edebug Views\7f643055
-Node: Edebug Eval\7f645020
-Node: Eval List\7f646197
-Node: Reading in Edebug\7f649582
-Node: Printing in Edebug\7f650381
-Node: Tracing\7f652096
-Node: Coverage Testing\7f653984
-Node: The Outside Context\7f656025
-Node: Checking Whether to Stop\7f656974
-Node: Edebug Display Update\7f657621
-Node: Edebug Recursive Edit\7f659644
-Node: Instrumenting Macro Calls\7f661299
-Node: Specification List\7f663781
-Node: Backtracking\7f673192
-Node: Debugging Backquote\7f675130
-Node: Specification Examples\7f678836
-Node: Edebug Options\7f680903
-Node: Read and Print\7f686242
-Node: Streams Intro\7f687219
-Node: Input Streams\7f689237
-Node: Input Functions\7f694138
-Node: Output Streams\7f696198
-Node: Output Functions\7f700249
-Node: Output Variables\7f704549
-Node: Minibuffers\7f709350
-Node: Intro to Minibuffers\7f710502
-Node: Text from Minibuffer\7f712690
-Node: Object from Minibuffer\7f717784
-Node: Minibuffer History\7f721877
-Node: Completion\7f724856
-Node: Basic Completion\7f726831
-Node: Minibuffer Completion\7f731714
-Node: Completion Commands\7f735291
-Node: High-Level Completion\7f739948
-Node: Reading File Names\7f744697
-Node: Programmed Completion\7f748389
-Node: Yes-or-No Queries\7f750771
-Node: Multiple Queries\7f756508
-Node: Reading a Password\7f760575
-Node: Minibuffer Misc\7f761918
-Node: Command Loop\7f766798
-Node: Command Overview\7f768142
-Node: Defining Commands\7f771420
-Node: Using Interactive\7f772168
-Node: Interactive Codes\7f776941
-Node: Interactive Examples\7f782733
-Node: Interactive Call\7f784047
-Node: Command Loop Info\7f789462
-Node: Events\7f794441
-Node: Event Types\7f795902
-Node: Event Contents\7f797825
-Node: Event Predicates\7f802301
-Node: Accessing Mouse Event Positions\7f803619
-Node: Frame-Level Event Position Info\7f804318
-Node: Window-Level Event Position Info\7f805358
-Node: Event Text Position Info\7f807122
-Node: Event Glyph Position Info\7f809614
-Node: Event Toolbar Position Info\7f810937
-Node: Other Event Position Info\7f811608
-Node: Accessing Other Event Info\7f812017
-Node: Working With Events\7f813637
-Node: Converting Events\7f819638
-Node: Reading Input\7f823037
-Node: Key Sequence Input\7f824039
-Node: Reading One Event\7f826674
-Node: Dispatching an Event\7f829498
-Node: Quoted Character Input\7f829949
-Node: Peeking and Discarding\7f831297
-Node: Waiting\7f835201
-Node: Quitting\7f837515
-Node: Prefix Command Arguments\7f841923
-Node: Recursive Editing\7f847010
-Node: Disabling Commands\7f851805
-Node: Command History\7f853873
-Node: Keyboard Macros\7f855610
-Node: Keymaps\7f857827
-Node: Keymap Terminology\7f859404
-Node: Format of Keymaps\7f862333
-Node: Creating Keymaps\7f862744
-Node: Inheritance and Keymaps\7f864824
-Node: Key Sequences\7f867196
-Node: Prefix Keys\7f871992
-Node: Active Keymaps\7f875577
-Node: Key Lookup\7f884948
-Node: Functions for Key Lookup\7f890111
-Node: Changing Key Bindings\7f895812
-Node: Key Binding Commands\7f902974
-Node: Scanning Keymaps\7f905039
-Node: Other Keymap Functions\7f913608
-Node: Menus\7f914230
-Node: Menu Format\7f914822
-Node: Menubar Format\7f923468
-Node: Menubar\7f924093
-Node: Modifying Menus\7f927206
-Node: Menu Filters\7f932550
-Node: Pop-Up Menus\7f934446
-Node: Menu Accelerators\7f936774
-Node: Creating Menu Accelerators\7f937530
-Node: Keyboard Menu Traversal\7f938890
-Node: Menu Accelerator Functions\7f939617
-Node: Buffers Menu\7f942693
-Node: Dialog Boxes\7f943987
-Node: Dialog Box Format\7f944154
-Node: Dialog Box Functions\7f945579
-Node: Toolbar\7f945976
-Node: Toolbar Intro\7f946411
-Node: Creating Toolbar\7f948811
-Node: Toolbar Descriptor Format\7f949728
-Node: Specifying the Toolbar\7f954225
-Node: Other Toolbar Variables\7f957832
-Node: Gutter\7f962260
-Node: Gutter Intro\7f962849
-Node: Creating Gutter\7f964852
-Node: Gutter Descriptor Format\7f967739
-Node: Specifying a Gutter\7f972196
-Node: Other Gutter Variables\7f975731
-Node: Common Gutter Widgets\7f980118
-Node: Buffer Tabs\7f981110
-Node: Progress Bars\7f981251
-Node: Scrollbars\7f981396
-Node: Drag and Drop\7f981531
-Node: Supported Protocols\7f982607
-Node: OffiX DND\7f983110
-Node: CDE dt\7f984117
-Node: MSWindows OLE\7f984708
-Node: Loose ends\7f984879
-Node: Drop Interface\7f985271
-Node: Drag Interface\7f986293
-Node: Modes\7f986467
-Node: Major Modes\7f987418
-Node: Major Mode Conventions\7f990333
-Node: Example Major Modes\7f996288
-Node: Auto Major Mode\7f1004321
-Node: Mode Help\7f1011771
-Node: Derived Modes\7f1012872
-Node: Minor Modes\7f1015063
-Node: Minor Mode Conventions\7f1016365
-Node: Keymaps and Minor Modes\7f1019228
-Node: Modeline Format\7f1020063
-Node: Modeline Data\7f1021831
-Node: Modeline Variables\7f1026984
-Node: %-Constructs\7f1031700
-Node: Hooks\7f1034687
-Node: Documentation\7f1041447
-Node: Documentation Basics\7f1042870
-Node: Accessing Documentation\7f1045921
-Node: Keys in Documentation\7f1052202
-Node: Describing Characters\7f1055685
-Node: Help Functions\7f1058034
-Node: Obsoleteness\7f1064484
-Node: Files\7f1067476
-Node: Visiting Files\7f1069401
-Node: Visiting Functions\7f1070906
-Node: Subroutines of Visiting\7f1076064
-Node: Saving Buffers\7f1078137
-Node: Reading from Files\7f1084230
-Node: Writing to Files\7f1086391
-Node: File Locks\7f1089108
-Node: Information about Files\7f1092175
-Node: Testing Accessibility\7f1092936
-Node: Kinds of Files\7f1096676
-Node: Truenames\7f1098357
-Node: File Attributes\7f1099359
-Node: Changing File Attributes\7f1104498
-Node: File Names\7f1109920
-Node: File Name Components\7f1111493
-Node: Directory Names\7f1113938
-Node: Relative File Names\7f1117168
-Node: File Name Expansion\7f1118138
-Node: Unique File Names\7f1121892
-Node: File Name Completion\7f1123507
-Node: User Name Completion\7f1126775
-Node: Contents of Directories\7f1128182
-Node: Create/Delete Dirs\7f1131495
-Node: Magic File Names\7f1132601
-Node: Partial Files\7f1138249
-Node: Intro to Partial Files\7f1138477
-Node: Creating a Partial File\7f1139717
-Node: Detached Partial Files\7f1140653
-Node: Format Conversion\7f1141775
-Node: Files and MS-DOS\7f1147273
-Node: Backups and Auto-Saving\7f1149337
-Node: Backup Files\7f1150012
-Node: Making Backups\7f1151409
-Node: Rename or Copy\7f1154158
-Node: Numbered Backups\7f1156651
-Node: Backup Names\7f1158886
-Node: Auto-Saving\7f1162178
-Node: Reverting\7f1170340
-Node: Buffers\7f1173676
-Node: Buffer Basics\7f1175092
-Node: Current Buffer\7f1177145
-Node: Buffer Names\7f1181849
-Node: Buffer File Name\7f1185056
-Node: Buffer Modification\7f1189175
-Node: Modification Time\7f1191418
-Node: Read Only Buffers\7f1194793
-Node: The Buffer List\7f1198032
-Node: Creating Buffers\7f1202849
-Node: Killing Buffers\7f1204995
-Node: Indirect Buffers\7f1208827
-Node: Windows\7f1211401
-Node: Basic Windows\7f1212879
-Node: Splitting Windows\7f1215977
-Node: Deleting Windows\7f1221303
-Node: Selecting Windows\7f1225221
-Node: Cyclic Window Ordering\7f1229444
-Node: Buffers and Windows\7f1234599
-Node: Displaying Buffers\7f1236377
-Node: Choosing Window\7f1241716
-Node: Window Point\7f1249634
-Node: Window Start\7f1251704
-Node: Vertical Scrolling\7f1256503
-Node: Horizontal Scrolling\7f1262701
-Node: Size of Window\7f1266230
-Node: Position of Window\7f1270948
-Node: Resizing Windows\7f1273201
-Node: Window Configurations\7f1278639
-Node: Frames\7f1282136
-Node: Creating Frames\7f1284477
-Node: Frame Properties\7f1285817
-Node: Property Access\7f1286633
-Node: Initial Properties\7f1287540
-Node: X Frame Properties\7f1290026
-Node: Size and Position\7f1294660
-Node: Frame Name\7f1296658
-Node: Frame Titles\7f1297572
-Node: Deleting Frames\7f1299396
-Node: Finding All Frames\7f1300371
-Node: Frames and Windows\7f1303599
-Node: Minibuffers and Frames\7f1306381
-Node: Input Focus\7f1307299
-Node: Visibility of Frames\7f1310404
-Node: Raising and Lowering\7f1312394
-Node: Frame Configurations\7f1314770
-Node: Frame Hooks\7f1315827
-Node: Consoles and Devices\7f1317632
-Node: Basic Console Functions\7f1320375
-Node: Basic Device Functions\7f1320798
-Node: Console Types and Device Classes\7f1321644
-Node: Connecting to a Console or Device\7f1323911
-Node: The Selected Console and Device\7f1326095
-Node: Console and Device I/O\7f1327121
-Node: Positions\7f1327885
-Node: Point\7f1328854
-Node: Motion\7f1331944
-Node: Character Motion\7f1332711
-Node: Word Motion\7f1334948
-Node: Buffer End Motion\7f1336338
-Node: Text Lines\7f1337875
-Node: Screen Lines\7f1342776
-Node: List Motion\7f1346839
-Node: Skipping Characters\7f1350322
-Node: Excursions\7f1352541
-Node: Narrowing\7f1355581
-Node: Markers\7f1360912
-Node: Overview of Markers\7f1361818
-Node: Predicates on Markers\7f1366510
-Node: Creating Markers\7f1367756
-Node: Information from Markers\7f1371956
-Node: Changing Markers\7f1373054
-Node: The Mark\7f1374582
-Node: The Region\7f1383085
-Node: Text\7f1388771
-Node: Near Point\7f1391470
-Node: Buffer Contents\7f1395657
-Node: Comparing Text\7f1397063
-Node: Insertion\7f1398471
-Node: Commands for Insertion\7f1402381
-Node: Deletion\7f1405275
-Node: User-Level Deletion\7f1408925
-Node: The Kill Ring\7f1413085
-Node: Kill Ring Concepts\7f1415259
-Node: Kill Functions\7f1416313
-Node: Yank Commands\7f1418236
-Node: Low-Level Kill Ring\7f1420107
-Node: Internals of Kill Ring\7f1423193
-Node: Undo\7f1425973
-Node: Maintaining Undo\7f1430310
-Node: Filling\7f1432928
-Node: Margins\7f1438922
-Node: Auto Filling\7f1442945
-Node: Sorting\7f1444126
-Node: Columns\7f1453440
-Node: Indentation\7f1456521
-Node: Primitive Indent\7f1457300
-Node: Mode-Specific Indent\7f1458625
-Node: Region Indent\7f1461157
-Node: Relative Indent\7f1464104
-Node: Indent Tabs\7f1466486
-Node: Motion by Indent\7f1467807
-Node: Case Changes\7f1468586
-Node: Text Properties\7f1471939
-Node: Examining Properties\7f1473752
-Node: Changing Properties\7f1475635
-Node: Property Search\7f1479226
-Node: Special Properties\7f1483945
-Node: Saving Properties\7f1484226
-Node: Substitution\7f1487368
-Node: Registers\7f1490638
-Node: Transposition\7f1493221
-Node: Change Hooks\7f1494115
-Node: Transformations\7f1496155
-Node: Searching and Matching\7f1501259
-Node: String Search\7f1502390
-Node: Regular Expressions\7f1507371
-Node: Syntax of Regexps\7f1508738
-Node: Regexp Example\7f1523341
-Node: Regexp Search\7f1525511
-Node: POSIX Regexps\7f1531848
-Node: Search and Replace\7f1533925
-Node: Match Data\7f1537290
-Node: Simple Match Data\7f1538420
-Node: Replacing Match\7f1542685
-Node: Entire Match Data\7f1545366
-Node: Saving Match Data\7f1547604
-Node: Searching and Case\7f1548992
-Node: Standard Regexps\7f1551026
-Node: Syntax Tables\7f1553224
-Node: Syntax Basics\7f1554338
-Node: Syntax Descriptors\7f1557310
-Node: Syntax Class Table\7f1559160
-Node: Syntax Flags\7f1565198
-Node: Syntax Table Functions\7f1568415
-Node: Motion and Syntax\7f1572703
-Node: Parsing Expressions\7f1574155
-Node: Standard Syntax Tables\7f1580253
-Node: Syntax Table Internals\7f1581097
-Node: Abbrevs\7f1582123
-Node: Abbrev Mode\7f1583927
-Node: Abbrev Tables\7f1584647
-Node: Defining Abbrevs\7f1586186
-Node: Abbrev Files\7f1588107
-Node: Abbrev Expansion\7f1589890
-Node: Standard Abbrev Tables\7f1594521
-Node: Extents\7f1595680
-Node: Intro to Extents\7f1596923
-Node: Creating and Modifying Extents\7f1600915
-Node: Extent Endpoints\7f1602496
-Node: Finding Extents\7f1605759
-Node: Mapping Over Extents\7f1609881
-Node: Extent Properties\7f1616004
-Node: Detached Extents\7f1626165
-Node: Extent Parents\7f1628024
-Node: Duplicable Extents\7f1629718
-Node: Extents and Events\7f1632939
-Node: Atomic Extents\7f1634846
-Node: Specifiers\7f1635293
-Node: Introduction to Specifiers\7f1637406
-Node: Specifiers In-Depth\7f1639716
-Node: Specifier Instancing\7f1644628
-Node: Specifier Types\7f1647890
-Node: Adding Specifications\7f1652964
-Node: Retrieving Specifications\7f1662385
-Node: Specifier Tag Functions\7f1666130
-Node: Specifier Instancing Functions\7f1669364
-Node: Specifier Example\7f1672771
-Node: Creating Specifiers\7f1675927
-Node: Specifier Validation Functions\7f1680244
-Node: Other Specification Functions\7f1682630
-Node: Faces and Window-System Objects\7f1686451
-Node: Faces\7f1686775
-Node: Merging Faces\7f1688392
-Node: Basic Face Functions\7f1690353
-Node: Face Properties\7f1692501
-Node: Face Convenience Functions\7f1702774
-Node: Other Face Display Functions\7f1705994
-Node: Fonts\7f1706806
-Node: Font Specifiers\7f1707507
-Node: Font Instances\7f1708692
-Node: Font Instance Names\7f1709659
-Node: Font Instance Size\7f1710500
-Node: Font Instance Characteristics\7f1711786
-Node: Font Convenience Functions\7f1712964
-Node: Colors\7f1714254
-Node: Color Specifiers\7f1714694
-Node: Color Instances\7f1717054
-Node: Color Instance Properties\7f1717798
-Node: Color Convenience Functions\7f1718424
-Node: Glyphs\7f1719477
-Node: Glyph Functions\7f1721078
-Node: Creating Glyphs\7f1721485
-Node: Glyph Properties\7f1734125
-Node: Glyph Convenience Functions\7f1743292
-Node: Glyph Dimensions\7f1747239
-Node: Images\7f1748319
-Node: Image Specifiers\7f1748768
-Node: Image Instantiator Conversion\7f1764259
-Node: Image Instances\7f1765624
-Node: Image Instance Types\7f1766375
-Node: Image Instance Functions\7f1769140
-Node: Glyph Types\7f1776197
-Node: Mouse Pointer\7f1777969
-Node: Redisplay Glyphs\7f1780972
-Node: Subwindows\7f1782005
-Node: Annotations\7f1782248
-Node: Annotation Basics\7f1783264
-Node: Annotation Primitives\7f1787202
-Node: Annotation Properties\7f1788541
-Node: Locating Annotations\7f1791581
-Node: Margin Primitives\7f1792418
-Node: Annotation Hooks\7f1794312
-Node: Display\7f1794972
-Node: Refresh Screen\7f1795950
-Node: Truncation\7f1798144
-Node: The Echo Area\7f1800669
-Node: Warnings\7f1807112
-Node: Invisible Text\7f1811548
-Node: Selective Display\7f1814127
-Node: Overlay Arrow\7f1818253
-Node: Temporary Displays\7f1819606
-Node: Blinking\7f1823727
-Node: Usual Display\7f1825911
-Node: Display Tables\7f1828460
-Node: Display Table Format\7f1829264
-Node: Active Display Table\7f1830706
-Node: Character Descriptors\7f1834701
-Node: Beeping\7f1835458
-Node: Hash Tables\7f1840224
-Node: Introduction to Hash Tables\7f1840832
-Node: Working With Hash Tables\7f1847391
-Node: Weak Hash Tables\7f1848508
-Node: Range Tables\7f1850525
-Node: Introduction to Range Tables\7f1851214
-Node: Working With Range Tables\7f1851660
-Node: Databases\7f1852619
-Node: Connecting to a Database\7f1852918
-Node: Working With a Database\7f1854025
-Node: Other Database Functions\7f1854899
-Node: Processes\7f1855468
-Node: Subprocess Creation\7f1857692
-Node: Synchronous Processes\7f1861143
-Node: MS-DOS Subprocesses\7f1867865
-Node: Asynchronous Processes\7f1868939
-Node: Deleting Processes\7f1873296
-Node: Process Information\7f1875167
-Node: Input to Processes\7f1879259
-Node: Signals to Processes\7f1881954
-Node: Output from Processes\7f1886769
-Node: Process Buffers\7f1887581
-Node: Filter Functions\7f1890460
-Node: Accepting Output\7f1896051
-Node: Sentinels\7f1897578
-Node: Process Window Size\7f1901068
-Node: Transaction Queues\7f1901417
-Node: Network\7f1903115
-Node: System Interface\7f1905749
-Node: Starting Up\7f1907019
-Node: Start-up Summary\7f1907613
-Node: Init File\7f1911167
-Node: Terminal-Specific\7f1913548
-Node: Command Line Arguments\7f1916707
-Node: Getting Out\7f1920196
-Node: Killing XEmacs\7f1920765
-Node: Suspending XEmacs\7f1922433
-Node: System Environment\7f1925812
-Node: User Identification\7f1931993
-Node: Time of Day\7f1935522
-Node: Time Conversion\7f1938309
-Node: Timers\7f1943551
-Node: Terminal Input\7f1945724
-Node: Input Modes\7f1946227
-Node: Translating Input\7f1948686
-Node: Recording Input\7f1952851
-Node: Terminal Output\7f1954951
-Node: Flow Control\7f1958572
-Node: Batch Mode\7f1962534
-Node: X-Windows\7f1963916
-Node: X Selections\7f1964787
-Node: X Server\7f1967538
-Node: Resources\7f1967989
-Node: Server Data\7f1973300
-Node: Grabs\7f1974507
-Node: X Miscellaneous\7f1976087
-Node: ToolTalk Support\7f1978472
-Node: XEmacs ToolTalk API Summary\7f1978689
-Node: Sending Messages\7f1979989
-Node: Example of Sending Messages\7f1980240
-Node: Elisp Interface for Sending Messages\7f1981302
-Node: Receiving Messages\7f1987898
-Node: Example of Receiving Messages\7f1988121
-Node: Elisp Interface for Receiving Messages\7f1988957
-Node: LDAP Support\7f1992814
-Node: Building XEmacs with LDAP support\7f1993308
-Node: XEmacs LDAP API\7f1994285
-Node: LDAP Variables\7f1995337
-Node: The High-Level LDAP API\7f1997937
-Node: The Low-Level LDAP API\7f2001410
-Node: The LDAP Lisp Object\7f2002241
-Node: Opening and Closing a LDAP Connection\7f2002796
-Node: Low-level Operations on a LDAP Server\7f2004602
-Node: LDAP Internationalization\7f2007326
-Node: LDAP Internationalization Variables\7f2008231
-Node: Encoder/Decoder Functions\7f2009962
-Node: Syntax of Search Filters\7f2010999
-Node: PostgreSQL Support\7f2012297
-Node: Building XEmacs with PostgreSQL support\7f2012692
-Node: XEmacs PostgreSQL libpq API\7f2014039
-Node: libpq Lisp Variables\7f2015918
-Node: libpq Lisp Symbols and DataTypes\7f2018882
-Node: Synchronous Interface Functions\7f2032138
-Node: Asynchronous Interface Functions\7f2036629
-Node: Large Object Support\7f2040134
-Node: Other libpq Functions\7f2040761
-Node: Unimplemented libpq Functions\7f2043796
-Node: XEmacs PostgreSQL libpq Examples\7f2049115
-Node: Internationalization\7f2055206
-Node: I18N Levels 1 and 2\7f2055549
-Node: I18N Level 3\7f2056255
-Node: Level 3 Basics\7f2056536
-Node: Level 3 Primitives\7f2057369
-Node: Dynamic Messaging\7f2058975
-Node: Domain Specification\7f2059438
-Node: Documentation String Extraction\7f2061108
-Node: I18N Level 4\7f2062026
-Node: MULE\7f2062218
-Node: Internationalization Terminology\7f2063267
-Node: Charsets\7f2075466
-Node: Charset Properties\7f2076162
-Node: Basic Charset Functions\7f2080877
-Node: Charset Property Functions\7f2083058
-Node: Predefined Charsets\7f2085128
-Node: MULE Characters\7f2088048
-Node: Composite Characters\7f2088923
-Node: Coding Systems\7f2090190
-Node: Coding System Types\7f2092330
-Node: ISO 2022\7f2096314
-Node: EOL Conversion\7f2108589
-Node: Coding System Properties\7f2109761
-Node: Basic Coding System Functions\7f2114084
-Node: Coding System Property Functions\7f2116118
-Node: Encoding and Decoding Text\7f2116676
-Node: Detection of Textual Encoding\7f2117812
-Node: Big5 and Shift-JIS Functions\7f2119348
-Node: Predefined Coding Systems\7f2120500
-Node: CCL\7f2132594
-Node: CCL Syntax\7f2135698
-Node: CCL Statements\7f2137274
-Node: CCL Expressions\7f2141922
-Node: Calling CCL\7f2144461
-Node: CCL Examples\7f2147466
-Node: Category Tables\7f2147603
-Node: Tips\7f2149962
-Node: Style Tips\7f2150603
-Node: Compilation Tips\7f2160122
-Node: Documentation Tips\7f2162036
-Node: Comment Tips\7f2167545
-Node: Library Headers\7f2170548
-Node: Building XEmacs and Object Allocation\7f2174520
-Node: Building XEmacs\7f2175403
-Node: Pure Storage\7f2181981
-Node: Garbage Collection\7f2184769
-Node: Standard Errors\7f2195612
-Node: Standard Buffer-Local Variables\7f2199821
-Node: Standard Keymaps\7f2202456
-Node: Standard Hooks\7f2206190
-Node: Index\7f2213690
+Node: Copying\7f50069
+Node: Introduction\7f69219
+Node: Caveats\7f70801
+Node: Lisp History\7f72477
+Node: Conventions\7f73730
+Node: Some Terms\7f74542
+Node: nil and t\7f75260
+Node: Evaluation Notation\7f76934
+Node: Printing Notation\7f77845
+Node: Error Messages\7f78715
+Node: Buffer Text Notation\7f79153
+Node: Format of Descriptions\7f80025
+Node: A Sample Function Description\7f80876
+Node: A Sample Variable Description\7f84859
+Node: Acknowledgements\7f85764
+Node: Packaging\7f87739
+Node: Package Overview\7f89486
+Node: The User View\7f91666
+Node: The Library Maintainer View\7f98125
+Node: Infrastructure\7f100037
+Node: Control Files\7f103981
+Node: Obtaining\7f106049
+Node: The Package Release Engineer View\7f106563
+Node: Package Terminology\7f107294
+Node: Building Packages\7f110118
+Node: Makefile Targets\7f111327
+Node: Local.rules File\7f113188
+Node: Creating Packages\7f120123
+Node: package-info.in\7f120657
+Node: Makefile\7f125512
+Node: Documenting Packages\7f139309
+Node: Issues\7f140602
+Node: Lisp Data Types\7f140717
+Node: Printed Representation\7f143266
+Node: Comments\7f145305
+Node: Primitive Types\7f146199
+Node: Programming Types\7f147855
+Node: Integer Type\7f149804
+Node: Floating Point Type\7f150838
+Node: Character Type\7f151454
+Node: Symbol Type\7f159355
+Node: Sequence Type\7f162047
+Node: Cons Cell Type\7f163563
+Node: Dotted Pair Notation\7f168044
+Node: Association List Type\7f170162
+Node: Array Type\7f171042
+Node: String Type\7f172505
+Node: Vector Type\7f175183
+Node: Bit Vector Type\7f175952
+Node: Function Type\7f176811
+Node: Macro Type\7f177921
+Node: Primitive Function Type\7f178615
+Node: Compiled-Function Type\7f180138
+Node: Autoload Type\7f180689
+Node: Char Table Type\7f181700
+Node: Hash Table Type\7f181871
+Node: Range Table Type\7f183022
+Node: Weak List Type\7f183872
+Node: Editing Types\7f184019
+Node: Buffer Type\7f185643
+Node: Marker Type\7f187667
+Node: Extent Type\7f188387
+Node: Window Type\7f189652
+Node: Frame Type\7f191060
+Node: Device Type\7f191852
+Node: Console Type\7f192675
+Node: Window Configuration Type\7f193873
+Node: Event Type\7f194568
+Node: Process Type\7f194729
+Node: Stream Type\7f195761
+Node: Keymap Type\7f196881
+Node: Syntax Table Type\7f197416
+Node: Display Table Type\7f198435
+Node: Database Type\7f198872
+Node: Charset Type\7f199035
+Node: Coding System Type\7f199196
+Node: ToolTalk Message Type\7f199377
+Node: ToolTalk Pattern Type\7f199573
+Node: Window-System Types\7f199742
+Node: Face Type\7f200885
+Node: Glyph Type\7f201013
+Node: Specifier Type\7f201166
+Node: Font Instance Type\7f201336
+Node: Color Instance Type\7f201523
+Node: Image Instance Type\7f201717
+Node: Toolbar Button Type\7f201912
+Node: Subwindow Type\7f202102
+Node: X Resource Type\7f202278
+Node: Type Predicates\7f202428
+Node: Equality Predicates\7f211554
+Node: Numbers\7f216362
+Node: Integer Basics\7f217814
+Node: Float Basics\7f220160
+Node: Predicates on Numbers\7f221899
+Node: Comparison of Numbers\7f223529
+Node: Numeric Conversions\7f227347
+Node: Arithmetic Operations\7f228810
+Node: Rounding Operations\7f234946
+Node: Bitwise Operations\7f236056
+Node: Math Functions\7f245099
+Node: Random Numbers\7f247631
+Node: Strings and Characters\7f249394
+Node: String Basics\7f250844
+Node: Predicates for Strings\7f253259
+Node: Creating Strings\7f254019
+Node: Predicates for Characters\7f259357
+Node: Character Codes\7f260428
+Node: Text Comparison\7f261848
+Node: String Conversion\7f265293
+Node: Modifying Strings\7f268960
+Node: String Properties\7f269598
+Node: Formatting Strings\7f270240
+Node: Character Case\7f279855
+Node: Case Tables\7f283406
+Node: Char Tables\7f287373
+Node: Char Table Types\7f288763
+Node: Working With Char Tables\7f290345
+Node: Lists\7f292362
+Node: Cons Cells\7f293482
+Node: Lists as Boxes\7f294815
+Node: List-related Predicates\7f297454
+Node: List Elements\7f299153
+Node: Building Lists\7f304179
+Node: Modifying Lists\7f310167
+Node: Setcar\7f310976
+Node: Setcdr\7f313404
+Node: Rearrangement\7f315922
+Node: Sets And Lists\7f321505
+Node: Association Lists\7f325730
+Ref: Association Lists-Footnote-1\7f335018
+Node: Property Lists\7f335223
+Node: Working With Normal Plists\7f336768
+Node: Working With Lax Plists\7f339105
+Node: Converting Plists To/From Alists\7f341382
+Node: Weak Lists\7f342730
+Node: Sequences Arrays Vectors\7f344890
+Node: Sequence Functions\7f347523
+Node: Arrays\7f351179
+Node: Array Functions\7f354240
+Node: Vectors\7f356770
+Node: Vector Functions\7f358265
+Node: Bit Vectors\7f360833
+Node: Bit Vector Functions\7f361675
+Node: Symbols\7f363971
+Node: Symbol Components\7f365017
+Node: Definitions\7f369197
+Node: Creating Symbols\7f371419
+Node: Symbol Properties\7f378450
+Node: Plists and Alists\7f379974
+Node: Object Plists\7f381720
+Node: Other Plists\7f384477
+Node: Evaluation\7f386273
+Node: Intro Eval\7f387075
+Ref: Intro Eval-Footnote-1\7f390425
+Node: Eval\7f390560
+Node: Forms\7f394976
+Node: Self-Evaluating Forms\7f396133
+Node: Symbol Forms\7f397643
+Node: Classifying Lists\7f398557
+Node: Function Indirection\7f399310
+Node: Function Forms\7f402406
+Node: Macro Forms\7f403400
+Node: Special Forms\7f404997
+Node: Autoloading\7f407303
+Node: Quoting\7f407798
+Node: Control Structures\7f409156
+Node: Sequencing\7f410774
+Node: Conditionals\7f413636
+Node: Combining Conditions\7f417056
+Node: Iteration\7f420323
+Node: Nonlocal Exits\7f422099
+Node: Catch and Throw\7f422797
+Node: Examples of Catch\7f426633
+Node: Errors\7f428649
+Node: Signaling Errors\7f430135
+Node: Processing of Errors\7f438879
+Node: Handling Errors\7f441154
+Node: Error Symbols\7f448390
+Node: Cleanups\7f452343
+Node: Variables\7f456118
+Node: Global Variables\7f457885
+Node: Constant Variables\7f458958
+Node: Local Variables\7f459581
+Node: Void Variables\7f464516
+Node: Defining Variables\7f468029
+Node: Accessing Variables\7f475190
+Node: Setting Variables\7f476612
+Node: Variable Scoping\7f481128
+Node: Scope\7f482724
+Node: Extent\7f484247
+Node: Impl of Scope\7f485723
+Node: Using Scoping\7f487683
+Node: Buffer-Local Variables\7f489202
+Node: Intro to Buffer-Local\7f490035
+Node: Creating Buffer-Local\7f492575
+Node: Default Value\7f498474
+Node: Variable Aliases\7f501614
+Node: Functions\7f503462
+Node: What Is a Function\7f504553
+Node: Lambda Expressions\7f508596
+Node: Lambda Components\7f509503
+Node: Simple Lambda\7f511328
+Node: Argument List\7f512982
+Node: Function Documentation\7f516707
+Node: Function Names\7f518646
+Node: Defining Functions\7f521216
+Node: Calling Functions\7f524253
+Node: Mapping Functions\7f528098
+Node: Anonymous Functions\7f530795
+Node: Function Cells\7f534037
+Node: Inline Functions\7f538852
+Node: Related Topics\7f540659
+Node: Macros\7f541709
+Node: Simple Macro\7f542990
+Node: Expansion\7f543722
+Node: Compiling Macros\7f546723
+Node: Defining Macros\7f548556
+Node: Backquote\7f549870
+Node: Problems with Macros\7f552264
+Node: Argument Evaluation\7f552955
+Node: Surprising Local Vars\7f555867
+Node: Eval During Expansion\7f557929
+Node: Repeated Expansion\7f559619
+Node: Customization\7f561532
+Node: Common Keywords\7f561998
+Node: Group Definitions\7f564839
+Node: Variable Definitions\7f567029
+Node: Customization Types\7f572016
+Node: Simple Types\7f573448
+Node: Composite Types\7f575602
+Node: Splicing into Lists\7f580289
+Node: Type Keywords\7f582121
+Node: Loading\7f585639
+Node: How Programs Do Loading\7f587311
+Node: Autoload\7f596434
+Node: Repeated Loading\7f602501
+Node: Named Features\7f604611
+Node: Unloading\7f611038
+Node: Hooks for Loading\7f613191
+Node: Byte Compilation\7f613908
+Node: Speed of Byte-Code\7f615972
+Node: Compilation Functions\7f617176
+Node: Compilation Options\7f623946
+Node: Docs and Compilation\7f633876
+Node: Dynamic Loading\7f636541
+Node: Eval During Compile\7f638917
+Node: Compiled-Function Objects\7f640179
+Node: Disassembly\7f644977
+Node: Different Behavior\7f652255
+Node: Debugging\7f653597
+Node: Debugger\7f655006
+Node: Error Debugging\7f656148
+Node: Infinite Loops\7f658898
+Node: Function Debugging\7f660139
+Node: Explicit Debug\7f662936
+Node: Using Debugger\7f663704
+Node: Debugger Commands\7f665563
+Node: Invoking the Debugger\7f669877
+Node: Internals of Debugger\7f673789
+Node: Syntax Errors\7f678673
+Node: Excess Open\7f679918
+Node: Excess Close\7f681790
+Node: Compilation Errors\7f683208
+Node: Edebug\7f684493
+Node: Using Edebug\7f686598
+Node: Instrumenting\7f689292
+Node: Edebug Execution Modes\7f692778
+Node: Jumping\7f695885
+Node: Edebug Misc\7f698226
+Node: Breakpoints\7f699612
+Node: Global Break Condition\7f702415
+Node: Embedded Breakpoints\7f703367
+Node: Trapping Errors\7f704319
+Node: Edebug Views\7f706392
+Node: Edebug Eval\7f708355
+Node: Eval List\7f709529
+Node: Reading in Edebug\7f712911
+Node: Printing in Edebug\7f713707
+Node: Tracing\7f715419
+Node: Coverage Testing\7f717304
+Node: The Outside Context\7f719342
+Node: Checking Whether to Stop\7f720288
+Node: Edebug Display Update\7f720932
+Node: Edebug Recursive Edit\7f722952
+Node: Instrumenting Macro Calls\7f724604
+Node: Specification List\7f727082
+Node: Backtracking\7f736492
+Node: Debugging Backquote\7f738427
+Node: Specification Examples\7f742130
+Node: Edebug Options\7f744194
+Node: Read and Print\7f749530
+Node: Streams Intro\7f750504
+Node: Input Streams\7f752519
+Node: Input Functions\7f757417
+Node: Output Streams\7f759474
+Node: Output Functions\7f763522
+Node: Output Variables\7f767819
+Node: Minibuffers\7f772620
+Node: Intro to Minibuffers\7f773769
+Node: Text from Minibuffer\7f775954
+Node: Object from Minibuffer\7f781045
+Node: Minibuffer History\7f785135
+Node: Completion\7f788111
+Node: Basic Completion\7f790083
+Node: Minibuffer Completion\7f794963
+Node: Completion Commands\7f798537
+Node: High-Level Completion\7f803191
+Node: Reading File Names\7f807937
+Node: Programmed Completion\7f811626
+Node: Yes-or-No Queries\7f814005
+Node: Multiple Queries\7f819739
+Node: Reading a Password\7f823803
+Node: Minibuffer Misc\7f825143
+Node: Command Loop\7f830020
+Node: Command Overview\7f831361
+Node: Defining Commands\7f834635
+Node: Using Interactive\7f835380
+Node: Interactive Codes\7f840150
+Node: Interactive Examples\7f845939
+Node: Interactive Call\7f847250
+Node: Command Loop Info\7f852661
+Node: Events\7f857637
+Node: Event Types\7f859095
+Node: Event Contents\7f861015
+Node: Event Predicates\7f865489
+Node: Accessing Mouse Event Positions\7f866804
+Node: Frame-Level Event Position Info\7f867500
+Node: Window-Level Event Position Info\7f868537
+Node: Event Text Position Info\7f870298
+Node: Event Glyph Position Info\7f872787
+Node: Event Toolbar Position Info\7f874107
+Node: Other Event Position Info\7f874778
+Node: Accessing Other Event Info\7f875187
+Node: Working With Events\7f876804
+Node: Converting Events\7f882802
+Node: Reading Input\7f886198
+Node: Key Sequence Input\7f887197
+Node: Reading One Event\7f889829
+Node: Dispatching an Event\7f892650
+Node: Quoted Character Input\7f893101
+Node: Peeking and Discarding\7f894447
+Node: Waiting\7f898349
+Node: Quitting\7f900660
+Node: Prefix Command Arguments\7f905065
+Node: Recursive Editing\7f910149
+Node: Disabling Commands\7f914940
+Node: Command History\7f917005
+Node: Keyboard Macros\7f918739
+Node: Keymaps\7f920953
+Node: Keymap Terminology\7f922527
+Node: Format of Keymaps\7f925453
+Node: Creating Keymaps\7f925861
+Node: Inheritance and Keymaps\7f927938
+Node: Key Sequences\7f930307
+Node: Prefix Keys\7f935100
+Node: Active Keymaps\7f938682
+Node: Key Lookup\7f948050
+Node: Functions for Key Lookup\7f953210
+Node: Changing Key Bindings\7f958908
+Node: Key Binding Commands\7f966067
+Node: Scanning Keymaps\7f968129
+Node: Other Keymap Functions\7f976695
+Node: Menus\7f977317
+Node: Menu Format\7f977909
+Node: Menubar Format\7f986552
+Node: Menubar\7f987174
+Node: Modifying Menus\7f990287
+Node: Menu Filters\7f995628
+Node: Pop-Up Menus\7f997521
+Node: Menu Accelerators\7f999849
+Node: Creating Menu Accelerators\7f1000602
+Node: Keyboard Menu Traversal\7f1001959
+Node: Menu Accelerator Functions\7f1002684
+Node: Buffers Menu\7f1005779
+Node: Dialog Boxes\7f1007070
+Node: Dialog Box Format\7f1007237
+Node: Dialog Box Functions\7f1008659
+Node: Toolbar\7f1009056
+Node: Toolbar Intro\7f1009491
+Node: Creating Toolbar\7f1011889
+Node: Toolbar Descriptor Format\7f1012806
+Node: Specifying the Toolbar\7f1017300
+Node: Other Toolbar Variables\7f1020904
+Node: Gutter\7f1025329
+Node: Gutter Intro\7f1025915
+Node: Creating Gutter\7f1027915
+Node: Gutter Descriptor Format\7f1030802
+Node: Specifying a Gutter\7f1035256
+Node: Other Gutter Variables\7f1038788
+Node: Common Gutter Widgets\7f1043172
+Node: Buffer Tabs\7f1044161
+Node: Progress Bars\7f1044299
+Node: Scrollbars\7f1044441
+Node: Drag and Drop\7f1044573
+Node: Supported Protocols\7f1045646
+Node: OffiX DND\7f1046146
+Node: CDE dt\7f1047150
+Node: MSWindows OLE\7f1047738
+Node: Loose ends\7f1047906
+Node: Drop Interface\7f1048295
+Node: Drag Interface\7f1049315
+Node: Modes\7f1049486
+Node: Major Modes\7f1050434
+Node: Major Mode Conventions\7f1053346
+Node: Example Major Modes\7f1059298
+Node: Auto Major Mode\7f1067329
+Node: Mode Help\7f1074776
+Node: Derived Modes\7f1075874
+Node: Minor Modes\7f1078062
+Node: Minor Mode Conventions\7f1079361
+Node: Keymaps and Minor Modes\7f1082221
+Node: Modeline Format\7f1083053
+Node: Modeline Data\7f1084818
+Node: Modeline Variables\7f1089968
+Node: %-Constructs\7f1094681
+Node: Hooks\7f1097665
+Node: Documentation\7f1104422
+Node: Documentation Basics\7f1105842
+Node: Accessing Documentation\7f1108890
+Node: Keys in Documentation\7f1115171
+Node: Describing Characters\7f1118651
+Node: Help Functions\7f1120997
+Node: Obsoleteness\7f1127444
+Node: Files\7f1130433
+Node: Visiting Files\7f1132355
+Node: Visiting Functions\7f1133857
+Node: Subroutines of Visiting\7f1139013
+Node: Saving Buffers\7f1141083
+Node: Reading from Files\7f1147173
+Node: Writing to Files\7f1149331
+Node: File Locks\7f1152045
+Node: Information about Files\7f1155109
+Node: Testing Accessibility\7f1155867
+Node: Kinds of Files\7f1159604
+Node: Truenames\7f1161282
+Node: File Attributes\7f1162281
+Node: Changing File Attributes\7f1167417
+Node: File Names\7f1172836
+Node: File Name Components\7f1174405
+Node: Directory Names\7f1176847
+Node: Relative File Names\7f1180074
+Node: File Name Expansion\7f1181040
+Node: Unique File Names\7f1184791
+Node: File Name Completion\7f1186403
+Node: User Name Completion\7f1189668
+Node: Contents of Directories\7f1191072
+Node: Create/Delete Dirs\7f1194382
+Node: Magic File Names\7f1195485
+Node: Partial Files\7f1201130
+Node: Intro to Partial Files\7f1201358
+Node: Creating a Partial File\7f1202595
+Node: Detached Partial Files\7f1203531
+Node: Format Conversion\7f1204650
+Node: Files and MS-DOS\7f1210145
+Node: Backups and Auto-Saving\7f1212206
+Node: Backup Files\7f1212878
+Node: Making Backups\7f1214272
+Node: Rename or Copy\7f1217021
+Node: Numbered Backups\7f1219511
+Node: Backup Names\7f1221743
+Node: Auto-Saving\7f1225032
+Node: Reverting\7f1233191
+Node: Buffers\7f1236524
+Node: Buffer Basics\7f1237937
+Node: Current Buffer\7f1239983
+Node: Buffer Names\7f1244684
+Node: Buffer File Name\7f1247888
+Node: Buffer Modification\7f1252004
+Node: Modification Time\7f1254244
+Node: Read Only Buffers\7f1257616
+Node: The Buffer List\7f1260852
+Node: Creating Buffers\7f1265666
+Node: Killing Buffers\7f1267809
+Node: Indirect Buffers\7f1271638
+Node: Windows\7f1274209
+Node: Basic Windows\7f1275684
+Node: Splitting Windows\7f1278779
+Node: Deleting Windows\7f1284102
+Node: Selecting Windows\7f1288017
+Node: Cyclic Window Ordering\7f1292237
+Node: Buffers and Windows\7f1297389
+Node: Displaying Buffers\7f1299164
+Node: Choosing Window\7f1304500
+Node: Window Point\7f1312415
+Node: Window Start\7f1314482
+Node: Vertical Scrolling\7f1319278
+Node: Horizontal Scrolling\7f1325473
+Node: Size of Window\7f1328999
+Node: Position of Window\7f1333714
+Node: Resizing Windows\7f1335964
+Node: Window Configurations\7f1341399
+Node: Frames\7f1344885
+Node: Creating Frames\7f1347223
+Node: Frame Properties\7f1348560
+Node: Property Access\7f1349373
+Node: Initial Properties\7f1350277
+Node: X Frame Properties\7f1352760
+Node: Size and Position\7f1357391
+Node: Frame Name\7f1359386
+Node: Frame Titles\7f1360297
+Node: Deleting Frames\7f1362118
+Node: Finding All Frames\7f1363089
+Node: Frames and Windows\7f1366317
+Node: Minibuffers and Frames\7f1369096
+Node: Input Focus\7f1370011
+Node: Visibility of Frames\7f1373113
+Node: Raising and Lowering\7f1375100
+Node: Frame Configurations\7f1377473
+Node: Frame Hooks\7f1378527
+Node: Consoles and Devices\7f1380329
+Node: Basic Console Functions\7f1383069
+Node: Basic Device Functions\7f1383492
+Node: Console Types and Device Classes\7f1384338
+Node: Connecting to a Console or Device\7f1386602
+Node: The Selected Console and Device\7f1388786
+Node: Console and Device I/O\7f1389812
+Node: Positions\7f1390576
+Node: Point\7f1391543
+Node: Motion\7f1394630
+Node: Character Motion\7f1395394
+Node: Word Motion\7f1397629
+Node: Buffer End Motion\7f1399016
+Node: Text Lines\7f1400550
+Node: Screen Lines\7f1405447
+Node: List Motion\7f1409507
+Node: Skipping Characters\7f1412987
+Node: Excursions\7f1415203
+Node: Narrowing\7f1418240
+Node: Markers\7f1423568
+Node: Overview of Markers\7f1424471
+Node: Predicates on Markers\7f1429160
+Node: Creating Markers\7f1430403
+Node: Information from Markers\7f1434600
+Node: Changing Markers\7f1435695
+Node: The Mark\7f1437220
+Node: The Region\7f1445721
+Node: Text\7f1451433
+Node: Near Point\7f1454129
+Node: Buffer Contents\7f1458313
+Node: Comparing Text\7f1459716
+Node: Insertion\7f1461121
+Node: Commands for Insertion\7f1465028
+Node: Deletion\7f1467919
+Node: User-Level Deletion\7f1471566
+Node: The Kill Ring\7f1475723
+Node: Kill Ring Concepts\7f1477894
+Node: Kill Functions\7f1478945
+Node: Yank Commands\7f1480865
+Node: Low-Level Kill Ring\7f1482733
+Node: Internals of Kill Ring\7f1485816
+Node: Undo\7f1488593
+Node: Maintaining Undo\7f1492927
+Node: Filling\7f1495542
+Node: Margins\7f1501533
+Node: Auto Filling\7f1505556
+Node: Sorting\7f1506734
+Node: Columns\7f1516045
+Node: Indentation\7f1519123
+Node: Primitive Indent\7f1519899
+Node: Mode-Specific Indent\7f1521221
+Node: Region Indent\7f1523750
+Node: Relative Indent\7f1526694
+Node: Indent Tabs\7f1529073
+Node: Motion by Indent\7f1530391
+Node: Case Changes\7f1531167
+Node: Text Properties\7f1534517
+Node: Examining Properties\7f1536327
+Node: Changing Properties\7f1538207
+Node: Property Search\7f1541795
+Node: Special Properties\7f1546511
+Node: Saving Properties\7f1546789
+Node: Substitution\7f1549928
+Node: Registers\7f1553195
+Node: Transposition\7f1555774
+Node: Change Hooks\7f1556665
+Node: Transformations\7f1558702
+Node: Searching and Matching\7f1563802
+Node: String Search\7f1564930
+Node: Regular Expressions\7f1569908
+Node: Syntax of Regexps\7f1571272
+Node: Regexp Example\7f1585872
+Node: Regexp Search\7f1588039
+Node: POSIX Regexps\7f1594373
+Node: Search and Replace\7f1596447
+Node: Match Data\7f1599812
+Node: Simple Match Data\7f1600939
+Node: Replacing Match\7f1605201
+Node: Entire Match Data\7f1607879
+Node: Saving Match Data\7f1610114
+Node: Searching and Case\7f1611499
+Node: Standard Regexps\7f1613530
+Node: Syntax Tables\7f1615725
+Node: Syntax Basics\7f1616836
+Node: Syntax Descriptors\7f1619812
+Node: Syntax Class Table\7f1621659
+Node: Syntax Flags\7f1627838
+Node: Syntax Table Functions\7f1632234
+Node: Motion and Syntax\7f1636529
+Node: Parsing Expressions\7f1637978
+Node: Standard Syntax Tables\7f1644073
+Node: Syntax Table Internals\7f1644914
+Node: Abbrevs\7f1645937
+Node: Abbrev Mode\7f1647738
+Node: Abbrev Tables\7f1648455
+Node: Defining Abbrevs\7f1649991
+Node: Abbrev Files\7f1651909
+Node: Abbrev Expansion\7f1653689
+Node: Standard Abbrev Tables\7f1658317
+Node: Extents\7f1659473
+Node: Intro to Extents\7f1660712
+Node: Creating and Modifying Extents\7f1664701
+Node: Extent Endpoints\7f1666282
+Node: Finding Extents\7f1669542
+Node: Mapping Over Extents\7f1673661
+Node: Extent Properties\7f1679781
+Node: Detached Extents\7f1690001
+Node: Extent Parents\7f1691857
+Node: Duplicable Extents\7f1693548
+Node: Extents and Events\7f1696766
+Node: Atomic Extents\7f1698724
+Node: Specifiers\7f1699168
+Node: Introduction to Specifiers\7f1701297
+Node: Simple Specifier Usage\7f1705478
+Node: Specifiers In-Depth\7f1711896
+Node: Specifier Instancing\7f1718530
+Node: Specifier Types\7f1721789
+Node: Adding Specifications\7f1726860
+Node: Retrieving Specifications\7f1738350
+Node: Specifier Tag Functions\7f1742095
+Node: Specifier Instancing Functions\7f1745326
+Node: Specifier Examples\7f1750181
+Node: Creating Specifiers\7f1757885
+Node: Specifier Validation Functions\7f1762228
+Node: Other Specification Functions\7f1764614
+Node: Faces and Window-System Objects\7f1768496
+Node: Faces\7f1768820
+Node: Merging Faces\7f1770434
+Node: Basic Face Functions\7f1772392
+Node: Face Properties\7f1774537
+Node: Face Convenience Functions\7f1784807
+Node: Other Face Display Functions\7f1788027
+Node: Fonts\7f1788839
+Node: Font Specifiers\7f1789537
+Node: Font Instances\7f1790722
+Node: Font Instance Names\7f1791689
+Node: Font Instance Size\7f1792530
+Node: Font Instance Characteristics\7f1793816
+Node: Font Convenience Functions\7f1794994
+Node: Colors\7f1796284
+Node: Color Specifiers\7f1796724
+Node: Color Instances\7f1799084
+Node: Color Instance Properties\7f1799825
+Node: Color Convenience Functions\7f1800451
+Node: Glyphs\7f1801504
+Node: Glyph Functions\7f1803163
+Node: Creating Glyphs\7f1803570
+Node: Glyph Properties\7f1816210
+Node: Glyph Convenience Functions\7f1825374
+Node: Glyph Dimensions\7f1829318
+Node: Images\7f1830398
+Node: Image Specifiers\7f1830847
+Node: Image Instantiator Conversion\7f1846336
+Node: Image Instances\7f1847701
+Node: Image Instance Types\7f1848449
+Node: Image Instance Functions\7f1851211
+Node: Glyph Types\7f1858268
+Node: Mouse Pointer\7f1860037
+Node: Redisplay Glyphs\7f1863037
+Node: Subwindows\7f1864070
+Node: Glyph Examples\7f1864333
+Node: Annotations\7f1872589
+Node: Annotation Basics\7f1873602
+Node: Annotation Primitives\7f1877537
+Node: Annotation Properties\7f1878876
+Node: Locating Annotations\7f1881916
+Node: Margin Primitives\7f1882753
+Node: Annotation Hooks\7f1884644
+Node: Display\7f1885301
+Node: Refresh Screen\7f1886276
+Node: Truncation\7f1888467
+Node: The Echo Area\7f1890989
+Node: Warnings\7f1897429
+Node: Invisible Text\7f1901862
+Node: Selective Display\7f1904573
+Node: Overlay Arrow\7f1908696
+Node: Temporary Displays\7f1910046
+Node: Blinking\7f1914165
+Node: Usual Display\7f1916346
+Node: Display Tables\7f1918892
+Node: Display Table Format\7f1919693
+Node: Active Display Table\7f1921132
+Node: Character Descriptors\7f1925124
+Node: Beeping\7f1925878
+Node: Hash Tables\7f1930643
+Node: Introduction to Hash Tables\7f1931251
+Node: Working With Hash Tables\7f1937807
+Node: Weak Hash Tables\7f1938924
+Node: Range Tables\7f1940938
+Node: Introduction to Range Tables\7f1941624
+Node: Working With Range Tables\7f1942070
+Node: Databases\7f1943029
+Node: Connecting to a Database\7f1943328
+Node: Working With a Database\7f1944435
+Node: Other Database Functions\7f1945309
+Node: Processes\7f1945878
+Node: Subprocess Creation\7f1948099
+Node: Synchronous Processes\7f1951547
+Node: MS-DOS Subprocesses\7f1958266
+Node: Asynchronous Processes\7f1959337
+Node: Deleting Processes\7f1963691
+Node: Process Information\7f1965559
+Node: Input to Processes\7f1969649
+Node: Signals to Processes\7f1972341
+Node: Output from Processes\7f1977153
+Node: Process Buffers\7f1977962
+Node: Filter Functions\7f1980838
+Node: Accepting Output\7f1986426
+Node: Sentinels\7f1987950
+Node: Process Window Size\7f1991437
+Node: Transaction Queues\7f1991786
+Node: Network\7f1993481
+Node: System Interface\7f1996112
+Node: Starting Up\7f1997379
+Node: Start-up Summary\7f1997970
+Node: Init File\7f2001521
+Node: Terminal-Specific\7f2003899
+Node: Command Line Arguments\7f2007055
+Node: Getting Out\7f2010541
+Node: Killing XEmacs\7f2011107
+Node: Suspending XEmacs\7f2012772
+Node: System Environment\7f2016148
+Node: User Identification\7f2022326
+Node: Time of Day\7f2025855
+Node: Time Conversion\7f2028639
+Node: Timers\7f2033878
+Node: Terminal Input\7f2036048
+Node: Input Modes\7f2036548
+Node: Translating Input\7f2039007
+Node: Recording Input\7f2043169
+Node: Terminal Output\7f2045269
+Node: Flow Control\7f2048887
+Node: Batch Mode\7f2052846
+Node: X-Windows\7f2054224
+Node: X Selections\7f2055093
+Node: X Server\7f2057841
+Node: Resources\7f2058289
+Node: Server Data\7f2063598
+Node: Grabs\7f2064802
+Node: X Miscellaneous\7f2066382
+Node: ToolTalk Support\7f2068767
+Node: XEmacs ToolTalk API Summary\7f2068984
+Node: Sending Messages\7f2070281
+Node: Example of Sending Messages\7f2070532
+Node: Elisp Interface for Sending Messages\7f2071591
+Node: Receiving Messages\7f2078187
+Node: Example of Receiving Messages\7f2078410
+Node: Elisp Interface for Receiving Messages\7f2079243
+Node: LDAP Support\7f2083100
+Node: Building XEmacs with LDAP support\7f2083591
+Node: XEmacs LDAP API\7f2084565
+Node: LDAP Variables\7f2085614
+Node: The High-Level LDAP API\7f2088214
+Node: The Low-Level LDAP API\7f2091684
+Node: The LDAP Lisp Object\7f2092512
+Node: Opening and Closing a LDAP Connection\7f2093064
+Node: Low-level Operations on a LDAP Server\7f2094879
+Node: LDAP Internationalization\7f2097600
+Node: LDAP Internationalization Variables\7f2098502
+Node: Encoder/Decoder Functions\7f2100233
+Node: Syntax of Search Filters\7f2101278
+Node: PostgreSQL Support\7f2102572
+Node: Building XEmacs with PostgreSQL support\7f2102964
+Node: XEmacs PostgreSQL libpq API\7f2104308
+Node: libpq Lisp Variables\7f2106184
+Node: libpq Lisp Symbols and DataTypes\7f2109178
+Node: Synchronous Interface Functions\7f2122435
+Node: Asynchronous Interface Functions\7f2126939
+Node: Large Object Support\7f2130441
+Node: Other libpq Functions\7f2131068
+Node: Unimplemented libpq Functions\7f2134105
+Node: XEmacs PostgreSQL libpq Examples\7f2139424
+Node: Internationalization\7f2145512
+Node: I18N Levels 1 and 2\7f2145855
+Node: I18N Level 3\7f2146558
+Node: Level 3 Basics\7f2146839
+Node: Level 3 Primitives\7f2147670
+Node: Dynamic Messaging\7f2149276
+Node: Domain Specification\7f2149736
+Node: Documentation String Extraction\7f2151403
+Node: I18N Level 4\7f2152318
+Node: MULE\7f2152507
+Node: Internationalization Terminology\7f2153553
+Node: Charsets\7f2165749
+Node: Charset Properties\7f2166442
+Node: Basic Charset Functions\7f2171154
+Node: Charset Property Functions\7f2173335
+Node: Predefined Charsets\7f2175550
+Node: MULE Characters\7f2178467
+Node: Composite Characters\7f2179342
+Node: Coding Systems\7f2180606
+Node: Coding System Types\7f2182743
+Node: ISO 2022\7f2186724
+Node: EOL Conversion\7f2198995
+Node: Coding System Properties\7f2200167
+Node: Basic Coding System Functions\7f2204490
+Node: Coding System Property Functions\7f2206524
+Node: Encoding and Decoding Text\7f2207082
+Node: Detection of Textual Encoding\7f2208218
+Node: Big5 and Shift-JIS Functions\7f2209754
+Node: Predefined Coding Systems\7f2210903
+Node: CCL\7f2222995
+Node: CCL Syntax\7f2226096
+Node: CCL Statements\7f2227669
+Node: CCL Expressions\7f2232299
+Node: Calling CCL\7f2234835
+Node: CCL Examples\7f2237837
+Node: Category Tables\7f2237971
+Node: Tips\7f2240327
+Node: Style Tips\7f2240966
+Node: Compilation Tips\7f2250841
+Node: Documentation Tips\7f2252752
+Node: Comment Tips\7f2258258
+Node: Library Headers\7f2261259
+Node: Building XEmacs and Object Allocation\7f2265227
+Node: Building XEmacs\7f2266107
+Node: Pure Storage\7f2272682
+Node: Garbage Collection\7f2275322
+Node: Standard Errors\7f2286163
+Node: Standard Buffer-Local Variables\7f2290369
+Node: Standard Keymaps\7f2293001
+Node: Standard Hooks\7f2296733
+Node: Index\7f2304231

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

diff --git a/info/lispref.info-1 b/info/lispref.info-1
index a440030..a035092 100644 (file)
--- a/info/lispref.info-1
+++ b/info/lispref.info-1
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -60,6 +60,8 @@ Reference Manual, corresponding to XEmacs version 21.0.
 * Copying::                 Conditions for copying and changing XEmacs.
 * Introduction::            Introduction and conventions used.
 
 * Copying::                 Conditions for copying and changing XEmacs.
 * Introduction::            Introduction and conventions used.
 

+* Packaging::               Lisp library administrative infrastructure.
+

 * 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.
 * 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.

@@ -180,6 +182,33 @@ Format of Descriptions
 * A Sample Function Description::
 * A Sample Variable Description::
 
 * A Sample Function Description::
 * A Sample Variable Description::
 

+Packaging
+
+* Package Overview::       Lisp Libraries and Packages.
+* Package Terminology::    Basic stuff.
+* Building Packages::      Turn packaged source into a tarball.
+* Local.rules File::       Tell the XEmacs Packaging System about your host.
+* Creating Packages::      Tell the XEmacs Packaging System about your package.
+* Issues::
+
+Package Overview
+
+* The User View::
+* The Library Maintainer View::
+* The Package Release Engineer View::
+
+The Library Maintainer's View
+
+* Infrastructure::    Global Makefiles and common rules.
+* Control Files::     Package-specific Makefiles and administrative files.
+* Obtaining::         Obtaining the XEmacs Packaging System and utilities.
+
+Creating Packages
+
+* package-info.in::             package-info.in
+* Makefile::                    `Makefile'
+* Makefile Targets::
+

 Lisp Data Types
 
 * Printed Representation::  How Lisp objects are represented as text.
 Lisp Data Types
 
 * Printed Representation::  How Lisp objects are represented as text.

@@ -847,7 +876,7 @@ Specifiers
 * Retrieving Specifications::  Querying a specifier's specifications.
 * Specifier Instancing Functions::
                                Functions to instance a specifier.
 * Retrieving Specifications::  Querying a specifier's specifications.
 * Specifier Instancing Functions::
                                Functions to instance a specifier.

-* Specifier Example::          Making all this stuff clearer.
+* Specifier Examples::         Making all this stuff clearer.

 * Creating Specifiers::                Creating specifiers for your own use.
 * Specifier Validation Functions::
                                Validating the components of a specifier.
 * Creating Specifiers::                Creating specifiers for your own use.
 * Specifier Validation Functions::
                                Validating the components of a specifier.

@@ -900,6 +929,7 @@ Glyphs
 * Redisplay Glyphs::    Glyphs controlling various redisplay functions.
 * Subwindows::          Inserting an externally-controlled subwindow
                           into a buffer.
 * Redisplay Glyphs::    Glyphs controlling various redisplay functions.
 * Subwindows::          Inserting an externally-controlled subwindow
                           into a buffer.

+* Glyph Examples::      Examples of how to work with glyphs.

 
 Glyph Functions
 
 
 Glyph Functions
 

@@ -1080,3 +1110,6308 @@ Building XEmacs and Object Allocation
 * Pure Storage::            A kludge to make preloaded Lisp functions sharable.
 * Garbage Collection::      Reclaiming space for Lisp objects no longer used.
 
 * Pure Storage::            A kludge to make preloaded Lisp functions sharable.
 * Garbage Collection::      Reclaiming space for Lisp objects no longer used.
 

+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Introduction,  Next: Packaging,  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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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)
+
+\1f
+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
+
+\1f
+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
+
+\1f
+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 ----------
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Packaging,  Next: Lisp Data Types,  Prev: Introduction,  Up: Top
+
+The XEmacs Packaging System
+***************************
+
+The XEmacs distribution, starting with version 21, comes only with a
+very basic set of built-in modes and libraries.  Most of the libraries
+that were part of the distribution of earlier versions of XEmacs are now
+available separately.  The user as well as the system administrator can
+choose which packages to install; the actual installation process is
+easy.  This gives an installer the ability to tailor an XEmacs
+installation for local needs with safe removal of unnecessary code.
+
+   This chapter describes how to package Lisp libraries for use with the
+XEmacs Packaging System.
+
+   _Please note carefully_ that the term "package" as used in XEmacs
+refers to an aggregation of Lisp code and/or data distributed as a
+unit.  It does not, as it does in many Lisps, refer to a way of
+creating separate name spaces.  XEmacs has no facility for providing
+separate name spaces.  (If we ever do get separate name spaces, we'll
+probably regret overloading the nomenclature in this way, but it's
+become established.)
+
+* Menu:
+
+Introduction:
+* Package Overview::            Lisp Libraries and Packages.
+
+Packaging Lisp Libraries:
+* Package Terminology::         Basic stuff.
+* Building Packages::           Turn packaged source into a tarball.
+* Makefile Targets::            Package `Makefile' targets
+* Local.rules File::            Tell the XEmacs Packaging System about your host.
+* Creating Packages::           Tell the XEmacs Packaging System about your package.
+* Documenting Packages::        Explain your package to users and hackers.
+
+Internals and Package Release Engineering:
+* Issues::
+
+\1f
+File: lispref.info,  Node: Package Overview,  Next: Package Terminology,  Up: Packaging
+
+An overview of the XEmacs Packaging System
+******************************************
+
+The XEmacs Packaging System is a system for administering the
+installation, upgrade, and removal of Lisp libraries.  For the end
+user, it provides facilities for determining availability of packages
+and which versions at remote sites.  It will download and automatically
+install a package, ensuring that any old files from previous versions
+of the package are removed first.  By providing a standard set of
+hierarchies for installation, it makes configuration of XEmacs simpler.
+Furthermore, packages normally provide ancillary auto-autoloads and
+custom-loads libraries, which are automatically detected and loaded by
+XEmacs upon startup.  This means that once installed, all facilities of
+package, including autoloading the library upon invocation of a command
+provided by the library and convenient configuration and customization,
+are automatically available to the user.  There is no need to add
+autoloads or keybindings to in the init file, and structured
+configuration of the package is available through the Customize system
+even before the libraries are loaded.
+
+   All of this convenience comes at a cost.  The cost of administration
+at the package level is negligible compared to the benefits, of course.
+However, the requirement that XEmacs find and load auto-autoloads and
+custom-loads libraries comes at a fairly large cost in startup time.  In
+order to reduce this cost, XEmacs imposes fairly strict conditions on
+the structure of an installed package.
+
+   Meeting these requirements, as well as simply providing the
+auto-autoloads and the information about availability and so on does
+impose some costs on the library maintainer.  The XEmacs Packaging
+System also provides structure and utilities to the library maintainer
+to make these tasks easier.  This manual documents the requirements and
+the tools that the XEmacs Packaging System provides to ensure that a
+package satisfies them.
+
+* Menu:
+
+* The User View::
+* The Library Maintainer View::
+* The Package Release Engineer View::
+
+\1f
+File: lispref.info,  Node: The User View,  Next: The Library Maintainer View,  Up: Package Overview
+
+The User View
+=============
+
+*N.B.*  Much of the discussion in this section undoubtedly belongs
+elsewhere, *Note Packages: (xemacs)Packages.
+
+   From the user's point of view, an XEmacs binary package is simply a
+standard tarball (usually gzipped) containing Lisp sources, compiled
+Lisp, documentation, and possibly data files or supporting executables.
+The tarball is unpacked using standard tools such as GNU tar and gzip.
+The package system does impose certain requirements for automatic
+configuration to work.
+
+   Here the main consideration is that the tarball "expects" to be
+unpacked from the top of a package hierarchy.  A "package hierarchy" is
+basically an image of a classic Emacs "run-in-place" tree, with `lisp',
+`etc', `info', `man', `lib-src', and `pkginfo' subdirectories of the
+top.  The `pkginfo' subdirectory is for use by the XEmacs Packaging
+System administration tools, and currently contains a
+`MANIFEST.PACKAGE-NAME' file for each package to ensure that no cruft
+remains when a package is removed or updated.  The `lisp', `etc', and
+`lib-src' subdirectories are further subdivided, with a subdirectory
+for each package.  The `info' directory obeys the usual conventions.
+_I.e._, the `info' directory is flat with a(n) (optional) `dir' file
+and one (set of) info file(s) per package.  The `man' subdirectory
+typically contains documentation sources, separated by package.  (It
+does not contain `man(1)' pages, as Emacs provides very few of them.)
+
+   There are several standard package hierarchies, and administrators
+can configure others at build time, while users can configure others at
+run time.  The standard system hierarchies are all subdirectories of an
+XEmacs installation root, typically `/usr/local/lib/xemacs/'.  These
+are the `xemacs-packages', `mule-packages', `infodock-packages', and
+`site-packages' hierarchies.  Each has the structure described above,
+but the purposes differ.  The `xemacs-packages' is the normal place for
+installing "official" packages and many third-party libraries.
+Unfortunately, it is not yet quite possible to read libraries
+containing international characters with a non-Mule XEmacs, so such
+libraries are sequestered in the `mule-packages' hierarchy.  Some
+packages are compatible only with the Infodock development environment,
+and they will be installed in the `infodock-packages' hierarchy.  The
+`site-packages' hierarchy is for packages not distributed by
+XEmacs.org, typically locally developed.
+
+   Packages are in principle supposed to be XEmacs version-independent,
+but if such dependencies are unavoidable, additional standard package
+hierarchies may be installed under version directories, _e.g._
+`/usr/local/lib/xemacs-21.4.6/'.
+
+   Users who do not have sufficient privilege to install packages in the
+system hierarchies may install package hierarchies under `~/.xemacs'.
+At present only the `xemacs-packages', `mule-packages', and
+`site-packages' hierarchies are supported, but it might make sense to
+extend this to support `infodock-packages' hierarchies in the future.
+
+   The package hierarchies are not searched directly for libraries to be
+loaded; this would be very costly.  Instead, the hierarchies are ordered
+according to certain rules, and searched for package lisp directories at
+invocation.  These directories are added to the general `load-path'.
+As usual, it is `load-path' that is searched at run-time.  This
+approach is somewhat costly at initialization, but results in a very
+"clean" `load-path'.
+
+   The order of search can be changed at build time by specifying the
+`--package-path' option to `configure', or at run-time by specifying
+the `EMACSPACKAGEPATH' environment variable.  *Note Packages:
+(xemacs)Packages.
+
+   The default order of search is hierarchically determined.  First, the
+roots are ordered.  The "early" roots are the user-specific roots,
+typically `~/.xemacs'.  The "late" roots are the system roots,
+typically `/usr/local/lib/xemacs-21.4.6' and `/usr/local/lib/xemacs',
+in that order.  All hierarchies for a given root are searched for
+package Lisp directories, which are appended to `load-path' in the
+order found.  Then the search proceeds to the next root, whose results
+will be appended to the `load-path' generated by previous roots.
+
+   Second, the hierarchies below each root are searched in the order
+`site-packages', `infodock-packages', `mule-packages', then
+`xemacs-packages'.
+
+   In each hierarchy there should be a `lisp' subdirectory, containing
+directories named for the packages.  Each package's Lisp libraries thus
+are contained in a directory of the form ROOT/HIERARCHY/lisp/PACKAGE/.
+
+   With such a complex search algorithm, the possibility of libraries
+being shadowed by another library with the same name is quite real.
+There are two considerations here.  First, every XEmacs package
+contains certain libraries with constant names.  These are
+
+`_pkg.el'
+     Lisp code to inform the package administration system about the
+     package
+
+`auto-autoloads.el'
+     Lisp code to set up autoloaded functions and variables that may be
+     needed at load time
+
+`custom-load.el'
+     definitions of configuration variables for use with the Customize
+     system.
+
+   They are special-cased, because the way they are used prevents
+shadowing from being an issue.
+
+   Second, it is possible that multiple copies of some library, or
+different libraries with the same name, are installed in various places
+in the hierarchies.  To detect such shadows, use
+`list-load-path-shadows'.
+
+   Finally, note that most basic Emacs functionality, including most of
+the Lisp API, is implemented in Lisp libraries.  Because they use
+internal reserved APIs that are subject to change according the needs
+of the developers, these libraries are distributed with the XEmacs
+binary, and are called "core Lisp libraries".  Most core Lisp libraries
+are "preloaded" into the Emacs binary and in normal usage are never
+explicitly loaded.  However, they can be explicitly loaded, and if so
+they are searched on `load-path'.  Furthermore, functions such as
+`locate-library' will also search on the `load-path'.  The searching
+takes place under somewhat different rules from those used for packaged
+Lisp.  It is probably easiest to think of the package hierarchy
+searching algorithm as receiving a `load-path' initialized to the core
+Lisp directories.
+
+\1f
+File: lispref.info,  Node: The Library Maintainer View,  Next: The Package Release Engineer View,  Prev: The User View,  Up: Package Overview
+
+The Library Maintainer View
+===========================
+
+From the library maintainer's viewpoint, the advantages to the XEmacs
+Packaging System stem from the convenience to the user of installation
+and upgrade.  Since an installed package automatically registers its
+entry points via autoload and its configuration variables with the
+Customize system, configuration FAQs are reduced.  When it's easy to
+upgrade, users learn to try `Tools | Packages | Update Installed
+Packages' before posting a FAQ whose answer is "long since fixed,
+please upgrade."
+
+   This comes at some cost, as the library maintainer needs to arrange
+that the package be installed in a directory structure that satisfies
+the requirements of the XEmacs Packaging System.  Autoload cookies and
+defcustoms must also be added to existing libraries.  The XEmacs
+Packaging System provides infrastructure to assure that all of these
+annoyances need only be dealt with once.  The autoload cookies and
+defcustoms are beyond the scope of this chapter, but most maintainers
+of modern packages are already familiar with these mechanisms.
+
+   The XEmacs Packaging System may be divided into the "infrastructure"
+common to all packages, and the package-specific "control files".  The
+infrastructure supports global builds, installation, and generation of
+the "sumo" bundles of packages, as well as generation of individual
+packages.  The package control files describe the structure of the
+package's source tree and provide administrative information.
+
+* Menu:
+
+* Infrastructure::              Global Makefiles and common rules.
+* Control Files::               Package-specific Makefiles and administrative files.
+* Obtaining::                   Obtaining the XEmacs Packaging System and required utilities.
+
+\1f
+File: lispref.info,  Node: Infrastructure,  Next: Control Files,  Up: The Library Maintainer View
+
+Infrastructure
+--------------
+
+In order to get the greatest benefit from the XEmacs Packaging System,
+a library maintainer should place the package sources in an appropriate
+place in the XEmacs source package hierarchy, and arrange to have the
+source package imported into the XEmacs CVS repository.  (We realize
+that the latter requirement can be quite burdensome.  We are working on
+ways to remove this requirement, but for the present it remains
+necessary.)  The library maintainer must also keep sources for any
+packages his/her package requires.  This requirement is somewhat
+burdensome, but unlikely to be relaxed because of the implementation of
+compilation of macros in Emacs Lisp.  Macros cannot be called by
+compiled Lisp (the macro expansion, which is always known at compile
+time, is inlined), so the source of the macro must be loaded before
+compiling the called function.
+
+   The source package hierarchy may be rooted anywhere.  The CVS module
+is called "packages," so we will refer to the top directory of the
+source package hierarchy as "the `packages' directory."  The `packages'
+directory contains two source subdirectories, `xemacs-packages' and
+`mule-packages' (for convenience in segregating the packages which
+depend on Mule, as they will cause load-time errors in a non-Mule
+XEmacs).  Each subdirectory contains many package source directories,
+whose internal structure is not specified.  That structure is left up
+to the convenience of the library maintainers.  The requirements on the
+top directory of an individual package source tree are given below,
+*Note Control Files::.
+
+   The `packages' directory contains some auxiliary Lisp libraries used
+in the compilation and packaging process.  The content of these
+libraries is of interest primarily to the packaging engineers, *Note
+The Package Release Engineer View::.
+
+   Finally, the `packages', `packages/xemacs-packages', and
+`packages/mule-packages' directories contain `Makefile's and include
+files to control the package creation process.  The `Makefile's in
+`packages/xemacs-packages' and `packages/mule-packages' simply define
+the default sets of known packages and include `../iterate.rules',
+which implements recursive building of all target packages.
+
+   The `make' infrastructure in `packages' includes
+
+`Makefile'
+     controls building of individual packages, local installation, and
+     bundling of "sumo" tarballs
+
+`iterate.rules'
+     controls recursive builds of multiple packages
+
+`meta-iterate.rules'
+     This is used by higher-level subdirectories that do not directly
+     contain packages.  Subdirectories directly containing packages
+     should use iterate.rules instead.
+
+`XEmacs.rules'
+     provides the rules for building and packaging.  Included by all
+     package `Makefile's.
+
+`Local.rules'
+     provides local configuration, such as installation targets and
+     staging directories, as well as a number of kludges (many now
+     obsolete) required for building packages on the Windows platform.
+
+`Local.rules.template'
+     a template for Local.rules, liberally commented
+
+`Local.rules.mk'
+     consistency checking for `Local.rules', included by both the
+     top-level `Makefile' and by `XEmacs.rules'.
+
+`Local.rules.inc'
+     a file to `include' in package `Makefile's to be able to get at
+     variables in `Local.rules' _before_ including `XEmacs.rules'.
+
+`package-compile.el'
+     compile environment (_e.g._, load-path) setup.
+
+   Of these, only `Local.rules' and `package-compile.el' need to be
+modified by the library maintainer.  The changes to Local.rules affect
+only your environment.  This should need to be done only once when
+first preparing the source environment.  The necessary modifications to
+`package-compile.el' need to be done for each package and are discussed
+in the next section, *Note Control Files::.
+
+\1f
+File: lispref.info,  Node: Control Files,  Next: Obtaining,  Prev: Infrastructure,  Up: The Library Maintainer View
+
+Control Files
+-------------
+
+Each package source must contain a number of control files in the
+top-level directory.  These files in general can be created and then
+ignored, except for a few variables that need to be updated when new
+versions are released.  In most cases even adding, renaming, and
+removing library source files can be handled by generic rules.
+
+   The package control files include
+
+`Makefile'
+     Must set a few `make' variables used by the administrative
+     utilities, and defines a couple of package-building targets to
+     depend on appropriate targets defined generically in
+     `XEmacs.rules'.  It may also provide various variables and rules
+     to transform the source tree structure into that expected by the
+     run-time system.
+
+`package-info.in'
+     Provides a template for package information to be provided to the
+     administrative utilities.  Static variables that are rarely changed
+     (such as the package's name) are entered as literals.  Some
+     variables are generated by the build process (build dates and MD5
+     checksums) and are automatically filled in.  Finally, some
+     variables that change irregularly (dependences and even version
+     numbers) are set as `make' variables in the `Makefile'.
+
+`ChangeLog'
+     Not strictly required, but normally a ChangeLog will be added by
+     the XEmacs package maintainer if different from the upstream
+     maintainer.
+
+`_pkg.el'
+     Generated.  Simply does a `package-provide' for the package.
+
+`auto-autoloads.el'
+     Generated.  Read when XEmacs is initialized, and provides
+     autoloads for defuns and other forms in the sources that are
+     marked with an "autoload cookie" (`;;;###autoload'.
+
+`custom-loads.el'
+     Generated.  Read when XEmacs is initialized, and informs the
+     Customize subsystem how to find the defcustom forms needed to
+     create Customization forms for the usre configuration variables of
+     the package.
+
+\1f
+File: lispref.info,  Node: Obtaining,  Prev: Control Files,  Up: The Library Maintainer View
+
+Obtaining the XEmacs Packaging System and Required Utilities
+------------------------------------------------------------
+
+Currently both the infrastructure for creating XEmacs packages and the
+package sources themselves are available only by CVS.  See
+`http://www.xemacs.org/Develop/cvsaccess.html' for more intformation.
+
+   The XEmacs Packaging System currently requires GNU `make', and
+XEmacs, to build packages.
+
+\1f
+File: lispref.info,  Node: The Package Release Engineer View,  Prev: The Library Maintainer View,  Up: Package Overview
+
+The Package Release Engineer View
+---------------------------------
+
+The XEmacs Package Release Engineer is responsible for keeping the
+system coherent.  The changes to `packages/package-compile.el' and
+`packages/xemacs-packages/Makefile' required to make the package
+available to others, and for building SUMO tarballs, _etc_, are done by
+the Package Release Engineer, not individual library maintainers.
+
+   The Package Release Engineer also maintains assorted infrastructure
+for actually making releases.  These are generally available for
+inspection in the `xemacs-builds' module in the CVS repository.
+
+\1f
+File: lispref.info,  Node: Package Terminology,  Next: Building Packages,  Prev: Package Overview,  Up: Packaging
+
+Package Terminology:
+====================
+
+Libraries and Packages
+----------------------
+
+A Lisp "library" is a single loadable file containing Lisp code.  It
+may be in source or byte-compiled form.  A Lisp "package" is a set of
+one or more libraries, usually related to each other in some way,
+bundled with administrative information for convenient distribution.
+
+Package Flavors
+---------------
+
+There are two main flavors of packages.
+
+*Regular Packages*
+     A regular package is a set of Lisp libraries design to cooperate
+     with one another.  A very complex example is Gnus.  One may not in
+     general safely remove any of the component libraries.
+
+*Single-File Packages*
+     A single-file package is a collection of thematically related but
+     otherwise independent Lisp libraries.  These libraries are bundled
+     together for convenience of the maintainers.  Usually individual
+     libraries may be deleted at will without any loss of functionality
+     of other libraries in the package.  However, we would recommend
+     that you follow this rule of thumb: "When in doubt, don't delete".
+     If it's really that big a deal, request that the maintainers
+     split the package into smaller aggregations.
+
+Package Distributions
+---------------------
+
+XEmacs Lisp packages are distributed in two ways.  "Binary packages"
+are used by system administrators and end users.  They are packaged in a
+form convenient for direct installation into an XEmacs package
+hierarchy.  "Source packages" are for developers and include all files
+necessary for rebuilding byte-compiled lisp and creating tarballs for
+distribution or installation.  This is all of the package author's
+source code plus all of the files necessary to build distribution
+tarballs (Unix Tar format files, gzipped for space savings).
+(Occasionally sources that are not relevant to XEmacs are usually
+renamed to `file.upstream'.)
+
+   Currently, source packages are only available via CVS.  See
+<http://www.xemacs.org/Develop/cvsaccess.html> for details.
+
+   The package distributions are also split according to major features
+required in XEmacs to support them.  At present there are "generic"
+packages, which can be loaded by _any_ XEmacs, and "Mule" packages,
+which _require_ Mule support or they will cause errors when loaded.
+Note that there is no guarantee that a generic package will have any
+useful functionality in a minimally configured XEmacs.  As long as any
+XEmacs can successfully load the package's libraries (perhaps given
+other required Lisp libraries), it will be classified as generic.  At
+the present time only Mule packages need be treated specially, and even
+those only if they contain multibyte characters.
+
+\1f
+File: lispref.info,  Node: Building Packages,  Next: Makefile Targets,  Prev: Package Terminology,  Up: Packaging
+
+Building Packages:
+==================
+
+Currently, source packages are only available via anonymous CVS.  See
+<http://www.xemacs.org/Develop/cvsaccess.html> for details of checking
+out the `packages' module.
+
+Prerequisites for Building Source Packages
+------------------------------------------
+
+`GNU cp'
+
+`GNU install'
+     (or a BSD compatible install program).
+
+`GNU make'
+     (3.79 or later preferred).
+
+`makeinfo'
+     (4.2 from texinfo-4.2)
+
+`GNU tar'
+     (or equivalent).
+
+`GNU gzip'
+     (or equivalent).
+
+`A properly configured `Local.rules' file.'
+     *Note Local.rules File::.
+
+   And of course, XEmacs, 21.0 or higher.
+
+What You Can Do With Source Packages
+====================================
+
+The packages CVS sources are most useful for creating XEmacs package
+tarballs for installation into your own XEmacs installations or for
+distributing to others.
+
+   It should be noted that most of the package `Makefile's do _not_
+need to contain _any_ target rules.  Everything is handled from the
+`XEmacs.rules' file, located in the toplevel directory of the packages
+source tree.
+
+\1f
+File: lispref.info,  Node: Makefile Targets,  Next: Local.rules File,  Prev: Building Packages,  Up: Packaging
+
+`Makefile' targets
+******************
+
+The following targets can be used when running `make' to build the
+packages:
+
+`mostlyclean'
+     Removes any documentation files that have been processed by TeX.
+
+`clean'
+     Does a `mostlyclean', plus removes generated postscript and dvi
+     files.  Also removes any generated .elc files, along with the
+     normal .elc files in the package and HTML and .info files.
+
+`distclean'
+     Use this when preparing a distribution.  It kills anything that
+     can be rebuilt.
+
+`extraclean'
+     Does a `distclean' and also removes any backup files (`*~') and
+     `core' files.
+
+`package-info'
+     Creates the `package-info' file from the `package-info.in' and
+     writes an entry in the `package-index' file.
+
+`bindist'
+     Builds the package, including any Texinfo documentation (info
+     format), writes an entry into the `package-index' file and builds
+     a tarball of the package.  Also writes an entry into
+     `setup-packages.ini' which is later used in the creation of
+     netinstaller's `setup.ini'.
+
+`install'
+     Builds and installs a package
+
+`install-only'
+     Doesn't build anything, just installs it.
+
+`autoloads'
+     Generate the package's `auto-autoloads.el' file.
+
+`binkit'
+     Creates the directories needed for installation and copies the
+     files there.  Basically this is an alias for `install-only'.
+
+`html'
+     Builds the HTML versions of the documentation.
+
+`compile'
+     Does most of the work.  Builds the elcs, infos at a minimum.
+
+The targets that most people would be interested in would be:
+-------------------------------------------------------------
+
+   * `all'
+
+   * `bindist'
+
+   * `html'
+
+   * `install'
+
+   * `install-only'
+
+   * `clean'
+
+   * `distclean'
+
+\1f
+File: lispref.info,  Node: Local.rules File,  Next: Creating Packages,  Prev: Makefile Targets,  Up: Packaging
+
+The Local.rules File:
+=====================
+
+This file in `packages' provides the XEmacs Packaging System with
+information about the local configuration and environment.  To create
+`Local.rules', simply copy `Local.rules.template' from that directory to
+`Local.rules' and edit it to suit your needs.
+
+   These are the variables in `Local.rules' that you may need to
+provide values for:
+
+`XEMACS'
+     The name (and path if needed) of the XEmacs binary to use for
+     building the packages.  The default is `xemacs'.
+
+`XEMACS_21_5'
+     This will enable some, as yet, unimplemented features in XEmacs
+     21.5 and above.  For now leave this blank (the default) regardless
+     of the XEmacs version you are using.
+
+`BUILD_WITHOUT_MULE'
+     Set this to `t' if you are using a non-Mule XEmacs.  The default is
+     that this variable is not set (blank) which means to build _with_
+     Mule.
+
+`XEMACS_NATIVE_NT'
+     Set this to `t' if you are using a native Microsoft Windows build
+     of XEmacs (not a Cygwin build) to build the packages.  *N.B.* To
+     Windows users, you still need the Cygwin environment to actually
+     build the packages.
+
+`XEMACS_INSTALLED_PACKAGES_ROOT'
+     Set this to the root of where you want the packages to be
+     installed.  Under this directory will hang `xemacs-packages' and
+     `mule-packages'.  See NONMULE_INSTALLED_PACKAGES_ROOT and
+     MULE_INSTALLED_PACKAGES_ROOT.  The default for this is
+     `/usr/local/lib/xemacs'.  Which may not be what you want if you are
+     developing XEmacs.  To quote the comments in
+     `Local.rules.template':
+
+          If you are developing XEmacs, you probably don't want to
+          install the packages under /usr/local, which is where the
+          stable, released version of XEmacs goes.  Instead, we suggest
+          a layout as described in the base README file of recent
+          versions of XEmacs.  In a nutshell, we suggest you put your
+          source under /src/xemacs, and under this put the package
+          sources in package-src/, and the installed packages in
+          xemacs-packages/ and mule-packages/.  If you do everything
+          this way, you might want to set things as follows:
+
+          XEMACS_INSTALLED_PACKAGES_ROOT = ${XEMACS_PACKAGES_BASE}/..
+
+          which puts the xemacs-packages/ and mule-packages/
+          directories as sisters of the package-src/ directory, and you
+          have to tell configure the location of the installed packages
+          using `-package-path', something like
+
+          configure
+          -package-path=/src/xemacs/xemacs-packages;/src/xemacs/mule-packages
+
+`symlink'
+     The default is unset (blank).  If you set this to `t' then `make
+     install' will create a "symlink farm" of the installed packages
+     under XEMACS_INSTALLED_PACKAGES_ROOT.  Obviously, for this to
+     work, your system has to support symbolic links.  This is as close
+     as you can get to "running in place" for the packages.
+
+`NONMULE_INSTALLED_PACKAGES_ROOT'
+     This is where the non-Mule packages get installed to.  The default
+     is `${XEMACS_INSTALLED_PACKAGES_ROOT}/xemacs-packages'.
+
+`MULE_INSTALLED_PACKAGES_ROOT'
+     This is where the Mule packages get installed to.  The default is
+     `${XEMACS_INSTALLED_PACKAGES_ROOT}/mule-packages'.
+
+`NONMULE_PACKAGES'
+     A whitespace separated list of non-Mule packages to build/install.
+
+          NONMULE_PACKAGES = bbdb gnus xemacs-base prog-modes
+
+     The value for this variable can also be the symbol
+     `xemacs-packages', which means to build/install _all_ of the
+     non-Mule packages.  The default is `xemacs-packages'.
+
+`MULE_PACKAGES'
+     A whitespace separated list of Mule packages to build/install.
+
+          MULE_PACKAGES = mule-base leim locale
+
+     The value for this variable can also be the symbol
+     `mule-packages', which means to build/install _all_ of the Mule
+     packages.  The default is `mule-packages'.
+
+`PACKAGE_INDEX'
+     The name of the package-index file.  The default is `package-index'
+     and you probably don't need to worry about changing it.
+
+`INSTALL'
+     The path to a BSD compatible install program.  The default is
+     `install -c'.
+
+`TAR'
+     The path to GNU/tar.  The default is `tar'.
+
+`BZIP2'
+     The path to the bzip2 compression program.  The default is unset
+     (blank).  If this is set `.tar.bz2' archives will be built _in
+     addition to_ the `.tar.gz' archives.
+
+`EXCLUDES'
+     For things that you _don't_ want to go into the package tarballs.
+     It takes the same format as GNU/tar's `--exclude' option.  The
+     default is:
+
+          EXCLUDES =                                   \
+               --exclude 'CVS'                         \
+               --exclude 'RCS'                         \
+               --exclude 'SCCS'                        \
+               --exclude '*~'                          \
+               --exclude '*.orig'                      \
+               --exclude '*.rej'                       \
+               --exclude '.\#*'
+
+`VANILLA'
+     Set to the XEmacs command line option that forces running in
+     "vanilla" mode.  The default is `-vanilla'.  You wouldn't ever
+     need to alter this.
+
+`BATCH'
+     How to put XEmacs into "batch" mode.  It also sets a couple of
+     other things and in the normal course of events you wouldn't need
+     to alter this from the default which is:
+
+          BATCH = $(VANILLA) -batch -eval \
+                  '(setq stack-trace-on-error t \
+                         load-always-display-messages t \
+                         load-ignore-out-of-date-elc-files t \
+                         load-show-full-path-in-messages t)'
+
+`MAKEINFO'
+     The path to `makeinfo'.  The default is `makeinfo'
+
+`INSTALL_HTML'
+     Set this to `t' if you want to install HTML versions of the Texinfo
+     documentation.  The default is unset (blank).
+
+`TEXI2HTML'
+     The path to the program that can convert Texinfo source to HTML.
+     The default is `texi2html'.
+
+`TEXI2DVI'
+     The path to the program that can convert Texinfo source to DVI.
+     The default is `texi2dvi'
+
+`DVIPS'
+     The path to the program that can convert DVI to Postscript.  The
+     default is `dvips'
+
+`TEXI2PDF'
+     The path to the program that can convert Texinfo source to PDF
+     format.  The default is `texi2pdf'.
+
+`TEX'
+     The path to TeX.  The default is `tex'
+
+`MSGFMT'
+     The path to msgfmt.  The default is `msgfmt'
+
+`RCOPY'
+     The path to your copy command (GNU cp).  The default is dependent
+     on whether or not SYMLINK is set (`t').
+
+     If SYMLINK is unset (blank), RCOPY's default is `cp -af'.  If
+     SYMLINK is set (`t'), RCOPY's default is `cp --force --recursive
+     --symbolic-link'.
+
+   It should be noted that in most cases the defaults should be fine.
+Most people will probably only need to alter:
+
+   * XEMACS_INSTALLED_PACKAGES_ROOT
+
+   * NONMULE_INSTALLED_PACKAGES_ROOT
+
+   * MULE_INSTALLED_PACKAGES_ROOT
+
+   * NONMULE_PACKAGES
+
+   * MULE_PACKAGES
+
+\1f
+File: lispref.info,  Node: Creating Packages,  Next: Documenting Packages,  Prev: Local.rules File,  Up: Packaging
+
+Creating Packages:
+******************
+
+Creating a package from an existing Lisp library is not very difficult.
+
+   In addition to the Lisp libraries themselves, you need a *Note
+package-info.in:: file and a simple *Note Makefile::.  The rest is done
+by `XEmacs.rules', part of the packaging system infrastructure.
+
+* Menu:
+
+* package-info.in::             package-info.in
+* Makefile::                    `Makefile'
+
+\1f
+File: lispref.info,  Node: package-info.in,  Next: Makefile,  Up: Creating Packages
+
+package-info.in
+***************
+
+`package-info.in' contains information that gets injected into the
+`package-index' file when `make bindist' is run.  Here is a real world
+example from the xemacs-base package (a description of each field
+follows the example):
+
+     (xemacs-base
+       (standards-version 1.1
+        version VERSION
+        author-version AUTHOR_VERSION
+        date DATE
+        build-date BUILD_DATE
+        maintainer MAINTAINER
+        distribution xemacs
+        priority high
+        category CATEGORY
+        dump nil
+        description "Fundamental XEmacs support, you almost certainly need this."
+        filename FILENAME
+        md5sum MD5SUM
+        size SIZE
+        provides (add-log advice-preload advice annotations assoc case-table chistory comint-xemacs comint compile debug ebuff-menu echistory edmacro ehelp electric enriched env facemenu ffap helper imenu iso-syntax macros novice outline passwd pp regexp-opt regi ring shell skeleton sort thing time-stamp timezone tq xbm-button xpm-button)
+        requires (REQUIRES)
+        type regular
+     ))
+
+Description of the Fields in `package-info.in':
+-----------------------------------------------
+
+`NAME'
+     The name of the package.  In the case of the example it is
+     `xemacs-base'.
+
+`standards-version'
+     Part of the internal package infrastructure, its value should
+     always be `1.1'.  Do not change this.
+
+`version'
+     This is the XEmacs package version number of the package.  It is
+     set from the `Makefile' variable VERSION.  This is something that
+     the XEmacs Package Release Engineer deals with so there is no need
+     for a package maintainer to touch it.  In `package-info.in' just
+     put the place-marker, `VERSION' here.
+
+`author-version'
+     This is the package's internal, or `upstream' version number if it
+     has one.  It is set from the `Makefile' variable AUTHOR_VERSION.
+
+`date'
+     This is the date of the last change made to the package.  It is
+     auto-generated at build time, taken from the package's toplevel
+     `ChangeLog'.
+
+`build-date'
+     The date the package was built.  It is auto-generated.
+
+`maintainer'
+     This is the name and email address of the package's maintainer.
+     It is taken from the `Makefile' variable MAINTAINER.
+
+`distribution'
+     An unused field, leave as `xemacs'
+
+`priority'
+     An unused field, can be any of `high', `medium', or `low'.
+
+`category'
+     The `category' of the package.  It is taken from the `Makefile'
+     variable CATEGORY and can be either `standard' for non-Mule
+     packages, or `mule' for Mule packages.  The is also provision for
+     `unsupported' in this field which would be for packages that
+     XEmacs.org do not distribute.
+
+     *N.B.* As yet, the XEmacs Packaging System does _not_ support this
+     type of package.  It will in the future.
+
+`dump'
+     Unused.  Always `nil'
+
+`description'
+     A free form short description of the package.
+
+`filename'
+     The file name of the package's binary tarball.  It is generated at
+     build time by `make bindist'.
+
+`md5sum'
+     The MD5 message digest of the package's binary tarball.  Generated
+     at build time by `make bindist'.
+
+`size'
+     The size in bytes of the package's binary tarball.  Generated at
+     build time.
+
+`provides'
+     A whitespace separated list of _all_ the features the package
+     provides.  Surround the list with parens.
+
+`requires'
+     Taken from the `Makefile' variable REQUIRES.  It is a list of all
+     the package's dependencies, including any macros and defstructs
+     that need to be inlined.
+
+     `REQUIRES' cannot be correctly computed from the calls to
+     `require' in the package's library sources.  `REQUIRES' is used to
+     ensure that all macro and defstruct definitions used by the
+     package are available at build time.  This is not merely a matter
+     of efficiency, to get the expansions inlined.  In fact, it is
+     _impossible_ to call a macro by name in byte-compiled Emacs Lisp
+     code.  Thus, if the macro expansion is not inlined, the call will
+     result in an error at run-time!  Thus, packages providing
+     libraries that would be loaded because of autoload definitions
+     must also be included.
+
+`type'
+     Can either be `regular' for a regular package, or `single-file'
+     for a single file package.
+
+     *N.B.* This doesn't refer to the number of lisp files in a
+     package.  A single-file package can have multiple lisp files in it.
+     *Note Package Terminology::.
+
+   The fields in `package-info.in' that need to be changed directly are:
+
+   * NAME
+
+   * description
+
+   * provides
+
+   * type
+
+   Everything else is either set from the appropriate `Makefile'
+variable, is auto-generated at build time, or is static.
+
+\1f
+File: lispref.info,  Node: Makefile,  Prev: package-info.in,  Up: Creating Packages
+
+`Makefile'
+**********
+
+The `Makefile' is quite stylized.  The idea is similar to an
+`Imakefile' or an `automake' file: the complexity is hidden in generic
+rules files, in this case the `XEmacs.rules' include file in the top
+directory of the packages hierarchy.
+
+   It is important to note that the XEmacs used to compile packages is
+the bare minimum: it is called with the `-no-autoloads'.  This means
+that anything not dumped into XEmacs by default needs to be specified
+in the `REQUIRES' variable (for packaged Lisp) or in some cases the
+`PRELOADS' (autoloads used in libraries mentioned in `PRELOADS').
+
+   There isn't much to an XEmacs Packaging System `Makefile', basically
+it just contains a few `Makefile' variables and that's it.  See the
+example.
+
+   Here is a real world example, from the `build' package:
+
+     # Makefile for build lisp code
+     
+     # This file is part of XEmacs.
+     
+     # XEmacs 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, or (at your option) any
+     # later version.
+     
+     # XEmacs 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 XEmacs; see the file COPYING.  If not, write to
+     # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     # Boston, MA 02111-1307, USA.
+     
+     # For the time being, remove MULE_ELCS from the all dependencies if
+     # building without Mule.
+     
+     VERSION = 1.10
+     AUTHOR_VERSION = 2.02
+     MAINTAINER = Adrian Aichner <adrian@xemacs.org>
+     PACKAGE = build
+     PKG_TYPE = regular
+     REQUIRES = xemacs-base pcl-cvs dired w3 prog-modes
+     CATEGORY = standard
+     
+     ELCS = build.elc build-report.elc
+     
+     STANDARD_DOCS = t
+     
+     include ../../XEmacs.rules
+
+   Most packages don't need any more than what you see above.  It is
+usually _not_ necessary to specify any special `Makefile' rules.
+Everything is handled from the `*.rules' files in the toplevel of the
+package source hierarchy.
+
+   Of course, with that said, there are always exceptions to the rule.
+If you think that your package will need some special `Makefile'
+hackery contact the XEmacs developers <xemacs-beta@xemacs.org>.  We
+distribute over 100 packages so the chances are good that you won't be
+the first to need such hackery and it is probably already catered for.
+
+`Makefile' Variables Explained:
+-------------------------------
+
+A number of `make' variables are defined by the XEmacs Packaging
+System.  Some are required, others are optional.  Of course your
+`Makefile' may define other variables for private use, but you should
+be careful not to choose names that conflict with variables defined and
+used by the XEmacs Packaging System.
+
+   The required variables are described in the table below.  The
+corresponding field names for `package-info.in', where relevant, are
+given in parentheses.
+
+`VERSION'
+     (version) The version of the XEmacs package, a numeric literal (a
+     decimal fixed-point number with two-places of precision).  The
+     only person who ever needs to touch this is the XEmacs Packages
+     Release Engineer.
+
+`AUTHOR_VERSION'
+     (author-version) The upstream author's version, an uninterpreted
+     literal.
+
+`MAINTAINER'
+     (maintainer) A literal containing the XEmacs package's maintainer
+     and his/her email address.
+
+`PACKAGE'
+     The name of the package, a literal
+
+`PKG_TYPE'
+     The type of package, a literal containing either `regular' for
+     regular packages, or `single-file' for single-file packages.  This
+     should feed the `type' field in `package-info.in', but currently
+     it doesn't.
+
+     *N.B.* `single-file' here does _not_ refer to the number of lisp
+     files in a package. *Note Package Terminology::.
+
+`CATEGORY'
+     (category) A literal, either `standard' or `mule'.  The non-Mule
+     packages are `standard' and the Mule packages are, you guessed it,
+     `mule'.  This field is used at package installation time as part of
+     the process of determining where a package should be installed to.
+
+`REQUIRES'
+     (requires) A list of packages required to correctly build this
+     package.
+
+     Note that the usual form in `package-info.in' already has the
+     parentheses, so the `make' variable should be set to a
+     space-separated list of package names _not_ enclosed in
+     parentheses.
+
+     The list is of _packages_, not _libraries_, as would ordinarily be
+     provided to the Lisp `require' function.
+
+     `REQUIRES' cannot be correctly computed from the calls to
+     `require' in the package's library sources.  `REQUIRES' is used to
+     ensure that all macro and defstruct definitions used by the
+     package are available at build time.  This is not merely a matter
+     of efficiency, to get the expansions inlined.  In fact, it is
+     _impossible_ to call a macro by name in byte-compiled Emacs Lisp
+     code.  Thus, if the macro expansion is not inlined, the call will
+     result in an error at run-time!  Thus, packages providing
+     libraries that would be loaded because of autoload definitions
+     must also be included.
+
+`ELCS'
+     The list of the byte-compiled Lisp files used by the package.
+     These files and their `.el' versions will be included in the binary
+     package.  This variable determines which libraries will be
+     byte-compiled.  These libraries are also deleted by `make clean'.
+
+     Note there is no sanity-checking done on this variable.  If you put
+     `.el' files in here, they will not be compiled and they _will_ be
+     deleted by `make clean'.  You would surely be very distressed if
+     that happened, so be very careful.  If this variable is left
+     empty, none of your Lisp code will be compiled or packaged.  This
+     would be a less than amusing surprise, too.
+
+     We don't consider this a feature, of course.  Please do submit
+     code to do sanity checking to <xemacs-patches@xemacs.org>.
+
+   Optional, but commonly used variables are explained below.
+
+`ELCS_1'
+     A list of extra byte-compiled Lisp files used by the package to be
+     installed in a subdirectory of the package's lisp directory.  The
+     same care should be taken with this as with ELCS in regard to
+     `make clean'.
+
+`ELCS_1_DEST'
+     The name of the subdirectory for the ELCS_1 files to be installed
+     to.  Be sure to include `$(PACKAGE)/' as part of the name.
+
+          ELCS_1_DEST = $(PACKAGE)/extra
+
+     Would put the ELCS_1 files for the package, `foo' into
+     `xemacs-packages/lisp/foo/extra/'.
+
+`EARLY_GENERATED_LISP'
+     For additional `.el' files that will be generated before any
+     byte-compiling happens.  Use this for `autoload-type' files.  You
+     must write `Makefile' rules to build these files.
+
+`GENERATED_LISP'
+     For additional `.el' files that will be generated at
+     byte-compilation time.  You must write `Makefile' rules to build
+     these files.
+
+`PRELOADS'
+     This is used if you need to pass extra command line arguments to
+     XEmacs to build the package.  For instance, a specification for
+     loading libraries containing macros before compiling the Lisp in
+     the package.  This is spliced directly into the invocation of
+     XEmacs for byte-compilation, so it must contain the `-l' flag for
+     XEmacs:
+
+          PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
+
+     Preloads are loaded before `package-compile.el', so the LOAD-PATH
+     is minimal.  Therefore `PRELOADS' must specify a full path to
+     packaged Lisp.  The base LOAD-PATH does include the core Lisp
+     directory, so core libraries are found.
+
+`AUTOLOAD_PATH'
+     The subdirectory in the package's source tree where the `.el' files
+     reside.  This is where the `auto-autoloads.el' file will be placed.
+
+     *N.B.* There is no need to use this variable if the `.el' files
+     are in the package's toplevel directory.  AUTOLOAD_PATH defaults
+     to `.'.
+
+`PACKAGE_SUPPRESS'
+     Place calls to `package-suppress' here to indicate Lisp libraries
+     that should only be available to particular versions of XEmacs.
+     For example:
+
+          PACKAGE_SUPPRESS = \
+           (package-suppress 'xemacs-base \"regexp-opt\" '(emacs-version>= 21 5 11)) \
+           (package-suppress 'xemacs-base \"easy-mmode\" '(emacs-version>= 21 5 11))
+
+     *N.B.* This feature has not yet been implemented in XEmacs yet.
+     It will appear in an upcoming version of XEmacs 21.5.
+
+`STANDARD_DOCS'
+     Set this to `t' if your package's Texinfo source file is located in
+     the package's toplevel directory _and_ is named `$(PACKAGE).texi'.
+
+`EXPLICIT_DOCS'
+     Use this to explicitly list Texinfo sources that _aren't_ in the
+     package's toplevel directory.  For example:
+
+          EXPLICIT_DOCS = texi/$(PACKAGE).texi
+
+     See DOCS_TXI_EXTENSION and DOCS_TEXINFO_EXTENSION if you don't use
+     the `.texi' file extension on your Texinfo sources.
+
+`EXTRA_TEXI_FILES'
+     List here extra Texinfo source files needed to build your
+     documentation.  Whatever is listed here is passed on to `makeinfo'
+     as a dependency.
+
+`EXTRA_HTML_FILES'
+     Use this to specify extra `.html' files to output.
+
+`DOCS_TEXINFO_EXTENSION'
+     Set this to `t' if your Texinfo source files have a `.texinfo'
+     extension.
+
+`DOCS_TXI_EXTENSION'
+     Set this to `t' if your Texinfo source files have a `.txi'
+     extension.
+
+`EXTRA_DOC_FILES'
+     Files listed here will be installed to `.../man/$(PACKAGE)/'.  For
+     example, you might want to list TeX files or `.eps' files here.
+
+`EXTRA_SOURCES'
+     Other files (such as extra Lisp sources or an upstream `Makefile')
+     that are normally placed in the installed Lisp directory, but not
+     byte-compiled.  These files are _preserved_ by the `clean' targets.
+
+`LIBSRC_FILES'
+     For files that need to be installed to `lib-src/$(PACKAGE)/'.  If
+     the files listed here need to be built you will have to write
+     `Makefile' rules to do so.
+
+`DATA_FILES'
+     Any data files, such as pixmaps, READMEs, and ChangeLogs.  These
+     must be paths relative to the root of the package's source tree.
+     These files will be copied to `$(DATA_DEST)' for installation.
+     Any directory component of the path for a file will be stripped,
+     so that the file ends up in `$(DATA_DEST)', not in a subdiredtory.
+
+`DATA_DEST'
+     The directory where the files in DATA_FILES are installed to.  It
+     is a subdirectory of the installed `etc/' directory.  Be sure to
+     prefix this value with `$(PACKAGE)', for example:
+
+          DATA_DEST = $(PACKAGE)/foo
+
+     Would put files into `.../etc/$(PACKAGE)/foo/'.
+
+`DATA_1_FILES ... DATA_35_FILES'
+     For data files that need to go into a different directory from
+     DATA_DEST.
+
+`DATA_1_DEST ... DATA_35_DEST'
+     The name of the subdirectory for files specified in DATA_N_FILES.
+     And like DATA_DEST, be sure to prefix `$(PACKAGE)' to the value of
+     these variables.
+
+`EXTRA_DEPENDENCIES'
+     For additional files to build that aren't appropriate to place in
+     any other `Makefile' variable.  You will need to write `Makefile'
+     rules to build these files.
+
+`package-compile.el'
+====================
+
+The XEmacs Packaging System does not automatically become aware of your
+package simply because there is a new subtree.  If any package,
+including your own, requires any of your files, it must be explicitly
+added to the compile environment or loads/requires that search
+load-path will fail.  The changes that need to be made are
+
+*an entry in `package-directory-map'*
+     This tells the XEmacs Packaging System which distribution
+     (currently `xemacs-packages' or `mule-packages') your package is
+     found in.  It then looks in the distribution subdirectory whose
+     name is the same as the package's.
+
+*an entry in the `cond' in `package-name-to-directory'*
+     This is optional; it is necessary only if you keep your Lisp code
+     somewhere other than the top-level directory of the package's
+     source tree, eg, in `packages/xemacs-packages/PACKAGE/lisp'.
+
+   This only needs to be done once, when the package is first added to
+the XEmacs Packaging System.  (Well, when you randomly change the
+subdirectory layout, too.)  Your changes to `package-compile.el' must
+be cleared and checked in by the XEmacs Package Release Engineer before
+your package will build correctly from a fresh checkout.
+
+   This is unfortunate; it works pretty well once set up, but can cause
+confusion when first building a package in the XEmacs Packaging System
+context.  In particular, if the `package-directory-map' entry for a
+required package, including the package itself, is not found, the
+necessary requires will not be executed by `package-compile.el'.  If
+required functions are executed (under `eval-when-compile'), they won't
+be found and the compile will fail.  If required function is actually a
+macro, the byte compiler will not recognize that, compile a function
+call to the macro.  This will cause a run-time error because the
+byte-code interpreter does not know how to execute macros.  (Macros can
+always be expanded at compile-time, and this is more efficient.)
+
+   If your package keeps some or all Lisp code somewhere other than the
+top directory, then an entry in `package-name-to-directory' is also
+necessary, or requires will fail, leading to the problems just
+described.
+
+\1f
+File: lispref.info,  Node: Documenting Packages,  Next: Issues,  Prev: Creating Packages,  Up: Packaging
+
+Documenting Packages:
+=====================
+
+Some random notes on documenting your package.
+
+   Do write a Texinfo file.  It's not that hard to do basically, and
+even using the more advanced features of Texinfo soon become natural.
+For a start, just grab the template `Samples/package.texi' from the
+XEmacs Packaging System source tree, and drop your current README into
+the Top node.  At least this way your documentation will be accessible
+from the standard Info readers.  Next, try to add lots of
+cross-referencing and logical markup, and then node structure.
+
+   Address both end users and developer issues.  You may not be the
+maintainer forever.
+
+   If you are maintaining a package that is part of the GNU Emacs
+distribution, you'll likely find that you occasionally synchronize your
+package with the GNU Emacs sources.  When you synch a file,
+conventionally you should place a comment just above the standard `;;;
+Code' comment that looks like this:
+
+     ;; Synched with:
+     ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull <stephen@xemacs.org>
+
+   This comment is a status flag; the ChangeLog doesn't really give the
+same information.
+
+   Do maintain a detailed ChangeLog.
+
+\1f
+File: lispref.info,  Node: Issues,  Prev: Documenting Packages,  Up: Packaging
+
+Issues
+======
+
+To be completed.
+
+\1f
+File: lispref.info,  Node: Lisp Data Types,  Next: Numbers,  Prev: Packaging,  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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Character Type,  Next: Symbol Type,  Prev: Floating Point Type,  Up: Programming Types
+
+Character Type
+--------------
+
+In XEmacs version 19, and in all versions of FSF GNU Emacs, a
+"character" in XEmacs Lisp is nothing more than an integer.  This is
+yet another holdover from XEmacs Lisp's derivation from vintage-1980
+Lisps; modern versions of Lisp consider this equivalence a bad idea,
+and have separate character types.  In XEmacs version 20, the modern
+convention is followed, and characters are their own primitive types.
+(This change was necessary in order for MULE, i.e. Asian-language,
+support to be correctly implemented.)
+
+   Even in XEmacs version 20, remnants of the equivalence between
+characters and integers still exist; this is termed the "char-int
+confoundance disease".  In particular, many functions such as `eq',
+`equal', and `memq' have equivalent functions (`old-eq', `old-equal',
+`old-memq', etc.) that pretend like characters are integers are the
+same.  Byte code compiled under any version 19 Emacs will have all such
+functions mapped to their `old-' equivalents when the byte code is read
+into XEmacs 20.  This is to preserve compatibility--Emacs 19 converts
+all constant characters to the equivalent integer during
+byte-compilation, and thus there is no other way to preserve byte-code
+compatibility even if the code has specifically been written with the
+distinction between characters and integers in mind.
+
+   Every character has an equivalent integer, called the "character
+code".  For example, the character `A' is represented as the
+integer 65, following the standard ASCII representation of characters.
+If XEmacs was not compiled with MULE support, the range of this integer
+will always be 0 to 255--eight bits, or one byte. (Integers outside
+this range are accepted but silently truncated; however, you should
+most decidedly _not_ rely on this, because it will not work under
+XEmacs with MULE support.)  When MULE support is present, the range of
+character codes is much larger. (Currently, 19 bits are used.)
+
+   FSF GNU Emacs uses kludgy character codes above 255 to represent
+keyboard input of ASCII characters in combination with certain
+modifiers.  XEmacs does not use this (a more general mechanism is used
+that does not distinguish between ASCII keys and other keys), so you
+will never find character codes above 255 in a non-MULE XEmacs.
+
+   Individual characters are not often used in programs.  It is far more
+common to work with _strings_, which are sequences composed of
+characters.  *Note String Type::.
+
+   The read syntax for characters begins with a question mark, followed
+by the character (if it's printable) or some symbolic representation of
+it.  In XEmacs 20, where characters are their own type, this is also the
+print representation.  In XEmacs 19, however, where characters are
+really integers, the printed representation of a character is a decimal
+number.  This is also a possible read syntax for a character, but
+writing characters that way in Lisp programs is a very bad idea.  You
+should _always_ use the special read syntax formats that XEmacs Lisp
+provides for characters.
+
+   The usual read syntax for alphanumeric characters is a question mark
+followed by the character; thus, `?A' for the character `A', `?B' for
+the character `B', and `?a' for the character `a'.
+
+   For example:
+
+     ;; Under XEmacs 20:
+     ?Q => ?Q    ?q => ?q
+     (char-int ?Q) => 81
+     ;; Under XEmacs 19:
+     ?Q => 81     ?q => 113
+
+   You can use the same syntax for punctuation characters, but it is
+often a good idea to add a `\' so that the Emacs commands for editing
+Lisp code don't get confused.  For example, `?\ ' is the way to write
+the space character.  If the character is `\', you _must_ use a second
+`\' to quote it: `?\\'.  XEmacs 20 always prints punctuation characters
+with a `\' in front of them, to avoid confusion.
+
+   You can express the characters Control-g, backspace, tab, newline,
+vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
+`?\n', `?\v', `?\f', `?\r', `?\e', respectively.  Their character codes
+are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal.  Thus,
+
+     ;; Under XEmacs 20:
+     ?\a => ?\^G              ; `C-g'
+     (char-int ?\a) => 7
+     ?\b => ?\^H              ; backspace, <BS>, `C-h'
+     (char-int ?\b) => 8
+     ?\t => ?\t               ; tab, <TAB>, `C-i'
+     (char-int ?\t) => 9
+     ?\n => ?\n               ; newline, <LFD>, `C-j'
+     ?\v => ?\^K              ; vertical tab, `C-k'
+     ?\f => ?\^L              ; formfeed character, `C-l'
+     ?\r => ?\r               ; carriage return, <RET>, `C-m'
+     ?\e => ?\^[              ; escape character, <ESC>, `C-['
+     ?\\ => ?\\               ; backslash character, `\'
+     ;; Under XEmacs 19:
+     ?\a => 7                 ; `C-g'
+     ?\b => 8                 ; backspace, <BS>, `C-h'
+     ?\t => 9                 ; tab, <TAB>, `C-i'
+     ?\n => 10                ; newline, <LFD>, `C-j'
+     ?\v => 11                ; vertical tab, `C-k'
+     ?\f => 12                ; formfeed character, `C-l'
+     ?\r => 13                ; carriage return, <RET>, `C-m'
+     ?\e => 27                ; escape character, <ESC>, `C-['
+     ?\\ => 92                ; backslash character, `\'
+
+   These sequences which start with backslash are also known as "escape
+sequences", because backslash plays the role of an escape character;
+this usage has nothing to do with the character <ESC>.
+
+   Control characters may be represented using yet another read syntax.
+This consists of a question mark followed by a backslash, caret, and the
+corresponding non-control character, in either upper or lower case.  For
+example, both `?\^I' and `?\^i' are valid read syntax for the character
+`C-i', the character whose value is 9.
+
+   Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
+`?\^I' and to `?\^i':
+
+     ;; Under XEmacs 20:
+     ?\^I => ?\t   ?\C-I => ?\t
+     (char-int ?\^I) => 9
+     ;; Under XEmacs 19:
+     ?\^I => 9     ?\C-I => 9
+
+   There is also a character read syntax beginning with `\M-'.  This
+sets the high bit of the character code (same as adding 128 to the
+character code).  For example, `?\M-A' stands for the character with
+character code 193, or 128 plus 65.  You should _not_ use this syntax
+in your programs.  It is a holdover of yet another confoundance disease
+from earlier Emacsen. (This was used to represent keyboard input with
+the <META> key set, thus the `M'; however, it conflicts with the
+legitimate ISO-8859-1 interpretation of the character code.  For
+example, character code 193 is a lowercase `a' with an acute accent, in
+ISO-8859-1.)
+
+   Finally, the most general read syntax consists of a question mark
+followed by a backslash and the character code in octal (up to three
+octal digits); thus, `?\101' for the character `A', `?\001' for the
+character `C-a', and `?\002' for the character `C-b'.  Although this
+syntax can represent any ASCII character, it is preferred only when the
+precise octal value is more important than the ASCII representation.
+
+     ;; Under XEmacs 20:
+     ?\012 => ?\n        ?\n => ?\n        ?\C-j => ?\n
+     ?\101 => ?A         ?A => ?A
+     ;; Under XEmacs 19:
+     ?\012 => 10         ?\n => 10         ?\C-j => 10
+     ?\101 => 65         ?A => 65
+
+   A backslash is allowed, and harmless, preceding any character without
+a special escape meaning; thus, `?\+' is equivalent to `?+'.  There is
+no reason to add a backslash before most characters.  However, you
+should add a backslash before any of the characters `()\|;'`"#.,' to
+avoid confusing the Emacs commands for editing Lisp code.  Also add a
+backslash before whitespace characters such as space, tab, newline and
+formfeed.  However, it is cleaner to use one of the easily readable
+escape sequences, such as `\t', instead of an actual whitespace
+character such as a tab.
+
+\1f
+File: lispref.info,  Node: Symbol Type,  Next: Sequence Type,  Prev: Character Type,  Up: Programming Types
+
+Symbol Type
+-----------
+
+A "symbol" in XEmacs Lisp is an object with a name.  The symbol name
+serves as the printed representation of the symbol.  In ordinary use,
+the name is unique--no two symbols have the same name.
+
+   A symbol can serve as a variable, as a function name, or to hold a
+property list.  Or it may serve only to be distinct from all other Lisp
+objects, so that its presence in a data structure may be recognized
+reliably.  In a given context, usually only one of these uses is
+intended.  But you can use one symbol in all of these ways,
+independently.
+
+   A symbol name can contain any characters whatever.  Most symbol names
+are written with letters, digits, and the punctuation characters
+`-+=*/'.  Such names require no special punctuation; the characters of
+the name suffice as long as the name does not look like a number.  (If
+it does, write a `\' at the beginning of the name to force
+interpretation as a symbol.)  The characters `_~!@$%^&:<>{}' are less
+often used but also require no special punctuation.  Any other
+characters may be included in a symbol's name by escaping them with a
+backslash.  In contrast to its use in strings, however, a backslash in
+the name of a symbol simply quotes the single character that follows the
+backslash.  For example, in a string, `\t' represents a tab character;
+in the name of a symbol, however, `\t' merely quotes the letter `t'.
+To have a symbol with a tab character in its name, you must actually
+use a tab (preceded with a backslash).  But it's rare to do such a
+thing.
+
+     Common Lisp note: In Common Lisp, lower case letters are always
+     "folded" to upper case, unless they are explicitly escaped.  In
+     Emacs Lisp, upper case and lower case letters are distinct.
+
+   Here are several examples of symbol names.  Note that the `+' in the
+fifth example is escaped to prevent it from being read as a number.
+This is not necessary in the sixth example because the rest of the name
+makes it invalid as a number.
+
+     foo                 ; A symbol named `foo'.
+     FOO                 ; A symbol named `FOO', different from `foo'.
+     char-to-string      ; A symbol named `char-to-string'.
+     1+                  ; A symbol named `1+'
+                         ;   (not `+1', which is an integer).
+     \+1                 ; A symbol named `+1'
+                         ;   (not a very readable name).
+     \(*\ 1\ 2\)         ; A symbol named `(* 1 2)' (a worse name).
+     +-*/_~!@$%^&=:<>{}  ; A symbol named `+-*/_~!@$%^&=:<>{}'.
+                         ;   These characters need not be escaped.
+
+\1f
+File: lispref.info,  Node: Sequence Type,  Next: Cons Cell Type,  Prev: Symbol Type,  Up: Programming Types
+
+Sequence Types
+--------------
+
+A "sequence" is a Lisp object that represents an ordered set of
+elements.  There are two kinds of sequence in XEmacs Lisp, lists and
+arrays.  Thus, an object of type list or of type array is also
+considered a sequence.
+
+   Arrays are further subdivided into strings, vectors, and bit vectors.
+Vectors can hold elements of any type, but string elements must be
+characters, and bit vector elements must be either 0 or 1.  However, the
+characters in a string can have extents (*note Extents::) and text
+properties (*note Text Properties::) like characters in a buffer;
+vectors do not support extents or text properties even when their
+elements happen to be characters.
+
+   Lists, strings, vectors, and bit vectors are different, but they have
+important similarities.  For example, all have a length L, and all have
+elements which can be indexed from zero to L minus one.  Also, several
+functions, called sequence functions, accept any kind of sequence.  For
+example, the function `elt' can be used to extract an element of a
+sequence, given its index.  *Note Sequences Arrays Vectors::.
+
+   It is impossible to read the same sequence twice, since sequences are
+always created anew upon reading.  If you read the read syntax for a
+sequence twice, you get two sequences with equal contents.  There is one
+exception: the empty list `()' always stands for the same object, `nil'.
+
+\1f
+File: lispref.info,  Node: Cons Cell Type,  Next: Array Type,  Prev: Sequence Type,  Up: Programming Types
+
+Cons Cell and List Types
+------------------------
+
+A "cons cell" is an object comprising two pointers named the CAR and
+the CDR.  Each of them can point to any Lisp object.
+
+   A "list" is a series of cons cells, linked together so that the CDR
+of each cons cell points either to another cons cell or to the empty
+list.  *Note Lists::, for functions that work on lists.  Because most
+cons cells are used as part of lists, the phrase "list structure" has
+come to refer to any structure made out of cons cells.
+
+   The names CAR and CDR have only historical meaning now.  The
+original Lisp implementation ran on an IBM 704 computer which divided
+words into two parts, called the "address" part and the "decrement";
+CAR was an instruction to extract the contents of the address part of a
+register, and CDR an instruction to extract the contents of the
+decrement.  By contrast, "cons cells" are named for the function `cons'
+that creates them, which in turn is named for its purpose, the
+construction of cells.
+
+   Because cons cells are so central to Lisp, we also have a word for
+"an object which is not a cons cell".  These objects are called "atoms".
+
+   The read syntax and printed representation for lists are identical,
+and consist of a left parenthesis, an arbitrary number of elements, and
+a right parenthesis.
+
+   Upon reading, each object inside the parentheses becomes an element
+of the list.  That is, a cons cell is made for each element.  The CAR
+of the cons cell points to the element, and its CDR points to the next
+cons cell of the list, which holds the next element in the list.  The
+CDR of the last cons cell is set to point to `nil'.
+
+   A list can be illustrated by a diagram in which the cons cells are
+shown as pairs of boxes.  (The Lisp reader cannot read such an
+illustration; unlike the textual notation, which can be understood by
+both humans and computers, the box illustrations can be understood only
+by humans.)  The following represents the three-element list `(rose
+violet buttercup)':
+
+         ___ ___      ___ ___      ___ ___
+        |___|___|--> |___|___|--> |___|___|--> nil
+          |            |            |
+          |            |            |
+           --> rose     --> violet   --> buttercup
+
+   In this diagram, each box represents a slot that can refer to any
+Lisp object.  Each pair of boxes represents a cons cell.  Each arrow is
+a reference to a Lisp object, either an atom or another cons cell.
+
+   In this example, the first box, the CAR of the first cons cell,
+refers to or "contains" `rose' (a symbol).  The second box, the CDR of
+the first cons cell, refers to the next pair of boxes, the second cons
+cell.  The CAR of the second cons cell refers to `violet' and the CDR
+refers to the third cons cell.  The CDR of the third (and last) cons
+cell refers to `nil'.
+
+   Here is another diagram of the same list, `(rose violet buttercup)',
+sketched in a different manner:
+
+      ---------------       ----------------       -------------------
+     | car   | cdr   |     | car    | cdr   |     | car       | cdr   |
+     | rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
+     |       |       |     |        |       |     |           |       |
+      ---------------       ----------------       -------------------
+
+   A list with no elements in it is the "empty list"; it is identical
+to the symbol `nil'.  In other words, `nil' is both a symbol and a list.
+
+   Here are examples of lists written in Lisp syntax:
+
+     (A 2 "A")            ; A list of three elements.
+     ()                   ; A list of no elements (the empty list).
+     nil                  ; A list of no elements (the empty list).
+     ("A ()")             ; A list of one element: the string `"A ()"'.
+     (A ())               ; A list of two elements: `A' and the empty list.
+     (A nil)              ; Equivalent to the previous.
+     ((A B C))            ; A list of one element
+                          ;   (which is a list of three elements).
+
+   Here is the list `(A ())', or equivalently `(A nil)', depicted with
+boxes and arrows:
+
+         ___ ___      ___ ___
+        |___|___|--> |___|___|--> nil
+          |            |
+          |            |
+           --> A        --> nil
+
+* Menu:
+
+* Dotted Pair Notation::        An alternative syntax for lists.
+* Association List Type::       A specially constructed list.
+
+\1f
+File: lispref.info,  Node: Dotted Pair Notation,  Next: Association List Type,  Up: Cons Cell Type
+
+Dotted Pair Notation
+....................
+
+"Dotted pair notation" is an alternative syntax for cons cells that
+represents the CAR and CDR explicitly.  In this syntax, `(A . B)'
+stands for a cons cell whose CAR is the object A, and whose CDR is the
+object B.  Dotted pair notation is therefore more general than list
+syntax.  In the dotted pair notation, the list `(1 2 3)' is written as
+`(1 .  (2 . (3 . nil)))'.  For `nil'-terminated lists, the two
+notations produce the same result, but list notation is usually clearer
+and more convenient when it is applicable.  When printing a list, the
+dotted pair notation is only used if the CDR of a cell is not a list.
+
+   Here's how box notation can illustrate dotted pairs.  This example
+shows the pair `(rose . violet)':
+
+         ___ ___
+        |___|___|--> violet
+          |
+          |
+           --> rose
+
+   Dotted pair notation can be combined with list notation to represent
+a chain of cons cells with a non-`nil' final CDR.  For example, `(rose
+violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
+The object looks like this:
+
+         ___ ___      ___ ___
+        |___|___|--> |___|___|--> buttercup
+          |            |
+          |            |
+           --> rose     --> violet
+
+   These diagrams make it evident why `(rose . violet . buttercup)' is
+invalid syntax; it would require a cons cell that has three parts
+rather than two.
+
+   The list `(rose violet)' is equivalent to `(rose . (violet))' and
+looks like this:
+
+         ___ ___      ___ ___
+        |___|___|--> |___|___|--> nil
+          |            |
+          |            |
+           --> rose     --> violet
+
+   Similarly, the three-element list `(rose violet buttercup)' is
+equivalent to `(rose . (violet . (buttercup)))'.  It looks like this:
+
+         ___ ___      ___ ___      ___ ___
+        |___|___|--> |___|___|--> |___|___|--> nil
+          |            |            |
+          |            |            |
+           --> rose     --> violet   --> buttercup
+
+\1f
+File: lispref.info,  Node: Association List Type,  Prev: Dotted Pair Notation,  Up: Cons Cell Type
+
+Association List Type
+.....................
+
+An "association list" or "alist" is a specially-constructed list whose
+elements are cons cells.  In each element, the CAR is considered a
+"key", and the CDR is considered an "associated value".  (In some
+cases, the associated value is stored in the CAR of the CDR.)
+Association lists are often used as stacks, since it is easy to add or
+remove associations at the front of the list.
+
+   For example,
+
+     (setq alist-of-colors
+           '((rose . red) (lily . white)  (buttercup . yellow)))
+
+sets the variable `alist-of-colors' to an alist of three elements.  In
+the first element, `rose' is the key and `red' is the value.
+
+   *Note Association Lists::, for a further explanation of alists and
+for functions that work on alists.
+
+\1f
+File: lispref.info,  Node: Array Type,  Next: String Type,  Prev: Cons Cell Type,  Up: Programming Types
+
+Array Type
+----------
+
+An "array" is composed of an arbitrary number of slots for referring to
+other Lisp objects, arranged in a contiguous block of memory.
+Accessing any element of an array takes the same amount of time.  In
+contrast, accessing an element of a list requires time proportional to
+the position of the element in the list.  (Elements at the end of a
+list take longer to access than elements at the beginning of a list.)
+
+   XEmacs defines three types of array, strings, vectors, and bit
+vectors.  A string is an array of characters, a vector is an array of
+arbitrary objects, and a bit vector is an array of 1's and 0's.  All are
+one-dimensional.  (Most other programming languages support
+multidimensional arrays, but they are not essential; you can get the
+same effect with an array of arrays.)  Each type of array has its own
+read syntax; see *Note String Type::, *Note Vector Type::, and *Note
+Bit Vector Type::.
+
+   An array may have any length up to the largest integer; but once
+created, it has a fixed size.  The first element of an array has index
+zero, the second element has index 1, and so on.  This is called
+"zero-origin" indexing.  For example, an array of four elements has
+indices 0, 1, 2, and 3.
+
+   The array type is contained in the sequence type and contains the
+string type, the vector type, and the bit vector type.
+
+\1f
+File: lispref.info,  Node: String Type,  Next: Vector Type,  Prev: Array Type,  Up: Programming Types
+
+String Type
+-----------
+
+A "string" is an array of characters.  Strings are used for many
+purposes in XEmacs, as can be expected in a text editor; for example, as
+the names of Lisp symbols, as messages for the user, and to represent
+text extracted from buffers.  Strings in Lisp are constants: evaluation
+of a string returns the same string.
+
+   The read syntax for strings is a double-quote, an arbitrary number of
+characters, and another double-quote, `"like this"'.  The Lisp reader
+accepts the same formats for reading the characters of a string as it
+does for reading single characters (without the question mark that
+begins a character literal).  You can enter a nonprinting character such
+as tab or `C-a' using the convenient escape sequences, like this: `"\t,
+\C-a"'.  You can include a double-quote in a string by preceding it
+with a backslash; thus, `"\""' is a string containing just a single
+double-quote character.  (*Note Character Type::, for a description of
+the read syntax for characters.)
+
+   The printed representation of a string consists of a double-quote,
+the characters it contains, and another double-quote.  However, you must
+escape any backslash or double-quote characters in the string with a
+backslash, like this: `"this \" is an embedded quote"'.
+
+   The newline character is not special in the read syntax for strings;
+if you write a new line between the double-quotes, it becomes a
+character in the string.  But an escaped newline--one that is preceded
+by `\'--does not become part of the string; i.e., the Lisp reader
+ignores an escaped newline while reading a string.
+
+     "It is useful to include newlines
+     in documentation strings,
+     but the newline is \
+     ignored if escaped."
+          => "It is useful to include newlines
+     in documentation strings,
+     but the newline is ignored if escaped."
+
+   A string can hold extents and properties of the text it contains, in
+addition to the characters themselves.  This enables programs that copy
+text between strings and buffers to preserve the extents and properties
+with no special effort.  *Note Extents::, *Note Text Properties::.
+
+   Note that FSF GNU Emacs has a special read and print syntax for
+strings with text properties, but XEmacs does not currently implement
+this.  It was judged better not to include this in XEmacs because it
+entails that `equal' return `nil' when passed a string with text
+properties and the equivalent string without text properties, which is
+often counter-intuitive.
+
+   *Note Strings and Characters::, for functions that work on strings.
+
+\1f
+File: lispref.info,  Node: Vector Type,  Next: Bit Vector Type,  Prev: String Type,  Up: Programming Types
+
+Vector Type
+-----------
+
+A "vector" is a one-dimensional array of elements of any type.  It
+takes a constant amount of time to access any element of a vector.  (In
+a list, the access time of an element is proportional to the distance of
+the element from the beginning of the list.)
+
+   The printed representation of a vector consists of a left square
+bracket, the elements, and a right square bracket.  This is also the
+read syntax.  Like numbers and strings, vectors are considered constants
+for evaluation.
+
+     [1 "two" (three)]      ; A vector of three elements.
+          => [1 "two" (three)]
+
+   *Note Vectors::, for functions that work with vectors.
+
+\1f
+File: lispref.info,  Node: Bit Vector Type,  Next: Function Type,  Prev: Vector Type,  Up: Programming Types
+
+Bit Vector Type
+---------------
+
+A "bit vector" is a one-dimensional array of 1's and 0's.  It takes a
+constant amount of time to access any element of a bit vector, as for
+vectors.  Bit vectors have an extremely compact internal representation
+(one machine bit per element), which makes them ideal for keeping track
+of unordered sets, large collections of boolean values, etc.
+
+   The printed representation of a bit vector consists of `#*' followed
+by the bits in the vector.  This is also the read syntax.  Like
+numbers, strings, and vectors, bit vectors are considered constants for
+evaluation.
+
+     #*00101000      ; A bit vector of eight elements.
+          => #*00101000
+
+   *Note Bit Vectors::, for functions that work with bit vectors.
+
+\1f
+File: lispref.info,  Node: Function Type,  Next: Macro Type,  Prev: Bit Vector Type,  Up: Programming Types
+
+Function Type
+-------------
+
+Just as functions in other programming languages are executable, "Lisp
+function" objects are pieces of executable code.  However, functions in
+Lisp are primarily Lisp objects, and only secondarily the text which
+represents them.  These Lisp objects are lambda expressions: lists
+whose first element is the symbol `lambda' (*note Lambda Expressions::).
+
+   In most programming languages, it is impossible to have a function
+without a name.  In Lisp, a function has no intrinsic name.  A lambda
+expression is also called an "anonymous function" (*note Anonymous
+Functions::).  A named function in Lisp is actually a symbol with a
+valid function in its function cell (*note Defining Functions::).
+
+   Most of the time, functions are called when their names are written
+in Lisp expressions in Lisp programs.  However, you can construct or
+obtain a function object at run time and then call it with the primitive
+functions `funcall' and `apply'.  *Note Calling Functions::.
+
+\1f
+File: lispref.info,  Node: Macro Type,  Next: Primitive Function Type,  Prev: Function Type,  Up: Programming Types
+
+Macro Type
+----------
+
+A "Lisp macro" is a user-defined construct that extends the Lisp
+language.  It is represented as an object much like a function, but with
+different parameter-passing semantics.  A Lisp macro has the form of a
+list whose first element is the symbol `macro' and whose CDR is a Lisp
+function object, including the `lambda' symbol.
+
+   Lisp macro objects are usually defined with the built-in `defmacro'
+function, but any list that begins with `macro' is a macro as far as
+XEmacs is concerned.  *Note Macros::, for an explanation of how to
+write a macro.
+
+\1f
+File: lispref.info,  Node: Primitive Function Type,  Next: Compiled-Function Type,  Prev: Macro Type,  Up: Programming Types
+
+Primitive Function Type
+-----------------------
+
+A "primitive function" is a function callable from Lisp but written in
+the C programming language.  Primitive functions are also called
+"subrs" or "built-in functions".  (The word "subr" is derived from
+"subroutine".)  Most primitive functions evaluate all their arguments
+when they are called.  A primitive function that does not evaluate all
+its arguments is called a "special form" (*note Special Forms::).
+
+   It does not matter to the caller of a function whether the function
+is primitive.  However, this does matter if you try to substitute a
+function written in Lisp for a primitive of the same name.  The reason
+is that the primitive function may be called directly from C code.
+Calls to the redefined function from Lisp will use the new definition,
+but calls from C code may still use the built-in definition.
+
+   The term "function" refers to all Emacs functions, whether written
+in Lisp or C.  *Note Function Type::, for information about the
+functions written in Lisp.
+
+   Primitive functions have no read syntax and print in hash notation
+with the name of the subroutine.
+
+     (symbol-function 'car)          ; Access the function cell
+                                     ;   of the symbol.
+          => #<subr car>
+     (subrp (symbol-function 'car))  ; Is this a primitive function?
+          => t                       ; Yes.
+
+\1f
+File: lispref.info,  Node: Compiled-Function Type,  Next: Autoload Type,  Prev: Primitive Function Type,  Up: Programming Types
+
+Compiled-Function Type
+----------------------
+
+The byte compiler produces "compiled-function objects".  The evaluator
+handles this data type specially when it appears as a function to be
+called.  *Note Byte Compilation::, for information about the byte
+compiler.
+
+   The printed representation for a compiled-function object is normally
+`#<compiled-function...>'.  If `print-readably' is true, however, it is
+`#[...]'.
+
+\1f
+File: lispref.info,  Node: Autoload Type,  Next: Char Table Type,  Prev: Compiled-Function Type,  Up: Programming Types
+
+Autoload Type
+-------------
+
+An "autoload object" is a list whose first element is the symbol
+`autoload'.  It is stored as the function definition of a symbol as a
+placeholder for the real definition; it says that the real definition
+is found in a file of Lisp code that should be loaded when necessary.
+The autoload object contains the name of the file, plus some other
+information about the real definition.
+
+   After the file has been loaded, the symbol should have a new function
+definition that is not an autoload object.  The new definition is then
+called as if it had been there to begin with.  From the user's point of
+view, the function call works as expected, using the function definition
+in the loaded file.
+
+   An autoload object is usually created with the function `autoload',
+which stores the object in the function cell of a symbol.  *Note
+Autoload::, for more details.
+
+\1f
+File: lispref.info,  Node: Char Table Type,  Next: Hash Table Type,  Prev: Autoload Type,  Up: Programming Types
+
+Char Table Type
+---------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Hash Table Type,  Next: Range Table Type,  Prev: Char Table Type,  Up: Programming Types
+
+Hash Table Type
+---------------
+
+A "hash table" is a table providing an arbitrary mapping from one Lisp
+object to another, using an internal indexing method called "hashing".
+Hash tables are very fast (much more efficient that using an
+association list, when there are a large number of elements in the
+table).
+
+   Hash tables have a special read syntax beginning with
+`#s(hash-table' (this is an example of "structure" read syntax.  This
+notation is also used for printing when `print-readably' is `t'.
+
+   Otherwise they print in hash notation (The "hash" in "hash notation"
+has nothing to do with the "hash" in "hash table"), giving the number
+of elements, total space allocated for elements, and a unique number
+assigned at the time the hash table was created. (Hash tables
+automatically resize as necessary so there is no danger of running out
+of space for elements.)
+
+     (make-hash-table :size 50)
+          => #<hash-table 0/107 0x313a>
+
+   *Note Hash Tables::, for information on how to create and work with
+hash tables.
+
+\1f
+File: lispref.info,  Node: Range Table Type,  Next: Weak List Type,  Prev: Hash Table Type,  Up: Programming Types
+
+Range Table Type
+----------------
+
+A "range table" is a table that maps from ranges of integers to
+arbitrary Lisp objects.  Range tables automatically combine overlapping
+ranges that map to the same Lisp object, and operations are provided
+for mapping over all of the ranges in a range table.
+
+   Range tables have a special read syntax beginning with
+`#s(range-table' (this is an example of "structure" read syntax, which
+is also used for char tables and faces).
+
+     (setq x (make-range-table))
+     (put-range-table 20 50 'foo x)
+     (put-range-table 100 200 "bar" x)
+     x
+          => #s(range-table data ((20 50) foo (100 200) "bar"))
+
+   *Note Range Tables::, for information on how to create and work with
+range tables.
+
+\1f
+File: lispref.info,  Node: Weak List Type,  Prev: Range Table Type,  Up: Programming Types
+
+Weak List Type
+--------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Editing Types,  Next: Window-System Types,  Prev: Programming Types,  Up: Lisp Data Types
+
+Editing Types
+=============
+
+The types in the previous section are common to many Lisp dialects.
+XEmacs Lisp provides several additional data types for purposes
+connected with editing.
+
+* Menu:
+
+* Buffer Type::         The basic object of editing.
+* Marker Type::         A position in a buffer.
+* Extent Type::         A range in a buffer or string, maybe with properties.
+* Window Type::         Buffers are displayed in windows.
+* Frame Type::         Windows subdivide frames.
+* Device Type::         Devices group all frames on a display.
+* Console Type::        Consoles group all devices with the same keyboard.
+* Window Configuration Type::   Recording the way a frame is subdivided.
+* Event Type::          An interesting occurrence in the system.
+* 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.
+* Display Table Type::  How display tables are represented.
+* Database Type::       A connection to an external DBM or DB database.
+* Charset Type::        A character set (e.g. all Kanji characters),
+                          under XEmacs/MULE.
+* Coding System Type::  An object encapsulating a way of converting between
+                          different textual encodings, under XEmacs/MULE.
+* ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
+* ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
+
+\1f
+File: lispref.info,  Node: Buffer Type,  Next: Marker Type,  Up: Editing Types
+
+Buffer Type
+-----------
+
+A "buffer" is an object that holds text that can be edited (*note
+Buffers::).  Most buffers hold the contents of a disk file (*note
+Files::) so they can be edited, but some are used for other purposes.
+Most buffers are also meant to be seen by the user, and therefore
+displayed, at some time, in a window (*note Windows::).  But a buffer
+need not be displayed in any window.
+
+   The contents of a buffer are much like a string, but buffers are not
+used like strings in XEmacs Lisp, and the available operations are
+different.  For example, insertion of text into a buffer is very
+efficient, whereas "inserting" text into a string requires
+concatenating substrings, and the result is an entirely new string
+object.
+
+   Each buffer has a designated position called "point" (*note
+Positions::).  At any time, one buffer is the "current buffer".  Most
+editing commands act on the contents of the current buffer in the
+neighborhood of point.  Many of the standard Emacs functions manipulate
+or test the characters in the current buffer; a whole chapter in this
+manual is devoted to describing these functions (*note Text::).
+
+   Several other data structures are associated with each buffer:
+
+   * a local syntax table (*note Syntax Tables::);
+
+   * a local keymap (*note Keymaps::);
+
+   * a local variable binding list (*note Buffer-Local Variables::);
+
+   * a list of extents (*note Extents::);
+
+   * and various other related properties.
+
+The local keymap and variable list contain entries that individually
+override global bindings or values.  These are used to customize the
+behavior of programs in different buffers, without actually changing the
+programs.
+
+   A buffer may be "indirect", which means it shares the text of
+another buffer.  *Note Indirect Buffers::.
+
+   Buffers have no read syntax.  They print in hash notation, showing
+the buffer name.
+
+     (current-buffer)
+          => #<buffer "objects.texi">
+
+\1f
+File: lispref.info,  Node: Marker Type,  Next: Extent Type,  Prev: Buffer Type,  Up: Editing Types
+
+Marker Type
+-----------
+
+A "marker" denotes a position in a specific buffer.  Markers therefore
+have two components: one for the buffer, and one for the position.
+Changes in the buffer's text automatically relocate the position value
+as necessary to ensure that the marker always points between the same
+two characters in the buffer.
+
+   Markers have no read syntax.  They print in hash notation, giving the
+current character position and the name of the buffer.
+
+     (point-marker)
+          => #<marker at 50661 in objects.texi>
+
+   *Note Markers::, for information on how to test, create, copy, and
+move markers.
+
+\1f
+File: lispref.info,  Node: Extent Type,  Next: Window Type,  Prev: Marker Type,  Up: Editing Types
+
+Extent Type
+-----------
+
+An "extent" specifies temporary alteration of the display appearance of
+a part of a buffer (or string).  It contains markers delimiting a range
+of the buffer, plus a property list (a list whose elements are
+alternating property names and values).  Extents are used to present
+parts of the buffer temporarily in a different display style.  They
+have no read syntax, and print in hash notation, giving the buffer name
+and range of positions.
+
+   Extents can exist over strings as well as buffers; the primary use
+of this is to preserve extent and text property information as text is
+copied from one buffer to another or between different parts of a
+buffer.
+
+   Extents have no read syntax.  They print in hash notation, giving the
+range of text they cover, the name of the buffer or string they are in,
+the address in core, and a summary of some of the properties attached to
+the extent.
+
+     (extent-at (point))
+          => #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
+
+   *Note Extents::, for how to create and use extents.
+
+   Extents are used to implement text properties.  *Note Text
+Properties::.
+
+\1f
+File: lispref.info,  Node: Window Type,  Next: Frame Type,  Prev: Extent Type,  Up: Editing Types
+
+Window Type
+-----------
+
+A "window" describes the portion of the frame that XEmacs uses to
+display a buffer. (In standard window-system usage, a "window" is what
+XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to
+refer to what is called a "pane" in standard window-system usage.)
+Every window has one associated buffer, whose contents appear in the
+window.  By contrast, a given buffer may appear in one window, no
+window, or several windows.
+
+   Though many windows may exist simultaneously, at any time one window
+is designated the "selected window".  This is the window where the
+cursor is (usually) displayed when XEmacs is ready for a command.  The
+selected window usually displays the current buffer, but this is not
+necessarily the case.
+
+   Windows are grouped on the screen into frames; each window belongs to
+one and only one frame.  *Note Frame Type::.
+
+   Windows have no read syntax.  They print in hash notation, giving the
+name of the buffer being displayed and a unique number assigned at the
+time the window was created. (This number can be useful because the
+buffer displayed in any given window can change frequently.)
+
+     (selected-window)
+          => #<window on "objects.texi" 0x266c>
+
+   *Note Windows::, for a description of the functions that work on
+windows.
+
+\1f
+File: lispref.info,  Node: Frame Type,  Next: Device Type,  Prev: Window Type,  Up: Editing Types
+
+Frame Type
+----------
+
+A FRAME is a rectangle on the screen (a "window" in standard
+window-system terminology) that contains one or more non-overlapping
+Emacs windows ("panes" in standard window-system terminology).  A frame
+initially contains a single main window (plus perhaps a minibuffer
+window) which you can subdivide vertically or horizontally into smaller
+windows.
+
+   Frames have no read syntax.  They print in hash notation, giving the
+frame's type, name as used for resourcing, and a unique number assigned
+at the time the frame was created.
+
+     (selected-frame)
+          => #<x-frame "emacs" 0x9db>
+
+   *Note Frames::, for a description of the functions that work on
+frames.
+
+\1f
+File: lispref.info,  Node: Device Type,  Next: Console Type,  Prev: Frame Type,  Up: Editing Types
+
+Device Type
+-----------
+
+A "device" represents a single display on which frames exist.
+Normally, there is only one device object, but there may be more than
+one if XEmacs is being run on a multi-headed display (e.g. an X server
+with attached color and mono screens) or if XEmacs is simultaneously
+driving frames attached to different consoles, e.g.  an X display and a
+TTY connection.
+
+   Devices do not have a read syntax.  They print in hash notation,
+giving the device's type, connection name, and a unique number assigned
+at the time the device was created.
+
+     (selected-device)
+          => #<x-device on ":0.0" 0x5b9>
+
+   *Note Consoles and Devices::, for a description of several functions
+related to devices.
+
+\1f
+File: lispref.info,  Node: Console Type,  Next: Window Configuration Type,  Prev: Device Type,  Up: Editing Types
+
+Console Type
+------------
+
+A "console" represents a single keyboard to which devices (i.e.
+displays on which frames exist) are connected.  Normally, there is only
+one console object, but there may be more than one if XEmacs is
+simultaneously driving frames attached to different X servers and/or
+TTY connections. (XEmacs is capable of driving multiple X and TTY
+connections at the same time, and provides a robust mechanism for
+handling the differing display capabilities of such heterogeneous
+environments.  A buffer with embedded glyphs and multiple fonts and
+colors, for example, will display reasonably if it simultaneously
+appears on a frame on a color X display, a frame on a mono X display,
+and a frame on a TTY connection.)
+
+   Consoles do not have a read syntax.  They print in hash notation,
+giving the console's type, connection name, and a unique number assigned
+at the time the console was created.
+
+     (selected-console)
+          => #<x-console on "localhost:0" 0x5b7>
+
+   *Note Consoles and Devices::, for a description of several functions
+related to consoles.
+
+\1f
+File: lispref.info,  Node: Window Configuration Type,  Next: Event Type,  Prev: Console Type,  Up: Editing Types
+
+Window Configuration Type
+-------------------------
+
+A "window configuration" stores information about the positions, sizes,
+and contents of the windows in a frame, so you can recreate the same
+arrangement of windows later.
+
+   Window configurations do not have a read syntax.  They print in hash
+notation, giving a unique number assigned at the time the window
+configuration was created.
+
+     (current-window-configuration)
+          => #<window-configuration 0x2db4>
+
+   *Note Window Configurations::, for a description of several functions
+related to window configurations.
+
+\1f
+File: lispref.info,  Node: Event Type,  Next: Process Type,  Prev: Window Configuration Type,  Up: Editing Types
+
+Event Type
+----------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Process Type,  Next: Stream Type,  Prev: Event Type,  Up: Editing Types
+
+Process Type
+------------
+
+The word "process" usually means a running program.  XEmacs itself runs
+in a process of this sort.  However, in XEmacs Lisp, a process is a
+Lisp object that designates a subprocess created by the XEmacs process.
+Programs such as shells, GDB, ftp, and compilers, running in
+subprocesses of XEmacs, extend the capabilities of XEmacs.
+
+   An Emacs subprocess takes textual input from Emacs and returns
+textual output to Emacs for further manipulation.  Emacs can also send
+signals to the subprocess.
+
+   Process objects have no read syntax.  They print in hash notation,
+giving the name of the process, its associated process ID, and the
+current state of the process:
+
+     (process-list)
+          => (#<process "shell" pid 2909 state:run>)
+
+   *Note Processes::, for information about functions that create,
+delete, return information about, send input or signals to, and receive
+output from processes.
+
+\1f
+File: lispref.info,  Node: Stream Type,  Next: Keymap Type,  Prev: Process Type,  Up: Editing Types
+
+Stream Type
+-----------
+
+A "stream" is an object that can be used as a source or sink for
+characters--either to supply characters for input or to accept them as
+output.  Many different types can be used this way: markers, buffers,
+strings, and functions.  Most often, input streams (character sources)
+obtain characters from the keyboard, a buffer, or a file, and output
+streams (character sinks) send characters to a buffer, such as a
+`*Help*' buffer, or to the echo area.
+
+   The object `nil', in addition to its other meanings, may be used as
+a stream.  It stands for the value of the variable `standard-input' or
+`standard-output'.  Also, the object `t' as a stream specifies input
+using the minibuffer (*note Minibuffers::) or output in the echo area
+(*note The Echo Area::).
+
+   Streams have no special printed representation or read syntax, and
+print as whatever primitive type they are.
+
+   *Note Read and Print::, for a description of functions related to
+streams, including parsing and printing functions.
+
+\1f
+File: lispref.info,  Node: Keymap Type,  Next: Syntax Table Type,  Prev: Stream Type,  Up: Editing Types
+
+Keymap Type
+-----------
+
+A "keymap" maps keys typed by the user to commands.  This mapping
+controls how the user's command input is executed.
+
+   NOTE: In XEmacs, a keymap is a separate primitive type.  In FSF GNU
+Emacs, a keymap is actually a list whose CAR is the symbol `keymap'.
+
+   *Note Keymaps::, for information about creating keymaps, handling
+prefix keys, local as well as global keymaps, and changing key bindings.
+
+\1f
+File: lispref.info,  Node: Syntax Table Type,  Next: Display Table Type,  Prev: Keymap Type,  Up: Editing Types
+
+Syntax Table Type
+-----------------
+
+Under XEmacs 20, a "syntax table" is a particular type of char table.
+Under XEmacs 19, a syntax table a vector of 256 integers.  In both
+cases, each element defines how one character is interpreted when it
+appears in a buffer.  For example, in C mode (*note Major Modes::), the
+`+' character is punctuation, but in Lisp mode it is a valid character
+in a symbol.  These modes specify different interpretations by changing
+the syntax table entry for `+'.
+
+   Syntax tables are used only for scanning text in buffers, not for
+reading Lisp expressions.  The table the Lisp interpreter uses to read
+expressions is built into the XEmacs source code and cannot be changed;
+thus, to change the list delimiters to be `{' and `}' instead of `('
+and `)' would be impossible.
+
+   *Note Syntax Tables::, for details about syntax classes and how to
+make and modify syntax tables.
+
+\1f
+File: lispref.info,  Node: Display Table Type,  Next: Database Type,  Prev: Syntax Table Type,  Up: Editing Types
+
+Display Table Type
+------------------
+
+A "display table" specifies how to display each character code.  Each
+buffer and each window can have its own display table.  A display table
+is actually a vector of length 256, although in XEmacs 20 this may
+change to be a particular type of char table.  *Note Display Tables::.
+
+\1f
+File: lispref.info,  Node: Database Type,  Next: Charset Type,  Prev: Display Table Type,  Up: Editing Types
+
+Database Type
+-------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Charset Type,  Next: Coding System Type,  Prev: Database Type,  Up: Editing Types
+
+Charset Type
+------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Coding System Type,  Next: ToolTalk Message Type,  Prev: Charset Type,  Up: Editing Types
+
+Coding System Type
+------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: ToolTalk Message Type,  Next: ToolTalk Pattern Type,  Prev: Coding System Type,  Up: Editing Types
+
+ToolTalk Message Type
+---------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: ToolTalk Pattern Type,  Prev: ToolTalk Message Type,  Up: Editing Types
+
+ToolTalk Pattern Type
+---------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Window-System Types,  Next: Type Predicates,  Prev: Editing Types,  Up: Lisp Data Types
+
+Window-System Types
+===================
+
+XEmacs also has some types that represent objects such as faces
+(collections of display characters), fonts, and pixmaps that are
+commonly found in windowing systems.
+
+* Menu:
+
+* Face Type::           A collection of display characteristics.
+* Glyph Type::          An image appearing in a buffer or elsewhere.
+* Specifier Type::      A way of controlling display characteristics on
+                          a per-buffer, -frame, -window, or -device level.
+* Font Instance Type::  The way a font appears on a particular device.
+* Color Instance Type:: The way a color appears on a particular device.
+* Image Instance Type:: The way an image appears on a particular device.
+* Toolbar Button Type:: An object representing a button in a toolbar.
+* Subwindow Type::      An externally-controlled window-system window
+                          appearing in a buffer.
+* X Resource Type::     A miscellaneous X resource, if Epoch support was
+                          compiled into XEmacs.
+
+\1f
+File: lispref.info,  Node: Face Type,  Next: Glyph Type,  Up: Window-System Types
+
+Face Type
+---------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Glyph Type,  Next: Specifier Type,  Prev: Face Type,  Up: Window-System Types
+
+Glyph Type
+----------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Specifier Type,  Next: Font Instance Type,  Prev: Glyph Type,  Up: Window-System Types
+
+Specifier Type
+--------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Font Instance Type,  Next: Color Instance Type,  Prev: Specifier Type,  Up: Window-System Types
+
+Font Instance Type
+------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Color Instance Type,  Next: Image Instance Type,  Prev: Font Instance Type,  Up: Window-System Types
+
+Color Instance Type
+-------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Image Instance Type,  Next: Toolbar Button Type,  Prev: Color Instance Type,  Up: Window-System Types
+
+Image Instance Type
+-------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Toolbar Button Type,  Next: Subwindow Type,  Prev: Image Instance Type,  Up: Window-System Types
+
+Toolbar Button Type
+-------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Subwindow Type,  Next: X Resource Type,  Prev: Toolbar Button Type,  Up: Window-System Types
+
+Subwindow Type
+--------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: X Resource Type,  Prev: Subwindow Type,  Up: Window-System Types
+
+X Resource Type
+---------------
+
+(not yet documented)
+
+\1f
+File: lispref.info,  Node: Type Predicates,  Next: Equality Predicates,  Prev: Window-System Types,  Up: Lisp Data Types
+
+Type Predicates
+===============
+
+The XEmacs Lisp interpreter itself does not perform type checking on
+the actual arguments passed to functions when they are called.  It could
+not do so, since function arguments in Lisp do not have declared data
+types, as they do in other programming languages.  It is therefore up to
+the individual function to test whether each actual argument belongs to
+a type that the function can use.
+
+   All built-in functions do check the types of their actual arguments
+when appropriate, and signal a `wrong-type-argument' error if an
+argument is of the wrong type.  For example, here is what happens if you
+pass an argument to `+' that it cannot handle:
+
+     (+ 2 'a)
+          error--> Wrong type argument: integer-or-marker-p, a
+
+   If you want your program to handle different types differently, you
+must do explicit type checking.  The most common way to check the type
+of an object is to call a "type predicate" function.  Emacs has a type
+predicate for each type, as well as some predicates for combinations of
+types.
+
+   A type predicate function takes one argument; it returns `t' if the
+argument belongs to the appropriate type, and `nil' otherwise.
+Following a general Lisp convention for predicate functions, most type
+predicates' names end with `p'.
+
+   Here is an example which uses the predicates `listp' to check for a
+list and `symbolp' to check for a symbol.
+
+     (defun add-on (x)
+       (cond ((symbolp x)
+              ;; If X is a symbol, put it on LIST.
+              (setq list (cons x list)))
+             ((listp x)
+              ;; If X is a list, add its elements to LIST.
+              (setq list (append x list)))
+             (t
+              ;; We only handle symbols and lists.
+              (error "Invalid argument %s in add-on" x))))
+
+   Here is a table of predefined type predicates, in alphabetical order,
+with references to further information.
+
+`annotationp'
+     *Note annotationp: Annotation Primitives.
+
+`arrayp'
+     *Note arrayp: Array Functions.
+
+`atom'
+     *Note atom: List-related Predicates.
+
+`bit-vector-p'
+     *Note bit-vector-p: Bit Vector Functions.
+
+`bitp'
+     *Note bitp: Bit Vector Functions.
+
+`boolean-specifier-p'
+     *Note boolean-specifier-p: Specifier Types.
+
+`buffer-glyph-p'
+     *Note buffer-glyph-p: Glyph Types.
+
+`buffer-live-p'
+     *Note buffer-live-p: Killing Buffers.
+
+`bufferp'
+     *Note bufferp: Buffer Basics.
+
+`button-event-p'
+     *Note button-event-p: Event Predicates.
+
+`button-press-event-p'
+     *Note button-press-event-p: Event Predicates.
+
+`button-release-event-p'
+     *Note button-release-event-p: Event Predicates.
+
+`case-table-p'
+     *Note case-table-p: Case Tables.
+
+`char-int-p'
+     *Note char-int-p: Character Codes.
+
+`char-or-char-int-p'
+     *Note char-or-char-int-p: Character Codes.
+
+`char-or-string-p'
+     *Note char-or-string-p: Predicates for Strings.
+
+`char-table-p'
+     *Note char-table-p: Char Tables.
+
+`characterp'
+     *Note characterp: Predicates for Characters.
+
+`color-instance-p'
+     *Note color-instance-p: Colors.
+
+`color-pixmap-image-instance-p'
+     *Note color-pixmap-image-instance-p: Image Instance Types.
+
+`color-specifier-p'
+     *Note color-specifier-p: Specifier Types.
+
+`commandp'
+     *Note commandp: Interactive Call.
+
+`compiled-function-p'
+     *Note compiled-function-p: Compiled-Function Type.
+
+`console-live-p'
+     *Note console-live-p: Connecting to a Console or Device.
+
+`consolep'
+     *Note consolep: Consoles and Devices.
+
+`consp'
+     *Note consp: List-related Predicates.
+
+`database-live-p'
+     *Note database-live-p: Connecting to a Database.
+
+`databasep'
+     *Note databasep: Databases.
+
+`device-live-p'
+     *Note device-live-p: Connecting to a Console or Device.
+
+`device-or-frame-p'
+     *Note device-or-frame-p: Basic Device Functions.
+
+`devicep'
+     *Note devicep: Consoles and Devices.
+
+`eval-event-p'
+     *Note eval-event-p: Event Predicates.
+
+`event-live-p'
+     *Note event-live-p: Event Predicates.
+
+`eventp'
+     *Note eventp: Events.
+
+`extent-live-p'
+     *Note extent-live-p: Creating and Modifying Extents.
+
+`extentp'
+     *Note extentp: Extents.
+
+`face-boolean-specifier-p'
+     *Note face-boolean-specifier-p: Specifier Types.
+
+`facep'
+     *Note facep: Basic Face Functions.
+
+`floatp'
+     *Note floatp: Predicates on Numbers.
+
+`font-instance-p'
+     *Note font-instance-p: Fonts.
+
+`font-specifier-p'
+     *Note font-specifier-p: Specifier Types.
+
+`frame-live-p'
+     *Note frame-live-p: Deleting Frames.
+
+`framep'
+     *Note framep: Frames.
+
+`functionp'
+     (not yet documented)
+
+`generic-specifier-p'
+     *Note generic-specifier-p: Specifier Types.
+
+`glyphp'
+     *Note glyphp: Glyphs.
+
+`hash-table-p'
+     *Note hash-table-p: Hash Tables.
+
+`icon-glyph-p'
+     *Note icon-glyph-p: Glyph Types.
+
+`image-instance-p'
+     *Note image-instance-p: Images.
+
+`image-specifier-p'
+     *Note image-specifier-p: Specifier Types.
+
+`integer-char-or-marker-p'
+     *Note integer-char-or-marker-p: Predicates on Markers.
+
+`integer-or-char-p'
+     *Note integer-or-char-p: Predicates for Characters.
+
+`integer-or-marker-p'
+     *Note integer-or-marker-p: Predicates on Markers.
+
+`integer-specifier-p'
+     *Note integer-specifier-p: Specifier Types.
+
+`integerp'
+     *Note integerp: Predicates on Numbers.
+
+`itimerp'
+     (not yet documented)
+
+`key-press-event-p'
+     *Note key-press-event-p: Event Predicates.
+
+`keymapp'
+     *Note keymapp: Creating Keymaps.
+
+`keywordp'
+     (not yet documented)
+
+`listp'
+     *Note listp: List-related Predicates.
+
+`markerp'
+     *Note markerp: Predicates on Markers.
+
+`misc-user-event-p'
+     *Note misc-user-event-p: Event Predicates.
+
+`mono-pixmap-image-instance-p'
+     *Note mono-pixmap-image-instance-p: Image Instance Types.
+
+`motion-event-p'
+     *Note motion-event-p: Event Predicates.
+
+`mouse-event-p'
+     *Note mouse-event-p: Event Predicates.
+
+`natnum-specifier-p'
+     *Note natnum-specifier-p: Specifier Types.
+
+`natnump'
+     *Note natnump: Predicates on Numbers.
+
+`nlistp'
+     *Note nlistp: List-related Predicates.
+
+`nothing-image-instance-p'
+     *Note nothing-image-instance-p: Image Instance Types.
+
+`number-char-or-marker-p'
+     *Note number-char-or-marker-p: Predicates on Markers.
+
+`number-or-marker-p'
+     *Note number-or-marker-p: Predicates on Markers.
+
+`numberp'
+     *Note numberp: Predicates on Numbers.
+
+`pointer-glyph-p'
+     *Note pointer-glyph-p: Glyph Types.
+
+`pointer-image-instance-p'
+     *Note pointer-image-instance-p: Image Instance Types.
+
+`process-event-p'
+     *Note process-event-p: Event Predicates.
+
+`processp'
+     *Note processp: Processes.
+
+`range-table-p'
+     *Note range-table-p: Range Tables.
+
+`ringp'
+     (not yet documented)
+
+`sequencep'
+     *Note sequencep: Sequence Functions.
+
+`specifierp'
+     *Note specifierp: Specifiers.
+
+`stringp'
+     *Note stringp: Predicates for Strings.
+
+`subrp'
+     *Note subrp: Function Cells.
+
+`subwindow-image-instance-p'
+     *Note subwindow-image-instance-p: Image Instance Types.
+
+`subwindowp'
+     *Note subwindowp: Subwindows.
+
+`symbolp'
+     *Note symbolp: Symbols.
+
+`syntax-table-p'
+     *Note syntax-table-p: Syntax Tables.
+
+`text-image-instance-p'
+     *Note text-image-instance-p: Image Instance Types.
+
+`timeout-event-p'
+     *Note timeout-event-p: Event Predicates.
+
+`toolbar-button-p'
+     *Note toolbar-button-p: Toolbar.
+
+`toolbar-specifier-p'
+     *Note toolbar-specifier-p: Toolbar.
+
+`user-variable-p'
+     *Note user-variable-p: Defining Variables.
+
+`vectorp'
+     *Note vectorp: Vectors.
+
+`weak-list-p'
+     *Note weak-list-p: Weak Lists.
+
+`window-configuration-p'
+     *Note window-configuration-p: Window Configurations.
+
+`window-live-p'
+     *Note window-live-p: Deleting Windows.
+
+`windowp'
+     *Note windowp: Basic Windows.
+
+   The most general way to check the type of an object is to call the
+function `type-of'.  Recall that each object belongs to one and only
+one primitive type; `type-of' tells you which one (*note Lisp Data
+Types::).  But `type-of' knows nothing about non-primitive types.  In
+most cases, it is more convenient to use type predicates than `type-of'.
+
+ - Function: type-of object
+     This function returns a symbol naming the primitive type of
+     OBJECT.  The value is one of `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', or `x-resource'.
+
+          (type-of 1)
+               => integer
+          (type-of 'nil)
+               => symbol
+          (type-of '())    ; `()' is `nil'.
+               => symbol
+          (type-of '(x))
+               => cons
+
+\1f
+File: lispref.info,  Node: Equality Predicates,  Prev: Type Predicates,  Up: Lisp Data Types
+
+Equality Predicates
+===================
+
+Here we describe two functions that test for equality between any two
+objects.  Other functions test equality between objects of specific
+types, e.g., strings.  For these predicates, see the appropriate chapter
+describing the data type.
+
+ - Function: eq object1 object2
+     This function returns `t' if OBJECT1 and OBJECT2 are the same
+     object, `nil' otherwise.  The "same object" means that a change in
+     one will be reflected by the same change in the other.
+
+     `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
+     value.  Also, since symbol names are normally unique, if the
+     arguments are symbols with the same name, they are `eq'.  For
+     other types (e.g., lists, vectors, strings), two arguments with
+     the same contents or elements are not necessarily `eq' to each
+     other: they are `eq' only if they are the same object.
+
+     (The `make-symbol' function returns an uninterned symbol that is
+     not interned in the standard `obarray'.  When uninterned symbols
+     are in use, symbol names are no longer unique.  Distinct symbols
+     with the same name are not `eq'.  *Note Creating Symbols::.)
+
+     NOTE: Under XEmacs 19, characters are really just integers, and
+     thus characters and integers are `eq'.  Under XEmacs 20, it was
+     necessary to preserve remnants of this in function such as `old-eq'
+     in order to maintain byte-code compatibility.  Byte code compiled
+     under any Emacs 19 will automatically have calls to `eq' mapped to
+     `old-eq' when executed under XEmacs 20.
+
+          (eq 'foo 'foo)
+               => t
+          
+          (eq 456 456)
+               => t
+          
+          (eq "asdf" "asdf")
+               => nil
+          
+          (eq '(1 (2 (3))) '(1 (2 (3))))
+               => nil
+          
+          (setq foo '(1 (2 (3))))
+               => (1 (2 (3)))
+          (eq foo foo)
+               => t
+          (eq foo '(1 (2 (3))))
+               => nil
+          
+          (eq [(1 2) 3] [(1 2) 3])
+               => nil
+          
+          (eq (point-marker) (point-marker))
+               => nil
+
+
+ - Function: old-eq object1 object2
+     This function exists under XEmacs 20 and is exactly like `eq'
+     except that it suffers from the char-int confoundance disease.  In
+     other words, it returns `t' if given a character and the
+     equivalent integer, even though the objects are of different types!
+     You should _not_ ever call this function explicitly in your code.
+     However, be aware that all calls to `eq' in byte code compiled
+     under version 19 map to `old-eq' in XEmacs 20.  (Likewise for
+     `old-equal', `old-memq', `old-member', `old-assq' and
+     `old-assoc'.)
+
+          ;; Remember, this does not apply under XEmacs 19.
+          ?A
+               => ?A
+          (char-int ?A)
+               => 65
+          (old-eq ?A 65)
+               => t               ; Eek, we've been infected.
+          (eq ?A 65)
+               => nil             ; We are still healthy.
+
+ - Function: equal object1 object2
+     This function returns `t' if OBJECT1 and OBJECT2 have equal
+     components, `nil' otherwise.  Whereas `eq' tests if its arguments
+     are the same object, `equal' looks inside nonidentical arguments
+     to see if their elements are the same.  So, if two objects are
+     `eq', they are `equal', but the converse is not always true.
+
+          (equal 'foo 'foo)
+               => t
+          
+          (equal 456 456)
+               => t
+          
+          (equal "asdf" "asdf")
+               => t
+          (eq "asdf" "asdf")
+               => nil
+          
+          (equal '(1 (2 (3))) '(1 (2 (3))))
+               => t
+          (eq '(1 (2 (3))) '(1 (2 (3))))
+               => nil
+          
+          (equal [(1 2) 3] [(1 2) 3])
+               => t
+          (eq [(1 2) 3] [(1 2) 3])
+               => nil
+          
+          (equal (point-marker) (point-marker))
+               => t
+          
+          (eq (point-marker) (point-marker))
+               => nil
+
+     Comparison of strings is case-sensitive.
+
+     Note that in FSF GNU Emacs, comparison of strings takes into
+     account their text properties, and you have to use `string-equal'
+     if you want only the strings themselves compared.  This difference
+     does not exist in XEmacs; `equal' and `string-equal' always return
+     the same value on the same strings.
+
+          (equal "asdf" "ASDF")
+               => nil
+
+     Two distinct buffers are never `equal', even if their contents are
+     the same.
+
+   The test for equality is implemented recursively, and circular lists
+may therefore cause infinite recursion (leading to an error).
+
+\1f
+File: lispref.info,  Node: Numbers,  Next: Strings and Characters,  Prev: Lisp Data Types,  Up: Top
+
+Numbers
+*******
+
+XEmacs supports two numeric data types: "integers" and "floating point
+numbers".  Integers are whole numbers such as -3, 0, #b0111, #xFEED,
+#o744.  Their values are exact.  The number prefixes `#b', `#o', and
+`#x' are supported to represent numbers in binary, octal, and
+hexadecimal notation (or radix).  Floating point numbers are numbers
+with fractional parts, such as -4.5, 0.0, or 2.71828.  They can also be
+expressed in exponential notation: 1.5e2 equals 150; in this example,
+`e2' stands for ten to the second power, and is multiplied by 1.5.
+Floating point values are not exact; they have a fixed, limited amount
+of precision.
+
+* Menu:
+
+* 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.
+* Numeric Conversions::              Converting float to integer and vice versa.
+* Arithmetic Operations::     How to add, subtract, multiply and divide.
+* Rounding Operations::       Explicitly rounding floating point numbers.
+* Bitwise Operations::        Logical and, or, not, shifting.
+* Math Functions::            Trig, exponential and logarithmic functions.
+* Random Numbers::            Obtaining random integers, predictable or not.
+
+\1f
+File: lispref.info,  Node: Integer Basics,  Next: Float Basics,  Up: Numbers
+
+Integer Basics
+==============
+
+The range of values for an integer depends on the machine.  The minimum
+range is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1),
+but some machines may provide a wider range.  Many examples in this
+chapter assume an integer has 28 bits.
+
+   The Lisp reader reads an integer as a sequence of digits with
+optional initial sign and optional final period.
+
+      1               ; The integer 1.
+      1.              ; The integer 1.
+     +1               ; Also the integer 1.
+     -1               ; The integer -1.
+      268435457       ; Also the integer 1, due to overflow.
+      0               ; The integer 0.
+     -0               ; The integer 0.
+
+   To understand how various functions work on integers, especially the
+bitwise operators (*note Bitwise Operations::), it is often helpful to
+view the numbers in their binary form.
+
+   In 28-bit binary, the decimal integer 5 looks like this:
+
+     0000  0000 0000  0000 0000  0000 0101
+
+(We have inserted spaces between groups of 4 bits, and two spaces
+between groups of 8 bits, to make the binary integer easier to read.)
+
+   The integer -1 looks like this:
+
+     1111  1111 1111  1111 1111  1111 1111
+
+-1 is represented as 28 ones.  (This is called "two's complement"
+notation.)
+
+   The negative integer, -5, is creating by subtracting 4 from -1.  In
+binary, the decimal integer 4 is 100.  Consequently, -5 looks like this:
+
+     1111  1111 1111  1111 1111  1111 1011
+
+   In this implementation, the largest 28-bit binary integer is the
+decimal integer 134,217,727.  In binary, it looks like this:
+
+     0111  1111 1111  1111 1111  1111 1111
+
+   Since the arithmetic functions do not check whether integers go
+outside their range, when you add 1 to 134,217,727, the value is the
+negative integer -134,217,728:
+
+     (+ 1 134217727)
+          => -134217728
+          => 1000  0000 0000  0000 0000  0000 0000
+
+   Many of the following functions accept markers for arguments as well
+as integers.  (*Note Markers::.)  More precisely, the actual arguments
+to such functions may be either integers or markers, which is why we
+often give these arguments the name INT-OR-MARKER.  When the argument
+value is a marker, its position value is used and its buffer is ignored.
+
+\1f
+File: lispref.info,  Node: Float Basics,  Next: Predicates on Numbers,  Prev: Integer Basics,  Up: Numbers
+
+Floating Point Basics
+=====================
+
+XEmacs supports floating point numbers.  The precise range of floating
+point numbers is machine-specific; it is the same as the range of the C
+data type `double' on the machine in question.
+
+   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.  You can also use a minus sign to write
+negative floating point numbers, as in `-1.0'.
+
+   Most modern computers support the IEEE floating point standard, which
+provides for positive infinity and negative infinity as floating point
+values.  It also provides for a class of values called NaN or
+"not-a-number"; numerical functions return such values in cases where
+there is no correct answer.  For example, `(sqrt -1.0)' returns a NaN.
+For practical purposes, there's no significant difference between
+different NaN values in XEmacs Lisp, and there's no rule for precisely
+which NaN value should be used in a particular case, so this manual
+doesn't try to distinguish them.  XEmacs Lisp has no read syntax for
+NaNs or infinities; perhaps we should create a syntax in the future.
+
+   You can use `logb' to extract the binary exponent of a floating
+point number (or estimate the logarithm of an integer):
+
+ - Function: logb number
+     This function returns the binary exponent of NUMBER.  More
+     precisely, the value is the logarithm of NUMBER base 2, rounded
+     down to an integer.
+
+\1f
+File: lispref.info,  Node: Predicates on Numbers,  Next: Comparison of Numbers,  Prev: Float Basics,  Up: Numbers
+
+Type Predicates for Numbers
+===========================
+
+The functions in this section test whether the argument is a number or
+whether it is a certain sort of number.  The functions `integerp' and
+`floatp' can take any type of Lisp object as argument (the predicates
+would not be of much use otherwise); but the `zerop' predicate requires
+a number as its argument.  See also `integer-or-marker-p',
+`integer-char-or-marker-p', `number-or-marker-p' and
+`number-char-or-marker-p', in *Note Predicates on Markers::.
+
+ - Function: floatp object
+     This predicate tests whether its argument is a floating point
+     number and returns `t' if so, `nil' otherwise.
+
+     `floatp' does not exist in Emacs versions 18 and earlier.
+
+ - Function: integerp object
+     This predicate tests whether its argument is an integer, and
+     returns `t' if so, `nil' otherwise.
+
+ - Function: numberp object
+     This predicate tests whether its argument is a number (either
+     integer or floating point), and returns `t' if so, `nil' otherwise.
+
+ - Function: natnump object
+     The `natnump' predicate (whose name comes from the phrase
+     "natural-number-p") tests to see whether its argument is a
+     nonnegative integer, and returns `t' if so, `nil' otherwise.  0 is
+     considered non-negative.
+
+ - Function: zerop number
+     This predicate tests whether its argument is zero, and returns `t'
+     if so, `nil' otherwise.  The argument must be a number.
+
+     These two forms are equivalent: `(zerop x)' == `(= x 0)'.
+
+\1f
+File: lispref.info,  Node: Comparison of Numbers,  Next: Numeric Conversions,  Prev: Predicates on Numbers,  Up: Numbers
+
+Comparison of Numbers
+=====================
+
+To test numbers for numerical equality, you should normally use `=',
+not `eq'.  There can be many distinct floating point number objects
+with the same numeric value.  If you use `eq' to compare them, then you
+test whether two values are the same _object_.  By contrast, `='
+compares only the numeric values of the objects.
+
+   At present, each integer value has a unique Lisp object in XEmacs
+Lisp.  Therefore, `eq' is equivalent to `=' where integers are
+concerned.  It is sometimes convenient to use `eq' for comparing an
+unknown value with an integer, because `eq' does not report an error if
+the unknown value is not a number--it accepts arguments of any type.
+By contrast, `=' signals an error if the arguments are not numbers or
+markers.  However, it is a good idea to use `=' if you can, even for
+comparing integers, just in case we change the representation of
+integers in a future XEmacs version.
+
+   There is another wrinkle: because floating point arithmetic is not
+exact, it is often a bad idea to check for equality of two floating
+point values.  Usually it is better to test for approximate equality.
+Here's a function to do this:
+
+     (defconst fuzz-factor 1.0e-6)
+     (defun approx-equal (x y)
+       (or (and (= x 0) (= y 0))
+           (< (/ (abs (- x y))
+                 (max (abs x) (abs y)))
+              fuzz-factor)))
+
+     Common Lisp note: Comparing numbers in Common Lisp always requires
+     `=' because Common Lisp implements multi-word integers, and two
+     distinct integer objects can have the same numeric value.  XEmacs
+     Lisp can have just one integer object for any given value because
+     it has a limited range of integer values.
+
+   In addition to numbers, all of the following functions also accept
+characters and markers as arguments, and treat them as their number
+equivalents.
+
+ - Function: = number &rest more-numbers
+     This function returns `t' if all of its arguments are numerically
+     equal, `nil' otherwise.
+
+          (= 5)
+               => t
+          (= 5 6)
+               => nil
+          (= 5 5.0)
+               => t
+          (= 5 5 6)
+               => nil
+
+ - Function: /= number &rest more-numbers
+     This function returns `t' if no two arguments are numerically
+     equal, `nil' otherwise.
+
+          (/= 5 6)
+               => t
+          (/= 5 5 6)
+               => nil
+          (/= 5 6 1)
+               => t
+
+ - Function: < number &rest more-numbers
+     This function returns `t' if the sequence of its arguments is
+     monotonically increasing, `nil' otherwise.
+
+          (< 5 6)
+               => t
+          (< 5 6 6)
+               => nil
+          (< 5 6 7)
+               => t
+
+ - Function: <= number &rest more-numbers
+     This function returns `t' if the sequence of its arguments is
+     monotonically nondecreasing, `nil' otherwise.
+
+          (<= 5 6)
+               => t
+          (<= 5 6 6)
+               => t
+          (<= 5 6 5)
+               => nil
+
+ - Function: > number &rest more-numbers
+     This function returns `t' if the sequence of its arguments is
+     monotonically decreasing, `nil' otherwise.
+
+ - Function: >= number &rest more-numbers
+     This function returns `t' if the sequence of its arguments is
+     monotonically nonincreasing, `nil' otherwise.
+
+ - Function: max number &rest more-numbers
+     This function returns the largest of its arguments.
+
+          (max 20)
+               => 20
+          (max 1 2.5)
+               => 2.5
+          (max 1 3 2.5)
+               => 3
+
+ - Function: min number &rest more-numbers
+     This function returns the smallest of its arguments.
+
+          (min -4 1)
+               => -4
+
+\1f
+File: lispref.info,  Node: Numeric Conversions,  Next: Arithmetic Operations,  Prev: Comparison of Numbers,  Up: Numbers
+
+Numeric Conversions
+===================
+
+To convert an integer to floating point, use the function `float'.
+
+ - Function: float number
+     This returns NUMBER converted to floating point.  If NUMBER is
+     already a floating point number, `float' returns it unchanged.
+
+   There are four functions to convert floating point numbers to
+integers; they differ in how they round.  These functions accept
+integer arguments also, and return such arguments unchanged.
+
+ - Function: truncate number
+     This returns NUMBER, converted to an integer by rounding towards
+     zero.
+
+ - Function: floor number &optional divisor
+     This returns NUMBER, converted to an integer by rounding downward
+     (towards negative infinity).
+
+     If DIVISOR is specified, NUMBER is divided by DIVISOR before the
+     floor is taken; this is the division operation that corresponds to
+     `mod'.  An `arith-error' results if DIVISOR is 0.
+
+ - Function: ceiling number
+     This returns NUMBER, converted to an integer by rounding upward
+     (towards positive infinity).
+
+ - Function: round number
+     This returns NUMBER, converted to an integer by rounding towards
+     the nearest integer.  Rounding a value equidistant between two
+     integers may choose the integer closer to zero, or it may prefer
+     an even integer, depending on your machine.
+
+\1f
+File: lispref.info,  Node: Arithmetic Operations,  Next: Rounding Operations,  Prev: Numeric Conversions,  Up: Numbers
+
+Arithmetic Operations
+=====================
+
+XEmacs Lisp provides the traditional four arithmetic operations:
+addition, subtraction, multiplication, and division.  Remainder and
+modulus functions supplement the division functions.  The functions to
+add or subtract 1 are provided because they are traditional in Lisp and
+commonly used.
+
+   All of these functions except `%' return a floating point value if
+any argument is floating.
+
+   It is important to note that in XEmacs Lisp, arithmetic functions do
+not check for overflow.  Thus `(1+ 134217727)' may evaluate to
+-134217728, depending on your hardware.
+
+ - Function: 1+ number
+     This function returns NUMBER plus one.  NUMBER may be a number,
+     character or marker.  Markers and characters are converted to
+     integers.
+
+     For example,
+
+          (setq foo 4)
+               => 4
+          (1+ foo)
+               => 5
+
+     This function is not analogous to the C operator `++'--it does not
+     increment a variable.  It just computes a sum.  Thus, if we
+     continue,
+
+          foo
+               => 4
+
+     If you want to increment the variable, you must use `setq', like
+     this:
+
+          (setq foo (1+ foo))
+               => 5
+
+     Now that the `cl' package is always available from lisp code, a
+     more convenient and natural way to increment a variable is
+     `(incf foo)'.
+
+ - Function: 1- number
+     This function returns NUMBER minus one.  NUMBER may be a number,
+     character or marker.  Markers and characters are converted to
+     integers.
+
+ - Function: abs number
+     This returns the absolute value of NUMBER.
+
+ - Function: + &rest numbers
+     This function adds its arguments together.  When given no
+     arguments, `+' returns 0.
+
+     If any of the arguments are characters or markers, they are first
+     converted to integers.
+
+          (+)
+               => 0
+          (+ 1)
+               => 1
+          (+ 1 2 3 4)
+               => 10
+
+ - Function: - &optional number &rest other-numbers
+     The `-' function serves two purposes: negation and subtraction.
+     When `-' has a single argument, the value is the negative of the
+     argument.  When there are multiple arguments, `-' subtracts each of
+     the OTHER-NUMBERS from NUMBER, cumulatively.  If there are no
+     arguments, an error is signaled.
+
+     If any of the arguments are characters or markers, they are first
+     converted to integers.
+
+          (- 10 1 2 3 4)
+               => 0
+          (- 10)
+               => -10
+          (-)
+               => 0
+
+ - Function: * &rest numbers
+     This function multiplies its arguments together, and returns the
+     product.  When given no arguments, `*' returns 1.
+
+     If any of the arguments are characters or markers, they are first
+     converted to integers.
+
+          (*)
+               => 1
+          (* 1)
+               => 1
+          (* 1 2 3 4)
+               => 24
+
+ - Function: / dividend &rest divisors
+     The `/' function serves two purposes: inversion and division.  When
+     `/' has a single argument, the value is the inverse of the
+     argument.  When there are multiple arguments, `/' divides DIVIDEND
+     by each of the DIVISORS, cumulatively, returning the quotient.  If
+     there are no arguments, an error is signaled.
+
+     If none of the arguments are floats, then the result is an integer.
+     This means the result has to be rounded.  On most machines, the
+     result is rounded towards zero after each division, but some
+     machines may round differently with negative arguments.  This is
+     because the Lisp function `/' is implemented using the C division
+     operator, which also permits machine-dependent rounding.  As a
+     practical matter, all known machines round in the standard fashion.
+
+     If any of the arguments are characters or markers, they are first
+     converted to integers.
+
+     If you divide by 0, an `arith-error' error is signaled.  (*Note
+     Errors::.)
+
+          (/ 6 2)
+               => 3
+          (/ 5 2)
+               => 2
+          (/ 25 3 2)
+               => 4
+          (/ 3.0)
+               => 0.3333333333333333
+          (/ -17 6)
+               => -2
+
+     The result of `(/ -17 6)' could in principle be -3 on some
+     machines.
+
+ - Function: % dividend divisor
+     This function returns the integer remainder after division of
+     DIVIDEND by DIVISOR.  The arguments must be integers or markers.
+
+     For negative arguments, the remainder is in principle
+     machine-dependent since the quotient is; but in practice, all
+     known machines behave alike.
+
+     An `arith-error' results if DIVISOR is 0.
+
+          (% 9 4)
+               => 1
+          (% -9 4)
+               => -1
+          (% 9 -4)
+               => 1
+          (% -9 -4)
+               => -1
+
+     For any two integers DIVIDEND and DIVISOR,
+
+          (+ (% DIVIDEND DIVISOR)
+             (* (/ DIVIDEND DIVISOR) DIVISOR))
+
+     always equals DIVIDEND.
+
+ - Function: mod dividend divisor
+     This function returns the value of DIVIDEND modulo DIVISOR; in
+     other words, the remainder after division of DIVIDEND by DIVISOR,
+     but with the same sign as DIVISOR.  The arguments must be numbers
+     or markers.
+
+     Unlike `%', `mod' returns a well-defined result for negative
+     arguments.  It also permits floating point arguments; it rounds the
+     quotient downward (towards minus infinity) to an integer, and uses
+     that quotient to compute the remainder.
+
+     An `arith-error' results if DIVISOR is 0.
+
+          (mod 9 4)
+               => 1
+          (mod -9 4)
+               => 3
+          (mod 9 -4)
+               => -3
+          (mod -9 -4)
+               => -1
+          (mod 5.5 2.5)
+               => .5
+
+     For any two numbers DIVIDEND and DIVISOR,
+
+          (+ (mod DIVIDEND DIVISOR)
+             (* (floor DIVIDEND DIVISOR) DIVISOR))
+
+     always equals DIVIDEND, subject to rounding error if either
+     argument is floating point.  For `floor', see *Note Numeric
+     Conversions::.
+
+\1f
+File: lispref.info,  Node: Rounding Operations,  Next: Bitwise Operations,  Prev: Arithmetic Operations,  Up: Numbers
+
+Rounding Operations
+===================
+
+The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
+floating point argument and return a floating point result whose value
+is a nearby integer.  `ffloor' returns the nearest integer below;
+`fceiling', the nearest integer above; `ftruncate', the nearest integer
+in the direction towards zero; `fround', the nearest integer.
+
+ - Function: ffloor number
+     This function rounds NUMBER to the next lower integral value, and
+     returns that value as a floating point number.
+
+ - Function: fceiling number
+     This function rounds NUMBER to the next higher integral value, and
+     returns that value as a floating point number.
+
+ - Function: ftruncate number
+     This function rounds NUMBER towards zero to an integral value, and
+     returns that value as a floating point number.
+
+ - Function: fround number
+     This function rounds NUMBER to the nearest integral value, and
+     returns that value as a floating point number.
+
+\1f
+File: lispref.info,  Node: Bitwise Operations,  Next: Math Functions,  Prev: Rounding Operations,  Up: Numbers
+
+Bitwise Operations on Integers
+==============================
+
+In a computer, an integer is represented as a binary number, a sequence
+of "bits" (digits which are either zero or one).  A bitwise operation
+acts on the individual bits of such a sequence.  For example,
+"shifting" moves the whole sequence left or right one or more places,
+reproducing the same pattern "moved over".
+
+   The bitwise operations in XEmacs Lisp apply only to integers.
+
+ - Function: lsh integer1 count
+     `lsh', which is an abbreviation for "logical shift", shifts the
+     bits in INTEGER1 to the left COUNT places, or to the right if
+     COUNT is negative, bringing zeros into the vacated bits.  If COUNT
+     is negative, `lsh' shifts zeros into the leftmost
+     (most-significant) bit, producing a positive result even if
+     INTEGER1 is negative.  Contrast this with `ash', below.
+
+     Here are two examples of `lsh', shifting a pattern of bits one
+     place to the left.  We show only the low-order eight bits of the
+     binary pattern; the rest are all zero.
+
+          (lsh 5 1)
+               => 10
+          ;; Decimal 5 becomes decimal 10.
+          00000101 => 00001010
+          
+          (lsh 7 1)
+               => 14
+          ;; Decimal 7 becomes decimal 14.
+          00000111 => 00001110
+
+     As the examples illustrate, shifting the pattern of bits one place
+     to the left produces a number that is twice the value of the
+     previous number.
+
+     Shifting a pattern of bits two places to the left produces results
+     like this (with 8-bit binary numbers):
+
+          (lsh 3 2)
+               => 12
+          ;; Decimal 3 becomes decimal 12.
+          00000011 => 00001100
+
+     On the other hand, shifting one place to the right looks like this:
+
+          (lsh 6 -1)
+               => 3
+          ;; Decimal 6 becomes decimal 3.
+          00000110 => 00000011
+          
+          (lsh 5 -1)
+               => 2
+          ;; Decimal 5 becomes decimal 2.
+          00000101 => 00000010
+
+     As the example illustrates, shifting one place to the right
+     divides the value of a positive integer by two, rounding downward.
+
+     The function `lsh', like all XEmacs Lisp arithmetic functions, does
+     not check for overflow, so shifting left can discard significant
+     bits and change the sign of the number.  For example, left shifting
+     134,217,727 produces -2 on a 28-bit machine:
+
+          (lsh 134217727 1)          ; left shift
+               => -2
+
+     In binary, in the 28-bit implementation, the argument looks like
+     this:
+
+          ;; Decimal 134,217,727
+          0111  1111 1111  1111 1111  1111 1111
+
+     which becomes the following when left shifted:
+
+          ;; Decimal -2
+          1111  1111 1111  1111 1111  1111 1110
+
+ - Function: ash integer1 count
+     `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
+     COUNT places, or to the right if COUNT is negative.
+
+     `ash' gives the same results as `lsh' except when INTEGER1 and
+     COUNT are both negative.  In that case, `ash' puts ones in the
+     empty bit positions on the left, while `lsh' puts zeros in those
+     bit positions.
+
+     Thus, with `ash', shifting the pattern of bits one place to the
+     right looks like this:
+
+          (ash -6 -1) => -3
+          ;; Decimal -6 becomes decimal -3.
+          1111  1111 1111  1111 1111  1111 1010
+               =>
+          1111  1111 1111  1111 1111  1111 1101
+
+     In contrast, shifting the pattern of bits one place to the right
+     with `lsh' looks like this:
+
+          (lsh -6 -1) => 134217725
+          ;; Decimal -6 becomes decimal 134,217,725.
+          1111  1111 1111  1111 1111  1111 1010
+               =>
+          0111  1111 1111  1111 1111  1111 1101
+
+     Here are other examples:
+
+                             ;               28-bit binary values
+          
+          (lsh 5 2)          ;   5  =  0000  0000 0000  0000 0000  0000 0101
+               => 20         ;      =  0000  0000 0000  0000 0000  0001 0100
+          (ash 5 2)
+               => 20
+          (lsh -5 2)         ;  -5  =  1111  1111 1111  1111 1111  1111 1011
+               => -20        ;      =  1111  1111 1111  1111 1111  1110 1100
+          (ash -5 2)
+               => -20
+          (lsh 5 -2)         ;   5  =  0000  0000 0000  0000 0000  0000 0101
+               => 1          ;      =  0000  0000 0000  0000 0000  0000 0001
+          (ash 5 -2)
+               => 1
+          (lsh -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
+               => 4194302    ;      =  0011  1111 1111  1111 1111  1111 1110
+          (ash -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
+               => -2         ;      =  1111  1111 1111  1111 1111  1111 1110
+
+ - Function: logand &rest ints-or-markers
+     This function returns the "logical and" of the arguments: the Nth
+     bit is set in the result if, and only if, the Nth bit is set in
+     all the arguments.  ("Set" means that the value of the bit is 1
+     rather than 0.)
+
+     For example, using 4-bit binary numbers, the "logical and" of 13
+     and 12 is 12: 1101 combined with 1100 produces 1100.  In both the
+     binary numbers, the leftmost two bits are set (i.e., they are
+     1's), so the leftmost two bits of the returned value are set.
+     However, for the rightmost two bits, each is zero in at least one
+     of the arguments, so the rightmost two bits of the returned value
+     are 0's.
+
+     Therefore,
+
+          (logand 13 12)
+               => 12
+
+     If `logand' is not passed any argument, it returns a value of -1.
+     This number is an identity element for `logand' because its binary
+     representation consists entirely of ones.  If `logand' is passed
+     just one argument, it returns that argument.
+
+                             ;                28-bit binary values
+          
+          (logand 14 13)     ; 14  =  0000  0000 0000  0000 0000  0000 1110
+                             ; 13  =  0000  0000 0000  0000 0000  0000 1101
+               => 12         ; 12  =  0000  0000 0000  0000 0000  0000 1100
+          
+          (logand 14 13 4)   ; 14  =  0000  0000 0000  0000 0000  0000 1110
+                             ; 13  =  0000  0000 0000  0000 0000  0000 1101
+                             ;  4  =  0000  0000 0000  0000 0000  0000 0100
+               => 4          ;  4  =  0000  0000 0000  0000 0000  0000 0100
+          
+          (logand)
+               => -1         ; -1  =  1111  1111 1111  1111 1111  1111 1111
+
+ - Function: logior &rest ints-or-markers
+     This function returns the "inclusive or" of its arguments: the Nth
+     bit is set in the result if, and only if, the Nth bit is set in at
+     least one of the arguments.  If there are no arguments, the result
+     is zero, which is an identity element for this operation.  If
+     `logior' is passed just one argument, it returns that argument.
+
+                             ;               28-bit binary values
+          
+          (logior 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
+                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
+               => 13         ; 13  =  0000  0000 0000  0000 0000  0000 1101
+          
+          (logior 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
+                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
+                             ;  7  =  0000  0000 0000  0000 0000  0000 0111
+               => 15         ; 15  =  0000  0000 0000  0000 0000  0000 1111
+
+ - Function: logxor &rest ints-or-markers
+     This function returns the "exclusive or" of its arguments: the Nth
+     bit is set in the result if, and only if, the Nth bit is set in an
+     odd number of the arguments.  If there are no arguments, the
+     result is 0, which is an identity element for this operation.  If
+     `logxor' is passed just one argument, it returns that argument.
+
+                             ;               28-bit binary values
+          
+          (logxor 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
+                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
+               => 9          ;  9  =  0000  0000 0000  0000 0000  0000 1001
+          
+          (logxor 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
+                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
+                             ;  7  =  0000  0000 0000  0000 0000  0000 0111
+               => 14         ; 14  =  0000  0000 0000  0000 0000  0000 1110
+
+ - Function: lognot integer
+     This function returns the logical complement of its argument: the
+     Nth bit is one in the result if, and only if, the Nth bit is zero
+     in INTEGER, and vice-versa.
+
+          (lognot 5)
+               => -6
+          ;;  5  =  0000  0000 0000  0000 0000  0000 0101
+          ;; becomes
+          ;; -6  =  1111  1111 1111  1111 1111  1111 1010
+
+\1f
+File: lispref.info,  Node: Math Functions,  Next: Random Numbers,  Prev: Bitwise Operations,  Up: Numbers
+
+Standard Mathematical Functions
+===============================
+
+These mathematical functions are available if floating point is
+supported (which is the normal state of affairs).  They allow integers
+as well as floating point numbers as arguments.
+
+ - Function: sin number
+ - Function: cos number
+ - Function: tan number
+     These are the ordinary trigonometric functions, with argument
+     measured in radians.
+
+ - Function: asin number
+     The value of `(asin NUMBER)' is a number between -pi/2 and pi/2
+     (inclusive) whose sine is NUMBER; if, however, NUMBER is out of
+     range (outside [-1, 1]), then the result is a NaN.
+
+ - Function: acos number
+     The value of `(acos NUMBER)' is a number between 0 and pi
+     (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of
+     range (outside [-1, 1]), then the result is a NaN.
+
+ - Function: atan number &optional number2
+     The value of `(atan NUMBER)' is a number between -pi/2 and pi/2
+     (exclusive) whose tangent is NUMBER.
+
+     If optional argument NUMBER2 is supplied, the function returns
+     `atan2(NUMBER,NUMBER2)'.
+
+ - Function: sinh number
+ - Function: cosh number
+ - Function: tanh number
+     These are the ordinary hyperbolic trigonometric functions.
+
+ - Function: asinh number
+ - Function: acosh number
+ - Function: atanh number
+     These are the inverse hyperbolic trigonometric functions.
+
+ - Function: exp number
+     This is the exponential function; it returns e to the power
+     NUMBER.  e is a fundamental mathematical constant also called the
+     base of natural logarithms.
+
+ - Function: log number &optional base
+     This function returns the logarithm of NUMBER, with base BASE.  If
+     you don't specify BASE, the base `e' is used.  If NUMBER is
+     negative, the result is a NaN.
+
+ - Function: log10 number
+     This function returns the logarithm of NUMBER, with base 10.  If
+     NUMBER is negative, the result is a NaN.  `(log10 X)' == `(log X
+     10)', at least approximately.
+
+ - Function: expt x y
+     This function returns X raised to power Y.  If both arguments are
+     integers and Y is positive, the result is an integer; in this
+     case, it is truncated to fit the range of possible integer values.
+
+ - Function: sqrt number
+     This returns the square root of NUMBER.  If NUMBER is negative,
+     the value is a NaN.
+
+ - Function: cube-root number
+     This returns the cube root of NUMBER.
+
+\1f
+File: lispref.info,  Node: Random Numbers,  Prev: Math Functions,  Up: Numbers
+
+Random Numbers
+==============
+
+A deterministic computer program cannot generate true random numbers.
+For most purposes, "pseudo-random numbers" suffice.  A series of
+pseudo-random numbers is generated in a deterministic fashion.  The
+numbers are not truly random, but they have certain properties that
+mimic a random series.  For example, all possible values occur equally
+often in a pseudo-random series.
+
+   In XEmacs, pseudo-random numbers are generated from a "seed" number.
+Starting from any given seed, the `random' function always generates
+the same sequence of numbers.  XEmacs always starts with the same seed
+value, so the sequence of values of `random' is actually the same in
+each XEmacs run!  For example, in one operating system, the first call
+to `(random)' after you start XEmacs always returns -1457731, and the
+second one always returns -7692030.  This repeatability is helpful for
+debugging.
+
+   If you want truly unpredictable random numbers, execute `(random
+t)'.  This chooses a new seed based on the current time of day and on
+XEmacs's process ID number.
+
+ - Function: random &optional limit
+     This function returns a pseudo-random integer.  Repeated calls
+     return a series of pseudo-random integers.
+
+     If LIMIT is a positive integer, the value is chosen to be
+     nonnegative and less than LIMIT.
+
+     If LIMIT is `t', it means to choose a new seed based on the
+     current time of day and on XEmacs's process ID number.
+
+     On some machines, any integer representable in Lisp may be the
+     result of `random'.  On other machines, the result can never be
+     larger than a certain maximum or less than a certain (negative)
+     minimum.
+
+\1f
+File: lispref.info,  Node: Strings and Characters,  Next: Lists,  Prev: Numbers,  Up: Top
+
+Strings and Characters
+**********************
+
+A string in XEmacs Lisp is an array that contains an ordered sequence
+of characters.  Strings are used as names of symbols, buffers, and
+files, to send messages to users, to hold text being copied between
+buffers, and for many other purposes.  Because strings are so important,
+XEmacs Lisp has many functions expressly for manipulating them.  XEmacs
+Lisp programs use strings more often than individual characters.
+
+* Menu:
+
+* 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.
+* Case Tables::                      Customizing case conversion.
+* Char Tables::               Mapping from characters to Lisp objects.
+
+\1f
+File: lispref.info,  Node: String Basics,  Next: Predicates for Strings,  Up: Strings and Characters
+
+String and Character Basics
+===========================
+
+Strings in XEmacs Lisp are arrays that contain an ordered sequence of
+characters.  Characters are their own primitive object type in XEmacs
+20.  However, in XEmacs 19, characters are represented in XEmacs Lisp as
+integers; whether an integer was intended as a character or not is
+determined only by how it is used.  *Note Character Type::.
+
+   The length of a string (like any array) is fixed and independent of
+the string contents, and cannot be altered.  Strings in Lisp are _not_
+terminated by a distinguished character code.  (By contrast, strings in
+C are terminated by a character with ASCII code 0.)  This means that
+any character, including the null character (ASCII code 0), is a valid
+element of a string.
+
+   Since strings are considered arrays, you can operate on them with the
+general array functions.  (*Note Sequences Arrays Vectors::.)  For
+example, you can access or change individual characters in a string
+using the functions `aref' and `aset' (*note Array Functions::).
+
+   Strings use an efficient representation for storing the characters
+in them, and thus take up much less memory than a vector of the same
+length.
+
+   Sometimes you will see strings used to hold key sequences.  This
+exists for backward compatibility with Emacs 18, but should _not_ be
+used in new code, since many key chords can't be represented at all and
+others (in particular meta key chords) are confused with accented
+characters.
+
+   Strings are useful for holding regular expressions.  You can also
+match regular expressions against strings (*note Regexp Search::).  The
+functions `match-string' (*note Simple Match Data::) and
+`replace-match' (*note Replacing Match::) are useful for decomposing
+and modifying strings based on regular expression matching.
+
+   Like a buffer, a string can contain extents in it.  These extents are
+created when a function such as `buffer-substring' is called on a
+region with duplicable extents in it.  When the string is inserted into
+a buffer, the extents are inserted along with it.  *Note Duplicable
+Extents::.
+
+   *Note Text::, for information about functions that display strings or
+copy them into buffers.  *Note Character Type::, and *Note String
+Type::, for information about the syntax of characters and strings.
+
+\1f
+File: lispref.info,  Node: Predicates for Strings,  Next: Creating Strings,  Prev: String Basics,  Up: Strings and Characters
+
+The Predicates for Strings
+==========================
+
+For more information about general sequence and array predicates, see
+*Note Sequences Arrays Vectors::, and *Note Arrays::.
+
+ - Function: stringp object
+     This function returns `t' if OBJECT is a string, `nil' otherwise.
+
+ - Function: char-or-string-p object
+     This function returns `t' if OBJECT is a string or a character,
+     `nil' otherwise.
+
+     In XEmacs addition, this function also returns `t' if OBJECT is an
+     integer that can be represented as a character.  This is because
+     of compatibility with previous XEmacs and should not be depended
+     on.
+
+\1f
+File: lispref.info,  Node: Creating Strings,  Next: Predicates for Characters,  Prev: Predicates for Strings,  Up: Strings and Characters
+
+Creating Strings
+================
+
+The following functions create strings, either from scratch, or by
+putting strings together, or by taking them apart.
+
+ - Function: string &rest characters
+     This function returns a new string made up of CHARACTERS.
+
+          (string ?X ?E ?m ?a ?c ?s)
+               => "XEmacs"
+          (string)
+               => ""
+
+     Analogous functions operating on other data types include `list',
+     `cons' (*note Building Lists::), `vector' (*note Vectors::) and
+     `bit-vector' (*note Bit Vectors::).  This function has not been
+     available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
+
+ - Function: make-string length character
+     This function returns a new string consisting entirely of LENGTH
+     successive copies of CHARACTER.  LENGTH must be a non-negative
+     integer.
+
+          (make-string 5 ?x)
+               => "xxxxx"
+          (make-string 0 ?x)
+               => ""
+
+     Other functions to compare with this one include `char-to-string'
+     (*note String Conversion::), `make-vector' (*note Vectors::), and
+     `make-list' (*note Building Lists::).
+
+ - Function: substring string start &optional end
+     This function returns a new string which consists of those
+     characters from STRING in the range from (and including) the
+     character at the index START up to (but excluding) the character
+     at the index END.  The first character is at index zero.
+
+          (substring "abcdefg" 0 3)
+               => "abc"
+
+     Here the index for `a' is 0, the index for `b' is 1, and the index
+     for `c' is 2.  Thus, three letters, `abc', are copied from the
+     string `"abcdefg"'.  The index 3 marks the character position up
+     to which the substring is copied.  The character whose index is 3
+     is actually the fourth character in the string.
+
+     A negative number counts from the end of the string, so that -1
+     signifies the index of the last character of the string.  For
+     example:
+
+          (substring "abcdefg" -3 -1)
+               => "ef"
+
+     In this example, the index for `e' is -3, the index for `f' is -2,
+     and the index for `g' is -1.  Therefore, `e' and `f' are included,
+     and `g' is excluded.
+
+     When `nil' is used as an index, it stands for the length of the
+     string.  Thus,
+
+          (substring "abcdefg" -3 nil)
+               => "efg"
+
+     Omitting the argument END is equivalent to specifying `nil'.  It
+     follows that `(substring STRING 0)' returns a copy of all of
+     STRING.
+
+          (substring "abcdefg" 0)
+               => "abcdefg"
+
+     But we recommend `copy-sequence' for this purpose (*note Sequence
+     Functions::).
+
+     If the characters copied from STRING have duplicable extents or
+     text properties, those are copied into the new string also.  *Note
+     Duplicable Extents::.
+
+     A `wrong-type-argument' error is signaled if either START or END
+     is not an integer or `nil'.  An `args-out-of-range' error is
+     signaled if START indicates a character following END, or if
+     either integer is out of range for STRING.
+
+     Contrast this function with `buffer-substring' (*note Buffer
+     Contents::), which returns a string containing a portion of the
+     text in the current buffer.  The beginning of a string is at index
+     0, but the beginning of a buffer is at index 1.
+
+ - Function: concat &rest sequences
+     This function returns a new string consisting of the characters in
+     the arguments passed to it (along with their text properties, if
+     any).  The arguments may be strings, lists of numbers, or vectors
+     of numbers; they are not themselves changed.  If `concat' receives
+     no arguments, it returns an empty string.
+
+          (concat "abc" "-def")
+               => "abc-def"
+          (concat "abc" (list 120 (+ 256 121)) [122])
+               => "abcxyz"
+          ;; `nil' is an empty sequence.
+          (concat "abc" nil "-def")
+               => "abc-def"
+          (concat "The " "quick brown " "fox.")
+               => "The quick brown fox."
+          (concat)
+               => ""
+
+     The second example above shows how characters stored in strings are
+     taken modulo 256.  In other words, each character in the string is
+     stored in one byte.
+
+     The `concat' function always constructs a new string that is not
+     `eq' to any existing string.
+
+     When an argument is an integer (not a sequence of integers), it is
+     converted to a string of digits making up the decimal printed
+     representation of the integer.  *Don't use this feature; we plan
+     to eliminate it.  If you already use this feature, change your
+     programs now!*  The proper way to convert an integer to a decimal
+     number in this way is with `format' (*note Formatting Strings::) or
+     `number-to-string' (*note String Conversion::).
+
+          (concat 137)
+               => "137"
+          (concat 54 321)
+               => "54321"
+
+     For information about other concatenation functions, see the
+     description of `mapconcat' in *Note Mapping Functions::, `vconcat'
+     in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
+     in *Note Building Lists::.
+
+\1f
+File: lispref.info,  Node: Predicates for Characters,  Next: Character Codes,  Prev: Creating Strings,  Up: Strings and Characters
+
+The Predicates for Characters
+=============================
+
+ - Function: characterp object
+     This function returns `t' if OBJECT is a character.
+
+     Some functions that work on integers (e.g. the comparison functions
+     <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
+     accept characters and implicitly convert them into integers.  In
+     general, functions that work on characters also accept char-ints
+     and implicitly convert them into characters.  WARNING: Neither of
+     these behaviors is very desirable, and they are maintained for
+     backward compatibility with old E-Lisp programs that confounded
+     characters and integers willy-nilly.  These behaviors may change
+     in the future; therefore, do not rely on them.  Instead, convert
+     the characters explicitly using `char-int'.
+
+ - Function: integer-or-char-p object
+     This function returns `t' if OBJECT is an integer or character.
+
+\1f
+File: lispref.info,  Node: Character Codes,  Next: Text Comparison,  Prev: Predicates for Characters,  Up: Strings and Characters
+
+Character Codes
+===============
+
+ - Function: char-int character
+     This function converts a character into an equivalent integer.
+     The resulting integer will always be non-negative.  The integers in
+     the range 0 - 255 map to characters as follows:
+
+    0 - 31
+          Control set 0
+
+    32 - 127
+          ASCII
+
+    128 - 159
+          Control set 1
+
+    160 - 255
+          Right half of ISO-8859-1
+
+     If support for MULE does not exist, these are the only valid
+     character values.  When MULE support exists, the values assigned to
+     other characters may vary depending on the particular version of
+     XEmacs, the order in which character sets were loaded, etc., and
+     you should not depend on them.
+
+ - Function: int-char integer
+     This function converts an integer into the equivalent character.
+     Not all integers correspond to valid characters; use `char-int-p'
+     to determine whether this is the case.  If the integer cannot be
+     converted, `nil' is returned.
+
+ - Function: char-int-p object
+     This function returns `t' if OBJECT is an integer that can be
+     converted into a character.
+
+ - Function: char-or-char-int-p object
+     This function returns `t' if OBJECT is a character or an integer
+     that can be converted into one.
+
+\1f
+File: lispref.info,  Node: Text Comparison,  Next: String Conversion,  Prev: Character Codes,  Up: Strings and Characters
+
+Comparison of Characters and Strings
+====================================
+
+ - Function: char-equal character1 character2 &optional buffer
+     This function returns `t' if the arguments represent the same
+     character, `nil' otherwise.  This function ignores differences in
+     case if the value of `case-fold-search' is non-`nil' in BUFFER,
+     which defaults to the current buffer.
+
+          (char-equal ?x ?x)
+               => t
+          (let ((case-fold-search t))
+            (char-equal ?x ?X))
+               => t
+          (let ((case-fold-search nil))
+            (char-equal ?x ?X))
+               => nil
+
+ - Function: char= character1 character2
+     This function returns `t' if the arguments represent the same
+     character, `nil' otherwise.  Case is significant.
+
+          (char= ?x ?x)
+               => t
+          (char= ?x ?X)
+               => nil
+          (let ((case-fold-search t))
+            (char-equal ?x ?X))
+               => nil
+          (let ((case-fold-search nil))
+            (char-equal ?x ?X))
+               => nil
+
+ - Function: string= string1 string2
+     This function returns `t' if the characters of the two strings
+     match exactly; case is significant.
+
+          (string= "abc" "abc")
+               => t
+          (string= "abc" "ABC")
+               => nil
+          (string= "ab" "ABC")
+               => nil
+
+
+ - Function: string-equal string1 string2
+     `string-equal' is another name for `string='.
+
+ - Function: string< string1 string2
+     This function compares two strings a character at a time.  First it
+     scans both the strings at once to find the first pair of
+     corresponding characters that do not match.  If the lesser
+     character of those two is the character from STRING1, then STRING1
+     is less, and this function returns `t'.  If the lesser character
+     is the one from STRING2, then STRING1 is greater, and this
+     function returns `nil'.  If the two strings match entirely, the
+     value is `nil'.
+
+     Pairs of characters are compared by their ASCII codes.  Keep in
+     mind that lower case letters have higher numeric values in the
+     ASCII character set than their upper case counterparts; numbers and
+     many punctuation characters have a lower numeric value than upper
+     case letters.
+
+          (string< "abc" "abd")
+               => t
+          (string< "abd" "abc")
+               => nil
+          (string< "123" "abc")
+               => t
+
+     When the strings have different lengths, and they match up to the
+     length of STRING1, then the result is `t'.  If they match up to
+     the length of STRING2, the result is `nil'.  A string of no
+     characters is less than any other string.
+
+          (string< "" "abc")
+               => t
+          (string< "ab" "abc")
+               => t
+          (string< "abc" "")
+               => nil
+          (string< "abc" "ab")
+               => nil
+          (string< "" "")
+               => nil
+
+ - Function: string-lessp string1 string2
+     `string-lessp' is another name for `string<'.
+
+   See also `compare-buffer-substrings' in *Note Comparing Text::, for
+a way to compare text in buffers.  The function `string-match', which
+matches a regular expression against a string, can be used for a kind
+of string comparison; see *Note Regexp Search::.
+
+\1f
+File: lispref.info,  Node: String Conversion,  Next: Modifying Strings,  Prev: Text Comparison,  Up: Strings and Characters
+
+Conversion of Characters and Strings
+====================================
+
+This section describes functions for conversions between characters,
+strings and integers.  `format' and `prin1-to-string' (*note Output
+Functions::) can also convert Lisp objects into strings.
+`read-from-string' (*note Input Functions::) can "convert" a string
+representation of a Lisp object into an object.
+
+   *Note Documentation::, for functions that produce textual
+descriptions of text characters and general input events
+(`single-key-description' and `text-char-description').  These
+functions are used primarily for making help messages.
+
+ - Function: char-to-string character
+     This function returns a new string with a length of one character.
+     The value of CHARACTER, modulo 256, is used to initialize the
+     element of the string.
+
+     This function is similar to `make-string' with an integer argument
+     of 1.  (*Note Creating Strings::.)  This conversion can also be
+     done with `format' using the `%c' format specification.  (*Note
+     Formatting Strings::.)
+
+          (char-to-string ?x)
+               => "x"
+          (char-to-string (+ 256 ?x))
+               => "x"
+          (make-string 1 ?x)
+               => "x"
+
+ - Function: string-to-char string
+     This function returns the first character in STRING.  If the
+     string is empty, the function returns 0. (Under XEmacs 19, the
+     value is also 0 when the first character of STRING is the null
+     character, ASCII code 0.)
+
+          (string-to-char "ABC")
+               => ?A   ;; Under XEmacs 20.
+               => 65   ;; Under XEmacs 19.
+          (string-to-char "xyz")
+               => ?x   ;; Under XEmacs 20.
+               => 120  ;; Under XEmacs 19.
+          (string-to-char "")
+               => 0
+          (string-to-char "\000")
+               => ?\^ ;; Under XEmacs 20.
+               => 0    ;; Under XEmacs 20.
+
+     This function may be eliminated in the future if it does not seem
+     useful enough to retain.
+
+ - Function: number-to-string number
+     This function returns a string consisting of the printed
+     representation of NUMBER, which may be an integer or a floating
+     point number.  The value starts with a sign if the argument is
+     negative.
+
+          (number-to-string 256)
+               => "256"
+          (number-to-string -23)
+               => "-23"
+          (number-to-string -23.5)
+               => "-23.5"
+
+     `int-to-string' is a semi-obsolete alias for this function.
+
+     See also the function `format' in *Note Formatting Strings::.
+
+ - Function: string-to-number string &optional base
+     This function returns the numeric value represented by STRING,
+     read in BASE.  It skips spaces and tabs at the beginning of
+     STRING, then reads as much of STRING as it can interpret as a
+     number.  (On some systems it ignores other whitespace at the
+     beginning, not just spaces and tabs.)  If the first character
+     after the ignored whitespace is not a digit or a minus sign, this
+     function returns 0.
+
+     If BASE is not specified, it defaults to ten.  With BASE other
+     than ten, only integers can be read.
+
+          (string-to-number "256")
+               => 256
+          (string-to-number "25 is a perfect square.")
+               => 25
+          (string-to-number "X256")
+               => 0
+          (string-to-number "-4.5")
+               => -4.5
+          (string-to-number "ffff" 16)
+               => 65535
+
+     `string-to-int' is an obsolete alias for this function.
+
+\1f
+File: lispref.info,  Node: Modifying Strings,  Next: String Properties,  Prev: String Conversion,  Up: Strings and Characters
+
+Modifying Strings
+=================
+
+You can modify a string using the general array-modifying primitives.
+*Note Arrays::.  The function `aset' modifies a single character; the
+function `fillarray' sets all characters in the string to a specified
+character.
+
+   Each string has a tick counter that starts out at zero (when the
+string is created) and is incremented each time a change is made to that
+string.
+
+ - Function: string-modified-tick string
+     This function returns the tick counter for `string'.
+
+\1f
+File: lispref.info,  Node: String Properties,  Next: Formatting Strings,  Prev: Modifying Strings,  Up: Strings and Characters
+
+String Properties
+=================
+
+Just as with symbols, extents, faces, and glyphs, you can attach
+additional information to strings in the form of "string properties".
+These differ from text properties, which are logically attached to
+particular characters in the string.
+
+   To attach a property to a string, use `put'.  To retrieve a property
+from a string, use `get'.  You can also use `remprop' to remove a
+property from a string and `object-plist' to retrieve a list of all the
+properties in a string.
+
+\1f
+File: lispref.info,  Node: Formatting Strings,  Next: Character Case,  Prev: String Properties,  Up: Strings and Characters
+
+Formatting Strings
+==================
+
+"Formatting" means constructing a string by substitution of computed
+values at various places in a constant string.  This string controls
+how the other values are printed as well as where they appear; it is
+called a "format string".
+
+   Formatting is often useful for computing messages to be displayed.
+In fact, the functions `message' and `error' provide the same
+formatting feature described here; they differ from `format' only in
+how they use the result of formatting.
+
+ - Function: format string &rest objects
+     This function returns a new string that is made by copying STRING
+     and then replacing any format specification in the copy with
+     encodings of the corresponding OBJECTS.  The arguments OBJECTS are
+     the computed values to be formatted.
+
+   A format specification is a sequence of characters beginning with a
+`%'.  Thus, if there is a `%d' in STRING, the `format' function
+replaces it with the printed representation of one of the values to be
+formatted (one of the arguments OBJECTS).  For example:
+
+     (format "The value of fill-column is %d." fill-column)
+          => "The value of fill-column is 72."
+
+   If STRING contains more than one format specification, the format
+specifications correspond with successive values from OBJECTS.  Thus,
+the first format specification in STRING uses the first such value, the
+second format specification uses the second such value, and so on.  Any
+extra format specifications (those for which there are no corresponding
+values) cause unpredictable behavior.  Any extra values to be formatted
+are ignored.
+
+   Certain format specifications require values of particular types.
+However, no error is signaled if the value actually supplied fails to
+have the expected type.  Instead, the output is likely to be
+meaningless.
+
+   Here is a table of valid format specifications:
+
+`%s'
+     Replace the specification with the printed representation of the
+     object, made without quoting.  Thus, strings are represented by
+     their contents alone, with no `"' characters, and symbols appear
+     without `\' characters.  This is equivalent to printing the object
+     with `princ'.
+
+     If there is no corresponding object, the empty string is used.
+
+`%S'
+     Replace the specification with the printed representation of the
+     object, made with quoting.  Thus, strings are enclosed in `"'
+     characters, and `\' characters appear where necessary before
+     special characters.  This is equivalent to printing the object
+     with `prin1'.
+
+     If there is no corresponding object, the empty string is used.
+
+`%o'
+     Replace the specification with the base-eight representation of an
+     integer.
+
+`%d'
+`%i'
+     Replace the specification with the base-ten representation of an
+     integer.
+
+`%x'
+     Replace the specification with the base-sixteen representation of
+     an integer, using lowercase letters.
+
+`%X'
+     Replace the specification with the base-sixteen representation of
+     an integer, using uppercase letters.
+
+`%c'
+     Replace the specification with the character which is the value
+     given.
+
+`%e'
+     Replace the specification with the exponential notation for a
+     floating point number (e.g. `7.85200e+03').
+
+`%f'
+     Replace the specification with the decimal-point notation for a
+     floating point number.
+
+`%g'
+     Replace the specification with notation for a floating point
+     number, using a "pretty format".  Either exponential notation or
+     decimal-point notation will be used (usually whichever is
+     shorter), and trailing zeroes are removed from the fractional part.
+
+`%%'
+     A single `%' is placed in the string.  This format specification is
+     unusual in that it does not use a value.  For example, `(format "%%
+     %d" 30)' returns `"% 30"'.
+
+   Any other format character results in an `Invalid format operation'
+error.
+
+   Here are several examples:
+
+     (format "The name of this buffer is %s." (buffer-name))
+          => "The name of this buffer is strings.texi."
+     
+     (format "The buffer object prints as %s." (current-buffer))
+          => "The buffer object prints as #<buffer strings.texi>."
+     
+     (format "The octal value of %d is %o,
+              and the hex value is %x." 18 18 18)
+          => "The octal value of 18 is 22,
+              and the hex value is 12."
+
+   There are many additional flags and specifications that can occur
+between the `%' and the format character, in the following order:
+
+  1. An optional repositioning specification, which is a positive
+     integer followed by a `$'.
+
+  2. Zero or more of the optional flag characters `-', `+', ` ', `0',
+     and `#'.
+
+  3. An asterisk (`*', meaning that the field width is now assumed to
+     have been specified as an argument.
+
+  4. An optional minimum field width.
+
+  5. An optional precision, preceded by a `.' character.
+
+   A "repositioning" specification changes which argument to `format'
+is used by the current and all following format specifications.
+Normally the first specification uses the first argument, the second
+specification uses the second argument, etc.  Using a repositioning
+specification, you can change this.  By placing a number N followed by
+a `$' between the `%' and the format character, you cause the
+specification to use the Nth argument.  The next specification will use
+the N+1'th argument, etc.
+
+   For example:
+
+     (format "Can't find file `%s' in directory `%s'."
+             "ignatius.c" "loyola/")
+          => "Can't find file `ignatius.c' in directory `loyola/'."
+     
+     (format "In directory `%2$s', the file `%1$s' was not found."
+             "ignatius.c" "loyola/")
+          => "In directory `loyola/', the file `ignatius.c' was not found."
+     
+     (format
+         "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
+         37 12)
+     => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
+
+   As you can see, this lets you reprocess arguments more than once or
+reword a format specification (thereby moving the arguments around)
+without having to actually reorder the arguments.  This is especially
+useful in translating messages from one language to another: Different
+languages use different word orders, and this sometimes entails changing
+the order of the arguments.  By using repositioning specifications,
+this can be accomplished without having to embed knowledge of particular
+languages into the location in the program's code where the message is
+displayed.
+
+   All the specification characters allow an optional numeric prefix
+between the `%' and the character, and following any repositioning
+specification or flag.  The optional numeric prefix defines the minimum
+width for the object.  If the printed representation of the object
+contains fewer characters than this, then it is padded.  The padding is
+normally on the left, but will be on the right if the `-' flag
+character is given.  The padding character is normally a space, but if
+the `0' flag character is given, zeros are used for padding.
+
+     (format "%06d is padded on the left with zeros" 123)
+          => "000123 is padded on the left with zeros"
+     
+     (format "%-6d is padded on the right" 123)
+          => "123    is padded on the right"
+
+   `format' never truncates an object's printed representation, no
+matter what width you specify.  Thus, you can use a numeric prefix to
+specify a minimum spacing between columns with no risk of losing
+information.
+
+   In the following three examples, `%7s' specifies a minimum width of
+7.  In the first case, the string inserted in place of `%7s' has only 3
+letters, so 4 blank spaces are inserted for padding.  In the second
+case, the string `"specification"' is 13 letters wide but is not
+truncated.  In the third case, the padding is on the right.
+
+     (format "The word `%7s' actually has %d letters in it."
+             "foo" (length "foo"))
+          => "The word `    foo' actually has 3 letters in it."
+     
+     (format "The word `%7s' actually has %d letters in it."
+             "specification" (length "specification"))
+          => "The word `specification' actually has 13 letters in it."
+     
+     (format "The word `%-7s' actually has %d letters in it."
+             "foo" (length "foo"))
+          => "The word `foo    ' actually has 3 letters in it."
+
+   After any minimum field width, a precision may be specified by
+preceding it with a `.' character.  The precision specifies the minimum
+number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
+conversions (the number is padded on the left with zeroes as
+necessary); the number of digits printed after the decimal point for
+`%f', `%e', and `%E' conversions; the number of significant digits
+printed in `%g' and `%G' conversions; and the maximum number of
+non-padding characters printed in `%s' and `%S' conversions.  The
+default precision for floating-point conversions is six.
+
+   The other flag characters have the following meanings:
+
+   * The ` ' flag means prefix non-negative numbers with a space.
+
+   * The `+' flag means prefix non-negative numbers with a plus sign.
+
+   * The `#' flag means print numbers in an alternate, more verbose
+     format: octal numbers begin with zero; hex numbers begin with a
+     `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
+     conversions even if no numbers are printed after it; and trailing
+     zeroes are not omitted in `%g' and `%G' conversions.
+
+\1f
+File: lispref.info,  Node: Character Case,  Next: Case Tables,  Prev: Formatting Strings,  Up: Strings and Characters
+
+Character Case
+==============
+
+The character case functions change the case of single characters or of
+the contents of strings.  The functions convert only alphabetic
+characters (the letters `A' through `Z' and `a' through `z'); other
+characters are not altered.  The functions do not modify the strings
+that are passed to them as arguments.
+
+   The examples below use the characters `X' and `x' which have ASCII
+codes 88 and 120 respectively.
+
+ - Function: downcase string-or-char &optional buffer
+     This function converts a character or a string to lower case.
+
+     When the argument to `downcase' is a string, the function creates
+     and returns a new string in which each letter in the argument that
+     is upper case is converted to lower case.  When the argument to
+     `downcase' is a character, `downcase' returns the corresponding
+     lower case character. (This value is actually an integer under
+     XEmacs 19.) If the original character is lower case, or is not a
+     letter, then the value equals the original character.
+
+     Optional second arg BUFFER specifies which buffer's case tables to
+     use, and defaults to the current buffer.
+
+          (downcase "The cat in the hat")
+               => "the cat in the hat"
+          
+          (downcase ?X)
+               => ?x   ;; Under XEmacs 20.
+               => 120  ;; Under XEmacs 19.
+
+ - Function: upcase string-or-char &optional buffer
+     This function converts a character or a string to upper case.
+
+     When the argument to `upcase' is a string, the function creates
+     and returns a new string in which each letter in the argument that
+     is lower case is converted to upper case.
+
+     When the argument to `upcase' is a character, `upcase' returns the
+     corresponding upper case character. (This value is actually an
+     integer under XEmacs 19.)  If the original character is upper
+     case, or is not a letter, then the value equals the original
+     character.
+
+     Optional second arg BUFFER specifies which buffer's case tables to
+     use, and defaults to the current buffer.
+
+          (upcase "The cat in the hat")
+               => "THE CAT IN THE HAT"
+          
+          (upcase ?x)
+               => ?X   ;; Under XEmacs 20.
+               => 88   ;; Under XEmacs 19.
+
+ - Function: capitalize string-or-char &optional buffer
+     This function capitalizes strings or characters.  If
+     STRING-OR-CHAR is a string, the function creates and returns a new
+     string, whose contents are a copy of STRING-OR-CHAR in which each
+     word has been capitalized.  This means that the first character of
+     each word is converted to upper case, and the rest are converted
+     to lower case.
+
+     The definition of a word is any sequence of consecutive characters
+     that are assigned to the word constituent syntax class in the
+     current syntax table (*note Syntax Class Table::).
+
+     When the argument to `capitalize' is a character, `capitalize' has
+     the same result as `upcase'.
+
+     Optional second arg BUFFER specifies which buffer's case tables to
+     use, and defaults to the current buffer.
+
+          (capitalize "The cat in the hat")
+               => "The Cat In The Hat"
+          
+          (capitalize "THE 77TH-HATTED CAT")
+               => "The 77th-Hatted Cat"
+          
+          (capitalize ?x)
+               => ?X   ;; Under XEmacs 20.
+               => 88   ;; Under XEmacs 19.
+
+\1f
+File: lispref.info,  Node: Case Tables,  Next: Char Tables,  Prev: Character Case,  Up: Strings and Characters
+
+The Case Table
+==============
+
+You can customize case conversion by installing a special "case table".
+A case table specifies the mapping between upper case and lower case
+letters.  It affects both the string and character case conversion
+functions (see the previous section) and those that apply to text in the
+buffer (*note Case Changes::).  You need a case table if you are using a
+language which has letters other than the standard ASCII letters.
+
+   A case table is a list of this form:
+
+     (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
+
+where each element is either `nil' or a string of length 256.  The
+element DOWNCASE says how to map each character to its lower-case
+equivalent.  The element UPCASE maps each character to its upper-case
+equivalent.  If lower and upper case characters are in one-to-one
+correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
+table from DOWNCASE.
+
+   For some languages, upper and lower case letters are not in
+one-to-one correspondence.  There may be two different lower case
+letters with the same upper case equivalent.  In these cases, you need
+to specify the maps for both directions.
+
+   The element CANONICALIZE maps each character to a canonical
+equivalent; any two characters that are related by case-conversion have
+the same canonical equivalent character.
+
+   The element EQUIVALENCES is a map that cyclicly permutes each
+equivalence class (of characters with the same canonical equivalent).
+(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
+likewise for each set of equivalent characters.)
+
+   When you construct a case table, you can provide `nil' for
+CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
+You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
+string from CANONICALIZE.  In a case table that is actually in use,
+those components are non-`nil'.  Do not try to specify EQUIVALENCES
+without also specifying CANONICALIZE.
+
+   Each buffer has a case table.  XEmacs also has a "standard case
+table" which is copied into each buffer when you create the buffer.
+Changing the standard case table doesn't affect any existing buffers.
+
+   Here are the functions for working with case tables:
+
+ - Function: case-table-p object
+     This predicate returns non-`nil' if OBJECT is a valid case table.
+
+ - Function: set-standard-case-table case-table
+     This function makes CASE-TABLE the standard case table, so that it
+     will apply to any buffers created subsequently.
+
+ - Function: standard-case-table
+     This returns the standard case table.
+
+ - Function: current-case-table &optional buffer
+     This function returns the case table of BUFFER, which defaults to
+     the current buffer.
+
+ - Function: set-case-table case-table
+     This sets the current buffer's case table to CASE-TABLE.
+
+   The following three functions are convenient subroutines for packages
+that define non-ASCII character sets.  They modify a string
+DOWNCASE-TABLE provided as an argument; this should be a string to be
+used as the DOWNCASE part of a case table.  They also modify the
+standard syntax table.  *Note Syntax Tables::.
+
+ - Function: set-case-syntax-pair uc lc downcase-table
+     This function specifies a pair of corresponding letters, one upper
+     case and one lower case.
+
+ - Function: set-case-syntax-delims l r downcase-table
+     This function makes characters L and R a matching pair of
+     case-invariant delimiters.
+
+ - Function: set-case-syntax char syntax downcase-table
+     This function makes CHAR case-invariant, with syntax SYNTAX.
+
+ - Command: describe-buffer-case-table
+     This command displays a description of the contents of the current
+     buffer's case table.
+
+   You can load the library `iso-syntax' to set up the standard syntax
+table and define a case table for the 8-bit ISO Latin 1 character set.
+
+\1f
+File: lispref.info,  Node: Char Tables,  Prev: Case Tables,  Up: Strings and Characters
+
+The Char Table
+==============
+
+A char table is a table that maps characters (or ranges of characters)
+to values.  Char tables are specialized for characters, only allowing
+particular sorts of ranges to be assigned values.  Although this loses
+in generality, it makes for extremely fast (constant-time) lookups, and
+thus is feasible for applications that do an extremely large number of
+lookups (e.g. scanning a buffer for a character in a particular syntax,
+where a lookup in the syntax table must occur once per character).
+
+   Note that char tables as a primitive type, and all of the functions
+in this section, exist only in XEmacs 20.  In XEmacs 19, char tables are
+generally implemented using a vector of 256 elements.
+
+   When MULE support exists, the types of ranges that can be assigned
+values are
+
+   * all characters
+
+   * an entire charset
+
+   * a single row in a two-octet charset
+
+   * a single character
+
+   When MULE support is not present, the types of ranges that can be
+assigned values are
+
+   * all characters
+
+   * a single character
+
+ - Function: char-table-p object
+     This function returns non-`nil' if OBJECT is a char table.
+
+* Menu:
+
+* Char Table Types::            Char tables have different uses.
+* Working With Char Tables::    Creating and working with char tables.
+
+\1f
+File: lispref.info,  Node: Char Table Types,  Next: Working With Char Tables,  Up: Char Tables
+
+Char Table Types
+----------------
+
+Each char table type is used for a different purpose and allows
+different sorts of values.  The different char table types are
+
+`category'
+     Used for category tables, which specify the regexp categories that
+     a character is in.  The valid values are `nil' or a bit vector of
+     95 elements.  Higher-level Lisp functions are provided for working
+     with category tables.  Currently categories and category tables
+     only exist when MULE support is present.
+
+`char'
+     A generalized char table, for mapping from one character to
+     another.  Used for case tables, syntax matching tables,
+     `keyboard-translate-table', etc.  The valid values are characters.
+
+`generic'
+     An even more generalized char table, for mapping from a character
+     to anything.
+
+`display'
+     Used for display tables, which specify how a particular character
+     is to appear when displayed.  #### Not yet implemented.
+
+`syntax'
+     Used for syntax tables, which specify the syntax of a particular
+     character.  Higher-level Lisp functions are provided for working
+     with syntax tables.  The valid values are integers.
+
+ - Function: char-table-type char-table
+     This function returns the type of char table CHAR-TABLE.
+
+ - Function: char-table-type-list
+     This function returns a list of the recognized char table types.
+
+ - Function: valid-char-table-type-p type
+     This function returns `t' if TYPE if a recognized char table type.
+
+\1f
+File: lispref.info,  Node: Working With Char Tables,  Prev: Char Table Types,  Up: Char Tables
+
+Working With Char Tables
+------------------------
+
+ - Function: make-char-table type
+     This function makes a new, empty char table of type TYPE.  TYPE
+     should be a symbol, one of `char', `category', `display',
+     `generic', or `syntax'.
+
+ - Function: put-char-table range value char-table
+     This function sets the value for chars in RANGE to be VALUE in
+     CHAR-TABLE.
+
+     RANGE specifies one or more characters to be affected and should be
+     one of the following:
+
+        * `t' (all characters are affected)
+
+        * A charset (only allowed when MULE support is present)
+
+        * A vector of two elements: a two-octet charset and a row number
+          (only allowed when MULE support is present)
+
+        * A single character
+
+     VALUE must be a value appropriate for the type of CHAR-TABLE.
+
+ - Function: get-char-table character char-table
+     This function finds the value for CHARACTER in CHAR-TABLE.
+
+ - Function: get-range-char-table range char-table &optional multi
+     This function finds the value for a range in CHAR-TABLE.  If there
+     is more than one value, MULTI is returned (defaults to `nil').
+
+ - Function: reset-char-table char-table
+     This function resets CHAR-TABLE to its default state.
+
+ - Function: map-char-table function char-table &optional range
+     This function maps FUNCTION over entries in CHAR-TABLE, calling it
+     with two args, each key and value in the table.
+
+     RANGE specifies a subrange to map over and is in the same format
+     as the RANGE argument to `put-range-table'.  If omitted or `t', it
+     defaults to the entire table.
+
+ - Function: valid-char-table-value-p value char-table-type
+     This function returns non-`nil' if VALUE is a valid value for
+     CHAR-TABLE-TYPE.
+
+ - Function: check-valid-char-table-value value char-table-type
+     This function signals an error if VALUE is not a valid value for
+     CHAR-TABLE-TYPE.
+
+\1f
+File: lispref.info,  Node: Lists,  Next: Sequences Arrays Vectors,  Prev: Strings and Characters,  Up: Top
+
+Lists
+*****
+
+A "list" represents a sequence of zero or more elements (which may be
+any Lisp objects).  The important difference between lists and vectors
+is that two or more lists can share part of their structure; in
+addition, you can insert or delete elements in a list without copying
+the whole list.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Cons Cells,  Next: Lists as Boxes,  Up: Lists
+
+Lists and Cons Cells
+====================
+
+Lists in Lisp are not a primitive data type; they are built up from
+"cons cells".  A cons cell is a data object that represents an ordered
+pair.  It records two Lisp objects, one labeled as the CAR, and the
+other labeled as the CDR.  These names are traditional; see *Note Cons
+Cell Type::.  CDR is pronounced "could-er."
+
+   A list is a series of cons cells chained together, one cons cell per
+element of the list.  By convention, the CARs of the cons cells are the
+elements of the list, and the CDRs are used to chain the list: the CDR
+of each cons cell is the following cons cell.  The CDR of the last cons
+cell is `nil'.  This asymmetry between the CAR and the CDR is entirely
+a matter of convention; at the level of cons cells, the CAR and CDR
+slots have the same characteristics.
+
+   Because most cons cells are used as part of lists, the phrase "list
+structure" has come to mean any structure made out of cons cells.
+
+   The symbol `nil' is considered a list as well as a symbol; it is the
+list with no elements.  For convenience, the symbol `nil' is considered
+to have `nil' as its CDR (and also as its CAR).
+
+   The CDR of any nonempty list L is a list containing all the elements
+of L except the first.
+
+\1f
+File: lispref.info,  Node: Lists as Boxes,  Next: List-related Predicates,  Prev: Cons Cells,  Up: Lists
+
+Lists as Linked Pairs of Boxes
+==============================
+
+A cons cell can be illustrated as a pair of boxes.  The first box
+represents the CAR and the second box represents the CDR.  Here is an
+illustration of the two-element list, `(tulip lily)', made from two
+cons cells:
+
+      ---------------         ---------------
+     | car   | cdr   |       | car   | cdr   |
+     | tulip |   o---------->| lily  |  nil  |
+     |       |       |       |       |       |
+      ---------------         ---------------
+
+   Each pair of boxes represents a cons cell.  Each box "refers to",
+"points to" or "contains" a Lisp object.  (These terms are synonymous.)
+The first box, which is the CAR of the first cons cell, contains the
+symbol `tulip'.  The arrow from the CDR of the first cons cell to the
+second cons cell indicates that the CDR of the first cons cell points
+to the second cons cell.
+
+   The same list can be illustrated in a different sort of box notation
+like this:
+
+         ___ ___      ___ ___
+        |___|___|--> |___|___|--> nil
+          |            |
+          |            |
+           --> tulip    --> lily
+
+   Here is a more complex illustration, showing the three-element list,
+`((pine needles) oak maple)', the first element of which is a
+two-element list:
+
+         ___ ___      ___ ___      ___ ___
+        |___|___|--> |___|___|--> |___|___|--> nil
+          |            |            |
+          |            |            |
+          |             --> oak      --> maple
+          |
+          |     ___ ___      ___ ___
+           --> |___|___|--> |___|___|--> nil
+                 |            |
+                 |            |
+                  --> pine     --> needles
+
+   The same list represented in the first box notation looks like this:
+
+      --------------       --------------       --------------
+     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
+     |   o   |   o------->| oak   |   o------->| maple |  nil |
+     |   |   |      |     |       |      |     |       |      |
+      -- | ---------       --------------       --------------
+         |
+         |
+         |        --------------       ----------------
+         |       | car   | cdr  |     | car     | cdr  |
+          ------>| pine  |   o------->| needles |  nil |
+                 |       |      |     |         |      |
+                  --------------       ----------------
+
+   *Note Cons Cell Type::, for the read and print syntax of cons cells
+and lists, and for more "box and arrow" illustrations of lists.
+
+\1f
+File: lispref.info,  Node: List-related Predicates,  Next: List Elements,  Prev: Lists as Boxes,  Up: Lists
+
+Predicates on Lists
+===================
+
+The following predicates test whether a Lisp object is an atom, is a
+cons cell or is a list, or whether it is the distinguished object
+`nil'.  (Many of these predicates can be defined in terms of the
+others, but they are used so often that it is worth having all of them.)
+
+ - Function: consp object
+     This function returns `t' if OBJECT is a cons cell, `nil'
+     otherwise.  `nil' is not a cons cell, although it _is_ a list.
+
+ - Function: atom object
+     This function returns `t' if OBJECT is an atom, `nil' otherwise.
+     All objects except cons cells are atoms.  The symbol `nil' is an
+     atom and is also a list; it is the only Lisp object that is both.
+
+          (atom OBJECT) == (not (consp OBJECT))
+
+ - Function: listp object
+     This function returns `t' if OBJECT is a cons cell or `nil'.
+     Otherwise, it returns `nil'.
+
+          (listp '(1))
+               => t
+          (listp '())
+               => t
+
+ - Function: nlistp object
+     This function is the opposite of `listp': it returns `t' if OBJECT
+     is not a list.  Otherwise, it returns `nil'.
+
+          (listp OBJECT) == (not (nlistp OBJECT))
+
+ - Function: null object
+     This function returns `t' if OBJECT is `nil', and returns `nil'
+     otherwise.  This function is identical to `not', but as a matter
+     of clarity we use `null' when OBJECT is considered a list and
+     `not' when it is considered a truth value (see `not' in *Note
+     Combining Conditions::).
+
+          (null '(1))
+               => nil
+          (null '())
+               => t
+

diff --git a/info/lispref.info-2 b/info/lispref.info-2
index 9d40b0e..6116d38 100644 (file)
--- a/info/lispref.info-2
+++ b/info/lispref.info-2
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1122 +50,7424 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: Copying,  Next: Introduction,  Prev: Top,  Up: Top
+File: lispref.info,  Node: List Elements,  Next: Building Lists,  Prev: List-related Predicates,  Up: Lists
+
+Accessing Elements of Lists
+===========================
+
+ - Function: car cons-cell
+     This function returns the value pointed to by the first pointer of
+     the cons cell CONS-CELL.  Expressed another way, this function
+     returns the CAR of CONS-CELL.
+
+     As a special case, if CONS-CELL is `nil', then `car' is defined to
+     return `nil'; therefore, any list is a valid argument for `car'.
+     An error is signaled if the argument is not a cons cell or `nil'.
+
+          (car '(a b c))
+               => a
+          (car '())
+               => nil
+
+ - Function: cdr cons-cell
+     This function returns the value pointed to by the second pointer of
+     the cons cell CONS-CELL.  Expressed another way, this function
+     returns the CDR of CONS-CELL.
+
+     As a special case, if CONS-CELL is `nil', then `cdr' is defined to
+     return `nil'; therefore, any list is a valid argument for `cdr'.
+     An error is signaled if the argument is not a cons cell or `nil'.
+
+          (cdr '(a b c))
+               => (b c)
+          (cdr '())
+               => nil
+
+ - Function: car-safe object
+     This function lets you take the CAR of a cons cell while avoiding
+     errors for other data types.  It returns the CAR of OBJECT if
+     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
+     `car', which signals an error if OBJECT is not a list.
+
+          (car-safe OBJECT)
+          ==
+          (let ((x OBJECT))
+            (if (consp x)
+                (car x)
+              nil))
+
+ - Function: cdr-safe object
+     This function lets you take the CDR of a cons cell while avoiding
+     errors for other data types.  It returns the CDR of OBJECT if
+     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
+     `cdr', which signals an error if OBJECT is not a list.
+
+          (cdr-safe OBJECT)
+          ==
+          (let ((x OBJECT))
+            (if (consp x)
+                (cdr x)
+              nil))
+
+ - Function: nth n list
+     This function returns the Nth element of LIST.  Elements are
+     numbered starting with zero, so the CAR of LIST is element number
+     zero.  If the length of LIST is N or less, the value is `nil'.
+
+     If N is negative, `nth' returns the first element of LIST.
+
+          (nth 2 '(1 2 3 4))
+               => 3
+          (nth 10 '(1 2 3 4))
+               => nil
+          (nth -3 '(1 2 3 4))
+               => 1
+          
+          (nth n x) == (car (nthcdr n x))
+
+ - Function: nthcdr n list
+     This function returns the Nth CDR of LIST.  In other words, it
+     removes the first N links of LIST and returns what follows.
+
+     If N is zero or negative, `nthcdr' returns all of LIST.  If the
+     length of LIST is N or less, `nthcdr' returns `nil'.
+
+          (nthcdr 1 '(1 2 3 4))
+               => (2 3 4)
+          (nthcdr 10 '(1 2 3 4))
+               => nil
+          (nthcdr -3 '(1 2 3 4))
+               => (1 2 3 4)
+
+Many convenience functions are provided to make it easier for you to
+access particular elements in a nested list.  All of these can be
+rewritten in terms of the functions just described.
+
+ - Function: caar cons-cell
+ - Function: cadr cons-cell
+ - Function: cdar cons-cell
+ - Function: cddr cons-cell
+ - Function: caaar cons-cell
+ - Function: caadr cons-cell
+ - Function: cadar cons-cell
+ - Function: caddr cons-cell
+ - Function: cdaar cons-cell
+ - Function: cdadr cons-cell
+ - Function: cddar cons-cell
+ - Function: cdddr cons-cell
+ - Function: caaaar cons-cell
+ - Function: caaadr cons-cell
+ - Function: caadar cons-cell
+ - Function: caaddr cons-cell
+ - Function: cadaar cons-cell
+ - Function: cadadr cons-cell
+ - Function: caddar cons-cell
+ - Function: cadddr cons-cell
+ - Function: cdaaar cons-cell
+ - Function: cdaadr cons-cell
+ - Function: cdadar cons-cell
+ - Function: cdaddr cons-cell
+ - Function: cddaar cons-cell
+ - Function: cddadr cons-cell
+ - Function: cdddar cons-cell
+ - Function: cddddr cons-cell
+     Each of these functions is equivalent to one or more applications
+     of `car' and/or `cdr'.  For example,
+
+          (cadr x)
+
+     is equivalent to
+
+          (car (cdr x))
+
+     and
+
+          (cdaddr x)
+
+     is equivalent to
+
+          (cdr (car (cdr (cdr x))))
+
+     That is to say, read the a's and d's from right to left and apply
+     a `car' or `cdr' for each a or d found, respectively.
+
+ - Function: first list
+     This is equivalent to `(nth 0 LIST)', i.e. the first element of
+     LIST. (Note that this is also equivalent to `car'.)
+
+ - Function: second list
+     This is equivalent to `(nth 1 LIST)', i.e. the second element of
+     LIST.
+
+ - Function: third list
+ - Function: fourth list
+ - Function: fifth list
+ - Function: sixth list
+ - Function: seventh list
+ - Function: eighth list
+ - Function: ninth list
+ - Function: tenth list
+     These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
+     respectively, i.e. the third through tenth elements of LIST.
+
+\1f
+File: lispref.info,  Node: Building Lists,  Next: Modifying Lists,  Prev: List Elements,  Up: Lists
+
+Building Cons Cells and Lists
+=============================
+
+Many functions build lists, as lists reside at the very heart of Lisp.
+`cons' is the fundamental list-building function; however, it is
+interesting to note that `list' is used more times in the source code
+for Emacs than `cons'.
+
+ - Function: cons object1 object2
+     This function is the fundamental function used to build new list
+     structure.  It creates a new cons cell, making OBJECT1 the CAR,
+     and OBJECT2 the CDR.  It then returns the new cons cell.  The
+     arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
+     often OBJECT2 is a list.
+
+          (cons 1 '(2))
+               => (1 2)
+          (cons 1 '())
+               => (1)
+          (cons 1 2)
+               => (1 . 2)
+
+     `cons' is often used to add a single element to the front of a
+     list.  This is called "consing the element onto the list".  For
+     example:
+
+          (setq list (cons newelt list))
+
+     Note that there is no conflict between the variable named `list'
+     used in this example and the function named `list' described below;
+     any symbol can serve both purposes.
+
+ - Function: list &rest objects
+     This function creates a list with OBJECTS as its elements.  The
+     resulting list is always `nil'-terminated.  If no OBJECTS are
+     given, the empty list is returned.
+
+          (list 1 2 3 4 5)
+               => (1 2 3 4 5)
+          (list 1 2 '(3 4 5) 'foo)
+               => (1 2 (3 4 5) foo)
+          (list)
+               => nil
+
+ - Function: make-list length object
+     This function creates a list of length LENGTH, in which all the
+     elements have the identical value OBJECT.  Compare `make-list'
+     with `make-string' (*note Creating Strings::).
+
+          (make-list 3 'pigs)
+               => (pigs pigs pigs)
+          (make-list 0 'pigs)
+               => nil
+
+ - Function: append &rest sequences
+     This function returns a list containing all the elements of
+     SEQUENCES.  The SEQUENCES may be lists, vectors, or strings, but
+     the last one should be a list.  All arguments except the last one
+     are copied, so none of them are altered.
+
+     More generally, the final argument to `append' may be any Lisp
+     object.  The final argument is not copied or converted; it becomes
+     the CDR of the last cons cell in the new list.  If the final
+     argument is itself a list, then its elements become in effect
+     elements of the result list.  If the final element is not a list,
+     the result is a "dotted list" since its final CDR is not `nil' as
+     required in a true list.
+
+     See `nconc' in *Note Rearrangement::, for a way to join lists with
+     no copying.
+
+     Here is an example of using `append':
+
+          (setq trees '(pine oak))
+               => (pine oak)
+          (setq more-trees (append '(maple birch) trees))
+               => (maple birch pine oak)
+          
+          trees
+               => (pine oak)
+          more-trees
+               => (maple birch pine oak)
+          (eq trees (cdr (cdr more-trees)))
+               => t
+
+     You can see how `append' works by looking at a box diagram.  The
+     variable `trees' is set to the list `(pine oak)' and then the
+     variable `more-trees' is set to the list `(maple birch pine oak)'.
+     However, the variable `trees' continues to refer to the original
+     list:
+
+          more-trees                trees
+          |                           |
+          |     ___ ___      ___ ___   -> ___ ___      ___ ___
+           --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
+                 |            |            |            |
+                 |            |            |            |
+                  --> maple    -->birch     --> pine     --> oak
+
+     An empty sequence contributes nothing to the value returned by
+     `append'.  As a consequence of this, a final `nil' argument forces
+     a copy of the previous argument.
+
+          trees
+               => (pine oak)
+          (setq wood (append trees ()))
+               => (pine oak)
+          wood
+               => (pine oak)
+          (eq wood trees)
+               => nil
+
+     This once was the usual way to copy a list, before the function
+     `copy-sequence' was invented.  *Note Sequences Arrays Vectors::.
+
+     With the help of `apply', we can append all the lists in a list of
+     lists:
+
+          (apply 'append '((a b c) nil (x y z) nil))
+               => (a b c x y z)
+
+     If no SEQUENCES are given, `nil' is returned:
+
+          (append)
+               => nil
+
+     Here are some examples where the final argument is not a list:
+
+          (append '(x y) 'z)
+               => (x y . z)
+          (append '(x y) [z])
+               => (x y . [z])
+
+     The second example shows that when the final argument is a
+     sequence but not a list, the sequence's elements do not become
+     elements of the resulting list.  Instead, the sequence becomes the
+     final CDR, like any other non-list final argument.
+
+     The `append' function also allows integers as arguments.  It
+     converts them to strings of digits, making up the decimal print
+     representation of the integer, and then uses the strings instead
+     of the original integers.  *Don't use this feature; we plan to
+     eliminate it.  If you already use this feature, change your
+     programs now!*  The proper way to convert an integer to a decimal
+     number in this way is with `format' (*note Formatting Strings::)
+     or `number-to-string' (*note String Conversion::).
+
+ - Function: reverse list
+     This function creates a new list whose elements are the elements of
+     LIST, but in reverse order.  The original argument LIST is _not_
+     altered.
+
+          (setq x '(1 2 3 4))
+               => (1 2 3 4)
+          (reverse x)
+               => (4 3 2 1)
+          x
+               => (1 2 3 4)
+
+\1f
+File: lispref.info,  Node: Modifying Lists,  Next: Sets And Lists,  Prev: Building Lists,  Up: Lists
+
+Modifying Existing List Structure
+=================================
+
+You can modify the CAR and CDR contents of a cons cell with the
+primitives `setcar' and `setcdr'.
+
+     Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
+     to alter list structure; they change structure the same way as
+     `setcar' and `setcdr', but the Common Lisp functions return the
+     cons cell while `setcar' and `setcdr' return the new CAR or CDR.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Setcar,  Next: Setcdr,  Up: Modifying Lists
+
+Altering List Elements with `setcar'
+------------------------------------
+
+Changing the CAR of a cons cell is done with `setcar'.  When used on a
+list, `setcar' replaces one element of a list with a different element.
+
+ - Function: setcar cons-cell object
+     This function stores OBJECT as the new CAR of CONS-CELL, replacing
+     its previous CAR.  It returns the value OBJECT.  For example:
+
+          (setq x '(1 2))
+               => (1 2)
+          (setcar x 4)
+               => 4
+          x
+               => (4 2)
+
+   When a cons cell is part of the shared structure of several lists,
+storing a new CAR into the cons changes one element of each of these
+lists.  Here is an example:
+
+     ;; Create two lists that are partly shared.
+     (setq x1 '(a b c))
+          => (a b c)
+     (setq x2 (cons 'z (cdr x1)))
+          => (z b c)
+     
+     ;; Replace the CAR of a shared link.
+     (setcar (cdr x1) 'foo)
+          => foo
+     x1                           ; Both lists are changed.
+          => (a foo c)
+     x2
+          => (z foo c)
+     
+     ;; Replace the CAR of a link that is not shared.
+     (setcar x1 'baz)
+          => baz
+     x1                           ; Only one list is changed.
+          => (baz foo c)
+     x2
+          => (z foo c)
+
+   Here is a graphical depiction of the shared structure of the two
+lists in the variables `x1' and `x2', showing why replacing `b' changes
+them both:
+
+             ___ ___        ___ ___      ___ ___
+     x1---> |___|___|----> |___|___|--> |___|___|--> nil
+              |        -->   |            |
+              |       |      |            |
+               --> a  |       --> b        --> c
+                      |
+            ___ ___   |
+     x2--> |___|___|--
+             |
+             |
+              --> z
+
+   Here is an alternative form of box diagram, showing the same
+relationship:
+
+     x1:
+      --------------       --------------       --------------
+     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
+     |   a   |   o------->|   b   |   o------->|   c   |  nil |
+     |       |      |  -->|       |      |     |       |      |
+      --------------  |    --------------       --------------
+                      |
+     x2:              |
+      --------------  |
+     | car   | cdr  | |
+     |   z   |   o----
+     |       |      |
+      --------------
+
+\1f
+File: lispref.info,  Node: Setcdr,  Next: Rearrangement,  Prev: Setcar,  Up: Modifying Lists
+
+Altering the CDR of a List
+--------------------------
+
+The lowest-level primitive for modifying a CDR is `setcdr':
+
+ - Function: setcdr cons-cell object
+     This function stores OBJECT as the new CDR of CONS-CELL, replacing
+     its previous CDR.  It returns the value OBJECT.
+
+   Here is an example of replacing the CDR of a list with a different
+list.  All but the first element of the list are removed in favor of a
+different sequence of elements.  The first element is unchanged,
+because it resides in the CAR of the list, and is not reached via the
+CDR.
+
+     (setq x '(1 2 3))
+          => (1 2 3)
+     (setcdr x '(4))
+          => (4)
+     x
+          => (1 4)
+
+   You can delete elements from the middle of a list by altering the
+CDRs of the cons cells in the list.  For example, here we delete the
+second element, `b', from the list `(a b c)', by changing the CDR of
+the first cell:
+
+     (setq x1 '(a b c))
+          => (a b c)
+     (setcdr x1 (cdr (cdr x1)))
+          => (c)
+     x1
+          => (a c)
+
+   Here is the result in box notation:
+
+                        --------------------
+                       |                    |
+      --------------   |   --------------   |    --------------
+     | car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
+     |   a   |   o-----   |   b   |   o-------->|   c   |  nil |
+     |       |      |     |       |      |      |       |      |
+      --------------       --------------        --------------
+
+The second cons cell, which previously held the element `b', still
+exists and its CAR is still `b', but it no longer forms part of this
+list.
+
+   It is equally easy to insert a new element by changing CDRs:
+
+     (setq x1 '(a b c))
+          => (a b c)
+     (setcdr x1 (cons 'd (cdr x1)))
+          => (d b c)
+     x1
+          => (a d b c)
+
+   Here is this result in box notation:
+
+      --------------        -------------       -------------
+     | car  | cdr   |      | car  | cdr  |     | car  | cdr  |
+     |   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
+     |      |   |   |  |   |      |      |     |      |      |
+      --------- | --   |    -------------       -------------
+                |      |
+          -----         --------
+         |                      |
+         |    ---------------   |
+         |   | car   | cdr   |  |
+          -->|   d   |   o------
+             |       |       |
+              ---------------
+
+\1f
+File: lispref.info,  Node: Rearrangement,  Prev: Setcdr,  Up: Modifying Lists
+
+Functions that Rearrange Lists
+------------------------------
+
+Here are some functions that rearrange lists "destructively" by
+modifying the CDRs of their component cons cells.  We call these
+functions "destructive" because they chew up the original lists passed
+to them as arguments, to produce a new list that is the returned value.
+
+   See `delq', in *Note Sets And Lists::, for another function that
+modifies cons cells.
+
+ - Function: nconc &rest lists
+     This function returns a list containing all the elements of LISTS.
+     Unlike `append' (*note Building Lists::), the LISTS are _not_
+     copied.  Instead, the last CDR of each of the LISTS is changed to
+     refer to the following list.  The last of the LISTS is not
+     altered.  For example:
+
+          (setq x '(1 2 3))
+               => (1 2 3)
+          (nconc x '(4 5))
+               => (1 2 3 4 5)
+          x
+               => (1 2 3 4 5)
+
+     Since the last argument of `nconc' is not itself modified, it is
+     reasonable to use a constant list, such as `'(4 5)', as in the
+     above example.  For the same reason, the last argument need not be
+     a list:
+
+          (setq x '(1 2 3))
+               => (1 2 3)
+          (nconc x 'z)
+               => (1 2 3 . z)
+          x
+               => (1 2 3 . z)
+
+     A common pitfall is to use a quoted constant list as a non-last
+     argument to `nconc'.  If you do this, your program will change
+     each time you run it!  Here is what happens:
+
+          (defun add-foo (x)            ; We want this function to add
+            (nconc '(foo) x))           ;   `foo' to the front of its arg.
+          
+          (symbol-function 'add-foo)
+               => (lambda (x) (nconc (quote (foo)) x))
+          
+          (setq xx (add-foo '(1 2)))    ; It seems to work.
+               => (foo 1 2)
+          (setq xy (add-foo '(3 4)))    ; What happened?
+               => (foo 1 2 3 4)
+          (eq xx xy)
+               => t
+          
+          (symbol-function 'add-foo)
+               => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
+
+ - Function: nreverse list
+     This function reverses the order of the elements of LIST.  Unlike
+     `reverse', `nreverse' alters its argument by reversing the CDRs in
+     the cons cells forming the list.  The cons cell that used to be
+     the last one in LIST becomes the first cell of the value.
+
+     For example:
+
+          (setq x '(1 2 3 4))
+               => (1 2 3 4)
+          x
+               => (1 2 3 4)
+          (nreverse x)
+               => (4 3 2 1)
+          ;; The cell that was first is now last.
+          x
+               => (1)
+
+     To avoid confusion, we usually store the result of `nreverse' back
+     in the same variable which held the original list:
+
+          (setq x (nreverse x))
+
+     Here is the `nreverse' of our favorite example, `(a b c)',
+     presented graphically:
+
+          Original list head:                       Reversed list:
+           -------------        -------------        ------------
+          | car  | cdr  |      | car  | cdr  |      | car | cdr  |
+          |   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
+          |      |      |   |  |      |   |  |   |  |     |   |  |
+           -------------    |   --------- | -    |   -------- | -
+                            |             |      |            |
+                             -------------        ------------
+
+ - Function: sort list predicate
+     This function sorts LIST stably, though destructively, and returns
+     the sorted list.  It compares elements using PREDICATE.  A stable
+     sort is one in which elements with equal sort keys maintain their
+     relative order before and after the sort.  Stability is important
+     when successive sorts are used to order elements according to
+     different criteria.
+
+     The argument PREDICATE must be a function that accepts two
+     arguments.  It is called with two elements of LIST.  To get an
+     increasing order sort, the PREDICATE should return `t' if the
+     first element is "less than" the second, or `nil' if not.
+
+     The destructive aspect of `sort' is that it rearranges the cons
+     cells forming LIST by changing CDRs.  A nondestructive sort
+     function would create new cons cells to store the elements in their
+     sorted order.  If you wish to make a sorted copy without
+     destroying the original, copy it first with `copy-sequence' and
+     then sort.
+
+     Sorting does not change the CARs of the cons cells in LIST; the
+     cons cell that originally contained the element `a' in LIST still
+     has `a' in its CAR after sorting, but it now appears in a
+     different position in the list due to the change of CDRs.  For
+     example:
+
+          (setq nums '(1 3 2 6 5 4 0))
+               => (1 3 2 6 5 4 0)
+          (sort nums '<)
+               => (0 1 2 3 4 5 6)
+          nums
+               => (1 2 3 4 5 6)
+
+     Note that the list in `nums' no longer contains 0; this is the same
+     cons cell that it was before, but it is no longer the first one in
+     the list.  Don't assume a variable that formerly held the argument
+     now holds the entire sorted list!  Instead, save the result of
+     `sort' and use that.  Most often we store the result back into the
+     variable that held the original list:
+
+          (setq nums (sort nums '<))
+
+     *Note Sorting::, for more functions that perform sorting.  See
+     `documentation' in *Note Accessing Documentation::, for a useful
+     example of `sort'.
+
+\1f
+File: lispref.info,  Node: Sets And Lists,  Next: Association Lists,  Prev: Modifying Lists,  Up: Lists
+
+Using Lists as Sets
+===================
+
+A list can represent an unordered mathematical set--simply consider a
+value an element of a set if it appears in the list, and ignore the
+order of the list.  To form the union of two sets, use `append' (as
+long as you don't mind having duplicate elements).  Other useful
+functions for sets include `memq' and `delq', and their `equal'
+versions, `member' and `delete'.
+
+     Common Lisp note: Common Lisp has functions `union' (which avoids
+     duplicate elements) and `intersection' for set operations, but
+     XEmacs Lisp does not have them.  You can write them in Lisp if you
+     wish.
+
+ - Function: memq object list
+     This function tests to see whether OBJECT is a member of LIST.  If
+     it is, `memq' returns a list starting with the first occurrence of
+     OBJECT.  Otherwise, it returns `nil'.  The letter `q' in `memq'
+     says that it uses `eq' to compare OBJECT against the elements of
+     the list.  For example:
+
+          (memq 'b '(a b c b a))
+               => (b c b a)
+          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
+               => nil
+
+ - Function: delq object list
+     This function destructively removes all elements `eq' to OBJECT
+     from LIST.  The letter `q' in `delq' says that it uses `eq' to
+     compare OBJECT against the elements of the list, like `memq'.
+
+   When `delq' deletes elements from the front of the list, it does so
+simply by advancing down the list and returning a sublist that starts
+after those elements:
+
+     (delq 'a '(a b c)) == (cdr '(a b c))
+
+   When an element to be deleted appears in the middle of the list,
+removing it involves changing the CDRs (*note Setcdr::).
+
+     (setq sample-list '(a b c (4)))
+          => (a b c (4))
+     (delq 'a sample-list)
+          => (b c (4))
+     sample-list
+          => (a b c (4))
+     (delq 'c sample-list)
+          => (a b (4))
+     sample-list
+          => (a b (4))
+
+   Note that `(delq 'c sample-list)' modifies `sample-list' to splice
+out the third element, but `(delq 'a sample-list)' does not splice
+anything--it just returns a shorter list.  Don't assume that a variable
+which formerly held the argument LIST now has fewer elements, or that
+it still holds the original list!  Instead, save the result of `delq'
+and use that.  Most often we store the result back into the variable
+that held the original list:
+
+     (setq flowers (delq 'rose flowers))
+
+   In the following example, the `(4)' that `delq' attempts to match
+and the `(4)' in the `sample-list' are not `eq':
+
+     (delq '(4) sample-list)
+          => (a c (4))
+
+   The following two functions are like `memq' and `delq' but use
+`equal' rather than `eq' to compare elements.  They are new in Emacs 19.
+
+ - Function: member object list
+     The function `member' tests to see whether OBJECT is a member of
+     LIST, comparing members with OBJECT using `equal'.  If OBJECT is a
+     member, `member' returns a list starting with its first occurrence
+     in LIST.  Otherwise, it returns `nil'.
+
+     Compare this with `memq':
+
+          (member '(2) '((1) (2)))  ; `(2)' and `(2)' are `equal'.
+               => ((2))
+          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
+               => nil
+          ;; Two strings with the same contents are `equal'.
+          (member "foo" '("foo" "bar"))
+               => ("foo" "bar")
+
+ - Function: delete object list
+     This function destructively removes all elements `equal' to OBJECT
+     from LIST.  It is to `delq' as `member' is to `memq': it uses
+     `equal' to compare elements with OBJECT, like `member'; when it
+     finds an element that matches, it removes the element just as
+     `delq' would.  For example:
+
+          (delete '(2) '((2) (1) (2)))
+               => '((1))
+
+     Common Lisp note: The functions `member' and `delete' in XEmacs
+     Lisp are derived from Maclisp, not Common Lisp.  The Common Lisp
+     versions do not use `equal' to compare elements.
+
+   See also the function `add-to-list', in *Note Setting Variables::,
+for another way to add an element to a list stored in a variable.
+
+\1f
+File: lispref.info,  Node: Association Lists,  Next: Property Lists,  Prev: Sets And Lists,  Up: Lists
+
+Association Lists
+=================
+
+An "association list", or "alist" for short, records a mapping from
+keys to values.  It is a list of cons cells called "associations": the
+CAR of each cell is the "key", and the CDR is the "associated value".(1)
+
+   Here is an example of an alist.  The key `pine' is associated with
+the value `cones'; the key `oak' is associated with `acorns'; and the
+key `maple' is associated with `seeds'.
+
+     '((pine . cones)
+       (oak . acorns)
+       (maple . seeds))
+
+   The associated values in an alist may be any Lisp objects; so may the
+keys.  For example, in the following alist, the symbol `a' is
+associated with the number `1', and the string `"b"' is associated with
+the _list_ `(2 3)', which is the CDR of the alist element:
+
+     ((a . 1) ("b" 2 3))
+
+   Sometimes it is better to design an alist to store the associated
+value in the CAR of the CDR of the element.  Here is an example:
+
+     '((rose red) (lily white) (buttercup yellow))
+
+Here we regard `red' as the value associated with `rose'.  One
+advantage of this method is that you can store other related
+information--even a list of other items--in the CDR of the CDR.  One
+disadvantage is that you cannot use `rassq' (see below) to find the
+element containing a given value.  When neither of these considerations
+is important, the choice is a matter of taste, as long as you are
+consistent about it for any given alist.
+
+   Note that the same alist shown above could be regarded as having the
+associated value in the CDR of the element; the value associated with
+`rose' would be the list `(red)'.
+
+   Association lists are often used to record information that you might
+otherwise keep on a stack, since new associations may be added easily to
+the front of the list.  When searching an association list for an
+association with a given key, the first one found is returned, if there
+is more than one.
+
+   In XEmacs Lisp, it is _not_ an error if an element of an association
+list is not a cons cell.  The alist search functions simply ignore such
+elements.  Many other versions of Lisp signal errors in such cases.
+
+   Note that property lists are similar to association lists in several
+respects.  A property list behaves like an association list in which
+each key can occur only once.  *Note Property Lists::, for a comparison
+of property lists and association lists.
+
+ - Function: assoc key alist
+     This function returns the first association for KEY in ALIST.  It
+     compares KEY against the alist elements using `equal' (*note
+     Equality Predicates::).  It returns `nil' if no association in
+     ALIST has a CAR `equal' to KEY.  For example:
+
+          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+               => ((pine . cones) (oak . acorns) (maple . seeds))
+          (assoc 'oak trees)
+               => (oak . acorns)
+          (cdr (assoc 'oak trees))
+               => acorns
+          (assoc 'birch trees)
+               => nil
+
+     Here is another example, in which the keys and values are not
+     symbols:
+
+          (setq needles-per-cluster
+                '((2 "Austrian Pine" "Red Pine")
+                  (3 "Pitch Pine")
+                  (5 "White Pine")))
+          
+          (cdr (assoc 3 needles-per-cluster))
+               => ("Pitch Pine")
+          (cdr (assoc 2 needles-per-cluster))
+               => ("Austrian Pine" "Red Pine")
+
+ - Function: rassoc value alist
+     This function returns the first association with value VALUE in
+     ALIST.  It returns `nil' if no association in ALIST has a CDR
+     `equal' to VALUE.
+
+     `rassoc' is like `assoc' except that it compares the CDR of each
+     ALIST association instead of the CAR.  You can think of this as
+     "reverse `assoc'", finding the key for a given value.
+
+ - Function: assq key alist
+     This function is like `assoc' in that it returns the first
+     association for KEY in ALIST, but it makes the comparison using
+     `eq' instead of `equal'.  `assq' returns `nil' if no association
+     in ALIST has a CAR `eq' to KEY.  This function is used more often
+     than `assoc', since `eq' is faster than `equal' and most alists
+     use symbols as keys.  *Note Equality Predicates::.
+
+          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+               => ((pine . cones) (oak . acorns) (maple . seeds))
+          (assq 'pine trees)
+               => (pine . cones)
+
+     On the other hand, `assq' is not usually useful in alists where the
+     keys may not be symbols:
+
+          (setq leaves
+                '(("simple leaves" . oak)
+                  ("compound leaves" . horsechestnut)))
+          
+          (assq "simple leaves" leaves)
+               => nil
+          (assoc "simple leaves" leaves)
+               => ("simple leaves" . oak)
+
+ - Function: rassq value alist
+     This function returns the first association with value VALUE in
+     ALIST.  It returns `nil' if no association in ALIST has a CDR `eq'
+     to VALUE.
+
+     `rassq' is like `assq' except that it compares the CDR of each
+     ALIST association instead of the CAR.  You can think of this as
+     "reverse `assq'", finding the key for a given value.
+
+     For example:
+
+          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+          
+          (rassq 'acorns trees)
+               => (oak . acorns)
+          (rassq 'spores trees)
+               => nil
+
+     Note that `rassq' cannot search for a value stored in the CAR of
+     the CDR of an element:
+
+          (setq colors '((rose red) (lily white) (buttercup yellow)))
+          
+          (rassq 'white colors)
+               => nil
+
+     In this case, the CDR of the association `(lily white)' is not the
+     symbol `white', but rather the list `(white)'.  This becomes
+     clearer if the association is written in dotted pair notation:
+
+          (lily white) == (lily . (white))
+
+ - Function: remassoc key alist
+     This function deletes by side effect any associations with key KEY
+     in ALIST--i.e. it removes any elements from ALIST whose `car' is
+     `equal' to KEY.  The modified ALIST is returned.
+
+     If the first member of ALIST has a `car' that is `equal' to KEY,
+     there is no way to remove it by side effect; therefore, write
+     `(setq foo (remassoc key foo))' to be sure of changing the value
+     of `foo'.
+
+ - Function: remassq key alist
+     This function deletes by side effect any associations with key KEY
+     in ALIST--i.e. it removes any elements from ALIST whose `car' is
+     `eq' to KEY.  The modified ALIST is returned.
+
+     This function is exactly like `remassoc', but comparisons between
+     KEY and keys in ALIST are done using `eq' instead of `equal'.
+
+ - Function: remrassoc value alist
+     This function deletes by side effect any associations with value
+     VALUE in ALIST--i.e. it removes any elements from ALIST whose
+     `cdr' is `equal' to VALUE.  The modified ALIST is returned.
+
+     If the first member of ALIST has a `car' that is `equal' to VALUE,
+     there is no way to remove it by side effect; therefore, write
+     `(setq foo (remassoc value foo))' to be sure of changing the value
+     of `foo'.
+
+     `remrassoc' is like `remassoc' except that it compares the CDR of
+     each ALIST association instead of the CAR.  You can think of this
+     as "reverse `remassoc'", removing an association based on its
+     value instead of its key.
+
+ - Function: remrassq value alist
+     This function deletes by side effect any associations with value
+     VALUE in ALIST--i.e. it removes any elements from ALIST whose
+     `cdr' is `eq' to VALUE.  The modified ALIST is returned.
+
+     This function is exactly like `remrassoc', but comparisons between
+     VALUE and values in ALIST are done using `eq' instead of `equal'.
+
+ - Function: copy-alist alist
+     This function returns a two-level deep copy of ALIST: it creates a
+     new copy of each association, so that you can alter the
+     associations of the new alist without changing the old one.
+
+          (setq needles-per-cluster
+                '((2 . ("Austrian Pine" "Red Pine"))
+                  (3 . ("Pitch Pine"))
+                  (5 . ("White Pine"))))
+          =>
+          ((2 "Austrian Pine" "Red Pine")
+           (3 "Pitch Pine")
+           (5 "White Pine"))
+          
+          (setq copy (copy-alist needles-per-cluster))
+          =>
+          ((2 "Austrian Pine" "Red Pine")
+           (3 "Pitch Pine")
+           (5 "White Pine"))
+          
+          (eq needles-per-cluster copy)
+               => nil
+          (equal needles-per-cluster copy)
+               => t
+          (eq (car needles-per-cluster) (car copy))
+               => nil
+          (cdr (car (cdr needles-per-cluster)))
+               => ("Pitch Pine")
+          (eq (cdr (car (cdr needles-per-cluster)))
+              (cdr (car (cdr copy))))
+               => t
+
+     This example shows how `copy-alist' makes it possible to change
+     the associations of one copy without affecting the other:
+
+          (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
+          (cdr (assq 3 needles-per-cluster))
+               => ("Pitch Pine")
+
+   ---------- Footnotes ----------
+
+   (1) This usage of "key" is not related to the term "key sequence";
+it means a value used to look up an item in a table.  In this case, the
+table is the alist, and the alist associations are the items.
+
+\1f
+File: lispref.info,  Node: Property Lists,  Next: Weak Lists,  Prev: Association Lists,  Up: Lists
+
+Property Lists
+==============
+
+A "property list" (or "plist") is another way of representing a mapping
+from keys to values.  Instead of the list consisting of conses of a key
+and a value, the keys and values alternate as successive entries in the
+list.  Thus, the association list
+
+     ((a . 1) (b . 2) (c . 3))
+
+   has the equivalent property list form
+
+     (a 1 b 2 c 3)
+
+   Property lists are used to represent the properties associated with
+various sorts of objects, such as symbols, strings, frames, etc.  The
+convention is that property lists can be modified in-place, while
+association lists generally are not.
+
+   Plists come in two varieties: "normal" plists, whose keys are
+compared with `eq', and "lax" plists, whose keys are compared with
+`equal',
+
+ - Function: valid-plist-p plist
+     Given a plist, this function returns non-`nil' if its format is
+     correct.  If it returns `nil', `check-valid-plist' will signal an
+     error when given the plist; that means it's a malformed or circular
+     plist or has non-symbols as keywords.
+
+ - Function: check-valid-plist plist
+     Given a plist, this function signals an error if there is anything
+     wrong with it.  This means that it's a malformed or circular plist.
+
+* Menu:
+
+* Working With Normal Plists::       Functions for normal plists.
+* Working With Lax Plists::          Functions for lax plists.
+* Converting Plists To/From Alists:: Alist to plist and vice-versa.
+
+\1f
+File: lispref.info,  Node: Working With Normal Plists,  Next: Working With Lax Plists,  Up: Property Lists
+
+Working With Normal Plists
+--------------------------
+
+ - Function: plist-get plist property &optional default
+     This function extracts a value from a property list.  The function
+     returns the value corresponding to the given PROPERTY, or DEFAULT
+     if PROPERTY is not one of the properties on the list.
+
+ - Function: plist-put plist property value
+     This function changes the value in PLIST of PROPERTY to VALUE.  If
+     PROPERTY is already a property on the list, its value is set to
+     VALUE, otherwise the new PROPERTY VALUE pair is added.  The new
+     plist is returned; use `(setq x (plist-put x property value))' to
+     be sure to use the new value.  The PLIST is modified by side
+     effects.
+
+ - Function: plist-remprop plist property
+     This function removes from PLIST the property PROPERTY and its
+     value.  The new plist is returned; use `(setq x (plist-remprop x
+     property))' to be sure to use the new value.  The PLIST is
+     modified by side effects.
+
+ - Function: plist-member plist property
+     This function returns `t' if PROPERTY has a value specified in
+     PLIST.
+
+   In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
+non-`nil', then a property with a `nil' value is ignored or removed.
+This feature is a virus that has infected old Lisp implementations (and
+thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
+used except for backward compatibility.
+
+ - Function: plists-eq a b &optional nil-means-not-present
+     This function returns non-`nil' if property lists A and B are `eq'
+     (i.e. their values are `eq').
+
+ - Function: plists-equal a b &optional nil-means-not-present
+     This function returns non-`nil' if property lists A and B are
+     `equal' (i.e. their values are `equal'; their keys are still
+     compared using `eq').
+
+ - Function: canonicalize-plist plist &optional nil-means-not-present
+     This function destructively removes any duplicate entries from a
+     plist.  In such cases, the first entry applies.
+
+     The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
+     return value may not be `eq' to the passed-in value, so make sure
+     to `setq' the value back into where it came from.
+
+\1f
+File: lispref.info,  Node: Working With Lax Plists,  Next: Converting Plists To/From Alists,  Prev: Working With Normal Plists,  Up: Property Lists
+
+Working With Lax Plists
+-----------------------

 
 

-GNU GENERAL PUBLIC LICENSE
-**************************
+Recall that a "lax plist" is a property list whose keys are compared
+using `equal' instead of `eq'.
+
+ - Function: lax-plist-get lax-plist property &optional default
+     This function extracts a value from a lax property list.  The
+     function returns the value corresponding to the given PROPERTY, or
+     DEFAULT if PROPERTY is not one of the properties on the list.
+
+ - Function: lax-plist-put lax-plist property value
+     This function changes the value in LAX-PLIST of PROPERTY to VALUE.
+
+ - Function: lax-plist-remprop lax-plist property
+     This function removes from LAX-PLIST the property PROPERTY and its
+     value.  The new plist is returned; use `(setq x (lax-plist-remprop
+     x property))' to be sure to use the new value.  The LAX-PLIST is
+     modified by side effects.
+
+ - Function: lax-plist-member lax-plist property
+     This function returns `t' if PROPERTY has a value specified in
+     LAX-PLIST.
+
+   In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
+non-`nil', then a property with a `nil' value is ignored or removed.
+This feature is a virus that has infected old Lisp implementations (and
+thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
+used except for backward compatibility.
+
+ - Function: lax-plists-eq a b &optional nil-means-not-present
+     This function returns non-`nil' if lax property lists A and B are
+     `eq' (i.e. their values are `eq'; their keys are still compared
+     using `equal').
+
+ - Function: lax-plists-equal a b &optional nil-means-not-present
+     This function returns non-`nil' if lax property lists A and B are
+     `equal' (i.e. their values are `equal').
+
+ - Function: canonicalize-lax-plist lax-plist &optional
+          nil-means-not-present
+     This function destructively removes any duplicate entries from a
+     lax plist.  In such cases, the first entry applies.
+
+     The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
+     return value may not be `eq' to the passed-in value, so make sure
+     to `setq' the value back into where it came from.
+
+\1f
+File: lispref.info,  Node: Converting Plists To/From Alists,  Prev: Working With Lax Plists,  Up: Property Lists
+
+Converting Plists To/From Alists
+--------------------------------
+
+ - Function: alist-to-plist alist
+     This function converts association list ALIST into the equivalent
+     property-list form.  The plist is returned.  This converts from
+
+          ((a . 1) (b . 2) (c . 3))
+
+     into
+
+          (a 1 b 2 c 3)
+
+     The original alist is not modified.
+
+ - Function: plist-to-alist plist
+     This function converts property list PLIST into the equivalent
+     association-list form.  The alist is returned.  This converts from
+
+          (a 1 b 2 c 3)
+
+     into
+
+          ((a . 1) (b . 2) (c . 3))
+
+     The original plist is not modified.
+
+   The following two functions are equivalent to the preceding two
+except that they destructively modify their arguments, using cons cells
+from the original list to form the new list rather than allocating new
+cons cells.
+
+ - Function: destructive-alist-to-plist alist
+     This function destructively converts association list ALIST into
+     the equivalent property-list form.  The plist is returned.
+
+ - Function: destructive-plist-to-alist plist
+     This function destructively converts property list PLIST into the
+     equivalent association-list form.  The alist is returned.
+
+\1f
+File: lispref.info,  Node: Weak Lists,  Prev: Property Lists,  Up: Lists
+
+Weak Lists
+==========
+
+A "weak list" is a special sort of list whose members are not counted
+as references for the purpose of garbage collection.  This means that,
+for any object in the list, if there are no references to the object
+anywhere outside of the list (or other weak list or weak hash table),
+that object will disappear the next time a garbage collection happens.
+Weak lists can be useful for keeping track of things such as unobtrusive
+lists of another function's buffers or markers.  When that function is
+done with the elements, they will automatically disappear from the list.
+
+   Weak lists are used internally, for example, to manage the list
+holding the children of an extent--an extent that is unused but has a
+parent will still be reclaimed, and will automatically be removed from
+its parent's list of children.
+
+   Weak lists are similar to weak hash tables (*note Weak Hash
+Tables::).
+
+ - Function: weak-list-p object
+     This function returns non-`nil' if OBJECT is a weak list.
+
+   Weak lists come in one of four types:
+
+`simple'
+     Objects in the list disappear if not referenced outside of the
+     list.
+
+`assoc'
+     Objects in the list disappear if they are conses and either the
+     car or the cdr of the cons is not referenced outside of the list.
+
+`key-assoc'
+     Objects in the list disappear if they are conses and the car is not
+     referenced outside of the list.
+
+`value-assoc'
+     Objects in the list disappear if they are conses and the cdr is not
+     referenced outside of the list.
+
+ - Function: make-weak-list &optional type
+     This function creates a new weak list of type TYPE.  TYPE is a
+     symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
+     as described above) and defaults to `simple'.
+
+ - Function: weak-list-type weak
+     This function returns the type of the given weak-list object.
+
+ - Function: weak-list-list weak
+     This function returns the list contained in a weak-list object.
+
+ - Function: set-weak-list-list weak new-list
+     This function changes the list contained in a weak-list object.
+
+\1f
+File: lispref.info,  Node: Sequences Arrays Vectors,  Next: Symbols,  Prev: Lists,  Up: Top
+
+Sequences, Arrays, and Vectors
+******************************
+
+Recall that the "sequence" type is the union of four other Lisp types:
+lists, vectors, bit vectors, and strings.  In other words, any list is
+a sequence, any vector is a sequence, any bit vector is a sequence, and
+any string is a sequence.  The common property that all sequences have
+is that each is an ordered collection of elements.
+
+   An "array" is a single primitive object that has a slot for each
+elements.  All the elements are accessible in constant time, but the
+length of an existing array cannot be changed.  Strings, vectors, and
+bit vectors are the three types of arrays.
+
+   A list is a sequence of elements, but it is not a single primitive
+object; it is made of cons cells, one cell per element.  Finding the
+Nth element requires looking through N cons cells, so elements farther
+from the beginning of the list take longer to access.  But it is
+possible to add elements to the list, or remove elements.
+
+   The following diagram shows the relationship between these types:
+
+               ___________________________________
+              |                                   |
+              |          Sequence                 |
+              |  ______   ______________________  |
+              | |      | |                      | |
+              | | List | |         Array        | |
+              | |      | |  ________   _______  | |
+              | |______| | |        | |       | | |
+              |          | | Vector | | String| | |
+              |          | |________| |_______| | |
+              |          |  __________________  | |
+              |          | |                  | | |
+              |          | |    Bit Vector    | | |
+              |          | |__________________| | |
+              |          |______________________| |
+              |___________________________________|
+
+   The elements of vectors and lists may be any Lisp objects.  The
+elements of strings are all characters.  The elements of bit vectors
+are the numbers 0 and 1.
+
+* Menu:
+
+* Sequence Functions::    Functions that accept any kind of sequence.
+* Arrays::                Characteristics of arrays in XEmacs Lisp.
+* Array Functions::       Functions specifically for arrays.
+* Vectors::               Special characteristics of XEmacs Lisp vectors.
+* Vector Functions::      Functions specifically for vectors.
+* Bit Vectors::           Special characteristics of XEmacs Lisp bit vectors.
+* Bit Vector Functions::  Functions specifically for bit vectors.
+
+\1f
+File: lispref.info,  Node: Sequence Functions,  Next: Arrays,  Up: Sequences Arrays Vectors
+
+Sequences
+=========
+
+In XEmacs Lisp, a "sequence" is either a list, a vector, a bit vector,
+or a string.  The common property that all sequences have is that each
+is an ordered collection of elements.  This section describes functions
+that accept any kind of sequence.
+
+ - Function: sequencep object
+     Returns `t' if OBJECT is a list, vector, bit vector, or string,
+     `nil' otherwise.
+
+ - Function: copy-sequence sequence
+     Returns a copy of SEQUENCE.  The copy is the same type of object
+     as the original sequence, and it has the same elements in the same
+     order.
+
+     Storing a new element into the copy does not affect the original
+     SEQUENCE, and vice versa.  However, the elements of the new
+     sequence are not copies; they are identical (`eq') to the elements
+     of the original.  Therefore, changes made within these elements, as
+     found via the copied sequence, are also visible in the original
+     sequence.
+
+     If the sequence is a string with extents or text properties, the
+     extents and text properties in the copy are also copied, not
+     shared with the original. (This means that modifying the extents
+     or text properties of the original will not affect the copy.)
+     However, the actual values of the properties are shared.  *Note
+     Extents::, *Note Text Properties::.
+
+     See also `append' in *Note Building Lists::, `concat' in *Note
+     Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
+     in *Note Bit Vectors::, for other ways to copy sequences.
+
+          (setq bar '(1 2))
+               => (1 2)
+          (setq x (vector 'foo bar))
+               => [foo (1 2)]
+          (setq y (copy-sequence x))
+               => [foo (1 2)]
+          
+          (eq x y)
+               => nil
+          (equal x y)
+               => t
+          (eq (elt x 1) (elt y 1))
+               => t
+          
+          ;; Replacing an element of one sequence.
+          (aset x 0 'quux)
+          x => [quux (1 2)]
+          y => [foo (1 2)]
+          
+          ;; Modifying the inside of a shared element.
+          (setcar (aref x 1) 69)
+          x => [quux (69 2)]
+          y => [foo (69 2)]
+          
+          ;; Creating a bit vector.
+          (bit-vector 1 0 1 1 0 1 0 0)
+               => #*10110100
+
+ - Function: length sequence
+     Returns the number of elements in SEQUENCE.  If SEQUENCE is a cons
+     cell that is not a list (because the final CDR is not `nil'), a
+     `wrong-type-argument' error is signaled.
+
+          (length '(1 2 3))
+              => 3
+          (length ())
+              => 0
+          (length "foobar")
+              => 6
+          (length [1 2 3])
+              => 3
+          (length #*01101)
+              => 5
+
+ - Function: elt sequence index
+     This function returns the element of SEQUENCE indexed by INDEX.
+     Legitimate values of INDEX are integers ranging from 0 up to one
+     less than the length of SEQUENCE.  If SEQUENCE is a list, then
+     out-of-range values of INDEX return `nil'; otherwise, they trigger
+     an `args-out-of-range' error.
+
+          (elt [1 2 3 4] 2)
+               => 3
+          (elt '(1 2 3 4) 2)
+               => 3
+          (char-to-string (elt "1234" 2))
+               => "3"
+          (elt #*00010000 3)
+               => 1
+          (elt [1 2 3 4] 4)
+               error-->Args out of range: [1 2 3 4], 4
+          (elt [1 2 3 4] -1)
+               error-->Args out of range: [1 2 3 4], -1
+
+     This function generalizes `aref' (*note Array Functions::) and
+     `nth' (*note List Elements::).
+
+\1f
+File: lispref.info,  Node: Arrays,  Next: Array Functions,  Prev: Sequence Functions,  Up: Sequences Arrays Vectors
+
+Arrays
+======
+
+An "array" object has slots that hold a number of other Lisp objects,
+called the elements of the array.  Any element of an array may be
+accessed in constant time.  In contrast, an element of a list requires
+access time that is proportional to the position of the element in the
+list.
+
+   When you create an array, you must specify how many elements it has.
+The amount of space allocated depends on the number of elements.
+Therefore, it is impossible to change the size of an array once it is
+created; you cannot add or remove elements.  However, you can replace an
+element with a different value.
+
+   XEmacs defines three types of array, all of which are
+one-dimensional: "strings", "vectors", and "bit vectors".  A vector is a
+general array; its elements can be any Lisp objects.  A string is a
+specialized array; its elements must be characters.  A bit vector is
+another specialized array; its elements must be bits (an integer, either
+0 or 1).  Each type of array has its own read syntax.  *Note String
+Type::, *Note Vector Type::, and *Note Bit Vector Type::.
+
+   All kinds of array share these characteristics:
+
+   * The first element of an array has index zero, the second element
+     has index 1, and so on.  This is called "zero-origin" indexing.
+     For example, an array of four elements has indices 0, 1, 2, and 3.
+
+   * The elements of an array may be referenced or changed with the
+     functions `aref' and `aset', respectively (*note Array
+     Functions::).
+
+   In principle, if you wish to have an array of text characters, you
+could use either a string or a vector.  In practice, we always choose
+strings for such applications, for four reasons:
+
+   * They usually occupy one-fourth the space of a vector of the same
+     elements.  (This is one-eighth the space for 64-bit machines such
+     as the DEC Alpha, and may also be different when MULE support is
+     compiled into XEmacs.)
+
+   * Strings are printed in a way that shows the contents more clearly
+     as characters.
+
+   * Strings can hold extent and text properties.  *Note Extents::,
+     *Note Text Properties::.
+
+   * Many of the specialized editing and I/O facilities of XEmacs
+     accept only strings.  For example, you cannot insert a vector of
+     characters into a buffer the way you can insert a string.  *Note
+     Strings and Characters::.
+
+   By contrast, for an array of keyboard input characters (such as a key
+sequence), a vector may be necessary, because many keyboard input
+characters are non-printable and are represented with symbols rather
+than with characters.  *Note Key Sequence Input::.
+
+   Similarly, when representing an array of bits, a bit vector has the
+following advantages over a regular vector:
+
+   * They occupy 1/32nd the space of a vector of the same elements.
+     (1/64th on 64-bit machines such as the DEC Alpha.)
+
+   * Bit vectors are printed in a way that shows the contents more
+     clearly as bits.
+
+\1f
+File: lispref.info,  Node: Array Functions,  Next: Vectors,  Prev: Arrays,  Up: Sequences Arrays Vectors
+
+Functions that Operate on Arrays
+================================
+
+In this section, we describe the functions that accept strings, vectors,
+and bit vectors.
+
+ - Function: arrayp object
+     This function returns `t' if OBJECT is an array (i.e., a string,
+     vector, or bit vector).
+
+          (arrayp "asdf")
+          => t
+          (arrayp [a])
+          => t
+          (arrayp #*101)
+          => t
+
+ - Function: aref array index
+     This function returns the INDEXth element of ARRAY.  The first
+     element is at index zero.
+
+          (setq primes [2 3 5 7 11 13])
+               => [2 3 5 7 11 13]
+          (aref primes 4)
+               => 11
+          (elt primes 4)
+               => 11
+          
+          (aref "abcdefg" 1)
+               => ?b
+          
+          (aref #*1101 2)
+               => 0
+
+     See also the function `elt', in *Note Sequence Functions::.
+
+ - Function: aset array index object
+     This function sets the INDEXth element of ARRAY to be OBJECT.  It
+     returns OBJECT.
+
+          (setq w [foo bar baz])
+               => [foo bar baz]
+          (aset w 0 'fu)
+               => fu
+          w
+               => [fu bar baz]
+          
+          (setq x "asdfasfd")
+               => "asdfasfd"
+          (aset x 3 ?Z)
+               => ?Z
+          x
+               => "asdZasfd"
+          
+          (setq bv #*1111)
+               => #*1111
+          (aset bv 2 0)
+               => 0
+          bv
+               => #*1101
+
+     If ARRAY is a string and OBJECT is not a character, a
+     `wrong-type-argument' error results.
+
+ - Function: fillarray array object
+     This function fills the array ARRAY with OBJECT, so that each
+     element of ARRAY is OBJECT.  It returns ARRAY.
+
+          (setq a [a b c d e f g])
+               => [a b c d e f g]
+          (fillarray a 0)
+               => [0 0 0 0 0 0 0]
+          a
+               => [0 0 0 0 0 0 0]
+          
+          (setq s "When in the course")
+               => "When in the course"
+          (fillarray s ?-)
+               => "------------------"
+          
+          (setq bv #*1101)
+               => #*1101
+          (fillarray bv 0)
+               => #*0000
+
+     If ARRAY is a string and OBJECT is not a character, a
+     `wrong-type-argument' error results.
+
+   The general sequence functions `copy-sequence' and `length' are
+often useful for objects known to be arrays.  *Note Sequence
+Functions::.
+
+\1f
+File: lispref.info,  Node: Vectors,  Next: Vector Functions,  Prev: Array Functions,  Up: Sequences Arrays Vectors
+
+Vectors
+=======
+
+Arrays in Lisp, like arrays in most languages, are blocks of memory
+whose elements can be accessed in constant time.  A "vector" is a
+general-purpose array; its elements can be any Lisp objects.  (The other
+kind of array in XEmacs Lisp is the "string", whose elements must be
+characters.)  Vectors in XEmacs serve as obarrays (vectors of symbols),
+although this is a shortcoming that should be fixed.  They are also used
+internally as part of the representation of a byte-compiled function; if
+you print such a function, you will see a vector in it.
+
+   In XEmacs Lisp, the indices of the elements of a vector start from
+zero and count up from there.
+
+   Vectors are printed with square brackets surrounding the elements.
+Thus, a vector whose elements are the symbols `a', `b' and `a' is
+printed as `[a b a]'.  You can write vectors in the same way in Lisp
+input.
+
+   A vector, like a string or a number, is considered a constant for
+evaluation: the result of evaluating it is the same vector.  This does
+not evaluate or even examine the elements of the vector.  *Note
+Self-Evaluating Forms::.
+
+   Here are examples of these principles:
+
+     (setq avector [1 two '(three) "four" [five]])
+          => [1 two (quote (three)) "four" [five]]
+     (eval avector)
+          => [1 two (quote (three)) "four" [five]]
+     (eq avector (eval avector))
+          => t
+
+\1f
+File: lispref.info,  Node: Vector Functions,  Next: Bit Vectors,  Prev: Vectors,  Up: Sequences Arrays Vectors
+
+Functions That Operate on Vectors
+=================================
+
+Here are some functions that relate to vectors:
+
+ - Function: vectorp object
+     This function returns `t' if OBJECT is a vector.
+
+          (vectorp [a])
+               => t
+          (vectorp "asdf")
+               => nil
+
+ - Function: vector &rest objects
+     This function creates and returns a vector whose elements are the
+     arguments, OBJECTS.
+
+          (vector 'foo 23 [bar baz] "rats")
+               => [foo 23 [bar baz] "rats"]
+          (vector)
+               => []
+
+ - Function: make-vector length object
+     This function returns a new vector consisting of LENGTH elements,
+     each initialized to OBJECT.
+
+          (setq sleepy (make-vector 9 'Z))
+               => [Z Z Z Z Z Z Z Z Z]
+
+ - Function: vconcat &rest sequences
+     This function returns a new vector containing all the elements of
+     the SEQUENCES.  The arguments SEQUENCES may be lists, vectors, or
+     strings.  If no SEQUENCES are given, an empty vector is returned.
+
+     The value is a newly constructed vector that is not `eq' to any
+     existing vector.
+
+          (setq a (vconcat '(A B C) '(D E F)))
+               => [A B C D E F]
+          (eq a (vconcat a))
+               => nil
+          (vconcat)
+               => []
+          (vconcat [A B C] "aa" '(foo (6 7)))
+               => [A B C 97 97 foo (6 7)]
+
+     The `vconcat' function also allows integers as arguments.  It
+     converts them to strings of digits, making up the decimal print
+     representation of the integer, and then uses the strings instead
+     of the original integers.  *Don't use this feature; we plan to
+     eliminate it.  If you already use this feature, change your
+     programs now!*  The proper way to convert an integer to a decimal
+     number in this way is with `format' (*note Formatting Strings::)
+     or `number-to-string' (*note String Conversion::).
+
+     For other concatenation functions, see `mapconcat' in *Note
+     Mapping Functions::, `concat' in *Note Creating Strings::, `append'
+     in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
+     Functions::.
+
+   The `append' function provides a way to convert a vector into a list
+with the same elements (*note Building Lists::):
+
+     (setq avector [1 two (quote (three)) "four" [five]])
+          => [1 two (quote (three)) "four" [five]]
+     (append avector nil)
+          => (1 two (quote (three)) "four" [five])
+
+\1f
+File: lispref.info,  Node: Bit Vectors,  Next: Bit Vector Functions,  Prev: Vector Functions,  Up: Sequences Arrays Vectors
+
+Bit Vectors
+===========
+
+Bit vectors are specialized vectors that can only represent arrays of
+1's and 0's.  Bit vectors have a very efficient representation and are
+useful for representing sets of boolean (true or false) values.
+
+   There is no limit on the size of a bit vector.  You could, for
+example, create a bit vector with 100,000 elements if you really wanted
+to.
+
+   Bit vectors have a special printed representation consisting of `#*'
+followed by the bits of the vector.  For example, a bit vector whose
+elements are 0, 1, 1, 0, and 1, respectively, is printed as
+
+     #*01101
+
+   Bit vectors are considered constants for evaluation, like vectors,
+strings, and numbers.  *Note Self-Evaluating Forms::.
+
+\1f
+File: lispref.info,  Node: Bit Vector Functions,  Prev: Bit Vectors,  Up: Sequences Arrays Vectors
+
+Functions That Operate on Bit Vectors
+=====================================
+
+Here are some functions that relate to bit vectors:
+
+ - Function: bit-vector-p object
+     This function returns `t' if OBJECT is a bit vector.
+
+          (bit-vector-p #*01)
+               => t
+          (bit-vector-p [0 1])
+               => nil
+          (bit-vector-p "01")
+               => nil
+
+ - Function: bitp object
+     This function returns `t' if OBJECT is either 0 or 1.
+
+ - Function: bit-vector &rest bits
+     This function creates and returns a bit vector whose elements are
+     the arguments BITS.  Each argument must be a bit, i.e. one of the
+     two integers 0 or 1.
+
+          (bit-vector 0 0 0 1 0 0 0 0 1 0)
+               => #*0001000010
+          (bit-vector)
+               => #*
+
+ - Function: make-bit-vector length bit
+     This function creates and returns a bit vector consisting of
+     LENGTH elements, each initialized to BIT, which must be one of the
+     two integers 0 or 1.
+
+          (setq picket-fence (make-bit-vector 9 1))
+               => #*111111111
+
+ - Function: bvconcat &rest sequences
+     This function returns a new bit vector containing all the elements
+     of the SEQUENCES.  The arguments SEQUENCES may be lists, vectors,
+     or bit vectors, all of whose elements are the integers 0 or 1.  If
+     no SEQUENCES are given, an empty bit vector is returned.
+
+     The value is a newly constructed bit vector that is not `eq' to any
+     existing bit vector.
+
+          (setq a (bvconcat '(1 1 0) '(0 0 1)))
+               => #*110001
+          (eq a (bvconcat a))
+               => nil
+          (bvconcat)
+               => #*
+          (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
+               => #*1000011100001
+
+     For other concatenation functions, see `mapconcat' in *Note
+     Mapping Functions::, `concat' in *Note Creating Strings::,
+     `vconcat' in *Note Vector Functions::, and `append' in *Note
+     Building Lists::.
+
+   The `append' function provides a way to convert a bit vector into a
+list with the same elements (*note Building Lists::):
+
+     (setq bv #*00001110)
+          => #*00001110
+     (append bv nil)
+          => (0 0 0 0 1 1 1 0)
+
+\1f
+File: lispref.info,  Node: Symbols,  Next: Evaluation,  Prev: Sequences Arrays Vectors,  Up: Top
+
+Symbols
+*******
+
+A "symbol" is an object with a unique name.  This chapter describes
+symbols, their components, their property lists, and how they are
+created and interned.  Separate chapters describe the use of symbols as
+variables and as function names; see *Note Variables::, and *Note
+Functions::.  For the precise read syntax for symbols, see *Note Symbol
+Type::.
+
+   You can test whether an arbitrary Lisp object is a symbol with
+`symbolp':
+
+ - Function: symbolp object
+     This function returns `t' if OBJECT is a symbol, `nil' otherwise.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Symbol Components,  Next: Definitions,  Up: Symbols
+
+Symbol Components
+=================
+
+Each symbol has four components (or "cells"), each of which references
+another object:
+
+Print name
+     The "print name cell" holds a string that names the symbol for
+     reading and printing.  See `symbol-name' in *Note Creating
+     Symbols::.
+
+Value
+     The "value cell" holds the current value of the symbol as a
+     variable.  When a symbol is used as a form, the value of the form
+     is the contents of the symbol's value cell.  See `symbol-value' in
+     *Note Accessing Variables::.
+
+Function
+     The "function cell" holds the function definition of the symbol.
+     When a symbol is used as a function, its function definition is
+     used in its place.  This cell is also used to make a symbol stand
+     for a keymap or a keyboard macro, for editor command execution.
+     Because each symbol has separate value and function cells,
+     variables and function names do not conflict.  See
+     `symbol-function' in *Note Function Cells::.
+
+Property list
+     The "property list cell" holds the property list of the symbol.
+     See `symbol-plist' in *Note Symbol Properties::.
+
+   The print name cell always holds a string, and cannot be changed.
+The other three cells can be set individually to any specified Lisp
+object.
+
+   The print name cell holds the string that is the name of the symbol.
+Since symbols are represented textually by their names, it is important
+not to have two symbols with the same name.  The Lisp reader ensures
+this: every time it reads a symbol, it looks for an existing symbol with
+the specified name before it creates a new one.  (In XEmacs Lisp, this
+lookup uses a hashing algorithm and an obarray; see *Note Creating
+Symbols::.)
+
+   In normal usage, the function cell usually contains a function or
+macro, as that is what the Lisp interpreter expects to see there (*note
+Evaluation::).  Keyboard macros (*note Keyboard Macros::), keymaps
+(*note Keymaps::) and autoload objects (*note Autoloading::) are also
+sometimes stored in the function cell of symbols.  We often refer to
+"the function `foo'" when we really mean the function stored in the
+function cell of the symbol `foo'.  We make the distinction only when
+necessary.
+
+   The property list cell normally should hold a correctly formatted
+property list (*note Property Lists::), as a number of functions expect
+to see a property list there.
+
+   The function cell or the value cell may be "void", which means that
+the cell does not reference any object.  (This is not the same thing as
+holding the symbol `void', nor the same as holding the symbol `nil'.)
+Examining a cell that is void results in an error, such as `Symbol's
+value as variable is void'.
+
+   The four functions `symbol-name', `symbol-value', `symbol-plist',
+and `symbol-function' return the contents of the four cells of a
+symbol.  Here as an example we show the contents of the four cells of
+the symbol `buffer-file-name':
+
+     (symbol-name 'buffer-file-name)
+          => "buffer-file-name"
+     (symbol-value 'buffer-file-name)
+          => "/gnu/elisp/symbols.texi"
+     (symbol-plist 'buffer-file-name)
+          => (variable-documentation 29529)
+     (symbol-function 'buffer-file-name)
+          => #<subr buffer-file-name>
+
+Because this symbol is the variable which holds the name of the file
+being visited in the current buffer, the value cell contents we see are
+the name of the source file of this chapter of the XEmacs Lisp Reference
+Manual.  The property list cell contains the list
+`(variable-documentation 29529)' which tells the documentation
+functions where to find the documentation string for the variable
+`buffer-file-name' in the `DOC' file.  (29529 is the offset from the
+beginning of the `DOC' file to where that documentation string begins.)
+The function cell contains the function for returning the name of the
+file.  `buffer-file-name' names a primitive function, which has no read
+syntax and prints in hash notation (*note Primitive Function Type::).  A
+symbol naming a function written in Lisp would have a lambda expression
+(or a byte-code object) in this cell.
+
+\1f
+File: lispref.info,  Node: Definitions,  Next: Creating Symbols,  Prev: Symbol Components,  Up: Symbols
+
+Defining Symbols
+================
+
+A "definition" in Lisp is a special form that announces your intention
+to use a certain symbol in a particular way.  In XEmacs Lisp, you can
+define a symbol as a variable, or define it as a function (or macro),
+or both independently.
+
+   A definition construct typically specifies a value or meaning for the
+symbol for one kind of use, plus documentation for its meaning when used
+in this way.  Thus, when you define a symbol as a variable, you can
+supply an initial value for the variable, plus documentation for the
+variable.
+
+   `defvar' and `defconst' are special forms that define a symbol as a
+global variable.  They are documented in detail in *Note Defining
+Variables::.
+
+   `defun' defines a symbol as a function, creating a lambda expression
+and storing it in the function cell of the symbol.  This lambda
+expression thus becomes the function definition of the symbol.  (The
+term "function definition", meaning the contents of the function cell,
+is derived from the idea that `defun' gives the symbol its definition
+as a function.)  `defsubst', `define-function' and `defalias' are other
+ways of defining a function.  *Note Functions::.
+
+   `defmacro' defines a symbol as a macro.  It creates a macro object
+and stores it in the function cell of the symbol.  Note that a given
+symbol can be a macro or a function, but not both at once, because both
+macro and function definitions are kept in the function cell, and that
+cell can hold only one Lisp object at any given time.  *Note Macros::.
+
+   In XEmacs Lisp, a definition is not required in order to use a symbol
+as a variable or function.  Thus, you can make a symbol a global
+variable with `setq', whether you define it first or not.  The real
+purpose of definitions is to guide programmers and programming tools.
+They inform programmers who read the code that certain symbols are
+_intended_ to be used as variables, or as functions.  In addition,
+utilities such as `etags' and `make-docfile' recognize definitions, and
+add appropriate information to tag tables and the `DOC' file. *Note
+Accessing Documentation::.
+
+\1f
+File: lispref.info,  Node: Creating Symbols,  Next: Symbol Properties,  Prev: Definitions,  Up: Symbols
+
+Creating and Interning Symbols
+==============================
+
+To understand how symbols are created in XEmacs Lisp, you must know how
+Lisp reads them.  Lisp must ensure that it finds the same symbol every
+time it reads the same set of characters.  Failure to do so would cause
+complete confusion.
+
+   When the Lisp reader encounters a symbol, it reads all the characters
+of the name.  Then it "hashes" those characters to find an index in a
+table called an "obarray".  Hashing is an efficient method of looking
+something up.  For example, instead of searching a telephone book cover
+to cover when looking up Jan Jones, you start with the J's and go from
+there.  That is a simple version of hashing.  Each element of the
+obarray is a "bucket" which holds all the symbols with a given hash
+code; to look for a given name, it is sufficient to look through all
+the symbols in the bucket for that name's hash code.
+
+   If a symbol with the desired name is found, the reader uses that
+symbol.  If the obarray does not contain a symbol with that name, the
+reader makes a new symbol and adds it to the obarray.  Finding or adding
+a symbol with a certain name is called "interning" it, and the symbol
+is then called an "interned symbol".
+
+   Interning ensures that each obarray has just one symbol with any
+particular name.  Other like-named symbols may exist, but not in the
+same obarray.  Thus, the reader gets the same symbols for the same
+names, as long as you keep reading with the same obarray.
+
+   No obarray contains all symbols; in fact, some symbols are not in any
+obarray.  They are called "uninterned symbols".  An uninterned symbol
+has the same four cells as other symbols; however, the only way to gain
+access to it is by finding it in some other object or as the value of a
+variable.
+
+   In XEmacs Lisp, an obarray is actually a vector.  Each element of the
+vector is a bucket; its value is either an interned symbol whose name
+hashes to that bucket, or 0 if the bucket is empty.  Each interned
+symbol has an internal link (invisible to the user) to the next symbol
+in the bucket.  Because these links are invisible, there is no way to
+find all the symbols in an obarray except using `mapatoms' (below).
+The order of symbols in a bucket is not significant.
+
+   In an empty obarray, every element is 0, and you can create an
+obarray with `(make-vector LENGTH 0)'.  *This is the only valid way to
+create an obarray.*  Prime numbers as lengths tend to result in good
+hashing; lengths one less than a power of two are also good.
+
+   *Do not try to put symbols in an obarray yourself.*  This does not
+work--only `intern' can enter a symbol in an obarray properly.  *Do not
+try to intern one symbol in two obarrays.*  This would garble both
+obarrays, because a symbol has just one slot to hold the following
+symbol in the obarray bucket.  The results would be unpredictable.
+
+   It is possible for two different symbols to have the same name in
+different obarrays; these symbols are not `eq' or `equal'.  However,
+this normally happens only as part of the abbrev mechanism (*note
+Abbrevs::).
+
+     Common Lisp note: In Common Lisp, a single symbol may be interned
+     in several obarrays.
+
+   Most of the functions below take a name and sometimes an obarray as
+arguments.  A `wrong-type-argument' error is signaled if the name is
+not a string, or if the obarray is not a vector.
+
+ - Function: symbol-name symbol
+     This function returns the string that is SYMBOL's name.  For
+     example:
+
+          (symbol-name 'foo)
+               => "foo"
+
+     Changing the string by substituting characters, etc, does change
+     the name of the symbol, but fails to update the obarray, so don't
+     do it!
+
+ - Function: make-symbol name
+     This function returns a newly-allocated, uninterned symbol whose
+     name is NAME (which must be a string).  Its value and function
+     definition are void, and its property list is `nil'.  In the
+     example below, the value of `sym' is not `eq' to `foo' because it
+     is a distinct uninterned symbol whose name is also `foo'.
+
+          (setq sym (make-symbol "foo"))
+               => foo
+          (eq sym 'foo)
+               => nil
+
+ - Function: intern name &optional obarray
+     This function returns the interned symbol whose name is NAME.  If
+     there is no such symbol in the obarray OBARRAY, `intern' creates a
+     new one, adds it to the obarray, and returns it.  If OBARRAY is
+     omitted, the value of the global variable `obarray' is used.
+
+          (setq sym (intern "foo"))
+               => foo
+          (eq sym 'foo)
+               => t
+          
+          (setq sym1 (intern "foo" other-obarray))
+               => foo
+          (eq sym 'foo)
+               => nil
+
+ - Function: intern-soft name &optional obarray
+     This function returns the symbol in OBARRAY whose name is NAME, or
+     `nil' if OBARRAY has no symbol with that name.  Therefore, you can
+     use `intern-soft' to test whether a symbol with a given name is
+     already interned.  If OBARRAY is omitted, the value of the global
+     variable `obarray' is used.
+
+          (intern-soft "frazzle")        ; No such symbol exists.
+               => nil
+          (make-symbol "frazzle")        ; Create an uninterned one.
+               => frazzle
+          (intern-soft "frazzle")        ; That one cannot be found.
+               => nil
+          (setq sym (intern "frazzle"))  ; Create an interned one.
+               => frazzle
+          (intern-soft "frazzle")        ; That one can be found!
+               => frazzle
+          (eq sym 'frazzle)              ; And it is the same one.
+               => t
+
+ - Variable: obarray
+     This variable is the standard obarray for use by `intern' and
+     `read'.
+
+ - Function: mapatoms function &optional obarray
+     This function calls FUNCTION for each symbol in the obarray
+     OBARRAY.  It returns `nil'.  If OBARRAY is omitted, it defaults to
+     the value of `obarray', the standard obarray for ordinary symbols.
+
+          (setq count 0)
+               => 0
+          (defun count-syms (s)
+            (setq count (1+ count)))
+               => count-syms
+          (mapatoms 'count-syms)
+               => nil
+          count
+               => 1871
+
+     See `documentation' in *Note Accessing Documentation::, for another
+     example using `mapatoms'.
+
+ - Function: unintern symbol &optional obarray
+     This function deletes SYMBOL from the obarray OBARRAY.  If
+     `symbol' is not actually in the obarray, `unintern' does nothing.
+     If OBARRAY is `nil', the current obarray is used.
+
+     If you provide a string instead of a symbol as SYMBOL, it stands
+     for a symbol name.  Then `unintern' deletes the symbol (if any) in
+     the obarray which has that name.  If there is no such symbol,
+     `unintern' does nothing.
+
+     If `unintern' does delete a symbol, it returns `t'.  Otherwise it
+     returns `nil'.
+
+\1f
+File: lispref.info,  Node: Symbol Properties,  Prev: Creating Symbols,  Up: Symbols
+
+Symbol Properties
+=================
+
+A "property list" ("plist" for short) is a list of paired elements,
+often stored in the property list cell of a symbol.  Each of the pairs
+associates a property name (usually a symbol) with a property or value.
+Property lists are generally used to record information about a
+symbol, such as its documentation as a variable, the name of the file
+where it was defined, or perhaps even the grammatical class of the
+symbol (representing a word) in a language-understanding system.
+
+   Some objects which are not symbols also have property lists
+associated with them, and XEmacs provides a full complement of
+functions for working with property lists.  *Note Property Lists::.
+
+   The property names and values in a property list can be any Lisp
+objects, but the names are usually symbols.  They are compared using
+`eq'.  Here is an example of a property list, found on the symbol
+`progn' when the compiler is loaded:
+
+     (lisp-indent-function 0 byte-compile byte-compile-progn)
+
+Here `lisp-indent-function' and `byte-compile' are property names, and
+the other two elements are the corresponding values.
+
+* Menu:
+
+* Plists and Alists::           Comparison of the advantages of property
+                                  lists and association lists.
+* Object Plists::               Functions to access objects' property lists.
+* Other Plists::                Accessing property lists stored elsewhere.
+
+\1f
+File: lispref.info,  Node: Plists and Alists,  Next: Object Plists,  Up: Symbol Properties
+
+Property Lists and Association Lists
+------------------------------------
+
+Association lists (*note Association Lists::) are very similar to
+property lists.  In contrast to association lists, the order of the
+pairs in the property list is not significant since the property names
+must be distinct.
+
+   Property lists are better than association lists for attaching
+information to various Lisp function names or variables.  If all the
+associations are recorded in one association list, the program will need
+to search that entire list each time a function or variable is to be
+operated on.  By contrast, if the information is recorded in the
+property lists of the function names or variables themselves, each
+search will scan only the length of one property list, which is usually
+short.  This is why the documentation for a variable is recorded in a
+property named `variable-documentation'.  The byte compiler likewise
+uses properties to record those functions needing special treatment.
+
+   However, association lists have their own advantages.  Depending on
+your application, it may be faster to add an association to the front of
+an association list than to update a property.  All properties for a
+symbol are stored in the same property list, so there is a possibility
+of a conflict between different uses of a property name.  (For this
+reason, it is a good idea to choose property names that are probably
+unique, such as by including the name of the library in the property
+name.)  An association list may be used like a stack where associations
+are pushed on the front of the list and later discarded; this is not
+possible with a property list.
+
+\1f
+File: lispref.info,  Node: Object Plists,  Next: Other Plists,  Prev: Plists and Alists,  Up: Symbol Properties
+
+Property List Functions for Objects
+-----------------------------------
+
+Once upon a time, only symbols had property lists.  Now, several other
+object types, including strings, extents, faces and glyphs also have
+property lists.
+
+ - Function: symbol-plist symbol
+     This function returns the property list of SYMBOL.
+
+ - Function: object-plist object
+     This function returns the property list of OBJECT.  If OBJECT is a
+     symbol, this is identical to `symbol-plist'.
+
+ - Function: setplist symbol plist
+     This function sets SYMBOL's property list to PLIST.  Normally,
+     PLIST should be a well-formed property list, but this is not
+     enforced.
+
+          (setplist 'foo '(a 1 b (2 3) c nil))
+               => (a 1 b (2 3) c nil)
+          (symbol-plist 'foo)
+               => (a 1 b (2 3) c nil)
+
+     For symbols in special obarrays, which are not used for ordinary
+     purposes, it may make sense to use the property list cell in a
+     nonstandard fashion; in fact, the abbrev mechanism does so (*note
+     Abbrevs::).  But generally, its use is discouraged.  Use `put'
+     instead.  `setplist' can only be used with symbols, not other
+     object types.
+
+ - Function: get object property &optional default
+     This function finds the value of the property named PROPERTY in
+     OBJECT's property list.  If there is no such property, `default'
+     (which itself defaults to `nil') is returned.
+
+     PROPERTY is compared with the existing properties using `eq', so
+     any object is a legitimate property.
+
+     See `put' for an example.
+
+ - Function: put object property value
+     This function puts VALUE onto OBJECT's property list under the
+     property name PROPERTY, replacing any previous property value.
+     The `put' function returns VALUE.
+
+          (put 'fly 'verb 'transitive)
+               =>'transitive
+          (put 'fly 'noun '(a buzzing little bug))
+               => (a buzzing little bug)
+          (get 'fly 'verb)
+               => transitive
+          (object-plist 'fly)
+               => (verb transitive noun (a buzzing little bug))
+
+ - Function: remprop object property
+     This function removes the entry for PROPERTY from the property
+     list of OBJECT.  It returns `t' if the property was indeed found
+     and removed, or `nil' if there was no such property.  (This
+     function was probably omitted from Emacs originally because, since
+     `get' did not allow a DEFAULT, it was very difficult to
+     distinguish between a missing property and a property whose value
+     was `nil'; thus, setting a property to `nil' was close enough to
+     `remprop' for most purposes.)
+
+\1f
+File: lispref.info,  Node: Other Plists,  Prev: Object Plists,  Up: Symbol Properties
+
+Property Lists Not Associated with Objects
+------------------------------------------
+
+These functions are useful for manipulating property lists that are
+stored in places other than symbols:
+
+ - Function: getf plist property &optional default
+     This returns the value of the PROPERTY property stored in the
+     property list PLIST.  For example,
+
+          (getf '(foo 4) 'foo)
+               => 4
+
+ - Macro: putf plist property value
+     This stores VALUE as the value of the PROPERTY property in the
+     property list PLIST.  It may modify PLIST destructively, or it may
+     construct a new list structure without altering the old.  The
+     function returns the modified property list, so you can store that
+     back in the place where you got PLIST.  For example,
+
+          (setq my-plist '(bar t foo 4))
+               => (bar t foo 4)
+          (setq my-plist (putf my-plist 'foo 69))
+               => (bar t foo 69)
+          (setq my-plist (putf my-plist 'quux '(a)))
+               => (quux (a) bar t foo 5)
+
+ - Function: plists-eq a b
+     This function returns non-`nil' if property lists A and B are
+     `eq'.  This means that the property lists have the same values for
+     all the same properties, where comparison between values is done
+     using `eq'.
+
+ - Function: plists-equal a b
+     This function returns non-`nil' if property lists A and B are
+     `equal'.
+
+   Both of the above functions do order-insensitive comparisons.
+
+     (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
+          => t
+     (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+          => nil
+     (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+          => t
+
+\1f
+File: lispref.info,  Node: Evaluation,  Next: Control Structures,  Prev: Symbols,  Up: Top
+
+Evaluation
+**********
+
+The "evaluation" of expressions in XEmacs Lisp is performed by the
+"Lisp interpreter"--a program that receives a Lisp object as input and
+computes its "value as an expression".  How it does this depends on the
+data type of the object, according to rules described in this chapter.
+The interpreter runs automatically to evaluate portions of your
+program, but can also be called explicitly via the Lisp primitive
+function `eval'.
+
+* Menu:
+
+* 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).
+
+\1f
+File: lispref.info,  Node: Intro Eval,  Next: Eval,  Up: Evaluation
+
+Introduction to Evaluation
+==========================
+
+The Lisp interpreter, or evaluator, is the program that computes the
+value of an expression that is given to it.  When a function written in
+Lisp is called, the evaluator computes the value of the function by
+evaluating the expressions in the function body.  Thus, running any
+Lisp program really means running the Lisp interpreter.
+
+   How the evaluator handles an object depends primarily on the data
+type of the object.
+
+   A Lisp object that is intended for evaluation is called an
+"expression" or a "form".  The fact that expressions are data objects
+and not merely text is one of the fundamental differences between
+Lisp-like languages and typical programming languages.  Any object can
+be evaluated, but in practice only numbers, symbols, lists and strings
+are evaluated very often.
+
+   It is very common to read a Lisp expression and then evaluate the
+expression, but reading and evaluation are separate activities, and
+either can be performed alone.  Reading per se does not evaluate
+anything; it converts the printed representation of a Lisp object to the
+object itself.  It is up to the caller of `read' whether this object is
+a form to be evaluated, or serves some entirely different purpose.
+*Note Input Functions::.
+
+   Do not confuse evaluation with command key interpretation.  The
+editor command loop translates keyboard input into a command (an
+interactively callable function) using the active keymaps, and then
+uses `call-interactively' to invoke the command.  The execution of the
+command itself involves evaluation if the command is written in Lisp,
+but that is not a part of command key interpretation itself.  *Note
+Command Loop::.
+
+   Evaluation is a recursive process.  That is, evaluation of a form may
+call `eval' to evaluate parts of the form.  For example, evaluation of
+a function call first evaluates each argument of the function call, and
+then evaluates each form in the function body.  Consider evaluation of
+the form `(car x)': the subform `x' must first be evaluated
+recursively, so that its value can be passed as an argument to the
+function `car'.
+
+   Evaluation of a function call ultimately calls the function specified
+in it.  *Note Functions::.  The execution of the function may itself
+work by evaluating the function definition; or the function may be a
+Lisp primitive implemented in C, or it may be a byte-compiled function
+(*note Byte Compilation::).
+
+   The evaluation of forms takes place in a context called the
+"environment", which consists of the current values and bindings of all
+Lisp variables.(1)  Whenever the form refers to a variable without
+creating a new binding for it, the value of the binding in the current
+environment is used.  *Note Variables::.
+
+   Evaluation of a form may create new environments for recursive
+evaluation by binding variables (*note Local Variables::).  These
+environments are temporary and vanish by the time evaluation of the form
+is complete.  The form may also make changes that persist; these changes
+are called "side effects".  An example of a form that produces side
+effects is `(setq foo 1)'.
+
+   The details of what evaluation means for each kind of form are
+described below (*note Forms::).
+
+   ---------- Footnotes ----------
+
+   (1) This definition of "environment" is specifically not intended to
+include all the data that can affect the result of a program.
+
+\1f
+File: lispref.info,  Node: Eval,  Next: Forms,  Prev: Intro Eval,  Up: Evaluation
+
+Eval
+====
+
+Most often, forms are evaluated automatically, by virtue of their
+occurrence in a program being run.  On rare occasions, you may need to
+write code that evaluates a form that is computed at run time, such as
+after reading a form from text being edited or getting one from a
+property list.  On these occasions, use the `eval' function.
+
+   *Please note:* it is generally cleaner and more flexible to call
+functions that are stored in data structures, rather than to evaluate
+expressions stored in data structures.  Using functions provides the
+ability to pass information to them as arguments.
+
+   The functions and variables described in this section evaluate forms,
+specify limits to the evaluation process, or record recently returned
+values.  Loading a file also does evaluation (*note Loading::).
+
+ - Function: eval form
+     This is the basic function for performing evaluation.  It evaluates
+     FORM in the current environment and returns the result.  How the
+     evaluation proceeds depends on the type of the object (*note
+     Forms::).
+
+     Since `eval' is a function, the argument expression that appears
+     in a call to `eval' is evaluated twice: once as preparation before
+     `eval' is called, and again by the `eval' function itself.  Here
+     is an example:
+
+          (setq foo 'bar)
+               => bar
+          (setq bar 'baz)
+               => baz
+          ;; `eval' receives argument `bar', which is the value of `foo'
+          (eval foo)
+               => baz
+          (eval 'foo)
+               => bar
+
+     The number of currently active calls to `eval' is limited to
+     `max-lisp-eval-depth' (see below).
+
+ - Command: eval-region start end &optional stream
+     This function evaluates the forms in the current buffer in the
+     region defined by the positions START and END.  It reads forms from
+     the region and calls `eval' on them until the end of the region is
+     reached, or until an error is signaled and not handled.
+
+     If STREAM is supplied, `standard-output' is bound to it during the
+     evaluation.
+
+     You can use the variable `load-read-function' to specify a function
+     for `eval-region' to use instead of `read' for reading
+     expressions.  *Note How Programs Do Loading::.
+
+     `eval-region' always returns `nil'.
+
+ - Command: eval-buffer buffer &optional stream
+     This is like `eval-region' except that it operates on the whole
+     contents of BUFFER.
+
+ - Variable: max-lisp-eval-depth
+     This variable defines the maximum depth allowed in calls to `eval',
+     `apply', and `funcall' before an error is signaled (with error
+     message `"Lisp nesting exceeds max-lisp-eval-depth"').  This counts
+     internal uses of those functions, such as for calling the functions
+     mentioned in Lisp expressions, and recursive evaluation of
+     function call arguments and function body forms.
+
+     This limit, with the associated error when it is exceeded, is one
+     way that Lisp avoids infinite recursion on an ill-defined function.
+
+     The default value of this variable is 1000.  If you set it to a
+     value less than 100, Lisp will reset it to 100 if the given value
+     is reached.
+
+     `max-specpdl-size' provides another limit on nesting.  *Note Local
+     Variables::.
+
+ - Variable: values
+     The value of this variable is a list of the values returned by all
+     the expressions that were read from buffers (including the
+     minibuffer), evaluated, and printed.  The elements are ordered
+     most recent first.
+
+          (setq x 1)
+               => 1
+          (list 'A (1+ 2) auto-save-default)
+               => (A 3 t)
+          values
+               => ((A 3 t) 1 ...)
+
+     This variable is useful for referring back to values of forms
+     recently evaluated.  It is generally a bad idea to print the value
+     of `values' itself, since this may be very long.  Instead, examine
+     particular elements, like this:
+
+          ;; Refer to the most recent evaluation result.
+          (nth 0 values)
+               => (A 3 t)
+          ;; That put a new element on,
+          ;;   so all elements move back one.
+          (nth 1 values)
+               => (A 3 t)
+          ;; This gets the element that was next-to-most-recent
+          ;;   before this example.
+          (nth 3 values)
+               => 1
+
+\1f
+File: lispref.info,  Node: Forms,  Next: Quoting,  Prev: Eval,  Up: Evaluation
+
+Kinds of Forms
+==============
+
+A Lisp object that is intended to be evaluated is called a "form".  How
+XEmacs evaluates a form depends on its data type.  XEmacs has three
+different kinds of form that are evaluated differently: symbols, lists,
+and "all other types".  This section describes all three kinds,
+starting with "all other types" which are self-evaluating forms.
+
+* Menu:
+
+* 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 Indirection::    When a symbol appears as the car of a list,
+                             we find the real function via the symbol.
+* 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.
+
+\1f
+File: lispref.info,  Node: Self-Evaluating Forms,  Next: Symbol Forms,  Up: Forms
+
+Self-Evaluating Forms
+---------------------
+
+A "self-evaluating form" is any form that is not a list or symbol.
+Self-evaluating forms evaluate to themselves: the result of evaluation
+is the same object that was evaluated.  Thus, the number 25 evaluates to
+25, and the string `"foo"' evaluates to the string `"foo"'.  Likewise,
+evaluation of a vector does not cause evaluation of the elements of the
+vector--it returns the same vector with its contents unchanged.
+
+     '123               ; An object, shown without evaluation.
+          => 123
+     123                ; Evaluated as usual--result is the same.
+          => 123
+     (eval '123)        ; Evaluated "by hand"--result is the same.
+          => 123
+     (eval (eval '123)) ; Evaluating twice changes nothing.
+          => 123
+
+   It is common to write numbers, characters, strings, and even vectors
+in Lisp code, taking advantage of the fact that they self-evaluate.
+However, it is quite unusual to do this for types that lack a read
+syntax, because there's no way to write them textually.  It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program.  Here is an example:
+
+     ;; Build an expression containing a buffer object.
+     (setq buffer (list 'print (current-buffer)))
+          => (print #<buffer eval.texi>)
+     ;; Evaluate it.
+     (eval buffer)
+          -| #<buffer eval.texi>
+          => #<buffer eval.texi>
+
+\1f
+File: lispref.info,  Node: Symbol Forms,  Next: Classifying Lists,  Prev: Self-Evaluating Forms,  Up: Forms
+
+Symbol Forms
+------------
+
+When a symbol is evaluated, it is treated as a variable.  The result is
+the variable's value, if it has one.  If it has none (if its value cell
+is void), an error is signaled.  For more information on the use of
+variables, see *Note Variables::.
+
+   In the following example, we set the value of a symbol with `setq'.
+Then we evaluate the symbol, and get back the value that `setq' stored.
+
+     (setq a 123)
+          => 123
+     (eval 'a)
+          => 123
+     a
+          => 123
+
+   The symbols `nil' and `t' are treated specially, so that the value
+of `nil' is always `nil', and the value of `t' is always `t'; you
+cannot set or bind them to any other values.  Thus, these two symbols
+act like self-evaluating forms, even though `eval' treats them like any
+other symbol.
+
+\1f
+File: lispref.info,  Node: Classifying Lists,  Next: Function Indirection,  Prev: Symbol Forms,  Up: Forms
+
+Classification of List Forms
+----------------------------
+
+A form that is a nonempty list is either a function call, a macro call,
+or a special form, according to its first element.  These three kinds
+of forms are evaluated in different ways, described below.  The
+remaining list elements constitute the "arguments" for the function,
+macro, or special form.
+
+   The first step in evaluating a nonempty list is to examine its first
+element.  This element alone determines what kind of form the list is
+and how the rest of the list is to be processed.  The first element is
+_not_ evaluated, as it would be in some Lisp dialects such as Scheme.
+
+\1f
+File: lispref.info,  Node: Function Indirection,  Next: Function Forms,  Prev: Classifying Lists,  Up: Forms
+
+Symbol Function Indirection
+---------------------------
+
+If the first element of the list is a symbol then evaluation examines
+the symbol's function cell, and uses its contents instead of the
+original symbol.  If the contents are another symbol, this process,
+called "symbol function indirection", is repeated until it obtains a
+non-symbol.  *Note Function Names::, for more information about using a
+symbol as a name for a function stored in the function cell of the
+symbol.
+
+   One possible consequence of this process is an infinite loop, in the
+event that a symbol's function cell refers to the same symbol.  Or a
+symbol may have a void function cell, in which case the subroutine
+`symbol-function' signals a `void-function' error.  But if neither of
+these things happens, we eventually obtain a non-symbol, which ought to
+be a function or other suitable object.
+
+   More precisely, we should now have a Lisp function (a lambda
+expression), a byte-code function, a primitive function, a Lisp macro, a
+special form, or an autoload object.  Each of these types is a case
+described in one of the following sections.  If the object is not one of
+these types, the error `invalid-function' is signaled.
+
+   The following example illustrates the symbol indirection process.  We
+use `fset' to set the function cell of a symbol and `symbol-function'
+to get the function cell contents (*note Function Cells::).
+Specifically, we store the symbol `car' into the function cell of
+`first', and the symbol `first' into the function cell of `erste'.
+
+     ;; Build this function cell linkage:
+     ;;   -------------       -----        -------        -------
+     ;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
+     ;;   -------------       -----        -------        -------
+
+     (symbol-function 'car)
+          => #<subr car>
+     (fset 'first 'car)
+          => car
+     (fset 'erste 'first)
+          => first
+     (erste '(1 2 3))   ; Call the function referenced by `erste'.
+          => 1
+
+   By contrast, the following example calls a function without any
+symbol function indirection, because the first element is an anonymous
+Lisp function, not a symbol.
+
+     ((lambda (arg) (erste arg))
+      '(1 2 3))
+          => 1
+
+Executing the function itself evaluates its body; this does involve
+symbol function indirection when calling `erste'.
+
+   The built-in function `indirect-function' provides an easy way to
+perform symbol function indirection explicitly.
+
+ - Function: indirect-function object
+     This function returns the meaning of OBJECT as a function.  If
+     OBJECT is a symbol, then it finds OBJECT's function definition and
+     starts over with that value.  If OBJECT is not a symbol, then it
+     returns OBJECT itself.
+
+     Here is how you could define `indirect-function' in Lisp:
+
+          (defun indirect-function (function)
+            (if (symbolp function)
+                (indirect-function (symbol-function function))
+              function))
+
+\1f
+File: lispref.info,  Node: Function Forms,  Next: Macro Forms,  Prev: Function Indirection,  Up: Forms
+
+Evaluation of Function Forms
+----------------------------
+
+If the first element of a list being evaluated is a Lisp function
+object, byte-code object or primitive function object, then that list is
+a "function call".  For example, here is a call to the function `+':
+
+     (+ 1 x)
+
+   The first step in evaluating a function call is to evaluate the
+remaining elements of the list from left to right.  The results are the
+actual argument values, one value for each list element.  The next step
+is to call the function with this list of arguments, effectively using
+the function `apply' (*note Calling Functions::).  If the function is
+written in Lisp, the arguments are used to bind the argument variables
+of the function (*note Lambda Expressions::); then the forms in the
+function body are evaluated in order, and the value of the last body
+form becomes the value of the function call.
+
+\1f
+File: lispref.info,  Node: Macro Forms,  Next: Special Forms,  Prev: Function Forms,  Up: Forms
+
+Lisp Macro Evaluation
+---------------------
+
+If the first element of a list being evaluated is a macro object, then
+the list is a "macro call".  When a macro call is evaluated, the
+elements of the rest of the list are _not_ initially evaluated.
+Instead, these elements themselves are used as the arguments of the
+macro.  The macro definition computes a replacement form, called the
+"expansion" of the macro, to be evaluated in place of the original
+form.  The expansion may be any sort of form: a self-evaluating
+constant, a symbol, or a list.  If the expansion is itself a macro call,
+this process of expansion repeats until some other sort of form results.
+
+   Ordinary evaluation of a macro call finishes by evaluating the
+expansion.  However, the macro expansion is not necessarily evaluated
+right away, or at all, because other programs also expand macro calls,
+and they may or may not evaluate the expansions.
+
+   Normally, the argument expressions are not evaluated as part of
+computing the macro expansion, but instead appear as part of the
+expansion, so they are computed when the expansion is computed.
+
+   For example, given a macro defined as follows:
+
+     (defmacro cadr (x)
+       (list 'car (list 'cdr x)))
+
+an expression such as `(cadr (assq 'handler list))' is a macro call,
+and its expansion is:
+
+     (car (cdr (assq 'handler list)))
+
+Note that the argument `(assq 'handler list)' appears in the expansion.
+
+   *Note Macros::, for a complete description of XEmacs Lisp macros.
+
+\1f
+File: lispref.info,  Node: Special Forms,  Next: Autoloading,  Prev: Macro Forms,  Up: Forms
+
+Special Forms
+-------------
+
+A "special form" is a primitive function specially marked so that its
+arguments are not all evaluated.  Most special forms define control
+structures or perform variable bindings--things which functions cannot
+do.
+
+   Each special form has its own rules for which arguments are evaluated
+and which are used without evaluation.  Whether a particular argument is
+evaluated may depend on the results of evaluating other arguments.
+
+   Here is a list, in alphabetical order, of all of the special forms in
+XEmacs Lisp with a reference to where each is described.
+
+`and'
+     *note Combining Conditions::
+
+`catch'
+     *note Catch and Throw::
+
+`cond'
+     *note Conditionals::
+
+`condition-case'
+     *note Handling Errors::
+
+`defconst'
+     *note Defining Variables::
+
+`defmacro'
+     *note Defining Macros::
+
+`defun'
+     *note Defining Functions::
+
+`defvar'
+     *note Defining Variables::
+
+`function'
+     *note Anonymous Functions::
+
+`if'
+     *note Conditionals::
+
+`interactive'
+     *note Interactive Call::
+
+`let'
+`let*'
+     *note Local Variables::
+
+`or'
+     *note Combining Conditions::
+
+`prog1'
+`prog2'
+`progn'
+     *note Sequencing::
+
+`quote'
+     *note Quoting::
+
+`save-current-buffer'
+     *note Excursions::
+
+`save-excursion'
+     *note Excursions::
+
+`save-restriction'
+     *note Narrowing::
+
+`save-selected-window'
+     *note Excursions::
+
+`save-window-excursion'
+     *note Window Configurations::
+
+`setq'
+     *note Setting Variables::
+
+`setq-default'
+     *note Creating Buffer-Local::
+
+`unwind-protect'
+     *note Nonlocal Exits::
+
+`while'
+     *note Iteration::
+
+`with-output-to-temp-buffer'
+     *note Temporary Displays::
+
+     Common Lisp note: here are some comparisons of special forms in
+     XEmacs Lisp and Common Lisp.  `setq', `if', and `catch' are
+     special forms in both XEmacs Lisp and Common Lisp.  `defun' is a
+     special form in XEmacs Lisp, but a macro in Common Lisp.
+     `save-excursion' is a special form in XEmacs Lisp, but doesn't
+     exist in Common Lisp.  `throw' is a special form in Common Lisp
+     (because it must be able to throw multiple values), but it is a
+     function in XEmacs Lisp (which doesn't have multiple values).
+
+\1f
+File: lispref.info,  Node: Autoloading,  Prev: Special Forms,  Up: Forms
+
+Autoloading
+-----------
+
+The "autoload" feature allows you to call a function or macro whose
+function definition has not yet been loaded into XEmacs.  It specifies
+which file contains the definition.  When an autoload object appears as
+a symbol's function definition, calling that symbol as a function
+automatically loads the specified file; then it calls the real
+definition loaded from that file.  *Note Autoload::.
+
+\1f
+File: lispref.info,  Node: Quoting,  Prev: Forms,  Up: Evaluation
+
+Quoting
+=======
+
+The special form `quote' returns its single argument, as written,
+without evaluating it.  This provides a way to include constant symbols
+and lists, which are not self-evaluating objects, in a program.  (It is
+not necessary to quote self-evaluating objects such as numbers, strings,
+and vectors.)
+
+ - Special Form: quote object
+     This special form returns OBJECT, without evaluating it.
+
+   Because `quote' is used so often in programs, Lisp provides a
+convenient read syntax for it.  An apostrophe character (`'') followed
+by a Lisp object (in read syntax) expands to a list whose first element
+is `quote', and whose second element is the object.  Thus, the read
+syntax `'x' is an abbreviation for `(quote x)'.
+
+   Here are some examples of expressions that use `quote':
+
+     (quote (+ 1 2))
+          => (+ 1 2)
+     (quote foo)
+          => foo
+     'foo
+          => foo
+     ''foo
+          => (quote foo)
+     '(quote foo)
+          => (quote foo)
+     ['foo]
+          => [(quote foo)]
+
+   Other quoting constructs include `function' (*note Anonymous
+Functions::), which causes an anonymous lambda expression written in
+Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
+only part of a list, while computing and substituting other parts.
+
+\1f
+File: lispref.info,  Node: Control Structures,  Next: Variables,  Prev: Evaluation,  Up: Top
+
+Control Structures
+******************
+
+A Lisp program consists of expressions or "forms" (*note Forms::).  We
+control the order of execution of the forms by enclosing them in
+"control structures".  Control structures are special forms which
+control when, whether, or how many times to execute the forms they
+contain.
+
+   The simplest order of execution is sequential execution: first form
+A, then form B, and so on.  This is what happens when you write several
+forms in succession in the body of a function, or at top level in a
+file of Lisp code--the forms are executed in the order written.  We
+call this "textual order".  For example, if a function body consists of
+two forms A and B, evaluation of the function evaluates first A and
+then B, and the function's value is the value of B.
+
+   Explicit control structures make possible an order of execution other
+than sequential.
+
+   XEmacs Lisp provides several kinds of control structure, including
+other varieties of sequencing, conditionals, iteration, and (controlled)
+jumps--all discussed below.  The built-in control structures are
+special forms since their subforms are not necessarily evaluated or not
+evaluated sequentially.  You can use macros to define your own control
+structure constructs (*note Macros::).
+
+* Menu:
+
+* Sequencing::             Evaluation in textual order.
+* Conditionals::           `if', `cond'.
+* Combining Conditions::   `and', `or', `not'.
+* Iteration::              `while' loops.
+* Nonlocal Exits::         Jumping out of a sequence.
+
+\1f
+File: lispref.info,  Node: Sequencing,  Next: Conditionals,  Up: Control Structures
+
+Sequencing
+==========
+
+Evaluating forms in the order they appear is the most common way
+control passes from one form to another.  In some contexts, such as in a
+function body, this happens automatically.  Elsewhere you must use a
+control structure construct to do this: `progn', the simplest control
+construct of Lisp.
+
+   A `progn' special form looks like this:
+
+     (progn A B C ...)
+
+and it says to execute the forms A, B, C and so on, in that order.
+These forms are called the body of the `progn' form.  The value of the
+last form in the body becomes the value of the entire `progn'.
+
+   In the early days of Lisp, `progn' was the only way to execute two
+or more forms in succession and use the value of the last of them.  But
+programmers found they often needed to use a `progn' in the body of a
+function, where (at that time) only one form was allowed.  So the body
+of a function was made into an "implicit `progn'": several forms are
+allowed just as in the body of an actual `progn'.  Many other control
+structures likewise contain an implicit `progn'.  As a result, `progn'
+is not used as often as it used to be.  It is needed now most often
+inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
+
+ - Special Form: progn forms...
+     This special form evaluates all of the FORMS, in textual order,
+     returning the result of the final form.
+
+          (progn (print "The first form")
+                 (print "The second form")
+                 (print "The third form"))
+               -| "The first form"
+               -| "The second form"
+               -| "The third form"
+          => "The third form"
+
+   Two other control constructs likewise evaluate a series of forms but
+return a different value:
+
+ - Special Form: prog1 form1 forms...
+     This special form evaluates FORM1 and all of the FORMS, in textual
+     order, returning the result of FORM1.
+
+          (prog1 (print "The first form")
+                 (print "The second form")
+                 (print "The third form"))
+               -| "The first form"
+               -| "The second form"
+               -| "The third form"
+          => "The first form"
+
+     Here is a way to remove the first element from a list in the
+     variable `x', then return the value of that former element:
+
+          (prog1 (car x) (setq x (cdr x)))
+
+ - Special Form: prog2 form1 form2 forms...
+     This special form evaluates FORM1, FORM2, and all of the following
+     FORMS, in textual order, returning the result of FORM2.
+
+          (prog2 (print "The first form")
+                 (print "The second form")
+                 (print "The third form"))
+               -| "The first form"
+               -| "The second form"
+               -| "The third form"
+          => "The second form"
+
+\1f
+File: lispref.info,  Node: Conditionals,  Next: Combining Conditions,  Prev: Sequencing,  Up: Control Structures
+
+Conditionals
+============
+
+Conditional control structures choose among alternatives.  XEmacs Lisp
+has two conditional forms: `if', which is much the same as in other
+languages, and `cond', which is a generalized case statement.
+
+ - Special Form: if condition then-form else-forms...
+     `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
+     value of CONDITION.  If the evaluated CONDITION is non-`nil',
+     THEN-FORM is evaluated and the result returned.  Otherwise, the
+     ELSE-FORMS are evaluated in textual order, and the value of the
+     last one is returned.  (The ELSE part of `if' is an example of an
+     implicit `progn'.  *Note Sequencing::.)
+
+     If CONDITION has the value `nil', and no ELSE-FORMS are given,
+     `if' returns `nil'.
+
+     `if' is a special form because the branch that is not selected is
+     never evaluated--it is ignored.  Thus, in the example below,
+     `true' is not printed because `print' is never called.
+
+          (if nil
+              (print 'true)
+            'very-false)
+          => very-false
+
+ - Special Form: cond clause...
+     `cond' chooses among an arbitrary number of alternatives.  Each
+     CLAUSE in the `cond' must be a list.  The CAR of this list is the
+     CONDITION; the remaining elements, if any, the BODY-FORMS.  Thus,
+     a clause looks like this:
+
+          (CONDITION BODY-FORMS...)
+
+     `cond' tries the clauses in textual order, by evaluating the
+     CONDITION of each clause.  If the value of CONDITION is non-`nil',
+     the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
+     the value of the last of BODY-FORMS becomes the value of the
+     `cond'.  The remaining clauses are ignored.
+
+     If the value of CONDITION is `nil', the clause "fails", so the
+     `cond' moves on to the following clause, trying its CONDITION.
+
+     If every CONDITION evaluates to `nil', so that every clause fails,
+     `cond' returns `nil'.
+
+     A clause may also look like this:
+
+          (CONDITION)
+
+     Then, if CONDITION is non-`nil' when tested, the value of
+     CONDITION becomes the value of the `cond' form.
+
+     The following example has four clauses, which test for the cases
+     where the value of `x' is a number, string, buffer and symbol,
+     respectively:
+
+          (cond ((numberp x) x)
+                ((stringp x) x)
+                ((bufferp x)
+                 (setq temporary-hack x) ; multiple body-forms
+                 (buffer-name x))        ; in one clause
+                ((symbolp x) (symbol-value x)))
+
+     Often we want to execute the last clause whenever none of the
+     previous clauses was successful.  To do this, we use `t' as the
+     CONDITION of the last clause, like this: `(t BODY-FORMS)'.  The
+     form `t' evaluates to `t', which is never `nil', so this clause
+     never fails, provided the `cond' gets to it at all.
+
+     For example,
+
+          (cond ((eq a 'hack) 'foo)
+                (t "default"))
+          => "default"
+
+     This expression is a `cond' which returns `foo' if the value of
+     `a' is 1, and returns the string `"default"' otherwise.
+
+   Any conditional construct can be expressed with `cond' or with `if'.
+Therefore, the choice between them is a matter of style.  For example:
+
+     (if A B C)
+     ==
+     (cond (A B) (t C))
+
+\1f
+File: lispref.info,  Node: Combining Conditions,  Next: Iteration,  Prev: Conditionals,  Up: Control Structures
+
+Constructs for Combining Conditions
+===================================
+
+This section describes three constructs that are often used together
+with `if' and `cond' to express complicated conditions.  The constructs
+`and' and `or' can also be used individually as kinds of multiple
+conditional constructs.
+
+ - Function: not condition
+     This function tests for the falsehood of CONDITION.  It returns
+     `t' if CONDITION is `nil', and `nil' otherwise.  The function
+     `not' is identical to `null', and we recommend using the name
+     `null' if you are testing for an empty list.
+
+ - Special Form: and conditions...
+     The `and' special form tests whether all the CONDITIONS are true.
+     It works by evaluating the CONDITIONS one by one in the order
+     written.
+
+     If any of the CONDITIONS evaluates to `nil', then the result of
+     the `and' must be `nil' regardless of the remaining CONDITIONS; so
+     `and' returns right away, ignoring the remaining CONDITIONS.
+
+     If all the CONDITIONS turn out non-`nil', then the value of the
+     last of them becomes the value of the `and' form.
+
+     Here is an example.  The first condition returns the integer 1,
+     which is not `nil'.  Similarly, the second condition returns the
+     integer 2, which is not `nil'.  The third condition is `nil', so
+     the remaining condition is never evaluated.
+
+          (and (print 1) (print 2) nil (print 3))
+               -| 1
+               -| 2
+          => nil
+
+     Here is a more realistic example of using `and':
+
+          (if (and (consp foo) (eq (car foo) 'x))
+              (message "foo is a list starting with x"))
+
+     Note that `(car foo)' is not executed if `(consp foo)' returns
+     `nil', thus avoiding an error.
+
+     `and' can be expressed in terms of either `if' or `cond'.  For
+     example:
+
+          (and ARG1 ARG2 ARG3)
+          ==
+          (if ARG1 (if ARG2 ARG3))
+          ==
+          (cond (ARG1 (cond (ARG2 ARG3))))
+
+ - Special Form: or conditions...
+     The `or' special form tests whether at least one of the CONDITIONS
+     is true.  It works by evaluating all the CONDITIONS one by one in
+     the order written.
+
+     If any of the CONDITIONS evaluates to a non-`nil' value, then the
+     result of the `or' must be non-`nil'; so `or' returns right away,
+     ignoring the remaining CONDITIONS.  The value it returns is the
+     non-`nil' value of the condition just evaluated.
+
+     If all the CONDITIONS turn out `nil', then the `or' expression
+     returns `nil'.
+
+     For example, this expression tests whether `x' is either 0 or
+     `nil':
+
+          (or (eq x nil) (eq x 0))
+
+     Like the `and' construct, `or' can be written in terms of `cond'.
+     For example:
+
+          (or ARG1 ARG2 ARG3)
+          ==
+          (cond (ARG1)
+                (ARG2)
+                (ARG3))
+
+     You could almost write `or' in terms of `if', but not quite:
+
+          (if ARG1 ARG1
+            (if ARG2 ARG2
+              ARG3))
+
+     This is not completely equivalent because it can evaluate ARG1 or
+     ARG2 twice.  By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
+     any argument more than once.
+
+\1f
+File: lispref.info,  Node: Iteration,  Next: Nonlocal Exits,  Prev: Combining Conditions,  Up: Control Structures
+
+Iteration
+=========
+
+Iteration means executing part of a program repetitively.  For example,
+you might want to repeat some computation once for each element of a
+list, or once for each integer from 0 to N.  You can do this in XEmacs
+Lisp with the special form `while':
+
+ - Special Form: while condition forms...
+     `while' first evaluates CONDITION.  If the result is non-`nil', it
+     evaluates FORMS in textual order.  Then it reevaluates CONDITION,
+     and if the result is non-`nil', it evaluates FORMS again.  This
+     process repeats until CONDITION evaluates to `nil'.
+
+     There is no limit on the number of iterations that may occur.  The
+     loop will continue until either CONDITION evaluates to `nil' or
+     until an error or `throw' jumps out of it (*note Nonlocal Exits::).
+
+     The value of a `while' form is always `nil'.
+
+          (setq num 0)
+               => 0
+          (while (< num 4)
+            (princ (format "Iteration %d." num))
+            (setq num (1+ num)))
+               -| Iteration 0.
+               -| Iteration 1.
+               -| Iteration 2.
+               -| Iteration 3.
+               => nil
+
+     If you would like to execute something on each iteration before the
+     end-test, put it together with the end-test in a `progn' as the
+     first argument of `while', as shown here:
+
+          (while (progn
+                   (forward-line 1)
+                   (not (looking-at "^$"))))
+
+     This moves forward one line and continues moving by lines until it
+     reaches an empty.  It is unusual in that the `while' has no body,
+     just the end test (which also does the real work of moving point).
+
+\1f
+File: lispref.info,  Node: Nonlocal Exits,  Prev: Iteration,  Up: Control Structures
+
+Nonlocal Exits
+==============
+
+A "nonlocal exit" is a transfer of control from one point in a program
+to another remote point.  Nonlocal exits can occur in XEmacs Lisp as a
+result of errors; you can also use them under explicit control.
+Nonlocal exits unbind all variable bindings made by the constructs being
+exited.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Catch and Throw,  Next: Examples of Catch,  Up: Nonlocal Exits
+
+Explicit Nonlocal Exits: `catch' and `throw'
+--------------------------------------------
+
+Most control constructs affect only the flow of control within the
+construct itself.  The function `throw' is the exception to this rule
+of normal program execution: it performs a nonlocal exit on request.
+(There are other exceptions, but they are for error handling only.)
+`throw' is used inside a `catch', and jumps back to that `catch'.  For
+example:
+
+     (catch 'foo
+       (progn
+         ...
+         (throw 'foo t)
+         ...))
+
+The `throw' transfers control straight back to the corresponding
+`catch', which returns immediately.  The code following the `throw' is
+not executed.  The second argument of `throw' is used as the return
+value of the `catch'.
+
+   The `throw' and the `catch' are matched through the first argument:
+`throw' searches for a `catch' whose first argument is `eq' to the one
+specified.  Thus, in the above example, the `throw' specifies `foo',
+and the `catch' specifies the same symbol, so that `catch' is
+applicable.  If there is more than one applicable `catch', the
+innermost one takes precedence.
+
+   Executing `throw' exits all Lisp constructs up to the matching
+`catch', including function calls.  When binding constructs such as
+`let' or function calls are exited in this way, the bindings are
+unbound, just as they are when these constructs exit normally (*note
+Local Variables::).  Likewise, `throw' restores the buffer and position
+saved by `save-excursion' (*note Excursions::), and the narrowing
+status saved by `save-restriction' and the window selection saved by
+`save-window-excursion' (*note Window Configurations::).  It also runs
+any cleanups established with the `unwind-protect' special form when it
+exits that form (*note Cleanups::).
+
+   The `throw' need not appear lexically within the `catch' that it
+jumps to.  It can equally well be called from another function called
+within the `catch'.  As long as the `throw' takes place chronologically
+after entry to the `catch', and chronologically before exit from it, it
+has access to that `catch'.  This is why `throw' can be used in
+commands such as `exit-recursive-edit' that throw back to the editor
+command loop (*note Recursive Editing::).
+
+     Common Lisp note: Most other versions of Lisp, including Common
+     Lisp, have several ways of transferring control nonsequentially:
+     `return', `return-from', and `go', for example.  XEmacs Lisp has
+     only `throw'.
+
+ - Special Form: catch tag body...
+     `catch' establishes a return point for the `throw' function.  The
+     return point is distinguished from other such return points by TAG,
+     which may be any Lisp object.  The argument TAG is evaluated
+     normally before the return point is established.
+
+     With the return point in effect, `catch' evaluates the forms of the
+     BODY in textual order.  If the forms execute normally, without
+     error or nonlocal exit, the value of the last body form is
+     returned from the `catch'.
+
+     If a `throw' is done within BODY specifying the same value TAG,
+     the `catch' exits immediately; the value it returns is whatever
+     was specified as the second argument of `throw'.
+
+ - Function: throw tag value
+     The purpose of `throw' is to return from a return point previously
+     established with `catch'.  The argument TAG is used to choose
+     among the various existing return points; it must be `eq' to the
+     value specified in the `catch'.  If multiple return points match
+     TAG, the innermost one is used.
+
+     The argument VALUE is used as the value to return from that
+     `catch'.
+
+     If no return point is in effect with tag TAG, then a `no-catch'
+     error is signaled with data `(TAG VALUE)'.
+
+\1f
+File: lispref.info,  Node: Examples of Catch,  Next: Errors,  Prev: Catch and Throw,  Up: Nonlocal Exits
+
+Examples of `catch' and `throw'
+-------------------------------
+
+One way to use `catch' and `throw' is to exit from a doubly nested
+loop.  (In most languages, this would be done with a "go to".)  Here we
+compute `(foo I J)' for I and J varying from 0 to 9:
+
+     (defun search-foo ()
+       (catch 'loop
+         (let ((i 0))
+           (while (< i 10)
+             (let ((j 0))
+               (while (< j 10)
+                 (if (foo i j)
+                     (throw 'loop (list i j)))
+                 (setq j (1+ j))))
+             (setq i (1+ i))))))
+
+If `foo' ever returns non-`nil', we stop immediately and return a list
+of I and J.  If `foo' always returns `nil', the `catch' returns
+normally, and the value is `nil', since that is the result of the
+`while'.
+
+   Here are two tricky examples, slightly different, showing two return
+points at once.  First, two return points with the same tag, `hack':
+
+     (defun catch2 (tag)
+       (catch tag
+         (throw 'hack 'yes)))
+     => catch2
+     
+     (catch 'hack
+       (print (catch2 'hack))
+       'no)
+     -| yes
+     => no
+
+Since both return points have tags that match the `throw', it goes to
+the inner one, the one established in `catch2'.  Therefore, `catch2'
+returns normally with value `yes', and this value is printed.  Finally
+the second body form in the outer `catch', which is `'no', is evaluated
+and returned from the outer `catch'.
+
+   Now let's change the argument given to `catch2':
+
+     (defun catch2 (tag)
+       (catch tag
+         (throw 'hack 'yes)))
+     => catch2
+     
+     (catch 'hack
+       (print (catch2 'quux))
+       'no)
+     => yes
+
+We still have two return points, but this time only the outer one has
+the tag `hack'; the inner one has the tag `quux' instead.  Therefore,
+`throw' makes the outer `catch' return the value `yes'.  The function
+`print' is never called, and the body-form `'no' is never evaluated.
+
+\1f
+File: lispref.info,  Node: Errors,  Next: Cleanups,  Prev: Examples of Catch,  Up: Nonlocal Exits
+
+Errors
+------
+
+When XEmacs Lisp attempts to evaluate a form that, for some reason,
+cannot be evaluated, it "signals" an "error".
+
+   When an error is signaled, XEmacs's default reaction is to print an
+error message and terminate execution of the current command.  This is
+the right thing to do in most cases, such as if you type `C-f' at the
+end of the buffer.
+
+   In complicated programs, simple termination may not be what you want.
+For example, the program may have made temporary changes in data
+structures, or created temporary buffers that should be deleted before
+the program is finished.  In such cases, you would use `unwind-protect'
+to establish "cleanup expressions" to be evaluated in case of error.
+(*Note Cleanups::.)  Occasionally, you may wish the program to continue
+execution despite an error in a subroutine.  In these cases, you would
+use `condition-case' to establish "error handlers" to recover control
+in case of error.
+
+   Resist the temptation to use error handling to transfer control from
+one part of the program to another; use `catch' and `throw' instead.
+*Note Catch and Throw::.
+
+* Menu:

 
 

-                         Version 2, June 1991
+* 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.

 
 

-     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-     675 Mass Ave, Cambridge, MA 02139, USA
+\1f
+File: lispref.info,  Node: Signaling Errors,  Next: Processing of Errors,  Up: Errors
+
+How to Signal an Error
+......................
+
+Most errors are signaled "automatically" within Lisp primitives which
+you call for other purposes, such as if you try to take the CAR of an
+integer or move forward a character at the end of the buffer; you can
+also signal errors explicitly with the functions `error', `signal', and
+others.
+
+   Quitting, which happens when the user types `C-g', is not considered
+an error, but it is handled almost like an error.  *Note Quitting::.
+
+   XEmacs has a rich hierarchy of error symbols predefined via
+`deferror'.
+
+     error
+       syntax-error
+         invalid-read-syntax
+         list-formation-error
+           malformed-list
+             malformed-property-list
+           circular-list
+             circular-property-list

      
      

-     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
+       invalid-argument
+         wrong-type-argument
+         args-out-of-range
+         wrong-number-of-arguments
+         invalid-function
+         no-catch

      
      

-     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.
+       invalid-state
+         void-function
+         cyclic-function-indirection
+         void-variable
+         cyclic-variable-indirection

      
      

-     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.
+       invalid-operation
+         invalid-change
+           setting-constant
+         editing-error
+           beginning-of-buffer
+           end-of-buffer
+           buffer-read-only
+         io-error
+           end-of-file
+         arith-error
+           range-error
+           domain-error
+           singularity-error
+           overflow-error
+           underflow-error
+
+   The five most common errors you will probably use or base your new
+errors off of are `syntax-error', `invalid-argument', `invalid-state',
+`invalid-operation', and `invalid-change'.  Note the semantic
+differences:
+
+   * `syntax-error' is for errors in complex structures: parsed strings,
+     lists, and the like.
+
+   * `invalid-argument' is for errors in a simple value.  Typically, the
+     entire value, not just one part of it, is wrong.
+
+   * `invalid-state' means that some settings have been changed in such
+     a way that their current state is unallowable.  More and more,
+     code is being written more carefully, and catches the error when
+     the settings are being changed, rather than afterwards.  This
+     leads us to the next error:
+
+   * `invalid-change' means that an attempt is being made to change some
+     settings into an invalid state.  `invalid-change' is a type of
+     `invalid-operation'.
+
+   * `invalid-operation' refers to all cases where code is trying to do
+     something that's disallowed.  This includes file errors, buffer
+     errors (e.g. running off the end of a buffer), `invalid-change' as
+     just mentioned, and arithmetic errors.
+
+ - Function: error datum &rest args
+     This function signals a non-continuable error.
+
+     DATUM should normally be an error symbol, i.e. a symbol defined
+     using `define-error'.  ARGS will be made into a list, and DATUM
+     and ARGS passed as the two arguments to `signal', the most basic
+     error handling function.
+
+     This error is not continuable: you cannot continue execution after
+     the error using the debugger `r' command.  See also `cerror'.
+
+     The correct semantics of ARGS varies from error to error, but for
+     most errors that need to be generated in Lisp code, the first
+     argument should be a string describing the *context* of the error
+     (i.e. the exact operation being performed and what went wrong),
+     and the remaining arguments or \"frobs\" (most often, there is
+     one) specify the offending object(s) and/or provide additional
+     details such as the exact error when a file error occurred, e.g.:
+
+        * the buffer in which an editing error occurred.
+
+        * an invalid value that was encountered. (In such cases, the
+          string should describe the purpose or \"semantics\" of the
+          value [e.g. if the value is an argument to a function, the
+          name of the argument; if the value is the value corresponding
+          to a keyword, the name of the keyword; if the value is
+          supposed to be a list length, say this and say what the
+          purpose of the list is; etc.] as well as specifying why the
+          value is invalid, if that's not self-evident.)
+
+        * the file in which an error occurred. (In such cases, there
+          should be a second frob, probably a string, specifying the
+          exact error that occurred.  This does not occur in the string
+          that precedes the first frob, because that frob describes the
+          exact operation that was happening.
+
+     For historical compatibility, DATUM can also be a string.  In this
+     case, DATUM and ARGS are passed together as the arguments to
+     `format', and then an error is signalled using the error symbol
+     `error' and formatted string.  Although this usage of `error' is
+     very common, it is deprecated because it totally defeats the
+     purpose of having structured errors.  There is now a rich set of
+     defined errors to use.
+
+     See also `cerror', `signal', and `signal-error'."
+
+     These examples show typical uses of `error':
+
+          (error 'syntax-error
+                 "Dialog descriptor must supply at least one button"
+               descriptor)
+          
+          (error "You have committed an error.
+                  Try something else.")
+               error--> You have committed an error.
+                  Try something else.
+          
+          (error "You have committed %d errors." 10)
+               error--> You have committed 10 errors.
+
+     If you want to use your own string as an error message verbatim,
+     don't just write `(error STRING)'.  If STRING contains `%', it
+     will be interpreted as a format specifier, with undesirable
+     results.  Instead, use `(error "%s" STRING)'.
+
+ - Function: cerror datum &rest args
+     This function behaves like `error', except that the error it
+     signals is continuable.  That means that debugger commands `c' and
+     `r' can resume execution.
+
+ - Function: signal error-symbol data
+     This function signals a continuable error named by ERROR-SYMBOL.
+     The argument DATA is a list of additional Lisp objects relevant to
+     the circumstances of the error.
+
+     The argument ERROR-SYMBOL must be an "error symbol"--a symbol
+     bearing a property `error-conditions' whose value is a list of
+     condition names.  This is how XEmacs Lisp classifies different
+     sorts of errors.
+
+     The number and significance of the objects in DATA depends on
+     ERROR-SYMBOL.  For example, with a `wrong-type-argument' error,
+     there are two objects in the list: a predicate that describes the
+     type that was expected, and the object that failed to fit that
+     type.  *Note Error Symbols::, for a description of error symbols.
+
+     Both ERROR-SYMBOL and DATA are available to any error handlers
+     that handle the error: `condition-case' binds a local variable to
+     a list of the form `(ERROR-SYMBOL .  DATA)' (*note Handling
+     Errors::).  If the error is not handled, these two values are used
+     in printing the error message.
+
+     The function `signal' can return, if the debugger is invoked and
+     the user invokes the "return from signal" option.  If you want the
+     error not to be continuable, use `signal-error' instead.  Note that
+     in FSF Emacs `signal' never returns.
+
+          (signal 'wrong-number-of-arguments '(x y))
+               error--> Wrong number of arguments: x, y
+          
+          (signal 'no-such-error '("My unknown error condition"))
+               error--> Peculiar error (no-such-error "My unknown error condition")
+
+ - Function: signal-error error-symbol data
+     This function behaves like `signal', except that the error it
+     signals is not continuable.
+
+ - Macro: check-argument-type predicate argument
+     This macro checks that ARGUMENT satisfies PREDICATE.  If that is
+     not the case, it signals a continuable `wrong-type-argument' error
+     until the returned value satisfies PREDICATE, and assigns the
+     returned value to ARGUMENT.  In other words, execution of the
+     program will not continue until PREDICATE is met.
+
+     ARGUMENT is not evaluated, and should be a symbol.  PREDICATE is
+     evaluated, and should name a function.
+
+     As shown in the following example, `check-argument-type' is useful
+     in low-level code that attempts to ensure the sanity of its data
+     before proceeding.
+
+          (defun cache-object-internal (object wlist)
+            ;; Before doing anything, make sure that WLIST is indeed
+            ;; a weak list, which is what we expect.
+            (check-argument-type 'weak-list-p wlist)
+            ...)
+
+\1f
+File: lispref.info,  Node: Processing of Errors,  Next: Handling Errors,  Prev: Signaling Errors,  Up: Errors
+
+How XEmacs Processes Errors
+...........................
+
+When an error is signaled, `signal' searches for an active "handler"
+for the error.  A handler is a sequence of Lisp expressions designated
+to be executed if an error happens in part of the Lisp program.  If the
+error has an applicable handler, the handler is executed, and control
+resumes following the handler.  The handler executes in the environment
+of the `condition-case' that established it; all functions called
+within that `condition-case' have already been exited, and the handler
+cannot return to them.
+
+   If there is no applicable handler for the error, the current command
+is terminated and control returns to the editor command loop, because
+the command loop has an implicit handler for all kinds of errors.  The
+command loop's handler uses the error symbol and associated data to
+print an error message.
+
+   Errors in command loop are processed using the `command-error'
+function, which takes care of some necessary cleanup, and prints a
+formatted error message to the echo area.  The functions that do the
+formatting are explained below.
+
+ - Function: display-error error-object stream
+     This function displays ERROR-OBJECT on STREAM.  ERROR-OBJECT is a
+     cons of error type, a symbol, and error arguments, a list.  If the
+     error type symbol of one of its error condition superclasses has a
+     `display-error' property, that function is invoked for printing
+     the actual error message.  Otherwise, the error is printed as
+     `Error: arg1, arg2, ...'.
+
+ - Function: error-message-string error-object
+     This function converts ERROR-OBJECT to an error message string,
+     and returns it.  The message is equivalent to the one that would be
+     printed by `display-error', except that it is conveniently returned
+     in string form.
+
+   An error that has no explicit handler may call the Lisp debugger.
+The debugger is enabled if the variable `debug-on-error' (*note Error
+Debugging::) is non-`nil'.  Unlike error handlers, the debugger runs in
+the environment of the error, so that you can examine values of
+variables precisely as they were at the time of the error.
+
+\1f
+File: lispref.info,  Node: Handling Errors,  Next: Error Symbols,  Prev: Processing of Errors,  Up: Errors
+
+Writing Code to Handle Errors
+.............................
+
+The usual effect of signaling an error is to terminate the command that
+is running and return immediately to the XEmacs editor command loop.
+You can arrange to trap errors occurring in a part of your program by
+establishing an error handler, with the special form `condition-case'.
+A simple example looks like this:
+
+     (condition-case nil
+         (delete-file filename)
+       (error nil))
+
+This deletes the file named FILENAME, catching any error and returning
+`nil' if an error occurs.
+
+   The second argument of `condition-case' is called the "protected
+form".  (In the example above, the protected form is a call to
+`delete-file'.)  The error handlers go into effect when this form
+begins execution and are deactivated when this form returns.  They
+remain in effect for all the intervening time.  In particular, they are
+in effect during the execution of functions called by this form, in
+their subroutines, and so on.  This is a good thing, since, strictly
+speaking, errors can be signaled only by Lisp primitives (including
+`signal' and `error') called by the protected form, not by the
+protected form itself.
+
+   The arguments after the protected form are handlers.  Each handler
+lists one or more "condition names" (which are symbols) to specify
+which errors it will handle.  The error symbol specified when an error
+is signaled also defines a list of condition names.  A handler applies
+to an error if they have any condition names in common.  In the example
+above, there is one handler, and it specifies one condition name,
+`error', which covers all errors.
+
+   The search for an applicable handler checks all the established
+handlers starting with the most recently established one.  Thus, if two
+nested `condition-case' forms offer to handle the same error, the inner
+of the two will actually handle it.
+
+   When an error is handled, control returns to the handler.  Before
+this happens, XEmacs unbinds all variable bindings made by binding
+constructs that are being exited and executes the cleanups of all
+`unwind-protect' forms that are exited.  Once control arrives at the
+handler, the body of the handler is executed.
+
+   After execution of the handler body, execution continues by returning
+from the `condition-case' form.  Because the protected form is exited
+completely before execution of the handler, the handler cannot resume
+execution at the point of the error, nor can it examine variable
+bindings that were made within the protected form.  All it can do is
+clean up and proceed.
+
+   `condition-case' is often used to trap errors that are predictable,
+such as failure to open a file in a call to `insert-file-contents'.  It
+is also used to trap errors that are totally unpredictable, such as
+when the program evaluates an expression read from the user.
+
+   Even when an error is handled, the debugger may still be called if
+the variable `debug-on-signal' (*note Error Debugging::) is non-`nil'.
+Note that this may yield unpredictable results with code that traps
+expected errors as normal part of its operation.  Do not set
+`debug-on-signal' unless you know what you are doing.
+
+   Error signaling and handling have some resemblance to `throw' and
+`catch', but they are entirely separate facilities.  An error cannot be
+caught by a `catch', and a `throw' cannot be handled by an error
+handler (though using `throw' when there is no suitable `catch' signals
+an error that can be handled).
+
+ - Special Form: condition-case var protected-form handlers...
+     This special form establishes the error handlers HANDLERS around
+     the execution of PROTECTED-FORM.  If PROTECTED-FORM executes
+     without error, the value it returns becomes the value of the
+     `condition-case' form; in this case, the `condition-case' has no
+     effect.  The `condition-case' form makes a difference when an
+     error occurs during PROTECTED-FORM.
+
+     Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
+     Here CONDITIONS is an error condition name to be handled, or a
+     list of condition names; BODY is one or more Lisp expressions to
+     be executed when this handler handles an error.  Here are examples
+     of handlers:
+
+          (error nil)
+          
+          (arith-error (message "Division by zero"))
+          
+          ((arith-error file-error)
+           (message
+            "Either division by zero or failure to open a file"))
+
+     Each error that occurs has an "error symbol" that describes what
+     kind of error it is.  The `error-conditions' property of this
+     symbol is a list of condition names (*note Error Symbols::).  Emacs
+     searches all the active `condition-case' forms for a handler that
+     specifies one or more of these condition names; the innermost
+     matching `condition-case' handles the error.  Within this
+     `condition-case', the first applicable handler handles the error.
+
+     After executing the body of the handler, the `condition-case'
+     returns normally, using the value of the last form in the handler
+     body as the overall value.
+
+     The argument VAR is a variable.  `condition-case' does not bind
+     this variable when executing the PROTECTED-FORM, only when it
+     handles an error.  At that time, it binds VAR locally to a list of
+     the form `(ERROR-SYMBOL . DATA)', giving the particulars of the
+     error.  The handler can refer to this list to decide what to do.
+     For example, if the error is for failure opening a file, the file
+     name is the second element of DATA--the third element of VAR.
+
+     If VAR is `nil', that means no variable is bound.  Then the error
+     symbol and associated data are not available to the handler.
+
+   Here is an example of using `condition-case' to handle the error
+that results from dividing by zero.  The handler prints out a warning
+message and returns a very large number.
+
+     (defun safe-divide (dividend divisor)
+       (condition-case err
+           ;; Protected form.
+           (/ dividend divisor)
+         ;; The handler.
+         (arith-error                        ; Condition.
+          (princ (format "Arithmetic error: %s" err))
+          1000000)))
+     => safe-divide

      
      

-     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.
+     (safe-divide 5 0)
+          -| Arithmetic error: (arith-error)
+     => 1000000
+
+The handler specifies condition name `arith-error' so that it will
+handle only division-by-zero errors.  Other kinds of errors will not be
+handled, at least not by this `condition-case'.  Thus,
+
+     (safe-divide nil 3)
+          error--> Wrong type argument: integer-or-marker-p, nil
+
+   Here is a `condition-case' that catches all kinds of errors,
+including those signaled with `error':
+
+     (setq baz 34)
+          => 34

      
      

-     SIGNATURE OF TY COON, 1 April 1989
-     Ty Coon, President of Vice
+     (condition-case err
+         (if (eq baz 35)
+             t
+           ;; This is a call to the function `error'.
+           (error "Rats!  The variable %s was %s, not 35" 'baz baz))
+       ;; This is the handler; it is not a form.
+       (error (princ (format "The error was: %s" err))
+              2))
+     -| The error was: (error "Rats!  The variable baz was 34, not 35")
+     => 2
+
+\1f
+File: lispref.info,  Node: Error Symbols,  Prev: Handling Errors,  Up: Errors
+
+Error Symbols and Condition Names
+.................................
+
+When you signal an error, you specify an "error symbol" to specify the
+kind of error you have in mind.  Each error has one and only one error
+symbol to categorize it.  This is the finest classification of errors
+defined by the XEmacs Lisp language.
+
+   These narrow classifications are grouped into a hierarchy of wider
+classes called "error conditions", identified by "condition names".
+The narrowest such classes belong to the error symbols themselves: each
+error symbol is also a condition name.  There are also condition names
+for more extensive classes, up to the condition name `error' which
+takes in all kinds of errors.  Thus, each error has one or more
+condition names: `error', the error symbol if that is distinct from
+`error', and perhaps some intermediate classifications.
+
+   In other words, each error condition "inherits" from another error
+condition, with `error' sitting at the top of the inheritance hierarchy.
+
+ - Function: define-error error-symbol error-message &optional
+          inherits-from
+     This function defines a new error, denoted by ERROR-SYMBOL.
+     ERROR-MESSAGE is an informative message explaining the error, and
+     will be printed out when an unhandled error occurs.  ERROR-SYMBOL
+     is a sub-error of INHERITS-FROM (which defaults to `error').
+
+     `define-error' internally works by putting on ERROR-SYMBOL an
+     `error-message' property whose value is ERROR-MESSAGE, and an
+     `error-conditions' property that is a list of ERROR-SYMBOL
+     followed by each of its super-errors, up to and including `error'.
+     You will sometimes see code that sets this up directly rather than
+     calling `define-error', but you should _not_ do this yourself,
+     unless you wish to maintain compatibility with FSF Emacs, which
+     does not provide `define-error'.
+
+   Here is how we define a new error symbol, `new-error', that belongs
+to a range of errors called `my-own-errors':
+
+     (define-error 'my-own-errors "A whole range of errors" 'error)
+     (define-error 'new-error "A new error" 'my-own-errors)
+
+`new-error' has three condition names: `new-error', the narrowest
+classification; `my-own-errors', which we imagine is a wider
+classification; and `error', which is the widest of all.
+
+   Note that it is not legal to try to define an error unless its
+super-error is also defined.  For instance, attempting to define
+`new-error' before `my-own-errors' are defined will signal an error.
+
+   The error string should start with a capital letter but it should
+not end with a period.  This is for consistency with the rest of Emacs.
+
+   Naturally, XEmacs will never signal `new-error' on its own; only an
+explicit call to `signal' (*note Signaling Errors::) in your code can
+do this:
+
+     (signal 'new-error '(x y))
+          error--> A new error: x, y
+
+   This error can be handled through any of the three condition names.
+This example handles `new-error' and any other errors in the class
+`my-own-errors':
+
+     (condition-case foo
+         (bar nil t)
+       (my-own-errors nil))
+
+   The significant way that errors are classified is by their condition
+names--the names used to match errors with handlers.  An error symbol
+serves only as a convenient way to specify the intended error message
+and list of condition names.  It would be cumbersome to give `signal' a
+list of condition names rather than one error symbol.
+
+   By contrast, using only error symbols without condition names would
+seriously decrease the power of `condition-case'.  Condition names make
+it possible to categorize errors at various levels of generality when
+you write an error handler.  Using error symbols alone would eliminate
+all but the narrowest level of classification.
+
+   *Note Standard Errors::, for a list of all the standard error symbols
+and their conditions.
+
+\1f
+File: lispref.info,  Node: Cleanups,  Prev: Errors,  Up: Nonlocal Exits
+
+Cleaning Up from Nonlocal Exits
+-------------------------------
+
+The `unwind-protect' construct is essential whenever you temporarily
+put a data structure in an inconsistent state; it permits you to ensure
+the data are consistent in the event of an error or throw.
+
+ - Special Form: unwind-protect body cleanup-forms...
+     `unwind-protect' executes the BODY with a guarantee that the
+     CLEANUP-FORMS will be evaluated if control leaves BODY, no matter
+     how that happens.  The BODY may complete normally, or execute a
+     `throw' out of the `unwind-protect', or cause an error; in all
+     cases, the CLEANUP-FORMS will be evaluated.
+
+     If the BODY forms finish normally, `unwind-protect' returns the
+     value of the last BODY form, after it evaluates the CLEANUP-FORMS.
+     If the BODY forms do not finish, `unwind-protect' does not return
+     any value in the normal sense.
+
+     Only the BODY is actually protected by the `unwind-protect'.  If
+     any of the CLEANUP-FORMS themselves exits nonlocally (e.g., via a
+     `throw' or an error), `unwind-protect' is _not_ guaranteed to
+     evaluate the rest of them.  If the failure of one of the
+     CLEANUP-FORMS has the potential to cause trouble, then protect it
+     with another `unwind-protect' around that form.
+
+     The number of currently active `unwind-protect' forms counts,
+     together with the number of local variable bindings, against the
+     limit `max-specpdl-size' (*note Local Variables::).
+
+   For example, here we make an invisible buffer for temporary use, and
+make sure to kill it before finishing:
+
+     (save-excursion
+       (let ((buffer (get-buffer-create " *temp*")))
+         (set-buffer buffer)
+         (unwind-protect
+             BODY
+           (kill-buffer buffer))))
+
+You might think that we could just as well write `(kill-buffer
+(current-buffer))' and dispense with the variable `buffer'.  However,
+the way shown above is safer, if BODY happens to get an error after
+switching to a different buffer!  (Alternatively, you could write
+another `save-excursion' around the body, to ensure that the temporary
+buffer becomes current in time to kill it.)
+
+   Here is an actual example taken from the file `ftp.el'.  It creates
+a process (*note Processes::) to try to establish a connection to a
+remote machine.  As the function `ftp-login' is highly susceptible to
+numerous problems that the writer of the function cannot anticipate, it
+is protected with a form that guarantees deletion of the process in the
+event of failure.  Otherwise, XEmacs might fill up with useless
+subprocesses.
+
+     (let ((win nil))
+       (unwind-protect
+           (progn
+             (setq process (ftp-setup-buffer host file))
+             (if (setq win (ftp-login process host user password))
+                 (message "Logged in")
+               (error "Ftp login failed")))
+         (or win (and process (delete-process process)))))
+
+   This example actually has a small bug: if the user types `C-g' to
+quit, and the quit happens immediately after the function
+`ftp-setup-buffer' returns but before the variable `process' is set,
+the process will not be killed.  There is no easy way to fix this bug,
+but at least it is very unlikely.
+
+   Here is another example which uses `unwind-protect' to make sure to
+kill a temporary buffer.  In this example, the value returned by
+`unwind-protect' is used.
+
+     (defun shell-command-string (cmd)
+       "Return the output of the shell command CMD, as a string."
+       (save-excursion
+         (set-buffer (generate-new-buffer " OS*cmd"))
+         (shell-command cmd t)
+         (unwind-protect
+             (buffer-string)
+           (kill-buffer (current-buffer)))))
+
+\1f
+File: lispref.info,  Node: Variables,  Next: Functions,  Prev: Control Structures,  Up: Top
+
+Variables
+*********
+
+A "variable" is a name used in a program to stand for a value.  Nearly
+all programming languages have variables of some sort.  In the text of
+a Lisp program, variables are written using the syntax for symbols.
+
+   In Lisp, unlike most programming languages, programs are represented
+primarily as Lisp objects and only secondarily as text.  The Lisp
+objects used for variables are symbols: the symbol name is the variable
+name, and the variable's value is stored in the value cell of the
+symbol.  The use of a symbol as a variable is independent of its use as
+a function name.  *Note Symbol Components::.
+
+   The Lisp objects that constitute a Lisp program determine the textual
+form of the program--it is simply the read syntax for those Lisp
+objects.  This is why, for example, a variable in a textual Lisp program
+is written using the read syntax for the symbol that represents the
+variable.
+
+* Menu:
+
+* 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.
+* Variable Aliases::     Making one variable point to another.
+
+\1f
+File: lispref.info,  Node: Global Variables,  Next: Constant Variables,  Up: Variables
+
+Global Variables
+================
+
+The simplest way to use a variable is "globally".  This means that the
+variable has just one value at a time, and this value is in effect (at
+least for the moment) throughout the Lisp system.  The value remains in
+effect until you specify a new one.  When a new value replaces the old
+one, no trace of the old value remains in the variable.
+
+   You specify a value for a symbol with `setq'.  For example,
+
+     (setq x '(a b))
+
+gives the variable `x' the value `(a b)'.  Note that `setq' does not
+evaluate its first argument, the name of the variable, but it does
+evaluate the second argument, the new value.
+
+   Once the variable has a value, you can refer to it by using the
+symbol by itself as an expression.  Thus,
+
+     x => (a b)

 
 

-   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.
+assuming the `setq' form shown above has already been executed.
+
+   If you do another `setq', the new value replaces the old one:
+
+     x
+          => (a b)
+     (setq x 4)
+          => 4
+     x
+          => 4
+
+\1f
+File: lispref.info,  Node: Constant Variables,  Next: Local Variables,  Prev: Global Variables,  Up: Variables
+
+Variables That Never Change
+===========================
+
+In XEmacs Lisp, some symbols always evaluate to themselves: the two
+special symbols `nil' and `t', as well as "keyword symbols", that is,
+symbols whose name begins with the character ``:''.  These symbols
+cannot be rebound, nor can their value cells be changed.  An attempt to
+change the value of `nil' or `t' signals a `setting-constant' error.
+
+     nil == 'nil
+          => nil
+     (setq nil 500)
+     error--> Attempt to set constant symbol: nil
+
+\1f
+File: lispref.info,  Node: Local Variables,  Next: Void Variables,  Prev: Constant Variables,  Up: Variables
+
+Local Variables
+===============
+
+Global variables have values that last until explicitly superseded with
+new values.  Sometimes it is useful to create variable values that
+exist temporarily--only while within a certain part of the program.
+These values are called "local", and the variables so used are called
+"local variables".
+
+   For example, when a function is called, its argument variables
+receive new local values that last until the function exits.  The `let'
+special form explicitly establishes new local values for specified
+variables; these last until exit from the `let' form.
+
+   Establishing a local value saves away the previous value (or lack of
+one) of the variable.  When the life span of the local value is over,
+the previous value is restored.  In the mean time, we say that the
+previous value is "shadowed" and "not visible".  Both global and local
+values may be shadowed (*note Scope::).
+
+   If you set a variable (such as with `setq') while it is local, this
+replaces the local value; it does not alter the global value, or
+previous local values that are shadowed.  To model this behavior, we
+speak of a "local binding" of the variable as well as a local value.
+
+   The local binding is a conceptual place that holds a local value.
+Entry to a function, or a special form such as `let', creates the local
+binding; exit from the function or from the `let' removes the local
+binding.  As long as the local binding lasts, the variable's value is
+stored within it.  Use of `setq' or `set' while there is a local
+binding stores a different value into the local binding; it does not
+create a new binding.
+
+   We also speak of the "global binding", which is where (conceptually)
+the global value is kept.
+
+   A variable can have more than one local binding at a time (for
+example, if there are nested `let' forms that bind it).  In such a
+case, the most recently created local binding that still exists is the
+"current binding" of the variable.  (This is called "dynamic scoping";
+see *Note Variable Scoping::.)  If there are no local bindings, the
+variable's global binding is its current binding.  We also call the
+current binding the "most-local existing binding", for emphasis.
+Ordinary evaluation of a symbol always returns the value of its current
+binding.
+
+   The special forms `let' and `let*' exist to create local bindings.
+
+ - Special Form: let (bindings...) forms...
+     This special form binds variables according to BINDINGS and then
+     evaluates all of the FORMS in textual order.  The `let'-form
+     returns the value of the last form in FORMS.
+
+     Each of the BINDINGS is either (i) a symbol, in which case that
+     symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL
+     VALUE-FORM)', in which case SYMBOL is bound to the result of
+     evaluating VALUE-FORM.  If VALUE-FORM is omitted, `nil' is used.
+
+     All of the VALUE-FORMs in BINDINGS are evaluated in the order they
+     appear and _before_ any of the symbols are bound.  Here is an
+     example of this: `Z' is bound to the old value of `Y', which is 2,
+     not the new value, 1.
+
+          (setq Y 2)
+               => 2
+          (let ((Y 1)
+                (Z Y))
+            (list Y Z))
+               => (1 2)
+
+ - Special Form: let* (bindings...) forms...
+     This special form is like `let', but it binds each variable right
+     after computing its local value, before computing the local value
+     for the next variable.  Therefore, an expression in BINDINGS can
+     reasonably refer to the preceding symbols bound in this `let*'
+     form.  Compare the following example with the example above for
+     `let'.
+
+          (setq Y 2)
+               => 2
+          (let* ((Y 1)
+                 (Z Y))    ; Use the just-established value of `Y'.
+            (list Y Z))
+               => (1 1)
+
+   Here is a complete list of the other facilities that create local
+bindings:
+
+   * Function calls (*note Functions::).
+
+   * Macro calls (*note Macros::).
+
+   * `condition-case' (*note Errors::).
+
+   Variables can also have buffer-local bindings (*note Buffer-Local
+Variables::).  These kinds of bindings work somewhat like ordinary local
+bindings, but they are localized depending on "where" you are in Emacs,
+rather than localized in time.
+
+ - Variable: max-specpdl-size
+     This variable defines the limit on the total number of local
+     variable bindings and `unwind-protect' cleanups (*note Nonlocal
+     Exits::) that are allowed before signaling an error (with data
+     `"Variable binding depth exceeds max-specpdl-size"').
+
+     This limit, with the associated error when it is exceeded, is one
+     way that Lisp avoids infinite recursion on an ill-defined function.
+
+     The default value is 3000.
+
+     `max-lisp-eval-depth' provides another limit on depth of nesting.
+     *Note Eval::.
+
+\1f
+File: lispref.info,  Node: Void Variables,  Next: Defining Variables,  Prev: Local Variables,  Up: Variables
+
+When a Variable is "Void"
+=========================
+
+If you have never given a symbol any value as a global variable, we say
+that that symbol's global value is "void".  In other words, the
+symbol's value cell does not have any Lisp object in it.  If you try to
+evaluate the symbol, you get a `void-variable' error rather than a
+value.
+
+   Note that a value of `nil' is not the same as void.  The symbol
+`nil' is a Lisp object and can be the value of a variable just as any
+other object can be; but it is _a value_.  A void variable does not
+have any value.
+
+   After you have given a variable a value, you can make it void once
+more using `makunbound'.
+
+ - Function: makunbound symbol
+     This function makes the current binding of SYMBOL void.
+     Subsequent attempts to use this symbol's value as a variable will
+     signal the error `void-variable', unless or until you set it again.
+
+     `makunbound' returns SYMBOL.
+
+          (makunbound 'x)      ; Make the global value
+                               ;   of `x' void.
+               => x
+          x
+          error--> Symbol's value as variable is void: x
+
+     If SYMBOL is locally bound, `makunbound' affects the most local
+     existing binding.  This is the only way a symbol can have a void
+     local binding, since all the constructs that create local bindings
+     create them with values.  In this case, the voidness lasts at most
+     as long as the binding does; when the binding is removed due to
+     exit from the construct that made it, the previous or global
+     binding is reexposed as usual, and the variable is no longer void
+     unless the newly reexposed binding was void all along.
+
+          (setq x 1)               ; Put a value in the global binding.
+               => 1
+          (let ((x 2))             ; Locally bind it.
+            (makunbound 'x)        ; Void the local binding.
+            x)
+          error--> Symbol's value as variable is void: x
+          x                        ; The global binding is unchanged.
+               => 1
+          
+          (let ((x 2))             ; Locally bind it.
+            (let ((x 3))           ; And again.
+              (makunbound 'x)      ; Void the innermost-local binding.
+              x))                  ; And refer: it's void.
+          error--> Symbol's value as variable is void: x
+          
+          (let ((x 2))
+            (let ((x 3))
+              (makunbound 'x))     ; Void inner binding, then remove it.
+            x)                     ; Now outer `let' binding is visible.
+               => 2
+
+   A variable that has been made void with `makunbound' is
+indistinguishable from one that has never received a value and has
+always been void.
+
+   You can use the function `boundp' to test whether a variable is
+currently void.
+
+ - Function: boundp variable
+     `boundp' returns `t' if VARIABLE (a symbol) is not void; more
+     precisely, if its current binding is not void.  It returns `nil'
+     otherwise.
+
+          (boundp 'abracadabra)          ; Starts out void.
+               => nil
+          (let ((abracadabra 5))         ; Locally bind it.
+            (boundp 'abracadabra))
+               => t
+          (boundp 'abracadabra)          ; Still globally void.
+               => nil
+          (setq abracadabra 5)           ; Make it globally nonvoid.
+               => 5
+          (boundp 'abracadabra)
+               => t
+
+\1f
+File: lispref.info,  Node: Defining Variables,  Next: Accessing Variables,  Prev: Void Variables,  Up: Variables
+
+Defining Global Variables
+=========================
+
+You may announce your intention to use a symbol as a global variable
+with a "variable definition": a special form, either `defconst' or
+`defvar'.
+
+   In XEmacs Lisp, definitions serve three purposes.  First, they inform
+people who read the code that certain symbols are _intended_ to be used
+a certain way (as variables).  Second, they inform the Lisp system of
+these things, supplying a value and documentation.  Third, they provide
+information to utilities such as `etags' and `make-docfile', which
+create data bases of the functions and variables in a program.
+
+   The difference between `defconst' and `defvar' is primarily a matter
+of intent, serving to inform human readers of whether programs will
+change the variable.  XEmacs Lisp does not restrict the ways in which a
+variable can be used based on `defconst' or `defvar' declarations.
+However, it does make a difference for initialization: `defconst'
+unconditionally initializes the variable, while `defvar' initializes it
+only if it is void.
+
+   One would expect user option variables to be defined with
+`defconst', since programs do not change them.  Unfortunately, this has
+bad results if the definition is in a library that is not preloaded:
+`defconst' would override any prior value when the library is loaded.
+Users would like to be able to set user options in their init files,
+and override the default values given in the definitions.  For this
+reason, user options must be defined with `defvar'.
+
+ - Special Form: defvar symbol [value [doc-string]]
+     This special form defines SYMBOL as a value and initializes it.
+     The definition informs a person reading your code that SYMBOL is
+     used as a variable that programs are likely to set or change.  It
+     is also used for all user option variables except in the preloaded
+     parts of XEmacs.  Note that SYMBOL is not evaluated; the symbol to
+     be defined must appear explicitly in the `defvar'.
+
+     If SYMBOL already has a value (i.e., it is not void), VALUE is not
+     even evaluated, and SYMBOL's value remains unchanged.  If SYMBOL
+     is void and VALUE is specified, `defvar' evaluates it and sets
+     SYMBOL to the result.  (If VALUE is omitted, the value of SYMBOL
+     is not changed in any case.)
+
+     When you evaluate a top-level `defvar' form with `C-M-x' in Emacs
+     Lisp mode (`eval-defun'), a special feature of `eval-defun'
+     evaluates it as a `defconst'.  The purpose of this is to make sure
+     the variable's value is reinitialized, when you ask for it
+     specifically.
+
+     If SYMBOL has a buffer-local binding in the current buffer,
+     `defvar' sets the default value, not the local value.  *Note
+     Buffer-Local Variables::.
+
+     If the DOC-STRING argument appears, it specifies the documentation
+     for the variable.  (This opportunity to specify documentation is
+     one of the main benefits of defining the variable.)  The
+     documentation is stored in the symbol's `variable-documentation'
+     property.  The XEmacs help functions (*note Documentation::) look
+     for this property.
+
+     If the first character of DOC-STRING is `*', it means that this
+     variable is considered a user option.  This lets users set the
+     variable conveniently using the commands `set-variable' and
+     `edit-options'.
+
+     For example, this form defines `foo' but does not set its value:
+
+          (defvar foo)
+               => foo
+
+     The following example sets the value of `bar' to `23', and gives
+     it a documentation string:
+
+          (defvar bar 23
+            "The normal weight of a bar.")
+               => bar
+
+     The following form changes the documentation string for `bar',
+     making it a user option, but does not change the value, since `bar'
+     already has a value.  (The addition `(1+ 23)' is not even
+     performed.)
+
+          (defvar bar (1+ 23)
+            "*The normal weight of a bar.")
+               => bar
+          bar
+               => 23
+
+     Here is an equivalent expression for the `defvar' special form:
+
+          (defvar SYMBOL VALUE DOC-STRING)
+          ==
+          (progn
+            (if (not (boundp 'SYMBOL))
+                (setq SYMBOL VALUE))
+            (put 'SYMBOL 'variable-documentation 'DOC-STRING)
+            'SYMBOL)
+
+     The `defvar' form returns SYMBOL, but it is normally used at top
+     level in a file where its value does not matter.
+
+ - Special Form: defconst symbol [value [doc-string]]
+     This special form defines SYMBOL as a value and initializes it.
+     It informs a person reading your code that SYMBOL has a global
+     value, established here, that will not normally be changed or
+     locally bound by the execution of the program.  The user, however,
+     may be welcome to change it.  Note that SYMBOL is not evaluated;
+     the symbol to be defined must appear explicitly in the `defconst'.
+
+     `defconst' always evaluates VALUE and sets the global value of
+     SYMBOL to the result, provided VALUE is given.  If SYMBOL has a
+     buffer-local binding in the current buffer, `defconst' sets the
+     default value, not the local value.
+
+     *Please note:* Don't use `defconst' for user option variables in
+     libraries that are not standardly preloaded.  The user should be
+     able to specify a value for such a variable in the `.emacs' file,
+     so that it will be in effect if and when the library is loaded
+     later.
+
+     Here, `pi' is a constant that presumably ought not to be changed
+     by anyone (attempts by the Indiana State Legislature
+     notwithstanding).  As the second form illustrates, however, this
+     is only advisory.
+
+          (defconst pi 3.1415 "Pi to five places.")
+               => pi
+          (setq pi 3)
+               => pi
+          pi
+               => 3
+
+ - Function: user-variable-p variable
+     This function returns `t' if VARIABLE is a user option--a variable
+     intended to be set by the user for customization--and `nil'
+     otherwise.  (Variables other than user options exist for the
+     internal purposes of Lisp programs, and users need not know about
+     them.)
+
+     User option variables are distinguished from other variables by the
+     first character of the `variable-documentation' property.  If the
+     property exists and is a string, and its first character is `*',
+     then the variable is a user option.
+
+   If a user option variable has a `variable-interactive' property, the
+`set-variable' command uses that value to control reading the new value
+for the variable.  The property's value is used as if it were the
+argument to `interactive'.
+
+   *Warning:* If the `defconst' and `defvar' special forms are used
+while the variable has a local binding, they set the local binding's
+value; the global binding is not changed.  This is not what we really
+want.  To prevent it, use these special forms at top level in a file,
+where normally no local binding is in effect, and make sure to load the
+file before making a local binding for the variable.
+
+\1f
+File: lispref.info,  Node: Accessing Variables,  Next: Setting Variables,  Prev: Defining Variables,  Up: Variables
+
+Accessing Variable Values
+=========================
+
+The usual way to reference a variable is to write the symbol which
+names it (*note Symbol Forms::).  This requires you to specify the
+variable name when you write the program.  Usually that is exactly what
+you want to do.  Occasionally you need to choose at run time which
+variable to reference; then you can use `symbol-value'.
+
+ - Function: symbol-value symbol
+     This function returns the value of SYMBOL.  This is the value in
+     the innermost local binding of the symbol, or its global value if
+     it has no local bindings.
+
+          (setq abracadabra 5)
+               => 5
+          (setq foo 9)
+               => 9
+          
+          ;; Here the symbol `abracadabra'
+          ;;   is the symbol whose value is examined.
+          (let ((abracadabra 'foo))
+            (symbol-value 'abracadabra))
+               => foo
+          
+          ;; Here the value of `abracadabra',
+          ;;   which is `foo',
+          ;;   is the symbol whose value is examined.
+          (let ((abracadabra 'foo))
+            (symbol-value abracadabra))
+               => 9
+          
+          (symbol-value 'abracadabra)
+               => 5
+
+     A `void-variable' error is signaled if SYMBOL has neither a local
+     binding nor a global value.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Introduction,  Next: Lisp Data Types,  Prev: Copying,  Up: Top
+File: lispref.info,  Node: Setting Variables,  Next: Variable Scoping,  Prev: Accessing Variables,  Up: Variables
+
+How to Alter a Variable Value
+=============================
+
+The usual way to change the value of a variable is with the special
+form `setq'.  When you need to compute the choice of variable at run
+time, use the function `set'.
+
+ - Special Form: setq [symbol form]...
+     This special form is the most common method of changing a
+     variable's value.  Each SYMBOL is given a new value, which is the
+     result of evaluating the corresponding FORM.  The most-local
+     existing binding of the symbol is changed.
+
+     `setq' does not evaluate SYMBOL; it sets the symbol that you
+     write.  We say that this argument is "automatically quoted".  The
+     `q' in `setq' stands for "quoted."
+
+     The value of the `setq' form is the value of the last FORM.
+
+          (setq x (1+ 2))
+               => 3
+          x                   ; `x' now has a global value.
+               => 3
+          (let ((x 5))
+            (setq x 6)        ; The local binding of `x' is set.
+            x)
+               => 6
+          x                   ; The global value is unchanged.
+               => 3
+
+     Note that the first FORM is evaluated, then the first SYMBOL is
+     set, then the second FORM is evaluated, then the second SYMBOL is
+     set, and so on:
+
+          (setq x 10          ; Notice that `x' is set before
+                y (1+ x))     ;   the value of `y' is computed.
+               => 11
+
+ - Function: set symbol value
+     This function sets SYMBOL's value to VALUE, then returns VALUE.
+     Since `set' is a function, the expression written for SYMBOL is
+     evaluated to obtain the symbol to set.
+
+     The most-local existing binding of the variable is the binding
+     that is set; shadowed bindings are not affected.
+
+          (set one 1)
+          error--> Symbol's value as variable is void: one
+          (set 'one 1)
+               => 1
+          (set 'two 'one)
+               => one
+          (set two 2)         ; `two' evaluates to symbol `one'.
+               => 2
+          one                 ; So it is `one' that was set.
+               => 2
+          (let ((one 1))      ; This binding of `one' is set,
+            (set 'one 3)      ;   not the global value.
+            one)
+               => 3
+          one
+               => 2
+
+     If SYMBOL is not actually a symbol, a `wrong-type-argument' error
+     is signaled.
+
+          (set '(x y) 'z)
+          error--> Wrong type argument: symbolp, (x y)
+
+     Logically speaking, `set' is a more fundamental primitive than
+     `setq'.  Any use of `setq' can be trivially rewritten to use
+     `set'; `setq' could even be defined as a macro, given the
+     availability of `set'.  However, `set' itself is rarely used;
+     beginners hardly need to know about it.  It is useful only for
+     choosing at run time which variable to set.  For example, the
+     command `set-variable', which reads a variable name from the user
+     and then sets the variable, needs to use `set'.
+
+          Common Lisp note: In Common Lisp, `set' always changes the
+          symbol's special value, ignoring any lexical bindings.  In
+          XEmacs Lisp, all variables and all bindings are (in effect)
+          special, so `set' always affects the most local existing
+          binding.
+
+   One other function for setting a variable is designed to add an
+element to a list if it is not already present in the list.
+
+ - Function: add-to-list symbol element
+     This function sets the variable SYMBOL by consing ELEMENT onto the
+     old value, if ELEMENT is not already a member of that value.  It
+     returns the resulting list, whether updated or not.  The value of
+     SYMBOL had better be a list already before the call.
+
+     The argument SYMBOL is not implicitly quoted; `add-to-list' is an
+     ordinary function, like `set' and unlike `setq'.  Quote the
+     argument yourself if that is what you want.
+
+     Here's a scenario showing how to use `add-to-list':
+
+          (setq foo '(a b))
+               => (a b)
+          
+          (add-to-list 'foo 'c)     ;; Add `c'.
+               => (c a b)
+          
+          (add-to-list 'foo 'b)     ;; No effect.
+               => (c a b)
+          
+          foo                       ;; `foo' was changed.
+               => (c a b)
+
+   An equivalent expression for `(add-to-list 'VAR VALUE)' is this:
+
+     (or (member VALUE VAR)
+         (setq VAR (cons VALUE VAR)))

 
 

-Introduction
-************
+\1f
+File: lispref.info,  Node: Variable Scoping,  Next: Buffer-Local Variables,  Prev: Setting Variables,  Up: Variables
+
+Scoping Rules for Variable Bindings
+===================================

 
 

-   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.
+A given symbol `foo' may have several local variable bindings,
+established at different places in the Lisp program, as well as a global
+binding.  The most recently established binding takes precedence over
+the others.

 
 

-   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.
+   Local bindings in XEmacs Lisp have "indefinite scope" and "dynamic
+extent".  "Scope" refers to _where_ textually in the source code the
+binding can be accessed.  Indefinite scope means that any part of the
+program can potentially access the variable binding.  "Extent" refers
+to _when_, as the program is executing, the binding exists.  Dynamic
+extent means that the binding lasts as long as the activation of the
+construct that established it.

 
 

-   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.
+   The combination of dynamic extent and indefinite scope is called
+"dynamic scoping".  By contrast, most programming languages use
+"lexical scoping", in which references to a local variable must be
+located textually within the function or block that binds the variable.

 
 

-   This is edition 3.3.
+     Common Lisp note: Variables declared "special" in Common Lisp are
+     dynamically scoped, like variables in XEmacs Lisp.

 
 * Menu:
 
 
 * 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.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Caveats,  Next: Lisp History,  Up: Introduction
+File: lispref.info,  Node: Scope,  Next: Extent,  Up: Variable Scoping

 
 

-Caveats
-=======
+Scope
+-----
+
+XEmacs Lisp uses "indefinite scope" for local variable bindings.  This
+means that any function anywhere in the program text might access a
+given binding of a variable.  Consider the following function
+definitions:

 
 

-   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.
+     (defun binder (x)   ; `x' is bound in `binder'.
+        (foo 5))         ; `foo' is some other function.
+     
+     (defun user ()      ; `x' is used in `user'.
+       (list x))
+
+   In a lexically scoped language, the binding of `x' in `binder' would
+never be accessible in `user', because `user' is not textually
+contained within the function `binder'.  However, in dynamically scoped
+XEmacs Lisp, `user' may or may not refer to the binding of `x'
+established in `binder', depending on circumstances:

 
 

-   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.
+   * If we call `user' directly without calling `binder' at all, then
+     whatever binding of `x' is found, it cannot come from `binder'.

 
 

-   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.
+   * If we define `foo' as follows and call `binder', then the binding
+     made in `binder' will be seen in `user':

 
 

-   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
+          (defun foo (lose)
+            (user))

 
 

-   or post to the newsgroup
-     comp.emacs.xemacs
+   * If we define `foo' as follows and call `binder', then the binding
+     made in `binder' _will not_ be seen in `user':

 
 

-      --Ben Wing
+          (defun foo (x)
+            (user))
+
+     Here, when `foo' is called by `binder', it binds `x'.  (The
+     binding in `foo' is said to "shadow" the one made in `binder'.)
+     Therefore, `user' will access the `x' bound by `foo' instead of
+     the one bound by `binder'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Lisp History,  Next: Conventions,  Prev: Caveats,  Up: Introduction
+File: lispref.info,  Node: Extent,  Next: Impl of Scope,  Prev: Scope,  Up: Variable Scoping
+
+Extent
+------
+
+"Extent" refers to the time during program execution that a variable
+name is valid.  In XEmacs Lisp, a variable is valid only while the form
+that bound it is executing.  This is called "dynamic extent".  "Local"
+or "automatic" variables in most languages, including C and Pascal,
+have dynamic extent.
+
+   One alternative to dynamic extent is "indefinite extent".  This
+means that a variable binding can live on past the exit from the form
+that made the binding.  Common Lisp and Scheme, for example, support
+this, but XEmacs Lisp does not.
+
+   To illustrate this, the function below, `make-add', returns a
+function that purports to add N to its own argument M.  This would work
+in Common Lisp, but it does not work as intended in XEmacs Lisp,
+because after the call to `make-add' exits, the variable `n' is no
+longer bound to the actual argument 2.
+
+     (defun make-add (n)
+         (function (lambda (m) (+ n m))))  ; Return a function.
+          => make-add
+     (fset 'add2 (make-add 2))  ; Define function `add2'
+                                ;   with `(make-add 2)'.
+          => (lambda (m) (+ n m))
+     (add2 4)                   ; Try to add 2 to 4.
+     error--> Symbol's value as variable is void: n
+
+   Some Lisp dialects have "closures", objects that are like functions
+but record additional variable bindings.  XEmacs Lisp does not have
+closures.

 
 

-Lisp History
-============
+\1f
+File: lispref.info,  Node: Impl of Scope,  Next: Using Scoping,  Prev: Extent,  Up: Variable Scoping
+
+Implementation of Dynamic Scoping
+---------------------------------
+
+A simple sample implementation (which is not how XEmacs Lisp actually
+works) may help you understand dynamic binding.  This technique is
+called "deep binding" and was used in early Lisp systems.
+
+   Suppose there is a stack of bindings: variable-value pairs.  At entry
+to a function or to a `let' form, we can push bindings on the stack for
+the arguments or local variables created there.  We can pop those
+bindings from the stack at exit from the binding construct.
+
+   We can find the value of a variable by searching the stack from top
+to bottom for a binding for that variable; the value from that binding
+is the value of the variable.  To set the variable, we search for the
+current binding, then store the new value into that binding.
+
+   As you can see, a function's bindings remain in effect as long as it
+continues execution, even during its calls to other functions.  That is
+why we say the extent of the binding is dynamic.  And any other function
+can refer to the bindings, if it uses the same variables while the
+bindings are in effect.  That is why we say the scope is indefinite.
+
+   The actual implementation of variable scoping in XEmacs Lisp uses a
+technique called "shallow binding".  Each variable has a standard place
+in which its current value is always found--the value cell of the
+symbol.
+
+   In shallow binding, setting the variable works by storing a value in
+the value cell.  Creating a new binding works by pushing the old value
+(belonging to a previous binding) on a stack, and storing the local
+value in the value cell.  Eliminating a binding works by popping the
+old value off the stack, into the value cell.
+
+   We use shallow binding because it has the same results as deep
+binding, but runs faster, since there is never a need to search for a
+binding.
+
+\1f
+File: lispref.info,  Node: Using Scoping,  Prev: Impl of Scope,  Up: Variable Scoping
+
+Proper Use of Dynamic Scoping
+-----------------------------

 
 

-   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.
+Binding a variable in one function and using it in another is a
+powerful technique, but if used without restraint, it can make programs
+hard to understand.  There are two clean ways to use this technique:

 
 

-   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.
+   * Use or bind the variable only in a few related functions, written
+     close together in one file.  Such a variable is used for
+     communication within one program.

 
 

-   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.
+     You should write comments to inform other programmers that they
+     can see all uses of the variable before them, and to advise them
+     not to add uses elsewhere.
+
+   * Give the variable a well-defined, documented meaning, and make all
+     appropriate functions refer to it (but not bind it or set it)
+     wherever that meaning is relevant.  For example, the variable
+     `case-fold-search' is defined as "non-`nil' means ignore case when
+     searching"; various search and replace functions refer to it
+     directly or through their subroutines, but do not bind or set it.
+
+     Then you can bind the variable in other programs, knowing reliably
+     what the effect will be.
+
+   In either case, you should define the variable with `defvar'.  This
+helps other people understand your program by telling them to look for
+inter-function usage.  It also avoids a warning from the byte compiler.
+Choose the variable's name to avoid name conflicts--don't use short
+names like `x'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Conventions,  Next: Acknowledgements,  Prev: Lisp History,  Up: Introduction
+File: lispref.info,  Node: Buffer-Local Variables,  Next: Variable Aliases,  Prev: Variable Scoping,  Up: Variables

 
 

-Conventions
-===========
+Buffer-Local Variables
+======================

 
 

-   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.
+Global and local variable bindings are found in most programming
+languages in one form or another.  XEmacs also supports another, unusual
+kind of variable binding: "buffer-local" bindings, which apply only to
+one buffer.  XEmacs Lisp is meant for programming editing commands, and
+having different values for a variable in different buffers is an
+important customization method.

 
 * Menu:
 
 
 * 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.
+* 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.
+
+\1f
+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::.
+
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Some Terms,  Next: nil and t,  Up: Conventions
+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

 
 

-Some Terms
-----------
+\1f
+File: lispref.info,  Node: Variable Aliases,  Prev: Buffer-Local Variables,  Up: Variables

 
 

-   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.
+Variable Aliases
+================

 
 

-   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.
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: nil and t,  Next: Evaluation Notation,  Prev: Some Terms,  Up: Conventions
+File: lispref.info,  Node: Functions,  Next: Macros,  Prev: Variables,  Up: Top

 
 

-`nil' and `t'
--------------
+Functions
+*********

 
 

-   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::.
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: nil and t,  Up: Conventions
+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

 
 

-Evaluation Notation
--------------------
+\1f
+File: lispref.info,  Node: Lambda Expressions,  Next: Function Names,  Prev: What Is a Function,  Up: Functions

 
 

-   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 `=>':
+Lambda Expressions
+==================

 
 

-     (car '(1 2))
-          => 1
+A function written in Lisp is a list that looks like this:

 
 

-You can read this as "`(car '(1 2))' evaluates to 1".
+     (lambda (ARG-VARIABLES...)
+       [DOCUMENTATION-STRING]
+       [INTERACTIVE-DECLARATION]
+       BODY-FORMS...)

 
 

-   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.
+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.

 
 

-     (news-cadr '(a b c))
-          ==> (car (cdr '(a b c)))
-          => b
+* Menu:

 
 

-   Sometimes to help describe one form we show another form that
-produces identical results.  The exact equivalence of two forms is
-indicated with `=='.
+* 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.

 
 

-     (cons 'a nil) == (list 'a)
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions
+File: lispref.info,  Node: Simple Lambda,  Next: Argument List,  Prev: Lambda Components,  Up: Lambda Expressions

 
 

-Printing Notation
------------------
+A Simple Lambda-Expression Example
+----------------------------------

 
 

-   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.
+Consider for example the following function:

 
 

-   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.
+     (lambda (a b c) (+ a b c))

 
 

-     (progn (print 'foo) (print 'bar))
-          -| foo
-          -| bar
-          => bar
+We can call this function by writing it as the CAR of an expression,
+like this:

 
 

-\1f
-File: lispref.info,  Node: Error Messages,  Next: Buffer Text Notation,  Prev: Printing Notation,  Up: Conventions
+     ((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))

 
 

-Error Messages
---------------
+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.

 
 

-   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.
+   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::).

 
 

-     (+ 23 'x)
-     error--> Wrong type argument: integer-or-marker-p, x
+   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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Buffer Text Notation,  Next: Format of Descriptions,  Prev: Error Messages,  Up: Conventions
+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

 
 

-Buffer Text Notation
---------------------
+\1f
+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.

 
 

-   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.)
+\1f
+File: lispref.info,  Node: Function Names,  Next: Defining Functions,  Prev: Lambda Expressions,  Up: Functions

 
 

-     ---------- Buffer: foo ----------
-     This is the -!-contents of foo.
-     ---------- Buffer: foo ----------
-     
-     (insert "changed ")
-          => nil
-     ---------- Buffer: foo ----------
-     This is the changed -!-contents of foo.
-     ---------- Buffer: foo ----------
+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.
+
+\1f
+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::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Format of Descriptions,  Prev: Buffer Text Notation,  Up: Conventions
+File: lispref.info,  Node: Calling Functions,  Next: Mapping Functions,  Prev: Defining Functions,  Up: Functions

 
 

-Format of Descriptions
-----------------------
+Calling Functions
+=================

 
 

-   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.
+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'.

 
 

-* Menu:
+\1f
+File: lispref.info,  Node: Mapping Functions,  Next: Anonymous Functions,  Prev: Calling Functions,  Up: Functions
+
+Mapping Functions
+=================

 
 

-* A Sample Function Description::       A description of an imaginary
-                                          function, `foo'.
-* A Sample Variable Description::       A description of an imaginary
-                                          variable,
-                                          `electric-future-map'.
+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"

 
 \1f
 
 \1f

-File: lispref.info,  Node: A Sample Function Description,  Next: A Sample Variable Description,  Up: Format of Descriptions
+File: lispref.info,  Node: Anonymous Functions,  Next: Function Cells,  Prev: Mapping Functions,  Up: Functions

 
 

-A Sample Function Description
-.............................
+Anonymous Functions
+===================

 
 

-   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.
+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.

 
 

-   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.
+   Any method of creating such a list makes a valid function.  Even
+this:

 
 

-   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.
+     (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
+     => (lambda (x) (+ 12 x))

 
 

-   Here is a description of an imaginary function `foo':
+This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
+it the value (_not_ the function definition!) of `silly'.

 
 

- - 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.
+   Here is how we might call this function:

 
 

-          (foo 1 5 3 9)
-               => 16
-          (foo 5)
-               => 14
+     (funcall silly 1)
+     => 13

 
 

-     More generally,
+(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.)

 
 

-          (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.
-
-\1f
-File: lispref.info,  Node: A Sample Variable Description,  Prev: A Sample Function Description,  Up: Format of Descriptions
-
-A Sample Variable Description
-.............................
+   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:

 
 

-   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.
+     (defun double-each (list)
+       (mapcar '(lambda (x) (* 2 x)) list))
+     => double-each
+     (double-each '(2 11))
+     => (4 22)

 
 

-   Here is a description of the imaginary `electric-future-map'
-variable.
+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.

 
 

- - 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.
+     (function SYMBOL) == (quote SYMBOL) == 'SYMBOL

 
 

-   User option descriptions have the same format, but `Variable' is
-replaced by `User Option'.
+   See `documentation' in *Note Accessing Documentation::, for a
+realistic example using `function' and an anonymous function.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Acknowledgements,  Prev: Conventions,  Up: Introduction
+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.

 
 

-Acknowledgements
+\1f
+File: lispref.info,  Node: Inline Functions,  Next: Related Topics,  Prev: Function Cells,  Up: Functions
+
+Inline Functions

 ================
 
 ================
 

-   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.
-
-\1f
-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.
+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.
+
+\1f
+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::.
+
+\1f
+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:
 
 
 * 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.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Printed Representation,  Next: Comments,  Up: Lisp Data Types
+File: lispref.info,  Node: Simple Macro,  Next: Expansion,  Up: Macros

 
 

-Printed Representation and Read Syntax
-======================================
+A Simple Example of a Macro
+===========================

 
 

-   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.
-
-\1f
-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.
-
-\1f
-File: lispref.info,  Node: Primitive Types,  Next: Programming Types,  Prev: Comments,  Up: Lisp Data Types
-
-Primitive Types
-===============
+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)))

 
 

-   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.
+   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'.

 
 

-   * bit-vector
+\1f
+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.

 
 

-   * buffer
+\1f
+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::).

 
 

-   * char-table
+\1f
+File: lispref.info,  Node: Defining Macros,  Next: Backquote,  Prev: Compiling Macros,  Up: Macros

 
 

-   * character
+Defining Macros
+===============

 
 

-   * charset
+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.

 
 

-   * coding-system
+   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'.

 
 

-   * cons
+ - Special Form: defmacro name argument-list body-forms...
+     `defmacro' defines the symbol NAME as a macro that looks like this:

 
 

-   * color-instance
+          (macro lambda ARGUMENT-LIST . BODY-FORMS)

 
 

-   * compiled-function
+     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.

 
 

-   * console
+     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.

 
 

-   * database
+\1f
+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.

 
 

-   * device
+\1f
+File: lispref.info,  Node: Problems with Macros,  Prev: Backquote,  Up: Macros

 
 

-   * event
+Common Problems Using Macros
+============================

 
 

-   * extent
+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.

 
 

-   * face
+* Menu:

 
 

-   * float
+* 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.

 
 

-   * font-instance
+\1f
+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.

 
 

-   * frame
+\1f
+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.

 
 

-   * glyph
+\1f
+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.

 
 

-   * hash-table
+\1f
+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.

 
 

-   * image-instance
+\1f
+File: lispref.info,  Node: Customization,  Up: Top

 
 

-   * integer
+Writing Customization Definitions
+*********************************

 
 

-   * keymap
+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.

 
 

-   * marker
+* Menu:

 
 

-   * process
+* Common Keywords::
+* Group Definitions::
+* Variable Definitions::
+* Customization Types::

 
 

-   * range-table
+\1f
+File: lispref.info,  Node: Common Keywords,  Next: Group Definitions,  Up: Customization

 
 

-   * specifier
+Common Keywords for All Kinds of Items
+======================================

 
 

-   * string
+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.

 
 

-   * subr
+   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.

 
 

-   * subwindow
+`:tag NAME'
+     Use NAME, a string, instead of the item's name, to label the item
+     in customization menus and buffers.

 
 

-   * symbol
+`: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.

 
 

-   * toolbar-button
+     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!

 
 

-   * tooltalk-message
+`: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.

 
 

-   * tooltalk-pattern
+     There are three alternatives you can use for LINK-DATA:

 
 

-   * vector
+    `(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.

 
 

-   * weak-list
+    `(info-link INFO-NODE)'
+          Like `custom-manual' except that the link appears in the
+          customization buffer with the Info node name.

 
 

-   * window
+    `(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.

 
 

-   * window-configuration
+     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'.

 
 

-   * x-resource
+     An item can have more than one external link; however, most items
+     have none at all.

 
 

-   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.
+`: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.

 
 

-   * char-table-entry
+`: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'.

 
 

-   * command-builder
+     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.

 
 

-   * extent-auxiliary
+\1f
+File: lispref.info,  Node: Group Definitions,  Next: Variable Definitions,  Prev: Common Keywords,  Up: Customization

 
 

-   * extent-info
+Defining Custom Groups
+======================

 
 

-   * lcrecord-list
+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.

 
 

-   * lstream
+   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.

 
 

-   * opaque
+   The way to declare new customization groups is with `defgroup'.

 
 

-   * opaque-list
+ - 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.

 
 

-   * popup-data
+     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.

 
 

-   * symbol-value-buffer-local
+     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.

 
 

-   * symbol-value-forward
+     In addition to the common keywords (*note Common Keywords::), you
+     can use this keyword in `defgroup':

 
 

-   * symbol-value-lisp-magic
+    `: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.

 
 

-   * symbol-value-varalias
+          One group can have any number of prefixes.

 
 

-   * toolbar-data
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Programming Types,  Next: Editing Types,  Prev: Primitive Types,  Up: Lisp Data Types
+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)'.

 
 

-Programming Types
-=================
+* Menu:

 
 

-   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.
+* Simple Types::
+* Composite Types::
+* Splicing into Lists::
+* Type Keywords::

 
 

-* Menu:
+\1f
+File: lispref.info,  Node: Simple Types,  Next: Composite Types,  Up: Customization 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.
-* 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.
-
-\1f
-File: lispref.info,  Node: Integer Type,  Next: Floating Point Type,  Up: Programming Types
-
-Integer Type
+Simple Types

 ------------
 
 ------------
 

-   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.)
+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.
+
+\1f
+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.

 
 

-   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 `+'.)
+`(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)'.

 
 

-     -1               ; The integer -1.
-     1                ; The integer 1.
-     +1               ; Also the integer 1.
-     268435457        ; Causes an error on a 28-bit implementation.
+     In the customization buffer, the CAR and the CDR are displayed and
+     edited separately, each according to the type that you specify for
+     it.

 
 

-   *Note Numbers::, for more information.
+`(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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Floating Point Type,  Next: Character Type,  Prev: Integer Type,  Up: Programming Types
+File: lispref.info,  Node: Splicing into Lists,  Next: Type Keywords,  Prev: Composite Types,  Up: Customization Types

 
 

-Floating Point Type
+Splicing into Lists

 -------------------
 
 -------------------
 

-   XEmacs supports floating point numbers.  The precise range of
-floating point numbers is machine-specific.
+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.
+
+\1f
+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.

 
 

-   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.
+     If `nil' is not a valid value for the alternative, then it is
+     essential to specify a valid default with `:value'.

 
 

-   *Note Numbers::, for more information.
+`: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.
+
+
+\1f
+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.
+
+\1f
+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::.

 
 

diff --git a/info/lispref.info-3 b/info/lispref.info-3
index 837bb60..9f2d6df 100644 (file)
--- a/info/lispref.info-3
+++ b/info/lispref.info-3
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1196 +50,7175 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: Character Type,  Next: Symbol Type,  Prev: Floating Point Type,  Up: Programming Types
+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::.

 
 

-Character Type
---------------
+\1f
+File: lispref.info,  Node: Repeated Loading,  Next: Named Features,  Prev: Autoload,  Up: Loading

 
 

-   In XEmacs version 19, and in all versions of FSF GNU Emacs, a
-"character" in XEmacs Lisp is nothing more than an integer.  This is
-yet another holdover from XEmacs Lisp's derivation from vintage-1980
-Lisps; modern versions of Lisp consider this equivalence a bad idea,
-and have separate character types.  In XEmacs version 20, the modern
-convention is followed, and characters are their own primitive types.
-(This change was necessary in order for MULE, i.e. Asian-language,
-support to be correctly implemented.)
-
-   Even in XEmacs version 20, remnants of the equivalence between
-characters and integers still exist; this is termed the "char-int
-confoundance disease".  In particular, many functions such as `eq',
-`equal', and `memq' have equivalent functions (`old-eq', `old-equal',
-`old-memq', etc.) that pretend like characters are integers are the
-same.  Byte code compiled under any version 19 Emacs will have all such
-functions mapped to their `old-' equivalents when the byte code is read
-into XEmacs 20.  This is to preserve compatibility--Emacs 19 converts
-all constant characters to the equivalent integer during
-byte-compilation, and thus there is no other way to preserve byte-code
-compatibility even if the code has specifically been written with the
-distinction between characters and integers in mind.
-
-   Every character has an equivalent integer, called the "character
-code".  For example, the character `A' is represented as the
-integer 65, following the standard ASCII representation of characters.
-If XEmacs was not compiled with MULE support, the range of this integer
-will always be 0 to 255--eight bits, or one byte. (Integers outside
-this range are accepted but silently truncated; however, you should
-most decidedly _not_ rely on this, because it will not work under
-XEmacs with MULE support.)  When MULE support is present, the range of
-character codes is much larger. (Currently, 19 bits are used.)
-
-   FSF GNU Emacs uses kludgy character codes above 255 to represent
-keyboard input of ASCII characters in combination with certain
-modifiers.  XEmacs does not use this (a more general mechanism is used
-that does not distinguish between ASCII keys and other keys), so you
-will never find character codes above 255 in a non-MULE XEmacs.
-
-   Individual characters are not often used in programs.  It is far more
-common to work with _strings_, which are sequences composed of
-characters.  *Note String Type::.
-
-   The read syntax for characters begins with a question mark, followed
-by the character (if it's printable) or some symbolic representation of
-it.  In XEmacs 20, where characters are their own type, this is also the
-print representation.  In XEmacs 19, however, where characters are
-really integers, the printed representation of a character is a decimal
-number.  This is also a possible read syntax for a character, but
-writing characters that way in Lisp programs is a very bad idea.  You
-should _always_ use the special read syntax formats that XEmacs Lisp
-provides for characters.
-
-   The usual read syntax for alphanumeric characters is a question mark
-followed by the character; thus, `?A' for the character `A', `?B' for
-the character `B', and `?a' for the character `a'.
-
-   For example:
-
-     ;; Under XEmacs 20:
-     ?Q => ?Q    ?q => ?q
-     (char-int ?Q) => 81
-     ;; Under XEmacs 19:
-     ?Q => 81     ?q => 113
-
-   You can use the same syntax for punctuation characters, but it is
-often a good idea to add a `\' so that the Emacs commands for editing
-Lisp code don't get confused.  For example, `?\ ' is the way to write
-the space character.  If the character is `\', you _must_ use a second
-`\' to quote it: `?\\'.  XEmacs 20 always prints punctuation characters
-with a `\' in front of them, to avoid confusion.
-
-   You can express the characters Control-g, backspace, tab, newline,
-vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
-`?\n', `?\v', `?\f', `?\r', `?\e', respectively.  Their character codes
-are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal.  Thus,
-
-     ;; Under XEmacs 20:
-     ?\a => ?\^G              ; `C-g'
-     (char-int ?\a) => 7
-     ?\b => ?\^H              ; backspace, <BS>, `C-h'
-     (char-int ?\b) => 8
-     ?\t => ?\t               ; tab, <TAB>, `C-i'
-     (char-int ?\t) => 9
-     ?\n => ?\n               ; newline, <LFD>, `C-j'
-     ?\v => ?\^K              ; vertical tab, `C-k'
-     ?\f => ?\^L              ; formfeed character, `C-l'
-     ?\r => ?\r               ; carriage return, <RET>, `C-m'
-     ?\e => ?\^[              ; escape character, <ESC>, `C-['
-     ?\\ => ?\\               ; backslash character, `\'
-     ;; Under XEmacs 19:
-     ?\a => 7                 ; `C-g'
-     ?\b => 8                 ; backspace, <BS>, `C-h'
-     ?\t => 9                 ; tab, <TAB>, `C-i'
-     ?\n => 10                ; newline, <LFD>, `C-j'
-     ?\v => 11                ; vertical tab, `C-k'
-     ?\f => 12                ; formfeed character, `C-l'
-     ?\r => 13                ; carriage return, <RET>, `C-m'
-     ?\e => 27                ; escape character, <ESC>, `C-['
-     ?\\ => 92                ; backslash character, `\'
-
-   These sequences which start with backslash are also known as "escape
-sequences", because backslash plays the role of an escape character;
-this usage has nothing to do with the character <ESC>.
-
-   Control characters may be represented using yet another read syntax.
-This consists of a question mark followed by a backslash, caret, and the
-corresponding non-control character, in either upper or lower case.  For
-example, both `?\^I' and `?\^i' are valid read syntax for the character
-`C-i', the character whose value is 9.
-
-   Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
-`?\^I' and to `?\^i':
-
-     ;; Under XEmacs 20:
-     ?\^I => ?\t   ?\C-I => ?\t
-     (char-int ?\^I) => 9
-     ;; Under XEmacs 19:
-     ?\^I => 9     ?\C-I => 9
-
-   There is also a character read syntax beginning with `\M-'.  This
-sets the high bit of the character code (same as adding 128 to the
-character code).  For example, `?\M-A' stands for the character with
-character code 193, or 128 plus 65.  You should _not_ use this syntax
-in your programs.  It is a holdover of yet another confoundance disease
-from earlier Emacsen. (This was used to represent keyboard input with
-the <META> key set, thus the `M'; however, it conflicts with the
-legitimate ISO-8859-1 interpretation of the character code.  For
-example, character code 193 is a lowercase `a' with an acute accent, in
-ISO-8859-1.)
-
-   Finally, the most general read syntax consists of a question mark
-followed by a backslash and the character code in octal (up to three
-octal digits); thus, `?\101' for the character `A', `?\001' for the
-character `C-a', and `?\002' for the character `C-b'.  Although this
-syntax can represent any ASCII character, it is preferred only when the
-precise octal value is more important than the ASCII representation.
-
-     ;; Under XEmacs 20:
-     ?\012 => ?\n        ?\n => ?\n        ?\C-j => ?\n
-     ?\101 => ?A         ?A => ?A
-     ;; Under XEmacs 19:
-     ?\012 => 10         ?\n => 10         ?\C-j => 10
-     ?\101 => 65         ?A => 65
-
-   A backslash is allowed, and harmless, preceding any character without
-a special escape meaning; thus, `?\+' is equivalent to `?+'.  There is
-no reason to add a backslash before most characters.  However, you
-should add a backslash before any of the characters `()\|;'`"#.,' to
-avoid confusing the Emacs commands for editing Lisp code.  Also add a
-backslash before whitespace characters such as space, tab, newline and
-formfeed.  However, it is cleaner to use one of the easily readable
-escape sequences, such as `\t', instead of an actual whitespace
-character such as a tab.
-
-\1f
-File: lispref.info,  Node: Symbol Type,  Next: Sequence Type,  Prev: Character Type,  Up: Programming Types
-
-Symbol Type
------------
+Repeated Loading
+================

 
 

-   A "symbol" in XEmacs Lisp is an object with a name.  The symbol name
-serves as the printed representation of the symbol.  In ordinary use,
-the name is unique--no two symbols have the same name.
-
-   A symbol can serve as a variable, as a function name, or to hold a
-property list.  Or it may serve only to be distinct from all other Lisp
-objects, so that its presence in a data structure may be recognized
-reliably.  In a given context, usually only one of these uses is
-intended.  But you can use one symbol in all of these ways,
-independently.
-
-   A symbol name can contain any characters whatever.  Most symbol names
-are written with letters, digits, and the punctuation characters
-`-+=*/'.  Such names require no special punctuation; the characters of
-the name suffice as long as the name does not look like a number.  (If
-it does, write a `\' at the beginning of the name to force
-interpretation as a symbol.)  The characters `_~!@$%^&:<>{}' are less
-often used but also require no special punctuation.  Any other
-characters may be included in a symbol's name by escaping them with a
-backslash.  In contrast to its use in strings, however, a backslash in
-the name of a symbol simply quotes the single character that follows the
-backslash.  For example, in a string, `\t' represents a tab character;
-in the name of a symbol, however, `\t' merely quotes the letter `t'.
-To have a symbol with a tab character in its name, you must actually
-use a tab (preceded with a backslash).  But it's rare to do such a
-thing.
-
-     Common Lisp note: In Common Lisp, lower case letters are always
-     "folded" to upper case, unless they are explicitly escaped.  In
-     Emacs Lisp, upper case and lower case letters are distinct.
-
-   Here are several examples of symbol names.  Note that the `+' in the
-fifth example is escaped to prevent it from being read as a number.
-This is not necessary in the sixth example because the rest of the name
-makes it invalid as a number.
-
-     foo                 ; A symbol named `foo'.
-     FOO                 ; A symbol named `FOO', different from `foo'.
-     char-to-string      ; A symbol named `char-to-string'.
-     1+                  ; A symbol named `1+'
-                         ;   (not `+1', which is an integer).
-     \+1                 ; A symbol named `+1'
-                         ;   (not a very readable name).
-     \(*\ 1\ 2\)         ; A symbol named `(* 1 2)' (a worse name).
-     +-*/_~!@$%^&=:<>{}  ; A symbol named `+-*/_~!@$%^&=:<>{}'.
-                         ;   These characters need not be escaped.
-
-\1f
-File: lispref.info,  Node: Sequence Type,  Next: Cons Cell Type,  Prev: Symbol Type,  Up: Programming Types
-
-Sequence Types
---------------
+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))

 
 

-   A "sequence" is a Lisp object that represents an ordered set of
-elements.  There are two kinds of sequence in XEmacs Lisp, lists and
-arrays.  Thus, an object of type list or of type array is also
-considered a sequence.
+But this would add multiple elements if the library is reloaded.  To
+avoid the problem, write this:

 
 

-   Arrays are further subdivided into strings, vectors, and bit vectors.
-Vectors can hold elements of any type, but string elements must be
-characters, and bit vector elements must be either 0 or 1.  However, the
-characters in a string can have extents (*note Extents::) and text
-properties (*note Text Properties::) like characters in a buffer;
-vectors do not support extents or text properties even when their
-elements happen to be characters.
+     (or (assq 'leif-mode minor-mode-alist)
+         (setq minor-mode-alist
+               (cons '(leif-mode " Leif") minor-mode-alist)))

 
 

-   Lists, strings, vectors, and bit vectors are different, but they have
-important similarities.  For example, all have a length L, and all have
-elements which can be indexed from zero to L minus one.  Also, several
-functions, called sequence functions, accept any kind of sequence.  For
-example, the function `elt' can be used to extract an element of a
-sequence, given its index.  *Note Sequences Arrays Vectors::.
+   To add an element to a list just once, use `add-to-list' (*note
+Setting Variables::).

 
 

-   It is impossible to read the same sequence twice, since sequences are
-always created anew upon reading.  If you read the read syntax for a
-sequence twice, you get two sequences with equal contents.  There is one
-exception: the empty list `()' always stands for the same object, `nil'.
+   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::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Cons Cell Type,  Next: Array Type,  Prev: Sequence Type,  Up: Programming Types
+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.

 
 

-Cons Cell and List Types
-------------------------
+\1f
+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.
+
+\1f
+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.

 
 

-   A "cons cell" is an object comprising two pointers named the CAR and
-the CDR.  Each of them can point to any Lisp object.
-
-   A "list" is a series of cons cells, linked together so that the CDR
-of each cons cell points either to another cons cell or to the empty
-list.  *Note Lists::, for functions that work on lists.  Because most
-cons cells are used as part of lists, the phrase "list structure" has
-come to refer to any structure made out of cons cells.
-
-   The names CAR and CDR have only historical meaning now.  The
-original Lisp implementation ran on an IBM 704 computer which divided
-words into two parts, called the "address" part and the "decrement";
-CAR was an instruction to extract the contents of the address part of a
-register, and CDR an instruction to extract the contents of the
-decrement.  By contrast, "cons cells" are named for the function `cons'
-that creates them, which in turn is named for its purpose, the
-construction of cells.
-
-   Because cons cells are so central to Lisp, we also have a word for
-"an object which is not a cons cell".  These objects are called "atoms".
-
-   The read syntax and printed representation for lists are identical,
-and consist of a left parenthesis, an arbitrary number of elements, and
-a right parenthesis.
-
-   Upon reading, each object inside the parentheses becomes an element
-of the list.  That is, a cons cell is made for each element.  The CAR
-of the cons cell points to the element, and its CDR points to the next
-cons cell of the list, which holds the next element in the list.  The
-CDR of the last cons cell is set to point to `nil'.
-
-   A list can be illustrated by a diagram in which the cons cells are
-shown as pairs of boxes.  (The Lisp reader cannot read such an
-illustration; unlike the textual notation, which can be understood by
-both humans and computers, the box illustrations can be understood only
-by humans.)  The following represents the three-element list `(rose
-violet buttercup)':
-
-         ___ ___      ___ ___      ___ ___
-        |___|___|--> |___|___|--> |___|___|--> nil
-          |            |            |
-          |            |            |
-           --> rose     --> violet   --> buttercup
-
-   In this diagram, each box represents a slot that can refer to any
-Lisp object.  Each pair of boxes represents a cons cell.  Each arrow is
-a reference to a Lisp object, either an atom or another cons cell.
-
-   In this example, the first box, the CAR of the first cons cell,
-refers to or "contains" `rose' (a symbol).  The second box, the CDR of
-the first cons cell, refers to the next pair of boxes, the second cons
-cell.  The CAR of the second cons cell refers to `violet' and the CDR
-refers to the third cons cell.  The CDR of the third (and last) cons
-cell refers to `nil'.
-
-   Here is another diagram of the same list, `(rose violet buttercup)',
-sketched in a different manner:
-
-      ---------------       ----------------       -------------------
-     | car   | cdr   |     | car    | cdr   |     | car       | cdr   |
-     | rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
-     |       |       |     |        |       |     |           |       |
-      ---------------       ----------------       -------------------
-
-   A list with no elements in it is the "empty list"; it is identical
-to the symbol `nil'.  In other words, `nil' is both a symbol and a list.
-
-   Here are examples of lists written in Lisp syntax:
-
-     (A 2 "A")            ; A list of three elements.
-     ()                   ; A list of no elements (the empty list).
-     nil                  ; A list of no elements (the empty list).
-     ("A ()")             ; A list of one element: the string `"A ()"'.
-     (A ())               ; A list of two elements: `A' and the empty list.
-     (A nil)              ; Equivalent to the previous.
-     ((A B C))            ; A list of one element
-                          ;   (which is a list of three elements).
-
-   Here is the list `(A ())', or equivalently `(A nil)', depicted with
-boxes and arrows:
-
-         ___ ___      ___ ___
-        |___|___|--> |___|___|--> nil
-          |            |
-          |            |
-           --> A        --> nil
+
+\1f
+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:
 
 
 * Menu:
 

-* Dotted Pair Notation::        An alternative syntax for lists.
-* Association List Type::       A specially constructed list.
+* Speed of Byte-Code::          An example of speedup from byte compilation.
+* Compilation Functions::       Byte compilation functions.
+* Compilation Options::         Controlling the byte compiler's behavior.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Dotted Pair Notation,  Next: Association List Type,  Up: Cons Cell Type
+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.

 
 

-Dotted Pair Notation
-....................
+\1f
+File: lispref.info,  Node: Compilation Functions,  Next: Compilation Options,  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
+     When non-`nil', `byte-recompile-directory' will continue compiling
+     even when an error occurs in a file.  Default: `nil', but bound to
+     `t' by `batch-byte-recompile-directory'.
+
+ - Variable: byte-recompile-directory-recursively
+     When non-`nil', `byte-recompile-directory' will recurse on
+     subdirectories.  Default: `t'.
+
+ - 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.

 
 

-   "Dotted pair notation" is an alternative syntax for cons cells that
-represents the CAR and CDR explicitly.  In this syntax, `(A . B)'
-stands for a cons cell whose CAR is the object A, and whose CDR is the
-object B.  Dotted pair notation is therefore more general than list
-syntax.  In the dotted pair notation, the list `(1 2 3)' is written as
-`(1 .  (2 . (3 . nil)))'.  For `nil'-terminated lists, the two
-notations produce the same result, but list notation is usually clearer
-and more convenient when it is applicable.  When printing a list, the
-dotted pair notation is only used if the CDR of a cell is not a list.
-
-   Here's how box notation can illustrate dotted pairs.  This example
-shows the pair `(rose . violet)':
-
-         ___ ___
-        |___|___|--> violet
-          |
-          |
-           --> rose
-
-   Dotted pair notation can be combined with list notation to represent
-a chain of cons cells with a non-`nil' final CDR.  For example, `(rose
-violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
-The object looks like this:
-
-         ___ ___      ___ ___
-        |___|___|--> |___|___|--> buttercup
-          |            |
-          |            |
-           --> rose     --> violet
-
-   These diagrams make it evident why `(rose . violet . buttercup)' is
-invalid syntax; it would require a cons cell that has three parts
-rather than two.
-
-   The list `(rose violet)' is equivalent to `(rose . (violet))' and
-looks like this:
-
-         ___ ___      ___ ___
-        |___|___|--> |___|___|--> nil
-          |            |
-          |            |
-           --> rose     --> violet
-
-   Similarly, the three-element list `(rose violet buttercup)' is
-equivalent to `(rose . (violet . (buttercup)))'.  It looks like this:
-
-         ___ ___      ___ ___      ___ ___
-        |___|___|--> |___|___|--> |___|___|--> nil
-          |            |            |
-          |            |            |
-           --> rose     --> violet   --> buttercup
-
-\1f
-File: lispref.info,  Node: Association List Type,  Prev: Dotted Pair Notation,  Up: Cons Cell Type
-
-Association List Type
-.....................
+\1f
+File: lispref.info,  Node: Compilation Options,  Next: Docs and Compilation,  Prev: Compilation Functions,  Up: Byte Compilation
+
+Options for the Byte Compiler
+=============================
+
+Warning: this node is a quick draft based on docstrings.  There may be
+inaccuracies, as the docstrings occasionally disagree with each other.
+This has not been checked yet.
+
+   The byte compiler and optimizer are controlled by the following
+variables.  The `byte-compiler-options' macro described below provides
+a convenient way to set most of them on a file-by-file basis.

 
 

-   An "association list" or "alist" is a specially-constructed list
-whose elements are cons cells.  In each element, the CAR is considered
-a "key", and the CDR is considered an "associated value".  (In some
-cases, the associated value is stored in the CAR of the CDR.)
-Association lists are often used as stacks, since it is easy to add or
-remove associations at the front of the list.
+ - Variable: emacs-lisp-file-regexp
+     Regexp which matches Emacs Lisp source files.  You may want to
+     redefine `byte-compile-dest-file' if you change this.  Default:
+     `"\\.el$"'.

 
 

-   For example,
+ - Function: byte-compile-dest-file filename
+     Convert an Emacs Lisp source file name to a compiled file name.
+     This function may be redefined by the user, if necessary, for
+     compatibility with `emacs-lisp-file-regexp'.

 
 

-     (setq alist-of-colors
-           '((rose . red) (lily . white)  (buttercup . yellow)))
+ - Variable: byte-compile-verbose
+     When non-`nil', print messages describing progress of
+     byte-compiler.  Default: `t' if interactive on a not-too-slow
+     terminal (see `search-slow-speed'), otherwise `nil'.

 
 

-sets the variable `alist-of-colors' to an alist of three elements.  In
-the first element, `rose' is the key and `red' is the value.
+ - Variable: byte-optimize
+     Level of optimization in the byte compiler.

 
 

-   *Note Association Lists::, for a further explanation of alists and
-for functions that work on alists.
+    `nil'
+          Do no optimization.
+
+    `t'
+          Do all optimizations.
+
+    `source'
+          Do optimizations manipulating the source code only.
+
+    `byte'
+          Do optimizations manipulating the byte code (actually, LAP
+          code) only.
+     Default: `t'.
+
+ - Variable: byte-compile-delete-errors
+     When non-`nil', the optimizer may delete forms that may signal an
+     error if that is the only change in the function's behavior.  This
+     includes variable references and calls to functions such as `car'.
+     Default: `t'.
+
+ - Variable: byte-optimize-log nil
+     When non-`nil', the byte-compiler logs optimizations into
+     `*Compile-Log*'.
+
+    `nil'
+          Log no optimization.
+
+    `t'
+          Log all optimizations.
+
+    `source'
+          Log optimizations manipulating the source code only.
+
+    `byte'
+          Log optimizations manipulating the byte code (actually, LAP
+          code) only.
+     Default: `nil'.
+
+ - Variable: byte-compile-error-on-warn
+     When non-`nil', the byte-compiler reports warnings with `error'.
+     Default:  `nil'.
+
+ - Variable: byte-compile-default-warnings
+     The warnings used when `byte-compile-warnings' is `t'.  Called
+     `byte-compile-warning-types' in GNU Emacs.  Default: `(redefine
+     callargs subr-callargs free-vars unresolved unused-vars obsolete)'.
+
+ - Variable: byte-compile-warnings
+     List of warnings that the compiler should issue (`t' for the
+     default set).  Elements of the list may be:
+
+    `free-vars'
+          References to variables not in the current lexical scope.
+
+    `unused-vars'
+          References to non-global variables bound but not referenced.
+
+    `unresolved'
+          Calls to unknown functions.
+
+    `callargs'
+          Lambda calls with args that don't match the definition.
+
+    `subr-callargs'
+          Calls to subrs with args that don't match the definition.
+
+    `redefine'
+          Function cell redefined from a macro to a lambda or vice
+          versa, or redefined to take a different number of arguments.
+
+    `obsolete'
+          Use of an obsolete function or variable.
+
+    `pedantic'
+          Warn of use of compatible symbols.
+
+     The default set is specified by `byte-compile-default-warnings' and
+     normally encompasses all possible warnings.
+
+     See also the macro `byte-compiler-options'.  Default: `t'.
+
+   The compiler can generate a call graph, which gives information about
+which functions call which functions.
+
+ - Variable: byte-compile-generate-call-tree
+     When non-`nil', the compiler generates a call graph.  This records
+     functions that were called and from where.  If the value is `t',
+     compilation displays the call graph when it finishes.  If the
+     value is neither `t' nor `nil', compilation asks you whether to
+     display the graph.
+
+     The call tree only lists functions called, not macros used. Those
+     functions which the byte-code interpreter knows about directly
+     (`eq', `cons', etc.) are not reported.
+
+     The call tree also lists those functions which are not known to be
+     called (that is, to which no calls have been compiled).  Functions
+     which can be invoked interactively are excluded from this list.
+     Default: `nil'.
+
+ - Variable: byte-compile-call-tree nil
+     Alist of functions and their call tree, used internally.  Each
+     element takes the form
+
+     (FUNCTION CALLERS CALLS)
+
+     where CALLERS is a list of functions that call FUNCTION, and CALLS
+     is a list of functions for which calls were generated while
+     compiling FUNCTION.
+
+ - Variable: byte-compile-call-tree-sort
+     When non-`nil', sort the call tree.  The values `name', `callers',
+     `calls', and `calls+callers' specify different fields to sort
+     on.")  Default: `name'.
+
+   `byte-compile-overwrite-file' controls treatment of existing
+compiled files.
+
+ - Variable: byte-compile-overwrite-file
+     When non-`nil', do not preserve backups of `.elc's.  Precisely, if
+     `nil', old `.elc' files are deleted before the new one is saved,
+     and `.elc' files will have the same modes as the corresponding
+     `.el' file.  Otherwise, existing `.elc' files will simply be
+     overwritten, and the existing modes will not be changed.  If this
+     variable is `nil', then an `.elc' file which is a symbolic link
+     will be turned into a normal file, instead of the file which the
+     link points to being overwritten.  Default: `t'.
+
+   Variables controlling recompiling directories are described elsewhere
+*Note Compilation Functions::.  They are
+`byte-recompile-directory-ignore-errors-p' and
+`byte-recompile-directory-recursively'.
+
+   The dynamic loading features are described elsewhere.  These are
+controlled by the variables `byte-compile-dynamic' (*note Dynamic
+Loading::) and `byte-compile-dynamic-docstrings' (*note Docs and
+Compilation::).
+
+   The byte compiler is a relatively recent development, and has evolved
+significantly over the period covering Emacs versions 19 and 20.  The
+following variables control use of newer functionality by the byte
+compiler.  These are rarely needed since the release of XEmacs 21.
+
+   Another set of compatibility issues arises between Mule and non-Mule
+XEmacsen; there are no known compatibility issues specific to the byte
+compiler.  There are also compatibility issues between XEmacs and GNU
+Emacs's versions of the byte compiler.  While almost all of the byte
+codes are the same, and code compiled by one version often runs
+perfectly well on the other, this is very dangerous, and can result in
+crashes or data loss.  Always recompile your Lisp when moving between
+XEmacs and GNU Emacs.
+
+ - Variable: byte-compile-single-version nil
+     When non-`nil', the choice of emacs version (v19 or v20) byte-codes
+     will be hard-coded into bytecomp when it compiles itself.  If the
+     compiler itself is compiled with optimization, this causes a
+     speedup.  Default: `nil'.
+
+ - Variable: byte-compile-emacs19-compatibility
+     When non-`nil' generate output that can run in Emacs 19.  Default:
+     `nil' when Emacs version is 20 or above, otherwise `t'.
+
+ - Variable: byte-compile-print-gensym
+     When non-`nil', the compiler may generate code that creates unique
+     symbols at run-time.  This is achieved by printing uninterned
+     symbols using the `#:' notation, so that they will be read
+     uninterned when run.
+
+     With this feature, code that uses uninterned symbols in macros will
+     not be runnable under pre-21.0 XEmacsen.
+
+     Default: When `byte-compile-emacs19-compatibility' is non-nil, this
+     variable is ignored and considered to be `nil'.  Otherwise `t'.
+
+ - Variable: byte-compile-new-bytecodes
+     This is completely ignored.  For backwards compatibility.
+
+ - Function: byte-compiler-options &rest args
+     Set some compilation-parameters for this file.  This will affect
+     only the file in which it appears; this does nothing when
+     evaluated, or when loaded from a `.el' file.
+
+     Each argument to this macro must be a list of a key and a value.
+     (#### Need to check whether the newer variables are settable here.)
+
+            Keys:                Values:               Corresponding variable:
+          
+            verbose      t, nil                byte-compile-verbose
+            optimize     t, nil, source, byte  byte-optimize
+            warnings     list of warnings      byte-compile-warnings
+            file-format          emacs19, emacs20      byte-compile-emacs19-compatibility
+
+     The value specified with the `warnings'option must be a list,
+     containing some subset of the following flags:
+
+            free-vars  references to variables not in the current lexical scope.
+            unused-vars        references to non-global variables bound but not referenced.
+            unresolved calls to unknown functions.
+            callargs   lambda calls with args that don't match the definition.
+            redefine   function cell redefined from a macro to a lambda or vice
+                       versa, or redefined to take a different number of arguments.
+
+     If the first element if the list is `+' or ``' then the specified
+     elements are added to or removed from the current set of warnings,
+     instead of the entire set of warnings being overwritten.  (####
+     Need to check whether the newer warnings are settable here.)
+
+     For example, something like this might appear at the top of a
+     source file:
+
+              (byte-compiler-options
+                (optimize t)
+                (warnings (- callargs))                ; Don't warn about arglist mismatch
+                (warnings (+ unused-vars))     ; Do warn about unused bindings
+                (file-format emacs19))

 
 \1f
 
 \1f

-File: lispref.info,  Node: Array Type,  Next: String Type,  Prev: Cons Cell Type,  Up: Programming Types
+File: lispref.info,  Node: Docs and Compilation,  Next: Dynamic Loading,  Prev: Compilation Options,  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.
+     Default: t.
+
+   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.

 
 

-Array Type
-----------
+\1f
+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.  Default: nil.
+
+ - 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.

 
 

-   An "array" is composed of an arbitrary number of slots for referring
-to other Lisp objects, arranged in a contiguous block of memory.
-Accessing any element of an array takes the same amount of time.  In
-contrast, accessing an element of a list requires time proportional to
-the position of the element in the list.  (Elements at the end of a
-list take longer to access than elements at the beginning of a list.)
+\1f
+File: lispref.info,  Node: Eval During Compile,  Next: Compiled-Function Objects,  Prev: Dynamic Loading,  Up: Byte Compilation

 
 

-   XEmacs defines three types of array, strings, vectors, and bit
-vectors.  A string is an array of characters, a vector is an array of
-arbitrary objects, and a bit vector is an array of 1's and 0's.  All are
-one-dimensional.  (Most other programming languages support
-multidimensional arrays, but they are not essential; you can get the
-same effect with an array of arrays.)  Each type of array has its own
-read syntax; see *Note String Type::, *Note Vector Type::, and *Note
-Bit Vector Type::.
+Evaluation During Compilation
+=============================

 
 

-   An array may have any length up to the largest integer; but once
-created, it has a fixed size.  The first element of an array has index
-zero, the second element has index 1, and so on.  This is called
-"zero-origin" indexing.  For example, an array of four elements has
-indices 0, 1, 2, and 3.
+These features permit you to write code to be evaluated during
+compilation of a program.

 
 

-   The array type is contained in the sequence type and contains the
-string type, the vector type, and the bit vector type.
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: String Type,  Next: Vector Type,  Prev: Array Type,  Up: Programming Types
+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::.

 
 

-String Type
------------
+\1f
+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

 
 

-   A "string" is an array of characters.  Strings are used for many
-purposes in XEmacs, as can be expected in a text editor; for example, as
-the names of Lisp symbols, as messages for the user, and to represent
-text extracted from buffers.  Strings in Lisp are constants: evaluation
-of a string returns the same string.
-
-   The read syntax for strings is a double-quote, an arbitrary number of
-characters, and another double-quote, `"like this"'.  The Lisp reader
-accepts the same formats for reading the characters of a string as it
-does for reading single characters (without the question mark that
-begins a character literal).  You can enter a nonprinting character such
-as tab or `C-a' using the convenient escape sequences, like this: `"\t,
-\C-a"'.  You can include a double-quote in a string by preceding it
-with a backslash; thus, `"\""' is a string containing just a single
-double-quote character.  (*Note Character Type::, for a description of
-the read syntax for characters.)
-
-   The printed representation of a string consists of a double-quote,
-the characters it contains, and another double-quote.  However, you must
-escape any backslash or double-quote characters in the string with a
-backslash, like this: `"this \" is an embedded quote"'.
-
-   The newline character is not special in the read syntax for strings;
-if you write a new line between the double-quotes, it becomes a
-character in the string.  But an escaped newline--one that is preceded
-by `\'--does not become part of the string; i.e., the Lisp reader
-ignores an escaped newline while reading a string.
-
-     "It is useful to include newlines
-     in documentation strings,
-     but the newline is \
-     ignored if escaped."
-          => "It is useful to include newlines
-     in documentation strings,
-     but the newline is ignored if escaped."
-
-   A string can hold extents and properties of the text it contains, in
-addition to the characters themselves.  This enables programs that copy
-text between strings and buffers to preserve the extents and properties
-with no special effort.  *Note Extents::, *Note Text Properties::.
-
-   Note that FSF GNU Emacs has a special read and print syntax for
-strings with text properties, but XEmacs does not currently implement
-this.  It was judged better not to include this in XEmacs because it
-entails that `equal' return `nil' when passed a string with text
-properties and the equivalent string without text properties, which is
-often counter-intuitive.
-
-   *Note Strings and Characters::, for functions that work on strings.
-
-\1f
-File: lispref.info,  Node: Vector Type,  Next: Bit Vector Type,  Prev: String Type,  Up: Programming Types
-
-Vector Type
------------
+\1f
+File: lispref.info,  Node: Different Behavior,  Prev: Disassembly,  Up: Byte Compilation
+
+Different Behavior
+==================

 
 

-   A "vector" is a one-dimensional array of elements of any type.  It
-takes a constant amount of time to access any element of a vector.  (In
-a list, the access time of an element is proportional to the distance of
-the element from the beginning of the list.)
+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.

 
 

-   The printed representation of a vector consists of a left square
-bracket, the elements, and a right square bracket.  This is also the
-read syntax.  Like numbers and strings, vectors are considered constants
-for evaluation.
+   * 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.

 
 

-     [1 "two" (three)]      ; A vector of three elements.
-          => [1 "two" (three)]
+   * 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.

 
 

-   *Note Vectors::, for functions that work with vectors.
+     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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Bit Vector Type,  Next: Function Type,  Prev: Vector Type,  Up: Programming Types
+File: lispref.info,  Node: Debugging,  Next: Read and Print,  Prev: Byte Compilation,  Up: Top

 
 

-Bit Vector Type
----------------
+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::.

 
 

-   A "bit vector" is a one-dimensional array of 1's and 0's.  It takes
-a constant amount of time to access any element of a bit vector, as for
-vectors.  Bit vectors have an extremely compact internal representation
-(one machine bit per element), which makes them ideal for keeping track
-of unordered sets, large collections of boolean values, etc.
+\1f
+File: lispref.info,  Node: Debugger,  Next: Syntax Errors,  Up: Debugging
+
+The Lisp Debugger
+=================

 
 

-   The printed representation of a bit vector consists of `#*' followed
-by the bits in the vector.  This is also the read syntax.  Like
-numbers, strings, and vectors, bit vectors are considered constants for
-evaluation.
+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::.

 
 

-     #*00101000      ; A bit vector of eight elements.
-          => #*00101000
+* Menu:

 
 

-   *Note Bit Vectors::, for functions that work with bit vectors.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Function Type,  Next: Macro Type,  Prev: Bit Vector Type,  Up: Programming Types
+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)))

 
 

-Function Type
--------------
+\1f
+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.

 
 

-   Just as functions in other programming languages are executable,
-"Lisp function" objects are pieces of executable code.  However,
-functions in Lisp are primarily Lisp objects, and only secondarily the
-text which represents them.  These Lisp objects are lambda expressions:
-lists whose first element is the symbol `lambda' (*note Lambda
-Expressions::).
+   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.

 
 

-   In most programming languages, it is impossible to have a function
-without a name.  In Lisp, a function has no intrinsic name.  A lambda
-expression is also called an "anonymous function" (*note Anonymous
-Functions::).  A named function in Lisp is actually a symbol with a
-valid function in its function cell (*note Defining Functions::).
+   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.

 
 

-   Most of the time, functions are called when their names are written
-in Lisp expressions in Lisp programs.  However, you can construct or
-obtain a function object at run time and then call it with the primitive
-functions `funcall' and `apply'.  *Note Calling Functions::.
+ - 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::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Macro Type,  Next: Primitive Function Type,  Prev: Function Type,  Up: Programming Types
+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.

 
 

-Macro Type
-----------
+\1f
+File: lispref.info,  Node: Explicit Debug,  Next: Using Debugger,  Prev: Function Debugging,  Up: Debugger
+
+Explicit Entry to the Debugger
+------------------------------

 
 

-   A "Lisp macro" is a user-defined construct that extends the Lisp
-language.  It is represented as an object much like a function, but with
-different parameter-passing semantics.  A Lisp macro has the form of a
-list whose first element is the symbol `macro' and whose CDR is a Lisp
-function object, including the `lambda' symbol.
+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!

 
 

-   Lisp macro objects are usually defined with the built-in `defmacro'
-function, but any list that begins with `macro' is a macro as far as
-XEmacs is concerned.  *Note Macros::, for an explanation of how to
-write a macro.
+   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::).

 
 \1f
 
 \1f

-File: lispref.info,  Node: Primitive Function Type,  Next: Compiled-Function Type,  Prev: Macro Type,  Up: Programming Types
+File: lispref.info,  Node: Using Debugger,  Next: Debugger Commands,  Prev: Explicit Debug,  Up: Debugger

 
 

-Primitive Function Type
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Excess Open,  Next: Excess Close,  Up: Syntax Errors
+
+Excess Open Parentheses

 -----------------------
 
 -----------------------
 

-   A "primitive function" is a function callable from Lisp but written
-in the C programming language.  Primitive functions are also called
-"subrs" or "built-in functions".  (The word "subr" is derived from
-"subroutine".)  Most primitive functions evaluate all their arguments
-when they are called.  A primitive function that does not evaluate all
-its arguments is called a "special form" (*note Special Forms::).
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.

 
 

-   It does not matter to the caller of a function whether the function
-is primitive.  However, this does matter if you try to substitute a
-function written in Lisp for a primitive of the same name.  The reason
-is that the primitive function may be called directly from C code.
-Calls to the redefined function from Lisp will use the new definition,
-but calls from C code may still use the built-in definition.
+   * Set conditional or unconditional breakpoints, install embedded
+     breakpoints, or a global break event.

 
 

-   The term "function" refers to all Emacs functions, whether written
-in Lisp or C.  *Note Function Type::, for information about the
-functions written in Lisp.
+   * Trace slow or fast stopping briefly at each stop point, or each
+     breakpoint.

 
 

-   Primitive functions have no read syntax and print in hash notation
-with the name of the subroutine.
+   * 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.
+
+\1f
+File: lispref.info,  Node: Using Edebug,  Next: Instrumenting,  Up: Edebug
+
+Using Edebug
+------------

 
 

-     (symbol-function 'car)          ; Access the function cell
-                                     ;   of the symbol.
-          => #<subr car>
-     (subrp (symbol-function 'car))  ; Is this a primitive function?
-          => t                       ; Yes.
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Compiled-Function Type,  Next: Autoload Type,  Prev: Primitive Function Type,  Up: Programming Types
+File: lispref.info,  Node: Instrumenting,  Next: Edebug Execution Modes,  Prev: Using Edebug,  Up: Edebug

 
 

-Compiled-Function Type
+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.
+
+\1f
+File: lispref.info,  Node: Edebug Execution Modes,  Next: Jumping,  Prev: Instrumenting,  Up: Edebug
+
+Edebug Execution Modes

 ----------------------
 
 ----------------------
 

-   The byte compiler produces "compiled-function objects".  The
-evaluator handles this data type specially when it appears as a function
-to be called.  *Note Byte Compilation::, for information about the byte
-compiler.
+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'.
+
+\1f
+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.

 
 

-   The printed representation for a compiled-function object is normally
-`#<compiled-function...>'.  If `print-readably' is true, however, it is
-`#[...]'.
+`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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Autoload Type,  Next: Char Table Type,  Prev: Compiled-Function Type,  Up: Programming Types
+File: lispref.info,  Node: Edebug Misc,  Next: Breakpoints,  Prev: Jumping,  Up: Edebug

 
 

-Autoload Type
+Miscellaneous

 -------------
 
 -------------
 

-   An "autoload object" is a list whose first element is the symbol
-`autoload'.  It is stored as the function definition of a symbol as a
-placeholder for the real definition; it says that the real definition
-is found in a file of Lisp code that should be loaded when necessary.
-The autoload object contains the name of the file, plus some other
-information about the real definition.
+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').

 
 

-   After the file has been loaded, the symbol should have a new function
-definition that is not an autoload object.  The new definition is then
-called as if it had been there to begin with.  From the user's point of
-view, the function call works as expected, using the function definition
-in the loaded file.
+`r'
+     Redisplay the most recently known expression result in the echo
+     area (`edebug-previous-result').

 
 

-   An autoload object is usually created with the function `autoload',
-which stores the object in the function cell of a symbol.  *Note
-Autoload::, for more details.
+`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'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Char Table Type,  Next: Hash Table Type,  Prev: Autoload Type,  Up: Programming Types
+File: lispref.info,  Node: Breakpoints,  Next: Trapping Errors,  Prev: Edebug Misc,  Up: Edebug

 
 

-Char Table Type
----------------
+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.

 
 

-   (not yet documented)
+* Menu:
+
+* Global Break Condition::     Breaking on an event.
+* Embedded Breakpoints::       Embedding breakpoints in code.
+
+\1f
+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.
+
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Hash Table Type,  Next: Range Table Type,  Prev: Char Table Type,  Up: Programming Types
+File: lispref.info,  Node: Trapping Errors,  Next: Edebug Views,  Prev: Breakpoints,  Up: Edebug

 
 

-Hash Table Type
+Trapping Errors

 ---------------
 
 ---------------
 

-   A "hash table" is a table providing an arbitrary mapping from one
-Lisp object to another, using an internal indexing method called
-"hashing".  Hash tables are very fast (much more efficient that using
-an association list, when there are a large number of elements in the
-table).
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.

 
 

-   Hash tables have a special read syntax beginning with
-`#s(hash-table' (this is an example of "structure" read syntax.  This
-notation is also used for printing when `print-readably' is `t'.
+\1f
+File: lispref.info,  Node: Printing in Edebug,  Next: Tracing,  Prev: Reading in Edebug,  Up: Edebug

 
 

-   Otherwise they print in hash notation (The "hash" in "hash notation"
-has nothing to do with the "hash" in "hash table"), giving the number
-of elements, total space allocated for elements, and a unique number
-assigned at the time the hash table was created. (Hash tables
-automatically resize as necessary so there is no danger of running out
-of space for elements.)
+Printing in Edebug
+------------------

 
 

-     (make-hash-table :size 50)
-          => #<hash-table 0/107 0x313a>
+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.

 
 

-   *Note Hash Tables::, for information on how to create and work with
-hash tables.
+\1f
+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.)

 
 \1f
 
 \1f

-File: lispref.info,  Node: Range Table Type,  Next: Weak List Type,  Prev: Hash Table Type,  Up: Programming Types
+File: lispref.info,  Node: Coverage Testing,  Next: The Outside Context,  Prev: Tracing,  Up: Edebug

 
 

-Range Table Type
+Coverage Testing

 ----------------
 
 ----------------
 

-   A "range table" is a table that maps from ranges of integers to
-arbitrary Lisp objects.  Range tables automatically combine overlapping
-ranges that map to the same Lisp object, and operations are provided
-for mapping over all of the ranges in a range table.
+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.
+
+\1f
+File: lispref.info,  Node: The Outside Context,  Next: Instrumenting Macro Calls,  Prev: Coverage Testing,  Up: Edebug
+
+The Outside Context
+-------------------

 
 

-   Range tables have a special read syntax beginning with
-`#s(range-table' (this is an example of "structure" read syntax, which
-is also used for char tables and faces).
+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.

 
 

-     (setq x (make-range-table))
-     (put-range-table 20 50 'foo x)
-     (put-range-table 100 200 "bar" x)
-     x
-          => #s(range-table data ((20 50) foo (100 200) "bar"))
+* Menu:

 
 

-   *Note Range Tables::, for information on how to create and work with
-range tables.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Weak List Type,  Prev: Range Table Type,  Up: Programming Types
+File: lispref.info,  Node: Checking Whether to Stop,  Next: Edebug Display Update,  Up: The Outside Context

 
 

-Weak List Type
---------------
+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'.

 
 

-   (not yet documented)

 
 \1f
 
 \1f

-File: lispref.info,  Node: Editing Types,  Next: Window-System Types,  Prev: Programming Types,  Up: Lisp Data Types
+File: lispref.info,  Node: Edebug Display Update,  Next: Edebug Recursive Edit,  Prev: Checking Whether to Stop,  Up: The Outside Context

 
 

-Editing Types
-=============
+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.
+
+
+\1f
+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.

 
 

-   The types in the previous section are common to many Lisp dialects.
-XEmacs Lisp provides several additional data types for purposes
-connected with editing.
+   * `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'.
+
+
+\1f
+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:
 
 
 * Menu:
 

-* Buffer Type::         The basic object of editing.
-* Marker Type::         A position in a buffer.
-* Extent Type::         A range in a buffer or string, maybe with properties.
-* Window Type::         Buffers are displayed in windows.
-* Frame Type::         Windows subdivide frames.
-* Device Type::         Devices group all frames on a display.
-* Console Type::        Consoles group all devices with the same keyboard.
-* Window Configuration Type::   Recording the way a frame is subdivided.
-* Event Type::          An interesting occurrence in the system.
-* 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.
-* Display Table Type::  How display tables are represented.
-* Database Type::       A connection to an external DBM or DB database.
-* Charset Type::        A character set (e.g. all Kanji characters),
-                          under XEmacs/MULE.
-* Coding System Type::  An object encapsulating a way of converting between
-                          different textual encodings, under XEmacs/MULE.
-* ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
-* ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
-
-\1f
-File: lispref.info,  Node: Buffer Type,  Next: Marker Type,  Up: Editing Types
-
-Buffer Type
------------
+* 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.
+
+\1f
+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...)'.

 
 

-   A "buffer" is an object that holds text that can be edited (*note
-Buffers::).  Most buffers hold the contents of a disk file (*note
-Files::) so they can be edited, but some are used for other purposes.
-Most buffers are also meant to be seen by the user, and therefore
-displayed, at some time, in a window (*note Windows::).  But a buffer
-need not be displayed in any window.

 
 

-   The contents of a buffer are much like a string, but buffers are not
-used like strings in XEmacs Lisp, and the available operations are
-different.  For example, insertion of text into a buffer is very
-efficient, whereas "inserting" text into a string requires
-concatenating substrings, and the result is an entirely new string
-object.
+\1f
+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.

 
 

-   Each buffer has a designated position called "point" (*note
-Positions::).  At any time, one buffer is the "current buffer".  Most
-editing commands act on the contents of the current buffer in the
-neighborhood of point.  Many of the standard Emacs functions manipulate
-or test the characters in the current buffer; a whole chapter in this
-manual is devoted to describing these functions (*note Text::).
+\1f
+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.

 
 

-   Several other data structures are associated with each buffer:
+\1f
+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))

 
 

-   * a local syntax table (*note Syntax Tables::);
+\1f
+File: lispref.info,  Node: Edebug Options,  Prev: Instrumenting Macro Calls,  Up: Edebug

 
 

-   * a local keymap (*note Keymaps::);
+Edebug Options
+--------------

 
 

-   * a local variable binding list (*note Buffer-Local Variables::);
+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::.

 
 

-   * a list of extents (*note Extents::);
+\1f
+File: lispref.info,  Node: Read and Print,  Next: Minibuffers,  Prev: Debugging,  Up: Top

 
 

-   * and various other related properties.
+Reading and Printing Lisp Objects
+*********************************

 
 

-The local keymap and variable list contain entries that individually
-override global bindings or values.  These are used to customize the
-behavior of programs in different buffers, without actually changing the
-programs.
+"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::.

 
 

-   A buffer may be "indirect", which means it shares the text of
-another buffer.  *Note Indirect Buffers::.
+   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).

 
 

-   Buffers have no read syntax.  They print in hash notation, showing
-the buffer name.
+* Menu:

 
 

-     (current-buffer)
-          => #<buffer "objects.texi">
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Marker Type,  Next: Extent Type,  Prev: Buffer Type,  Up: Editing Types
+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.

 
 

-Marker Type
------------
+\1f
+File: lispref.info,  Node: Input Streams,  Next: Input Functions,  Prev: Streams Intro,  Up: Read and Print

 
 

-   A "marker" denotes a position in a specific buffer.  Markers
-therefore have two components: one for the buffer, and one for the
-position.  Changes in the buffer's text automatically relocate the
-position value as necessary to ensure that the marker always points
-between the same two characters in the buffer.
+Input Streams
+=============

 
 

-   Markers have no read syntax.  They print in hash notation, giving the
-current character position and the name of the buffer.
+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'.

 
 

-     (point-marker)
-          => #<marker at 50661 in objects.texi>
+\1f
+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'.

 
 

-   *Note Markers::, for information on how to test, create, copy, and
-move markers.
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Extent Type,  Next: Window Type,  Prev: Marker Type,  Up: Editing Types
+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.

 
 

-Extent Type
------------
+\1f
+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.

 
 

-   An "extent" specifies temporary alteration of the display appearance
-of a part of a buffer (or string).  It contains markers delimiting a
-range of the buffer, plus a property list (a list whose elements are
-alternating property names and values).  Extents are used to present
-parts of the buffer temporarily in a different display style.  They
-have no read syntax, and print in hash notation, giving the buffer name
-and range of positions.
+\1f
+File: lispref.info,  Node: Minibuffers,  Next: Command Loop,  Prev: Read and Print,  Up: Top

 
 

-   Extents can exist over strings as well as buffers; the primary use
-of this is to preserve extent and text property information as text is
-copied from one buffer to another or between different parts of a
-buffer.
+Minibuffers
+***********

 
 

-   Extents have no read syntax.  They print in hash notation, giving the
-range of text they cover, the name of the buffer or string they are in,
-the address in core, and a summary of some of the properties attached to
-the extent.
+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.

 
 

-     (extent-at (point))
-          => #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
+* Menu:

 
 

-   *Note Extents::, for how to create and use extents.
+* 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.

 
 

-   Extents are used to implement text properties.  *Note Text
-Properties::.
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Window Type,  Next: Frame Type,  Prev: Extent Type,  Up: Editing Types
+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'

 
 

-Window Type
------------
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Minibuffer History,  Next: Completion,  Prev: Object from Minibuffer,  Up: Minibuffers

 
 

-   A "window" describes the portion of the frame that XEmacs uses to
-display a buffer. (In standard window-system usage, a "window" is what
-XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to
-refer to what is called a "pane" in standard window-system usage.)
-Every window has one associated buffer, whose contents appear in the
-window.  By contrast, a given buffer may appear in one window, no
-window, or several windows.
+Minibuffer History
+==================

 
 

-   Though many windows may exist simultaneously, at any time one window
-is designated the "selected window".  This is the window where the
-cursor is (usually) displayed when XEmacs is ready for a command.  The
-selected window usually displays the current buffer, but this is not
-necessarily the case.
+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.

 
 

-   Windows are grouped on the screen into frames; each window belongs to
-one and only one frame.  *Note Frame Type::.
+   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.

 
 

-   Windows have no read syntax.  They print in hash notation, giving the
-name of the buffer being displayed and a unique number assigned at the
-time the window was created. (This number can be useful because the
-buffer displayed in any given window can change frequently.)
+   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:

 
 

-     (selected-window)
-          => #<window on "objects.texi" 0x266c>
+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).

 
 

-   *Note Windows::, for a description of the functions that work on
-windows.
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Frame Type,  Next: Device Type,  Prev: Window Type,  Up: Editing Types
+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.

 
 

-Frame Type
-----------
+* Menu:

 
 

-   A FRAME is a rectangle on the screen (a "window" in standard
-window-system terminology) that contains one or more non-overlapping
-Emacs windows ("panes" in standard window-system terminology).  A frame
-initially contains a single main window (plus perhaps a minibuffer
-window) which you can subdivide vertically or horizontally into smaller
-windows.
+* 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.

 
 

-   Frames have no read syntax.  They print in hash notation, giving the
-frame's type, name as used for resourcing, and a unique number assigned
-at the time the frame was created.
+\1f
+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.

 
 

-     (selected-frame)
-          => #<x-frame "emacs" 0x9db>
+\1f
+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::.

 
 

-   *Note Frames::, for a description of the functions that work on
-frames.
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Device Type,  Next: Console Type,  Prev: Frame Type,  Up: Editing Types
+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))

 
 

-Device Type
------------
+\1f
+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 ----------
+
+\1f
+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'.

 
 

-   A "device" represents a single display on which frames exist.
-Normally, there is only one device object, but there may be more than
-one if XEmacs is being run on a multi-headed display (e.g. an X server
-with attached color and mono screens) or if XEmacs is simultaneously
-driving frames attached to different consoles, e.g.  an X display and a
-TTY connection.
+   * `t' specifies `all-completions'.  The completion function should
+     return a list of all possible completions of the specified string.

 
 

-   Devices do not have a read syntax.  They print in hash notation,
-giving the device's type, connection name, and a unique number assigned
-at the time the device was created.
+   * `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.

 
 

-     (selected-device)
-          => #<x-device on ":0.0" 0x5b9>
+   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.

 
 

-   *Note Consoles and Devices::, for a description of several functions
-related to devices.
+   Emacs uses programmed completion when completing file names.  *Note
+File Name Completion::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Console Type,  Next: Window Configuration Type,  Prev: Device Type,  Up: Editing Types
+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.

 
 

-Console Type
-------------
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Reading a Password,  Next: Minibuffer Misc,  Prev: Multiple Queries,  Up: Minibuffers

 
 

-   A "console" represents a single keyboard to which devices (i.e.
-displays on which frames exist) are connected.  Normally, there is only
-one console object, but there may be more than one if XEmacs is
-simultaneously driving frames attached to different X servers and/or
-TTY connections. (XEmacs is capable of driving multiple X and TTY
-connections at the same time, and provides a robust mechanism for
-handling the differing display capabilities of such heterogeneous
-environments.  A buffer with embedded glyphs and multiple fonts and
-colors, for example, will display reasonably if it simultaneously
-appears on a frame on a color X display, a frame on a mono X display,
-and a frame on a TTY connection.)
+Reading a Password
+==================

 
 

-   Consoles do not have a read syntax.  They print in hash notation,
-giving the console's type, connection name, and a unique number assigned
-at the time the console was created.
+To read a password to pass to another program, you can use the function
+`read-passwd'.

 
 

-     (selected-console)
-          => #<x-console on "localhost:0" 0x5b7>
+ - 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.

 
 

-   *Note Consoles and Devices::, for a description of several functions
-related to consoles.
+     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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Window Configuration Type,  Next: Event Type,  Prev: Console Type,  Up: Editing Types
+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'.

 
 

-Window Configuration Type
--------------------------
+\1f
+File: lispref.info,  Node: Command Loop,  Next: Keymaps,  Prev: Minibuffers,  Up: Top

 
 

-   A "window configuration" stores information about the positions,
-sizes, and contents of the windows in a frame, so you can recreate the
-same arrangement of windows later.
+Command Loop
+************

 
 

-   Window configurations do not have a read syntax.  They print in hash
-notation, giving a unique number assigned at the time the window
-configuration was created.
+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.

 
 

-     (current-window-configuration)
-          => #<window-configuration 0x2db4>
+* Menu:

 
 

-   *Note Window Configurations::, for a description of several functions
-related to window configurations.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Event Type,  Next: Process Type,  Prev: Window Configuration Type,  Up: Editing Types
+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.

 
 

-Event Type
-----------
+\1f
+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:

 
 

-   (not yet documented)
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Process Type,  Next: Stream Type,  Prev: Event Type,  Up: Editing Types
+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.

 
 

-Process Type
-------------
+\1f
+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.
+
+\1f
+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
+
+\1f
+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)

 
 

-   The word "process" usually means a running program.  XEmacs itself
-runs in a process of this sort.  However, in XEmacs Lisp, a process is a
-Lisp object that designates a subprocess created by the XEmacs process.
-Programs such as shells, GDB, ftp, and compilers, running in
-subprocesses of XEmacs, extend the capabilities of XEmacs.
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Events,  Next: Reading Input,  Prev: Command Loop Info,  Up: Command Loop
+
+Events
+======

 
 

-   An Emacs subprocess takes textual input from Emacs and returns
-textual output to Emacs for further manipulation.  Emacs can also send
-signals to the subprocess.
+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.

 
 

-   Process objects have no read syntax.  They print in hash notation,
-giving the name of the process, its associated process ID, and the
-current state of the process:
+   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.

 
 

-     (process-list)
-          => (#<process "shell" pid 2909 state:run>)
+   For information about how exactly the XEmacs command loop works,
+*Note Reading Input::.

 
 

-   *Note Processes::, for information about functions that create,
-delete, return information about, send input or signals to, and receive
-output from processes.
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Stream Type,  Next: Keymap Type,  Prev: Process Type,  Up: Editing Types
+File: lispref.info,  Node: Event Types,  Next: Event Contents,  Up: Events

 
 

-Stream Type
+Event Types

 -----------
 
 -----------
 

-   A "stream" is an object that can be used as a source or sink for
-characters--either to supply characters for input or to accept them as
-output.  Many different types can be used this way: markers, buffers,
-strings, and functions.  Most often, input streams (character sources)
-obtain characters from the keyboard, a buffer, or a file, and output
-streams (character sinks) send characters to a buffer, such as a
-`*Help*' buffer, or to the echo area.
+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::.
+
+\1f
+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.

 
 

-   The object `nil', in addition to its other meanings, may be used as
-a stream.  It stands for the value of the variable `standard-input' or
-`standard-output'.  Also, the object `t' as a stream specifies input
-using the minibuffer (*note Minibuffers::) or output in the echo area
-(*note The Echo Area::).
+    `motion'
+          The mouse moved.

 
 

-   Streams have no special printed representation or read syntax, and
-print as whatever primitive type they are.
+    `misc-user'
+          Some other user action happened; typically, this is a menu
+          selection, scrollbar action, or drag and drop action.

 
 

-   *Note Read and Print::, for a description of functions related to
-streams, including parsing and printing functions.
+    `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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Keymap Type,  Next: Syntax Table Type,  Prev: Stream Type,  Up: Editing Types
+File: lispref.info,  Node: Event Predicates,  Next: Accessing Mouse Event Positions,  Prev: Event Contents,  Up: Events

 
 

-Keymap Type
------------
+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.

 
 

-   A "keymap" maps keys typed by the user to commands.  This mapping
-controls how the user's command input is executed.
+ - Function: button-press-event-p object
+     This is true if OBJECT is a mouse button-press event.

 
 

-   NOTE: In XEmacs, a keymap is a separate primitive type.  In FSF GNU
-Emacs, a keymap is actually a list whose CAR is the symbol `keymap'.
+ - Function: button-release-event-p object
+     This is true if OBJECT is a mouse button-release event.

 
 

-   *Note Keymaps::, for information about creating keymaps, handling
-prefix keys, local as well as global keymaps, and changing key bindings.
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Syntax Table Type,  Next: Display Table Type,  Prev: Keymap Type,  Up: Editing Types
+File: lispref.info,  Node: Accessing Mouse Event Positions,  Next: Accessing Other Event Info,  Prev: Event Predicates,  Up: Events

 
 

-Syntax Table Type
------------------
+Accessing the Position of a Mouse Event
+---------------------------------------

 
 

-   Under XEmacs 20, a "syntax table" is a particular type of char
-table.  Under XEmacs 19, a syntax table a vector of 256 integers.  In
-both cases, each element defines how one character is interpreted when
-it appears in a buffer.  For example, in C mode (*note Major Modes::),
-the `+' character is punctuation, but in Lisp mode it is a valid
-character in a symbol.  These modes specify different interpretations by
-changing the syntax table entry for `+'.
+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.

 
 

-   Syntax tables are used only for scanning text in buffers, not for
-reading Lisp expressions.  The table the Lisp interpreter uses to read
-expressions is built into the XEmacs source code and cannot be changed;
-thus, to change the list delimiters to be `{' and `}' instead of `('
-and `)' would be impossible.
+* Menu:

 
 

-   *Note Syntax Tables::, for details about syntax classes and how to
-make and modify syntax tables.
+* 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::

 
 \1f
 
 \1f

-File: lispref.info,  Node: Display Table Type,  Next: Database Type,  Prev: Syntax Table Type,  Up: Editing Types
+File: lispref.info,  Node: Frame-Level Event Position Info,  Next: Window-Level Event Position Info,  Up: Accessing Mouse Event Positions

 
 

-Display Table Type
-------------------
+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.

 
 

-   A "display table" specifies how to display each character code.
-Each buffer and each window can have its own display table.  A display
-table is actually a vector of length 256, although in XEmacs 20 this may
-change to be a particular type of char table.  *Note Display Tables::.
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Database Type,  Next: Charset Type,  Prev: Display Table Type,  Up: Editing Types
+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.

 
 

-Database Type
--------------
+\1f
+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.

 
 

-   (not yet documented)
+\1f
+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'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Charset Type,  Next: Coding System Type,  Prev: Database Type,  Up: Editing Types
+File: lispref.info,  Node: Event Toolbar Position Info,  Next: Other Event Position Info,  Prev: Event Glyph Position Info,  Up: Accessing Mouse Event Positions

 
 

-Charset Type
-------------
+Event Toolbar Position Info
+...........................

 
 

-   (not yet documented)
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Coding System Type,  Next: ToolTalk Message Type,  Prev: Charset Type,  Up: Editing Types
+File: lispref.info,  Node: Other Event Position Info,  Prev: Event Toolbar Position Info,  Up: Accessing Mouse Event Positions

 
 

-Coding System Type
-------------------
+Other Event Position Info
+.........................

 
 

-   (not yet documented)
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: ToolTalk Message Type,  Next: ToolTalk Pattern Type,  Prev: Coding System Type,  Up: Editing Types
+File: lispref.info,  Node: Accessing Other Event Info,  Next: Working With Events,  Prev: Accessing Mouse Event Positions,  Up: Events

 
 

-ToolTalk Message Type
----------------------
+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.

 
 

-   (not yet documented)
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: ToolTalk Pattern Type,  Prev: ToolTalk Message Type,  Up: Editing Types
+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.

 
 

-ToolTalk Pattern Type
----------------------
+\1f
+File: lispref.info,  Node: Converting Events,  Prev: Working With Events,  Up: Events
+
+Converting Events
+-----------------

 
 

-   (not yet documented)
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Window-System Types,  Next: Type Predicates,  Prev: Editing Types,  Up: Lisp Data Types
+File: lispref.info,  Node: Reading Input,  Next: Waiting,  Prev: Events,  Up: Command Loop
+
+Reading Input
+=============

 
 

-Window-System Types
-===================
+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.

 
 

-   XEmacs also has some types that represent objects such as faces
-(collections of display characters), fonts, and pixmaps that are
-commonly found in windowing systems.
+   For higher-level input facilities, see *Note Minibuffers::.

 
 * Menu:
 
 
 * Menu:
 

-* Face Type::           A collection of display characteristics.
-* Glyph Type::          An image appearing in a buffer or elsewhere.
-* Specifier Type::      A way of controlling display characteristics on
-                          a per-buffer, -frame, -window, or -device level.
-* Font Instance Type::  The way a font appears on a particular device.
-* Color Instance Type:: The way a color appears on a particular device.
-* Image Instance Type:: The way an image appears on a particular device.
-* Toolbar Button Type:: An object representing a button in a toolbar.
-* Subwindow Type::      An externally-controlled window-system window
-                          appearing in a buffer.
-* X Resource Type::     A miscellaneous X resource, if Epoch support was
-                          compiled into XEmacs.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Face Type,  Next: Glyph Type,  Up: Window-System Types
+File: lispref.info,  Node: Key Sequence Input,  Next: Reading One Event,  Up: Reading Input

 
 

-Face Type
----------
+Key Sequence Input
+------------------

 
 

-   (not yet documented)
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Glyph Type,  Next: Specifier Type,  Prev: Face Type,  Up: Window-System Types
+File: lispref.info,  Node: Reading One Event,  Next: Dispatching an Event,  Prev: Key Sequence Input,  Up: Reading Input

 
 

-Glyph Type
-----------
+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.
+
+\1f
+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).
+
+\1f
+File: lispref.info,  Node: Quoted Character Input,  Next: Peeking and Discarding,  Prev: Dispatching an Event,  Up: Reading Input
+
+Quoted Character Input
+----------------------

 
 

-   (not yet documented)
+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

 
 

diff --git a/info/lispref.info-4 b/info/lispref.info-4
index 5f78301..114aa7a 100644 (file)
--- a/info/lispref.info-4
+++ b/info/lispref.info-4
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1455 +50,7022 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: Specifier Type,  Next: Font Instance Type,  Prev: Glyph Type,  Up: Window-System Types
+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 an
+     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
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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)
+            ...
+
+\1f
+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)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 ]
+       )
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+File: lispref.info,  Node: Dialog Boxes,  Next: Toolbar,  Prev: Menus,  Up: Top
+
+Dialog Boxes
+************
+
+* Menu:
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+\1f
+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 ]+ ] ')'
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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::).
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Buffer Tabs,  Next: Progress Bars,  Up: Common Gutter Widgets
+
+Buffer Tabs
+-----------
+
+Not documented yet.
+
+\1f
+File: lispref.info,  Node: Progress Bars,  Prev: Buffer Tabs,  Up: Common Gutter Widgets
+
+Progress Bars
+-------------
+
+Not documented yet.
+
+\1f
+File: lispref.info,  Node: Scrollbars,  Next: Drag and Drop,  Prev: Gutter,  Up: Top
+
+Scrollbars
+**********
+
+Not yet documented.
+
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Supported Protocols,  Next: Drop Interface,  Up: Drag and Drop

 
 

-Specifier Type
---------------
+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:

 
 

-   (not yet documented)
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Font Instance Type,  Next: Color Instance Type,  Prev: Specifier Type,  Up: Window-System Types
+File: lispref.info,  Node: OffiX DND,  Next: CDE dt,  Up: Supported Protocols

 
 

-Font Instance Type
-------------------
+OffiX DND
+---------

 
 

-   (not yet documented)
+_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/

 
 \1f
 
 \1f

-File: lispref.info,  Node: Color Instance Type,  Next: Image Instance Type,  Prev: Font Instance Type,  Up: Window-System Types
+File: lispref.info,  Node: CDE dt,  Next: MSWindows OLE,  Prev: OffiX DND,  Up: Supported Protocols

 
 

-Color Instance Type
--------------------
+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.

 
 

-   (not yet documented)
+   Buffer drags are always converted to plain text.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Image Instance Type,  Next: Toolbar Button Type,  Prev: Color Instance Type,  Up: Window-System Types
+File: lispref.info,  Node: MSWindows OLE,  Next: Loose ends,  Prev: CDE dt,  Up: Supported Protocols

 
 

-Image Instance Type
--------------------
+MSWindows OLE
+-------------

 
 

-   (not yet documented)
+Only allows file drags and drops.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Toolbar Button Type,  Next: Subwindow Type,  Prev: Image Instance Type,  Up: Window-System Types
+File: lispref.info,  Node: Loose ends,  Prev: MSWindows OLE,  Up: Supported Protocols

 
 

-Toolbar Button Type
--------------------
+Loose ends
+----------

 
 

-   (not yet documented)
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Subwindow Type,  Next: X Resource Type,  Prev: Toolbar Button Type,  Up: Window-System Types
+File: lispref.info,  Node: Drop Interface,  Next: Drag Interface,  Prev: Supported Protocols,  Up: Drag and Drop
+
+Drop Interface
+==============
+
+For each activated low-level protocol, an internal routine will catch
+incoming drops and convert them to a dragdrop-drop type misc-user-event.

 
 

-Subwindow Type
---------------
+   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.

 
 

-   (not yet documented)
+   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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: X Resource Type,  Prev: Subwindow Type,  Up: Window-System Types
+File: lispref.info,  Node: Drag Interface,  Prev: Drop Interface,  Up: Drag and Drop

 
 

-X Resource Type
----------------
+Drag Interface
+==============

 
 

-   (not yet documented)
+This describes the drag API (not implemented yet).

 
 \1f
 
 \1f

-File: lispref.info,  Node: Type Predicates,  Next: Equality Predicates,  Prev: Window-System Types,  Up: Lisp Data Types
+File: lispref.info,  Node: Modes,  Next: Documentation,  Prev: Drag and Drop,  Up: Top

 
 

-Type Predicates
-===============
+Major and Minor Modes
+*********************

 
 

-   The XEmacs Lisp interpreter itself does not perform type checking on
-the actual arguments passed to functions when they are called.  It could
-not do so, since function arguments in Lisp do not have declared data
-types, as they do in other programming languages.  It is therefore up to
-the individual function to test whether each actual argument belongs to
-a type that the function can use.
+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.

 
 

-   All built-in functions do check the types of their actual arguments
-when appropriate, and signal a `wrong-type-argument' error if an
-argument is of the wrong type.  For example, here is what happens if you
-pass an argument to `+' that it cannot handle:
+   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::.

 
 

-     (+ 2 'a)
-          error--> Wrong type argument: integer-or-marker-p, a
+* Menu:

 
 

-   If you want your program to handle different types differently, you
-must do explicit type checking.  The most common way to check the type
-of an object is to call a "type predicate" function.  Emacs has a type
-predicate for each type, as well as some predicates for combinations of
-types.
+* 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.

 
 

-   A type predicate function takes one argument; it returns `t' if the
-argument belongs to the appropriate type, and `nil' otherwise.
-Following a general Lisp convention for predicate functions, most type
-predicates' names end with `p'.
+\1f
+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.

 
 

-   Here is an example which uses the predicates `listp' to check for a
-list and `symbolp' to check for a symbol.
+* Menu:

 
 

-     (defun add-on (x)
-       (cond ((symbolp x)
-              ;; If X is a symbol, put it on LIST.
-              (setq list (cons x list)))
-             ((listp x)
-              ;; If X is a list, add its elements to LIST.
-              (setq list (append x list)))
-             (t
-              ;; We only handle symbols and lists.
-              (error "Invalid argument %s in add-on" x))))
+* 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.

 
 

-   Here is a table of predefined type predicates, in alphabetical order,
-with references to further information.
+\1f
+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::.

 
 

-`annotationp'
-     *Note annotationp: Annotation Primitives.
+\1f
+File: lispref.info,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes

 
 

-`arrayp'
-     *Note arrayp: Array Functions.
+Major Mode Examples
+-------------------

 
 

-`atom'
-     *Note atom: List-related Predicates.
+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.

 
 

-`bit-vector-p'
-     *Note bit-vector-p: Bit Vector Functions.
+\1f
+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)'.

 
 

-`bitp'
-     *Note bitp: Bit Vector Functions.
+     For example,

 
 

-`boolean-specifier-p'
-     *Note boolean-specifier-p: Specifier Types.
+          (("^/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'.

 
 

-`buffer-glyph-p'
-     *Note buffer-glyph-p: Glyph Types.
+\1f
+File: lispref.info,  Node: Mode Help,  Next: Derived Modes,  Prev: Auto Major Mode,  Up: Major Modes

 
 

-`buffer-live-p'
-     *Note buffer-live-p: Killing Buffers.
+Getting Help about a Major Mode
+-------------------------------

 
 

-`bufferp'
-     *Note bufferp: Buffer Basics.
+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.

 
 

-`button-event-p'
-     *Note button-event-p: Event Predicates.
+ - Command: describe-mode
+     This function displays the documentation of the current major mode.

 
 

-`button-press-event-p'
-     *Note button-press-event-p: Event Predicates.
+     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::.)

 
 

-`button-release-event-p'
-     *Note button-release-event-p: Event Predicates.
+ - 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.

 
 

-`case-table-p'
-     *Note case-table-p: Case Tables.
+\1f
+File: lispref.info,  Node: Derived Modes,  Prev: Mode Help,  Up: Major Modes

 
 

-`char-int-p'
-     *Note char-int-p: Character Codes.
+Defining Derived Modes
+----------------------

 
 

-`char-or-char-int-p'
-     *Note char-or-char-int-p: Character Codes.
+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'.

 
 

-`char-or-string-p'
-     *Note char-or-string-p: Predicates for Strings.
+ - 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.

 
 

-`char-table-p'
-     *Note char-table-p: Char Tables.
+     The new command VARIANT is defined to call the function PARENT,
+     then override certain aspects of that parent mode:

 
 

-`characterp'
-     *Note characterp: Predicates for Characters.
+        * 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.

 
 

-`color-instance-p'
-     *Note color-instance-p: Colors.
+        * 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.

 
 

-`color-pixmap-image-instance-p'
-     *Note color-pixmap-image-instance-p: Image Instance Types.
+        * 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.

 
 

-`color-specifier-p'
-     *Note color-specifier-p: Specifier Types.
+        * 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.)

 
 

-`commandp'
-     *Note commandp: Interactive Call.
+     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'.

 
 

-`compiled-function-p'
-     *Note compiled-function-p: Compiled-Function Type.
+     The argument DOCSTRING specifies the documentation string for the
+     new mode.  If you omit DOCSTRING, `define-derived-mode' generates
+     a documentation string.

 
 

-`console-live-p'
-     *Note console-live-p: Connecting to a Console or Device.
+     Here is a hypothetical example:

 
 

-`consolep'
-     *Note consolep: Consoles and Devices.
+          (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)

 
 

-`consp'
-     *Note consp: List-related Predicates.
+\1f
+File: lispref.info,  Node: Minor Modes,  Next: Modeline Format,  Prev: Major Modes,  Up: Modes

 
 

-`database-live-p'
-     *Note database-live-p: Connecting to a Database.
+Minor Modes
+===========

 
 

-`databasep'
-     *Note databasep: Databases.
+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.

 
 

-`device-live-p'
-     *Note device-live-p: Connecting to a Console or Device.
+   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.

 
 

-`device-or-frame-p'
-     *Note device-or-frame-p: Basic Device Functions.
+   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.

 
 

-`devicep'
-     *Note devicep: Consoles and Devices.
+   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.

 
 

-`eval-event-p'
-     *Note eval-event-p: Event Predicates.
+* Menu:

 
 

-`event-live-p'
-     *Note event-live-p: Event Predicates.
+* Minor Mode Conventions::      Tips for writing a minor mode.
+* Keymaps and Minor Modes::     How a minor mode can have its own keymap.

 
 

-`eventp'
-     *Note eventp: Events.
+\1f
+File: lispref.info,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes

 
 

-`extent-live-p'
-     *Note extent-live-p: Creating and Modifying Extents.
+Conventions for Writing Minor Modes
+-----------------------------------

 
 

-`extentp'
-     *Note extentp: Extents.
+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.

 
 

-`face-boolean-specifier-p'
-     *Note face-boolean-specifier-p: Specifier Types.
+   In addition, there are several conventions that are specific to
+minor modes.

 
 

-`facep'
-     *Note facep: Basic Face Functions.
+   * 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".

 
 

-`floatp'
-     *Note floatp: Predicates on Numbers.
+     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.

 
 

-`font-instance-p'
-     *Note font-instance-p: Fonts.
+     If you want the minor mode to be enabled separately in each buffer,
+     make the variable buffer-local.

 
 

-`font-specifier-p'
-     *Note font-specifier-p: Specifier Types.
+   * 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.

 
 

-`frame-live-p'
-     *Note frame-live-p: Deleting Frames.
+     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.

 
 

-`framep'
-     *Note framep: Frames.
+     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.

 
 

-`functionp'
-     (not yet documented)
+          (setq transient-mark-mode
+                (if (null arg) (not transient-mark-mode)
+                  (> (prefix-numeric-value arg) 0)))

 
 

-`generic-specifier-p'
-     *Note generic-specifier-p: Specifier Types.
+   * Add an element to `minor-mode-alist' for each minor mode (*note
+     Modeline Variables::).  This element should be a list of the
+     following form:

 
 

-`glyphp'
-     *Note glyphp: Glyphs.
+          (MODE-VARIABLE STRING)

 
 

-`hash-table-p'
-     *Note hash-table-p: Hash Tables.
+     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.

 
 

-`icon-glyph-p'
-     *Note icon-glyph-p: Glyph Types.
+     When you add an element to `minor-mode-alist', use `assq' to check
+     for an existing element, to avoid duplication.  For example:

 
 

-`image-instance-p'
-     *Note image-instance-p: Images.
+          (or (assq 'leif-mode minor-mode-alist)
+              (setq minor-mode-alist
+                    (cons '(leif-mode " Leif") minor-mode-alist)))

 
 

-`image-specifier-p'
-     *Note image-specifier-p: Specifier Types.
+\1f
+File: lispref.info,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes

 
 

-`integer-char-or-marker-p'
-     *Note integer-char-or-marker-p: Predicates on Markers.
+Keymaps and Minor Modes
+-----------------------

 
 

-`integer-or-char-p'
-     *Note integer-or-char-p: Predicates for Characters.
+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::.

 
 

-`integer-or-marker-p'
-     *Note integer-or-marker-p: Predicates on Markers.
+   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.)

 
 

-`integer-specifier-p'
-     *Note integer-specifier-p: Specifier Types.
+\1f
+File: lispref.info,  Node: Modeline Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes

 
 

-`integerp'
-     *Note integerp: Predicates on Numbers.
+Modeline Format
+===============

 
 

-`itimerp'
-     (not yet documented)
+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.

 
 

-`key-press-event-p'
-     *Note key-press-event-p: Event Predicates.
+   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.

 
 

-`keymapp'
-     *Note keymapp: Creating Keymaps.
+   `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).

 
 

-`keywordp'
-     (not yet documented)
+   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.

 
 

-`listp'
-     *Note listp: List-related Predicates.
+ - Function: redraw-modeline &optional all
+     Force redisplay of the current buffer's modeline.  If ALL is
+     non-`nil', then force redisplay of all modelines.

 
 

-`markerp'
-     *Note markerp: Predicates on Markers.
+   The modeline is usually displayed in inverse video.  This is
+controlled using the `modeline' face.  *Note Faces::.

 
 

-`misc-user-event-p'
-     *Note misc-user-event-p: Event Predicates.
+* Menu:

 
 

-`mono-pixmap-image-instance-p'
-     *Note mono-pixmap-image-instance-p: Image Instance Types.
+* Modeline Data::         The data structure that controls the modeline.
+* Modeline Variables::    Variables used in that data structure.
+* %-Constructs::          Putting information into a modeline.

 
 

-`motion-event-p'
-     *Note motion-event-p: Event Predicates.
+\1f
+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")
+        "-%-"))

 
 

-`mouse-event-p'
-     *Note mouse-event-p: Event Predicates.
+\1f
+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.

 
 

-`natnum-specifier-p'
-     *Note natnum-specifier-p: Specifier Types.
+\1f
+File: lispref.info,  Node: %-Constructs,  Prev: Modeline Variables,  Up: Modeline Format

 
 

-`natnump'
-     *Note natnump: Predicates on Numbers.
+`%'-Constructs in the ModeLine
+------------------------------

 
 

-`nlistp'
-     *Note nlistp: List-related Predicates.
+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.

 
 

-`nothing-image-instance-p'
-     *Note nothing-image-instance-p: Image Instance Types.
+`%b'
+     The current buffer name, obtained with the `buffer-name' function.
+     *Note Buffer Names::.

 
 

-`number-char-or-marker-p'
-     *Note number-char-or-marker-p: Predicates on Markers.
+`%f'
+     The visited file name, obtained with the `buffer-file-name'
+     function.  *Note Buffer File Name::.

 
 

-`number-or-marker-p'
-     *Note number-or-marker-p: Predicates on Markers.
+`%F'
+     The name of the selected frame.

 
 

-`numberp'
-     *Note numberp: Predicates on Numbers.
+`%c'
+     The current column number of point.

 
 

-`pointer-glyph-p'
-     *Note pointer-glyph-p: Glyph Types.
+`%l'
+     The current line number of point.

 
 

-`pointer-image-instance-p'
-     *Note pointer-image-instance-p: Image Instance Types.
+`%*'
+     `%' if the buffer is read only (see `buffer-read-only');
+     `*' if the buffer is modified (see `buffer-modified-p');
+     `-' otherwise.  *Note Buffer Modification::.

 
 

-`process-event-p'
-     *Note process-event-p: Event Predicates.
+`%+'
+     `*' 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::.

 
 

-`processp'
-     *Note processp: Processes.
+`%&'
+     `*' if the buffer is modified, and `-' otherwise.

 
 

-`range-table-p'
-     *Note range-table-p: Range Tables.
+`%s'
+     The status of the subprocess belonging to the current buffer,
+     obtained with `process-status'.  *Note Process Information::.

 
 

-`ringp'
-     (not yet documented)
+`%l'
+     The current line number.

 
 

-`sequencep'
-     *Note sequencep: Sequence Functions.
+`%S'
+     The name of the selected frame; this is only meaningful under the
+     X Window System.  *Note Frame Name::.

 
 

-`specifierp'
-     *Note specifierp: Specifiers.
+`%t'
+     Whether the visited file is a text file or a binary file.  (This
+     is a meaningful distinction only on certain operating systems.)

 
 

-`stringp'
-     *Note stringp: Predicates for Strings.
+`%p'
+     The percentage of the buffer text above the *top* of window, or
+     `Top', `Bottom' or `All'.

 
 

-`subrp'
-     *Note subrp: Function Cells.
+`%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'.

 
 

-`subwindow-image-instance-p'
-     *Note subwindow-image-instance-p: Image Instance Types.
+`%n'
+     `Narrow' when narrowing is in effect; nothing otherwise (see
+     `narrow-to-region' in *Note Narrowing::).

 
 

-`subwindowp'
-     *Note subwindowp: Subwindows.
+`%C'
+     Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.

 
 

-`symbolp'
-     *Note symbolp: Symbols.
+`%['
+     An indication of the depth of recursive editing levels (not
+     counting minibuffer levels): one `[' for each editing level.
+     *Note Recursive Editing::.

 
 

-`syntax-table-p'
-     *Note syntax-table-p: Syntax Tables.
+`%]'
+     One `]' for each recursive editing level (not counting minibuffer
+     levels).

 
 

-`text-image-instance-p'
-     *Note text-image-instance-p: Image Instance Types.
+`%%'
+     The character `%'--this is how to include a literal `%' in a
+     string in which `%'-constructs are allowed.

 
 

-`timeout-event-p'
-     *Note timeout-event-p: Event Predicates.
+`%-'
+     Dashes sufficient to fill the remainder of the modeline.

 
 

-`toolbar-button-p'
-     *Note toolbar-button-p: Toolbar.
+   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'.

 
 

-`toolbar-specifier-p'
-     *Note toolbar-specifier-p: Toolbar.
+`%m'
+     The value of `mode-name'.

 
 

-`user-variable-p'
-     *Note user-variable-p: Defining Variables.
+`%M'
+     The value of `global-mode-string'.  Currently, only `display-time'
+     modifies the value of `global-mode-string'.

 
 

-`vectorp'
-     *Note vectorp: Vectors.
+\1f
+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.

 
 

-`weak-list-p'
-     *Note weak-list-p: Weak Lists.
+\1f
+File: lispref.info,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top

 
 

-`window-configuration-p'
-     *Note window-configuration-p: Window Configurations.
+Documentation
+*************

 
 

-`window-live-p'
-     *Note window-live-p: Deleting Windows.
+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.

 
 

-`windowp'
-     *Note windowp: Basic Windows.
+   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.

 
 

-   The most general way to check the type of an object is to call the
-function `type-of'.  Recall that each object belongs to one and only
-one primitive type; `type-of' tells you which one (*note Lisp Data
-Types::).  But `type-of' knows nothing about non-primitive types.  In
-most cases, it is more convenient to use type predicates than `type-of'.
+* Menu:

 
 

- - Function: type-of object
-     This function returns a symbol naming the primitive type of
-     OBJECT.  The value is one of `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', or `x-resource'.
+* 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.

 
 

-          (type-of 1)
-               => integer
-          (type-of 'nil)
-               => symbol
-          (type-of '())    ; `()' is `nil'.
-               => symbol
-          (type-of '(x))
-               => cons
+\1f
+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'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Equality Predicates,  Prev: Type Predicates,  Up: Lisp Data Types
+File: lispref.info,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation

 
 

-Equality Predicates
-===================
+Access to Documentation Strings
+===============================

 
 

-   Here we describe two functions that test for equality between any two
-objects.  Other functions test equality between objects of specific
-types, e.g., strings.  For these predicates, see the appropriate chapter
-describing the data type.
-
- - Function: eq object1 object2
-     This function returns `t' if OBJECT1 and OBJECT2 are the same
-     object, `nil' otherwise.  The "same object" means that a change in
-     one will be reflected by the same change in the other.
-
-     `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
-     value.  Also, since symbol names are normally unique, if the
-     arguments are symbols with the same name, they are `eq'.  For
-     other types (e.g., lists, vectors, strings), two arguments with
-     the same contents or elements are not necessarily `eq' to each
-     other: they are `eq' only if they are the same object.
-
-     (The `make-symbol' function returns an uninterned symbol that is
-     not interned in the standard `obarray'.  When uninterned symbols
-     are in use, symbol names are no longer unique.  Distinct symbols
-     with the same name are not `eq'.  *Note Creating Symbols::.)
-
-     NOTE: Under XEmacs 19, characters are really just integers, and
-     thus characters and integers are `eq'.  Under XEmacs 20, it was
-     necessary to preserve remnants of this in function such as `old-eq'
-     in order to maintain byte-code compatibility.  Byte code compiled
-     under any Emacs 19 will automatically have calls to `eq' mapped to
-     `old-eq' when executed under XEmacs 20.
-
-          (eq 'foo 'foo)
-               => t
-          
-          (eq 456 456)
-               => t
-          
-          (eq "asdf" "asdf")
-               => nil
-          
-          (eq '(1 (2 (3))) '(1 (2 (3))))
-               => nil
-          
-          (setq foo '(1 (2 (3))))
-               => (1 (2 (3)))
-          (eq foo foo)
-               => t
-          (eq foo '(1 (2 (3))))
-               => nil
-          
-          (eq [(1 2) 3] [(1 2) 3])
-               => nil
-          
-          (eq (point-marker) (point-marker))
-               => nil
+ - 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.

 
 

+\1f
+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."

 
 

- - Function: old-eq object1 object2
-     This function exists under XEmacs 20 and is exactly like `eq'
-     except that it suffers from the char-int confoundance disease.  In
-     other words, it returns `t' if given a character and the
-     equivalent integer, even though the objects are of different types!
-     You should _not_ ever call this function explicitly in your code.
-     However, be aware that all calls to `eq' in byte code compiled
-     under version 19 map to `old-eq' in XEmacs 20.  (Likewise for
-     `old-equal', `old-memq', `old-member', `old-assq' and
-     `old-assoc'.)
-
-          ;; Remember, this does not apply under XEmacs 19.
-          ?A
-               => ?A
-          (char-int ?A)
-               => 65
-          (old-eq ?A 65)
-               => t               ; Eek, we've been infected.
-          (eq ?A 65)
-               => nil             ; We are still healthy.
-
- - Function: equal object1 object2
-     This function returns `t' if OBJECT1 and OBJECT2 have equal
-     components, `nil' otherwise.  Whereas `eq' tests if its arguments
-     are the same object, `equal' looks inside nonidentical arguments
-     to see if their elements are the same.  So, if two objects are
-     `eq', they are `equal', but the converse is not always true.
-
-          (equal 'foo 'foo)
-               => t
-          
-          (equal 456 456)
-               => t
-          
-          (equal "asdf" "asdf")
-               => t
-          (eq "asdf" "asdf")
-               => nil
-          
-          (equal '(1 (2 (3))) '(1 (2 (3))))
-               => t
-          (eq '(1 (2 (3))) '(1 (2 (3))))
-               => nil
-          
-          (equal [(1 2) 3] [(1 2) 3])
-               => t
-          (eq [(1 2) 3] [(1 2) 3])
-               => nil
-          
-          (equal (point-marker) (point-marker))
-               => t
+\1f
+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"
+
+\1f
+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)

           
           

-          (eq (point-marker) (point-marker))
-               => nil
+          (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'.

 
 

-     Comparison of strings is case-sensitive.
+\1f
+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'.

 
 

-     Note that in FSF GNU Emacs, comparison of strings takes into
-     account their text properties, and you have to use `string-equal'
-     if you want only the strings themselves compared.  This difference
-     does not exist in XEmacs; `equal' and `string-equal' always return
-     the same value on the same strings.
+\1f
+File: lispref.info,  Node: Files,  Next: Backups and Auto-Saving,  Prev: Documentation,  Up: Top

 
 

-          (equal "asdf" "ASDF")
-               => nil
+Files
+*****

 
 

-     Two distinct buffers are never `equal', even if their contents are
-     the same.
+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::.

 
 

-   The test for equality is implemented recursively, and circular lists
-may therefore cause infinite recursion (leading to an error).
+   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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Numbers,  Next: Strings and Characters,  Prev: Lisp Data Types,  Up: Top
+File: lispref.info,  Node: Visiting Files,  Next: Saving Buffers,  Up: Files

 
 

-Numbers
-*******
+Visiting Files
+==============

 
 

-   XEmacs supports two numeric data types: "integers" and "floating
-point numbers".  Integers are whole numbers such as -3, 0, #b0111,
-#xFEED, #o744.  Their values are exact.  The number prefixes `#b',
-`#o', and `#x' are supported to represent numbers in binary, octal, and
-hexadecimal notation (or radix).  Floating point numbers are numbers
-with fractional parts, such as -4.5, 0.0, or 2.71828.  They can also be
-expressed in exponential notation: 1.5e2 equals 150; in this example,
-`e2' stands for ten to the second power, and is multiplied by 1.5.
-Floating point values are not exact; they have a fixed, limited amount
-of precision.
+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:
 
 
 * Menu:
 

-* 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.
-* Numeric Conversions::              Converting float to integer and vice versa.
-* Arithmetic Operations::     How to add, subtract, multiply and divide.
-* Rounding Operations::       Explicitly rounding floating point numbers.
-* Bitwise Operations::        Logical and, or, not, shifting.
-* Math Functions::            Trig, exponential and logarithmic functions.
-* Random Numbers::            Obtaining random integers, predictable or not.
+* Visiting Functions::         The usual interface functions for visiting.
+* Subroutines of Visiting::    Lower-level subroutines that they use.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Integer Basics,  Next: Float Basics,  Up: Numbers
+File: lispref.info,  Node: Visiting Functions,  Next: Subroutines of Visiting,  Up: Visiting Files

 
 

-Integer Basics
-==============
+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))

 
 

-   The range of values for an integer depends on the machine.  The
-minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to
-2**27 - 1), but some machines may provide a wider range.  Many examples
-in this chapter assume an integer has 28 bits.
+     (See `switch-to-buffer' in *Note Displaying Buffers::.)

 
 

-   The Lisp reader reads an integer as a sequence of digits with
-optional initial sign and optional final period.
+     When `find-file' is called interactively, it prompts for FILENAME
+     in the minibuffer.

 
 

-      1               ; The integer 1.
-      1.              ; The integer 1.
-     +1               ; Also the integer 1.
-     -1               ; The integer -1.
-      268435457       ; Also the integer 1, due to overflow.
-      0               ; The integer 0.
-     -0               ; The integer 0.
+ - 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.

 
 

-   To understand how various functions work on integers, especially the
-bitwise operators (*note Bitwise Operations::), it is often helpful to
-view the numbers in their binary form.
+     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.

 
 

-   In 28-bit binary, the decimal integer 5 looks like this:
+     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.

 
 

-     0000  0000 0000  0000 0000  0000 0101
+     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.

 
 

-(We have inserted spaces between groups of 4 bits, and two spaces
-between groups of 8 bits, to make the binary integer easier to read.)
+     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 integer -1 looks like this:
+     The `find-file-noselect' function returns the buffer that is
+     visiting the file FILENAME.

 
 

-     1111  1111 1111  1111 1111  1111 1111
+          (find-file-noselect "/etc/fstab")
+               => #<buffer fstab>

 
 

--1 is represented as 28 ones.  (This is called "two's complement"
-notation.)
+ - 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::.

 
 

-   The negative integer, -5, is creating by subtracting 4 from -1.  In
-binary, the decimal integer 4 is 100.  Consequently, -5 looks like this:
+     When this command is called interactively, it prompts for FILENAME.

 
 

-     1111  1111 1111  1111 1111  1111 1011
+ - 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.

 
 

-   In this implementation, the largest 28-bit binary integer is the
-decimal integer 134,217,727.  In binary, it looks like this:
+     When this command is called interactively, it prompts for FILENAME.

 
 

-     0111  1111 1111  1111 1111  1111 1111
+ - 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::.

 
 

-   Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 134,217,727, the value is the
-negative integer -134,217,728:
+     When `view-file' is called interactively, it prompts for FILENAME.

 
 

-     (+ 1 134217727)
-          => -134217728
-          => 1000  0000 0000  0000 0000  0000 0000
+     With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
+     another window.

 
 

-   Many of the following functions accept markers for arguments as well
-as integers.  (*Note Markers::.)  More precisely, the actual arguments
-to such functions may be either integers or markers, which is why we
-often give these arguments the name INT-OR-MARKER.  When the argument
-value is a marker, its position value is used and its buffer is ignored.
+ - 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Float Basics,  Next: Predicates on Numbers,  Prev: Integer Basics,  Up: Numbers
+File: lispref.info,  Node: Subroutines of Visiting,  Prev: Visiting Functions,  Up: Visiting Files

 
 

-Floating Point Basics
-=====================
+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>>

 
 

-   XEmacs supports floating point numbers.  The precise range of
-floating point numbers is machine-specific; it is the same as the range
-of the C data type `double' on the machine in question.
+     This function is used by `find-file-noselect'.  It uses
+     `generate-new-buffer' (*note Creating Buffers::).

 
 

-   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.  You can also use a minus sign to write
-negative floating point numbers, as in `-1.0'.
+ - 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::).

 
 

-   Most modern computers support the IEEE floating point standard, which
-provides for positive infinity and negative infinity as floating point
-values.  It also provides for a class of values called NaN or
-"not-a-number"; numerical functions return such values in cases where
-there is no correct answer.  For example, `(sqrt -1.0)' returns a NaN.
-For practical purposes, there's no significant difference between
-different NaN values in XEmacs Lisp, and there's no rule for precisely
-which NaN value should be used in a particular case, so this manual
-doesn't try to distinguish them.  XEmacs Lisp has no read syntax for
-NaNs or infinities; perhaps we should create a syntax in the future.
+     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'.

 
 

-   You can use `logb' to extract the binary exponent of a floating
-point number (or estimate the logarithm of an integer):
+     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.

 
 

- - Function: logb number
-     This function returns the binary exponent of NUMBER.  More
-     precisely, the value is the logarithm of NUMBER base 2, rounded
-     down to an integer.
+     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'.
+
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Predicates on Numbers,  Next: Comparison of Numbers,  Prev: Float Basics,  Up: Numbers
+File: lispref.info,  Node: Reading from Files,  Next: Writing to Files,  Prev: Saving Buffers,  Up: Files

 
 

-Type Predicates for Numbers
-===========================
+Reading from Files
+==================

 
 

-   The functions in this section test whether the argument is a number
-or whether it is a certain sort of number.  The functions `integerp'
-and `floatp' can take any type of Lisp object as argument (the
-predicates would not be of much use otherwise); but the `zerop'
-predicate requires a number as its argument.  See also
-`integer-or-marker-p', `integer-char-or-marker-p', `number-or-marker-p'
-and `number-char-or-marker-p', in *Note Predicates on Markers::.
+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: floatp object
-     This predicate tests whether its argument is a floating point
-     number and returns `t' if so, `nil' otherwise.
+ - 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.

 
 

-     `floatp' does not exist in Emacs versions 18 and earlier.
+     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::.

 
 

- - Function: integerp object
-     This predicate tests whether its argument is an integer, and
-     returns `t' if so, `nil' otherwise.
+     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.

 
 

- - Function: numberp object
-     This predicate tests whether its argument is a number (either
-     integer or floating point), and returns `t' if so, `nil' otherwise.
+     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,

 
 

- - Function: natnump object
-     The `natnump' predicate (whose name comes from the phrase
-     "natural-number-p") tests to see whether its argument is a
-     nonnegative integer, and returns `t' if so, `nil' otherwise.  0 is
-     considered non-negative.
+          (insert-file-contents filename nil 0 500)

 
 

- - Function: zerop number
-     This predicate tests whether its argument is zero, and returns `t'
-     if so, `nil' otherwise.  The argument must be a number.
+     inserts the first 500 characters of a file.

 
 

-     These two forms are equivalent: `(zerop x)' == `(= x 0)'.
+     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::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Comparison of Numbers,  Next: Numeric Conversions,  Prev: Predicates on Numbers,  Up: Numbers
+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.

 
 

-Comparison of Numbers
-=====================
+\1f
+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.

 
 

-   To test numbers for numerical equality, you should normally use `=',
-not `eq'.  There can be many distinct floating point number objects
-with the same numeric value.  If you use `eq' to compare them, then you
-test whether two values are the same _object_.  By contrast, `='
-compares only the numeric values of the objects.
-
-   At present, each integer value has a unique Lisp object in XEmacs
-Lisp.  Therefore, `eq' is equivalent to `=' where integers are
-concerned.  It is sometimes convenient to use `eq' for comparing an
-unknown value with an integer, because `eq' does not report an error if
-the unknown value is not a number--it accepts arguments of any type.
-By contrast, `=' signals an error if the arguments are not numbers or
-markers.  However, it is a good idea to use `=' if you can, even for
-comparing integers, just in case we change the representation of
-integers in a future XEmacs version.
-
-   There is another wrinkle: because floating point arithmetic is not
-exact, it is often a bad idea to check for equality of two floating
-point values.  Usually it is better to test for approximate equality.
-Here's a function to do this:
-
-     (defconst fuzz-factor 1.0e-6)
-     (defun approx-equal (x y)
-       (or (and (= x 0) (= y 0))
-           (< (/ (abs (- x y))
-                 (max (abs x) (abs y)))
-              fuzz-factor)))
-
-     Common Lisp note: Comparing numbers in Common Lisp always requires
-     `=' because Common Lisp implements multi-word integers, and two
-     distinct integer objects can have the same numeric value.  XEmacs
-     Lisp can have just one integer object for any given value because
-     it has a limited range of integer values.
-
-   In addition to numbers, all of the following functions also accept
-characters and markers as arguments, and treat them as their number
-equivalents.
-
- - Function: = number &rest more-numbers
-     This function returns `t' if all of its arguments are numerically
-     equal, `nil' otherwise.
-
-          (= 5)
+          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'.
+
+\1f
+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.
+
+\1f
+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
                => t

-          (= 5 6)
-               => nil
-          (= 5 5.0)
+          (file-exists-p "/usr/spool/mqueue")

                => t
                => t

-          (= 5 5 6)
+          (file-readable-p "/usr/spool/mqueue")

                => nil
 
                => nil
 

- - Function: /= number &rest more-numbers
-     This function returns `t' if no two arguments are numerically
-     equal, `nil' otherwise.
-
-          (/= 5 6)
+ - 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
                => t

-          (/= 5 5 6)
+          (file-writable-p "/foo")
+               => nil
+          (file-writable-p "~/no-such-dir/foo")

                => nil
                => nil

-          (/= 5 6 1)
-               => t

 
 

- - Function: < number &rest more-numbers
-     This function returns `t' if the sequence of its arguments is
-     monotonically increasing, `nil' otherwise.
+ - 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.

 
 

-          (< 5 6)
-               => t
-          (< 5 6 6)
+     Example: after the following,
+
+          (file-accessible-directory-p "/foo")

                => nil
                => nil

-          (< 5 6 7)
-               => t

 
 

- - Function: <= number &rest more-numbers
-     This function returns `t' if the sequence of its arguments is
-     monotonically nondecreasing, `nil' otherwise.
+     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.

 
 

-          (<= 5 6)
+          (file-newer-than-file-p "aug-19" "aug-20")
+               => nil
+          (file-newer-than-file-p "aug-20" "aug-19")

                => t
                => t

-          (<= 5 6 6)
+          (file-newer-than-file-p "aug-19" "no-file")

                => t
                => t

-          (<= 5 6 5)
+          (file-newer-than-file-p "no-file" "aug-19")

                => nil
 
                => nil
 

- - Function: > number &rest more-numbers
-     This function returns `t' if the sequence of its arguments is
-     monotonically decreasing, `nil' otherwise.
+     You can use `file-attributes' to get a file's last modification
+     time as a list of two numbers.  *Note File Attributes::.

 
 

- - Function: >= number &rest more-numbers
-     This function returns `t' if the sequence of its arguments is
-     monotonically nonincreasing, `nil' otherwise.
+\1f
+File: lispref.info,  Node: Kinds of Files,  Next: Truenames,  Prev: Testing Accessibility,  Up: Information about Files

 
 

- - Function: max number &rest more-numbers
-     This function returns the largest of its arguments.
+Distinguishing Kinds of Files
+-----------------------------

 
 

-          (max 20)
-               => 20
-          (max 1 2.5)
-               => 2.5
-          (max 1 3 2.5)
-               => 3
+This section describes how to distinguish various kinds of files, such
+as directories, symbolic links, and ordinary files.

 
 

- - Function: min number &rest more-numbers
-     This function returns the smallest of its arguments.
+ - 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.

 
 

-          (min -4 1)
-               => -4
+     If the file FILENAME is not a symbolic link (or there is no such
+     file), `file-symlink-p' returns `nil'.

 
 

-\1f
-File: lispref.info,  Node: Numeric Conversions,  Next: Arithmetic Operations,  Prev: Comparison of Numbers,  Up: Numbers
+          (file-symlink-p "foo")
+               => nil
+          (file-symlink-p "sym-link")
+               => "foo"
+          (file-symlink-p "sym-link2")
+               => "sym-link"
+          (file-symlink-p "/bin")
+               => "/pub/bin"

 
 

-Numeric Conversions
-===================

 
 

-   To convert an integer to floating point, use the function `float'.
+ - 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: float number
-     This returns NUMBER converted to floating point.  If NUMBER is
-     already a floating point number, `float' returns it unchanged.
+ - 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).

 
 

-   There are four functions to convert floating point numbers to
-integers; they differ in how they round.  These functions accept
-integer arguments also, and return such arguments unchanged.
+\1f
+File: lispref.info,  Node: Truenames,  Next: File Attributes,  Prev: Kinds of Files,  Up: Information about Files

 
 

- - Function: truncate number
-     This returns NUMBER, converted to an integer by rounding towards
-     zero.
+Truenames
+---------

 
 

- - Function: floor number &optional divisor
-     This returns NUMBER, converted to an integer by rounding downward
-     (towards negative infinity).
+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.

 
 

-     If DIVISOR is specified, NUMBER is divided by DIVISOR before the
-     floor is taken; this is the division operation that corresponds to
-     `mod'.  An `arith-error' results if DIVISOR is 0.
+ - 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.

 
 

- - Function: ceiling number
-     This returns NUMBER, converted to an integer by rounding upward
-     (towards positive infinity).
+     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.

 
 

- - Function: round number
-     This returns NUMBER, converted to an integer by rounding towards
-     the nearest integer.  Rounding a value equidistant between two
-     integers may choose the integer closer to zero, or it may prefer
-     an even integer, depending on your machine.
+   *Note Buffer File Name::, for related information.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Arithmetic Operations,  Next: Rounding Operations,  Prev: Numeric Conversions,  Up: Numbers
+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

 
 

-Arithmetic Operations
-=====================
+ - Function: file-attributes filename
+     This function returns a list of attributes of file FILENAME.  If
+     the specified file cannot be opened, it returns `nil'.

 
 

-   XEmacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division.  Remainder and
-modulus functions supplement the division functions.  The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
+     The elements of the list, in order, are:

 
 

-   All of these functions except `%' return a floating point value if
-any argument is floating.
+       0. `t' for a directory, a string for a symbolic link (the name
+          linked to), or `nil' for a text file.

 
 

-   It is important to note that in XEmacs Lisp, arithmetic functions do
-not check for overflow.  Thus `(1+ 134217727)' may evaluate to
--134217728, depending on your hardware.
+       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::).

 
 

- - Function: 1+ number
-     This function returns NUMBER plus one.  NUMBER may be a number,
-     character or marker.  Markers and characters are converted to
-     integers.
+       2. The file's UID.

 
 

-     For example,
+       3. The file's GID.

 
 

-          (setq foo 4)
-               => 4
-          (1+ foo)
-               => 5
+       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::.)

 
 

-     This function is not analogous to the C operator `++'--it does not
-     increment a variable.  It just computes a sum.  Thus, if we
-     continue,
+       5. The time of last modification as a list of two integers (as
+          above).

 
 

-          foo
-               => 4
+       6. The time of last status change as a list of two integers (as
+          above).

 
 

-     If you want to increment the variable, you must use `setq', like
-     this:
+       7. The size of the file in bytes.

 
 

-          (setq foo (1+ foo))
-               => 5
-
-     Now that the `cl' package is always available from lisp code, a
-     more convenient and natural way to increment a variable is
-     `(incf foo)'.
-
- - Function: 1- number
-     This function returns NUMBER minus one.  NUMBER may be a number,
-     character or marker.  Markers and characters are converted to
-     integers.
-
- - Function: abs number
-     This returns the absolute value of NUMBER.
-
- - Function: + &rest numbers
-     This function adds its arguments together.  When given no
-     arguments, `+' returns 0.
-
-     If any of the arguments are characters or markers, they are first
-     converted to integers.
-
-          (+)
-               => 0
-          (+ 1)
-               => 1
-          (+ 1 2 3 4)
-               => 10
-
- - Function: - &optional number &rest other-numbers
-     The `-' function serves two purposes: negation and subtraction.
-     When `-' has a single argument, the value is the negative of the
-     argument.  When there are multiple arguments, `-' subtracts each of
-     the OTHER-NUMBERS from NUMBER, cumulatively.  If there are no
-     arguments, an error is signaled.
-
-     If any of the arguments are characters or markers, they are first
-     converted to integers.
-
-          (- 10 1 2 3 4)
-               => 0
-          (- 10)
-               => -10
-          (-)
-               => 0
-
- - Function: * &rest numbers
-     This function multiplies its arguments together, and returns the
-     product.  When given no arguments, `*' returns 1.
-
-     If any of the arguments are characters or markers, they are first
-     converted to integers.
-
-          (*)
-               => 1
-          (* 1)
-               => 1
-          (* 1 2 3 4)
-               => 24
+       8. The file's modes, as a string of ten letters or dashes, as in
+          `ls -l'.

 
 

- - Function: / dividend &rest divisors
-     The `/' function serves two purposes: inversion and division.  When
-     `/' has a single argument, the value is the inverse of the
-     argument.  When there are multiple arguments, `/' divides DIVIDEND
-     by each of the DIVISORS, cumulatively, returning the quotient.  If
-     there are no arguments, an error is signaled.
-
-     If none of the arguments are floats, then the result is an integer.
-     This means the result has to be rounded.  On most machines, the
-     result is rounded towards zero after each division, but some
-     machines may round differently with negative arguments.  This is
-     because the Lisp function `/' is implemented using the C division
-     operator, which also permits machine-dependent rounding.  As a
-     practical matter, all known machines round in the standard fashion.
-
-     If any of the arguments are characters or markers, they are first
-     converted to integers.
-
-     If you divide by 0, an `arith-error' error is signaled.  (*Note
-     Errors::.)
-
-          (/ 6 2)
-               => 3
-          (/ 5 2)
-               => 2
-          (/ 25 3 2)
-               => 4
-          (/ 3.0)
-               => 0.3333333333333333
-          (/ -17 6)
-               => -2
+       9. `t' if the file's GID would change if file were deleted and
+          recreated; `nil' otherwise.

 
 

-     The result of `(/ -17 6)' could in principle be -3 on some
-     machines.
+      10. The file's inode number.

 
 

- - Function: % dividend divisor
-     This function returns the integer remainder after division of
-     DIVIDEND by DIVISOR.  The arguments must be integers or markers.
+      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 negative arguments, the remainder is in principle
-     machine-dependent since the quotient is; but in practice, all
-     known machines behave alike.
+     For example, here are the file attributes for `files.texi':

 
 

-     An `arith-error' results if DIVISOR is 0.
+          (file-attributes "files.texi")
+               =>  (nil
+                    1
+                    2235
+                    75
+                    (8489 20284)
+                    (8489 20284)
+                    (8489 20285)
+                    14906
+                    "-rw-rw-rw-"
+                    nil
+                    129500
+                    -32252)

 
 

-          (% 9 4)
-               => 1
-          (% -9 4)
-               => -1
-          (% 9 -4)
-               => 1
-          (% -9 -4)
-               => -1
+     and here is how the result is interpreted:

 
 

-     For any two integers DIVIDEND and DIVISOR,
+    `nil'
+          is neither a directory nor a symbolic link.

 
 

-          (+ (% DIVIDEND DIVISOR)
-             (* (/ DIVIDEND DIVISOR) DIVISOR))
+    `1'
+          has only one name (the name `files.texi' in the current
+          default directory).

 
 

-     always equals DIVIDEND.
+    `2235'
+          is owned by the user with UID 2235.

 
 

- - Function: mod dividend divisor
-     This function returns the value of DIVIDEND modulo DIVISOR; in
-     other words, the remainder after division of DIVIDEND by DIVISOR,
-     but with the same sign as DIVISOR.  The arguments must be numbers
-     or markers.
+    `75'
+          is in the group with GID 75.

 
 

-     Unlike `%', `mod' returns a well-defined result for negative
-     arguments.  It also permits floating point arguments; it rounds the
-     quotient downward (towards minus infinity) to an integer, and uses
-     that quotient to compute the remainder.
+    `(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::.

 
 

-     An `arith-error' results if DIVISOR is 0.
+    `(8489 20284)'
+          was last modified on Aug 19 00:09.

 
 

-          (mod 9 4)
-               => 1
-          (mod -9 4)
-               => 3
-          (mod 9 -4)
-               => -3
-          (mod -9 -4)
-               => -1
-          (mod 5.5 2.5)
-               => .5
+    `(8489 20285)'
+          last had its inode changed on Aug 19 00:09.

 
 

-     For any two numbers DIVIDEND and DIVISOR,
+    `14906'
+          is 14906 characters long.

 
 

-          (+ (mod DIVIDEND DIVISOR)
-             (* (floor DIVIDEND DIVISOR) DIVISOR))
+    `"-rw-rw-rw-"'
+          has a mode of read and write access for the owner, group, and
+          world.

 
 

-     always equals DIVIDEND, subject to rounding error if either
-     argument is floating point.  For `floor', see *Note Numeric
-     Conversions::.
+    `nil'
+          would retain the same GID if it were recreated.
+
+    `129500'
+          has an inode number of 129500.
+
+    `-32252'
+          is on file system number -32252.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Rounding Operations,  Next: Bitwise Operations,  Prev: Arithmetic Operations,  Up: Numbers
+File: lispref.info,  Node: Changing File Attributes,  Next: File Names,  Prev: Information about Files,  Up: Files

 
 

-Rounding Operations
-===================
+Changing File Names and Attributes
+==================================

 
 

-   The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
-floating point argument and return a floating point result whose value
-is a nearby integer.  `ffloor' returns the nearest integer below;
-`fceiling', the nearest integer above; `ftruncate', the nearest integer
-in the direction towards zero; `fround', the nearest integer.
+The functions in this section rename, copy, delete, link, and set the
+modes of files.

 
 

- - Function: ffloor number
-     This function rounds NUMBER to the next lower integral value, and
-     returns that value as a floating point number.
+   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:

 
 

- - Function: fceiling number
-     This function rounds NUMBER to the next higher integral value, and
-     returns that value as a floating point number.
+   * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
+     `nil'.

 
 

- - Function: ftruncate number
-     This function rounds NUMBER towards zero to an integral value, and
-     returns that value as a floating point number.
+   * Request confirmation if OK-IF-ALREADY-EXISTS is a number.  This is
+     what happens when the function is invoked interactively.

 
 

- - Function: fround number
-     This function rounds NUMBER to the nearest integral value, and
-     returns that value as a floating point number.
+   * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
+     is any other value.

 
 

-\1f
-File: lispref.info,  Node: Bitwise Operations,  Next: Math Functions,  Prev: Rounding Operations,  Up: Numbers
+ - 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.

 
 

-Bitwise Operations on Integers
-==============================
+     In the first part of the following example, we list two files,
+     `foo' and `foo3'.

 
 

-   In a computer, an integer is represented as a binary number, a
-sequence of "bits" (digits which are either zero or one).  A bitwise
-operation acts on the individual bits of such a sequence.  For example,
-"shifting" moves the whole sequence left or right one or more places,
-reproducing the same pattern "moved over".
+          % 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

 
 

-   The bitwise operations in XEmacs Lisp apply only to integers.
+     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'.

 
 

- - Function: lsh integer1 count
-     `lsh', which is an abbreviation for "logical shift", shifts the
-     bits in INTEGER1 to the left COUNT places, or to the right if
-     COUNT is negative, bringing zeros into the vacated bits.  If COUNT
-     is negative, `lsh' shifts zeros into the leftmost
-     (most-significant) bit, producing a positive result even if
-     INTEGER1 is negative.  Contrast this with `ash', below.
+          (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)

 
 

-     Here are two examples of `lsh', shifting a pattern of bits one
-     place to the left.  We show only the low-order eight bits of the
-     binary pattern; the rest are all zero.
+     and list the files again.  Now there are three names for one file:
+     `foo', `foo2', and `foo3'.  The old contents of `foo3' are lost.

 
 

-          (lsh 5 1)
-               => 10
-          ;; Decimal 5 becomes decimal 10.
-          00000101 => 00001010
+          (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
+               => nil

           
           

-          (lsh 7 1)
-               => 14
-          ;; Decimal 7 becomes decimal 14.
-          00000111 => 00001110
+          % 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

 
 

-     As the examples illustrate, shifting the pattern of bits one place
-     to the left produces a number that is twice the value of the
-     previous number.
+     This function is meaningless on non-Unix systems, where multiple
+     names for one file are not allowed.

 
 

-     Shifting a pattern of bits two places to the left produces results
-     like this (with 8-bit binary numbers):
+     See also `file-nlinks' in *Note File Attributes::.

 
 

-          (lsh 3 2)
-               => 12
-          ;; Decimal 3 becomes decimal 12.
-          00000011 => 00001100
+ - Command: rename-file filename newname &optional ok-if-already-exists
+     This command renames the file FILENAME as NEWNAME.

 
 

-     On the other hand, shifting one place to the right looks like this:
+     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.

 
 

-          (lsh 6 -1)
-               => 3
-          ;; Decimal 6 becomes decimal 3.
-          00000110 => 00000011
-          
-          (lsh 5 -1)
-               => 2
-          ;; Decimal 5 becomes decimal 2.
-          00000101 => 00000010
+     In an interactive call, this function prompts for FILENAME and
+     NEWNAME in the minibuffer; also, it requests confirmation if
+     NEWNAME already exists.

 
 

-     As the example illustrates, shifting one place to the right
-     divides the value of a positive integer by two, rounding downward.
+ - 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.

 
 

-     The function `lsh', like all XEmacs Lisp arithmetic functions, does
-     not check for overflow, so shifting left can discard significant
-     bits and change the sign of the number.  For example, left shifting
-     134,217,727 produces -2 on a 28-bit machine:
+     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.)

 
 

-          (lsh 134217727 1)          ; left shift
-               => -2
+     In an interactive call, this function prompts for FILENAME and
+     NEWNAME in the minibuffer; also, it requests confirmation if
+     NEWNAME already exists.

 
 

-     In binary, in the 28-bit implementation, the argument looks like
-     this:
+ - 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.

 
 

-          ;; Decimal 134,217,727
-          0111  1111 1111  1111 1111  1111 1111
+     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.)

 
 

-     which becomes the following when left shifted:
+     See also `delete-directory' in *Note Create/Delete Dirs::.

 
 

-          ;; Decimal -2
-          1111  1111 1111  1111 1111  1111 1110
+ - 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'.

 
 

- - Function: ash integer1 count
-     `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
-     COUNT places, or to the right if COUNT is negative.
+     In an interactive call, this function prompts for FILENAME and
+     NEWNAME in the minibuffer; also, it requests confirmation if
+     NEWNAME already exists.

 
 

-     `ash' gives the same results as `lsh' except when INTEGER1 and
-     COUNT are both negative.  In that case, `ash' puts ones in the
-     empty bit positions on the left, while `lsh' puts zeros in those
-     bit positions.
+ - 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.

 
 

-     Thus, with `ash', shifting the pattern of bits one place to the
-     right looks like this:
+ - 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.

 
 

-          (ash -6 -1) => -3
-          ;; Decimal -6 becomes decimal -3.
-          1111  1111 1111  1111 1111  1111 1010
-               =>
-          1111  1111 1111  1111 1111  1111 1101
+     The argument MODE must be an integer.  Only the low 9 bits of MODE
+     are used.

 
 

-     In contrast, shifting the pattern of bits one place to the right
-     with `lsh' looks like this:
+     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.

 
 

-          (lsh -6 -1) => 134217725
-          ;; Decimal -6 becomes decimal 134,217,725.
-          1111  1111 1111  1111 1111  1111 1010
-               =>
-          0111  1111 1111  1111 1111  1111 1101
+ - Function: default-file-modes
+     This function returns the current default protection value.

 
 

-     Here are other examples:
+   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'.

 
 

-                             ;               28-bit binary values
-          
-          (lsh 5 2)          ;   5  =  0000  0000 0000  0000 0000  0000 0101
-               => 20         ;      =  0000  0000 0000  0000 0000  0001 0100
-          (ash 5 2)
-               => 20
-          (lsh -5 2)         ;  -5  =  1111  1111 1111  1111 1111  1111 1011
-               => -20        ;      =  1111  1111 1111  1111 1111  1110 1100
-          (ash -5 2)
-               => -20
-          (lsh 5 -2)         ;   5  =  0000  0000 0000  0000 0000  0000 0101
-               => 1          ;      =  0000  0000 0000  0000 0000  0000 0001
-          (ash 5 -2)
-               => 1
-          (lsh -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
-               => 4194302    ;      =  0011  1111 1111  1111 1111  1111 1110
-          (ash -5 -2)        ;  -5  =  1111  1111 1111  1111 1111  1111 1011
-               => -2         ;      =  1111  1111 1111  1111 1111  1111 1110
-
- - Function: logand &rest ints-or-markers
-     This function returns the "logical and" of the arguments: the Nth
-     bit is set in the result if, and only if, the Nth bit is set in
-     all the arguments.  ("Set" means that the value of the bit is 1
-     rather than 0.)
-
-     For example, using 4-bit binary numbers, the "logical and" of 13
-     and 12 is 12: 1101 combined with 1100 produces 1100.  In both the
-     binary numbers, the leftmost two bits are set (i.e., they are
-     1's), so the leftmost two bits of the returned value are set.
-     However, for the rightmost two bits, each is zero in at least one
-     of the arguments, so the rightmost two bits of the returned value
-     are 0's.
-
-     Therefore,
-
-          (logand 13 12)
-               => 12
-
-     If `logand' is not passed any argument, it returns a value of -1.
-     This number is an identity element for `logand' because its binary
-     representation consists entirely of ones.  If `logand' is passed
-     just one argument, it returns that argument.
-
-                             ;                28-bit binary values
-          
-          (logand 14 13)     ; 14  =  0000  0000 0000  0000 0000  0000 1110
-                             ; 13  =  0000  0000 0000  0000 0000  0000 1101
-               => 12         ; 12  =  0000  0000 0000  0000 0000  0000 1100
-          
-          (logand 14 13 4)   ; 14  =  0000  0000 0000  0000 0000  0000 1110
-                             ; 13  =  0000  0000 0000  0000 0000  0000 1101
-                             ;  4  =  0000  0000 0000  0000 0000  0000 0100
-               => 4          ;  4  =  0000  0000 0000  0000 0000  0000 0100
-          
-          (logand)
-               => -1         ; -1  =  1111  1111 1111  1111 1111  1111 1111
+\1f
+File: lispref.info,  Node: File Names,  Next: Contents of Directories,  Prev: Changing File Attributes,  Up: Files

 
 

- - Function: logior &rest ints-or-markers
-     This function returns the "inclusive or" of its arguments: the Nth
-     bit is set in the result if, and only if, the Nth bit is set in at
-     least one of the arguments.  If there are no arguments, the result
-     is zero, which is an identity element for this operation.  If
-     `logior' is passed just one argument, it returns that argument.
+File Names
+==========

 
 

-                             ;               28-bit binary values
-          
-          (logior 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
-                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
-               => 13         ; 13  =  0000  0000 0000  0000 0000  0000 1101
-          
-          (logior 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
-                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
-                             ;  7  =  0000  0000 0000  0000 0000  0000 0111
-               => 15         ; 15  =  0000  0000 0000  0000 0000  0000 1111
-
- - Function: logxor &rest ints-or-markers
-     This function returns the "exclusive or" of its arguments: the Nth
-     bit is set in the result if, and only if, the Nth bit is set in an
-     odd number of the arguments.  If there are no arguments, the
-     result is 0, which is an identity element for this operation.  If
-     `logxor' is passed just one argument, it returns that argument.
-
-                             ;               28-bit binary values
-          
-          (logxor 12 5)      ; 12  =  0000  0000 0000  0000 0000  0000 1100
-                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
-               => 9          ;  9  =  0000  0000 0000  0000 0000  0000 1001
-          
-          (logxor 12 5 7)    ; 12  =  0000  0000 0000  0000 0000  0000 1100
-                             ;  5  =  0000  0000 0000  0000 0000  0000 0101
-                             ;  7  =  0000  0000 0000  0000 0000  0000 0111
-               => 14         ; 14  =  0000  0000 0000  0000 0000  0000 1110
+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.

 
 

- - Function: lognot integer
-     This function returns the logical complement of its argument: the
-     Nth bit is one in the result if, and only if, the Nth bit is zero
-     in INTEGER, and vice-versa.
+* Menu:

 
 

-          (lognot 5)
-               => -6
-          ;;  5  =  0000  0000 0000  0000 0000  0000 0101
-          ;; becomes
-          ;; -6  =  1111  1111 1111  1111 1111  1111 1010
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Math Functions,  Next: Random Numbers,  Prev: Bitwise Operations,  Up: Numbers
+File: lispref.info,  Node: File Name Components,  Next: Directory Names,  Up: File Names

 
 

-Standard Mathematical Functions
-===============================
+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"
+
+\1f
+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.

 
 

-   These mathematical functions are available if floating point is
-supported (which is the normal state of affairs).  They allow integers
-as well as floating point numbers as arguments.
+   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.

 
 

- - Function: sin number
- - Function: cos number
- - Function: tan number
-     These are the ordinary trigonometric functions, with argument
-     measured in radians.
+   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: asin number
-     The value of `(asin NUMBER)' is a number between -pi/2 and pi/2
-     (inclusive) whose sine is NUMBER; if, however, NUMBER is out of
-     range (outside [-1, 1]), then the result is a NaN.
+ - 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.

 
 

- - Function: acos number
-     The value of `(acos NUMBER)' is a number between 0 and pi
-     (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of
-     range (outside [-1, 1]), then the result is a NaN.
+          (file-name-as-directory "~rms/lewis")
+               => "~rms/lewis/"

 
 

- - Function: atan number &optional number2
-     The value of `(atan NUMBER)' is a number between -pi/2 and pi/2
-     (exclusive) whose tangent is NUMBER.
+ - 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.

 
 

-     If optional argument NUMBER2 is supplied, the function returns
-     `atan2(NUMBER,NUMBER2)'.
+          (directory-file-name "~lewis/")
+               => "~lewis"

 
 

- - Function: sinh number
- - Function: cosh number
- - Function: tanh number
-     These are the ordinary hyperbolic trigonometric functions.
+   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.

 
 

- - Function: asinh number
- - Function: acosh number
- - Function: atanh number
-     These are the inverse hyperbolic trigonometric functions.
+   If you wish to convert a directory name to its abbreviation, use this
+function:

 
 

- - Function: exp number
-     This is the exponential function; it returns e to the power
-     NUMBER.  e is a fundamental mathematical constant also called the
-     base of natural logarithms.
+ - 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.

 
 

- - Function: log number &optional base
-     This function returns the logarithm of NUMBER, with base BASE.  If
-     you don't specify BASE, the base E is used.  If NUMBER is
-     negative, the result is a NaN.
+     If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
+     the user's home directory.

 
 

- - Function: log10 number
-     This function returns the logarithm of NUMBER, with base 10.  If
-     NUMBER is negative, the result is a NaN.  `(log10 X)' == `(log X
-     10)', at least approximately.

 
 

- - Function: expt x y
-     This function returns X raised to power Y.  If both arguments are
-     integers and Y is positive, the result is an integer; in this
-     case, it is truncated to fit the range of possible integer values.
+ - 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.

 
 

- - Function: sqrt number
-     This returns the square root of NUMBER.  If NUMBER is negative,
-     the value is a NaN.
+     You can set this variable in `site-init.el' to describe the
+     abbreviations appropriate for your site.

 
 

- - Function: cube-root number
-     This returns the cube root of NUMBER.
+     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"))

 
 \1f
 
 \1f

-File: lispref.info,  Node: Random Numbers,  Prev: Math Functions,  Up: Numbers
+File: lispref.info,  Node: Relative File Names,  Next: File Name Expansion,  Prev: Directory Names,  Up: File Names

 
 

-Random Numbers
-==============
+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
+
+\1f
+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"
+
+\1f
+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.

 
 

-   A deterministic computer program cannot generate true random numbers.
-For most purposes, "pseudo-random numbers" suffice.  A series of
-pseudo-random numbers is generated in a deterministic fashion.  The
-numbers are not truly random, but they have certain properties that
-mimic a random series.  For example, all possible values occur equally
-often in a pseudo-random series.
+ - 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 `/'.

 
 

-   In XEmacs, pseudo-random numbers are generated from a "seed" number.
-Starting from any given seed, the `random' function always generates
-the same sequence of numbers.  XEmacs always starts with the same seed
-value, so the sequence of values of `random' is actually the same in
-each XEmacs run!  For example, in one operating system, the first call
-to `(random)' after you start XEmacs always returns -1457731, and the
-second one always returns -7692030.  This repeatability is helpful for
-debugging.
+     Note that the `temp-directory' function does not exist under FSF
+     Emacs.

 
 

-   If you want truly unpredictable random numbers, execute `(random
-t)'.  This chooses a new seed based on the current time of day and on
-XEmacs's process ID number.
+ - 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.

 
 

- - Function: random &optional limit
-     This function returns a pseudo-random integer.  Repeated calls
-     return a series of pseudo-random integers.
+          (make-temp-name "/tmp/foo")
+               => "/tmp/fooGaAQjC"

 
 

-     If LIMIT is a positive integer, the value is chosen to be
-     nonnegative and less than LIMIT.
+     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.

 
 

-     If LIMIT is `t', it means to choose a new seed based on the
-     current time of day and on XEmacs's process ID number.
+     To avoid confusion, each Lisp application should preferably use a
+     unique PREFIX to `make-temp-name'.

 
 

-     On some machines, any integer representable in Lisp may be the
-     result of `random'.  On other machines, the result can never be
-     larger than a certain maximum or less than a certain (negative)
-     minimum.
+\1f
+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")

 
 \1f
 
 \1f

-File: lispref.info,  Node: Strings and Characters,  Next: Lists,  Prev: Numbers,  Up: Top
+File: lispref.info,  Node: User Name Completion,  Prev: File Name Completion,  Up: File Names

 
 

-Strings and Characters
-**********************
+User Name Completion
+--------------------

 
 

-   A string in XEmacs Lisp is an array that contains an ordered sequence
-of characters.  Strings are used as names of symbols, buffers, and
-files, to send messages to users, to hold text being copied between
-buffers, and for many other purposes.  Because strings are so important,
-XEmacs Lisp has many functions expressly for manipulating them.  XEmacs
-Lisp programs use strings more often than individual characters.
+This section describes low-level subroutines for completing a user
+name.  For other completion functions, see *Note Completion::.

 
 

-* Menu:
+ - 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.

 
 

-* 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.
-* Case Tables::                      Customizing case conversion.
-* Char Tables::               Mapping from characters to Lisp objects.
+ - 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.
+
+\1f
+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'.

 
 

diff --git a/info/lispref.info-5 b/info/lispref.info-5
index 95a8a55..2543d27 100644 (file)
--- a/info/lispref.info-5
+++ b/info/lispref.info-5
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1226 +50,6960 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: String Basics,  Next: Predicates for Strings,  Up: Strings and Characters
+File: lispref.info,  Node: Create/Delete Dirs,  Next: Magic File Names,  Prev: Contents of Directories,  Up: Files

 
 

-String and Character Basics
-===========================
+Creating and Deleting Directories
+=================================

 
 

-   Strings in XEmacs Lisp are arrays that contain an ordered sequence of
-characters.  Characters are their own primitive object type in XEmacs
-20.  However, in XEmacs 19, characters are represented in XEmacs Lisp as
-integers; whether an integer was intended as a character or not is
-determined only by how it is used.  *Note Character Type::.
-
-   The length of a string (like any array) is fixed and independent of
-the string contents, and cannot be altered.  Strings in Lisp are _not_
-terminated by a distinguished character code.  (By contrast, strings in
-C are terminated by a character with ASCII code 0.)  This means that
-any character, including the null character (ASCII code 0), is a valid
-element of a string.
-
-   Since strings are considered arrays, you can operate on them with the
-general array functions.  (*Note Sequences Arrays Vectors::.)  For
-example, you can access or change individual characters in a string
-using the functions `aref' and `aset' (*note Array Functions::).
-
-   Strings use an efficient representation for storing the characters
-in them, and thus take up much less memory than a vector of the same
-length.
-
-   Sometimes you will see strings used to hold key sequences.  This
-exists for backward compatibility with Emacs 18, but should _not_ be
-used in new code, since many key chords can't be represented at all and
-others (in particular meta key chords) are confused with accented
-characters.
-
-   Strings are useful for holding regular expressions.  You can also
-match regular expressions against strings (*note Regexp Search::).  The
-functions `match-string' (*note Simple Match Data::) and
-`replace-match' (*note Replacing Match::) are useful for decomposing
-and modifying strings based on regular expression matching.
-
-   Like a buffer, a string can contain extents in it.  These extents are
-created when a function such as `buffer-substring' is called on a
-region with duplicable extents in it.  When the string is inserted into
-a buffer, the extents are inserted along with it.  *Note Duplicable
-Extents::.
-
-   *Note Text::, for information about functions that display strings or
-copy them into buffers.  *Note Character Type::, and *Note String
-Type::, for information about the syntax of characters and strings.
-
-\1f
-File: lispref.info,  Node: Predicates for Strings,  Next: Creating Strings,  Prev: String Basics,  Up: Strings and Characters
-
-The Predicates for Strings
-==========================
+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.

 
 

-   For more information about general sequence and array predicates,
-see *Note Sequences Arrays Vectors::, and *Note Arrays::.
+ - 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.

 
 

- - Function: stringp object
-     This function returns `t' if OBJECT is a string, `nil' otherwise.
+     Non-interactively, optional argument PARENTS says whether to
+     create parent directories if they don't exist. (Interactively, this
+     always happens.)

 
 

- - Function: char-or-string-p object
-     This function returns `t' if OBJECT is a string or a character,
-     `nil' otherwise.
+ - 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.
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+File: lispref.info,  Node: Creating a Partial File,  Next: Detached Partial Files,  Prev: Intro to Partial Files,  Up: Partial Files
+
+Creating a Partial File
+-----------------------

 
 

-     In XEmacs addition, this function also returns `t' if OBJECT is an
-     integer that can be represented as a character.  This is because
-     of compatibility with previous XEmacs and should not be depended
-     on.
+ - 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.
+
+\1f
+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.
+
+\1f
+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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Creating Strings,  Next: Predicates for Characters,  Prev: Predicates for Strings,  Up: Strings and Characters
+File: lispref.info,  Node: Files and MS-DOS,  Prev: Format Conversion,  Up: Files

 
 

-Creating Strings
+Files and MS-DOS

 ================
 
 ================
 

-   The following functions create strings, either from scratch, or by
-putting strings together, or by taking them apart.
-
- - Function: string &rest characters
-     This function returns a new string made up of CHARACTERS.
-
-          (string ?X ?E ?m ?a ?c ?s)
-               => "XEmacs"
-          (string)
-               => ""
-
-     Analogous functions operating on other data types include `list',
-     `cons' (*note Building Lists::), `vector' (*note Vectors::) and
-     `bit-vector' (*note Bit Vectors::).  This function has not been
-     available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
-
- - Function: make-string length character
-     This function returns a new string consisting entirely of LENGTH
-     successive copies of CHARACTER.  LENGTH must be a non-negative
-     integer.
-
-          (make-string 5 ?x)
-               => "xxxxx"
-          (make-string 0 ?x)
-               => ""
-
-     Other functions to compare with this one include `char-to-string'
-     (*note String Conversion::), `make-vector' (*note Vectors::), and
-     `make-list' (*note Building Lists::).
-
- - Function: substring string start &optional end
-     This function returns a new string which consists of those
-     characters from STRING in the range from (and including) the
-     character at the index START up to (but excluding) the character
-     at the index END.  The first character is at index zero.
-
-          (substring "abcdefg" 0 3)
-               => "abc"
-
-     Here the index for `a' is 0, the index for `b' is 1, and the index
-     for `c' is 2.  Thus, three letters, `abc', are copied from the
-     string `"abcdefg"'.  The index 3 marks the character position up
-     to which the substring is copied.  The character whose index is 3
-     is actually the fourth character in the string.
-
-     A negative number counts from the end of the string, so that -1
-     signifies the index of the last character of the string.  For
-     example:
+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.

 
 

-          (substring "abcdefg" -3 -1)
-               => "ef"
-
-     In this example, the index for `e' is -3, the index for `f' is -2,
-     and the index for `g' is -1.  Therefore, `e' and `f' are included,
-     and `g' is excluded.
-
-     When `nil' is used as an index, it stands for the length of the
-     string.  Thus,
-
-          (substring "abcdefg" -3 nil)
-               => "efg"
-
-     Omitting the argument END is equivalent to specifying `nil'.  It
-     follows that `(substring STRING 0)' returns a copy of all of
-     STRING.
-
-          (substring "abcdefg" 0)
-               => "abcdefg"
-
-     But we recommend `copy-sequence' for this purpose (*note Sequence
-     Functions::).
-
-     If the characters copied from STRING have duplicable extents or
-     text properties, those are copied into the new string also.  *Note
-     Duplicable Extents::.
-
-     A `wrong-type-argument' error is signaled if either START or END
-     is not an integer or `nil'.  An `args-out-of-range' error is
-     signaled if START indicates a character following END, or if
-     either integer is out of range for STRING.
-
-     Contrast this function with `buffer-substring' (*note Buffer
-     Contents::), which returns a string containing a portion of the
-     text in the current buffer.  The beginning of a string is at index
-     0, but the beginning of a buffer is at index 1.
-
- - Function: concat &rest sequences
-     This function returns a new string consisting of the characters in
-     the arguments passed to it (along with their text properties, if
-     any).  The arguments may be strings, lists of numbers, or vectors
-     of numbers; they are not themselves changed.  If `concat' receives
-     no arguments, it returns an empty string.
-
-          (concat "abc" "-def")
-               => "abc-def"
-          (concat "abc" (list 120 (+ 256 121)) [122])
-               => "abcxyz"
-          ;; `nil' is an empty sequence.
-          (concat "abc" nil "-def")
-               => "abc-def"
-          (concat "The " "quick brown " "fox.")
-               => "The quick brown fox."
-          (concat)
-               => ""
-
-     The second example above shows how characters stored in strings are
-     taken modulo 256.  In other words, each character in the string is
-     stored in one byte.
-
-     The `concat' function always constructs a new string that is not
-     `eq' to any existing string.
-
-     When an argument is an integer (not a sequence of integers), it is
-     converted to a string of digits making up the decimal printed
-     representation of the integer.  *Don't use this feature; we plan
-     to eliminate it.  If you already use this feature, change your
-     programs now!*  The proper way to convert an integer to a decimal
-     number in this way is with `format' (*note Formatting Strings::) or
-     `number-to-string' (*note String Conversion::).
-
-          (concat 137)
-               => "137"
-          (concat 54 321)
-               => "54321"
-
-     For information about other concatenation functions, see the
-     description of `mapconcat' in *Note Mapping Functions::, `vconcat'
-     in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
-     in *Note Building Lists::.
-
-\1f
-File: lispref.info,  Node: Predicates for Characters,  Next: Character Codes,  Prev: Creating Strings,  Up: Strings and Characters
-
-The Predicates for Characters
-=============================
+\1f
+File: lispref.info,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top

 
 

- - Function: characterp object
-     This function returns `t' if OBJECT is a character.
+Backups and Auto-Saving
+***********************

 
 

-     Some functions that work on integers (e.g. the comparison functions
-     <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
-     accept characters and implicitly convert them into integers.  In
-     general, functions that work on characters also accept char-ints
-     and implicitly convert them into characters.  WARNING: Neither of
-     these behaviors is very desirable, and they are maintained for
-     backward compatibility with old E-Lisp programs that confounded
-     characters and integers willy-nilly.  These behaviors may change
-     in the future; therefore, do not rely on them.  Instead, convert
-     the characters explicitly using `char-int'.
+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.

 
 

- - Function: integer-or-char-p object
-     This function returns `t' if OBJECT is an integer or character.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Character Codes,  Next: Text Comparison,  Prev: Predicates for Characters,  Up: Strings and Characters
+File: lispref.info,  Node: Backup Files,  Next: Auto-Saving,  Up: Backups and Auto-Saving

 
 

-Character Codes
-===============
+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:

 
 

- - Function: char-int character
-     This function converts a character into an equivalent integer.
-     The resulting integer will always be non-negative.  The integers in
-     the range 0 - 255 map to characters as follows:
+* 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.

 
 

-    0 - 31
-          Control set 0
+\1f
+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.
+
+\1f
+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.

 
 

-    32 - 127
-          ASCII
+   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::.

 
 

-    128 - 159
-          Control set 1
+ - Variable: backup-by-copying
+     If this variable is non-`nil', XEmacs always makes backup files by
+     copying.

 
 

-    160 - 255
-          Right half of ISO-8859-1
+   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.

 
 

-     If support for MULE does not exist, these are the only valid
-     character values.  When MULE support exists, the values assigned to
-     other characters may vary depending on the particular version of
-     XEmacs, the order in which character sets were loaded, etc., and
-     you should not depend on them.
+ - Variable: backup-by-copying-when-linked
+     If this variable is non-`nil', XEmacs makes backups by copying for
+     files with multiple names (hard links).

 
 

- - Function: int-char integer
-     This function converts an integer into the equivalent character.
-     Not all integers correspond to valid characters; use `char-int-p'
-     to determine whether this is the case.  If the integer cannot be
-     converted, `nil' is returned.
+     This variable is significant only if `backup-by-copying' is `nil',
+     since copying is always used when that variable is non-`nil'.

 
 

- - Function: char-int-p object
-     This function returns `t' if OBJECT is an integer that can be
-     converted into a character.
+ - 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.

 
 

- - Function: char-or-char-int-p object
-     This function returns `t' if OBJECT is a character or an integer
-     that can be converted into one.
+     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'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Text Comparison,  Next: String Conversion,  Prev: Character Codes,  Up: Strings and Characters
+File: lispref.info,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files

 
 

-Comparison of Characters and Strings
-====================================
+Making and Deleting Numbered Backup Files
+-----------------------------------------

 
 

- - Function: char-equal character1 character2 &optional buffer
-     This function returns `t' if the arguments represent the same
-     character, `nil' otherwise.  This function ignores differences in
-     case if the value of `case-fold-search' is non-`nil' in BUFFER,
-     which defaults to the current buffer.
+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.

 
 

-          (char-equal ?x ?x)
-               => t
-          (let ((case-fold-search t))
-            (char-equal ?x ?X))
-               => t
-          (let ((case-fold-search nil))
-            (char-equal ?x ?X))
-               => nil
+ - User Option: version-control
+     This variable controls whether to make a single non-numbered backup
+     file or multiple numbered backups.

 
 

- - Function: char= character1 character2
-     This function returns `t' if the arguments represent the same
-     character, `nil' otherwise.  Case is significant.
+    `nil'
+          Make numbered backups if the visited file already has
+          numbered backups; otherwise, do not.

 
 

-          (char= ?x ?x)
-               => t
-          (char= ?x ?X)
-               => nil
-          (let ((case-fold-search t))
-            (char-equal ?x ?X))
-               => nil
-          (let ((case-fold-search nil))
-            (char-equal ?x ?X))
-               => nil
+    `never'
+          Do not make numbered backups.

 
 

- - Function: string= string1 string2
-     This function returns `t' if the characters of the two strings
-     match exactly; case is significant.
+    ANYTHING ELSE
+          Make numbered backups.

 
 

-          (string= "abc" "abc")
-               => t
-          (string= "abc" "ABC")
-               => nil
-          (string= "ab" "ABC")
+   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.
+
+\1f
+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
                => nil

+          (backup-file-name-p "foo~")
+               => 3

 
 

+     The standard definition of this function is as follows:

 
 

- - Function: string-equal string1 string2
-     `string-equal' is another name for `string='.
+          (defun backup-file-name-p (file)
+            "Return non-nil if FILE is a backup file \
+          name (numeric or not)..."
+            (string-match "~$" file))

 
 

- - Function: string< string1 string2
-     This function compares two strings a character at a time.  First it
-     scans both the strings at once to find the first pair of
-     corresponding characters that do not match.  If the lesser
-     character of those two is the character from STRING1, then STRING1
-     is less, and this function returns `t'.  If the lesser character
-     is the one from STRING2, then STRING1 is greater, and this
-     function returns `nil'.  If the two strings match entirely, the
-     value is `nil'.
+     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.)

 
 

-     Pairs of characters are compared by their ASCII codes.  Keep in
-     mind that lower case letters have higher numeric values in the
-     ASCII character set than their upper case counterparts; numbers and
-     many punctuation characters have a lower numeric value than upper
-     case letters.
+     This simple expression is placed in a separate function to make it
+     easy to redefine for customization.

 
 

-          (string< "abc" "abd")
-               => t
-          (string< "abd" "abc")
+ - 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.
+
+\1f
+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
                => nil

-          (string< "123" "abc")
-               => t

 
 

-     When the strings have different lengths, and they match up to the
-     length of STRING1, then the result is `t'.  If they match up to
-     the length of STRING2, the result is `nil'.  A string of no
-     characters is less than any other string.
+     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.

 
 

-          (string< "" "abc")
-               => t
-          (string< "ab" "abc")
-               => t
-          (string< "abc" "")
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 written in XEmacs Lisp can be called from other
+programs as well as from the command loop.  It is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose).  Therefore, you
+should normally use `set-buffer' within a `save-excursion' that will
+restore the current buffer when your function is done (*note
+Excursions::).  Here is an example, the code for the command
+`append-to-buffer' (with the documentation string abridged):
+
+     (defun append-to-buffer (buffer start end)
+       "Append to specified buffer the text of the region.
+     ..."
+       (interactive "BAppend to buffer: \nr")
+       (let ((oldbuf (current-buffer)))
+         (save-excursion
+           (set-buffer (get-buffer-create buffer))
+           (insert-buffer-substring oldbuf start end))))
+
+This function binds a local variable to the current buffer, and then
+`save-excursion' records the values of point, the mark, and the
+original buffer.  Next, `set-buffer' makes another buffer current.
+Finally, `insert-buffer-substring' copies the string from the original
+current buffer to the new current buffer.
+
+   If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed.  Otherwise, you
+will not see the change immediately on the screen.  The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+   If you make local bindings (with `let' or function arguments) for a
+variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope.  Otherwise you might bind it in one buffer and unbind
+it in another!  There are two ways to do this.  In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding.  Otherwise, use `save-excursion' to make sure that the buffer
+current at the beginning is current again whenever the variable is
+unbound.
+
+   It is not reliable to change the current buffer back with
+`set-buffer', because that won't do the job if a quit happens while the
+wrong buffer is current.  Here is what _not_ to do:
+
+     (let (buffer-read-only
+           (obuf (current-buffer)))
+       (set-buffer ...)
+       ...
+       (set-buffer obuf))
+
+Using `save-excursion', as shown below, handles quitting, errors, and
+`throw', as well as ordinary evaluation.
+
+     (let (buffer-read-only)
+       (save-excursion
+         (set-buffer ...)
+         ...))
+
+ - Function: current-buffer
+     This function returns the current buffer.
+
+          (current-buffer)
+               => #<buffer buffers.texi>
+
+ - Function: set-buffer buffer-or-name
+     This function makes BUFFER-OR-NAME the current buffer.  It does
+     not display the buffer in the currently selected window or in any
+     other window, so the user cannot necessarily see the buffer.  But
+     Lisp programs can in any case work on it.
+
+     BUFFER-OR-NAME must be a buffer or the name of an existing
+     buffer-else an error is signaled.  This function returns the buffer
+     identified by BUFFER-OR-NAME.
+
+\1f
+File: lispref.info,  Node: Buffer Names,  Next: Buffer File Name,  Prev: Current Buffer,  Up: Buffers
+
+Buffer Names
+============
+
+Each buffer has a unique name, which is a string.  Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument.  Any argument called BUFFER-OR-NAME is of this sort,
+and an error is signaled if it is neither a string nor a buffer.  Any
+argument called BUFFER must be an actual buffer object, not a name.
+
+   Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the `list-buffers' and
+`buffer-menu' commands don't mention them.  A name starting with space
+also initially disables recording undo information; see *Note Undo::.
+
+ - Function: buffer-name &optional buffer
+     This function returns the name of BUFFER as a string.  If BUFFER
+     is not supplied, it defaults to the current buffer.
+
+     If `buffer-name' returns `nil', it means that BUFFER has been
+     killed.  *Note Killing Buffers::.
+
+          (buffer-name)
+               => "buffers.texi"
+          
+          (setq foo (get-buffer "temp"))
+               => #<buffer temp>
+          (kill-buffer foo)

                => nil
                => nil

-          (string< "abc" "ab")
+          (buffer-name foo)

                => nil
                => nil

-          (string< "" "")
+          foo
+               => #<killed buffer>
+
+ - Command: rename-buffer newname &optional unique
+     This function renames the current buffer to NEWNAME.  An error is
+     signaled if NEWNAME is not a string, or if there is already a
+     buffer with that name.  The function returns `nil'.
+
+     Ordinarily, `rename-buffer' signals an error if NEWNAME is already
+     in use.  However, if UNIQUE is non-`nil', it modifies NEWNAME to
+     make a name that is not in use.  Interactively, you can make
+     UNIQUE non-`nil' with a numeric prefix argument.
+
+     One application of this command is to rename the `*shell*' buffer
+     to some other name, thus making it possible to create a second
+     shell buffer under the name `*shell*'.
+
+ - Function: get-buffer buffer-or-name
+     This function returns the buffer named BUFFER-OR-NAME.  If
+     BUFFER-OR-NAME is a string and there is no buffer with that name,
+     the value is `nil'.  If BUFFER-OR-NAME is actually a buffer, it is
+     returned as given.  (That is not very useful, so the argument is
+     usually a name.)  For example:
+
+          (setq b (get-buffer "lewis"))
+               => #<buffer lewis>
+          (get-buffer b)
+               => #<buffer lewis>
+          (get-buffer "Frazzle-nots")

                => nil
 
                => nil
 

- - Function: string-lessp string1 string2
-     `string-lessp' is another name for `string<'.
+     See also the function `get-buffer-create' in *Note Creating
+     Buffers::.
+
+ - Function: generate-new-buffer-name starting-name &optional ignore
+     This function returns a name that would be unique for a new
+     buffer--but does not create the buffer.  It starts with
+     STARTING-NAME, and produces a name not currently in use for any
+     buffer by appending a number inside of `<...>'.

 
 

-   See also `compare-buffer-substrings' in *Note Comparing Text::, for
-a way to compare text in buffers.  The function `string-match', which
-matches a regular expression against a string, can be used for a kind
-of string comparison; see *Note Regexp Search::.
+     If IGNORE is given, it specifies a name that is okay to use (if it
+     is in the sequence to be tried), even if a buffer with that name
+     exists.
+
+     See the related function `generate-new-buffer' in *Note Creating
+     Buffers::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: String Conversion,  Next: Modifying Strings,  Prev: Text Comparison,  Up: Strings and Characters
+File: lispref.info,  Node: Buffer File Name,  Next: Buffer Modification,  Prev: Buffer Names,  Up: Buffers

 
 

-Conversion of Characters and Strings
-====================================
+Buffer File Name
+================

 
 

-   This section describes functions for conversions between characters,
-strings and integers.  `format' and `prin1-to-string' (*note Output
-Functions::) can also convert Lisp objects into strings.
-`read-from-string' (*note Input Functions::) can "convert" a string
-representation of a Lisp object into an object.
-
-   *Note Documentation::, for functions that produce textual
-descriptions of text characters and general input events
-(`single-key-description' and `text-char-description').  These
-functions are used primarily for making help messages.
-
- - Function: char-to-string character
-     This function returns a new string with a length of one character.
-     The value of CHARACTER, modulo 256, is used to initialize the
-     element of the string.
-
-     This function is similar to `make-string' with an integer argument
-     of 1.  (*Note Creating Strings::.)  This conversion can also be
-     done with `format' using the `%c' format specification.  (*Note
-     Formatting Strings::.)
-
-          (char-to-string ?x)
-               => "x"
-          (char-to-string (+ 256 ?x))
-               => "x"
-          (make-string 1 ?x)
-               => "x"
-
- - Function: string-to-char string
-     This function returns the first character in STRING.  If the
-     string is empty, the function returns 0. (Under XEmacs 19, the
-     value is also 0 when the first character of STRING is the null
-     character, ASCII code 0.)
-
-          (string-to-char "ABC")
-               => ?A   ;; Under XEmacs 20.
-               => 65   ;; Under XEmacs 19.
-          (string-to-char "xyz")
-               => ?x   ;; Under XEmacs 20.
-               => 120  ;; Under XEmacs 19.
-          (string-to-char "")
-               => 0
-          (string-to-char "\000")
-               => ?\^ ;; Under XEmacs 20.
-               => 0    ;; Under XEmacs 20.
-
-     This function may be eliminated in the future if it does not seem
-     useful enough to retain.
-
- - Function: number-to-string number
-     This function returns a string consisting of the printed
-     representation of NUMBER, which may be an integer or a floating
-     point number.  The value starts with a sign if the argument is
-     negative.
-
-          (number-to-string 256)
-               => "256"
-          (number-to-string -23)
-               => "-23"
-          (number-to-string -23.5)
-               => "-23.5"
-
-     `int-to-string' is a semi-obsolete alias for this function.
-
-     See also the function `format' in *Note Formatting Strings::.
-
- - Function: string-to-number string &optional base
-     This function returns the numeric value represented by STRING,
-     read in BASE.  It skips spaces and tabs at the beginning of
-     STRING, then reads as much of STRING as it can interpret as a
-     number.  (On some systems it ignores other whitespace at the
-     beginning, not just spaces and tabs.)  If the first character
-     after the ignored whitespace is not a digit or a minus sign, this
-     function returns 0.
-
-     If BASE is not specified, it defaults to ten.  With BASE other
-     than ten, only integers can be read.
-
-          (string-to-number "256")
-               => 256
-          (string-to-number "25 is a perfect square.")
-               => 25
-          (string-to-number "X256")
-               => 0
-          (string-to-number "-4.5")
-               => -4.5
-          (string-to-number "ffff" 16)
-               => 65535
+The "buffer file name" is the name of the file that is visited in that
+buffer.  When a buffer is not visiting a file, its buffer file name is
+`nil'.  Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently.  *Note
+Visiting Files::.
+
+ - Function: buffer-file-name &optional buffer
+     This function returns the absolute file name of the file that
+     BUFFER is visiting.  If BUFFER is not visiting any file,
+     `buffer-file-name' returns `nil'.  If BUFFER is not supplied, it
+     defaults to the current buffer.
+
+          (buffer-file-name (other-buffer))
+               => "/usr/user/lewis/manual/files.texi"
+
+ - Variable: buffer-file-name
+     This buffer-local variable contains the name of the file being
+     visited in the current buffer, or `nil' if it is not visiting a
+     file.  It is a permanent local, unaffected by
+     `kill-local-variables'.
+
+          buffer-file-name
+               => "/usr/user/lewis/manual/buffers.texi"
+
+     It is risky to change this variable's value without doing various
+     other things.  See the definition of `set-visited-file-name' in
+     `files.el'; some of the things done there, such as changing the
+     buffer name, are not strictly necessary, but others are essential
+     to avoid confusing XEmacs.
+
+ - Variable: buffer-file-truename
+     This buffer-local variable holds the truename of the file visited
+     in the current buffer, or `nil' if no file is visited.  It is a
+     permanent local, unaffected by `kill-local-variables'.  *Note
+     Truenames::.
+
+ - Variable: buffer-file-number
+     This buffer-local variable holds the file number and directory
+     device number of the file visited in the current buffer, or `nil'
+     if no file or a nonexistent file is visited.  It is a permanent
+     local, unaffected by `kill-local-variables'.  *Note Truenames::.
+
+     The value is normally a list of the form `(FILENUM DEVNUM)'.  This
+     pair of numbers uniquely identifies the file among all files
+     accessible on the system.  See the function `file-attributes', in
+     *Note File Attributes::, for more information about them.
+
+ - Function: get-file-buffer filename
+     This function returns the buffer visiting file FILENAME.  If there
+     is no such buffer, it returns `nil'.  The argument FILENAME, which
+     must be a string, is expanded (*note File Name Expansion::), then
+     compared against the visited file names of all live buffers.
+
+          (get-file-buffer "buffers.texi")
+              => #<buffer buffers.texi>
+
+     In unusual circumstances, there can be more than one buffer
+     visiting the same file name.  In such cases, this function returns
+     the first such buffer in the buffer list.
+
+ - Command: set-visited-file-name filename
+     If FILENAME is a non-empty string, this function changes the name
+     of the file visited in current buffer to FILENAME.  (If the buffer
+     had no visited file, this gives it one.)  The _next time_ the
+     buffer is saved it will go in the newly-specified file.  This
+     command marks the buffer as modified, since it does not (as far as
+     XEmacs knows) match the contents of FILENAME, even if it matched
+     the former visited file.
+
+     If FILENAME is `nil' or the empty string, that stands for "no
+     visited file".  In this case, `set-visited-file-name' marks the
+     buffer as having no visited file.
+
+     When the function `set-visited-file-name' is called interactively,
+     it prompts for FILENAME in the minibuffer.
+
+     See also `clear-visited-file-modtime' and
+     `verify-visited-file-modtime' in *Note Buffer Modification::.
+
+ - Variable: list-buffers-directory
+     This buffer-local variable records a string to display in a buffer
+     listing in place of the visited file name, for buffers that don't
+     have a visited file name.  Dired buffers use this variable.
+
+\1f
+File: lispref.info,  Node: Buffer Modification,  Next: Modification Time,  Prev: Buffer File Name,  Up: Buffers
+
+Buffer Modification
+===================
+
+XEmacs keeps a flag called the "modified flag" for each buffer, to
+record whether you have changed the text of the buffer.  This flag is
+set to `t' whenever you alter the contents of the buffer, and cleared
+to `nil' when you save it.  Thus, the flag shows whether there are
+unsaved changes.  The flag value is normally shown in the modeline
+(*note Modeline Variables::), and controls saving (*note Saving
+Buffers::) and auto-saving (*note Auto-Saving::).
+
+   Some Lisp programs set the flag explicitly.  For example, the
+function `set-visited-file-name' sets the flag to `t', because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+   The functions that modify the contents of buffers are described in
+*Note Text::.
+
+ - Function: buffer-modified-p &optional buffer
+     This function returns `t' if the buffer BUFFER has been modified
+     since it was last read in from a file or saved, or `nil'
+     otherwise.  If BUFFER is not supplied, the current buffer is
+     tested.
+
+ - Function: set-buffer-modified-p flag &optional buffer
+     This function marks BUFFER as modified if FLAG is non-`nil', or as
+     unmodified if the flag is `nil'.  BUFFER defaults to the current
+     buffer.
+
+     Another effect of calling this function is to cause unconditional
+     redisplay of the modeline for the current buffer.  In fact, the
+     function `redraw-modeline' works by doing this:
+
+          (set-buffer-modified-p (buffer-modified-p))
+
+ - Command: not-modified &optional arg
+     This command marks the current buffer as unmodified, and not
+     needing to be saved. (If ARG is non-`nil', the buffer is instead
+     marked as modified.) Don't use this function in programs, since it
+     prints a message in the echo area; use `set-buffer-modified-p'
+     (above) instead.
+
+ - Function: buffer-modified-tick &optional buffer
+     This function returns BUFFER`s modification-count.  This is a
+     counter that increments every time the buffer is modified.  If
+     BUFFER is `nil' (or omitted), the current buffer is used.

 
 

-     `string-to-int' is an obsolete alias for this function.
+\1f
+File: lispref.info,  Node: Modification Time,  Next: Read Only Buffers,  Prev: Buffer Modification,  Up: Buffers
+
+Comparison of Modification Time
+===============================
+
+Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk.  At this point, saving the
+buffer would overwrite the changes in the file.  Occasionally this may
+be what you want, but usually it would lose valuable information.
+XEmacs therefore checks the file's modification time using the functions
+described below before saving the file.
+
+ - Function: verify-visited-file-modtime buffer
+     This function compares what BUFFER has recorded for the
+     modification time of its visited file against the actual
+     modification time of the file as recorded by the operating system.
+     The two should be the same unless some other process has written
+     the file since XEmacs visited or saved it.
+
+     The function returns `t' if the last actual modification time and
+     XEmacs's recorded modification time are the same, `nil' otherwise.
+
+ - Function: clear-visited-file-modtime
+     This function clears out the record of the last modification time
+     of the file being visited by the current buffer.  As a result, the
+     next attempt to save this buffer will not complain of a
+     discrepancy in file modification times.
+
+     This function is called in `set-visited-file-name' and other
+     exceptional places where the usual test to avoid overwriting a
+     changed file should not be done.
+
+ - Function: visited-file-modtime
+     This function returns the buffer's recorded last file modification
+     time, as a list of the form `(HIGH . LOW)'.  (This is the same
+     format that `file-attributes' uses to return time values; see
+     *Note File Attributes::.)
+
+ - Function: set-visited-file-modtime &optional time
+     This function updates the buffer's record of the last modification
+     time of the visited file, to the value specified by TIME if TIME
+     is not `nil', and otherwise to the last modification time of the
+     visited file.
+
+     If TIME is not `nil', it should have the form `(HIGH . LOW)' or
+     `(HIGH LOW)', in either case containing two integers, each of
+     which holds 16 bits of the time.
+
+     This function is useful if the buffer was not read from the file
+     normally, or if the file itself has been changed for some known
+     benign reason.
+
+ - Function: ask-user-about-supersession-threat filename
+     This function is used to ask a user how to proceed after an
+     attempt to modify an obsolete buffer visiting file FILENAME.  An
+     "obsolete buffer" is an unmodified buffer for which the associated
+     file on disk is newer than the last save-time of the buffer.  This
+     means some other program has probably altered the file.
+
+     Depending on the user's answer, the function may return normally,
+     in which case the modification of the buffer proceeds, or it may
+     signal a `file-supersession' error with data `(FILENAME)', in which
+     case the proposed buffer modification is not allowed.
+
+     This function is called automatically by XEmacs on the proper
+     occasions.  It exists so you can customize XEmacs by redefining it.
+     See the file `userlock.el' for the standard definition.
+
+     See also the file locking mechanism in *Note File Locks::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Modifying Strings,  Next: String Properties,  Prev: String Conversion,  Up: Strings and Characters
+File: lispref.info,  Node: Read Only Buffers,  Next: The Buffer List,  Prev: Modification Time,  Up: Buffers

 
 

-Modifying Strings
+Read-Only Buffers

 =================
 
 =================
 

-   You can modify a string using the general array-modifying primitives.
-*Note Arrays::.  The function `aset' modifies a single character; the
-function `fillarray' sets all characters in the string to a specified
-character.
+If a buffer is "read-only", then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+   Read-only buffers are used in two kinds of situations:
+
+   * A buffer visiting a write-protected file is normally read-only.
+
+     Here, the purpose is to show the user that editing the buffer with
+     the aim of saving it in the file may be futile or undesirable.
+     The user who wants to change the buffer text despite this can do
+     so after clearing the read-only flag with `C-x C-q'.
+
+   * Modes such as Dired and Rmail make buffers read-only when altering
+     the contents with the usual editing commands is probably a mistake.
+
+     The special commands of these modes bind `buffer-read-only' to
+     `nil' (with `let') or bind `inhibit-read-only' to `t' around the
+     places where they change the text.
+
+ - Variable: buffer-read-only
+     This buffer-local variable specifies whether the buffer is
+     read-only.  The buffer is read-only if this variable is non-`nil'.
+
+ - Variable: inhibit-read-only
+     If this variable is non-`nil', then read-only buffers and read-only
+     characters may be modified.  Read-only characters in a buffer are
+     those that have non-`nil' `read-only' properties (either text
+     properties or extent properties).  *Note Extent Properties::, for
+     more information about text properties and extent properties.
+
+     If `inhibit-read-only' is `t', all `read-only' character
+     properties have no effect.  If `inhibit-read-only' is a list, then
+     `read-only' character properties have no effect if they are members
+     of the list (comparison is done with `eq').
+
+ - Command: toggle-read-only &optional arg
+     This command changes whether the current buffer is read-only.
+     Interactively, if a prefix arg ARG is supplied, set the current
+     buffer read only if and only if ARG is positive.
+
+     This command is intended for interactive use only; don't use it in
+     programs.  At any given point in a program, you should know
+     whether you want the read-only flag on or off; so you can set
+     `buffer-read-only' explicitly to the proper value, `t' or `nil'.
+
+ - Function: barf-if-buffer-read-only &optional buffer start end
+     This function signals a `buffer-read-only' error if BUFFER is
+     read-only.  BUFFER defaults to the current buffer.  *Note
+     Interactive Call::, for another way to signal an error if the
+     current buffer is read-only.
+
+     If optional argument START is non-`nil', all extents in the buffer
+     which overlap that part of the buffer are checked to ensure none
+     has a `read-only' property. (Extents that lie completely within the
+     range, however, are not checked.)  END defaults to the value of
+     START.
+
+     If START and END are equal, the range checked is [START, END]
+     (i.e.  closed on both ends); otherwise, the range checked is
+     (START, END) \(open on both ends), except that extents that lie
+     completely within [START, END] are not checked.  See
+     `extent-in-region-p' for a fuller discussion.
+
+\1f
+File: lispref.info,  Node: The Buffer List,  Next: Creating Buffers,  Prev: Read Only Buffers,  Up: Buffers

 
 

-   Each string has a tick counter that starts out at zero (when the
-string is created) and is incremented each time a change is made to that
-string.
+The Buffer List
+===============

 
 

- - Function: string-modified-tick string
-     This function returns the tick counter for `string'.
+The "buffer list" is a list of all live buffers.  Creating a buffer
+adds it to this list, and killing a buffer deletes it.  The order of
+the buffers in the list is based primarily on how recently each buffer
+has been displayed in the selected window.  Buffers move to the front
+of the list when they are selected and to the end when they are buried.
+Several functions, notably `other-buffer', use this ordering.  A
+buffer list displayed for the user also follows this order.
+
+   Every frame has its own order for the buffer list.  Switching to a
+new buffer inside of a particular frame changes the buffer list order
+for that frame, but does not affect the buffer list order of any other
+frames.  In addition, there is a global, non-frame buffer list order
+that is independent of the buffer list orders for any particular frame.
+
+   Note that the different buffer lists all contain the same elements.
+It is only the order of those elements that is different.
+
+ - Function: buffer-list &optional frame
+     This function returns a list of all buffers, including those whose
+     names begin with a space.  The elements are actual buffers, not
+     their names.  The order of the list is specific to FRAME, which
+     defaults to the current frame.  If FRAME is `t', the global,
+     non-frame ordering is returned instead.
+
+          (buffer-list)
+               => (#<buffer buffers.texi>
+                   #<buffer  *Minibuf-1*> #<buffer buffer.c>
+                   #<buffer *Help*> #<buffer TAGS>)
+          
+          ;; Note that the name of the minibuffer
+          ;;   begins with a space!
+          (mapcar (function buffer-name) (buffer-list))
+              => ("buffers.texi" " *Minibuf-1*"
+                  "buffer.c" "*Help*" "TAGS")
+
+     Buffers appear earlier in the list if they were current more
+     recently.
+
+     This list is a copy of a list used inside XEmacs; modifying it has
+     no effect on the buffers.
+
+ - Function: other-buffer &optional buffer-or-name frame visible-ok
+     This function returns the first buffer in the buffer list other
+     than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
+     (FRAME defaults to the current frame.  If FRAME is `t', then the
+     global, non-frame ordering is used.) Usually this is the buffer
+     most recently shown in the selected window, aside from
+     BUFFER-OR-NAME.  Buffers are moved to the front of the list when
+     they are selected and to the end when they are buried.  Buffers
+     whose names start with a space are not considered.
+
+     If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
+     `other-buffer' returns the first buffer on the buffer list that is
+     not visible in any window in a visible frame.
+
+     If the selected frame has a non-`nil' `buffer-predicate' property,
+     then `other-buffer' uses that predicate to decide which buffers to
+     consider.  It calls the predicate once for each buffer, and if the
+     value is `nil', that buffer is ignored.  *Note X Frame
+     Properties::.
+
+     If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
+     visible in any window on any visible frame, except as a last
+     resort.   If VISIBLE-OK is non-`nil', then it does not matter
+     whether a buffer is displayed somewhere or not.
+
+     If no suitable buffer exists, the buffer `*scratch*' is returned
+     (and created, if necessary).
+
+     Note that in FSF Emacs 19, there is no FRAME argument, and
+     VISIBLE-OK is the second argument instead of the third.
+
+ - Command: list-buffers &optional files-only
+     This function displays a listing of the names of existing buffers.
+     It clears the buffer `*Buffer List*', then inserts the listing
+     into that buffer and displays it in a window.  `list-buffers' is
+     intended for interactive use, and is described fully in `The XEmacs
+     Reference Manual'.  It returns `nil'.
+
+ - Command: bury-buffer &optional buffer-or-name before
+     This function puts BUFFER-OR-NAME at the end of the buffer list
+     without changing the order of any of the other buffers on the list.
+     This buffer therefore becomes the least desirable candidate for
+     `other-buffer' to return.
+
+     If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
+     current buffer.  In addition, if the buffer is displayed in the
+     selected window, this switches to some other buffer (obtained using
+     `other-buffer') in the selected window.  But if the buffer is
+     displayed in some other window, it remains displayed there.
+
+     If you wish to replace a buffer in all the windows that display
+     it, use `replace-buffer-in-windows'.  *Note Buffers and Windows::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: String Properties,  Next: Formatting Strings,  Prev: Modifying Strings,  Up: Strings and Characters
+File: lispref.info,  Node: Creating Buffers,  Next: Killing Buffers,  Prev: The Buffer List,  Up: Buffers

 
 

-String Properties
-=================
+Creating Buffers
+================
+
+This section describes the two primitives for creating buffers.
+`get-buffer-create' creates a buffer if it finds no existing buffer
+with the specified name; `generate-new-buffer' always creates a new
+buffer and gives it a unique name.
+
+   Other functions you can use to create buffers include
+`with-output-to-temp-buffer' (*note Temporary Displays::) and
+`create-file-buffer' (*note Visiting Files::).  Starting a subprocess
+can also create a buffer (*note Processes::).
+
+ - Function: get-buffer-create name
+     This function returns a buffer named NAME.  It returns an existing
+     buffer with that name, if one exists; otherwise, it creates a new
+     buffer.  The buffer does not become the current buffer--this
+     function does not change which buffer is current.
+
+     An error is signaled if NAME is not a string.
+
+          (get-buffer-create "foo")
+               => #<buffer foo>

 
 

-   Just as with symbols, extents, faces, and glyphs, you can attach
-additional information to strings in the form of "string properties".
-These differ from text properties, which are logically attached to
-particular characters in the string.
+     The major mode for the new buffer is set to Fundamental mode.  The
+     variable `default-major-mode' is handled at a higher level.  *Note
+     Auto Major Mode::.

 
 

-   To attach a property to a string, use `put'.  To retrieve a property
-from a string, use `get'.  You can also use `remprop' to remove a
-property from a string and `object-plist' to retrieve a list of all the
-properties in a string.
+ - Function: generate-new-buffer name
+     This function returns a newly created, empty buffer, but does not
+     make it current.  If there is no buffer named NAME, then that is
+     the name of the new buffer.  If that name is in use, this function
+     adds suffixes of the form `<N>' to NAME, where N is an integer.
+     It tries successive integers starting with 2 until it finds an
+     available name.
+
+     An error is signaled if NAME is not a string.
+
+          (generate-new-buffer "bar")
+               => #<buffer bar>
+          (generate-new-buffer "bar")
+               => #<buffer bar<2>>
+          (generate-new-buffer "bar")
+               => #<buffer bar<3>>
+
+     The major mode for the new buffer is set to Fundamental mode.  The
+     variable `default-major-mode' is handled at a higher level.  *Note
+     Auto Major Mode::.
+
+     See the related function `generate-new-buffer-name' in *Note
+     Buffer Names::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Formatting Strings,  Next: Character Case,  Prev: String Properties,  Up: Strings and Characters
+File: lispref.info,  Node: Killing Buffers,  Next: Indirect Buffers,  Prev: Creating Buffers,  Up: Buffers

 
 

-Formatting Strings
-==================
+Killing Buffers
+===============

 
 

-   "Formatting" means constructing a string by substitution of computed
-values at various places in a constant string.  This string controls
-how the other values are printed as well as where they appear; it is
-called a "format string".
-
-   Formatting is often useful for computing messages to be displayed.
-In fact, the functions `message' and `error' provide the same
-formatting feature described here; they differ from `format' only in
-how they use the result of formatting.
-
- - Function: format string &rest objects
-     This function returns a new string that is made by copying STRING
-     and then replacing any format specification in the copy with
-     encodings of the corresponding OBJECTS.  The arguments OBJECTS are
-     the computed values to be formatted.
-
-   A format specification is a sequence of characters beginning with a
-`%'.  Thus, if there is a `%d' in STRING, the `format' function
-replaces it with the printed representation of one of the values to be
-formatted (one of the arguments OBJECTS).  For example:
-
-     (format "The value of fill-column is %d." fill-column)
-          => "The value of fill-column is 72."
-
-   If STRING contains more than one format specification, the format
-specifications correspond with successive values from OBJECTS.  Thus,
-the first format specification in STRING uses the first such value, the
-second format specification uses the second such value, and so on.  Any
-extra format specifications (those for which there are no corresponding
-values) cause unpredictable behavior.  Any extra values to be formatted
-are ignored.
-
-   Certain format specifications require values of particular types.
-However, no error is signaled if the value actually supplied fails to
-have the expected type.  Instead, the output is likely to be
-meaningless.
-
-   Here is a table of valid format specifications:
-
-`%s'
-     Replace the specification with the printed representation of the
-     object, made without quoting.  Thus, strings are represented by
-     their contents alone, with no `"' characters, and symbols appear
-     without `\' characters.  This is equivalent to printing the object
-     with `princ'.
-
-     If there is no corresponding object, the empty string is used.
-
-`%S'
-     Replace the specification with the printed representation of the
-     object, made with quoting.  Thus, strings are enclosed in `"'
-     characters, and `\' characters appear where necessary before
-     special characters.  This is equivalent to printing the object
-     with `prin1'.
-
-     If there is no corresponding object, the empty string is used.
-
-`%o'
-     Replace the specification with the base-eight representation of an
-     integer.
-
-`%d'
-`%i'
-     Replace the specification with the base-ten representation of an
-     integer.
-
-`%x'
-     Replace the specification with the base-sixteen representation of
-     an integer, using lowercase letters.
-
-`%X'
-     Replace the specification with the base-sixteen representation of
-     an integer, using uppercase letters.
-
-`%c'
-     Replace the specification with the character which is the value
-     given.
-
-`%e'
-     Replace the specification with the exponential notation for a
-     floating point number (e.g. `7.85200e+03').
-
-`%f'
-     Replace the specification with the decimal-point notation for a
-     floating point number.
-
-`%g'
-     Replace the specification with notation for a floating point
-     number, using a "pretty format".  Either exponential notation or
-     decimal-point notation will be used (usually whichever is
-     shorter), and trailing zeroes are removed from the fractional part.
-
-`%%'
-     A single `%' is placed in the string.  This format specification is
-     unusual in that it does not use a value.  For example, `(format "%%
-     %d" 30)' returns `"% 30"'.
-
-   Any other format character results in an `Invalid format operation'
-error.
-
-   Here are several examples:
-
-     (format "The name of this buffer is %s." (buffer-name))
-          => "The name of this buffer is strings.texi."
-     
-     (format "The buffer object prints as %s." (current-buffer))
-          => "The buffer object prints as #<buffer strings.texi>."
-     
-     (format "The octal value of %d is %o,
-              and the hex value is %x." 18 18 18)
-          => "The octal value of 18 is 22,
-              and the hex value is 12."
+"Killing a buffer" makes its name unknown to XEmacs and makes its text
+space available for other use.
+
+   The buffer object for the buffer that has been killed remains in
+existence as long as anything refers to it, but it is specially marked
+so that you cannot make it current or display it.  Killed buffers retain
+their identity, however; two distinct buffers, when killed, remain
+distinct according to `eq'.
+
+   If you kill a buffer that is current or displayed in a window, XEmacs
+automatically selects or displays some other buffer instead.  This means
+that killing a buffer can in general change the current buffer.
+Therefore, when you kill a buffer, you should also take the precautions
+associated with changing the current buffer (unless you happen to know
+that the buffer being killed isn't current).  *Note Current Buffer::.
+
+   If you kill a buffer that is the base buffer of one or more indirect
+buffers, the indirect buffers are automatically killed as well.
+
+   The `buffer-name' of a killed buffer is `nil'.  To test whether a
+buffer has been killed, you can either use this feature or the function
+`buffer-live-p'.
+
+ - Function: buffer-live-p object
+     This function returns `t' if OBJECT is an editor buffer that has
+     not been deleted, `nil' otherwise.
+
+ - Command: kill-buffer buffer-or-name
+     This function kills the buffer BUFFER-OR-NAME, freeing all its
+     memory for use as space for other buffers.  (Emacs version 18 and
+     older was unable to return the memory to the operating system.)
+     It returns `nil'.  The argument BUFFER-OR-NAME may be a buffer or
+     the name of one.
+
+     Any processes that have this buffer as the `process-buffer' are
+     sent the `SIGHUP' signal, which normally causes them to terminate.
+     (The basic meaning of `SIGHUP' is that a dialup line has been
+     disconnected.)  *Note Deleting Processes::.
+
+     If the buffer is visiting a file and contains unsaved changes,
+     `kill-buffer' asks the user to confirm before the buffer is killed.
+     It does this even if not called interactively.  To prevent the
+     request for confirmation, clear the modified flag before calling
+     `kill-buffer'.  *Note Buffer Modification::.
+
+     Killing a buffer that is already dead has no effect.
+
+          (kill-buffer "foo.unchanged")
+               => nil
+          (kill-buffer "foo.changed")
+          
+          ---------- Buffer: Minibuffer ----------
+          Buffer foo.changed modified; kill anyway? (yes or no) yes
+          ---------- Buffer: Minibuffer ----------
+          
+               => nil

 
 

-   There are many additional flags and specifications that can occur
-between the `%' and the format character, in the following order:
+ - Variable: kill-buffer-query-functions
+     After confirming unsaved changes, `kill-buffer' calls the functions
+     in the list `kill-buffer-query-functions', in order of appearance,
+     with no arguments.  The buffer being killed is the current buffer
+     when they are called.  The idea is that these functions ask for
+     confirmation from the user for various nonstandard reasons.  If
+     any of them returns `nil', `kill-buffer' spares the buffer's life.
+
+ - Variable: kill-buffer-hook
+     This is a normal hook run by `kill-buffer' after asking all the
+     questions it is going to ask, just before actually killing the
+     buffer.  The buffer to be killed is current when the hook
+     functions run.  *Note Hooks::.
+
+ - Variable: buffer-offer-save
+     This variable, if non-`nil' in a particular buffer, tells
+     `save-buffers-kill-emacs' and `save-some-buffers' to offer to save
+     that buffer, just as they offer to save file-visiting buffers.  The
+     variable `buffer-offer-save' automatically becomes buffer-local
+     when set for any reason.  *Note Buffer-Local Variables::.

 
 

-  1. An optional repositioning specification, which is a positive
-     integer followed by a `$'.
+\1f
+File: lispref.info,  Node: Indirect Buffers,  Prev: Killing Buffers,  Up: Buffers

 
 

-  2. Zero or more of the optional flag characters `-', `+', ` ', `0',
-     and `#'.
+Indirect Buffers
+================

 
 

-  3. An asterisk (`*', meaning that the field width is now assumed to
-     have been specified as an argument.
+An "indirect buffer" shares the text of some other buffer, which is
+called the "base buffer" of the indirect buffer.  In some ways it is
+the analogue, for buffers, of a symbolic link among files.  The base
+buffer may not itself be an indirect buffer.  One base buffer may have
+several "indirect children".

 
 

-  4. An optional minimum field width.
+   The text of the indirect buffer is always identical to the text of
+its base buffer; changes made by editing either one are visible
+immediately in the other.

 
 

-  5. An optional precision, preceded by a `.' character.
+   But in all other respects, the indirect buffer and its base buffer
+are completely separate.  They have different names, different values of
+point and mark, different narrowing, different markers and extents
+(though inserting or deleting text in either buffer relocates the
+markers and extents for both), different major modes, and different
+local variables.  Unlike in FSF Emacs, XEmacs indirect buffers do not
+automatically share text properties among themselves and their base
+buffer.

 
 

-   A "repositioning" specification changes which argument to `format'
-is used by the current and all following format specifications.
-Normally the first specification uses the first argument, the second
-specification uses the second argument, etc.  Using a repositioning
-specification, you can change this.  By placing a number N followed by
-a `$' between the `%' and the format character, you cause the
-specification to use the Nth argument.  The next specification will use
-the N+1'th argument, etc.
+   An indirect buffer cannot visit a file, but its base buffer can.  If
+you try to save the indirect buffer, that actually works by saving the
+base buffer.

 
 

-   For example:
+   Killing an indirect buffer has no effect on its base buffer.  Killing
+the base buffer kills all its indirect children.

 
 

-     (format "Can't find file `%s' in directory `%s'."
-             "ignatius.c" "loyola/")
-          => "Can't find file `ignatius.c' in directory `loyola/'."
-     
-     (format "In directory `%2$s', the file `%1$s' was not found."
-             "ignatius.c" "loyola/")
-          => "In directory `loyola/', the file `ignatius.c' was not found."
-     
-     (format
-         "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
-         37 12)
-     => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
-
-   As you can see, this lets you reprocess arguments more than once or
-reword a format specification (thereby moving the arguments around)
-without having to actually reorder the arguments.  This is especially
-useful in translating messages from one language to another: Different
-languages use different word orders, and this sometimes entails changing
-the order of the arguments.  By using repositioning specifications,
-this can be accomplished without having to embed knowledge of particular
-languages into the location in the program's code where the message is
-displayed.
-
-   All the specification characters allow an optional numeric prefix
-between the `%' and the character, and following any repositioning
-specification or flag.  The optional numeric prefix defines the minimum
-width for the object.  If the printed representation of the object
-contains fewer characters than this, then it is padded.  The padding is
-normally on the left, but will be on the right if the `-' flag
-character is given.  The padding character is normally a space, but if
-the `0' flag character is given, zeros are used for padding.
-
-     (format "%06d is padded on the left with zeros" 123)
-          => "000123 is padded on the left with zeros"
-     
-     (format "%-6d is padded on the right" 123)
-          => "123    is padded on the right"
-
-   `format' never truncates an object's printed representation, no
-matter what width you specify.  Thus, you can use a numeric prefix to
-specify a minimum spacing between columns with no risk of losing
-information.
-
-   In the following three examples, `%7s' specifies a minimum width of
-7.  In the first case, the string inserted in place of `%7s' has only 3
-letters, so 4 blank spaces are inserted for padding.  In the second
-case, the string `"specification"' is 13 letters wide but is not
-truncated.  In the third case, the padding is on the right.
-
-     (format "The word `%7s' actually has %d letters in it."
-             "foo" (length "foo"))
-          => "The word `    foo' actually has 3 letters in it."
-     
-     (format "The word `%7s' actually has %d letters in it."
-             "specification" (length "specification"))
-          => "The word `specification' actually has 13 letters in it."
-     
-     (format "The word `%-7s' actually has %d letters in it."
-             "foo" (length "foo"))
-          => "The word `foo    ' actually has 3 letters in it."
+ - Command: make-indirect-buffer base-buffer name
+     This creates an indirect buffer named NAME whose base buffer is
+     BASE-BUFFER.  The argument BASE-BUFFER may be a buffer or a string.
+
+     If BASE-BUFFER is an indirect buffer, its base buffer is used as
+     the base for the new buffer.

 
 

-   After any minimum field width, a precision may be specified by
-preceding it with a `.' character.  The precision specifies the minimum
-number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
-conversions (the number is padded on the left with zeroes as
-necessary); the number of digits printed after the decimal point for
-`%f', `%e', and `%E' conversions; the number of significant digits
-printed in `%g' and `%G' conversions; and the maximum number of
-non-padding characters printed in `%s' and `%S' conversions.  The
-default precision for floating-point conversions is six.
+          (make-indirect-buffer "*scratch*" "indirect")
+               => #<buffer "indirect">

 
 

-   The other flag characters have the following meanings:
+ - Function: buffer-base-buffer &optional buffer
+     This function returns the base buffer of BUFFER.  If BUFFER is not
+     indirect, the value is `nil'.  Otherwise, the value is another
+     buffer, which is never an indirect buffer.  If BUFFER is not
+     supplied, it defaults to the current buffer.

 
 

-   * The ` ' flag means prefix non-negative numbers with a space.
+          (buffer-base-buffer (get-buffer "indirect"))
+               => #<buffer "*scratch*">

 
 

-   * The `+' flag means prefix non-negative numbers with a plus sign.
+ - Function: buffer-indirect-children &optional buffer
+     This function returns a list of all indirect buffers whose base
+     buffer is BUFFER.  If BUFFER is indirect, the return value will
+     always be `nil'; see `make-indirect-buffer'.  If BUFFER is not
+     supplied, it defaults to the current buffer.

 
 

-   * The `#' flag means print numbers in an alternate, more verbose
-     format: octal numbers begin with zero; hex numbers begin with a
-     `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
-     conversions even if no numbers are printed after it; and trailing
-     zeroes are not omitted in `%g' and `%G' conversions.
+          (buffer-indirect-children (get-buffer "*scratch*"))
+               => (#<buffer "indirect">)

 
 \1f
 
 \1f

-File: lispref.info,  Node: Character Case,  Next: Case Tables,  Prev: Formatting Strings,  Up: Strings and Characters
+File: lispref.info,  Node: Windows,  Next: Frames,  Prev: Buffers,  Up: Top

 
 

-Character Case
-==============
+Windows
+*******

 
 

-   The character case functions change the case of single characters or
-of the contents of strings.  The functions convert only alphabetic
-characters (the letters `A' through `Z' and `a' through `z'); other
-characters are not altered.  The functions do not modify the strings
-that are passed to them as arguments.
+This chapter describes most of the functions and variables related to
+Emacs windows.  See *Note Display::, for information on how text is
+displayed in windows.

 
 

-   The examples below use the characters `X' and `x' which have ASCII
-codes 88 and 120 respectively.
+* Menu:

 
 

- - Function: downcase string-or-char &optional buffer
-     This function converts a character or a string to lower case.
+* 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.
+* Choosing Window::       How to choose a window for displaying a buffer.
+* 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.
+* Position of Window::     Accessing the position of a window.
+* Resizing Windows::       Changing the size of a window.
+* Window Configurations::  Saving and restoring the state of the screen.

 
 

-     When the argument to `downcase' is a string, the function creates
-     and returns a new string in which each letter in the argument that
-     is upper case is converted to lower case.  When the argument to
-     `downcase' is a character, `downcase' returns the corresponding
-     lower case character. (This value is actually an integer under
-     XEmacs 19.) If the original character is lower case, or is not a
-     letter, then the value equals the original character.
+\1f
+File: lispref.info,  Node: Basic Windows,  Next: Splitting Windows,  Up: Windows

 
 

-     Optional second arg BUFFER specifies which buffer's case tables to
-     use, and defaults to the current buffer.
+Basic Concepts of Emacs Windows
+===============================

 
 

-          (downcase "The cat in the hat")
-               => "the cat in the hat"
-          
-          (downcase ?X)
-               => ?x   ;; Under XEmacs 20.
-               => 120  ;; Under XEmacs 19.
+A "window" in XEmacs is the physical area of the screen in which a
+buffer is displayed.  The term is also used to refer to a Lisp object
+that represents that screen area in XEmacs Lisp.  It should be clear
+from the context which is meant.

 
 

- - Function: upcase string-or-char &optional buffer
-     This function converts a character or a string to upper case.
+   XEmacs groups windows into frames.  A frame represents an area of
+screen available for XEmacs to use.  Each frame always contains at least
+one window, but you can subdivide it vertically or horizontally into
+multiple nonoverlapping Emacs windows.

 
 

-     When the argument to `upcase' is a string, the function creates
-     and returns a new string in which each letter in the argument that
-     is lower case is converted to upper case.
+   In each frame, at any time, one and only one window is designated as
+"selected within the frame".  The frame's cursor appears in that
+window.  At ant time, one frame is the selected frame; and the window
+selected within that frame is "the selected window".  The selected
+window's buffer is usually the current buffer (except when `set-buffer'
+has been used).  *Note Current Buffer::.

 
 

-     When the argument to `upcase' is a character, `upcase' returns the
-     corresponding upper case character. (This value is actually an
-     integer under XEmacs 19.)  If the original character is upper
-     case, or is not a letter, then the value equals the original
-     character.
+   For practical purposes, a window exists only while it is displayed in
+a frame.  Once removed from the frame, the window is effectively deleted
+and should not be used, _even though there may still be references to
+it_ from other Lisp objects.  Restoring a saved window configuration is
+the only way for a window no longer on the screen to come back to life.
+(*Note Deleting Windows::.)

 
 

-     Optional second arg BUFFER specifies which buffer's case tables to
-     use, and defaults to the current buffer.
+   Each window has the following attributes:

 
 

-          (upcase "The cat in the hat")
-               => "THE CAT IN THE HAT"
-          
-          (upcase ?x)
-               => ?X   ;; Under XEmacs 20.
-               => 88   ;; Under XEmacs 19.
-
- - Function: capitalize string-or-char &optional buffer
-     This function capitalizes strings or characters.  If
-     STRING-OR-CHAR is a string, the function creates and returns a new
-     string, whose contents are a copy of STRING-OR-CHAR in which each
-     word has been capitalized.  This means that the first character of
-     each word is converted to upper case, and the rest are converted
-     to lower case.
-
-     The definition of a word is any sequence of consecutive characters
-     that are assigned to the word constituent syntax class in the
-     current syntax table (*note Syntax Class Table::).
-
-     When the argument to `capitalize' is a character, `capitalize' has
-     the same result as `upcase'.
-
-     Optional second arg BUFFER specifies which buffer's case tables to
-     use, and defaults to the current buffer.
-
-          (capitalize "The cat in the hat")
-               => "The Cat In The Hat"
-          
-          (capitalize "THE 77TH-HATTED CAT")
-               => "The 77th-Hatted Cat"
+   * containing frame
+
+   * window height
+
+   * window width
+
+   * window edges with respect to the frame or screen
+
+   * the buffer it displays
+
+   * position within the buffer at the upper left of the window
+
+   * amount of horizontal scrolling, in columns
+
+   * point
+
+   * the mark
+
+   * how recently the window was selected
+
+   Users create multiple windows so they can look at several buffers at
+once.  Lisp libraries use multiple windows for a variety of reasons, but
+most often to display related information.  In Rmail, for example, you
+can move through a summary buffer in one window while the other window
+shows messages one at a time as they are reached.
+
+   The meaning of "window" in XEmacs is similar to what it means in the
+context of general-purpose window systems such as X, but not identical.
+The X Window System places X windows on the screen; XEmacs uses one or
+more X windows as frames, and subdivides them into Emacs windows.  When
+you use XEmacs on a character-only terminal, XEmacs treats the whole
+terminal screen as one frame.
+
+   Most window systems support arbitrarily located overlapping windows.
+In contrast, Emacs windows are "tiled"; they never overlap, and
+together they fill the whole screen or frame.  Because of the way in
+which XEmacs creates new windows and resizes them, you can't create
+every conceivable tiling of windows on an Emacs frame.  *Note Splitting
+Windows::, and *Note Size of Window::.
+
+   *Note Display::, for information on how the contents of the window's
+buffer are displayed in the window.
+
+ - Function: windowp object
+     This function returns `t' if OBJECT is a window.
+
+\1f
+File: lispref.info,  Node: Splitting Windows,  Next: Deleting Windows,  Prev: Basic Windows,  Up: Windows
+
+Splitting Windows
+=================
+
+The functions described here are the primitives used to split a window
+into two windows.  Two higher level functions sometimes split a window,
+but not always: `pop-to-buffer' and `display-buffer' (*note Displaying
+Buffers::).
+
+   The functions described here do not accept a buffer as an argument.
+The two "halves" of the split window initially display the same buffer
+previously visible in the window that was split.
+
+ - Function: one-window-p &optional nomini which-frames which-devices
+     This function returns non-`nil' if there is only one window.  The
+     argument NOMINI, if non-`nil', means don't count the minibuffer
+     even if it is active; otherwise, the minibuffer window is
+     included, if active, in the total number of windows which is
+     compared against one.
+
+     The remaining arguments controls which set of windows are counted,
+     as with `next-window'.
+
+ - Command: split-window &optional window size horizontal
+     This function splits WINDOW into two windows.  The original window
+     WINDOW remains the selected window, but occupies only part of its
+     former screen area.  The rest is occupied by a newly created
+     window which is returned as the value of this function.
+
+     If HORIZONTAL is non-`nil', then WINDOW splits into two side by
+     side windows.  The original window WINDOW keeps the leftmost SIZE
+     columns, and gives the rest of the columns to the new window.
+     Otherwise, it splits into windows one above the other, and WINDOW
+     keeps the upper SIZE lines and gives the rest of the lines to the
+     new window.  The original window is therefore the left-hand or
+     upper of the two, and the new window is the right-hand or lower.
+
+     If WINDOW is omitted or `nil', then the selected window is split.
+     If SIZE is omitted or `nil', then WINDOW is divided evenly into
+     two parts.  (If there is an odd line, it is allocated to the new
+     window.)  When `split-window' is called interactively, all its
+     arguments are `nil'.
+
+     The following example starts with one window on a frame that is 50
+     lines high by 80 columns wide; then the window is split.
+
+          (setq w (selected-window))
+               => #<window 8 on windows.texi>
+          (window-edges)          ; Edges in order:
+               => (0 0 80 50)     ;   left-top-right-bottom

           
           

-          (capitalize ?x)
-               => ?X   ;; Under XEmacs 20.
-               => 88   ;; Under XEmacs 19.
+          ;; Returns window created
+          (setq w2 (split-window w 15))
+               => #<window 28 on windows.texi>
+          (window-edges w2)
+               => (0 15 80 50)    ; Bottom window;
+                                  ;   top is line 15
+          (window-edges w)
+               => (0 0 80 15)     ; Top window
+
+     The frame looks like this:
+
+                   __________
+                  |          |  line 0
+                  |    w     |
+                  |__________|
+                  |          |  line 15
+                  |    w2    |
+                  |__________|
+                                line 50
+           column 0   column 80
+
+     Next, the top window is split horizontally:
+
+          (setq w3 (split-window w 35 t))
+               => #<window 32 on windows.texi>
+          (window-edges w3)
+               => (35 0 80 15)  ; Left edge at column 35
+          (window-edges w)
+               => (0 0 35 15)   ; Right edge at column 35
+          (window-edges w2)
+               => (0 15 80 50)  ; Bottom window unchanged
+
+     Now, the screen looks like this:
+
+               column 35
+                   __________
+                  |   |      |  line 0
+                  | w |  w3  |
+                  |___|______|
+                  |          |  line 15
+                  |    w2    |
+                  |__________|
+                                line 50
+           column 0   column 80
+
+     Normally, Emacs indicates the border between two side-by-side
+     windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
+     or `|' characters.  The display table can specify alternative
+     border characters; see *Note Display Tables::.
+
+ - Command: split-window-vertically &optional size
+     This function splits the selected window into two windows, one
+     above the other, leaving the selected window with SIZE lines.
+
+     This function is simply an interface to `split-window'.  Here is
+     the complete function definition for it:
+
+          (defun split-window-vertically (&optional arg)
+            "Split current window into two windows, one above the other."
+            (interactive "P")
+            (split-window nil (and arg (prefix-numeric-value arg))))
+
+ - Command: split-window-horizontally &optional size
+     This function splits the selected window into two windows
+     side-by-side, leaving the selected window with SIZE columns.
+
+     This function is simply an interface to `split-window'.  Here is
+     the complete definition for `split-window-horizontally' (except for
+     part of the documentation string):
+
+          (defun split-window-horizontally (&optional arg)
+            "Split selected window into two windows, side by side..."
+            (interactive "P")
+            (split-window nil (and arg (prefix-numeric-value arg)) t))

 
 \1f
 
 \1f

-File: lispref.info,  Node: Case Tables,  Next: Char Tables,  Prev: Character Case,  Up: Strings and Characters
+File: lispref.info,  Node: Deleting Windows,  Next: Selecting Windows,  Prev: Splitting Windows,  Up: Windows

 
 

-The Case Table
-==============
+Deleting Windows
+================

 
 

-   You can customize case conversion by installing a special "case
-table".  A case table specifies the mapping between upper case and lower
-case letters.  It affects both the string and character case conversion
-functions (see the previous section) and those that apply to text in the
-buffer (*note Case Changes::).  You need a case table if you are using a
-language which has letters other than the standard ASCII letters.
+A window remains visible on its frame unless you "delete" it by calling
+certain functions that delete windows.  A deleted window cannot appear
+on the screen, but continues to exist as a Lisp object until there are
+no references to it.  There is no way to cancel the deletion of a
+window aside from restoring a saved window configuration (*note Window
+Configurations::).  Restoring a window configuration also deletes any
+windows that aren't part of that configuration.

 
 

-   A case table is a list of this form:
+   When you delete a window, the space it took up is given to one
+adjacent sibling.  (In Emacs version 18, the space was divided evenly
+among all the siblings.)

 
 

-     (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
+ - Function: window-live-p window
+     This function returns `nil' if WINDOW is deleted, and `t'
+     otherwise.

 
 

-where each element is either `nil' or a string of length 256.  The
-element DOWNCASE says how to map each character to its lower-case
-equivalent.  The element UPCASE maps each character to its upper-case
-equivalent.  If lower and upper case characters are in one-to-one
-correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
-table from DOWNCASE.
+     *Warning:* Erroneous information or fatal errors may result from
+     using a deleted window as if it were live.

 
 

-   For some languages, upper and lower case letters are not in
-one-to-one correspondence.  There may be two different lower case
-letters with the same upper case equivalent.  In these cases, you need
-to specify the maps for both directions.
+ - Command: delete-window &optional window force
+     This function removes WINDOW from the display.  If WINDOW is
+     omitted, then the selected window is deleted. If window is the
+     only one on its frame, the frame is deleted as well.

 
 

-   The element CANONICALIZE maps each character to a canonical
-equivalent; any two characters that are related by case-conversion have
-the same canonical equivalent character.
+     Normally, you cannot delete the last non-minibuffer-only frame
+     (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
+     is signaled instead.  However, if optional second argument FORCE is
+     non-`nil', you can delete the last frame. (This will automatically
+     call `save-buffers-kill-emacs'.)

 
 

-   The element EQUIVALENCES is a map that cyclicly permutes each
-equivalence class (of characters with the same canonical equivalent).
-(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
-likewise for each set of equivalent characters.)
+     This function returns `nil'.

 
 

-   When you construct a case table, you can provide `nil' for
-CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
-You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
-string from CANONICALIZE.  In a case table that is actually in use,
-those components are non-`nil'.  Do not try to specify EQUIVALENCES
-without also specifying CANONICALIZE.
+     When `delete-window' is called interactively, the selected window
+     is deleted.

 
 

-   Each buffer has a case table.  XEmacs also has a "standard case
-table" which is copied into each buffer when you create the buffer.
-Changing the standard case table doesn't affect any existing buffers.
+ - Command: delete-other-windows &optional window
+     This function makes WINDOW the only window on its frame, by
+     deleting the other windows in that frame.  If WINDOW is omitted or
+     `nil', then the selected window is used by default.

 
 

-   Here are the functions for working with case tables:
+     The result is `nil'.

 
 

- - Function: case-table-p object
-     This predicate returns non-`nil' if OBJECT is a valid case table.
+ - Command: delete-windows-on buffer &optional which-frames
+          which-devices
+     This function deletes all windows showing BUFFER.  If there are no
+     windows showing BUFFER, it does nothing.

 
 

- - Function: set-standard-case-table case-table
-     This function makes CASE-TABLE the standard case table, so that it
-     will apply to any buffers created subsequently.
+     `delete-windows-on' operates frame by frame.  If a frame has
+     several windows showing different buffers, then those showing
+     BUFFER are removed, and the others expand to fill the space.  If
+     all windows in some frame are showing BUFFER (including the case
+     where there is only one window), then the frame reverts to having a
+     single window showing another buffer chosen with `other-buffer'.
+     *Note The Buffer List::.

 
 

- - Function: standard-case-table
-     This returns the standard case table.
+     The argument WHICH-FRAMES controls which frames to operate on:

 
 

- - Function: current-case-table &optional buffer
-     This function returns the case table of BUFFER, which defaults to
-     the current buffer.
+    `nil'
+          Delete all windows showing BUFFER in any frame.
+
+    `t'
+          Delete only windows showing BUFFER in the selected frame.
+
+    `visible'
+          Delete all windows showing BUFFER in any visible frame.
+
+    `0'
+          Delete all windows showing BUFFER in any visible frame.

 
 

- - Function: set-case-table case-table
-     This sets the current buffer's case table to CASE-TABLE.
+    FRAME
+          If it is a frame, delete all windows showing BUFFER in that
+          frame.

 
 

-   The following three functions are convenient subroutines for packages
-that define non-ASCII character sets.  They modify a string
-DOWNCASE-TABLE provided as an argument; this should be a string to be
-used as the DOWNCASE part of a case table.  They also modify the
-standard syntax table.  *Note Syntax Tables::.
+     *Warning:* This is similar to, but not identical to, the meaning
+     of the WHICH-FRAMES argument to `next-window'; the meanings of
+     `nil' and `t' are reversed.

 
 

- - Function: set-case-syntax-pair uc lc downcase-table
-     This function specifies a pair of corresponding letters, one upper
-     case and one lower case.
+     The optional argument WHICH-DEVICES further clarifies on which
+     devices to search for frames as specified by WHICH-FRAMES.  This
+     value is only meaningful if WHICH-FRAMES is not `t'.

 
 

- - Function: set-case-syntax-delims l r downcase-table
-     This function makes characters L and R a matching pair of
-     case-invariant delimiters.
+    `nil'
+          Consider all devices on the selected console.

 
 

- - Function: set-case-syntax char syntax downcase-table
-     This function makes CHAR case-invariant, with syntax SYNTAX.
+    DEVICE
+          Consider only the one device DEVICE.

 
 

- - Command: describe-buffer-case-table
-     This command displays a description of the contents of the current
-     buffer's case table.
+    CONSOLE
+          Consider all devices on CONSOLE.

 
 

-   You can load the library `iso-syntax' to set up the standard syntax
-table and define a case table for the 8-bit ISO Latin 1 character set.
+    DEVICE-TYPE
+          Consider all devices with device type DEVICE-TYPE.
+
+    `window-system'
+          Consider all devices on window system consoles.
+
+    anything else
+          Consider all devices without restriction.
+
+     This function always returns `nil'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Char Tables,  Prev: Case Tables,  Up: Strings and Characters
+File: lispref.info,  Node: Selecting Windows,  Next: Cyclic Window Ordering,  Prev: Deleting Windows,  Up: Windows

 
 

-The Char Table
-==============
+Selecting Windows
+=================

 
 

-   A char table is a table that maps characters (or ranges of
-characters) to values.  Char tables are specialized for characters,
-only allowing particular sorts of ranges to be assigned values.
-Although this loses in generality, it makes for extremely fast
-(constant-time) lookups, and thus is feasible for applications that do
-an extremely large number of lookups (e.g. scanning a buffer for a
-character in a particular syntax, where a lookup in the syntax table
-must occur once per character).
+When a window is selected, the buffer in the window becomes the current
+buffer, and the cursor will appear in it.

 
 

-   Note that char tables as a primitive type, and all of the functions
-in this section, exist only in XEmacs 20.  In XEmacs 19, char tables are
-generally implemented using a vector of 256 elements.
+ - Function: selected-window &optional device
+     This function returns the selected window.  This is the window in
+     which the cursor appears and to which many commands apply.  Each
+     separate device can have its own selected window, which is
+     remembered as focus changes from device to device.  Optional
+     argument DEVICE specifies which device to return the selected
+     window for, and defaults to the selected device.

 
 

-   When MULE support exists, the types of ranges that can be assigned
-values are
+ - Function: select-window window &optional norecord
+     This function makes WINDOW the selected window.  The cursor then
+     appears in WINDOW (on redisplay).  The buffer being displayed in
+     WINDOW is immediately designated the current buffer.

 
 

-   * all characters
+     If optional argument NORECORD is non-`nil' then the global and
+     per-frame buffer orderings are not modified, as by the function
+     `record-buffer'.

 
 

-   * an entire charset
+     The return value is WINDOW.

 
 

-   * a single row in a two-octet charset
+          (setq w (next-window))
+          (select-window w)
+               => #<window 65 on windows.texi>

 
 

-   * a single character
+ - Special Form: save-selected-window forms...
+     This special form records the selected window, executes FORMS in
+     sequence, then restores the earlier selected window.  It does not
+     save or restore anything about the sizes, arrangement or contents
+     of windows; therefore, if the FORMS change them, the changes are
+     permanent.

 
 

-   When MULE support is not present, the types of ranges that can be
-assigned values are
+   The following functions choose one of the windows on the screen,
+offering various criteria for the choice.

 
 

-   * all characters
+ - Function: get-lru-window &optional which-frames which-devices
+     This function returns the window least recently "used" (that is,
+     selected).  The selected window is always the most recently used
+     window.

 
 

-   * a single character
+     The selected window can be the least recently used window if it is
+     the only window.  A newly created window becomes the least
+     recently used window until it is selected.  A minibuffer window is
+     never a candidate.

 
 

- - Function: char-table-p object
-     This function returns non-`nil' if OBJECT is a char table.
+     By default, only the windows in the selected frame are considered.
+     The optional argument WHICH-FRAMES changes this behavior.  Here
+     are the possible values and their meanings:

 
 

-* Menu:
+    `nil'
+          Consider all the windows in the selected windows's frame,
+          plus the minibuffer used by that frame even if it lies in
+          some other frame.
+
+    `t'
+          Consider all windows in all existing frames.
+
+    `visible'
+          Consider all windows in all visible frames.  (To get useful
+          results, you must ensure WINDOW is in a visible frame.)
+
+    `0'
+          Consider all windows in all visible or iconified frames.
+
+    FRAME
+          Consider all windows on frame FRAME.
+
+    anything else
+          Consider precisely the windows in the selected window's
+          frame, and no others.
+
+     The optional argument WHICH-DEVICES further clarifies on which
+     devices to search for frames as specified by WHICH-FRAMES.  This
+     value is only meaningful if WHICH-FRAMES is non-`nil'.

 
 

-* Char Table Types::            Char tables have different uses.
-* Working With Char Tables::    Creating and working with char tables.
+    `nil'
+          Consider all devices on the selected console.
+
+    DEVICE
+          Consider only the one device DEVICE.
+
+    CONSOLE
+          Consider all devices on CONSOLE.
+
+    DEVICE-TYPE
+          Consider all devices with device type DEVICE-TYPE.
+
+    `window-system'
+          Consider all devices on window system consoles.
+
+    anything else
+          Consider all devices without restriction.
+
+
+ - Function: get-largest-window &optional which-frames which-devices
+     This function returns the window with the largest area (height
+     times width).  If there are no side-by-side windows, then this is
+     the window with the most lines.  A minibuffer window is never a
+     candidate.
+
+     If there are two windows of the same size, then the function
+     returns the window that is first in the cyclic ordering of windows
+     (see following section), starting from the selected window.
+
+     The remaining arguments control which set of windows are
+     considered.  See `next-window', above.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Char Table Types,  Next: Working With Char Tables,  Up: Char Tables
+File: lispref.info,  Node: Cyclic Window Ordering,  Next: Buffers and Windows,  Prev: Selecting Windows,  Up: Windows
+
+Cyclic Ordering of Windows
+==========================

 
 

-Char Table Types
-----------------
+When you use the command `C-x o' (`other-window') to select the next
+window, it moves through all the windows on the screen in a specific
+cyclic order.  For any given configuration of windows, this order never
+varies.  It is called the "cyclic ordering of windows".
+
+   This ordering generally goes from top to bottom, and from left to
+right.  But it may go down first or go right first, depending on the
+order in which the windows were split.
+
+   If the first split was vertical (into windows one above each other),
+and then the subwindows were split horizontally, then the ordering is
+left to right in the top of the frame, and then left to right in the
+next lower part of the frame, and so on.  If the first split was
+horizontal, the ordering is top to bottom in the left part, and so on.
+In general, within each set of siblings at any level in the window tree,
+the order is left to right, or top to bottom.

 
 

-   Each char table type is used for a different purpose and allows
-different sorts of values.  The different char table types are
+ - Function: next-window &optional window minibuf which-frames
+          which-devices
+     This function returns the window following WINDOW in the cyclic
+     ordering of windows.  This is the window that `C-x o' would select
+     if typed when WINDOW is selected.  If WINDOW is the only window
+     visible, then this function returns WINDOW.  If omitted, WINDOW
+     defaults to the selected window.

 
 

-`category'
-     Used for category tables, which specify the regexp categories that
-     a character is in.  The valid values are `nil' or a bit vector of
-     95 elements.  Higher-level Lisp functions are provided for working
-     with category tables.  Currently categories and category tables
-     only exist when MULE support is present.
+     The value of the argument MINIBUF determines whether the
+     minibuffer is included in the window order.  Normally, when
+     MINIBUF is `nil', the minibuffer is included if it is currently
+     active; this is the behavior of `C-x o'.  (The minibuffer window
+     is active while the minibuffer is in use.  *Note Minibuffers::.)

 
 

-`char'
-     A generalized char table, for mapping from one character to
-     another.  Used for case tables, syntax matching tables,
-     `keyboard-translate-table', etc.  The valid values are characters.
+     If MINIBUF is `t', then the cyclic ordering includes the
+     minibuffer window even if it is not active.

 
 

-`generic'
-     An even more generalized char table, for mapping from a character
-     to anything.
+     If MINIBUF is neither `t' nor `nil', then the minibuffer window is
+     not included even if it is active.

 
 

-`display'
-     Used for display tables, which specify how a particular character
-     is to appear when displayed.  #### Not yet implemented.
+     By default, only the windows in the selected frame are considered.
+     The optional argument WHICH-FRAMES changes this behavior.  Here
+     are the possible values and their meanings:
+
+    `nil'
+          Consider all the windows in WINDOW's frame, plus the
+          minibuffer used by that frame even if it lies in some other
+          frame.
+
+    `t'
+          Consider all windows in all existing frames.
+
+    `visible'
+          Consider all windows in all visible frames.  (To get useful
+          results, you must ensure WINDOW is in a visible frame.)
+
+    `0'
+          Consider all windows in all visible or iconified frames.

 
 

-`syntax'
-     Used for syntax tables, which specify the syntax of a particular
-     character.  Higher-level Lisp functions are provided for working
-     with syntax tables.  The valid values are integers.
+    FRAME
+          Consider all windows on frame FRAME.

 
 

- - Function: char-table-type char-table
-     This function returns the type of char table CHAR-TABLE.
+    anything else
+          Consider precisely the windows in WINDOW's frame, and no
+          others.

 
 

- - Function: char-table-type-list
-     This function returns a list of the recognized char table types.
+     The optional argument WHICH-DEVICES further clarifies on which
+     devices to search for frames as specified by WHICH-FRAMES.  This
+     value is only meaningful if WHICH-FRAMES is non-`nil'.

 
 

- - Function: valid-char-table-type-p type
-     This function returns `t' if TYPE if a recognized char table type.
+    `nil'
+          Consider all devices on the selected console.
+
+    DEVICE
+          Consider only the one device DEVICE.
+
+    CONSOLE
+          Consider all devices on CONSOLE.
+
+    DEVICE-TYPE
+          Consider all devices with device type DEVICE-TYPE.
+
+    `window-system'
+          Consider all devices on window system consoles.
+
+    anything else
+          Consider all devices without restriction.
+
+     If you use consistent values for MINIBUF, WHICH-FRAMES, and
+     WHICH-DEVICES, you can use `next-window' to iterate through the
+     entire cycle of acceptable windows, eventually ending up back at
+     the window you started with.  `previous-window' traverses the same
+     cycle, in the reverse order.
+
+     This example assumes there are two windows, both displaying the
+     buffer `windows.texi':
+
+          (selected-window)
+               => #<window 56 on windows.texi>
+          (next-window (selected-window))
+               => #<window 52 on windows.texi>
+          (next-window (next-window (selected-window)))
+               => #<window 56 on windows.texi>
+
+ - Function: previous-window &optional window minibuf which-frames
+          which-devices
+     This function returns the window preceding WINDOW in the cyclic
+     ordering of windows.  The other arguments specify which windows to
+     include in the cycle, as in `next-window'.
+
+ - Command: other-window count &optional which-frames which-devices
+     This function selects the COUNTth following window in the cyclic
+     order.  If COUNT is negative, then it selects the -COUNTth
+     preceding window.  It returns `nil'.
+
+     In an interactive call, COUNT is the numeric prefix argument.
+
+     The other arguments specify which windows to include in the cycle,
+     as in `next-window'.
+
+ - Function: walk-windows function &optional minibuf which-frames
+          which-devices
+     This function cycles through all windows, calling `function' once
+     for each window with the window as its sole argument.
+
+     The other arguments specify which windows to cycle through, as in
+     `next-window'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Working With Char Tables,  Prev: Char Table Types,  Up: Char Tables
+File: lispref.info,  Node: Buffers and Windows,  Next: Displaying Buffers,  Prev: Cyclic Window Ordering,  Up: Windows

 
 

-Working With Char Tables
-------------------------
+Buffers and Windows
+===================

 
 

- - Function: make-char-table type
-     This function makes a new, empty char table of type TYPE.  TYPE
-     should be a symbol, one of `char', `category', `display',
-     `generic', or `syntax'.
+This section describes low-level functions to examine windows or to
+display buffers in windows in a precisely controlled fashion.  *Note
+Displaying Buffers::, for related functions that find a window to use
+and specify a buffer for it.  The functions described there are easier
+to use than these, but they employ heuristics in choosing or creating a
+window; use these functions when you need complete control.

 
 

- - Function: put-char-table range value char-table
-     This function sets the value for chars in RANGE to be VALUE in
-     CHAR-TABLE.
+ - Function: set-window-buffer window buffer-or-name &optional norecord
+     This function makes WINDOW display BUFFER-OR-NAME as its contents.
+     BUFFER-OR-NAME can be a buffer or a buffer name.

 
 

-     RANGE specifies one or more characters to be affected and should be
-     one of the following:
+     With non-`nil' optional argument NORECORD, do not modify the
+     global or per-frame buffer ordering.

 
 

-        * `t' (all characters are affected)
+     This function returns `nil'.

 
 

-        * A charset (only allowed when MULE support is present)
+          (set-window-buffer (selected-window) "foo")
+               => nil

 
 

-        * A vector of two elements: a two-octet charset and a row number
-          (only allowed when MULE support is present)
+ - Function: window-buffer &optional window
+     This function returns the buffer that WINDOW is displaying.  If
+     WINDOW is omitted, this function returns the buffer for the
+     selected window.

 
 

-        * A single character
+          (window-buffer)
+               => #<buffer windows.texi>

 
 

-     VALUE must be a value appropriate for the type of CHAR-TABLE.
+ - Function: get-buffer-window buffer-or-name &optional which-frames
+          which-devices
+     This function returns a window currently displaying
+     BUFFER-OR-NAME, or `nil' if there is none.  If there are several
+     such windows, then the function returns the first one in the
+     cyclic ordering of windows, starting from the selected window.
+     *Note Cyclic Window Ordering::.

 
 

- - Function: get-char-table character char-table
-     This function finds the value for CHARACTER in CHAR-TABLE.
+     The remaining arguments control which windows to consider.  They
+     have the same meaning as for `next-window'.

 
 

- - Function: get-range-char-table range char-table &optional multi
-     This function finds the value for a range in CHAR-TABLE.  If there
-     is more than one value, MULTI is returned (defaults to `nil').
+\1f
+File: lispref.info,  Node: Displaying Buffers,  Next: Choosing Window,  Prev: Buffers and Windows,  Up: Windows

 
 

- - Function: reset-char-table char-table
-     This function resets CHAR-TABLE to its default state.
+Displaying Buffers in Windows
+=============================

 
 

- - Function: map-char-table function char-table &optional range
-     This function maps FUNCTION over entries in CHAR-TABLE, calling it
-     with two args, each key and value in the table.
+In this section we describe convenient functions that choose a window
+automatically and use it to display a specified buffer.  These functions
+can also split an existing window in certain circumstances.  We also
+describe variables that parameterize the heuristics used for choosing a
+window.  *Note Buffers and Windows::, for low-level functions that give
+you more precise control.
+
+   Do not use the functions in this section in order to make a buffer
+current so that a Lisp program can access or modify it; they are too
+drastic for that purpose, since they change the display of buffers in
+windows, which is gratuitous and will surprise the user.  Instead, use
+`set-buffer' (*note Current Buffer::) and `save-excursion' (*note
+Excursions::), which designate buffers as current for programmed access
+without affecting the display of buffers in windows.
+
+ - Command: switch-to-buffer buffer-or-name &optional norecord
+     This function makes BUFFER-OR-NAME the current buffer, and also
+     displays the buffer in the selected window.  This means that a
+     human can see the buffer and subsequent keyboard commands will
+     apply to it.  Contrast this with `set-buffer', which makes
+     BUFFER-OR-NAME the current buffer but does not display it in the
+     selected window.  *Note Current Buffer::.
+
+     If BUFFER-OR-NAME does not identify an existing buffer, then a new
+     buffer by that name is created.  The major mode for the new buffer
+     is set according to the variable `default-major-mode'.  *Note Auto
+     Major Mode::.
+
+     Normally the specified buffer is put at the front of the buffer
+     list.  This affects the operation of `other-buffer'.  However, if
+     NORECORD is non-`nil', this is not done.  *Note The Buffer List::.
+
+     The `switch-to-buffer' function is often used interactively, as
+     the binding of `C-x b'.  It is also used frequently in programs.
+     It always returns `nil'.
+
+ - Command: switch-to-buffer-other-window buffer-or-name
+     This function makes BUFFER-OR-NAME the current buffer and displays
+     it in a window not currently selected.  It then selects that
+     window.  The handling of the buffer is the same as in
+     `switch-to-buffer'.
+
+     The currently selected window is absolutely never used to do the
+     job.  If it is the only window, then it is split to make a
+     distinct window for this purpose.  If the selected window is
+     already displaying the buffer, then it continues to do so, but
+     another window is nonetheless found to display it in as well.
+
+ - Function: pop-to-buffer buffer-or-name &optional other-window
+          on-frame
+     This function makes BUFFER-OR-NAME the current buffer and switches
+     to it in some window, preferably not the window previously
+     selected.  The "popped-to" window becomes the selected window
+     within its frame.
+
+     If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
+     looks for a window in any visible frame already displaying the
+     buffer; if there is one, it returns that window and makes it be
+     selected within its frame.  If there is none, it creates a new
+     frame and displays the buffer in it.
+
+     If `pop-up-frames' is `nil', then `pop-to-buffer' operates
+     entirely within the selected frame.  (If the selected frame has
+     just a minibuffer, `pop-to-buffer' operates within the most
+     recently selected frame that was not just a minibuffer.)
+
+     If the variable `pop-up-windows' is non-`nil', windows may be
+     split to create a new window that is different from the original
+     window.  For details, see *Note Choosing Window::.
+
+     If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
+     another window even if BUFFER-OR-NAME is already visible in the
+     selected window.  Thus BUFFER-OR-NAME could end up displayed in
+     two windows.  On the other hand, if BUFFER-OR-NAME is already
+     displayed in the selected window and OTHER-WINDOW is `nil', then
+     the selected window is considered sufficient display for
+     BUFFER-OR-NAME, so that nothing needs to be done.
+
+     All the variables that affect `display-buffer' affect
+     `pop-to-buffer' as well.  *Note Choosing Window::.
+
+     If BUFFER-OR-NAME is a string that does not name an existing
+     buffer, a buffer by that name is created.  The major mode for the
+     new buffer is set according to the variable `default-major-mode'.
+     *Note Auto Major Mode::.
+
+     If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
+
+     An example use of this function is found at the end of *Note
+     Filter Functions::.
+
+ - Command: replace-buffer-in-windows buffer &optional which-frames
+          which-devices
+     This function replaces BUFFER with some other buffer in all
+     windows displaying it.  The other buffer used is chosen with
+     `other-buffer'.  In the usual applications of this function, you
+     don't care which other buffer is used; you just want to make sure
+     that BUFFER is no longer displayed.
+
+     The optional arguments WHICH-FRAMES and WHICH-DEVICES have the
+     same meaning as with `delete-windows-on'.
+
+     This function returns `nil'.

 
 

-     RANGE specifies a subrange to map over and is in the same format
-     as the RANGE argument to `put-range-table'.  If omitted or `t', it
-     defaults to the entire table.
+\1f
+File: lispref.info,  Node: Choosing Window,  Next: Window Point,  Prev: Displaying Buffers,  Up: Windows

 
 

- - Function: valid-char-table-value-p value char-table-type
-     This function returns non-`nil' if VALUE is a valid value for
-     CHAR-TABLE-TYPE.
+Choosing a Window for Display
+=============================

 
 

- - Function: check-valid-char-table-value value char-table-type
-     This function signals an error if VALUE is not a valid value for
-     CHAR-TABLE-TYPE.
+This section describes the basic facility that chooses a window to
+display a buffer in--`display-buffer'.  All the higher-level functions
+and commands use this subroutine.  Here we describe how to use
+`display-buffer' and how to customize it.
+
+ - Command: display-buffer buffer-or-name &optional not-this-window
+          override-frame
+     This command makes BUFFER-OR-NAME appear in some window, like
+     `pop-to-buffer', but it does not select that window and does not
+     make the buffer current.  The identity of the selected window is
+     unaltered by this function.
+
+     BUFFER-OR-NAME can be a buffer or the name of one.
+
+     If NOT-THIS-WINDOW is non-`nil', it means to display the specified
+     buffer in a window other than the selected one, even if it is
+     already on display in the selected window.  This can cause the
+     buffer to appear in two windows at once.  Otherwise, if
+     BUFFER-OR-NAME is already being displayed in any window, that is
+     good enough, so this function does nothing.
+
+     If OVERRIDE-FRAME is non-`nil', display on that frame instead of
+     the current frame (or the dedicated frame).
+
+     `display-buffer' returns the window chosen to display
+     BUFFER-OR-NAME.
+
+     Precisely how `display-buffer' finds or creates a window depends on
+     the variables described below.
+
+   A window can be marked as "dedicated" to a particular buffer.  Then
+XEmacs will not automatically change which buffer appears in the
+window, such as `display-buffer' might normally do.
+
+ - Function: window-dedicated-p window
+     This function returns WINDOW's dedicated object, usually `t' or
+     `nil'.
+
+ - Function: set-window-buffer-dedicated window buffer
+     This function makes WINDOW display BUFFER and be dedicated to that
+     buffer.  Then XEmacs will not automatically change which buffer
+     appears in WINDOW.  If BUFFER is `nil', this function makes WINDOW
+     not be dedicated (but doesn't change which buffer appears in it
+     currently).
+
+ - User Option: pop-up-windows
+     This variable controls whether `display-buffer' makes new windows.
+     If it is non-`nil' and there is only one window, then that window
+     is split.  If it is `nil', then `display-buffer' does not split
+     the single window, but uses it whole.
+
+ - User Option: split-height-threshold
+     This variable determines when `display-buffer' may split a window,
+     if there are multiple windows.  `display-buffer' always splits the
+     largest window if it has at least this many lines.  If the largest
+     window is not this tall, it is split only if it is the sole window
+     and `pop-up-windows' is non-`nil'.
+
+ - User Option: pop-up-frames
+     This variable controls whether `display-buffer' makes new frames.
+     If it is non-`nil', `display-buffer' looks for an existing window
+     already displaying the desired buffer, on any visible frame.  If
+     it finds one, it returns that window.  Otherwise it makes a new
+     frame.  The variables `pop-up-windows' and
+     `split-height-threshold' do not matter if `pop-up-frames' is
+     non-`nil'.
+
+     If `pop-up-frames' is `nil', then `display-buffer' either splits a
+     window or reuses one.
+
+     *Note Frames::, for more information.
+
+ - Variable: pop-up-frame-function
+     This variable specifies how to make a new frame if `pop-up-frames'
+     is non-`nil'.
+
+     Its value should be a function of no arguments.  When
+     `display-buffer' makes a new frame, it does so by calling that
+     function, which should return a frame.  The default value of the
+     variable is a function that creates a frame using properties from
+     `pop-up-frame-plist'.
+
+ - Variable: pop-up-frame-plist
+     This variable holds a plist specifying frame properties used when
+     `display-buffer' makes a new frame.  *Note Frame Properties::, for
+     more information about frame properties.
+
+ - Variable: special-display-buffer-names
+     A list of buffer names for buffers that should be displayed
+     specially.  If the buffer's name is in this list, `display-buffer'
+     handles the buffer specially.
+
+     By default, special display means to give the buffer a dedicated
+     frame.
+
+     If an element is a list, instead of a string, then the CAR of the
+     list is the buffer name, and the rest of the list says how to
+     create the frame.  There are two possibilities for the rest of the
+     list.  It can be a plist, specifying frame properties, or it can
+     contain a function and arguments to give to it.  (The function's
+     first argument is always the buffer to be displayed; the arguments
+     from the list come after that.)
+
+ - Variable: special-display-regexps
+     A list of regular expressions that specify buffers that should be
+     displayed specially.  If the buffer's name matches any of the
+     regular expressions in this list, `display-buffer' handles the
+     buffer specially.
+
+     By default, special display means to give the buffer a dedicated
+     frame.
+
+     If an element is a list, instead of a string, then the CAR of the
+     list is the regular expression, and the rest of the list says how
+     to create the frame.  See above, under
+     `special-display-buffer-names'.
+
+ - Variable: special-display-function
+     This variable holds the function to call to display a buffer
+     specially.  It receives the buffer as an argument, and should
+     return the window in which it is displayed.
+
+     The default value of this variable is
+     `special-display-popup-frame'.
+
+ - Function: special-display-popup-frame buffer
+     This function makes BUFFER visible in a frame of its own.  If
+     BUFFER is already displayed in a window in some frame, it makes
+     the frame visible and raises it, to use that window.  Otherwise, it
+     creates a frame that will be dedicated to BUFFER.
+
+     This function uses an existing window displaying BUFFER whether or
+     not it is in a frame of its own; but if you set up the above
+     variables in your init file, before BUFFER was created, then
+     presumably the window was previously made by this function.
+
+ - User Option: special-display-frame-plist
+     This variable holds frame properties for
+     `special-display-popup-frame' to use when it creates a frame.
+
+ - Variable: same-window-buffer-names
+     A list of buffer names for buffers that should be displayed in the
+     selected window.  If the buffer's name is in this list,
+     `display-buffer' handles the buffer by switching to it in the
+     selected window.
+
+ - Variable: same-window-regexps
+     A list of regular expressions that specify buffers that should be
+     displayed in the selected window.  If the buffer's name matches
+     any of the regular expressions in this list, `display-buffer'
+     handles the buffer by switching to it in the selected window.
+
+ - Variable: display-buffer-function
+     This variable is the most flexible way to customize the behavior of
+     `display-buffer'.  If it is non-`nil', it should be a function
+     that `display-buffer' calls to do the work.  The function should
+     accept two arguments, the same two arguments that `display-buffer'
+     received.  It should choose or create a window, display the
+     specified buffer, and then return the window.
+
+     This hook takes precedence over all the other options and hooks
+     described above.
+
+   A window can be marked as "dedicated" to its buffer.  Then
+`display-buffer' does not try to use that window.
+
+ - Function: window-dedicated-p window
+     This function returns `t' if WINDOW is marked as dedicated;
+     otherwise `nil'.
+
+ - Function: set-window-dedicated-p window flag
+     This function marks WINDOW as dedicated if FLAG is non-`nil', and
+     nondedicated otherwise.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Lists,  Next: Sequences Arrays Vectors,  Prev: Strings and Characters,  Up: Top
+File: lispref.info,  Node: Window Point,  Next: Window Start,  Prev: Choosing Window,  Up: Windows

 
 

-Lists
-*****
+Windows and Point
+=================

 
 

-   A "list" represents a sequence of zero or more elements (which may
-be any Lisp objects).  The important difference between lists and
-vectors is that two or more lists can share part of their structure; in
-addition, you can insert or delete elements in a list without copying
-the whole list.
+Each window has its own value of point, independent of the value of
+point in other windows displaying the same buffer.  This makes it useful
+to have multiple windows showing one buffer.

 
 

-* Menu:
+   * The window point is established when a window is first created; it
+     is initialized from the buffer's point, or from the window point
+     of another window opened on the buffer if such a window exists.
+
+   * Selecting a window sets the value of point in its buffer to the
+     window's value of point.  Conversely, deselecting a window sets
+     the window's value of point from that of the buffer.  Thus, when
+     you switch between windows that display a given buffer, the point
+     value for the selected window is in effect in the buffer, while
+     the point values for the other windows are stored in those windows.
+
+   * As long as the selected window displays the current buffer, the
+     window's point and the buffer's point always move together; they
+     remain equal.
+
+   * *Note Positions::, for more details on buffer positions.
+
+   As far as the user is concerned, point is where the cursor is, and
+when the user switches to another buffer, the cursor jumps to the
+position of point in that buffer.
+
+ - Function: window-point &optional window
+     This function returns the current position of point in WINDOW.
+     For a non-selected window, this is the value point would have (in
+     that window's buffer) if that window were selected.
+
+     When WINDOW is the selected window and its buffer is also the
+     current buffer, the value returned is the same as the value of
+     point in that buffer.
+
+     Strictly speaking, it would be more correct to return the
+     "top-level" value of point, outside of any `save-excursion' forms.
+     But that value is hard to find.
+
+ - Function: set-window-point window position
+     This function positions point in WINDOW at position POSITION in
+     WINDOW's buffer.
+
+\1f
+File: lispref.info,  Node: Window Start,  Next: Vertical Scrolling,  Prev: Window Point,  Up: Windows
+
+The Window Start Position
+=========================
+
+Each window contains a marker used to keep track of a buffer position
+that specifies where in the buffer display should start.  This position
+is called the "display-start" position of the window (or just the
+"start").  The character after this position is the one that appears at
+the upper left corner of the window.  It is usually, but not
+inevitably, at the beginning of a text line.
+
+ - Function: window-start &optional window
+     This function returns the display-start position of window WINDOW.
+     If WINDOW is `nil', the selected window is used.  For example,
+
+          (window-start)
+               => 7058
+
+     When you create a window, or display a different buffer in it, the
+     display-start position is set to a display-start position recently
+     used for the same buffer, or 1 if the buffer doesn't have any.
+
+     For a realistic example, see the description of `count-lines' in
+     *Note Text Lines::.
+
+ - Function: window-end &optional window guarantee
+     This function returns the position of the end of the display in
+     window WINDOW.  If WINDOW is `nil', the selected window is used.
+
+     Simply changing the buffer text or setting `window-start' does not
+     update the value that `window-end' returns.  The value is updated
+     only when Emacs redisplays and redisplay actually finishes.
+
+     If the last redisplay of WINDOW was preempted, and did not finish,
+     Emacs does not know the position of the end of display in that
+     window.  In that case, this function returns a value that is not
+     correct.  In a future version, `window-end' will return `nil' in
+     that case.
+
+     If optional arg GUARANTEE is non-`nil', the return value is
+     guaranteed to be the same as `window-end' would return at the end
+     of the next full redisplay assuming nothing else changes in the
+     meantime.  This function is potentially much slower with this flag
+     set.
+
+
+ - Function: set-window-start window position &optional noforce
+     This function sets the display-start position of WINDOW to
+     POSITION in WINDOW's buffer.  It returns POSITION.
+
+     The display routines insist that the position of point be visible
+     when a buffer is displayed.  Normally, they change the
+     display-start position (that is, scroll the window) whenever
+     necessary to make point visible.  However, if you specify the
+     start position with this function using `nil' for NOFORCE, it
+     means you want display to start at POSITION even if that would put
+     the location of point off the screen.  If this does place point
+     off screen, the display routines move point to the left margin on
+     the middle line in the window.
+
+     For example, if point is 1 and you set the start of the window
+     to 2, then point would be "above" the top of the window.  The
+     display routines will automatically move point if it is still 1
+     when redisplay occurs.  Here is an example:
+
+          ;; Here is what `foo' looks like before executing
+          ;;   the `set-window-start' expression.
+          
+          ---------- Buffer: foo ----------
+          -!-This is the contents of buffer foo.
+          2
+          3
+          4
+          5
+          6
+          ---------- Buffer: foo ----------
+          
+          (set-window-start
+           (selected-window)
+           (1+ (window-start)))
+          => 2
+          
+          ;; Here is what `foo' looks like after executing
+          ;;   the `set-window-start' expression.
+          ---------- Buffer: foo ----------
+          his is the contents of buffer foo.
+          2
+          3
+          -!-4
+          5
+          6
+          ---------- Buffer: foo ----------
+
+     If NOFORCE is non-`nil', and POSITION would place point off screen
+     at the next redisplay, then redisplay computes a new window-start
+     position that works well with point, and thus POSITION is not used.
+
+ - Function: pos-visible-in-window-p &optional position window
+     This function returns `t' if POSITION is within the range of text
+     currently visible on the screen in WINDOW.  It returns `nil' if
+     POSITION is scrolled vertically out of view.  The argument
+     POSITION defaults to the current position of point; WINDOW, to the
+     selected window.  Here is an example:
+
+          (or (pos-visible-in-window-p
+               (point) (selected-window))
+              (recenter 0))
+
+     The `pos-visible-in-window-p' function considers only vertical
+     scrolling.  If POSITION is out of view only because WINDOW has
+     been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
+     *Note Horizontal Scrolling::.
+
+\1f
+File: lispref.info,  Node: Vertical Scrolling,  Next: Horizontal Scrolling,  Prev: Window Start,  Up: Windows
+
+Vertical Scrolling
+==================

 
 

-* 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.
+Vertical scrolling means moving the text up or down in a window.  It
+works by changing the value of the window's display-start location.  It
+may also change the value of `window-point' to keep it on the screen.
+
+   In the commands `scroll-up' and `scroll-down', the directions "up"
+and "down" refer to the motion of the text in the buffer at which you
+are looking through the window.  Imagine that the text is written on a
+long roll of paper and that the scrolling commands move the paper up
+and down.  Thus, if you are looking at text in the middle of a buffer
+and repeatedly call `scroll-down', you will eventually see the
+beginning of the buffer.
+
+   Some people have urged that the opposite convention be used: they
+imagine that the window moves over text that remains in place.  Then
+"down" commands would take you to the end of the buffer.  This view is
+more consistent with the actual relationship between windows and the
+text in the buffer, but it is less like what the user sees.  The
+position of a window on the terminal does not move, and short scrolling
+commands clearly move the text up or down on the screen.  We have chosen
+names that fit the user's point of view.
+
+   The scrolling functions (aside from `scroll-other-window') have
+unpredictable results if the current buffer is different from the buffer
+that is displayed in the selected window.  *Note Current Buffer::.
+
+ - Command: scroll-up &optional lines
+     This function scrolls the text in the selected window upward LINES
+     lines.  If LINES is negative, scrolling is actually downward.
+
+     If LINES is `nil' (or omitted), then the length of scroll is
+     `next-screen-context-lines' lines less than the usable height of
+     the window (not counting its modeline).
+
+     `scroll-up' returns `nil'.
+
+ - Command: scroll-down &optional lines
+     This function scrolls the text in the selected window downward
+     LINES lines.  If LINES is negative, scrolling is actually upward.
+
+     If LINES is omitted or `nil', then the length of the scroll is
+     `next-screen-context-lines' lines less than the usable height of
+     the window (not counting its mode line).
+
+     `scroll-down' returns `nil'.
+
+ - Command: scroll-other-window &optional lines
+     This function scrolls the text in another window upward LINES
+     lines.  Negative values of LINES, or `nil', are handled as in
+     `scroll-up'.
+
+     You can specify a buffer to scroll with the variable
+     `other-window-scroll-buffer'.  When the selected window is the
+     minibuffer, the next window is normally the one at the top left
+     corner.  You can specify a different window to scroll with the
+     variable `minibuffer-scroll-window'.  This variable has no effect
+     when any other window is selected.  *Note Minibuffer Misc::.
+
+     When the minibuffer is active, it is the next window if the
+     selected window is the one at the bottom right corner.  In this
+     case, `scroll-other-window' attempts to scroll the minibuffer.  If
+     the minibuffer contains just one line, it has nowhere to scroll
+     to, so the line reappears after the echo area momentarily displays
+     the message "Beginning of buffer".
+
+ - Variable: other-window-scroll-buffer
+     If this variable is non-`nil', it tells `scroll-other-window'
+     which buffer to scroll.
+
+ - User Option: scroll-step
+     This variable controls how scrolling is done automatically when
+     point moves off the screen.  If the value is zero, then redisplay
+     scrolls the text to center point vertically in the window.  If the
+     value is a positive integer N, then redisplay brings point back on
+     screen by scrolling N lines in either direction, if possible;
+     otherwise, it centers point.  The default value is zero.
+
+ - User Option: scroll-conservatively
+     This variable controls how many lines Emacs tries to scroll before
+     recentering.  If you set it to a small number, then when you move
+     point a short distance off the screen, XEmacs will scroll the
+     screen just far enough to bring point back on screen, provided
+     that does not exceed `scroll-conservatively' lines.  This variable
+     overrides the redisplay preemption.
+
+ - User Option: next-screen-context-lines
+     The value of this variable is the number of lines of continuity to
+     retain when scrolling by full screens.  For example, `scroll-up'
+     with an argument of `nil' scrolls so that this many lines at the
+     bottom of the window appear instead at the top.  The default value
+     is `2'.
+
+ - Command: recenter &optional location window
+     This function scrolls WINDOW (which defaults to the selected
+     window) to put the text where point is located at a specified
+     vertical position within the window.
+
+     If LOCATION is a nonnegative number, it puts the line containing
+     point LOCATION lines down from the top of the window.  If LOCATION
+     is a negative number, then it counts upward from the bottom of the
+     window, so that -1 stands for the last usable line in the window.
+     If LOCATION is a non-`nil' list, then it stands for the line in
+     the middle of the window.
+
+     If LOCATION is `nil', `recenter' puts the line containing point in
+     the middle of the window, then clears and redisplays the entire
+     selected frame.
+
+     When `recenter' is called interactively, LOCATION is the raw
+     prefix argument.  Thus, typing `C-u' as the prefix sets the
+     LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION
+     to 4, which positions the current line four lines from the top.
+
+     With an argument of zero, `recenter' positions the current line at
+     the top of the window.  This action is so handy that some people
+     make a separate key binding to do this.  For example,
+
+          (defun line-to-top-of-window ()
+            "Scroll current line to top of window.
+          Replaces three keystroke sequence C-u 0 C-l."
+            (interactive)
+            (recenter 0))
+          
+          (global-set-key [kp-multiply] 'line-to-top-of-window)

 
 \1f
 
 \1f

-File: lispref.info,  Node: Cons Cells,  Next: Lists as Boxes,  Up: Lists
+File: lispref.info,  Node: Horizontal Scrolling,  Next: Size of Window,  Prev: Vertical Scrolling,  Up: Windows

 
 

-Lists and Cons Cells
+Horizontal Scrolling

 ====================
 
 ====================
 

-   Lists in Lisp are not a primitive data type; they are built up from
-"cons cells".  A cons cell is a data object that represents an ordered
-pair.  It records two Lisp objects, one labeled as the CAR, and the
-other labeled as the CDR.  These names are traditional; see *Note Cons
-Cell Type::.  CDR is pronounced "could-er."
-
-   A list is a series of cons cells chained together, one cons cell per
-element of the list.  By convention, the CARs of the cons cells are the
-elements of the list, and the CDRs are used to chain the list: the CDR
-of each cons cell is the following cons cell.  The CDR of the last cons
-cell is `nil'.  This asymmetry between the CAR and the CDR is entirely
-a matter of convention; at the level of cons cells, the CAR and CDR
-slots have the same characteristics.
-
-   Because most cons cells are used as part of lists, the phrase "list
-structure" has come to mean any structure made out of cons cells.
-
-   The symbol `nil' is considered a list as well as a symbol; it is the
-list with no elements.  For convenience, the symbol `nil' is considered
-to have `nil' as its CDR (and also as its CAR).
-
-   The CDR of any nonempty list L is a list containing all the elements
-of L except the first.
-
-\1f
-File: lispref.info,  Node: Lists as Boxes,  Next: List-related Predicates,  Prev: Cons Cells,  Up: Lists
-
-Lists as Linked Pairs of Boxes
-==============================
-
-   A cons cell can be illustrated as a pair of boxes.  The first box
-represents the CAR and the second box represents the CDR.  Here is an
-illustration of the two-element list, `(tulip lily)', made from two
-cons cells:
-
-      ---------------         ---------------
-     | car   | cdr   |       | car   | cdr   |
-     | tulip |   o---------->| lily  |  nil  |
-     |       |       |       |       |       |
-      ---------------         ---------------
-
-   Each pair of boxes represents a cons cell.  Each box "refers to",
-"points to" or "contains" a Lisp object.  (These terms are synonymous.)
-The first box, which is the CAR of the first cons cell, contains the
-symbol `tulip'.  The arrow from the CDR of the first cons cell to the
-second cons cell indicates that the CDR of the first cons cell points
-to the second cons cell.
-
-   The same list can be illustrated in a different sort of box notation
-like this:
-
-         ___ ___      ___ ___
-        |___|___|--> |___|___|--> nil
-          |            |
-          |            |
-           --> tulip    --> lily
-
-   Here is a more complex illustration, showing the three-element list,
-`((pine needles) oak maple)', the first element of which is a
-two-element list:
-
-         ___ ___      ___ ___      ___ ___
-        |___|___|--> |___|___|--> |___|___|--> nil
-          |            |            |
-          |            |            |
-          |             --> oak      --> maple
-          |
-          |     ___ ___      ___ ___
-           --> |___|___|--> |___|___|--> nil
-                 |            |
-                 |            |
-                  --> pine     --> needles
-
-   The same list represented in the first box notation looks like this:
-
-      --------------       --------------       --------------
-     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
-     |   o   |   o------->| oak   |   o------->| maple |  nil |
-     |   |   |      |     |       |      |     |       |      |
-      -- | ---------       --------------       --------------
-         |
-         |
-         |        --------------       ----------------
-         |       | car   | cdr  |     | car     | cdr  |
-          ------>| pine  |   o------->| needles |  nil |
-                 |       |      |     |         |      |
-                  --------------       ----------------
-
-   *Note Cons Cell Type::, for the read and print syntax of cons cells
-and lists, and for more "box and arrow" illustrations of lists.
-
-\1f
-File: lispref.info,  Node: List-related Predicates,  Next: List Elements,  Prev: Lists as Boxes,  Up: Lists
-
-Predicates on Lists
-===================
+Because we read English first from top to bottom and second from left
+to right, horizontal scrolling is not like vertical scrolling.  Vertical
+scrolling involves selection of a contiguous portion of text to display.
+Horizontal scrolling causes part of each line to go off screen.  The
+amount of horizontal scrolling is therefore specified as a number of
+columns rather than as a position in the buffer.  It has nothing to do
+with the display-start position returned by `window-start'.
+
+   Usually, no horizontal scrolling is in effect; then the leftmost
+column is at the left edge of the window.  In this state, scrolling to
+the right is meaningless, since there is no data to the left of the
+screen to be revealed by it; so this is not allowed.  Scrolling to the
+left is allowed; it scrolls the first columns of text off the edge of
+the window and can reveal additional columns on the right that were
+truncated before.  Once a window has a nonzero amount of leftward
+horizontal scrolling, you can scroll it back to the right, but only so
+far as to reduce the net horizontal scroll to zero.  There is no limit
+to how far left you can scroll, but eventually all the text will
+disappear off the left edge.
+
+ - Command: scroll-left &optional count
+     This function scrolls the selected window COUNT columns to the
+     left (or to the right if COUNT is negative).  The return value is
+     the total amount of leftward horizontal scrolling in effect after
+     the change--just like the value returned by `window-hscroll'
+     (below).
+
+ - Command: scroll-right &optional count
+     This function scrolls the selected window COUNT columns to the
+     right (or to the left if COUNT is negative).  The return value is
+     the total amount of leftward horizontal scrolling in effect after
+     the change--just like the value returned by `window-hscroll'
+     (below).
+
+     Once you scroll a window as far right as it can go, back to its
+     normal position where the total leftward scrolling is zero,
+     attempts to scroll any farther right have no effect.
+
+ - Function: window-hscroll &optional window
+     This function returns the total leftward horizontal scrolling of
+     WINDOW--the number of columns by which the text in WINDOW is
+     scrolled left past the left margin.
+
+     The value is never negative.  It is zero when no horizontal
+     scrolling has been done in WINDOW (which is usually the case).
+
+     If WINDOW is `nil', the selected window is used.
+
+          (window-hscroll)
+               => 0
+          (scroll-left 5)
+               => 5
+          (window-hscroll)
+               => 5

 
 

-   The following predicates test whether a Lisp object is an atom, is a
-cons cell or is a list, or whether it is the distinguished object
-`nil'.  (Many of these predicates can be defined in terms of the
-others, but they are used so often that it is worth having all of them.)
+ - Function: set-window-hscroll window columns
+     This function sets the number of columns from the left margin that
+     WINDOW is scrolled to the value of COLUMNS.  The argument COLUMNS
+     should be zero or positive; if not, it is taken as zero.

 
 

- - Function: consp object
-     This function returns `t' if OBJECT is a cons cell, `nil'
-     otherwise.  `nil' is not a cons cell, although it _is_ a list.
+     The value returned is COLUMNS.

 
 

- - Function: atom object
-     This function returns `t' if OBJECT is an atom, `nil' otherwise.
-     All objects except cons cells are atoms.  The symbol `nil' is an
-     atom and is also a list; it is the only Lisp object that is both.
+          (set-window-hscroll (selected-window) 10)
+               => 10

 
 

-          (atom OBJECT) == (not (consp OBJECT))
+   Here is how you can determine whether a given position POSITION is
+off the screen due to horizontal scrolling:

 
 

- - Function: listp object
-     This function returns `t' if OBJECT is a cons cell or `nil'.
-     Otherwise, it returns `nil'.
+     (defun hscroll-on-screen (window position)
+       (save-excursion
+         (goto-char position)
+         (and
+          (>= (- (current-column) (window-hscroll window)) 0)
+          (< (- (current-column) (window-hscroll window))
+             (window-width window)))))

 
 

-          (listp '(1))
-               => t
-          (listp '())
-               => t
+\1f
+File: lispref.info,  Node: Size of Window,  Next: Position of Window,  Prev: Horizontal Scrolling,  Up: Windows

 
 

- - Function: nlistp object
-     This function is the opposite of `listp': it returns `t' if OBJECT
-     is not a list.  Otherwise, it returns `nil'.
+The Size of a Window
+====================

 
 

-          (listp OBJECT) == (not (nlistp OBJECT))
+An Emacs window is rectangular, and its size information consists of
+the height (in lines or pixels) and the width (in character positions
+or pixels).  The modeline is included in the height.  The pixel width
+and height values include scrollbars and margins, while the
+line/character-position values do not.
+
+   Note that the height in lines, and the width in characters, are
+determined by dividing the corresponding pixel value by the height or
+width of the default font in that window (if this is a variable-width
+font, the average width is used).  The resulting values may or may not
+represent the actual number of lines in the window, or the actual number
+of character positions in any particular line, esp. if there are pixmaps
+or various different fonts in the window.
+
+   The following functions return size information about a window:
+
+ - Function: window-height &optional window
+     This function returns the number of lines in WINDOW, including its
+     modeline but not including the horizontal scrollbar, if any (this
+     is different from `window-pixel-height').  If WINDOW is `nil', the
+     function uses the selected window.
+
+          (window-height)
+               => 40
+          (split-window-vertically)
+               => #<window on "windows.texi" 0x679b>
+          (window-height)
+               => 20
+
+ - Function: window-width &optional window
+     This function returns the number of columns in WINDOW, not
+     including any left margin, right margin, or vertical scrollbar
+     (this is different from `window-pixel-width').  If WINDOW is
+     `nil', the function uses the selected window.
+
+          (window-width)
+               => 80
+          (window-height)
+               => 40
+          (split-window-horizontally)
+               => #<window on "windows.texi" 0x7538>
+          (window-width)
+               => 39
+
+   Note that after splitting the window into two side-by-side windows,
+the width of each window is less the half the width of the original
+window because a vertical scrollbar appeared between the windows,
+occupying two columns worth of space.  Also, the height shrunk by one
+because horizontal scrollbars appeared that weren't there before.
+(Horizontal scrollbars appear only when lines are truncated, not when
+they wrap.  This is usually the case for horizontally split windows but
+not for full-frame windows.  You can change this using the variables
+`truncate-lines' and `truncate-partial-width-windows'.)
+
+ - Function: window-pixel-height &optional window
+     This function returns the height of WINDOW in pixels, including
+     its modeline and horizontal scrollbar, if any.  If WINDOW is
+     `nil', the function uses the selected window.
+
+          (window-pixel-height)
+               => 600
+          (split-window-vertically)
+               => #<window on "windows.texi" 0x68a6>
+          (window-pixel-height)
+               => 300
+
+ - Function: window-pixel-width &optional window
+     This function returns the width of WINDOW in pixels, including any
+     left margin, right margin, or vertical scrollbar that may be
+     displayed alongside it.  If WINDOW is `nil', the function uses the
+     selected window.
+
+          (window-pixel-width)
+               => 735
+          (window-pixel-height)
+               => 600
+          (split-window-horizontally)
+               => #<window on "windows.texi" 0x7538>
+          (window-pixel-width)
+               => 367
+          (window-pixel-height)
+               => 600
+
+ - Function: window-text-area-pixel-height &optional window
+     This function returns the height in pixels of the text displaying
+     portion of WINDOW, which defaults to the selected window.  Unlike
+     `window-pixel-height', the space occupied by the modeline and
+     horizontal scrollbar, if any, is not counted.
+
+ - Function: window-text-area-pixel-width &optional window
+     This function returns the width in pixels of the text displaying
+     portion of WINDOW, which defaults to the selected window.  Unlike
+     `window-pixel-width', the space occupied by the vertical scrollbar
+     and divider, if any, is not counted.
+
+ - Function: window-displayed-text-pixel-height &optional window
+          noclipped
+     This function returns the height in pixels of the text displayed in
+     WINDOW, which defaults to the selected window.  Unlike
+     `window-text-area-pixel-height', any blank space below the end of
+     the buffer is not included.  If optional argument NOCLIPPED is
+     non-`nil', any space occupied by clipped lines will not be
+     included.

 
 

- - Function: null object
-     This function returns `t' if OBJECT is `nil', and returns `nil'
-     otherwise.  This function is identical to `not', but as a matter
-     of clarity we use `null' when OBJECT is considered a list and
-     `not' when it is considered a truth value (see `not' in *Note
-     Combining Conditions::).
+\1f
+File: lispref.info,  Node: Position of Window,  Next: Resizing Windows,  Prev: Size of Window,  Up: Windows
+
+The Position of a Window
+========================
+
+XEmacs provides functions to determine the absolute location of windows
+within a frame, and the relative location of a window in comparison to
+other windows in the same frame.
+
+ - Function: window-pixel-edges &optional window
+     This function returns a list of the pixel edge coordinates of
+     WINDOW.  If WINDOW is `nil', the selected window is used.
+
+     The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
+     relative to 0, 0 at the top left corner of WINDOW's frame.  The
+     element RIGHT of the value is one more than the rightmost pixel
+     used by WINDOW (including any left margin, right margin, or
+     vertical scrollbar displayed alongside it), and BOTTOM is one more
+     than the bottommost pixel used by WINDOW (including any modeline
+     or horizontal scrollbar displayed above or below it).  The frame
+     area does not include any frame menubars, toolbars, or gutters
+     that may be displayed; thus, for example, if there is only one
+     window on the frame, the values for LEFT and TOP will always be 0.
+
+     If WINDOW is at the upper left corner of its frame, RIGHT and
+     BOTTOM are the same as the values returned by
+     `(window-pixel-width)' and `(window-pixel-height)' respectively,
+     and LEFT and TOP are zero.
+
+   There is no longer a function `window-edges' because it does not
+make sense in a world with variable-width and variable-height lines, as
+are allowed in XEmacs.
+
+ - Function: window-highest-p window
+     This function returns non-`nil' if WINDOW is along the top of its
+     frame.
+
+ - Function: window-lowest-p window
+     This function returns non-`nil' if WINDOW is along the bottom of
+     its frame.
+
+ - Function: window-text-area-pixel-edges &optional window
+     This function allows one to determine the location of the
+     text-displaying portion of WINDOW, which defaults to the selected
+     window, with respect to the top left corner of the window.  It
+     returns a list of integer pixel positions `(left top right
+     bottom)', all relative to `(0,0)' at the top left corner of the
+     window.

 
 

-          (null '(1))
-               => nil
-          (null '())
+\1f
+File: lispref.info,  Node: Resizing Windows,  Next: Window Configurations,  Prev: Position of Window,  Up: Windows
+
+Changing the Size of a Window
+=============================
+
+The window size functions fall into two classes: high-level commands
+that change the size of windows and low-level functions that access
+window size.  XEmacs does not permit overlapping windows or gaps between
+windows, so resizing one window affects other windows.
+
+ - Command: enlarge-window count &optional horizontal window
+     This function makes the selected window COUNT lines taller,
+     stealing lines from neighboring windows.  It takes the lines from
+     one window at a time until that window is used up, then takes from
+     another.  If a window from which lines are stolen shrinks below
+     `window-min-height' lines, that window disappears.
+
+     If HORIZONTAL is non-`nil', this function makes WINDOW wider by
+     COUNT columns, stealing columns instead of lines.  If a window
+     from which columns are stolen shrinks below `window-min-width'
+     columns, that window disappears.
+
+     If the requested size would exceed that of the window's frame,
+     then the function makes the window occupy the entire height (or
+     width) of the frame.
+
+     If COUNT is negative, this function shrinks the window by -COUNT
+     lines or columns.  If that makes the window smaller than the
+     minimum size (`window-min-height' and `window-min-width'),
+     `enlarge-window' deletes the window.
+
+     If WINDOW is non-`nil', it specifies a window to change instead of
+     the selected window.
+
+     `enlarge-window' returns `nil'.
+
+ - Command: enlarge-window-horizontally columns
+     This function makes the selected window COLUMNS wider.  It could
+     be defined as follows:
+
+          (defun enlarge-window-horizontally (columns)
+            (enlarge-window columns t))
+
+ - Command: enlarge-window-pixels count &optional side window
+     This function makes the selected window COUNT pixels larger.  When
+     called from Lisp, optional second argument SIDE non-`nil' means to
+     grow sideways COUNT pixels, and optional third argument WINDOW
+     specifies the window to change instead of the selected window.
+
+ - Command: shrink-window count &optional horizontal window
+     This function is like `enlarge-window' but negates the argument
+     COUNT, making the selected window smaller by giving lines (or
+     columns) to the other windows.  If the window shrinks below
+     `window-min-height' or `window-min-width', then it disappears.
+
+     If COUNT is negative, the window is enlarged by -COUNT lines or
+     columns.
+
+     If WINDOW is non-`nil', it specifies a window to change instead of
+     the selected window.
+
+ - Command: shrink-window-horizontally columns
+     This function makes the selected window COLUMNS narrower.  It
+     could be defined as follows:
+
+          (defun shrink-window-horizontally (columns)
+            (shrink-window columns t))
+
+ - Command: shrink-window-pixels count &optional side window
+     This function makes the selected window COUNT pixels smaller.
+     When called from Lisp, optional second argument SIDE non-`nil'
+     means to shrink sideways COUNT pixels, and optional third argument
+     WINDOW specifies the window to change instead of the selected
+     window.
+
+   The following two variables constrain the window-size-changing
+functions to a minimum height and width.
+
+ - User Option: window-min-height
+     The value of this variable determines how short a window may become
+     before it is automatically deleted.  Making a window smaller than
+     `window-min-height' automatically deletes it, and no window may be
+     created shorter than this.  The absolute minimum height is two
+     (allowing one line for the mode line, and one line for the buffer
+     display).  Actions that change window sizes reset this variable to
+     two if it is less than two.  The default value is 4.
+
+ - User Option: window-min-width
+     The value of this variable determines how narrow a window may
+     become before it automatically deleted.  Making a window smaller
+     than `window-min-width' automatically deletes it, and no window
+     may be created narrower than this.  The absolute minimum width is
+     one; any value below that is ignored.  The default value is 10.
+
+ - Variable: window-size-change-functions
+     This variable holds a list of functions to be called if the size
+     of any window changes for any reason.  The functions are called
+     just once per redisplay, and just once for each frame on which
+     size changes have occurred.
+
+     Each function receives the frame as its sole argument.  There is no
+     direct way to find out which windows changed size, or precisely
+     how; however, if your size-change function keeps track, after each
+     change, of the windows that interest you, you can figure out what
+     has changed by comparing the old size data with the new.
+
+     Creating or deleting windows counts as a size change, and therefore
+     causes these functions to be called.  Changing the frame size also
+     counts, because it changes the sizes of the existing windows.
+
+     It is not a good idea to use `save-window-excursion' in these
+     functions, because that always counts as a size change, and it
+     would cause these functions to be called over and over.  In most
+     cases, `save-selected-window' is what you need here.
+
+\1f
+File: lispref.info,  Node: Window Configurations,  Prev: Resizing Windows,  Up: Windows
+
+Window Configurations
+=====================
+
+A "window configuration" records the entire layout of a frame--all
+windows, their sizes, which buffers they contain, what part of each
+buffer is displayed, and the values of point and the mark.  You can
+bring back an entire previous layout by restoring a window
+configuration previously saved.
+
+   If you want to record all frames instead of just one, use a frame
+configuration instead of a window configuration.  *Note Frame
+Configurations::.
+
+ - Function: current-window-configuration &optional frame
+     This function returns a new object representing the current window
+     configuration of FRAME, namely the number of windows, their sizes
+     and current buffers, which window is the selected window, and for
+     each window the displayed buffer, the display-start position, and
+     the positions of point and the mark.  An exception is made for
+     point in the current buffer, whose value is not saved.
+
+     FRAME defaults to the selected frame.
+
+ - Function: set-window-configuration configuration
+     This function restores the configuration of XEmacs's windows and
+     buffers to the state specified by CONFIGURATION.  The argument
+     CONFIGURATION must be a value that was previously returned by
+     `current-window-configuration'.
+
+     This function always counts as a window size change and triggers
+     execution of the `window-size-change-functions'.  (It doesn't know
+     how to tell whether the new configuration actually differs from
+     the old one.)
+
+     Here is a way of using this function to get the same effect as
+     `save-window-excursion':
+
+          (let ((config (current-window-configuration)))
+            (unwind-protect
+                (progn (split-window-vertically nil)
+                       ...)
+              (set-window-configuration config)))
+
+ - Special Form: save-window-excursion forms...
+     This special form records the window configuration, executes FORMS
+     in sequence, then restores the earlier window configuration.  The
+     window configuration includes the value of point and the portion
+     of the buffer that is visible.  It also includes the choice of
+     selected window.  However, it does not include the value of point
+     in the current buffer; use `save-excursion' if you wish to
+     preserve that.
+
+     Don't use this construct when `save-selected-window' is all you
+     need.
+
+     Exit from `save-window-excursion' always triggers execution of the
+     `window-size-change-functions'.  (It doesn't know how to tell
+     whether the restored configuration actually differs from the one in
+     effect at the end of the FORMS.)
+
+     The return value is the value of the final form in FORMS.  For
+     example:
+
+          (split-window)
+               => #<window 25 on control.texi>
+          (setq w (selected-window))
+               => #<window 19 on control.texi>
+          (save-window-excursion
+            (delete-other-windows w)
+            (switch-to-buffer "foo")
+            'do-something)
+               => do-something
+               ;; The frame is now split again.
+
+ - Function: window-configuration-p object
+     This function returns `t' if OBJECT is a window configuration.
+
+   Primitives to look inside of window configurations would make sense,
+but none are implemented.  It is not clear they are useful enough to be
+worth implementing.
+
+\1f
+File: lispref.info,  Node: Frames,  Next: Consoles and Devices,  Prev: Windows,  Up: Top
+
+Frames
+******
+
+A FRAME is a rectangle on the screen that contains one or more XEmacs
+windows (*note Windows::).  A frame initially contains a single main
+window (plus perhaps an echo area), which you can subdivide vertically
+or horizontally into smaller windows.  Each window is associated with a
+modeline (*note Modeline Format::), and optionally two scrollbars
+(*note Scrollbars::).  By default the vertical scrollbar is on, the
+horizontal scrollbar is off.
+
+   The frame may also contain menubars (*note Menubar::), toolbars
+(*note Toolbar Intro::), and gutters (*note Gutter Intro::).  By default
+there is one of each at the top of the frame, with menubar topmost,
+toolbar next, and gutter lowest, immediately above the windows.
+(Warning: the gutter is a new, experimental, and unstable feature of
+XEmacs version 21.2.)
+
+   When XEmacs runs on a text-only terminal, it starts with one "TTY
+frame".  If you create additional ones, XEmacs displays one and only
+one at any given time--on the terminal screen, of course.
+
+   When XEmacs communicates directly with an X server, it does not have
+a TTY frame; instead, it starts with a single "X window frame".  It can
+display multiple X window frames at the same time, each in its own X
+window.
+
+ - Function: framep object
+     This predicate returns `t' if OBJECT is a frame, and `nil'
+     otherwise.
+
+* Menu:
+
+* 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 Configurations::       Saving the state of all frames.
+* Frame Hooks::                 Hooks for customizing frame behavior.
+
+   *Note Display::, for related information.
+
+\1f
+File: lispref.info,  Node: Creating Frames,  Next: Frame Properties,  Up: Frames
+
+Creating Frames
+===============
+
+To create a new frame, call the function `make-frame'.
+
+ - Command: make-frame &optional props device
+     This function creates a new frame on DEVICE, if DEVICE permits
+     creation of frames.  (An X server does; an ordinary terminal does
+     not (yet).)  DEVICE defaults to the selected device if omitted.
+     *Note Consoles and Devices::.
+
+     The argument PROPS is a property list (a list of alternating
+     keyword-value specifications) of properties for the new frame. (An
+     alist is accepted for backward compatibility but should not be
+     passed in.) Any properties not mentioned in PROPS default
+     according to the value of the variable `default-frame-plist'.  For
+     X devices, properties not specified in `default-frame-plist'
+     default in turn from `default-x-frame-plist' and, if not specified
+     there, from the X resources.  For TTY devices,
+     `default-tty-frame-plist' is consulted as well as
+     `default-frame-plist'.
+
+     The set of possible properties depends in principle on what kind of
+     window system XEmacs uses to display its frames.  *Note X Frame
+     Properties::, for documentation of individual properties you can
+     specify when creating an X window frame.
+
+\1f
+File: lispref.info,  Node: Frame Properties,  Next: Frame Titles,  Prev: Creating Frames,  Up: Frames
+
+Frame Properties
+================
+
+A frame has many properties that control its appearance and behavior.
+Just what properties a frame has depends on which display mechanism it
+uses.
+
+   Frame properties exist for the sake of window systems.  A terminal
+frame has few properties, mostly for compatibility's sake; only the
+height, width and `buffer-predicate' properties really do something.
+
+* Menu:
+
+* Property Access::    How to change a frame's properties.
+* Initial Properties:: Specifying frame properties when you make a frame.
+* X Frame Properties:: List of frame properties.
+* Size and Position::  Changing the size and position of a frame.
+* Frame Name::         The name of a frame (as opposed to its title).
+
+\1f
+File: lispref.info,  Node: Property Access,  Next: Initial Properties,  Up: Frame Properties
+
+Access to Frame Properties
+--------------------------
+
+These functions let you read and change the properties of a frame.
+
+ - Function: frame-properties &optional frame
+     This function returns a plist listing all the properties of FRAME
+     and their values.
+
+ - Function: frame-property frame property &optional default
+     This function returns FRAME's value for the property PROPERTY, or
+     DEFAULT if there is no such property.
+
+ - Function: set-frame-properties frame plist
+     This function alters the properties of frame FRAME based on the
+     elements of property list PLIST.  If you don't mention a property
+     in PLIST, its value doesn't change.
+
+ - Function: set-frame-property frame property value
+     This function sets the property PROPERTY of frame FRAME to the
+     value VALUE.
+
+\1f
+File: lispref.info,  Node: Initial Properties,  Next: X Frame Properties,  Prev: Property Access,  Up: Frame Properties
+
+Initial Frame Properties
+------------------------
+
+You can specify the properties for the initial startup frame by setting
+`initial-frame-plist' in your `.emacs' file.
+
+ - Variable: initial-frame-plist
+     This variable's value is a plist of alternating property-value
+     pairs used when creating the initial X window frame.
+
+     XEmacs creates the initial frame before it reads your `~/.emacs'
+     file.  After reading that file, XEmacs checks
+     `initial-frame-plist', and applies the property settings in the
+     altered value to the already created initial frame.
+
+     If these settings affect the frame geometry and appearance, you'll
+     see the frame appear with the wrong ones and then change to the
+     specified ones.  If that bothers you, you can specify the same
+     geometry and appearance with X resources; those do take affect
+     before the frame is created.  *Note X Resources: (xemacs)Resources
+     X.
+
+     X resource settings typically apply to all frames.  If you want to
+     specify some X resources solely for the sake of the initial frame,
+     and you don't want them to apply to subsequent frames, here's how
+     to achieve this: specify properties in `default-frame-plist' to
+     override the X resources for subsequent frames; then, to prevent
+     these from affecting the initial frame, specify the same
+     properties in `initial-frame-plist' with values that match the X
+     resources.
+
+   If these properties specify a separate minibuffer-only frame via a
+`minibuffer' property of `nil', and you have not yet created one,
+XEmacs creates one for you.
+
+ - Variable: minibuffer-frame-plist
+     This variable's value is a plist of properties used when creating
+     an initial minibuffer-only frame--if such a frame is needed,
+     according to the properties for the main initial frame.
+
+ - Variable: default-frame-plist
+     This is a plist specifying default values of frame properties for
+     subsequent XEmacs frames (not the initial ones).
+
+   See also `special-display-frame-plist', in *Note Choosing Window::.
+
+   If you use options that specify window appearance when you invoke
+XEmacs, they take effect by adding elements to `default-frame-plist'.
+One exception is `-geometry', which adds the specified position to
+`initial-frame-plist' instead.  *Note Command Arguments:
+(xemacs)Command Arguments.
+
+\1f
+File: lispref.info,  Node: X Frame Properties,  Next: Size and Position,  Prev: Initial Properties,  Up: Frame Properties
+
+X Window Frame Properties
+-------------------------
+
+Just what properties a frame has depends on what display mechanism it
+uses.  Here is a table of the properties of an X window frame; of these,
+`name', `height', `width', and `buffer-predicate' provide meaningful
+information in non-X frames.
+
+`name'
+     The name of the frame.  Most window managers display the frame's
+     name in the frame's border, at the top of the frame.  If you don't
+     specify a name, and you have more than one frame, XEmacs sets the
+     frame name based on the buffer displayed in the frame's selected
+     window.
+
+     If you specify the frame name explicitly when you create the
+     frame, the name is also used (instead of the name of the XEmacs
+     executable) when looking up X resources for the frame.
+
+`display'
+     The display on which to open this frame.  It should be a string of
+     the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
+     variable.
+
+`left'
+     The screen position of the left edge, in pixels, with respect to
+     the left edge of the screen.  The value may be a positive number
+     POS, or a list of the form `(+ POS)' which permits specifying a
+     negative POS value.
+
+     A negative number -POS, or a list of the form `(- POS)', actually
+     specifies the position of the right edge of the window with
+     respect to the right edge of the screen.  A positive value of POS
+     counts toward the left.  If the property is a negative integer
+     -POS then POS is positive!
+
+`top'
+     The screen position of the top edge, in pixels, with respect to the
+     top edge of the screen.  The value may be a positive number POS,
+     or a list of the form `(+ POS)' which permits specifying a
+     negative POS value.
+
+     A negative number -POS, or a list of the form `(- POS)', actually
+     specifies the position of the bottom edge of the window with
+     respect to the bottom edge of the screen.  A positive value of POS
+     counts toward the top.  If the property is a negative integer -POS
+     then POS is positive!
+
+`icon-left'
+     The screen position of the left edge _of the frame's icon_, in
+     pixels, counting from the left edge of the screen.  This takes
+     effect if and when the frame is iconified.
+
+`icon-top'
+     The screen position of the top edge _of the frame's icon_, in
+     pixels, counting from the top edge of the screen.  This takes
+     effect if and when the frame is iconified.
+
+`user-position'
+     Non-`nil' if the screen position of the frame was explicitly
+     requested by the user (for example, with the `-geometry' option).
+     Nothing automatically makes this property non-`nil'; it is up to
+     Lisp programs that call `make-frame' to specify this property as
+     well as specifying the `left' and `top' properties.
+
+`height'
+     The height of the frame contents, in characters.  (To get the
+     height in pixels, call `frame-pixel-height'; see *Note Size and
+     Position::.)
+
+`width'
+     The width of the frame contents, in characters.  (To get the
+     height in pixels, call `frame-pixel-width'; see *Note Size and
+     Position::.)
+
+`window-id'
+     The number of the X window for the frame.
+
+`minibuffer'
+     Whether this frame has its own minibuffer.  The value `t' means
+     yes, `nil' means no, `only' means this frame is just a minibuffer.
+     If the value is a minibuffer window (in some other frame), the
+     new frame uses that minibuffer. (Minibuffer-only and
+     minibuffer-less frames are not yet implemented in XEmacs.)
+
+`buffer-predicate'
+     The buffer-predicate function for this frame.  The function
+     `other-buffer' uses this predicate (from the selected frame) to
+     decide which buffers it should consider, if the predicate is not
+     `nil'.  It calls the predicate with one arg, a buffer, once for
+     each buffer; if the predicate returns a non-`nil' value, it
+     considers that buffer.
+
+`scroll-bar-width'
+     The width of the vertical scroll bar, in pixels.
+
+`cursor-color'
+     The color for the cursor that shows point.
+
+`border-color'
+     The color for the border of the frame.
+
+`border-width'
+     The width in pixels of the window border.
+
+`internal-border-width'
+     The distance in pixels between text and border.
+
+`unsplittable'
+     If non-`nil', this frame's window is never split automatically.
+
+`inter-line-space'
+     The space in pixels between adjacent lines of text. (Not currently
+     implemented.)
+
+`modeline'
+     Whether the frame has a modeline.
+
+\1f
+File: lispref.info,  Node: Size and Position,  Next: Frame Name,  Prev: X Frame Properties,  Up: Frame Properties
+
+Frame Size And Position
+-----------------------
+
+You can read or change the size and position of a frame using the frame
+properties `left', `top', `height', and `width'.  Whatever geometry
+properties you don't specify are chosen by the window manager in its
+usual fashion.
+
+   Here are some special features for working with sizes and positions:
+
+ - Function: set-frame-position frame left top
+     This function sets the position of the top left corner of FRAME to
+     LEFT and TOP.  These arguments are measured in pixels, and count
+     from the top left corner of the screen.  Negative property values
+     count up or rightward from the top left corner of the screen.
+
+ - Function: frame-height &optional frame
+ - Function: frame-width &optional frame
+     These functions return the height and width of FRAME, measured in
+     lines and columns.  If you don't supply FRAME, they use the
+     selected frame.
+
+ - Function: frame-pixel-height &optional frame
+ - Function: frame-pixel-width &optional frame
+     These functions return the height and width of FRAME, measured in
+     pixels.  If you don't supply FRAME, they use the selected frame.
+
+ - Function: set-frame-size frame cols rows &optional pretend
+     This function sets the size of FRAME, measured in characters; COLS
+     and ROWS specify the new width and height.  (If PRETEND is
+     non-`nil', it means that redisplay should act as if the frame's
+     size is COLS by ROWS, but the actual size of the frame should not
+     be changed.  You should not normally use this option.)
+
+   You can also use the functions `set-frame-height' and
+`set-frame-width' to set the height and width individually.  The frame
+is the first argument and the size (in rows or columns) is the second.
+(There is an optional third argument, PRETEND, which has the same
+purpose as the corresponding argument in `set-frame-size'.)
+
+\1f
+File: lispref.info,  Node: Frame Name,  Prev: Size and Position,  Up: Frame Properties
+
+The Name of a Frame (As Opposed to Its Title)
+---------------------------------------------
+
+Under X, every frame has a name, which is not the same as the title of
+the frame.  A frame's name is used to look up its resources and does
+not normally change over the lifetime of a frame.  It is perfectly
+allowable, and quite common, for multiple frames to have the same name.
+
+ - Function: frame-name &optional frame
+     This function returns the name of FRAME, which defaults to the
+     selected frame if not specified.  The name of a frame can also be
+     obtained from the frame's properties.  *Note Frame Properties::.
+
+ - Variable: default-frame-name
+     This variable holds the default name to assign to newly-created
+     frames.  This can be overridden by arguments to `make-frame'.  This
+     must be a string.
+
+\1f
+File: lispref.info,  Node: Frame Titles,  Next: Deleting Frames,  Prev: Frame Properties,  Up: Frames
+
+Frame Titles
+============
+
+Every frame has a title; most window managers display the frame title at
+the top of the frame.  You can specify an explicit title with the
+`name' frame property.  But normally you don't specify this explicitly,
+and XEmacs computes the title automatically.
+
+   XEmacs computes the frame title based on a template stored in the
+variable `frame-title-format'.
+
+ - Variable: frame-title-format
+     This variable specifies how to compute a title for a frame when
+     you have not explicitly specified one.
+
+     The variable's value is actually a modeline construct, just like
+     `modeline-format'.  *Note Modeline Data::.
+
+ - Variable: frame-icon-title-format
+     This variable specifies how to compute the title for an iconified
+     frame, when you have not explicitly specified the frame title.
+     This title appears in the icon itself.
+
+ - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
+     This function sets the icon of the given frame to the given image
+     instance, which should be an image instance object (as returned by
+     `make-image-instance'), a glyph object (as returned by
+     `make-glyph'), or `nil'.  If a glyph object is given, the glyph
+     will be instantiated on the frame to produce an image instance
+     object.
+
+     If the given image instance has a mask, that will be used as the
+     icon mask; however, not all window managers support this.
+
+     The window manager is also not required to support color pixmaps,
+     only bitmaps (one plane deep).
+
+     If the image instance does not have a mask, then the optional
+     third argument may be the image instance to use as the mask (it
+     must be one plane deep).  *Note Glyphs::.
+
+\1f
+File: lispref.info,  Node: Deleting Frames,  Next: Finding All Frames,  Prev: Frame Titles,  Up: Frames
+
+Deleting Frames
+===============
+
+Frames remain potentially visible until you explicitly "delete" them.
+A deleted frame cannot appear on the screen, but continues to exist as
+a Lisp object until there are no references to it.
+
+ - Command: delete-frame &optional frame force
+     This function deletes the frame FRAME.  By default, FRAME is the
+     selected frame.
+
+     A frame may not be deleted if its minibuffer is used by other
+     frames.  Normally, you cannot delete the last non-minibuffer-only
+     frame (you must use `save-buffers-kill-emacs' or `kill-emacs').
+     However, if optional second argument FORCE is non-`nil', you can
+     delete the last frame. (This will automatically call
+     `save-buffers-kill-emacs'.)
+
+ - Function: frame-live-p frame
+     The function `frame-live-p' returns non-`nil' if the frame FRAME
+     has not been deleted.
+
+\1f
+File: lispref.info,  Node: Finding All Frames,  Next: Frames and Windows,  Prev: Deleting Frames,  Up: Frames
+
+Finding All Frames
+==================
+
+ - Function: frame-list
+     The function `frame-list' returns a list of all the frames that
+     have not been deleted.  It is analogous to `buffer-list' for
+     buffers.  The list that you get is newly created, so modifying the
+     list doesn't have any effect on the internals of XEmacs.
+
+ - Function: device-frame-list &optional device
+     This function returns a list of all frames on DEVICE.  If DEVICE
+     is `nil', the selected device will be used.
+
+ - Function: visible-frame-list &optional device
+     This function returns a list of just the currently visible frames.
+     If DEVICE is specified only frames on that device will be returned.
+     *Note Visibility of Frames::.  (TTY frames always count as
+     "visible", even though only the selected one is actually
+     displayed.)
+
+ - Function: next-frame &optional frame which-frames which-devices
+     The function `next-frame' lets you cycle conveniently through all
+     the frames from an arbitrary starting point.  It returns the "next"
+     frame after FRAME in the cycle.  If FRAME defaults to the selected
+     frame.
+
+     The second argument, WHICH-FRAMES, says which frames to consider:
+
+    `visible'
+          Consider only frames that are visible.
+
+    `iconic'
+          Consider only frames that are iconic.
+
+    `invisible'
+          Consider only frames that are invisible (this is different
+          from iconic).
+
+    `visible-iconic'
+          Consider frames that are visible or iconic.
+
+    `invisible-iconic'
+          Consider frames that are invisible or iconic.
+
+    `nomini'
+          Consider all frames except minibuffer-only ones.
+
+    `visible-nomini'
+          Like `visible' but omits minibuffer-only frames.
+
+    `iconic-nomini'
+          Like `iconic' but omits minibuffer-only frames.
+
+    `invisible-nomini'
+          Like `invisible' but omits minibuffer-only frames.
+
+    `visible-iconic-nomini'
+          Like `visible-iconic' but omits minibuffer-only frames.
+
+    `invisible-iconic-nomini'
+          Like `invisible-iconic' but omits minibuffer-only frames.
+
+    `nil'
+          Identical to `nomini'.
+
+    WINDOW
+          Consider only the window WINDOW's frame and any frame now
+          using WINDOW as the minibuffer.
+
+    any other value
+          Consider all frames.
+
+     The optional argument WHICH-DEVICES further clarifies on which
+     devices to search for frames as specified by WHICH-FRAMES.
+
+    `nil'
+          Consider all devices on the selected console.
+
+    DEVICE
+          Consider only the one device DEVICE.
+
+    CONSOLE
+          Consider all devices on CONSOLE.
+
+    DEVICE-TYPE
+          Consider all devices with device type DEVICE-TYPE.
+
+    `window-system'
+          Consider all devices on window system consoles.
+
+    anything else
+          Consider all devices without restriction.
+
+ - Function: previous-frame &optional frame which-frames which-devices
+     Like `next-frame', but cycles through all frames in the opposite
+     direction.
+
+   See also `next-window' and `previous-window', in *Note Cyclic Window
+Ordering::.
+
+\1f
+File: lispref.info,  Node: Frames and Windows,  Next: Minibuffers and Frames,  Prev: Finding All Frames,  Up: Frames
+
+Frames and Windows
+==================
+
+Each window is part of one and only one frame; you can get the frame
+with `window-frame'.
+
+ - Function: frame-root-window &optional frame
+     This returns the root window of frame FRAME.  FRAME defaults to
+     the selected frame if not specified.
+
+ - Function: window-frame &optional window
+     This function returns the frame that WINDOW is on.  WINDOW
+     defaults to the selected window if omitted.
+
+   All the non-minibuffer windows in a frame are arranged in a cyclic
+order.  The order runs from the frame's top window, which is at the
+upper left corner, down and to the right, until it reaches the window at
+the lower right corner (always the minibuffer window, if the frame has
+one), and then it moves back to the top.
+
+ - Function: frame-highest-window &optional frame position
+     This function returns the topmost, leftmost window of frame FRAME
+     at position POSITION.
+
+     If omitted, FRAME defaults to the currently selected frame.
+
+     POSITION is used to distinguish between multiple windows that abut
+     the top of the frame: 0 means the leftmost window abutting the top
+     of the frame, 1 the next-leftmost, etc.  POSITION can also be less
+     than zero: -1 means the rightmost window abutting the top of the
+     frame, -2 the next-rightmost, etc.  If omitted, POSITION defaults
+     to 0, i.e. the leftmost highest window.  If there is no window at
+     the given POSITION, `nil' is returned.
+
+   The following three functions work similarly.
+
+ - Function: frame-lowest-window &optional frame position
+     This function returns the lowest window on FRAME which is at
+     POSITION.
+
+ - Function: frame-leftmost-window &optional frame position
+     This function returns the leftmost window on FRAME which is at
+     POSITION.
+
+ - Function: frame-rightmost-window &optional frame position
+     This function returns the rightmost window on FRAME which is at
+     POSITION.
+
+   At any time, exactly one window on any frame is "selected within the
+frame".  The significance of this designation is that selecting the
+frame also selects this window.  You can get the frame's current
+selected window with `frame-selected-window'.
+
+ - Function: frame-selected-window &optional frame
+     This function returns the window on FRAME that is selected within
+     FRAME.  FRAME defaults to the selected frame if not specified.
+
+   Conversely, selecting a window for XEmacs with `select-window' also
+makes that window selected within its frame.  *Note Selecting Windows::.
+
+   Another function that (usually) returns one of the windows in a
+frame is `minibuffer-window'.  *Note Minibuffer Misc::.
+
+\1f
+File: lispref.info,  Node: Minibuffers and Frames,  Next: Input Focus,  Prev: Frames and Windows,  Up: Frames
+
+Minibuffers and Frames
+======================
+
+Normally, each frame has its own minibuffer window at the bottom, which
+is used whenever that frame is selected.  If the frame has a minibuffer,
+you can get it with `minibuffer-window' (*note Minibuffer Misc::).
+
+   However, you can also create a frame with no minibuffer.  Such a
+frame must use the minibuffer window of some other frame.  When you
+create the frame, you can specify explicitly the minibuffer window to
+use (in some other frame).  If you don't, then the minibuffer is found
+in the frame which is the value of the variable
+`default-minibuffer-frame'.  Its value should be a frame which does
+have a minibuffer.
+
+ - Variable: default-minibuffer-frame
+     This variable specifies the frame to use for the minibuffer
+     window, by default.
+
+\1f
+File: lispref.info,  Node: Input Focus,  Next: Visibility of Frames,  Prev: Minibuffers and Frames,  Up: Frames
+
+Input Focus
+===========
+
+At any time, one frame in XEmacs is the "selected frame".  The selected
+window always resides on the selected frame.  As the focus moves from
+device to device, the selected frame on each device is remembered and
+restored when the focus moves back to that device.
+
+ - Function: selected-frame &optional device
+     This function returns the selected frame on DEVICE.  If DEVICE is
+     not specified, the selected device will be used.  If no frames
+     exist on the device, `nil' is returned.
+
+   The X server normally directs keyboard input to the X window that the
+mouse is in.  Some window managers use mouse clicks or keyboard events
+to "shift the focus" to various X windows, overriding the normal
+behavior of the server.
+
+   Lisp programs can switch frames "temporarily" by calling the
+function `select-frame'.  This does not override the window manager;
+rather, it escapes from the window manager's control until that control
+is somehow reasserted.
+
+   When using a text-only terminal, there is no window manager;
+therefore, `select-frame' is the only way to switch frames, and the
+effect lasts until overridden by a subsequent call to `select-frame'.
+Only the selected terminal frame is actually displayed on the terminal.
+Each terminal screen except for the initial one has a number, and the
+number of the selected frame appears in the mode line after the word
+`XEmacs' (*note Modeline Variables::).
+
+ - Function: select-frame frame
+     This function selects frame FRAME, temporarily disregarding the
+     focus of the X server if any.  The selection of FRAME lasts until
+     the next time the user does something to select a different frame,
+     or until the next time this function is called.
+
+     Note that `select-frame' does not actually cause the window-system
+     focus to be set to this frame, or the `select-frame-hook' or
+     `deselect-frame-hook' to be run, until the next time that XEmacs is
+     waiting for an event.
+
+     Also note that when the variable `focus-follows-mouse' is
+     non-`nil', the frame selection is temporary and is reverted when
+     the current command terminates, much like the buffer selected by
+     `set-buffer'.  In order to effect a permanent focus change use
+     `focus-frame'.
+
+ - Function: focus-frame frame
+     This function selects FRAME and gives it the window system focus.
+     The operation of `focus-frame' is not affected by the value of
+     `focus-follows-mouse'.
+
+ - Special Form: save-selected-frame forms...
+     This special form records the selected frame, executes FORMS in
+     sequence, then restores the earlier selected frame.  The value
+     returned is the value of the last form.
+
+ - Special Form: with-selected-frame frame forms...
+     This special form records the selected frame, then selects FRAME
+     and executes FORMS in sequence.  After the last form is finished,
+     the earlier selected frame is restored.  The value returned is the
+     value of the last form.
+
+\1f
+File: lispref.info,  Node: Visibility of Frames,  Next: Raising and Lowering,  Prev: Input Focus,  Up: Frames
+
+Visibility of Frames
+====================
+
+An frame on a window system may be "visible", "invisible", or
+"iconified".  If it is visible, you can see its contents.  If it is
+iconified, the frame's contents do not appear on the screen, but an icon
+does.  If the frame is invisible, it doesn't show on the screen, not
+even as an icon.
+
+   Visibility is meaningless for TTY frames, since only the selected
+one is actually displayed in any case.
+
+ - Function: make-frame-visible &optional frame
+     This function makes frame FRAME visible.  If you omit FRAME, it
+     makes the selected frame visible.
+
+ - Function: make-frame-invisible &optional frame force
+     This function makes frame FRAME invisible.
+
+ - Command: iconify-frame &optional frame
+     This function iconifies frame FRAME.
+
+ - Function: Command deiconify-frame &optional frame
+     This function de-iconifies frame FRAME.  Under a window system,
+     this is equivalent to `make-frame-visible'.
+
+ - Function: frame-visible-p &optional frame
+     This returns whether FRAME is currently "visible" (actually in use
+     for display).  A frame that is not visible is not updated, and, if
+     it works through a window system, may not show at all.
+
+ - Function: frame-iconified-p &optional frame
+     This returns whether FRAME is iconified.  Not all window managers
+     use icons; some merely unmap the window, so this function is not
+     the inverse of `frame-visible-p'.  It is possible for a frame to
+     not be visible and not be iconified either.  However, if the frame
+     is iconified, it will not be visible.  (Under FSF Emacs, the
+     functionality of this function is obtained through
+     `frame-visible-p'.)
+
+ - Function: frame-totally-visible-p &optional frame
+     This returns whether FRAME is not obscured by any other X windows.
+     On TTY frames, this is the same as `frame-visible-p'.
+
+\1f
+File: lispref.info,  Node: Raising and Lowering,  Next: Frame Configurations,  Prev: Visibility of Frames,  Up: Frames
+
+Raising and Lowering Frames
+===========================
+
+The X Window System uses a desktop metaphor.  Part of this metaphor is
+the idea that windows are stacked in a notional third dimension
+perpendicular to the screen surface, and thus ordered from "highest" to
+"lowest".  Where two windows overlap, the one higher up covers the one
+underneath.  Even a window at the bottom of the stack can be seen if no
+other window overlaps it.
+
+   A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently.  "Raising" a window means moving it
+"up", to the top of the stack.  "Lowering" a window means moving it to
+the bottom of the stack.  This motion is in the notional third
+dimension only, and does not change the position of the window on the
+screen.
+
+   You can raise and lower XEmacs's X windows with these functions:
+
+ - Command: raise-frame &optional frame
+     This function raises frame FRAME.
+
+ - Command: lower-frame &optional frame
+     This function lowers frame FRAME.
+
+   You can also specify auto-raise (raising automatically when a frame
+is selected) or auto-lower (lowering automatically when it is
+deselected).  Under X, most ICCCM-compliant window managers will have
+an option to do this for you, but the following variables are provided
+in case you're using a broken WM.  (Under FSF Emacs, the same
+functionality is provided through the `auto-raise' and `auto-lower'
+frame properties.)
+
+ - Variable: auto-raise-frame
+     This variable's value is `t' if frames will be raised to the top
+     when selected.
+
+ - Variable: auto-lower-frame
+     This variable's value is `t' if frames will be lowered to the
+     bottom when no longer selected.
+
+   Auto-raising and auto-lowering is implemented through functions
+attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
+Hooks::).  Under normal circumstances, you should not call these
+functions directly.
+
+ - Function: default-select-frame-hook
+     This hook function implements the `auto-raise-frame' variable; it
+     is for use as the value of `select-frame-hook'.
+
+ - Function: default-deselect-frame-hook
+     This hook function implements the `auto-lower-frame' variable; it
+     is for use as the value of `deselect-frame-hook'.
+
+\1f
+File: lispref.info,  Node: Frame Configurations,  Next: Frame Hooks,  Prev: Raising and Lowering,  Up: Frames
+
+Frame Configurations
+====================
+
+A "frame configuration" records the current arrangement of frames, all
+their properties, and the window configuration of each one.
+
+ - Function: current-frame-configuration
+     This function returns a frame configuration list that describes
+     the current arrangement of frames and their contents.
+
+ - Function: set-frame-configuration configuration &optional nodelete
+     This function restores the state of frames described by
+     CONFIGURATION, which should be the return value from a previous
+     call to `current-frame-configuration'.
+
+     Each frame listed in CONFIGURATION has its position, size, window
+     configuration, and other properties set as specified in
+     CONFIGURATION.
+
+     Ordinarily, this function deletes all existing frames not listed in
+     CONFIGURATION.  But if optional second argument NODELETE is
+     non-`nil', the unwanted frames are iconified instead.
+
+\1f
+File: lispref.info,  Node: Frame Hooks,  Prev: Frame Configurations,  Up: Frames
+
+Hooks for Customizing Frame Behavior
+====================================
+
+XEmacs provides many hooks that are called at various times during a
+frame's lifetime.  *Note Hooks::.
+
+ - Variable: create-frame-hook
+     This hook is called each time a frame is created.  The functions
+     are called with one argument, the newly-created frame.
+
+ - Variable: delete-frame-hook
+     This hook is called each time a frame is deleted.  The functions
+     are called with one argument, the about-to-be-deleted frame.
+
+ - Variable: select-frame-hook
+     This is a normal hook that is run just after a frame is selected.
+     The function `default-select-frame-hook', which implements
+     auto-raising (*note Raising and Lowering::), is normally attached
+     to this hook.
+
+     Note that calling `select-frame' does not necessarily set the
+     focus: The actual window-system focus will not be changed until
+     the next time that XEmacs is waiting for an event, and even then,
+     the window manager may refuse the focus-change request.
+
+ - Variable: deselect-frame-hook
+     This is a normal hook that is run just before a frame is deselected
+     (and another frame is selected).  The function
+     `default-deselect-frame-hook', which implements auto-lowering
+     (*note Raising and Lowering::), is normally attached to this hook.
+
+ - Variable: map-frame-hook
+     This hook is called each time a frame is mapped (i.e. made
+     visible).  The functions are called with one argument, the newly
+     mapped frame.
+
+ - Variable: unmap-frame-hook
+     This hook is called each time a frame is unmapped (i.e. made
+     invisible or iconified).  The functions are called with one
+     argument, the newly unmapped frame.
+
+\1f
+File: lispref.info,  Node: Consoles and Devices,  Next: Positions,  Prev: Frames,  Up: Top
+
+Consoles and Devices
+********************
+
+A "console" is an object representing a single input connection to
+XEmacs, such as an X display or a TTY connection.  It is possible for
+XEmacs to have frames on multiple consoles at once (even on
+heterogeneous types--you can simultaneously have a frame on an X
+display and a TTY connection).  Normally, there is only one console in
+existence.
+
+   A "device" is an object representing a single output device, such as
+a particular screen on an X display. (Usually there is exactly one
+device per X console connection, but there may be more than one if you
+have a multi-headed X display.  For TTY connections, there is always
+exactly one device per console.)
+
+   Each device has one or more "frames" in which text can be displayed.
+For X displays and the like, a frame corresponds to the normal
+window-system concept of a window.  Frames can overlap, be displayed at
+various locations within the display, be resized, etc.  For TTY, only
+one frame can be displayed at a time, and it occupies the entire TTY
+display area.
+
+   However, you can still define multiple frames and switch between
+them.  Their contents are entirely separate from each other.  These
+sorts of frames resemble the "virtual console" capability provided
+under Linux or the multiple screens provided by the multiplexing program
+`screen' under Unix.
+
+   When you start up XEmacs, an initial console and device are created
+to receive input and display frames on.  This will either be an X
+display or a TTY connection, depending on what mode you started XEmacs
+in (this is determined by the `DISPLAY' environment variable, the
+`-nw', `-t' and `-display' command-line options, etc.).
+
+   You can connect to other X displays and TTY connections by creating
+new console objects, and to other X screens on an existing display by
+creating new device objects, as described below.  Many functions (for
+example the frame-creation functions) take an optional device argument
+specifying which device the function pertains to.  If the argument is
+omitted, it defaults to the selected device (see below).
+
+ - Function: consolep object
+     This returns non-`nil' if OBJECT is a console.
+
+ - Function: devicep object
+     This returns non-`nil' if OBJECT is a device.
+
+* Menu:
+
+* Basic Console Functions::     Functions for working with consoles.
+* Basic Device Functions::      Functions for working with devices.
+* Console Types and Device Classes::
+                                I/O and color characteristics.
+* Connecting to a Console or Device::
+* The Selected Console and Device::
+* Console and Device I/O::      Controlling input and output.
+
+\1f
+File: lispref.info,  Node: Basic Console Functions,  Next: Basic Device Functions,  Up: Consoles and Devices
+
+Basic Console Functions
+=======================
+
+ - Function: console-list
+     This function returns a list of all existing consoles.
+
+ - Function: console-device-list &optional console
+     This function returns a list of all devices on CONSOLE.  If
+     CONSOLE is `nil', the selected console will be used.
+
+\1f
+File: lispref.info,  Node: Basic Device Functions,  Next: Console Types and Device Classes,  Prev: Basic Console Functions,  Up: Consoles and Devices
+
+Basic Device Functions
+======================
+
+ - Function: device-list
+     This function returns a list of all existing devices.
+
+ - Function: device-or-frame-p object
+     This function returns non-`nil' if OBJECT is a device or frame.
+     This function is useful because devices and frames are similar in
+     many respects and many functions can operate on either one.
+
+ - Function: device-frame-list &optional device
+     This function returns a list of all frames on DEVICE.  DEVICE
+     defaults to the currently selected device.
+
+ - Function: frame-device &optional frame
+     This function returns the device that FRAME is on.  FRAME defaults
+     to the currently selected frame.
+
+\1f
+File: lispref.info,  Node: Console Types and Device Classes,  Next: Connecting to a Console or Device,  Prev: Basic Device Functions,  Up: Consoles and Devices
+
+Console Types and Device Classes
+================================
+
+Every device is of a particular "type", which describes how the
+connection to that device is made and how the device operates, and a
+particular "class", which describes other characteristics of the device
+(currently, the color capabilities of the device).
+
+   The currently-defined device types are
+
+`x'
+     A connection to an X display (such as `willow:0').
+
+`tty'
+     A connection to a tty (such as `/dev/ttyp3').
+
+`stream'
+     A stdio connection.  This describes a device for which input and
+     output is only possible in a stream-like fashion, such as when
+     XEmacs in running in batch mode.  The very first device created by
+     XEmacs is a terminal device and is used to print out messages of
+     various sorts (for example, the help message when you use the
+     `-help' command-line option).
+
+   The currently-defined device classes are
+`color'
+     A color device.
+
+`grayscale'
+     A grayscale device (a device that can display multiple shades of
+     gray, but no color).
+
+`mono'
+     A device that can only display two colors (e.g. black and white).
+
+ - Function: device-type &optional device
+     This function returns the type of DEVICE.  This is a symbol whose
+     name is one of the device types mentioned above.  DEVICE defaults
+     to the selected device.
+
+ - Function: device-or-frame-type device-or-frame
+     This function returns the type of DEVICE-OR-FRAME.
+
+ - Function: device-class &optional device
+     This function returns the class (color behavior) of DEVICE.  This
+     is a symbol whose name is one of the device classes mentioned
+     above.
+
+ - Function: valid-device-type-p device-type
+     This function returns whether DEVICE-TYPE (which should be a
+     symbol) specifies a valid device type.
+
+ - Function: valid-device-class-p device-class
+     This function returns whether DEVICE-CLASS (which should be a
+     symbol) specifies a valid device class.
+
+ - Variable: terminal-device
+     This variable holds the initial terminal device object, which
+     represents XEmacs's stdout.
+
+\1f
+File: lispref.info,  Node: Connecting to a Console or Device,  Next: The Selected Console and Device,  Prev: Console Types and Device Classes,  Up: Consoles and Devices
+
+Connecting to a Console or Device
+=================================
+
+ - Function: make-device type connection &optional props
+     This function creates a new device.
+
+   The following two functions create devices of specific types and are
+written in terms of `make-device'.
+
+ - Function: make-tty-device &optional tty terminal-type
+     This function creates a new tty device on TTY.  This also creates
+     the tty's first frame.  TTY should be a string giving the name of
+     a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
+     returned by the `tty' command issued from the Unix shell.  A value
+     of `nil' means use the stdin and stdout as passed to XEmacs from
+     the shell.  If TERMINAL-TYPE is non-`nil', it should be a string
+     specifying the type of the terminal attached to the specified tty.
+     If it is `nil', the terminal type will be inferred from the
+     `TERM' environment variable.
+
+ - Function: make-x-device &optional display argv-list
+     This function creates a new device connected to DISPLAY.  Optional
+     argument ARGV-LIST is a list of strings describing command line
+     options.
+
+ - Function: delete-device device &optional force
+     This function deletes DEVICE, permanently eliminating it from use.
+     This disconnects XEmacs's connection to the device.
+
+ - Variable: create-device-hook
+     This variable, if non-`nil', should contain a list of functions,
+     which are called when a device is created.
+
+ - Variable: delete-device-hook
+     This variable, if non-`nil', should contain a list of functions,
+     which are called when a device is deleted.
+
+ - Function: console-live-p object
+     This function returns non-`nil' if OBJECT is a console that has
+     not been deleted.
+
+ - Function: device-live-p object
+     This function returns non-`nil' if OBJECT is a device that has not
+     been deleted.
+
+ - Function: device-x-display device
+     This function returns the X display which DEVICE is connected to,
+     if DEVICE is an X device.
+
+\1f
+File: lispref.info,  Node: The Selected Console and Device,  Next: Console and Device I/O,  Prev: Connecting to a Console or Device,  Up: Consoles and Devices
+
+The Selected Console and Device
+===============================
+
+ - Function: select-console console
+     This function selects the console CONSOLE.  Subsequent editing
+     commands apply to its selected device, selected frame, and selected
+     window.  The selection of CONSOLE lasts until the next time the
+     user does something to select a different console, or until the
+     next time this function is called.
+
+ - Function: selected-console
+     This function returns the console which is currently active.
+
+ - Function: select-device device
+     This function selects the device DEVICE.
+
+ - Function: selected-device &optional console
+     This function returns the device which is currently active.  If
+     optional CONSOLE is non-`nil', this function returns the device
+     that would be currently active if CONSOLE were the selected
+     console.
+
+\1f
+File: lispref.info,  Node: Console and Device I/O,  Prev: The Selected Console and Device,  Up: Consoles and Devices
+
+Console and Device I/O
+======================
+
+ - Function: console-disable-input console
+     This function disables input on console CONSOLE.
+
+ - Function: console-enable-input console
+     This function enables input on console CONSOLE.
+
+   Each device has a "baud rate" value associated with it.  On most
+systems, changing this value will affect the amount of padding and
+other strategic decisions made during redisplay.
+
+ - Function: device-baud-rate &optional device
+     This function returns the output baud rate of DEVICE.
+
+ - Function: set-device-baud-rate device rate
+     This function sets the output baud rate of DEVICE to RATE.
+
+\1f
+File: lispref.info,  Node: Positions,  Next: Markers,  Prev: Consoles and Devices,  Up: Top
+
+Positions
+*********
+
+A "position" is the index of a character in the text of a buffer.  More
+precisely, a position identifies the place between two characters (or
+before the first character, or after the last character), so we can
+speak of the character before or after a given position.  However, we
+often speak of the character "at" a position, meaning the character
+after that position.
+
+   Positions are usually represented as integers starting from 1, but
+can also be represented as "markers"--special objects that relocate
+automatically when text is inserted or deleted so they stay with the
+surrounding characters.  *Note Markers::.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Point,  Next: Motion,  Up: Positions
+
+Point
+=====
+
+"Point" is a special buffer position used by many editing commands,
+including the self-inserting typed characters and text insertion
+functions.  Other commands move point through the text to allow editing
+and insertion at different places.
+
+   Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character.  Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
+
+   The value of point is a number between 1 and the buffer size plus 1.
+If narrowing is in effect (*note Narrowing::), then point is constrained
+to fall within the accessible portion of the buffer (possibly at one end
+of it).
+
+   Each buffer has its own value of point, which is independent of the
+value of point in other buffers.  Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer.  This is why point can have different values in various windows
+that display the same buffer.  When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important.  *Note Window Point::, for more
+details.
+
+ - Function: point &optional buffer
+     This function returns the value of point in BUFFER, as an integer.
+     BUFFER defaults to the current buffer if omitted.
+
+          (point)
+               => 175
+
+ - Function: point-min &optional buffer
+     This function returns the minimum accessible value of point in
+     BUFFER.  This is normally 1, but if narrowing is in effect, it is
+     the position of the start of the region that you narrowed to.
+     (*Note Narrowing::.) BUFFER defaults to the current buffer if
+     omitted.
+
+ - Function: point-max &optional buffer
+     This function returns the maximum accessible value of point in
+     BUFFER.  This is `(1+ (buffer-size buffer))', unless narrowing is
+     in effect, in which case it is the position of the end of the
+     region that you narrowed to. (*note Narrowing::).  BUFFER defaults
+     to the current buffer if omitted.
+
+ - Function: buffer-end flag &optional buffer
+     This function returns `(point-min buffer)' if FLAG is less than 1,
+     `(point-max buffer)' otherwise.  The argument FLAG must be a
+     number.  BUFFER defaults to the current buffer if omitted.
+
+ - Function: buffer-size &optional buffer
+     This function returns the total number of characters in BUFFER.
+     In the absence of any narrowing (*note Narrowing::), `point-max'
+     returns a value one larger than this.  BUFFER defaults to the
+     current buffer if omitted.
+
+          (buffer-size)
+               => 35
+          (point-max)
+               => 36
+
+ - Variable: buffer-saved-size
+     The value of this buffer-local variable is the former length of the
+     current buffer, as of the last time it was read in, saved or
+     auto-saved.
+
+\1f
+File: lispref.info,  Node: Motion,  Next: Excursions,  Prev: Point,  Up: Positions
+
+Motion
+======
+
+Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window.  *Note Point::.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Character Motion,  Next: Word Motion,  Up: Motion
+
+Motion by Characters
+--------------------
+
+These functions move point based on a count of characters.  `goto-char'
+is the fundamental primitive; the other functions use that.
+
+ - Command: goto-char position &optional buffer
+     This function sets point in `buffer' to the value POSITION.  If
+     POSITION is less than 1, it moves point to the beginning of the
+     buffer.  If POSITION is greater than the length of the buffer, it
+     moves point to the end.  BUFFER defaults to the current buffer if
+     omitted.
+
+     If narrowing is in effect, POSITION still counts from the
+     beginning of the buffer, but point cannot go outside the accessible
+     portion.  If POSITION is out of range, `goto-char' moves point to
+     the beginning or the end of the accessible portion.
+
+     When this function is called interactively, POSITION is the
+     numeric prefix argument, if provided; otherwise it is read from the
+     minibuffer.
+
+     `goto-char' returns POSITION.
+
+ - Command: forward-char &optional count buffer
+     This function moves point COUNT characters forward, towards the
+     end of the buffer (or backward, towards the beginning of the
+     buffer, if COUNT is negative).  If the function attempts to move
+     point past the beginning or end of the buffer (or the limits of
+     the accessible portion, when narrowing is in effect), an error is
+     signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+     BUFFER defaults to the current buffer if omitted.
+
+     In an interactive call, COUNT is the numeric prefix argument.
+
+ - Command: backward-char &optional count buffer
+     This function moves point COUNT characters backward, towards the
+     beginning of the buffer (or forward, towards the end of the
+     buffer, if COUNT is negative).  If the function attempts to move
+     point past the beginning or end of the buffer (or the limits of
+     the accessible portion, when narrowing is in effect), an error is
+     signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+     BUFFER defaults to the current buffer if omitted.
+
+     In an interactive call, COUNT is the numeric prefix argument.
+
+\1f
+File: lispref.info,  Node: Word Motion,  Next: Buffer End Motion,  Prev: Character Motion,  Up: Motion
+
+Motion by Words
+---------------
+
+These functions for parsing words use the syntax table to decide
+whether a given character is part of a word.  *Note Syntax Tables::.
+
+ - Command: forward-word &optional count buffer
+     This function moves point forward COUNT words (or backward if
+     COUNT is negative).  Normally it returns `t'.  If this motion
+     encounters the beginning or end of the buffer, or the limits of the
+     accessible portion when narrowing is in effect, point stops there
+     and the value is `nil'.
+
+     COUNT defaults to `1' and BUFFER defaults to the current buffer.
+
+     In an interactive call, COUNT is set to the numeric prefix
+     argument.
+
+ - Command: backward-word &optional count buffer
+     This function is just like `forward-word', except that it moves
+     backward until encountering the front of a word, rather than
+     forward.  BUFFER defaults to the current buffer if omitted.
+
+     In an interactive call, COUNT is set to the numeric prefix
+     argument.
+
+ - Variable: words-include-escapes
+     This variable affects the behavior of `forward-word' and everything
+     that uses it.  If it is non-`nil', then characters in the "escape"
+     and "character quote" syntax classes count as part of words.
+     Otherwise, they do not.
+
+\1f
+File: lispref.info,  Node: Buffer End Motion,  Next: Text Lines,  Prev: Word Motion,  Up: Motion
+
+Motion to an End of the Buffer
+------------------------------
+
+To move point to the beginning of the buffer, write:
+
+     (goto-char (point-min))
+
+Likewise, to move to the end of the buffer, use:
+
+     (goto-char (point-max))
+
+   Here are two commands that users use to do these things.  They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
+
+ - Command: beginning-of-buffer &optional count
+     This function moves point to the beginning of the buffer (or the
+     limits of the accessible portion, when narrowing is in effect),
+     setting the mark at the previous position.  If COUNT is non-`nil',
+     then it puts point COUNT tenths of the way from the beginning of
+     the buffer.
+
+     In an interactive call, COUNT is the numeric prefix argument, if
+     provided; otherwise COUNT defaults to `nil'.
+
+     Don't use this function in Lisp programs!
+
+ - Command: end-of-buffer &optional count
+     This function moves point to the end of the buffer (or the limits
+     of the accessible portion, when narrowing is in effect), setting
+     the mark at the previous position.  If COUNT is non-`nil', then it
+     puts point COUNT tenths of the way from the end of the buffer.
+
+     In an interactive call, COUNT is the numeric prefix argument, if
+     provided; otherwise COUNT defaults to `nil'.
+
+     Don't use this function in Lisp programs!
+
+\1f
+File: lispref.info,  Node: Text Lines,  Next: Screen Lines,  Prev: Buffer End Motion,  Up: Motion
+
+Motion by Text Lines
+--------------------
+
+Text lines are portions of the buffer delimited by newline characters,
+which are regarded as part of the previous line.  The first text line
+begins at the beginning of the buffer, and the last text line ends at
+the end of the buffer whether or not the last character is a newline.
+The division of the buffer into text lines is not affected by the width
+of the window, by line continuation in display, or by how tabs and
+control characters are displayed.
+
+ - Command: goto-line line
+     This function moves point to the front of the LINEth line,
+     counting from line 1 at beginning of the buffer.  If LINE is less
+     than 1, it moves point to the beginning of the buffer.  If LINE is
+     greater than the number of lines in the buffer, it moves point to
+     the end of the buffer--that is, the _end of the last line_ of the
+     buffer.  This is the only case in which `goto-line' does not
+     necessarily move to the beginning of a line.
+
+     If narrowing is in effect, then LINE still counts from the
+     beginning of the buffer, but point cannot go outside the accessible
+     portion.  So `goto-line' moves point to the beginning or end of the
+     accessible portion, if the line number specifies an inaccessible
+     position.
+
+     The return value of `goto-line' is the difference between LINE and
+     the line number of the line to which point actually was able to
+     move (in the full buffer, before taking account of narrowing).
+     Thus, the value is positive if the scan encounters the real end of
+     the buffer.  The value is zero if scan encounters the end of the
+     accessible portion but not the real end of the buffer.
+
+     In an interactive call, LINE is the numeric prefix argument if one
+     has been provided.  Otherwise LINE is read in the minibuffer.
+
+ - Command: beginning-of-line &optional count buffer
+     This function moves point to the beginning of the current line.
+     With an argument COUNT not `nil' or 1, it moves forward COUNT-1
+     lines and then to the beginning of the line.  BUFFER defaults to
+     the current buffer if omitted.
+
+     If this function reaches the end of the buffer (or of the
+     accessible portion, if narrowing is in effect), it positions point
+     there.  No error is signaled.
+
+ - Command: end-of-line &optional count buffer
+     This function moves point to the end of the current line.  With an
+     argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
+     then to the end of the line.  BUFFER defaults to the current
+     buffer if omitted.
+
+     If this function reaches the end of the buffer (or of the
+     accessible portion, if narrowing is in effect), it positions point
+     there.  No error is signaled.
+
+ - Command: forward-line &optional count buffer
+     This function moves point forward COUNT lines, to the beginning of
+     the line.  If COUNT is negative, it moves point -COUNT lines
+     backward, to the beginning of a line.  If COUNT is zero, it moves
+     point to the beginning of the current line.  BUFFER defaults to
+     the current buffer if omitted.
+
+     If `forward-line' encounters the beginning or end of the buffer (or
+     of the accessible portion) before finding that many lines, it sets
+     point there.  No error is signaled.
+
+     `forward-line' returns the difference between COUNT and the number
+     of lines actually moved.  If you attempt to move down five lines
+     from the beginning of a buffer that has only three lines, point
+     stops at the end of the last line, and the value will be 2.
+
+     In an interactive call, COUNT is the numeric prefix argument.
+
+ - Function: count-lines start end &optional ignore-invisible-lines-flag
+     This function returns the number of lines between the positions
+     START and END in the current buffer.  If START and END are equal,
+     then it returns 0.  Otherwise it returns at least 1, even if START
+     and END are on the same line.  This is because the text between
+     them, considered in isolation, must contain at least one line
+     unless it is empty.
+
+     With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
+     collapsed with selective-display are excluded from the line count.
+
+     *Note:* The expression to return the current line number is not
+     obvious:
+
+          (1+ (count-lines 1 (point-at-bol)))
+
+     Here is an example of using `count-lines':
+
+          (defun current-line ()
+            "Return the vertical position of point..."
+            (+ (count-lines (window-start) (point))
+               (if (= (current-column) 0) 1 0)
+               -1))
+
+   Also see the functions `bolp' and `eolp' in *Note Near Point::.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+\1f
+File: lispref.info,  Node: Screen Lines,  Next: List Motion,  Prev: Text Lines,  Up: Motion
+
+Motion by Screen Lines
+----------------------
+
+The line functions in the previous section count text lines, delimited
+only by newline characters.  By contrast, these functions count screen
+lines, which are defined by the way the text appears on the screen.  A
+text line is a single screen line if it is short enough to fit the width
+of the selected window, but otherwise it may occupy several screen
+lines.
+
+   In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines.  In these cases,
+`vertical-motion' moves point much like `forward-line'.  *Note
+Truncation::.
+
+   Because the width of a given string depends on the flags that control
+the appearance of certain characters, `vertical-motion' behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows).  *Note Usual
+Display::.
+
+   These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned.  If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code.  *Note cache-long-line-scans: Text Lines.
+
+ - Function: vertical-motion count &optional window pixels
+     This function moves point to the start of the frame line COUNT
+     frame lines down from the frame line containing point.  If COUNT
+     is negative, it moves up instead.  The optional second argument
+     WINDOW may be used to specify a window other than the selected
+     window in which to perform the motion.
+
+     Normally, `vertical-motion' returns the number of lines moved.  The
+     value may be less in absolute value than COUNT if the beginning or
+     end of the buffer was reached.  If the optional third argument,
+     PIXELS is non-`nil', the vertical pixel height of the motion which
+     took place is returned instead of the actual number of lines
+     moved.  A motion of zero lines returns the height of the current
+     line.
+
+     Note that `vertical-motion' sets WINDOW's buffer's point, not
+     WINDOW's point. (This differs from FSF Emacs, which buggily always
+     sets current buffer's point, regardless of WINDOW.)
+
+ - Function: vertical-motion-pixels count &optional window how
+     This function moves point to the start of the frame line PIXELS
+     vertical pixels down from the frame line containing point, or up if
+     PIXELS is negative.  The optional second argument WINDOW is the
+     window to move in, and defaults to the selected window.  The
+     optional third argument HOW specifies the stopping condition.  A
+     negative integer indicates that the motion should be no more than
+     PIXELS.  A positive value indicates that the motion should be at
+     least PIXELS.  Any other value indicates that the motion should be
+     as close as possible to PIXELS.
+
+ - Command: move-to-window-line count &optional window
+     This function moves point with respect to the text currently
+     displayed in WINDOW, which defaults to the selected window.  It
+     moves point to the beginning of the screen line COUNT screen lines
+     from the top of the window.  If COUNT is negative, that specifies a
+     position -COUNT lines from the bottom (or the last line of the
+     buffer, if the buffer ends above the specified screen position).
+
+     If COUNT is `nil', then point moves to the beginning of the line
+     in the middle of the window.  If the absolute value of COUNT is
+     greater than the size of the window, then point moves to the place
+     that would appear on that screen line if the window were tall
+     enough.  This will probably cause the next redisplay to scroll to
+     bring that location onto the screen.
+
+     In an interactive call, COUNT is the numeric prefix argument.
+
+     The value returned is the window line number point has moved to,
+     with the top line in the window numbered 0.
+
+\1f
+File: lispref.info,  Node: List Motion,  Next: Skipping Characters,  Prev: Screen Lines,  Up: Motion
+
+Moving over Balanced Expressions
+--------------------------------
+
+Here are several functions concerned with balanced-parenthesis
+expressions (also called "sexps" in connection with moving across them
+in XEmacs).  The syntax table controls how these functions interpret
+various characters; see *Note Syntax Tables::.  *Note Parsing
+Expressions::, for lower-level primitives for scanning sexps or parts of
+sexps.  For user-level commands, see *Note Lists and Sexps:
+(xemacs)Lists and Sexps.
+
+ - Command: forward-list &optional arg
+     This function moves forward across ARG balanced groups of
+     parentheses. (Other syntactic entities such as words or paired
+     string quotes are ignored.) ARG defaults to 1 if omitted.  If ARG
+     is negative, move backward across that many groups of parentheses.
+
+ - Command: backward-list &optional count
+     This function moves backward across COUNT balanced groups of
+     parentheses. (Other syntactic entities such as words or paired
+     string quotes are ignored.) COUNT defaults to 1 if omitted.  If
+     COUNT is negative, move forward across that many groups of
+     parentheses.
+
+ - Command: up-list &optional count
+     This function moves forward out of COUNT levels of parentheses.  A
+     negative argument means move backward but still to a less deep
+     spot.
+
+ - Command: down-list &optional count
+     This function moves forward into COUNT levels of parentheses.  A
+     negative argument means move backward but still go deeper in
+     parentheses (-COUNT levels).
+
+ - Command: forward-sexp &optional count
+     This function moves forward across COUNT balanced expressions.
+     Balanced expressions include both those delimited by parentheses
+     and other kinds, such as words and string constants.  COUNT
+     defaults to 1 if omitted.  If COUNT is negative, move backward
+     across that many balanced expressions.  For example,
+
+          ---------- Buffer: foo ----------
+          (concat-!- "foo " (car x) y z)
+          ---------- Buffer: foo ----------
+          
+          (forward-sexp 3)
+               => nil
+          
+          ---------- Buffer: foo ----------
+          (concat "foo " (car x) y-!- z)
+          ---------- Buffer: foo ----------
+
+ - Command: backward-sexp &optional count
+     This function moves backward across COUNT balanced expressions.
+     COUNT defaults to 1 if omitted.  If COUNT is negative, move
+     forward across that many balanced expressions.
+
+ - Command: beginning-of-defun &optional count
+     This function moves back to the COUNTth beginning of a defun.  If
+     COUNT is negative, this actually moves forward, but it still moves
+     to the beginning of a defun, not to the end of one.  COUNT
+     defaults to 1 if omitted.
+
+ - Command: end-of-defun &optional count
+     This function moves forward to the COUNTth end of a defun.  If
+     COUNT is negative, this actually moves backward, but it still
+     moves to the end of a defun, not to the beginning of one.  COUNT
+     defaults to 1 if omitted.
+
+ - User Option: defun-prompt-regexp
+     If non-`nil', this variable holds a regular expression that
+     specifies what text can appear before the open-parenthesis that
+     starts a defun.  That is to say, a defun begins on a line that
+     starts with a match for this regular expression, followed by a
+     character with open-parenthesis syntax.
+
+\1f
+File: lispref.info,  Node: Skipping Characters,  Prev: List Motion,  Up: Motion
+
+Skipping Characters
+-------------------
+
+The following two functions move point over a specified set of
+characters.  For example, they are often used to skip whitespace.  For
+related functions, see *Note Motion and Syntax::.
+
+ - Function: skip-chars-forward character-set &optional limit buffer
+     This function moves point in BUFFER forward, skipping over a given
+     set of characters.  It examines the character following point,
+     then advances point if the character matches CHARACTER-SET.  This
+     continues until it reaches a character that does not match.  The
+     function returns `nil'.  BUFFER defaults to the current buffer if
+     omitted.
+
+     The argument CHARACTER-SET is like the inside of a `[...]' in a
+     regular expression except that `]' is never special and `\' quotes
+     `^', `-' or `\'.  Thus, `"a-zA-Z"' skips over all letters,
+     stopping before the first non-letter, and `"^a-zA-Z'" skips
+     non-letters stopping before the first letter.  *Note Regular
+     Expressions::.
+
+     If LIMIT is supplied (it must be a number or a marker), it
+     specifies the maximum position in the buffer that point can be
+     skipped to.  Point will stop at or before LIMIT.
+
+     In the following example, point is initially located directly
+     before the `T'.  After the form is evaluated, point is located at
+     the end of that line (between the `t' of `hat' and the newline).
+     The function skips all letters and spaces, but not newlines.
+
+          ---------- Buffer: foo ----------
+          I read "-!-The cat in the hat
+          comes back" twice.
+          ---------- Buffer: foo ----------
+          
+          (skip-chars-forward "a-zA-Z ")
+               => nil
+          
+          ---------- Buffer: foo ----------
+          I read "The cat in the hat-!-
+          comes back" twice.
+          ---------- Buffer: foo ----------
+
+ - Function: skip-chars-backward character-set &optional limit buffer
+     This function moves point backward, skipping characters that match
+     CHARACTER-SET, until LIMIT.  It just like `skip-chars-forward'
+     except for the direction of motion.
+
+\1f
+File: lispref.info,  Node: Excursions,  Next: Narrowing,  Prev: Motion,  Up: Positions
+
+Excursions
+==========
+
+It is often useful to move point "temporarily" within a localized
+portion of the program, or to switch buffers temporarily.  This is
+called an "excursion", and it is done with the `save-excursion' special
+form.  This construct saves the current buffer and its values of point
+and the mark so they can be restored after the completion of the
+excursion.
+
+   The forms for saving and restoring the configuration of windows are
+described elsewhere (see *Note Window Configurations:: and *note Frame
+Configurations::).
+
+ - Special Form: save-excursion forms...
+     The `save-excursion' special form saves the identity of the current
+     buffer and the values of point and the mark in it, evaluates
+     FORMS, and finally restores the buffer and its saved values of
+     point and the mark.  All three saved values are restored even in
+     case of an abnormal exit via `throw' or error (*note Nonlocal
+     Exits::).
+
+     The `save-excursion' special form is the standard way to switch
+     buffers or move point within one part of a program and avoid
+     affecting the rest of the program.  It is used more than 500 times
+     in the Lisp sources of XEmacs.
+
+     `save-excursion' does not save the values of point and the mark for
+     other buffers, so changes in other buffers remain in effect after
+     `save-excursion' exits.
+
+     Likewise, `save-excursion' does not restore window-buffer
+     correspondences altered by functions such as `switch-to-buffer'.
+     One way to restore these correspondences, and the selected window,
+     is to use `save-window-excursion' inside `save-excursion' (*note
+     Window Configurations::).
+
+     The value returned by `save-excursion' is the result of the last of
+     FORMS, or `nil' if no FORMS are given.
+
+          (save-excursion
+            FORMS)
+          ==
+          (let ((old-buf (current-buffer))
+                (old-pnt (point-marker))
+                (old-mark (copy-marker (mark-marker))))
+            (unwind-protect
+                (progn FORMS)
+              (set-buffer old-buf)
+              (goto-char old-pnt)
+              (set-marker (mark-marker) old-mark)))
+
+ - Special Form: save-current-buffer forms...
+     This special form is similar to `save-excursion' but it only saves
+     and restores the current buffer.  Beginning with XEmacs 20.3,
+     `save-current-buffer' is a primitive.
+
+ - Special Form: with-current-buffer buffer forms...
+     This special form evaluates FORMS with BUFFER as the current
+     buffer.  It returns the value of the last form.
+
+ - Special Form: with-temp-file filename forms...
+     This special form creates a new buffer, evaluates FORMS there, and
+     writes the buffer to FILENAME.  It returns the value of the last
+     form evaluated.
+
+ - Special Form: save-selected-window forms...
+     This special form is similar to `save-excursion' but it saves and
+     restores the selected window and nothing else.
+
+\1f
+File: lispref.info,  Node: Narrowing,  Prev: Excursions,  Up: Positions
+
+Narrowing
+=========
+
+"Narrowing" means limiting the text addressable by XEmacs editing
+commands to a limited range of characters in a buffer.  The text that
+remains addressable is called the "accessible portion" of the buffer.
+
+   Narrowing is specified with two buffer positions which become the
+beginning and end of the accessible portion.  For most editing commands
+and most Emacs primitives, these positions replace the values of the
+beginning and end of the buffer.  While narrowing is in effect, no text
+outside the accessible portion is displayed, and point cannot move
+outside the accessible portion.
+
+   Values such as positions or line numbers, which usually count from
+the beginning of the buffer, do so despite narrowing, but the functions
+which use them refuse to operate on text that is inaccessible.
+
+   The commands for saving buffers are unaffected by narrowing; they
+save the entire buffer regardless of any narrowing.
+
+ - Command: narrow-to-region start end &optional buffer
+     This function sets the accessible portion of BUFFER to start at
+     START and end at END.  Both arguments should be character
+     positions.  BUFFER defaults to the current buffer if omitted.
+
+     In an interactive call, START and END are set to the bounds of the
+     current region (point and the mark, with the smallest first).
+
+ - Command: narrow-to-page &optional move-count
+     This function sets the accessible portion of the current buffer to
+     include just the current page.  An optional first argument
+     MOVE-COUNT non-`nil' means to move forward or backward by
+     MOVE-COUNT pages and then narrow.  The variable `page-delimiter'
+     specifies where pages start and end (*note Standard Regexps::).
+
+     In an interactive call, MOVE-COUNT is set to the numeric prefix
+     argument.
+
+ - Command: widen &optional buffer
+     This function cancels any narrowing in BUFFER, so that the entire
+     contents are accessible.  This is called "widening".  It is
+     equivalent to the following expression:
+
+          (narrow-to-region 1 (1+ (buffer-size)))
+
+     BUFFER defaults to the current buffer if omitted.
+
+ - Special Form: save-restriction body...
+     This special form saves the current bounds of the accessible
+     portion, evaluates the BODY forms, and finally restores the saved
+     bounds, thus restoring the same state of narrowing (or absence
+     thereof) formerly in effect.  The state of narrowing is restored
+     even in the event of an abnormal exit via `throw' or error (*note
+     Nonlocal Exits::).  Therefore, this construct is a clean way to
+     narrow a buffer temporarily.
+
+     The value returned by `save-restriction' is that returned by the
+     last form in BODY, or `nil' if no body forms were given.
+
+     *Caution:* it is easy to make a mistake when using the
+     `save-restriction' construct.  Read the entire description here
+     before you try it.
+
+     If BODY changes the current buffer, `save-restriction' still
+     restores the restrictions on the original buffer (the buffer whose
+     restrictions it saved from), but it does not restore the identity
+     of the current buffer.
+
+     `save-restriction' does _not_ restore point and the mark; use
+     `save-excursion' for that.  If you use both `save-restriction' and
+     `save-excursion' together, `save-excursion' should come first (on
+     the outside).  Otherwise, the old point value would be restored
+     with temporary narrowing still in effect.  If the old point value
+     were outside the limits of the temporary narrowing, this would
+     fail to restore it accurately.
+
+     The `save-restriction' special form records the values of the
+     beginning and end of the accessible portion as distances from the
+     beginning and end of the buffer.  In other words, it records the
+     amount of inaccessible text before and after the accessible
+     portion.
+
+     This method yields correct results if BODY does further narrowing.
+     However, `save-restriction' can become confused if the body widens
+     and then make changes outside the range of the saved narrowing.
+     When this is what you want to do, `save-restriction' is not the
+     right tool for the job.  Here is what you must use instead:
+
+          (let ((start (point-min-marker))
+                (end (point-max-marker)))
+            (unwind-protect
+                (progn BODY)
+              (save-excursion
+                (set-buffer (marker-buffer start))
+                (narrow-to-region start end))))
+
+     Here is a simple example of correct use of `save-restriction':
+
+          ---------- Buffer: foo ----------
+          This is the contents of foo
+          This is the contents of foo
+          This is the contents of foo-!-
+          ---------- Buffer: foo ----------
+          
+          (save-excursion
+            (save-restriction
+              (goto-char 1)
+              (forward-line 2)
+              (narrow-to-region 1 (point))
+              (goto-char (point-min))
+              (replace-string "foo" "bar")))
+          
+          ---------- Buffer: foo ----------
+          This is the contents of bar
+          This is the contents of bar
+          This is the contents of foo-!-
+          ---------- Buffer: foo ----------
+
+\1f
+File: lispref.info,  Node: Markers,  Next: Text,  Prev: Positions,  Up: Top
+
+Markers
+*******
+
+A "marker" is a Lisp object used to specify a position in a buffer
+relative to the surrounding text.  A marker changes its offset from the
+beginning of the buffer automatically whenever text is inserted or
+deleted, so that it stays with the two characters on either side of it.
+
+* Menu:
+
+* 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''.
+
+\1f
+File: lispref.info,  Node: Overview of Markers,  Next: Predicates on Markers,  Up: Markers
+
+Overview of Markers
+===================
+
+A marker specifies a buffer and a position in that buffer.  The marker
+can be used to represent a position in the functions that require one,
+just as an integer could be used.  *Note Positions::, for a complete
+description of positions.
+
+   A marker has two attributes: the marker position, and the marker
+buffer.  The marker position is an integer that is equivalent (at a
+given time) to the marker as a position in that buffer.  But the
+marker's position value can change often during the life of the marker.
+Insertion and deletion of text in the buffer relocate the marker.  The
+idea is that a marker positioned between two characters remains between
+those two characters despite insertion and deletion elsewhere in the
+buffer.  Relocation changes the integer equivalent of the marker.
+
+   Deleting text around a marker's position leaves the marker between
+the characters immediately before and after the deleted text.  Inserting
+text at the position of a marker normally leaves the marker in front of
+the new text--unless it is inserted with `insert-before-markers' (*note
+Insertion::).
+
+   Insertion and deletion in a buffer must check all the markers and
+relocate them if necessary.  This slows processing in a buffer with a
+large number of markers.  For this reason, it is a good idea to make a
+marker point nowhere if you are sure you don't need it any more.
+Unreferenced markers are garbage collected eventually, but until then
+will continue to use time if they do point somewhere.
+
+   Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including `+' and `-')
+accept markers as arguments.  In such cases, the marker stands for its
+current position.
+
+   Note that you can use extents to achieve the same functionality, and
+more, as markers. (Markers were defined before extents, which is why
+they both continue to exist.) A zero-length extent with the
+`detachable' property removed is almost identical to a marker.  (*Note
+Extent Endpoints::, for more information on zero-length extents.)
+
+   In particular:
+
+   * In order to get marker-like behavior in a zero-length extent, the
+     `detachable' property must be removed (otherwise, the extent will
+     disappear when text near it is deleted) and exactly one endpoint
+     must be closed (if both endpoints are closed, the extent will
+     expand to contain text inserted where it is located).
+
+   * If a zero-length extent has the `end-open' property but not the
+     `start-open' property (this is the default), text inserted at the
+     extent's location causes the extent to move forward, just like a
+     marker.
+
+   * If a zero-length extent has the `start-open' property but not the
+     `end-open' property, text inserted at the extent's location causes
+     the extent to remain before the text, like what happens to markers
+     when `insert-before-markers' is used.
+
+   * Markers end up after or before inserted text depending on whether
+     `insert' or `insert-before-markers' was called.  These functions
+     do not affect zero-length extents differently; instead, the
+     presence or absence of the `start-open' and `end-open' extent
+     properties determines this, as just described.
+
+   * Markers are automatically removed from a buffer when they are no
+     longer in use.  Extents remain around until explicitly removed
+     from a buffer.
+
+   * Many functions are provided for listing the extents in a buffer or
+     in a region of a buffer.  No such functions exist for markers.
+
+   Here are examples of creating markers, setting markers, and moving
+point to markers:
+
+     ;; Make a new marker that initially does not point anywhere:
+     (setq m1 (make-marker))
+          => #<marker in no buffer>
+     
+     ;; Set `m1' to point between the 99th and 100th characters
+     ;;   in the current buffer:
+     (set-marker m1 100)
+          => #<marker at 100 in markers.texi>
+     
+     ;; Now insert one character at the beginning of the buffer:
+     (goto-char (point-min))
+          => 1
+     (insert "Q")
+          => nil
+     
+     ;; `m1' is updated appropriately.
+     m1
+          => #<marker at 101 in markers.texi>
+     
+     ;; Two markers that point to the same position
+     ;;   are not `eq', but they are `equal'.
+     (setq m2 (copy-marker m1))
+          => #<marker at 101 in markers.texi>
+     (eq m1 m2)
+          => nil
+     (equal m1 m2)
+          => t
+     
+     ;; When you are finished using a marker, make it point nowhere.
+     (set-marker m1 nil)
+          => #<marker in no buffer>
+
+\1f
+File: lispref.info,  Node: Predicates on Markers,  Next: Creating Markers,  Prev: Overview of Markers,  Up: Markers
+
+Predicates on Markers
+=====================
+
+You can test an object to see whether it is a marker, or whether it is
+either an integer or a marker or either an integer, a character, or a
+marker.  The latter tests are useful in connection with the arithmetic
+functions that work with any of markers, integers, or characters.
+
+ - Function: markerp object
+     This function returns `t' if OBJECT is a marker, `nil' otherwise.
+     Note that integers are not markers, even though many functions
+     will accept either a marker or an integer.
+
+ - Function: integer-or-marker-p object
+     This function returns `t' if OBJECT is an integer or a marker,
+     `nil' otherwise.
+
+ - Function: integer-char-or-marker-p object
+     This function returns `t' if OBJECT is an integer, a character, or
+     a marker, `nil' otherwise.
+
+ - Function: number-or-marker-p object
+     This function returns `t' if OBJECT is a number (either kind) or a
+     marker, `nil' otherwise.
+
+ - Function: number-char-or-marker-p object
+     This function returns `t' if OBJECT is a number (either kind), a
+     character, or a marker, `nil' otherwise.
+
+\1f
+File: lispref.info,  Node: Creating Markers,  Next: Information from Markers,  Prev: Predicates on Markers,  Up: Markers
+
+Functions That Create Markers
+=============================
+
+When you create a new marker, you can make it point nowhere, or point
+to the present position of point, or to the beginning or end of the
+accessible portion of the buffer, or to the same place as another given
+marker.
+
+ - Function: make-marker
+     This functions returns a newly created marker that does not point
+     anywhere.
+
+          (make-marker)
+               => #<marker in no buffer>
+
+ - Function: point-marker &optional dont-copy-p buffer
+     This function returns a marker that points to the present position
+     of point in BUFFER, which defaults to the current buffer.  *Note
+     Point::.  For an example, see `copy-marker', below.
+
+     Internally, a marker corresponding to point is always maintained.
+     Normally the marker returned by `point-marker' is a copy; you may
+     modify it with reckless abandon.  However, if optional argument
+     DONT-COPY-P is non-`nil', then the real point-marker is returned;
+     modifying the position of this marker will move point.  It is
+     illegal to change the buffer of it, or make it point nowhere.
+
+ - Function: point-min-marker &optional buffer
+     This function returns a new marker that points to the beginning of
+     the accessible portion of BUFFER, which defaults to the current
+     buffer.  This will be the beginning of the buffer unless narrowing
+     is in effect.  *Note Narrowing::.
+
+ - Function: point-max-marker &optional buffer
+     This function returns a new marker that points to the end of the
+     accessible portion of BUFFER, which defaults to the current
+     buffer.  This will be the end of the buffer unless narrowing is in
+     effect.  *Note Narrowing::.
+
+     Here are examples of this function and `point-min-marker', shown in
+     a buffer containing a version of the source file for the text of
+     this chapter.
+
+          (point-min-marker)
+               => #<marker at 1 in markers.texi>
+          (point-max-marker)
+               => #<marker at 15573 in markers.texi>
+          
+          (narrow-to-region 100 200)
+               => nil
+          (point-min-marker)
+               => #<marker at 100 in markers.texi>
+          (point-max-marker)
+               => #<marker at 200 in markers.texi>
+
+ - Function: copy-marker marker-or-integer &optional marker-type
+     If passed a marker as its argument, `copy-marker' returns a new
+     marker that points to the same place and the same buffer as does
+     MARKER-OR-INTEGER.  If passed an integer as its argument,
+     `copy-marker' returns a new marker that points to position
+     MARKER-OR-INTEGER in the current buffer.
+
+     If passed an integer argument less than 1, `copy-marker' returns a
+     new marker that points to the beginning of the current buffer.  If
+     passed an integer argument greater than the length of the buffer,
+     `copy-marker' returns a new marker that points to the end of the
+     buffer.
+
+     An error is signaled if MARKER-OR-INTEGER is neither a marker nor
+     an integer.
+
+     Optional second argument MARKER-TYPE specifies the insertion type
+     of the new marker; see `marker-insertion-type'.
+
+          (setq p (point-marker))
+               => #<marker at 2139 in markers.texi>
+          
+          (setq q (copy-marker p))
+               => #<marker at 2139 in markers.texi>
+          
+          (eq p q)
+               => nil
+          
+          (equal p q)

                => t
                => t

+          
+          (point)
+               => 2139
+          
+          (set-marker p 3000)
+               => #<marker at 3000 in markers.texi>
+          
+          (point)
+               => 2139
+          
+          (setq p (point-marker t))
+               => #<marker at 2139 in markers.texi>
+          
+          (set-marker p 3000)
+               => #<marker at 3000 in markers.texi>
+          
+          (point)
+               => 3000
+          
+          (copy-marker 0)
+               => #<marker at 1 in markers.texi>
+          
+          (copy-marker 20000)
+               => #<marker at 7572 in markers.texi>
+
+\1f
+File: lispref.info,  Node: Information from Markers,  Next: Changing Markers,  Prev: Creating Markers,  Up: Markers
+
+Information from Markers
+========================
+
+This section describes the functions for accessing the components of a
+marker object.
+
+ - Function: marker-position marker
+     This function returns the position that MARKER points to, or `nil'
+     if it points nowhere.
+
+ - Function: marker-buffer marker
+     This function returns the buffer that MARKER points into, or `nil'
+     if it points nowhere.
+
+          (setq m (make-marker))
+               => #<marker in no buffer>
+          (marker-position m)
+               => nil
+          (marker-buffer m)
+               => nil
+          
+          (set-marker m 3770 (current-buffer))
+               => #<marker at 3770 in markers.texi>
+          (marker-buffer m)
+               => #<buffer markers.texi>
+          (marker-position m)
+               => 3770
+
+   Two distinct markers are considered `equal' (even though not `eq')
+to each other if they have the same position and buffer, or if they
+both point nowhere.
+
+\1f
+File: lispref.info,  Node: Changing Markers,  Next: The Mark,  Prev: Information from Markers,  Up: Markers
+
+Changing Marker Positions
+=========================
+
+This section describes how to change the position of an existing
+marker.  When you do this, be sure you know whether the marker is used
+outside of your program, and, if so, what effects will result from
+moving it--otherwise, confusing things may happen in other parts of
+Emacs.
+
+ - Function: set-marker marker position &optional buffer
+     This function moves MARKER to POSITION in BUFFER.  If BUFFER is
+     not provided, it defaults to the current buffer.
+
+     POSITION can be a marker, an integer or `nil'.  If POSITION is an
+     integer, `set-marker' moves MARKER to point before the POSITIONth
+     character in BUFFER.  If POSITION is `nil', MARKER is made to
+     point nowhere.  Then it no longer slows down editing in any
+     buffer.  If POSITION is less than 1, MARKER is moved to the
+     beginning of BUFFER.  If POSITION is greater than the size of
+     BUFFER, MARKER is moved to the end of BUFFER.
+
+     The value returned is MARKER.
+
+          (setq m (point-marker))
+               => #<marker at 4714 in markers.texi>
+          (set-marker m 55)
+               => #<marker at 55 in markers.texi>
+          (setq b (get-buffer "foo"))
+               => #<buffer foo>
+          (set-marker m 0 b)
+               => #<marker at 1 in foo>
+
+ - Function: move-marker marker position &optional buffer
+     This is another name for `set-marker'.
+
+\1f
+File: lispref.info,  Node: The Mark,  Next: The Region,  Prev: Changing Markers,  Up: Markers
+
+The Mark
+========
+
+One special marker in each buffer is designated "the mark".  It records
+a position for the user for the sake of commands such as `C-w' and `C-x
+<TAB>'.  Lisp programs should set the mark only to values that have a
+potential use to the user, and never for their own internal purposes.
+For example, the `replace-regexp' command sets the mark to the value of
+point before doing any replacements, because this enables the user to
+move back there conveniently after the replace is finished.
+
+   Once the mark "exists" in a buffer, it normally never ceases to
+exist.  However, it may become "inactive", and usually does so after
+each command (other than simple motion commands and some commands that
+explicitly activate the mark).  When the mark is active, the region
+between point and the mark is called the "active region" and is
+highlighted specially.
+
+   Many commands are designed so that when called interactively they
+operate on the text between point and the mark.  Such commands work
+only when an active region exists, i.e. when the mark is active.  (The
+reason for this is to prevent you from accidentally deleting or
+changing large chunks of your text.) If you are writing such a command,
+don't examine the mark directly; instead, use `interactive' with the
+`r' specification.  This provides the values of point and the mark as
+arguments to the command in an interactive call, but permits other Lisp
+programs to specify arguments explicitly, and automatically signals an
+error if the command is called interactively when no active region
+exists.  *Note Interactive Codes::.
+
+   Each buffer has its own value of the mark that is independent of the
+value of the mark in other buffers. (When a buffer is created, the mark
+exists but does not point anywhere.  We consider this state as "the
+absence of a mark in that buffer.") However, only one active region can
+exist at a time.  Activating the mark in one buffer automatically
+deactivates an active mark in any other buffer.  Note that the user can
+explicitly activate a mark at any time by using the command
+`activate-region' (normally bound to `M-C-z') or by using the command
+`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
+side effect of activating the mark.
+
+   Some people do not like active regions, so they disable this behavior
+by setting the variable `zmacs-regions' to `nil'.  This makes the mark
+always active (except when a buffer is just created and the mark points
+nowhere), and turns off the highlighting of the region between point
+and the mark.  Commands that explicitly retrieve the value of the mark
+should make sure that they behave correctly and consistently
+irrespective of the setting of `zmacs-regions'; some primitives are
+provided to ensure this behavior.
+
+   In addition to the mark, each buffer has a "mark ring" which is a
+list of markers containing previous values of the mark.  When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring.  The variable `mark-ring-max' specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+ - Function: mark &optional force buffer
+     This function returns BUFFER's mark position as an integer.
+     BUFFER defaults to the current buffer if omitted.
+
+     If the mark is inactive, `mark' normally returns `nil'.  However,
+     if FORCE is non-`nil', then `mark' returns the mark position
+     anyway--or `nil', if the mark is not yet set for the buffer.
+
+     (Remember that if `zmacs-regions' is `nil', the mark is always
+     active as long as it exists, and the FORCE argument will have no
+     effect.)
+
+     If you are using this in an editing command, you are most likely
+     making a mistake; see the documentation of `set-mark' below.
+
+ - Function: mark-marker &optional force buffer
+     This function returns BUFFER's mark.  BUFFER defaults to the
+     current buffer if omitted.  This is the very marker that records
+     the mark location inside XEmacs, not a copy.  Therefore, changing
+     this marker's position will directly affect the position of the
+     mark.  Don't do it unless that is the effect you want.
+
+     If the mark is inactive, `mark-marker' normally returns `nil'.
+     However, if FORCE is non-`nil', then `mark-marker' returns the
+     mark anyway.
+          (setq m (mark-marker))
+               => #<marker at 3420 in markers.texi>
+          (set-marker m 100)
+               => #<marker at 100 in markers.texi>
+          (mark-marker)
+               => #<marker at 100 in markers.texi>
+
+     Like any marker, this marker can be set to point at any buffer you
+     like.  We don't recommend that you make it point at any buffer
+     other than the one of which it is the mark.  If you do, it will
+     yield perfectly consistent, but rather odd, results.
+
+ - Function: set-mark position &optional buffer
+     This function sets `buffer''s mark to POSITION, and activates the
+     mark.  BUFFER defaults to the current buffer if omitted.  The old
+     value of the mark is _not_ pushed onto the mark ring.
+
+     *Please note:* Use this function only if you want the user to see
+     that the mark has moved, and you want the previous mark position to
+     be lost.  Normally, when a new mark is set, the old one should go
+     on the `mark-ring'.  For this reason, most applications should use
+     `push-mark' and `pop-mark', not `set-mark'.
+
+     Novice XEmacs Lisp programmers often try to use the mark for the
+     wrong purposes.  The mark saves a location for the user's
+     convenience.  An editing command should not alter the mark unless
+     altering the mark is part of the user-level functionality of the
+     command.  (And, in that case, this effect should be documented.)
+     To remember a location for internal use in the Lisp program, store
+     it in a Lisp variable.  For example:
+
+          (let ((start (point)))
+            (forward-line 1)
+            (delete-region start (point))).
+
+ - Command: exchange-point-and-mark &optional dont-activate-region
+     This function exchanges the positions of point and the mark.  It
+     is intended for interactive use.  The mark is also activated
+     unless DONT-ACTIVATE-REGION is non-`nil'.
+
+ - Function: push-mark &optional position nomsg activate buffer
+     This function sets BUFFER's mark to POSITION, and pushes a copy of
+     the previous mark onto `mark-ring'.  BUFFER defaults to the
+     current buffer if omitted.  If POSITION is `nil', then the value
+     of point is used.  `push-mark' returns `nil'.
+
+     If the last global mark pushed was not in BUFFER, also push
+     POSITION on the global mark ring (see below).
+
+     The function `push-mark' normally _does not_ activate the mark.
+     To do that, specify `t' for the argument ACTIVATE.
+
+     A `Mark set' message is displayed unless NOMSG is non-`nil'.
+
+ - Function: pop-mark
+     This function pops off the top element of `mark-ring' and makes
+     that mark become the buffer's actual mark.  This does not move
+     point in the buffer, and it does nothing if `mark-ring' is empty.
+     It deactivates the mark.
+
+     The return value is not meaningful.
+
+ - Variable: mark-ring
+     The value of this buffer-local variable is the list of saved former
+     marks of the current buffer, most recent first.
+
+          mark-ring
+          => (#<marker at 11050 in markers.texi>
+              #<marker at 10832 in markers.texi>
+              ...)
+
+ - User Option: mark-ring-max
+     The value of this variable is the maximum size of `mark-ring'.  If
+     more marks than this are pushed onto the `mark-ring', `push-mark'
+     discards an old mark when it adds a new one.
+
+   In additional to a per-buffer mark ring, there is a "global mark
+ring".  Marks are pushed onto the global mark ring the first time you
+set a mark after switching buffers.
+
+ - Variable: global-mark-ring
+     The value of this variable is the list of saved former global
+     marks, most recent first.
+
+ - User Option: mark-ring-max
+     The value of this variable is the maximum size of
+     `global-mark-ring'.  If more marks than this are pushed onto the
+     `global-mark-ring', `push-mark' discards an old mark when it adds
+     a new one.
+
+ - Command: pop-global-mark
+     This function pops a mark off the global mark ring and jumps to
+     that location.
+
+\1f
+File: lispref.info,  Node: The Region,  Prev: The Mark,  Up: Markers
+
+The Region
+==========
+
+The text between point and the mark is known as "the region".  Various
+functions operate on text delimited by point and the mark, but only
+those functions specifically related to the region itself are described
+here.
+
+   When `zmacs-regions' is non-`nil' (this is the default), the concept
+of an "active region" exists.  The region is active when the
+corresponding mark is active.  Note that only one active region at a
+time can exist--i.e. only one buffer's region is active at a time.
+*Note The Mark::, for more information about active regions.
+
+ - User Option: zmacs-regions
+     If non-`nil' (the default), active regions are used.  *Note The
+     Mark::, for a detailed explanation of what this means.
+
+   A number of functions are provided for explicitly determining the
+bounds of the region and whether it is active.  Few programs need to use
+these functions, however.  A command designed to operate on a region
+should normally use `interactive' with the `r' specification to find
+the beginning and end of the region.  This lets other Lisp programs
+specify the bounds explicitly as arguments and automatically respects
+the user's setting for `zmacs-regions'.  (*Note Interactive Codes::.)
+
+ - Function: region-beginning &optional buffer
+     This function returns the position of the beginning of BUFFER's
+     region (as an integer).  This is the position of either point or
+     the mark, whichever is smaller.  BUFFER defaults to the current
+     buffer if omitted.
+
+     If the mark does not point anywhere, an error is signaled.  Note
+     that this function ignores whether the region is active.
+
+ - Function: region-end &optional buffer
+     This function returns the position of the end of BUFFER's region
+     (as an integer).  This is the position of either point or the mark,
+     whichever is larger.  BUFFER defaults to the current buffer if
+     omitted.
+
+     If the mark does not point anywhere, an error is signaled.  Note
+     that this function ignores whether the region is active.
+
+ - Function: region-exists-p
+     This function is non-`nil' if the region exists.  If active regions
+     are in use (i.e. `zmacs-regions' is true), this means that the
+     region is active.  Otherwise, this means that the user has pushed
+     a mark in this buffer at some point in the past.  If this function
+     returns `nil', a function that uses the `r' interactive
+     specification will cause an error when called interactively.
+
+ - Function: region-active-p
+     If `zmacs-regions' is true, this is equivalent to
+     `region-exists-p'.  Otherwise, this function always returns false.
+     This function is used by commands such as
+     `fill-paragraph-or-region' and `capitalize-region-or-word', which
+     operate either on the active region or on something else (e.g. the
+     word or paragraph at point).
+
+ - Variable: zmacs-region-stays
+     If a command sets this variable to true, the currently active
+     region will remain activated when the command finishes. (Normally
+     the region is deactivated when each command terminates.) If
+     `zmacs-regions' is false, however, this has no effect.  Under
+     normal circumstances, you do not need to set this; use the
+     interactive specification `_' instead, if you want the region to
+     remain active.
+
+ - Function: zmacs-activate-region
+     This function activates the region in the current buffer (this is
+     equivalent to activating the current buffer's mark).  This will
+     normally also highlight the text in the active region and set
+     `zmacs-region-stays' to `t'. (If `zmacs-regions' is false,
+     however, this function has no effect.)
+
+ - Function: zmacs-deactivate-region
+     This function deactivates the region in the current buffer (this is
+     equivalent to deactivating the current buffer's mark).  This will
+     normally also unhighlight the text in the active region and set
+     `zmacs-region-stays' to `nil'. (If `zmacs-regions' is false,
+     however, this function has no effect.)
+
+ - Function: zmacs-update-region
+     This function updates the active region, if it's currently active.
+     (If there is no active region, this function does nothing.) This
+     has the effect of updating the highlighting on the text in the
+     region; but you should never need to call this except under rather
+     strange circumstances.  The command loop automatically calls it
+     when appropriate.  Calling this function will call the hook
+     `zmacs-update-region-hook', if the region is active.
+
+ - Variable: zmacs-activate-region-hook
+     This normal hook is called when a region becomes active. (Usually
+     this happens as a result of a command that activates the region,
+     such as `set-mark-command', `activate-region', or
+     `exchange-point-and-mark'.) Note that calling
+     `zmacs-activate-region' will call this hook, even if the region is
+     already active.  If `zmacs-regions' is false, however, this hook
+     will never get called under any circumstances.
+
+ - Variable: zmacs-deactivate-region-hook
+     This normal hook is called when an active region becomes inactive.
+     (Calling `zmacs-deactivate-region' when the region is inactive will
+     _not_ cause this hook to be called.)  If `zmacs-regions' is false,
+     this hook will never get called.
+
+ - Variable: zmacs-update-region-hook
+     This normal hook is called when an active region is "updated" by
+     `zmacs-update-region'.  This normally gets called at the end of
+     each command that sets `zmacs-region-stays' to `t', indicating
+     that the region should remain activated.  The motion commands do
+     this.
+
+\1f
+File: lispref.info,  Node: Text,  Next: Searching and Matching,  Prev: Markers,  Up: Top
+
+Text
+****
+
+This chapter describes the functions that deal with the text in a
+buffer.  Most examine, insert, or delete text in the current buffer,
+often in the vicinity of point.  Many are interactive.  All the
+functions that change the text provide for undoing the changes (*note
+Undo::).
+
+   Many text-related functions operate on a region of text defined by
+two buffer positions passed in arguments named START and END.  These
+arguments should be either markers (*note Markers::) or numeric
+character positions (*note Positions::).  The order of these arguments
+does not matter; it is all right for START to be the end of the region
+and END the beginning.  For example, `(delete-region 1 10)' and
+`(delete-region 10 1)' are equivalent.  An `args-out-of-range' error is
+signaled if either START or END is outside the accessible portion of
+the buffer.  In an interactive call, point and the mark are used for
+these arguments.
+
+   Throughout this chapter, "text" refers to the characters in the
+buffer, together with their properties (when relevant).
+
+* Menu:
+
+* 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.
+* Transformations::  MD5 and base64 support.
+
+\1f
+File: lispref.info,  Node: Near Point,  Next: Buffer Contents,  Up: Text
+
+Examining Text Near Point
+=========================
+
+Many functions are provided to look at the characters around point.
+Several simple functions are described here.  See also `looking-at' in
+*Note Regexp Search::.
+
+   Many of these functions take an optional BUFFER argument.  In all
+such cases, the current buffer will be used if this argument is
+omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
+usually did not have these optional BUFFER arguments and always
+operated on the current buffer.)
+
+ - Function: char-after &optional position buffer
+     This function returns the character in the buffer at (i.e.,
+     immediately after) position POSITION.  If POSITION is out of range
+     for this purpose, either before the beginning of the buffer, or at
+     or beyond the end, then the value is `nil'.  The default for
+     POSITION is point.  If optional argument BUFFER is `nil', the
+     current buffer is assumed.
+
+     In the following example, assume that the first character in the
+     buffer is `@':
+
+          (char-to-string (char-after 1))
+               => "@"
+
+ - Function: char-before &optional position buffer
+     This function returns the character in the current buffer
+     immediately before position POSITION.  If POSITION is out of range
+     for this purpose, either at or before the beginning of the buffer,
+     or beyond the end, then the value is `nil'.  The default for
+     POSITION is point.  If optional argument BUFFER is `nil', the
+     current buffer is assumed.
+
+ - Function: following-char &optional buffer
+     This function returns the character following point in the buffer.
+     This is similar to `(char-after (point))'.  However, if point is at
+     the end of the buffer, then the result of `following-char' is 0.
+     If optional argument BUFFER is `nil', the current buffer is
+     assumed.
+
+     Remember that point is always between characters, and the terminal
+     cursor normally appears over the character following point.
+     Therefore, the character returned by `following-char' is the
+     character the cursor is over.
+
+     In this example, point is between the `a' and the `c'.
+
+          ---------- Buffer: foo ----------
+          Gentlemen may cry ``Pea-!-ce! Peace!,''
+          but there is no peace.
+          ---------- Buffer: foo ----------
+          
+          (char-to-string (preceding-char))
+               => "a"
+          (char-to-string (following-char))
+               => "c"
+
+ - Function: preceding-char &optional buffer
+     This function returns the character preceding point in the buffer.
+     See above, under `following-char', for an example.  If point is at
+     the beginning of the buffer, `preceding-char' returns 0.  If
+     optional argument BUFFER is `nil', the current buffer is assumed.
+
+ - Function: bobp &optional buffer
+     This function returns `t' if point is at the beginning of the
+     buffer.  If narrowing is in effect, this means the beginning of the
+     accessible portion of the text.  If optional argument BUFFER is
+     `nil', the current buffer is assumed.  See also `point-min' in
+     *Note Point::.
+
+ - Function: eobp &optional buffer
+     This function returns `t' if point is at the end of the buffer.
+     If narrowing is in effect, this means the end of accessible
+     portion of the text.  If optional argument BUFFER is `nil', the
+     current buffer is assumed.  See also `point-max' in *Note Point::.
+
+ - Function: bolp &optional buffer
+     This function returns `t' if point is at the beginning of a line.
+     If optional argument BUFFER is `nil', the current buffer is
+     assumed.  *Note Text Lines::.  The beginning of the buffer (or its
+     accessible portion) always counts as the beginning of a line.
+
+ - Function: eolp &optional buffer
+     This function returns `t' if point is at the end of a line.  The
+     end of the buffer is always considered the end of a line.  If
+     optional argument BUFFER is `nil', the current buffer is assumed.
+     The end of the buffer (or of its accessible portion) is always
+     considered the end of a line.
+
+\1f
+File: lispref.info,  Node: Buffer Contents,  Next: Comparing Text,  Prev: Near Point,  Up: Text
+
+Examining Buffer Contents
+=========================
+
+This section describes two functions that allow a Lisp program to
+convert any portion of the text in the buffer into a string.
+
+ - Function: buffer-substring start end &optional buffer
+ - Function: buffer-string start end &optional buffer
+     These functions are equivalent and return a string containing a
+     copy of the text of the region defined by positions START and END
+     in the buffer.  If the arguments are not positions in the
+     accessible portion of the buffer, `buffer-substring' signals an
+     `args-out-of-range' error.  If optional argument BUFFER is `nil',
+     the current buffer is assumed.
+
+     If the region delineated by START and END contains duplicable
+     extents, they will be remembered in the string.  *Note Duplicable
+     Extents::.
+
+     It is not necessary for START to be less than END; the arguments
+     can be given in either order.  But most often the smaller argument
+     is written first.
+
+          ---------- Buffer: foo ----------
+          This is the contents of buffer foo
+          
+          ---------- Buffer: foo ----------
+          
+          (buffer-substring 1 10)
+          => "This is t"
+          (buffer-substring (point-max) 10)
+          => "he contents of buffer foo
+          "
+
+\1f
+File: lispref.info,  Node: Comparing Text,  Next: Insertion,  Prev: Buffer Contents,  Up: Text
+
+Comparing Text
+==============
+
+This function lets you compare portions of the text in a buffer, without
+copying them into strings first.
+
+ - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
+          start2 end2
+     This function lets you compare two substrings of the same buffer
+     or two different buffers.  The first three arguments specify one
+     substring, giving a buffer and two positions within the buffer.
+     The last three arguments specify the other substring in the same
+     way.  You can use `nil' for BUFFER1, BUFFER2, or both to stand for
+     the current buffer.
+
+     The value is negative if the first substring is less, positive if
+     the first is greater, and zero if they are equal.  The absolute
+     value of the result is one plus the index of the first differing
+     characters within the substrings.
+
+     This function ignores case when comparing characters if
+     `case-fold-search' is non-`nil'.  It always ignores text
+     properties.
+
+     Suppose the current buffer contains the text `foobarbar
+     haha!rara!'; then in this example the two substrings are `rbar '
+     and `rara!'.  The value is 2 because the first substring is greater
+     at the second character.
+
+          (compare-buffer-substring nil 6 11 nil 16 21)
+               => 2
+
+\1f
+File: lispref.info,  Node: Insertion,  Next: Commands for Insertion,  Prev: Comparing Text,  Up: Text
+
+Inserting Text
+==============
+
+"Insertion" means adding new text to a buffer.  The inserted text goes
+at point--between the character before point and the character after
+point.
+
+   Insertion relocates markers that point at positions after the
+insertion point, so that they stay with the surrounding text (*note
+Markers::).  When a marker points at the place of insertion, insertion
+normally doesn't relocate the marker, so that it points to the
+beginning of the inserted text; however, certain special functions such
+as `insert-before-markers' relocate such markers to point after the
+inserted text.
+
+   Some insertion functions leave point before the inserted text, while
+other functions leave it after.  We call the former insertion "after
+point" and the latter insertion "before point".
+
+   If a string with non-`nil' extent data is inserted, the remembered
+extents will also be inserted.  *Note Duplicable Extents::.
+
+   Insertion functions signal an error if the current buffer is
+read-only.
+
+   These functions copy text characters from strings and buffers along
+with their properties.  The inserted characters have exactly the same
+properties as the characters they were copied from.  By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
+ - Function: insert &rest args
+     This function inserts the strings and/or characters ARGS into the
+     current buffer, at point, moving point forward.  In other words, it
+     inserts the text before point.  An error is signaled unless all
+     ARGS are either strings or characters.  The value is `nil'.
+
+ - Function: insert-before-markers &rest args
+     This function inserts the strings and/or characters ARGS into the
+     current buffer, at point, moving point forward.  An error is
+     signaled unless all ARGS are either strings or characters.  The
+     value is `nil'.
+
+     This function is unlike the other insertion functions in that it
+     relocates markers initially pointing at the insertion point, to
+     point after the inserted text.
+
+ - Function: insert-string string &optional buffer
+     This function inserts STRING into BUFFER before point.  BUFFER
+     defaults to the current buffer if omitted.  This function is
+     chiefly useful if you want to insert a string in a buffer other
+     than the current one (otherwise you could just use `insert').
+
+ - Function: insert-char character &optional count ignored buffer
+     This function inserts COUNT instances of CHARACTER into BUFFER
+     before point.  COUNT must be a number, and CHARACTER must be a
+     character.
+
+     If optional argument BUFFER is `nil', the current buffer is
+     assumed. (In FSF Emacs, the third argument is called INHERIT and
+     refers to text properties.  In XEmacs, it is always ignored.)
+
+     This function always returns `nil'.
+
+ - Function: insert-buffer-substring from-buffer-or-name &optional
+          start end
+     This function inserts a portion of buffer FROM-BUFFER-OR-NAME
+     (which must already exist) into the current buffer before point.
+     The text inserted is the region from START and END.  (These
+     arguments default to the beginning and end of the accessible
+     portion of that buffer.)  This function returns `nil'.
+
+     In this example, the form is executed with buffer `bar' as the
+     current buffer.  We assume that buffer `bar' is initially empty.
+
+          ---------- Buffer: foo ----------
+          We hold these truths to be self-evident, that all
+          ---------- Buffer: foo ----------
+          
+          (insert-buffer-substring "foo" 1 20)
+               => nil
+          
+          ---------- Buffer: bar ----------
+          We hold these truth-!-
+          ---------- Buffer: bar ----------
+
+\1f
+File: lispref.info,  Node: Commands for Insertion,  Next: Deletion,  Prev: Insertion,  Up: Text
+
+User-Level Insertion Commands
+=============================
+
+This section describes higher-level commands for inserting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
+
+ - Command: insert-buffer from-buffer-or-name
+     This command inserts the entire contents of FROM-BUFFER-OR-NAME
+     (which must exist) into the current buffer after point.  It leaves
+     the mark after the inserted text.  The value is `nil'.
+
+ - Command: self-insert-command count
+     This command inserts the last character typed; it does so COUNT
+     times, before point, and returns `nil'.  Most printing characters
+     are bound to this command.  In routine use, `self-insert-command'
+     is the most frequently called function in XEmacs, but programs
+     rarely use it except to install it on a keymap.
+
+     In an interactive call, COUNT is the numeric prefix argument.
+
+     This command calls `auto-fill-function' whenever that is non-`nil'
+     and the character inserted is a space or a newline (*note Auto
+     Filling::).
+
+     This command performs abbrev expansion if Abbrev mode is enabled
+     and the inserted character does not have word-constituent syntax.
+     (*Note Abbrevs::, and *Note Syntax Class Table::.)
+
+     This is also responsible for calling `blink-paren-function' when
+     the inserted character has close parenthesis syntax (*note
+     Blinking::).
+
+ - Command: newline &optional count
+     This command inserts newlines into the current buffer before point.
+     If COUNT is supplied, that many newline characters are inserted.
+
+     This function calls `auto-fill-function' if the current column
+     number is greater than the value of `fill-column' and COUNT is
+     `nil'.  Typically what `auto-fill-function' does is insert a
+     newline; thus, the overall result in this case is to insert two
+     newlines at different places: one at point, and another earlier in
+     the line.  `newline' does not auto-fill if COUNT is non-`nil'.
+
+     This command indents to the left margin if that is not zero.
+     *Note Margins::.
+
+     The value returned is `nil'.  In an interactive call, COUNT is the
+     numeric prefix argument.
+
+ - Command: split-line
+     This command splits the current line, moving the portion of the
+     line after point down vertically so that it is on the next line
+     directly below where it was before.  Whitespace is inserted as
+     needed at the beginning of the lower line, using the `indent-to'
+     function.  `split-line' returns the position of point.
+
+     Programs hardly ever use this function.
+
+ - Variable: overwrite-mode
+     This variable controls whether overwrite mode is in effect: a
+     non-`nil' value enables the mode.  It is automatically made
+     buffer-local when set in any fashion.
+
+\1f
+File: lispref.info,  Node: Deletion,  Next: User-Level Deletion,  Prev: Commands for Insertion,  Up: Text
+
+Deleting Text
+=============
+
+Deletion means removing part of the text in a buffer, without saving it
+in the kill ring (*note The Kill Ring::).  Deleted text can't be
+yanked, but can be reinserted using the undo mechanism (*note Undo::).
+Some deletion functions do save text in the kill ring in some special
+cases.
+
+   All of the deletion functions operate on the current buffer, and all
+return a value of `nil'.
+
+ - Command: erase-buffer &optional buffer
+     This function deletes the entire text of BUFFER, leaving it empty.
+     If the buffer is read-only, it signals a `buffer-read-only'
+     error.  Otherwise, it deletes the text without asking for any
+     confirmation.  It returns `nil'.  BUFFER defaults to the current
+     buffer if omitted.
+
+     Normally, deleting a large amount of text from a buffer inhibits
+     further auto-saving of that buffer "because it has shrunk".
+     However, `erase-buffer' does not do this, the idea being that the
+     future text is not really related to the former text, and its size
+     should not be compared with that of the former text.
+
+ - Command: delete-region start end &optional buffer
+     This command deletes the text in BUFFER in the region defined by
+     START and END.  The value is `nil'.  If optional argument BUFFER
+     is `nil', the current buffer is assumed.
+
+ - Command: delete-char &optional count killp
+     This command deletes COUNT characters directly after point, or
+     before point if COUNT is negative.  COUNT defaults to `1'.  If
+     KILLP is non-`nil', then it saves the deleted characters in the
+     kill ring.
+
+     In an interactive call, COUNT is the numeric prefix argument, and
+     KILLP is the unprocessed prefix argument.  Therefore, if a prefix
+     argument is supplied, the text is saved in the kill ring.  If no
+     prefix argument is supplied, then one character is deleted, but
+     not saved in the kill ring.
+
+     The value returned is always `nil'.
+
+ - Command: delete-backward-char &optional count killp
+     This command deletes COUNT characters directly before point, or
+     after point if COUNT is negative.  COUNT defaults to 1.  If KILLP
+     is non-`nil', then it saves the deleted characters in the kill
+     ring.
+
+     In an interactive call, COUNT is the numeric prefix argument, and
+     KILLP is the unprocessed prefix argument.  Therefore, if a prefix
+     argument is supplied, the text is saved in the kill ring.  If no
+     prefix argument is supplied, then one character is deleted, but
+     not saved in the kill ring.
+
+     The value returned is always `nil'.
+
+ - Command: backward-delete-char-untabify count &optional killp
+     This command deletes COUNT characters backward, changing tabs into
+     spaces.  When the next character to be deleted is a tab, it is
+     first replaced with the proper number of spaces to preserve
+     alignment and then one of those spaces is deleted instead of the
+     tab.  If KILLP is non-`nil', then the command saves the deleted
+     characters in the kill ring.
+
+     Conversion of tabs to spaces happens only if COUNT is positive.
+     If it is negative, exactly -COUNT characters after point are
+     deleted.
+
+     In an interactive call, COUNT is the numeric prefix argument, and
+     KILLP is the unprocessed prefix argument.  Therefore, if a prefix
+     argument is supplied, the text is saved in the kill ring.  If no
+     prefix argument is supplied, then one character is deleted, but
+     not saved in the kill ring.
+
+     The value returned is always `nil'.
+
+\1f
+File: lispref.info,  Node: User-Level Deletion,  Next: The Kill Ring,  Prev: Deletion,  Up: Text
+
+User-Level Deletion Commands
+============================
+
+This section describes higher-level commands for deleting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
+
+ - Command: delete-horizontal-space
+     This function deletes all spaces and tabs around point.  It returns
+     `nil'.
+
+     In the following examples, we call `delete-horizontal-space' four
+     times, once on each line, with point between the second and third
+     characters on the line each time.
+
+          ---------- Buffer: foo ----------
+          I -!-thought
+          I -!-     thought
+          We-!- thought
+          Yo-!-u thought
+          ---------- Buffer: foo ----------
+          
+          (delete-horizontal-space)   ; Four times.
+               => nil
+          
+          ---------- Buffer: foo ----------
+          Ithought
+          Ithought
+          Wethought
+          You thought
+          ---------- Buffer: foo ----------
+
+ - Command: delete-indentation &optional join-following-p
+     This function joins the line point is on to the previous line,
+     deleting any whitespace at the join and in some cases replacing it
+     with one space.  If JOIN-FOLLOWING-P is non-`nil',
+     `delete-indentation' joins this line to the following line
+     instead.  The value is `nil'.
+
+     If there is a fill prefix, and the second of the lines being joined
+     starts with the prefix, then `delete-indentation' deletes the fill
+     prefix before joining the lines.  *Note Margins::.
+
+     In the example below, point is located on the line starting
+     `events', and it makes no difference if there are trailing spaces
+     in the preceding line.
+
+          ---------- Buffer: foo ----------
+          When in the course of human
+          -!-    events, it becomes necessary
+          ---------- Buffer: foo ----------
+          
+          (delete-indentation)
+               => nil
+          
+          ---------- Buffer: foo ----------
+          When in the course of human-!- events, it becomes necessary
+          ---------- Buffer: foo ----------
+
+     After the lines are joined, the function `fixup-whitespace' is
+     responsible for deciding whether to leave a space at the junction.
+
+ - Command: fixup-whitespace
+     This function replaces all the white space surrounding point with
+     either one space or no space, according to the context.  It
+     returns `nil'.
+
+     At the beginning or end of a line, the appropriate amount of space
+     is none.  Before a character with close parenthesis syntax, or
+     after a character with open parenthesis or expression-prefix
+     syntax, no space is also appropriate.  Otherwise, one space is
+     appropriate.  *Note Syntax Class Table::.
+
+     In the example below, `fixup-whitespace' is called the first time
+     with point before the word `spaces' in the first line.  For the
+     second invocation, point is directly after the `('.
+
+          ---------- Buffer: foo ----------
+          This has too many     -!-spaces
+          This has too many spaces at the start of (-!-   this list)
+          ---------- Buffer: foo ----------
+          
+          (fixup-whitespace)
+               => nil
+          (fixup-whitespace)
+               => nil
+          
+          ---------- Buffer: foo ----------
+          This has too many spaces
+          This has too many spaces at the start of (this list)
+          ---------- Buffer: foo ----------
+
+ - Command: just-one-space
+     This command replaces any spaces and tabs around point with a
+     single space.  It returns `nil'.
+
+ - Command: delete-blank-lines
+     This function deletes blank lines surrounding point.  If point is
+     on a blank line with one or more blank lines before or after it,
+     then all but one of them are deleted.  If point is on an isolated
+     blank line, then it is deleted.  If point is on a nonblank line,
+     the command deletes all blank lines following it.
+
+     A blank line is defined as a line containing only tabs and spaces.
+
+     `delete-blank-lines' returns `nil'.
+
+\1f
+File: lispref.info,  Node: The Kill Ring,  Next: Undo,  Prev: User-Level Deletion,  Up: Text
+
+The Kill Ring
+=============
+
+"Kill" functions delete text like the deletion functions, but save it
+so that the user can reinsert it by "yanking".  Most of these functions
+have `kill-' in their name.  By contrast, the functions whose names
+start with `delete-' normally do not save text for yanking (though they
+can still be undone); these are "deletion" functions.
+
+   Most of the kill commands are primarily for interactive use, and are
+not described here.  What we do describe are the functions provided for
+use in writing such commands.  You can use these functions to write
+commands for killing text.  When you need to delete text for internal
+purposes within a Lisp function, you should normally use deletion
+functions, so as not to disturb the kill ring contents.  *Note
+Deletion::.
+
+   Killed text is saved for later yanking in the "kill ring".  This is
+a list that holds a number of recent kills, not just the last text
+kill.  We call this a "ring" because yanking treats it as having
+elements in a cyclic order.  The list is kept in the variable
+`kill-ring', and can be operated on with the usual functions for lists;
+there are also specialized functions, described in this section, that
+treat it as a ring.
+
+   Some people think this use of the word "kill" is unfortunate, since
+it refers to operations that specifically _do not_ destroy the entities
+"killed".  This is in sharp contrast to ordinary life, in which death
+is permanent and "killed" entities do not come back to life.
+Therefore, other metaphors have been proposed.  For example, the term
+"cut ring" makes sense to people who, in pre-computer days, used
+scissors and paste to cut up and rearrange manuscripts.  However, it
+would be difficult to change the terminology now.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Kill Ring Concepts,  Next: Kill Functions,  Up: The Kill Ring
+
+Kill Ring Concepts
+------------------
+
+The kill ring records killed text as strings in a list, most recent
+first.  A short kill ring, for example, might look like this:
+
+     ("some text" "a different piece of text" "even older text")
+
+When the list reaches `kill-ring-max' entries in length, adding a new
+entry automatically deletes the last entry.
+
+   When kill commands are interwoven with other commands, each kill
+command makes a new entry in the kill ring.  Multiple kill commands in
+succession build up a single entry in the kill ring, which would be
+yanked as a unit; the second and subsequent consecutive kill commands
+add text to the entry made by the first one.
+
+   For yanking, one entry in the kill ring is designated the "front" of
+the ring.  Some yank commands "rotate" the ring by designating a
+different element as the "front."  But this virtual rotation doesn't
+change the list itself--the most recent entry always comes first in the
+list.
+
+\1f
+File: lispref.info,  Node: Kill Functions,  Next: Yank Commands,  Prev: Kill Ring Concepts,  Up: The Kill Ring
+
+Functions for Killing
+---------------------
+
+`kill-region' is the usual subroutine for killing text.  Any command
+that calls this function is a "kill command" (and should probably have
+`kill' in its name).  `kill-region' puts the newly killed text in a new
+element at the beginning of the kill ring or adds it to the most recent
+element.  It uses the `last-command' variable to determine whether the
+previous command was a kill command, and if so appends the killed text
+to the most recent entry.
+
+ - Command: kill-region start end &optional verbose
+     This function kills the text in the region defined by START and
+     END.  The text is deleted but saved in the kill ring, along with
+     its text properties.  The value is always `nil'.
+
+     In an interactive call, START and END are point and the mark.
+
+     If the buffer is read-only, `kill-region' modifies the kill ring
+     just the same, then signals an error without modifying the buffer.
+     This is convenient because it lets the user use all the kill
+     commands to copy text into the kill ring from a read-only buffer.
+
+ - Command: copy-region-as-kill start end
+     This command saves the region defined by START and END on the kill
+     ring (including text properties), but does not delete the text
+     from the buffer.  It returns `nil'.  It also indicates the extent
+     of the text copied by moving the cursor momentarily, or by
+     displaying a message in the echo area.
+
+     The command does not set `this-command' to `kill-region', so a
+     subsequent kill command does not append to the same kill ring
+     entry.
+
+     Don't call `copy-region-as-kill' in Lisp programs unless you aim to
+     support Emacs 18.  For Emacs 19, it is better to use `kill-new' or
+     `kill-append' instead.  *Note Low-Level Kill Ring::.
+
+\1f
+File: lispref.info,  Node: Yank Commands,  Next: Low-Level Kill Ring,  Prev: Kill Functions,  Up: The Kill Ring
+
+Functions for Yanking
+---------------------
+
+"Yanking" means reinserting an entry of previously killed text from the
+kill ring.  The text properties are copied too.
+
+ - Command: yank &optional arg
+     This command inserts before point the text in the first entry in
+     the kill ring.  It positions the mark at the beginning of that
+     text, and point at the end.
+
+     If ARG is a list (which occurs interactively when the user types
+     `C-u' with no digits), then `yank' inserts the text as described
+     above, but puts point before the yanked text and puts the mark
+     after it.
+
+     If ARG is a number, then `yank' inserts the ARGth most recently
+     killed text--the ARGth element of the kill ring list.
+
+     `yank' does not alter the contents of the kill ring or rotate it.
+     It returns `nil'.
+
+ - Command: yank-pop arg
+     This command replaces the just-yanked entry from the kill ring
+     with a different entry from the kill ring.
+
+     This is allowed only immediately after a `yank' or another
+     `yank-pop'.  At such a time, the region contains text that was just
+     inserted by yanking.  `yank-pop' deletes that text and inserts in
+     its place a different piece of killed text.  It does not add the
+     deleted text to the kill ring, since it is already in the kill
+     ring somewhere.
+
+     If ARG is `nil', then the replacement text is the previous element
+     of the kill ring.  If ARG is numeric, the replacement is the ARGth
+     previous kill.  If ARG is negative, a more recent kill is the
+     replacement.
+
+     The sequence of kills in the kill ring wraps around, so that after
+     the oldest one comes the newest one, and before the newest one
+     goes the oldest.
+
+     The value is always `nil'.
+
+\1f
+File: lispref.info,  Node: Low-Level Kill Ring,  Next: Internals of Kill Ring,  Prev: Yank Commands,  Up: The Kill Ring
+
+Low-Level Kill Ring
+-------------------
+
+These functions and variables provide access to the kill ring at a lower
+level, but still convenient for use in Lisp programs.  They take care of
+interaction with X Window selections.  They do not exist in Emacs
+version 18.
+
+ - Function: current-kill count &optional do-not-move
+     The function `current-kill' rotates the yanking pointer which
+     designates the "front" of the kill ring by COUNT places (from newer
+     kills to older ones), and returns the text at that place in the
+     ring.
+
+     If the optional second argument DO-NOT-MOVE is non-`nil', then
+     `current-kill' doesn't alter the yanking pointer; it just returns
+     the COUNTth kill, counting from the current yanking pointer.
+
+     If COUNT is zero, indicating a request for the latest kill,
+     `current-kill' calls the value of `interprogram-paste-function'
+     (documented below) before consulting the kill ring.
+
+ - Function: kill-new string &optional replace
+     This function makes the text STRING the latest entry in the kill
+     ring, and sets `kill-ring-yank-pointer' to point to it.
+
+     Normally, STRING is added to the front of the kill ring as a new
+     entry.  However, if optional argument REPLACE is non-`nil', the
+     entry previously at the front of the kill ring is discarded, and
+     STRING replaces it.
+
+     This function runs the functions on `kill-hooks', and also invokes
+     the value of `interprogram-cut-function' (see below).
+
+ - Function: kill-append string before-p
+     This function appends the text STRING to the first entry in the
+     kill ring.  Normally STRING goes at the end of the entry, but if
+     BEFORE-P is non-`nil', it goes at the beginning.  This function
+     also invokes the value of `interprogram-cut-function' (see below).
+
+ - Variable: interprogram-paste-function
+     This variable provides a way of transferring killed text from other
+     programs, when you are using a window system.  Its value should be
+     `nil' or a function of no arguments.
+
+     If the value is a function, `current-kill' calls it to get the
+     "most recent kill".  If the function returns a non-`nil' value,
+     then that value is used as the "most recent kill".  If it returns
+     `nil', then the first element of `kill-ring' is used.
+
+     The normal use of this hook is to get the X server's primary
+     selection as the most recent kill, even if the selection belongs
+     to another X client.  *Note X Selections::.
+
+ - Variable: interprogram-cut-function
+     This variable provides a way of communicating killed text to other
+     programs, when you are using a window system.  Its value should be
+     `nil' or a function of one argument.
+
+     If the value is a function, `kill-new' and `kill-append' call it
+     with the new first element of the kill ring as an argument.
+
+     The normal use of this hook is to set the X server's primary
+     selection to the newly killed text.
+
+\1f
+File: lispref.info,  Node: Internals of Kill Ring,  Prev: Low-Level Kill Ring,  Up: The Kill Ring
+
+Internals of the Kill Ring
+--------------------------
+
+The variable `kill-ring' holds the kill ring contents, in the form of a
+list of strings.  The most recent kill is always at the front of the
+list.
+
+   The `kill-ring-yank-pointer' variable points to a link in the kill
+ring list, whose CAR is the text to yank next.  We say it identifies
+the "front" of the ring.  Moving `kill-ring-yank-pointer' to a
+different link is called "rotating the kill ring".  We call the kill
+ring a "ring" because the functions that move the yank pointer wrap
+around from the end of the list to the beginning, or vice-versa.
+Rotation of the kill ring is virtual; it does not change the value of
+`kill-ring'.
+
+   Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
+whose values are normally lists.  The word "pointer" in the name of the
+`kill-ring-yank-pointer' indicates that the variable's purpose is to
+identify one element of the list for use by the next yank command.
+
+   The value of `kill-ring-yank-pointer' is always `eq' to one of the
+links in the kill ring list.  The element it identifies is the CAR of
+that link.  Kill commands, which change the kill ring, also set this
+variable to the value of `kill-ring'.  The effect is to rotate the ring
+so that the newly killed text is at the front.
+
+   Here is a diagram that shows the variable `kill-ring-yank-pointer'
+pointing to the second entry in the kill ring `("some text" "a
+different piece of text" "yet older text")'.
+
+     kill-ring       kill-ring-yank-pointer
+       |               |
+       |     ___ ___    --->  ___ ___      ___ ___
+        --> |___|___|------> |___|___|--> |___|___|--> nil
+              |                |            |
+              |                |            |
+              |                |             -->"yet older text"
+              |                |
+              |                 --> "a different piece of text"
+              |
+               --> "some text"
+
+This state of affairs might occur after `C-y' (`yank') immediately
+followed by `M-y' (`yank-pop').
+
+ - Variable: kill-ring
+     This variable holds the list of killed text sequences, most
+     recently killed first.
+
+ - Variable: kill-ring-yank-pointer
+     This variable's value indicates which element of the kill ring is
+     at the "front" of the ring for yanking.  More precisely, the value
+     is a tail of the value of `kill-ring', and its CAR is the kill
+     string that `C-y' should yank.
+
+ - User Option: kill-ring-max
+     The value of this variable is the maximum length to which the kill
+     ring can grow, before elements are thrown away at the end.  The
+     default value for `kill-ring-max' is 30.
+
+\1f
+File: lispref.info,  Node: Undo,  Next: Maintaining Undo,  Prev: The Kill Ring,  Up: Text
+
+Undo
+====
+
+Most buffers have an "undo list", which records all changes made to the
+buffer's text so that they can be undone.  (The buffers that don't have
+one are usually special-purpose buffers for which XEmacs assumes that
+undoing is not useful.)  All the primitives that modify the text in the
+buffer automatically add elements to the front of the undo list, which
+is in the variable `buffer-undo-list'.
+
+ - Variable: buffer-undo-list
+     This variable's value is the undo list of the current buffer.  A
+     value of `t' disables the recording of undo information.
+
+   Here are the kinds of elements an undo list can have:
+
+`INTEGER'
+     This kind of element records a previous value of point.  Ordinary
+     cursor motion does not get any sort of undo record, but deletion
+     commands use these entries to record where point was before the
+     command.
+
+`(START . END)'
+     This kind of element indicates how to delete text that was
+     inserted.  Upon insertion, the text occupied the range START-END
+     in the buffer.
+
+`(TEXT . POSITION)'
+     This kind of element indicates how to reinsert text that was
+     deleted.  The deleted text itself is the string TEXT.  The place to
+     reinsert it is `(abs POSITION)'.
+
+`(t HIGH . LOW)'
+     This kind of element indicates that an unmodified buffer became
+     modified.  The elements HIGH and LOW are two integers, each
+     recording 16 bits of the visited file's modification time as of
+     when it was previously visited or saved.  `primitive-undo' uses
+     those values to determine whether to mark the buffer as unmodified
+     once again; it does so only if the file's modification time
+     matches those numbers.
+
+`(nil PROPERTY VALUE START . END)'
+     This kind of element records a change in a text property.  Here's
+     how you might undo the change:
+
+          (put-text-property START END PROPERTY VALUE)
+
+`POSITION'
+     This element indicates where point was at an earlier time.
+     Undoing this element sets point to POSITION.  Deletion normally
+     creates an element of this kind as well as a reinsertion element.
+
+`nil'
+     This element is a boundary.  The elements between two boundaries
+     are called a "change group"; normally, each change group
+     corresponds to one keyboard command, and undo commands normally
+     undo an entire group as a unit.
+
+ - Function: undo-boundary
+     This function places a boundary element in the undo list.  The undo
+     command stops at such a boundary, and successive undo commands undo
+     to earlier and earlier boundaries.  This function returns `nil'.
+
+     The editor command loop automatically creates an undo boundary
+     before each key sequence is executed.  Thus, each undo normally
+     undoes the effects of one command.  Self-inserting input
+     characters are an exception.  The command loop makes a boundary
+     for the first such character; the next 19 consecutive
+     self-inserting input characters do not make boundaries, and then
+     the 20th does, and so on as long as self-inserting characters
+     continue.
+
+     All buffer modifications add a boundary whenever the previous
+     undoable change was made in some other buffer.  This way, a
+     command that modifies several buffers makes a boundary in each
+     buffer it changes.
+
+     Calling this function explicitly is useful for splitting the
+     effects of a command into more than one unit.  For example,
+     `query-replace' calls `undo-boundary' after each replacement, so
+     that the user can undo individual replacements one by one.
+
+ - Function: primitive-undo count list
+     This is the basic function for undoing elements of an undo list.
+     It undoes the first COUNT elements of LIST, returning the rest of
+     LIST.  You could write this function in Lisp, but it is convenient
+     to have it in C.
+
+     `primitive-undo' adds elements to the buffer's undo list when it
+     changes the buffer.  Undo commands avoid confusion by saving the
+     undo list value at the beginning of a sequence of undo operations.
+     Then the undo operations use and update the saved value.  The new
+     elements added by undoing are not part of this saved value, so
+     they don't interfere with continuing to undo.

 
 

diff --git a/info/lispref.info-6 b/info/lispref.info-6
index 4273b1d..ed9d846 100644 (file)
--- a/info/lispref.info-6
+++ b/info/lispref.info-6
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1289 +50,6813 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: List Elements,  Next: Building Lists,  Prev: List-related Predicates,  Up: Lists
+File: lispref.info,  Node: Maintaining Undo,  Next: Filling,  Prev: Undo,  Up: Text
+
+Maintaining Undo Lists
+======================
+
+This section describes how to enable and disable undo information for a
+given buffer.  It also explains how the undo list is truncated
+automatically so it doesn't get too big.
+
+   Recording of undo information in a newly created buffer is normally
+enabled to start with; but if the buffer name starts with a space, the
+undo recording is initially disabled.  You can explicitly enable or
+disable undo recording with the following two functions, or by setting
+`buffer-undo-list' yourself.
+
+ - Command: buffer-enable-undo &optional buffer-or-name
+     This command enables recording undo information for buffer
+     BUFFER-OR-NAME, so that subsequent changes can be undone.  If no
+     argument is supplied, then the current buffer is used.  This
+     function does nothing if undo recording is already enabled in the
+     buffer.  It returns `nil'.
+
+     In an interactive call, BUFFER-OR-NAME is the current buffer.  You
+     cannot specify any other buffer.
+
+ - Command: buffer-disable-undo &optional buffer
+ - Command: buffer-flush-undo &optional buffer
+     This function discards the undo list of BUFFER, and disables
+     further recording of undo information.  As a result, it is no
+     longer possible to undo either previous changes or any subsequent
+     changes.  If the undo list of BUFFER is already disabled, this
+     function has no effect.
+
+     This function returns `nil'.  It cannot be called interactively.
+
+     The name `buffer-flush-undo' is not considered obsolete, but the
+     preferred name `buffer-disable-undo' is new as of Emacs versions
+     19.
+
+   As editing continues, undo lists get longer and longer.  To prevent
+them from using up all available memory space, garbage collection trims
+them back to size limits you can set.  (For this purpose, the "size" of
+an undo list measures the cons cells that make up the list, plus the
+strings of deleted text.)  Two variables control the range of acceptable
+sizes: `undo-limit' and `undo-strong-limit'.
+
+ - Variable: undo-limit
+     This is the soft limit for the acceptable size of an undo list.
+     The change group at which this size is exceeded is the last one
+     kept.
+
+ - Variable: undo-strong-limit
+     This is the upper limit for the acceptable size of an undo list.
+     The change group at which this size is exceeded is discarded
+     itself (along with all older change groups).  There is one
+     exception: the very latest change group is never discarded no
+     matter how big it is.

 
 

-Accessing Elements of Lists
-===========================
+\1f
+File: lispref.info,  Node: Filling,  Next: Margins,  Prev: Maintaining Undo,  Up: Text
+
+Filling
+=======
+
+"Filling" means adjusting the lengths of lines (by moving the line
+breaks) so that they are nearly (but no greater than) a specified
+maximum width.  Additionally, lines can be "justified", which means
+inserting spaces to make the left and/or right margins line up
+precisely.  The width is controlled by the variable `fill-column'.  For
+ease of reading, lines should be no longer than 70 or so columns.
+
+   You can use Auto Fill mode (*note Auto Filling::) to fill text
+automatically as you insert it, but changes to existing text may leave
+it improperly filled.  Then you must fill the text explicitly.
+
+   Most of the commands in this section return values that are not
+meaningful.  All the functions that do filling take note of the current
+left margin, current right margin, and current justification style
+(*note Margins::).  If the current justification style is `none', the
+filling functions don't actually do anything.
+
+   Several of the filling functions have an argument JUSTIFY.  If it is
+non-`nil', that requests some kind of justification.  It can be `left',
+`right', `full', or `center', to request a specific style of
+justification.  If it is `t', that means to use the current
+justification style for this part of the text (see
+`current-justification', below).
+
+   When you call the filling functions interactively, using a prefix
+argument implies the value `full' for JUSTIFY.
+
+ - Command: fill-paragraph justify
+     This command fills the paragraph at or after point.  If JUSTIFY is
+     non-`nil', each line is justified as well.  It uses the ordinary
+     paragraph motion commands to find paragraph boundaries.  *Note
+     Paragraphs: (xemacs)Paragraphs.
+
+ - Command: fill-region start end &optional justify
+     This command fills each of the paragraphs in the region from START
+     to END.  It justifies as well if JUSTIFY is non-`nil'.
+
+     The variable `paragraph-separate' controls how to distinguish
+     paragraphs.  *Note Standard Regexps::.
+
+ - Command: fill-individual-paragraphs start end &optional justify
+          mail-flag
+     This command fills each paragraph in the region according to its
+     individual fill prefix.  Thus, if the lines of a paragraph were
+     indented with spaces, the filled paragraph will remain indented in
+     the same fashion.
+
+     The first two arguments, START and END, are the beginning and end
+     of the region to be filled.  The third and fourth arguments,
+     JUSTIFY and MAIL-FLAG, are optional.  If JUSTIFY is non-`nil', the
+     paragraphs are justified as well as filled.  If MAIL-FLAG is
+     non-`nil', it means the function is operating on a mail message
+     and therefore should not fill the header lines.
+
+     Ordinarily, `fill-individual-paragraphs' regards each change in
+     indentation as starting a new paragraph.  If
+     `fill-individual-varying-indent' is non-`nil', then only separator
+     lines separate paragraphs.  That mode can handle indented
+     paragraphs with additional indentation on the first line.
+
+ - User Option: fill-individual-varying-indent
+     This variable alters the action of `fill-individual-paragraphs' as
+     described above.
+
+ - Command: fill-region-as-paragraph start end &optional justify
+     This command considers a region of text as a paragraph and fills
+     it.  If the region was made up of many paragraphs, the blank lines
+     between paragraphs are removed.  This function justifies as well
+     as filling when JUSTIFY is non-`nil'.
+
+     In an interactive call, any prefix argument requests justification.
+
+     In Adaptive Fill mode, which is enabled by default,
+     `fill-region-as-paragraph' on an indented paragraph when there is
+     no fill prefix uses the indentation of the second line of the
+     paragraph as the fill prefix.
+
+ - Command: justify-current-line how eop nosqueeze
+     This command inserts spaces between the words of the current line
+     so that the line ends exactly at `fill-column'.  It returns `nil'.
+
+     The argument HOW, if non-`nil' specifies explicitly the style of
+     justification.  It can be `left', `right', `full', `center', or
+     `none'.  If it is `t', that means to do follow specified
+     justification style (see `current-justification', below).  `nil'
+     means to do full justification.
+
+     If EOP is non-`nil', that means do left-justification when
+     `current-justification' specifies full justification.  This is used
+     for the last line of a paragraph; even if the paragraph as a whole
+     is fully justified, the last line should not be.
+
+     If NOSQUEEZE is non-`nil', that means do not change interior
+     whitespace.
+
+ - User Option: default-justification
+     This variable's value specifies the style of justification to use
+     for text that doesn't specify a style with a text property.  The
+     possible values are `left', `right', `full', `center', or `none'.
+     The default value is `left'.
+
+ - Function: current-justification
+     This function returns the proper justification style to use for
+     filling the text around point.
+
+ - Variable: fill-paragraph-function
+     This variable provides a way for major modes to override the
+     filling of paragraphs.  If the value is non-`nil',
+     `fill-paragraph' calls this function to do the work.  If the
+     function returns a non-`nil' value, `fill-paragraph' assumes the
+     job is done, and immediately returns that value.
+
+     The usual use of this feature is to fill comments in programming
+     language modes.  If the function needs to fill a paragraph in the
+     usual way, it can do so as follows:
+
+          (let ((fill-paragraph-function nil))
+            (fill-paragraph arg))
+
+ - Variable: use-hard-newlines
+     If this variable is non-`nil', the filling functions do not delete
+     newlines that have the `hard' text property.  These "hard
+     newlines" act as paragraph separators.

 
 

- - Function: car cons-cell
-     This function returns the value pointed to by the first pointer of
-     the cons cell CONS-CELL.  Expressed another way, this function
-     returns the CAR of CONS-CELL.
+\1f
+File: lispref.info,  Node: Margins,  Next: Auto Filling,  Prev: Filling,  Up: Text

 
 

-     As a special case, if CONS-CELL is `nil', then `car' is defined to
-     return `nil'; therefore, any list is a valid argument for `car'.
-     An error is signaled if the argument is not a cons cell or `nil'.
+Margins for Filling
+===================

 
 

-          (car '(a b c))
-               => a
-          (car '())
-               => nil
+ - User Option: fill-prefix
+     This variable specifies a string of text that appears at the
+     beginning of normal text lines and should be disregarded when
+     filling them.  Any line that fails to start with the fill prefix
+     is considered the start of a paragraph; so is any line that starts
+     with the fill prefix followed by additional whitespace.  Lines
+     that start with the fill prefix but no additional whitespace are
+     ordinary text lines that can be filled together.  The resulting
+     filled lines also start with the fill prefix.
+
+     The fill prefix follows the left margin whitespace, if any.
+
+ - User Option: fill-column
+     This buffer-local variable specifies the maximum width of filled
+     lines.  Its value should be an integer, which is a number of
+     columns.  All the filling, justification and centering commands
+     are affected by this variable, including Auto Fill mode (*note
+     Auto Filling::).
+
+     As a practical matter, if you are writing text for other people to
+     read, you should set `fill-column' to no more than 70.  Otherwise
+     the line will be too long for people to read comfortably, and this
+     can make the text seem clumsy.
+
+ - Variable: default-fill-column
+     The value of this variable is the default value for `fill-column'
+     in buffers that do not override it.  This is the same as
+     `(default-value 'fill-column)'.
+
+     The default value for `default-fill-column' is 70.
+
+ - Command: set-left-margin from to margin
+     This sets the `left-margin' property on the text from FROM to TO
+     to the value MARGIN.  If Auto Fill mode is enabled, this command
+     also refills the region to fit the new margin.
+
+ - Command: set-right-margin from to margin
+     This sets the `right-margin' property on the text from FROM to TO
+     to the value MARGIN.  If Auto Fill mode is enabled, this command
+     also refills the region to fit the new margin.
+
+ - Function: current-left-margin
+     This function returns the proper left margin value to use for
+     filling the text around point.  The value is the sum of the
+     `left-margin' property of the character at the start of the
+     current line (or zero if none), and the value of the variable
+     `left-margin'.
+
+ - Function: current-fill-column
+     This function returns the proper fill column value to use for
+     filling the text around point.  The value is the value of the
+     `fill-column' variable, minus the value of the `right-margin'
+     property of the character after point.
+
+ - Command: move-to-left-margin &optional n force
+     This function moves point to the left margin of the current line.
+     The column moved to is determined by calling the function
+     `current-left-margin'.  If the argument N is non-`nil',
+     `move-to-left-margin' moves forward N-1 lines first.
+
+     If FORCE is non-`nil', that says to fix the line's indentation if
+     that doesn't match the left margin value.
+
+ - Function: delete-to-left-margin &optional from to
+     This function removes left margin indentation from the text
+     between FROM and TO.  The amount of indentation to delete is
+     determined by calling `current-left-margin'.  In no case does this
+     function delete non-whitespace.
+
+     The arguments FROM and TO are optional; the default is the whole
+     buffer.
+
+ - Function: indent-to-left-margin
+     This is the default `indent-line-function', used in Fundamental
+     mode, Text mode, etc.  Its effect is to adjust the indentation at
+     the beginning of the current line to the value specified by the
+     variable `left-margin'.  This may involve either inserting or
+     deleting whitespace.
+
+ - Variable: left-margin
+     This variable specifies the base left margin column.  In
+     Fundamental mode, <LFD> indents to this column.  This variable
+     automatically becomes buffer-local when set in any fashion.

 
 

- - Function: cdr cons-cell
-     This function returns the value pointed to by the second pointer of
-     the cons cell CONS-CELL.  Expressed another way, this function
-     returns the CDR of CONS-CELL.
+\1f
+File: lispref.info,  Node: Auto Filling,  Next: Sorting,  Prev: Margins,  Up: Text

 
 

-     As a special case, if CONS-CELL is `nil', then `cdr' is defined to
-     return `nil'; therefore, any list is a valid argument for `cdr'.
-     An error is signaled if the argument is not a cons cell or `nil'.
+Auto Filling
+============

 
 

-          (cdr '(a b c))
-               => (b c)
-          (cdr '())
-               => nil
+Auto Fill mode is a minor mode that fills lines automatically as text
+is inserted.  This section describes the hook used by Auto Fill mode.
+For a description of functions that you can call explicitly to fill and
+justify existing text, see *Note Filling::.

 
 

- - Function: car-safe object
-     This function lets you take the CAR of a cons cell while avoiding
-     errors for other data types.  It returns the CAR of OBJECT if
-     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
-     `car', which signals an error if OBJECT is not a list.
-
-          (car-safe OBJECT)
-          ==
-          (let ((x OBJECT))
-            (if (consp x)
-                (car x)
-              nil))
-
- - Function: cdr-safe object
-     This function lets you take the CDR of a cons cell while avoiding
-     errors for other data types.  It returns the CDR of OBJECT if
-     OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
-     `cdr', which signals an error if OBJECT is not a list.
-
-          (cdr-safe OBJECT)
-          ==
-          (let ((x OBJECT))
-            (if (consp x)
-                (cdr x)
-              nil))
-
- - Function: nth n list
-     This function returns the Nth element of LIST.  Elements are
-     numbered starting with zero, so the CAR of LIST is element number
-     zero.  If the length of LIST is N or less, the value is `nil'.
-
-     If N is negative, `nth' returns the first element of LIST.
-
-          (nth 2 '(1 2 3 4))
-               => 3
-          (nth 10 '(1 2 3 4))
-               => nil
-          (nth -3 '(1 2 3 4))
-               => 1
-          
-          (nth n x) == (car (nthcdr n x))
+   Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text.  *Note Margins::.

 
 

- - Function: nthcdr n list
-     This function returns the Nth CDR of LIST.  In other words, it
-     removes the first N links of LIST and returns what follows.
+ - Variable: auto-fill-function
+     The value of this variable should be a function (of no arguments)
+     to be called after self-inserting a space or a newline.  It may be
+     `nil', in which case nothing special is done in that case.

 
 

-     If N is zero or negative, `nthcdr' returns all of LIST.  If the
-     length of LIST is N or less, `nthcdr' returns `nil'.
+     The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
+     mode is enabled.  That is a function whose sole purpose is to
+     implement the usual strategy for breaking a line.

 
 

-          (nthcdr 1 '(1 2 3 4))
-               => (2 3 4)
-          (nthcdr 10 '(1 2 3 4))
-               => nil
-          (nthcdr -3 '(1 2 3 4))
-               => (1 2 3 4)
-
-   Many convenience functions are provided to make it easier for you to
-access particular elements in a nested list.  All of these can be
-rewritten in terms of the functions just described.
-
- - Function: caar cons-cell
- - Function: cadr cons-cell
- - Function: cdar cons-cell
- - Function: cddr cons-cell
- - Function: caaar cons-cell
- - Function: caadr cons-cell
- - Function: cadar cons-cell
- - Function: caddr cons-cell
- - Function: cdaar cons-cell
- - Function: cdadr cons-cell
- - Function: cddar cons-cell
- - Function: cdddr cons-cell
- - Function: caaaar cons-cell
- - Function: caaadr cons-cell
- - Function: caadar cons-cell
- - Function: caaddr cons-cell
- - Function: cadaar cons-cell
- - Function: cadadr cons-cell
- - Function: caddar cons-cell
- - Function: cadddr cons-cell
- - Function: cdaaar cons-cell
- - Function: cdaadr cons-cell
- - Function: cdadar cons-cell
- - Function: cdaddr cons-cell
- - Function: cddaar cons-cell
- - Function: cddadr cons-cell
- - Function: cdddar cons-cell
- - Function: cddddr cons-cell
-     Each of these functions is equivalent to one or more applications
-     of `car' and/or `cdr'.  For example,
-
-          (cadr x)
-
-     is equivalent to
-
-          (car (cdr x))
-
-     and
-
-          (cdaddr x)
-
-     is equivalent to
-
-          (cdr (car (cdr (cdr x))))
-
-     That is to say, read the a's and d's from right to left and apply
-     a `car' or `cdr' for each a or d found, respectively.
-
- - Function: first list
-     This is equivalent to `(nth 0 LIST)', i.e. the first element of
-     LIST. (Note that this is also equivalent to `car'.)
-
- - Function: second list
-     This is equivalent to `(nth 1 LIST)', i.e. the second element of
-     LIST.
-
- - Function: third list
- - Function: fourth list
- - Function: fifth list
- - Function: sixth list
- - Function: seventh list
- - Function: eighth list
- - Function: ninth list
- - Function: tenth list
-     These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
-     respectively, i.e. the third through tenth elements of LIST.
-
-\1f
-File: lispref.info,  Node: Building Lists,  Next: Modifying Lists,  Prev: List Elements,  Up: Lists
-
-Building Cons Cells and Lists
-=============================
-
-   Many functions build lists, as lists reside at the very heart of
-Lisp.  `cons' is the fundamental list-building function; however, it is
-interesting to note that `list' is used more times in the source code
-for Emacs than `cons'.
-
- - Function: cons object1 object2
-     This function is the fundamental function used to build new list
-     structure.  It creates a new cons cell, making OBJECT1 the CAR,
-     and OBJECT2 the CDR.  It then returns the new cons cell.  The
-     arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
-     often OBJECT2 is a list.
-
-          (cons 1 '(2))
-               => (1 2)
-          (cons 1 '())
-               => (1)
-          (cons 1 2)
-               => (1 . 2)
-
-     `cons' is often used to add a single element to the front of a
-     list.  This is called "consing the element onto the list".  For
-     example:
-
-          (setq list (cons newelt list))
-
-     Note that there is no conflict between the variable named `list'
-     used in this example and the function named `list' described below;
-     any symbol can serve both purposes.
-
- - Function: list &rest objects
-     This function creates a list with OBJECTS as its elements.  The
-     resulting list is always `nil'-terminated.  If no OBJECTS are
-     given, the empty list is returned.
-
-          (list 1 2 3 4 5)
-               => (1 2 3 4 5)
-          (list 1 2 '(3 4 5) 'foo)
-               => (1 2 (3 4 5) foo)
-          (list)
-               => nil
+          In older Emacs versions, this variable was named
+          `auto-fill-hook', but since it is not called with the
+          standard convention for hooks, it was renamed to
+          `auto-fill-function' in version 19.

 
 

- - Function: make-list length object
-     This function creates a list of length LENGTH, in which all the
-     elements have the identical value OBJECT.  Compare `make-list'
-     with `make-string' (*note Creating Strings::).
+\1f
+File: lispref.info,  Node: Sorting,  Next: Columns,  Prev: Auto Filling,  Up: Text
+
+Sorting Text
+============
+
+The sorting functions described in this section all rearrange text in a
+buffer.  This is in contrast to the function `sort', which rearranges
+the order of the elements of a list (*note Rearrangement::).  The
+values returned by these functions are not meaningful.
+
+ - Function: sort-subr reverse nextrecfun endrecfun &optional
+          startkeyfun endkeyfun
+     This function is the general text-sorting routine that divides a
+     buffer into records and sorts them.  Most of the commands in this
+     section use this function.
+
+     To understand how `sort-subr' works, consider the whole accessible
+     portion of the buffer as being divided into disjoint pieces called
+     "sort records".  The records may or may not be contiguous; they may
+     not overlap.  A portion of each sort record (perhaps all of it) is
+     designated as the sort key.  Sorting rearranges the records in
+     order by their sort keys.
+
+     Usually, the records are rearranged in order of ascending sort key.
+     If the first argument to the `sort-subr' function, REVERSE, is
+     non-`nil', the sort records are rearranged in order of descending
+     sort key.
+
+     The next four arguments to `sort-subr' are functions that are
+     called to move point across a sort record.  They are called many
+     times from within `sort-subr'.
+
+       1. NEXTRECFUN is called with point at the end of a record.  This
+          function moves point to the start of the next record.  The
+          first record is assumed to start at the position of point
+          when `sort-subr' is called.  Therefore, you should usually
+          move point to the beginning of the buffer before calling
+          `sort-subr'.
+
+          This function can indicate there are no more sort records by
+          leaving point at the end of the buffer.
+
+       2. ENDRECFUN is called with point within a record.  It moves
+          point to the end of the record.
+
+       3. STARTKEYFUN is called to move point from the start of a
+          record to the start of the sort key.  This argument is
+          optional; if it is omitted, the whole record is the sort key.
+          If supplied, the function should either return a non-`nil'
+          value to be used as the sort key, or return `nil' to indicate
+          that the sort key is in the buffer starting at point.  In the
+          latter case, ENDKEYFUN is called to find the end of the sort
+          key.
+
+       4. ENDKEYFUN is called to move point from the start of the sort
+          key to the end of the sort key.  This argument is optional.
+          If STARTKEYFUN returns `nil' and this argument is omitted (or
+          `nil'), then the sort key extends to the end of the record.
+          There is no need for ENDKEYFUN if STARTKEYFUN returns a
+          non-`nil' value.
+
+     As an example of `sort-subr', here is the complete function
+     definition for `sort-lines':
+
+          ;; Note that the first two lines of doc string
+          ;; are effectively one line when viewed by a user.
+          (defun sort-lines (reverse start end)
+            "Sort lines in region alphabetically.
+          Called from a program, there are three arguments:
+          REVERSE (non-nil means reverse order),
+          and START and END (the region to sort)."
+            (interactive "P\nr")
+            (save-restriction
+              (narrow-to-region start end)
+              (goto-char (point-min))
+              (sort-subr reverse
+                         'forward-line
+                         'end-of-line)))
+
+     Here `forward-line' moves point to the start of the next record,
+     and `end-of-line' moves point to the end of record.  We do not pass
+     the arguments STARTKEYFUN and ENDKEYFUN, because the entire record
+     is used as the sort key.
+
+     The `sort-paragraphs' function is very much the same, except that
+     its `sort-subr' call looks like this:
+
+          (sort-subr reverse
+                     (function
+                      (lambda ()
+                        (skip-chars-forward "\n \t\f")))
+                     'forward-paragraph)
+
+ - Command: sort-regexp-fields reverse record-regexp key-regexp start
+          end
+     This command sorts the region between START and END alphabetically
+     as specified by RECORD-REGEXP and KEY-REGEXP.  If REVERSE is a
+     negative integer, then sorting is in reverse order.
+
+     Alphabetical sorting means that two sort keys are compared by
+     comparing the first characters of each, the second characters of
+     each, and so on.  If a mismatch is found, it means that the sort
+     keys are unequal; the sort key whose character is less at the
+     point of first mismatch is the lesser sort key.  The individual
+     characters are compared according to their numerical values.
+     Since Emacs uses the ASCII character set, the ordering in that set
+     determines alphabetical order.
+
+     The value of the RECORD-REGEXP argument specifies how to divide
+     the buffer into sort records.  At the end of each record, a search
+     is done for this regular expression, and the text that matches it
+     is the next record.  For example, the regular expression `^.+$',
+     which matches lines with at least one character besides a newline,
+     would make each such line into a sort record.  *Note Regular
+     Expressions::, for a description of the syntax and meaning of
+     regular expressions.
+
+     The value of the KEY-REGEXP argument specifies what part of each
+     record is the sort key.  The KEY-REGEXP could match the whole
+     record, or only a part.  In the latter case, the rest of the
+     record has no effect on the sorted order of records, but it is
+     carried along when the record moves to its new position.
+
+     The KEY-REGEXP argument can refer to the text matched by a
+     subexpression of RECORD-REGEXP, or it can be a regular expression
+     on its own.
+
+     If KEY-REGEXP is:
+
+    `\DIGIT'
+          then the text matched by the DIGITth `\(...\)' parenthesis
+          grouping in RECORD-REGEXP is the sort key.
+
+    `\&'
+          then the whole record is the sort key.
+
+    a regular expression
+          then `sort-regexp-fields' searches for a match for the regular
+          expression within the record.  If such a match is found, it
+          is the sort key.  If there is no match for KEY-REGEXP within
+          a record then that record is ignored, which means its
+          position in the buffer is not changed.  (The other records
+          may move around it.)
+
+     For example, if you plan to sort all the lines in the region by the
+     first word on each line starting with the letter `f', you should
+     set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\<f\w*\>'.  The
+     resulting expression looks like this:
+
+          (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
+                              (region-beginning)
+                              (region-end))
+
+     If you call `sort-regexp-fields' interactively, it prompts for
+     RECORD-REGEXP and KEY-REGEXP in the minibuffer.
+
+ - Command: sort-lines reverse start end
+     This command alphabetically sorts lines in the region between
+     START and END.  If REVERSE is non-`nil', the sort is in reverse
+     order.
+
+ - Command: sort-paragraphs reverse start end
+     This command alphabetically sorts paragraphs in the region between
+     START and END.  If REVERSE is non-`nil', the sort is in reverse
+     order.
+
+ - Command: sort-pages reverse start end
+     This command alphabetically sorts pages in the region between
+     START and END.  If REVERSE is non-`nil', the sort is in reverse
+     order.
+
+ - Command: sort-fields field start end
+     This command sorts lines in the region between START and END,
+     comparing them alphabetically by the FIELDth field of each line.
+     Fields are separated by whitespace and numbered starting from 1.
+     If FIELD is negative, sorting is by the -FIELDth field from the
+     end of the line.  This command is useful for sorting tables.
+
+ - Command: sort-numeric-fields field start end
+     This command sorts lines in the region between START and END,
+     comparing them numerically by the FIELDth field of each line.  The
+     specified field must contain a number in each line of the region.
+     Fields are separated by whitespace and numbered starting from 1.
+     If FIELD is negative, sorting is by the -FIELDth field from the
+     end of the line.  This command is useful for sorting tables.
+
+ - Command: sort-columns reverse &optional start end
+     This command sorts the lines in the region between START and END,
+     comparing them alphabetically by a certain range of columns.  The
+     column positions of START and END bound the range of columns to
+     sort on.
+
+     If REVERSE is non-`nil', the sort is in reverse order.
+
+     One unusual thing about this command is that the entire line
+     containing position START, and the entire line containing position
+     END, are included in the region sorted.
+
+     Note that `sort-columns' uses the `sort' utility program, and so
+     cannot work properly on text containing tab characters.  Use `M-x
+     `untabify'' to convert tabs to spaces before sorting.

 
 

-          (make-list 3 'pigs)
-               => (pigs pigs pigs)
-          (make-list 0 'pigs)
-               => nil
+\1f
+File: lispref.info,  Node: Columns,  Next: Indentation,  Prev: Sorting,  Up: Text

 
 

- - Function: append &rest sequences
-     This function returns a list containing all the elements of
-     SEQUENCES.  The SEQUENCES may be lists, vectors, or strings, but
-     the last one should be a list.  All arguments except the last one
-     are copied, so none of them are altered.
-
-     More generally, the final argument to `append' may be any Lisp
-     object.  The final argument is not copied or converted; it becomes
-     the CDR of the last cons cell in the new list.  If the final
-     argument is itself a list, then its elements become in effect
-     elements of the result list.  If the final element is not a list,
-     the result is a "dotted list" since its final CDR is not `nil' as
-     required in a true list.
-
-     See `nconc' in *Note Rearrangement::, for a way to join lists with
-     no copying.
-
-     Here is an example of using `append':
-
-          (setq trees '(pine oak))
-               => (pine oak)
-          (setq more-trees (append '(maple birch) trees))
-               => (maple birch pine oak)
-          
-          trees
-               => (pine oak)
-          more-trees
-               => (maple birch pine oak)
-          (eq trees (cdr (cdr more-trees)))
-               => t
+Counting Columns
+================

 
 

-     You can see how `append' works by looking at a box diagram.  The
-     variable `trees' is set to the list `(pine oak)' and then the
-     variable `more-trees' is set to the list `(maple birch pine oak)'.
-     However, the variable `trees' continues to refer to the original
-     list:
-
-          more-trees                trees
-          |                           |
-          |     ___ ___      ___ ___   -> ___ ___      ___ ___
-           --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
-                 |            |            |            |
-                 |            |            |            |
-                  --> maple    -->birch     --> pine     --> oak
-
-     An empty sequence contributes nothing to the value returned by
-     `append'.  As a consequence of this, a final `nil' argument forces
-     a copy of the previous argument.
-
-          trees
-               => (pine oak)
-          (setq wood (append trees ()))
-               => (pine oak)
-          wood
-               => (pine oak)
-          (eq wood trees)
-               => nil
+The column functions convert between a character position (counting
+characters from the beginning of the buffer) and a column position
+(counting screen characters from the beginning of a line).

 
 

-     This once was the usual way to copy a list, before the function
-     `copy-sequence' was invented.  *Note Sequences Arrays Vectors::.
+   A character counts according to the number of columns it occupies on
+the screen.  This means control characters count as occupying 2 or 4
+columns, depending upon the value of `ctl-arrow', and tabs count as
+occupying a number of columns that depends on the value of `tab-width'
+and on the column where the tab begins.  *Note Usual Display::.

 
 

-     With the help of `apply', we can append all the lists in a list of
-     lists:
+   Column number computations ignore the width of the window and the
+amount of horizontal scrolling.  Consequently, a column value can be
+arbitrarily high.  The first (or leftmost) column is numbered 0.

 
 

-          (apply 'append '((a b c) nil (x y z) nil))
-               => (a b c x y z)
+ - Function: current-column &optional buffer
+     This function returns the horizontal position of point, measured in
+     columns, counting from 0 at the left margin.

 
 

-     If no SEQUENCES are given, `nil' is returned:
+     This is calculated by adding together the widths of all the
+     displayed representations of the character between the start of
+     the previous line and point. (e.g. control characters will have a
+     width of 2 or 4, tabs will have a variable width.)

 
 

-          (append)
-               => nil
+     Ignores the finite width of frame displaying the buffer, which
+     means that this function may return values greater than
+     `(frame-width)'.

 
 

-     Here are some examples where the final argument is not a list:
+     Whether the line is visible (if `selective-display' is t) has no
+     effect; however, ^M is treated as end of line when
+     `selective-display' is t.

 
 

-          (append '(x y) 'z)
-               => (x y . z)
-          (append '(x y) [z])
-               => (x y . [z])
+     If BUFFER is nil, the current buffer is assumed.

 
 

-     The second example shows that when the final argument is a
-     sequence but not a list, the sequence's elements do not become
-     elements of the resulting list.  Instead, the sequence becomes the
-     final CDR, like any other non-list final argument.
+     For an example of using `current-column', see the description of
+     `count-lines' in *Note Text Lines::.

 
 

-     The `append' function also allows integers as arguments.  It
-     converts them to strings of digits, making up the decimal print
-     representation of the integer, and then uses the strings instead
-     of the original integers.  *Don't use this feature; we plan to
-     eliminate it.  If you already use this feature, change your
-     programs now!*  The proper way to convert an integer to a decimal
-     number in this way is with `format' (*note Formatting Strings::)
-     or `number-to-string' (*note String Conversion::).
+ - Function: move-to-column column &optional force buffer
+     This function moves point to COLUMN in the current line.  The
+     calculation of COLUMN takes into account the widths of the
+     displayed representations of the characters between the start of
+     the line and point.

 
 

- - Function: reverse list
-     This function creates a new list whose elements are the elements of
-     LIST, but in reverse order.  The original argument LIST is _not_
-     altered.
+     If column COLUMN is beyond the end of the line, point moves to the
+     end of the line.  If COLUMN is negative, point moves to the
+     beginning of the line.

 
 

-          (setq x '(1 2 3 4))
-               => (1 2 3 4)
-          (reverse x)
-               => (4 3 2 1)
-          x
-               => (1 2 3 4)
+     If it is impossible to move to column COLUMN because that is in
+     the middle of a multicolumn character such as a tab, point moves
+     to the end of that character.  However, if FORCE is non-`nil', and
+     COLUMN is in the middle of a tab, then `move-to-column' converts
+     the tab into spaces so that it can move precisely to column
+     COLUMN.  Other multicolumn characters can cause anomalies despite
+     FORCE, since there is no way to split them.

 
 

-\1f
-File: lispref.info,  Node: Modifying Lists,  Next: Sets And Lists,  Prev: Building Lists,  Up: Lists
+     The argument FORCE also has an effect if the line isn't long
+     enough to reach column COLUMN; in that case, unless the value of
+     FORCE is the special value `coerce', it says to add whitespace at
+     the end of the line to reach that column.

 
 

-Modifying Existing List Structure
-=================================
+     If COLUMN is not a non-negative integer, an error is signaled.
+
+     The return value is the column number actually moved to.
+
+\1f
+File: lispref.info,  Node: Indentation,  Next: Case Changes,  Prev: Columns,  Up: Text

 
 

-   You can modify the CAR and CDR contents of a cons cell with the
-primitives `setcar' and `setcdr'.
+Indentation
+===========

 
 

-     Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
-     to alter list structure; they change structure the same way as
-     `setcar' and `setcdr', but the Common Lisp functions return the
-     cons cell while `setcar' and `setcdr' return the new CAR or CDR.
+The indentation functions are used to examine, move to, and change
+whitespace that is at the beginning of a line.  Some of the functions
+can also change whitespace elsewhere on a line.  Columns and indentation
+count from zero at the left margin.

 
 * Menu:
 
 
 * Menu:
 

-* 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.
+* 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.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Setcar,  Next: Setcdr,  Up: Modifying Lists
+File: lispref.info,  Node: Primitive Indent,  Next: Mode-Specific Indent,  Up: Indentation
+
+Indentation Primitives
+----------------------
+
+This section describes the primitive functions used to count and insert
+indentation.  The functions in the following sections use these
+primitives.
+
+ - Function: current-indentation &optional buffer
+     This function returns the indentation of the current line, which is
+     the horizontal position of the first nonblank character.  If the
+     contents are entirely blank, then this is the horizontal position
+     of the end of the line.
+
+ - Command: indent-to column &optional minimum buffer
+     This function indents from point with tabs and spaces until COLUMN
+     is reached.  If MINIMUM is specified and non-`nil', then at least
+     that many spaces are inserted even if this requires going beyond
+     COLUMN.  Otherwise the function does nothing if point is already
+     beyond COLUMN.  The value is the column at which the inserted
+     indentation ends.  If BUFFER is `nil', the current buffer is
+     assumed.
+
+ - User Option: indent-tabs-mode
+     If this variable is non-`nil', indentation functions can insert
+     tabs as well as spaces.  Otherwise, they insert only spaces.
+     Setting this variable automatically makes it local to the current
+     buffer.

 
 

-Altering List Elements with `setcar'
+\1f
+File: lispref.info,  Node: Mode-Specific Indent,  Next: Region Indent,  Prev: Primitive Indent,  Up: Indentation
+
+Indentation Controlled by Major Mode

 ------------------------------------
 
 ------------------------------------
 

-   Changing the CAR of a cons cell is done with `setcar'.  When used on
-a list, `setcar' replaces one element of a list with a different
-element.
+An important function of each major mode is to customize the <TAB> key
+to indent properly for the language being edited.  This section
+describes the mechanism of the <TAB> key and how to control it.  The
+functions in this section return unpredictable values.
+
+ - Variable: indent-line-function
+     This variable's value is the function to be used by <TAB> (and
+     various commands) to indent the current line.  The command
+     `indent-according-to-mode' does no more than call this function.
+
+     In Lisp mode, the value is the symbol `lisp-indent-line'; in C
+     mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'.  In
+     Fundamental mode, Text mode, and many other modes with no standard
+     for indentation, the value is `indent-to-left-margin' (which is the
+     default value).
+
+ - Command: indent-according-to-mode
+     This command calls the function in `indent-line-function' to
+     indent the current line in a way appropriate for the current major
+     mode.
+
+ - Command: indent-for-tab-command &optional prefix-arg
+     This command calls the function in `indent-line-function' to indent
+     the current line; except that if that function is
+     `indent-to-left-margin', it calls `insert-tab' instead.  (That is
+     a trivial command that inserts a tab character.)
+
+ - Command: newline-and-indent
+     This function inserts a newline, then indents the new line (the one
+     following the newline just inserted) according to the major mode.
+
+     It does indentation by calling the current `indent-line-function'.
+     In programming language modes, this is the same thing <TAB> does,
+     but in some text modes, where <TAB> inserts a tab,
+     `newline-and-indent' indents to the column specified by
+     `left-margin'.
+
+ - Command: reindent-then-newline-and-indent
+     This command reindents the current line, inserts a newline at
+     point, and then reindents the new line (the one following the
+     newline just inserted).
+
+     This command does indentation on both lines according to the
+     current major mode, by calling the current value of
+     `indent-line-function'.  In programming language modes, this is
+     the same thing <TAB> does, but in some text modes, where <TAB>
+     inserts a tab, `reindent-then-newline-and-indent' indents to the
+     column specified by `left-margin'.

 
 

- - Function: setcar cons-cell object
-     This function stores OBJECT as the new CAR of CONS-CELL, replacing
-     its previous CAR.  It returns the value OBJECT.  For example:
+\1f
+File: lispref.info,  Node: Region Indent,  Next: Relative Indent,  Prev: Mode-Specific Indent,  Up: Indentation

 
 

-          (setq x '(1 2))
-               => (1 2)
-          (setcar x 4)
-               => 4
-          x
-               => (4 2)
-
-   When a cons cell is part of the shared structure of several lists,
-storing a new CAR into the cons changes one element of each of these
-lists.  Here is an example:
-
-     ;; Create two lists that are partly shared.
-     (setq x1 '(a b c))
-          => (a b c)
-     (setq x2 (cons 'z (cdr x1)))
-          => (z b c)
-     
-     ;; Replace the CAR of a shared link.
-     (setcar (cdr x1) 'foo)
-          => foo
-     x1                           ; Both lists are changed.
-          => (a foo c)
-     x2
-          => (z foo c)
-     
-     ;; Replace the CAR of a link that is not shared.
-     (setcar x1 'baz)
-          => baz
-     x1                           ; Only one list is changed.
-          => (baz foo c)
-     x2
-          => (z foo c)
-
-   Here is a graphical depiction of the shared structure of the two
-lists in the variables `x1' and `x2', showing why replacing `b' changes
-them both:
-
-             ___ ___        ___ ___      ___ ___
-     x1---> |___|___|----> |___|___|--> |___|___|--> nil
-              |        -->   |            |
-              |       |      |            |
-               --> a  |       --> b        --> c
-                      |
-            ___ ___   |
-     x2--> |___|___|--
-             |
-             |
-              --> z
-
-   Here is an alternative form of box diagram, showing the same
-relationship:
-
-     x1:
-      --------------       --------------       --------------
-     | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
-     |   a   |   o------->|   b   |   o------->|   c   |  nil |
-     |       |      |  -->|       |      |     |       |      |
-      --------------  |    --------------       --------------
-                      |
-     x2:              |
-      --------------  |
-     | car   | cdr  | |
-     |   z   |   o----
-     |       |      |
-      --------------
-
-\1f
-File: lispref.info,  Node: Setcdr,  Next: Rearrangement,  Prev: Setcar,  Up: Modifying Lists
-
-Altering the CDR of a List
+Indenting an Entire Region

 --------------------------
 
 --------------------------
 

-   The lowest-level primitive for modifying a CDR is `setcdr':
-
- - Function: setcdr cons-cell object
-     This function stores OBJECT as the new CDR of CONS-CELL, replacing
-     its previous CDR.  It returns the value OBJECT.
-
-   Here is an example of replacing the CDR of a list with a different
-list.  All but the first element of the list are removed in favor of a
-different sequence of elements.  The first element is unchanged,
-because it resides in the CAR of the list, and is not reached via the
-CDR.
-
-     (setq x '(1 2 3))
-          => (1 2 3)
-     (setcdr x '(4))
-          => (4)
-     x
-          => (1 4)
-
-   You can delete elements from the middle of a list by altering the
-CDRs of the cons cells in the list.  For example, here we delete the
-second element, `b', from the list `(a b c)', by changing the CDR of
-the first cell:
-
-     (setq x1 '(a b c))
-          => (a b c)
-     (setcdr x1 (cdr (cdr x1)))
-          => (c)
-     x1
-          => (a c)
-
-   Here is the result in box notation:
-
-                        --------------------
-                       |                    |
-      --------------   |   --------------   |    --------------
-     | car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
-     |   a   |   o-----   |   b   |   o-------->|   c   |  nil |
-     |       |      |     |       |      |      |       |      |
-      --------------       --------------        --------------
-
-The second cons cell, which previously held the element `b', still
-exists and its CAR is still `b', but it no longer forms part of this
-list.
-
-   It is equally easy to insert a new element by changing CDRs:
-
-     (setq x1 '(a b c))
-          => (a b c)
-     (setcdr x1 (cons 'd (cdr x1)))
-          => (d b c)
-     x1
-          => (a d b c)
-
-   Here is this result in box notation:
-
-      --------------        -------------       -------------
-     | car  | cdr   |      | car  | cdr  |     | car  | cdr  |
-     |   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
-     |      |   |   |  |   |      |      |     |      |      |
-      --------- | --   |    -------------       -------------
-                |      |
-          -----         --------
-         |                      |
-         |    ---------------   |
-         |   | car   | cdr   |  |
-          -->|   d   |   o------
-             |       |       |
-              ---------------
-
-\1f
-File: lispref.info,  Node: Rearrangement,  Prev: Setcdr,  Up: Modifying Lists
-
-Functions that Rearrange Lists
-------------------------------
-
-   Here are some functions that rearrange lists "destructively" by
-modifying the CDRs of their component cons cells.  We call these
-functions "destructive" because they chew up the original lists passed
-to them as arguments, to produce a new list that is the returned value.
-
-   See `delq', in *Note Sets And Lists::, for another function that
-modifies cons cells.
-
- - Function: nconc &rest lists
-     This function returns a list containing all the elements of LISTS.
-     Unlike `append' (*note Building Lists::), the LISTS are _not_
-     copied.  Instead, the last CDR of each of the LISTS is changed to
-     refer to the following list.  The last of the LISTS is not
-     altered.  For example:
-
-          (setq x '(1 2 3))
-               => (1 2 3)
-          (nconc x '(4 5))
-               => (1 2 3 4 5)
-          x
-               => (1 2 3 4 5)
-
-     Since the last argument of `nconc' is not itself modified, it is
-     reasonable to use a constant list, such as `'(4 5)', as in the
-     above example.  For the same reason, the last argument need not be
-     a list:
-
-          (setq x '(1 2 3))
-               => (1 2 3)
-          (nconc x 'z)
-               => (1 2 3 . z)
-          x
-               => (1 2 3 . z)
-
-     A common pitfall is to use a quoted constant list as a non-last
-     argument to `nconc'.  If you do this, your program will change
-     each time you run it!  Here is what happens:
-
-          (defun add-foo (x)            ; We want this function to add
-            (nconc '(foo) x))           ;   `foo' to the front of its arg.
-          
-          (symbol-function 'add-foo)
-               => (lambda (x) (nconc (quote (foo)) x))
-          
-          (setq xx (add-foo '(1 2)))    ; It seems to work.
-               => (foo 1 2)
-          (setq xy (add-foo '(3 4)))    ; What happened?
-               => (foo 1 2 3 4)
-          (eq xx xy)
-               => t
-          
-          (symbol-function 'add-foo)
-               => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
-
- - Function: nreverse list
-     This function reverses the order of the elements of LIST.  Unlike
-     `reverse', `nreverse' alters its argument by reversing the CDRs in
-     the cons cells forming the list.  The cons cell that used to be
-     the last one in LIST becomes the first cell of the value.
-
-     For example:
-
-          (setq x '(1 2 3 4))
-               => (1 2 3 4)
-          x
-               => (1 2 3 4)
-          (nreverse x)
-               => (4 3 2 1)
-          ;; The cell that was first is now last.
-          x
-               => (1)
-
-     To avoid confusion, we usually store the result of `nreverse' back
-     in the same variable which held the original list:
-
-          (setq x (nreverse x))
-
-     Here is the `nreverse' of our favorite example, `(a b c)',
-     presented graphically:
-
-          Original list head:                       Reversed list:
-           -------------        -------------        ------------
-          | car  | cdr  |      | car  | cdr  |      | car | cdr  |
-          |   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
-          |      |      |   |  |      |   |  |   |  |     |   |  |
-           -------------    |   --------- | -    |   -------- | -
-                            |             |      |            |
-                             -------------        ------------
-
- - Function: sort list predicate
-     This function sorts LIST stably, though destructively, and returns
-     the sorted list.  It compares elements using PREDICATE.  A stable
-     sort is one in which elements with equal sort keys maintain their
-     relative order before and after the sort.  Stability is important
-     when successive sorts are used to order elements according to
-     different criteria.
-
-     The argument PREDICATE must be a function that accepts two
-     arguments.  It is called with two elements of LIST.  To get an
-     increasing order sort, the PREDICATE should return `t' if the
-     first element is "less than" the second, or `nil' if not.
-
-     The destructive aspect of `sort' is that it rearranges the cons
-     cells forming LIST by changing CDRs.  A nondestructive sort
-     function would create new cons cells to store the elements in their
-     sorted order.  If you wish to make a sorted copy without
-     destroying the original, copy it first with `copy-sequence' and
-     then sort.
-
-     Sorting does not change the CARs of the cons cells in LIST; the
-     cons cell that originally contained the element `a' in LIST still
-     has `a' in its CAR after sorting, but it now appears in a
-     different position in the list due to the change of CDRs.  For
-     example:
-
-          (setq nums '(1 3 2 6 5 4 0))
-               => (1 3 2 6 5 4 0)
-          (sort nums '<)
-               => (0 1 2 3 4 5 6)
-          nums
-               => (1 2 3 4 5 6)
-
-     Note that the list in `nums' no longer contains 0; this is the same
-     cons cell that it was before, but it is no longer the first one in
-     the list.  Don't assume a variable that formerly held the argument
-     now holds the entire sorted list!  Instead, save the result of
-     `sort' and use that.  Most often we store the result back into the
-     variable that held the original list:
-
-          (setq nums (sort nums '<))
-
-     *Note Sorting::, for more functions that perform sorting.  See
-     `documentation' in *Note Accessing Documentation::, for a useful
-     example of `sort'.
-
-\1f
-File: lispref.info,  Node: Sets And Lists,  Next: Association Lists,  Prev: Modifying Lists,  Up: Lists
-
-Using Lists as Sets
-===================
+This section describes commands that indent all the lines in the
+region.  They return unpredictable values.
+
+ - Command: indent-region start end to-column
+     This command indents each nonblank line starting between START
+     (inclusive) and END (exclusive).  If TO-COLUMN is `nil',
+     `indent-region' indents each nonblank line by calling the current
+     mode's indentation function, the value of `indent-line-function'.
+
+     If TO-COLUMN is non-`nil', it should be an integer specifying the
+     number of columns of indentation; then this function gives each
+     line exactly that much indentation, by either adding or deleting
+     whitespace.
+
+     If there is a fill prefix, `indent-region' indents each line by
+     making it start with the fill prefix.
+
+ - Variable: indent-region-function
+     The value of this variable is a function that can be used by
+     `indent-region' as a short cut.  You should design the function so
+     that it will produce the same results as indenting the lines of the
+     region one by one, but presumably faster.
+
+     If the value is `nil', there is no short cut, and `indent-region'
+     actually works line by line.
+
+     A short-cut function is useful in modes such as C mode and Lisp
+     mode, where the `indent-line-function' must scan from the
+     beginning of the function definition: applying it to each line
+     would be quadratic in time.  The short cut can update the scan
+     information as it moves through the lines indenting them; this
+     takes linear time.  In a mode where indenting a line individually
+     is fast, there is no need for a short cut.
+
+     `indent-region' with a non-`nil' argument TO-COLUMN has a
+     different meaning and does not use this variable.
+
+ - Command: indent-rigidly start end count
+     This command indents all lines starting between START (inclusive)
+     and END (exclusive) sideways by COUNT columns.  This "preserves
+     the shape" of the affected region, moving it as a rigid unit.
+     Consequently, this command is useful not only for indenting
+     regions of unindented text, but also for indenting regions of
+     formatted code.
+
+     For example, if COUNT is 3, this command adds 3 columns of
+     indentation to each of the lines beginning in the region specified.
+
+     In Mail mode, `C-c C-y' (`mail-yank-original') uses
+     `indent-rigidly' to indent the text copied from the message being
+     replied to.
+
+ - Command: indent-code-rigidly start end columns &optional
+          nochange-regexp
+     This is like `indent-rigidly', except that it doesn't alter lines
+     that start within strings or comments.
+
+     In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at
+     the beginning of the line (if NOCHANGE-REGEXP is non-`nil').

 
 

-   A list can represent an unordered mathematical set--simply consider a
-value an element of a set if it appears in the list, and ignore the
-order of the list.  To form the union of two sets, use `append' (as
-long as you don't mind having duplicate elements).  Other useful
-functions for sets include `memq' and `delq', and their `equal'
-versions, `member' and `delete'.
-
-     Common Lisp note: Common Lisp has functions `union' (which avoids
-     duplicate elements) and `intersection' for set operations, but
-     XEmacs Lisp does not have them.  You can write them in Lisp if you
-     wish.
-
- - Function: memq object list
-     This function tests to see whether OBJECT is a member of LIST.  If
-     it is, `memq' returns a list starting with the first occurrence of
-     OBJECT.  Otherwise, it returns `nil'.  The letter `q' in `memq'
-     says that it uses `eq' to compare OBJECT against the elements of
-     the list.  For example:
-
-          (memq 'b '(a b c b a))
-               => (b c b a)
-          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
-               => nil
+\1f
+File: lispref.info,  Node: Relative Indent,  Next: Indent Tabs,  Prev: Region Indent,  Up: Indentation

 
 

- - Function: delq object list
-     This function destructively removes all elements `eq' to OBJECT
-     from LIST.  The letter `q' in `delq' says that it uses `eq' to
-     compare OBJECT against the elements of the list, like `memq'.
-
-   When `delq' deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
-
-     (delq 'a '(a b c)) == (cdr '(a b c))
-
-   When an element to be deleted appears in the middle of the list,
-removing it involves changing the CDRs (*note Setcdr::).
-
-     (setq sample-list '(a b c (4)))
-          => (a b c (4))
-     (delq 'a sample-list)
-          => (b c (4))
-     sample-list
-          => (a b c (4))
-     (delq 'c sample-list)
-          => (a b (4))
-     sample-list
-          => (a b (4))
-
-   Note that `(delq 'c sample-list)' modifies `sample-list' to splice
-out the third element, but `(delq 'a sample-list)' does not splice
-anything--it just returns a shorter list.  Don't assume that a variable
-which formerly held the argument LIST now has fewer elements, or that
-it still holds the original list!  Instead, save the result of `delq'
-and use that.  Most often we store the result back into the variable
-that held the original list:
-
-     (setq flowers (delq 'rose flowers))
-
-   In the following example, the `(4)' that `delq' attempts to match
-and the `(4)' in the `sample-list' are not `eq':
-
-     (delq '(4) sample-list)
-          => (a c (4))
-
-   The following two functions are like `memq' and `delq' but use
-`equal' rather than `eq' to compare elements.  They are new in Emacs 19.
-
- - Function: member object list
-     The function `member' tests to see whether OBJECT is a member of
-     LIST, comparing members with OBJECT using `equal'.  If OBJECT is a
-     member, `member' returns a list starting with its first occurrence
-     in LIST.  Otherwise, it returns `nil'.
-
-     Compare this with `memq':
-
-          (member '(2) '((1) (2)))  ; `(2)' and `(2)' are `equal'.
-               => ((2))
-          (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
-               => nil
-          ;; Two strings with the same contents are `equal'.
-          (member "foo" '("foo" "bar"))
-               => ("foo" "bar")
+Indentation Relative to Previous Lines
+--------------------------------------
+
+This section describes two commands that indent the current line based
+on the contents of previous lines.
+
+ - Command: indent-relative &optional unindented-ok
+     This command inserts whitespace at point, extending to the same
+     column as the next "indent point" of the previous nonblank line.
+     An indent point is a non-whitespace character following
+     whitespace.  The next indent point is the first one at a column
+     greater than the current column of point.  For example, if point
+     is underneath and to the left of the first non-blank character of
+     a line of text, it moves to that column by inserting whitespace.
+
+     If the previous nonblank line has no next indent point (i.e., none
+     at a great enough column position), `indent-relative' either does
+     nothing (if UNINDENTED-OK is non-`nil') or calls
+     `tab-to-tab-stop'.  Thus, if point is underneath and to the right
+     of the last column of a short line of text, this command ordinarily
+     moves point to the next tab stop by inserting whitespace.
+
+     The return value of `indent-relative' is unpredictable.
+
+     In the following example, point is at the beginning of the second
+     line:
+
+                      This line is indented twelve spaces.
+          -!-The quick brown fox jumped.
+
+     Evaluation of the expression `(indent-relative nil)' produces the
+     following:
+
+                      This line is indented twelve spaces.
+                      -!-The quick brown fox jumped.
+
+     In this example, point is between the `m' and `p' of `jumped':

 
 

- - Function: delete object list
-     This function destructively removes all elements `equal' to OBJECT
-     from LIST.  It is to `delq' as `member' is to `memq': it uses
-     `equal' to compare elements with OBJECT, like `member'; when it
-     finds an element that matches, it removes the element just as
-     `delq' would.  For example:
+                      This line is indented twelve spaces.
+          The quick brown fox jum-!-ped.

 
 

-          (delete '(2) '((2) (1) (2)))
-               => '((1))
+     Evaluation of the expression `(indent-relative nil)' produces the
+     following:

 
 

-     Common Lisp note: The functions `member' and `delete' in XEmacs
-     Lisp are derived from Maclisp, not Common Lisp.  The Common Lisp
-     versions do not use `equal' to compare elements.
+                      This line is indented twelve spaces.
+          The quick brown fox jum  -!-ped.

 
 

-   See also the function `add-to-list', in *Note Setting Variables::,
-for another way to add an element to a list stored in a variable.
+ - Command: indent-relative-maybe
+     This command indents the current line like the previous nonblank
+     line.  It calls `indent-relative' with `t' as the UNINDENTED-OK
+     argument.  The return value is unpredictable.
+
+     If the previous nonblank line has no indent points beyond the
+     current column, this command does nothing.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Association Lists,  Next: Property Lists,  Prev: Sets And Lists,  Up: Lists
+File: lispref.info,  Node: Indent Tabs,  Next: Motion by Indent,  Prev: Relative Indent,  Up: Indentation
+
+Adjustable "Tab Stops"
+----------------------
+
+This section explains the mechanism for user-specified "tab stops" and
+the mechanisms that use and set them.  The name "tab stops" is used
+because the feature is similar to that of the tab stops on a
+typewriter.  The feature works by inserting an appropriate number of
+spaces and tab characters to reach the next tab stop column; it does not
+affect the display of tab characters in the buffer (*note Usual
+Display::).  Note that the <TAB> character as input uses this tab stop
+feature only in a few major modes, such as Text mode.
+
+ - Command: tab-to-tab-stop
+     This command inserts spaces or tabs up to the next tab stop column
+     defined by `tab-stop-list'.  It searches the list for an element
+     greater than the current column number, and uses that element as
+     the column to indent to.  It does nothing if no such element is
+     found.
+
+ - User Option: tab-stop-list
+     This variable is the list of tab stop columns used by
+     `tab-to-tab-stops'.  The elements should be integers in increasing
+     order.  The tab stop columns need not be evenly spaced.
+
+     Use `M-x edit-tab-stops' to edit the location of tab stops
+     interactively.

 
 

-Association Lists
-=================
+\1f
+File: lispref.info,  Node: Motion by Indent,  Prev: Indent Tabs,  Up: Indentation

 
 

-   An "association list", or "alist" for short, records a mapping from
-keys to values.  It is a list of cons cells called "associations": the
-CAR of each cell is the "key", and the CDR is the "associated value".(1)
-
-   Here is an example of an alist.  The key `pine' is associated with
-the value `cones'; the key `oak' is associated with `acorns'; and the
-key `maple' is associated with `seeds'.
-
-     '((pine . cones)
-       (oak . acorns)
-       (maple . seeds))
-
-   The associated values in an alist may be any Lisp objects; so may the
-keys.  For example, in the following alist, the symbol `a' is
-associated with the number `1', and the string `"b"' is associated with
-the _list_ `(2 3)', which is the CDR of the alist element:
-
-     ((a . 1) ("b" 2 3))
-
-   Sometimes it is better to design an alist to store the associated
-value in the CAR of the CDR of the element.  Here is an example:
-
-     '((rose red) (lily white) (buttercup yellow))
-
-Here we regard `red' as the value associated with `rose'.  One
-advantage of this method is that you can store other related
-information--even a list of other items--in the CDR of the CDR.  One
-disadvantage is that you cannot use `rassq' (see below) to find the
-element containing a given value.  When neither of these considerations
-is important, the choice is a matter of taste, as long as you are
-consistent about it for any given alist.
-
-   Note that the same alist shown above could be regarded as having the
-associated value in the CDR of the element; the value associated with
-`rose' would be the list `(red)'.
-
-   Association lists are often used to record information that you might
-otherwise keep on a stack, since new associations may be added easily to
-the front of the list.  When searching an association list for an
-association with a given key, the first one found is returned, if there
-is more than one.
-
-   In XEmacs Lisp, it is _not_ an error if an element of an association
-list is not a cons cell.  The alist search functions simply ignore such
-elements.  Many other versions of Lisp signal errors in such cases.
-
-   Note that property lists are similar to association lists in several
-respects.  A property list behaves like an association list in which
-each key can occur only once.  *Note Property Lists::, for a comparison
-of property lists and association lists.
-
- - Function: assoc key alist
-     This function returns the first association for KEY in ALIST.  It
-     compares KEY against the alist elements using `equal' (*note
-     Equality Predicates::).  It returns `nil' if no association in
-     ALIST has a CAR `equal' to KEY.  For example:
-
-          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-               => ((pine . cones) (oak . acorns) (maple . seeds))
-          (assoc 'oak trees)
-               => (oak . acorns)
-          (cdr (assoc 'oak trees))
-               => acorns
-          (assoc 'birch trees)
-               => nil
+Indentation-Based Motion Commands
+---------------------------------
+
+These commands, primarily for interactive use, act based on the
+indentation in the text.
+
+ - Command: back-to-indentation
+     This command moves point to the first non-whitespace character in
+     the current line (which is the line in which point is located).
+     It returns `nil'.
+
+ - Command: backward-to-indentation arg
+     This command moves point backward ARG lines and then to the first
+     nonblank character on that line.  It returns `nil'.
+
+ - Command: forward-to-indentation arg
+     This command moves point forward ARG lines and then to the first
+     nonblank character on that line.  It returns `nil'.

 
 

-     Here is another example, in which the keys and values are not
-     symbols:
+\1f
+File: lispref.info,  Node: Case Changes,  Next: Text Properties,  Prev: Indentation,  Up: Text
+
+Case Changes
+============
+
+The case change commands described here work on text in the current
+buffer.  *Note Character Case::, for case conversion commands that work
+on strings and characters.  *Note Case Tables::, for how to customize
+which characters are upper or lower case and how to convert them.
+
+ - Command: capitalize-region start end &optional buffer
+     This function capitalizes all words in the region defined by START
+     and END.  To capitalize means to convert each word's first
+     character to upper case and convert the rest of each word to lower
+     case.  The function returns `nil'.

 
 

-          (setq needles-per-cluster
-                '((2 "Austrian Pine" "Red Pine")
-                  (3 "Pitch Pine")
-                  (5 "White Pine")))
+     If one end of the region is in the middle of a word, the part of
+     the word within the region is treated as an entire word.
+
+     When `capitalize-region' is called interactively, START and END
+     are point and the mark, with the smallest first.
+
+          ---------- Buffer: foo ----------
+          This is the contents of the 5th foo.
+          ---------- Buffer: foo ----------

           
           

-          (cdr (assoc 3 needles-per-cluster))
-               => ("Pitch Pine")
-          (cdr (assoc 2 needles-per-cluster))
-               => ("Austrian Pine" "Red Pine")
-
- - Function: rassoc value alist
-     This function returns the first association with value VALUE in
-     ALIST.  It returns `nil' if no association in ALIST has a CDR
-     `equal' to VALUE.
-
-     `rassoc' is like `assoc' except that it compares the CDR of each
-     ALIST association instead of the CAR.  You can think of this as
-     "reverse `assoc'", finding the key for a given value.
-
- - Function: assq key alist
-     This function is like `assoc' in that it returns the first
-     association for KEY in ALIST, but it makes the comparison using
-     `eq' instead of `equal'.  `assq' returns `nil' if no association
-     in ALIST has a CAR `eq' to KEY.  This function is used more often
-     than `assoc', since `eq' is faster than `equal' and most alists
-     use symbols as keys.  *Note Equality Predicates::.
-
-          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-               => ((pine . cones) (oak . acorns) (maple . seeds))
-          (assq 'pine trees)
-               => (pine . cones)
-
-     On the other hand, `assq' is not usually useful in alists where the
-     keys may not be symbols:
-
-          (setq leaves
-                '(("simple leaves" . oak)
-                  ("compound leaves" . horsechestnut)))
+          (capitalize-region 1 44)
+          => nil

           
           

-          (assq "simple leaves" leaves)
-               => nil
-          (assoc "simple leaves" leaves)
-               => ("simple leaves" . oak)
+          ---------- Buffer: foo ----------
+          This Is The Contents Of The 5th Foo.
+          ---------- Buffer: foo ----------

 
 

- - Function: rassq value alist
-     This function returns the first association with value VALUE in
-     ALIST.  It returns `nil' if no association in ALIST has a CDR `eq'
-     to VALUE.
+ - Command: downcase-region start end &optional buffer
+     This function converts all of the letters in the region defined by
+     START and END to lower case.  The function returns `nil'.

 
 

-     `rassq' is like `assq' except that it compares the CDR of each
-     ALIST association instead of the CAR.  You can think of this as
-     "reverse `assq'", finding the key for a given value.
+     When `downcase-region' is called interactively, START and END are
+     point and the mark, with the smallest first.

 
 

-     For example:
+ - Command: upcase-region start end &optional buffer
+     This function converts all of the letters in the region defined by
+     START and END to upper case.  The function returns `nil'.

 
 

-          (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
-          
-          (rassq 'acorns trees)
-               => (oak . acorns)
-          (rassq 'spores trees)
-               => nil
+     When `upcase-region' is called interactively, START and END are
+     point and the mark, with the smallest first.
+
+ - Command: capitalize-word count &optional buffer
+     This function capitalizes COUNT words after point, moving point
+     over as it does.  To capitalize means to convert each word's first
+     character to upper case and convert the rest of each word to lower
+     case.  If COUNT is negative, the function capitalizes the -COUNT
+     previous words but does not move point.  The value is `nil'.
+
+     If point is in the middle of a word, the part of the word before
+     point is ignored when moving forward.  The rest is treated as an
+     entire word.
+
+     When `capitalize-word' is called interactively, COUNT is set to
+     the numeric prefix argument.
+
+ - Command: downcase-word count &optional buffer
+     This function converts the COUNT words after point to all lower
+     case, moving point over as it does.  If COUNT is negative, it
+     converts the -COUNT previous words but does not move point.  The
+     value is `nil'.
+
+     When `downcase-word' is called interactively, COUNT is set to the
+     numeric prefix argument.
+
+ - Command: upcase-word count &optional buffer
+     This function converts the COUNT words after point to all upper
+     case, moving point over as it does.  If COUNT is negative, it
+     converts the -COUNT previous words but does not move point.  The
+     value is `nil'.
+
+     When `upcase-word' is called interactively, COUNT is set to the
+     numeric prefix argument.
+
+\1f
+File: lispref.info,  Node: Text Properties,  Next: Substitution,  Prev: Case Changes,  Up: Text
+
+Text Properties
+===============
+
+Text properties are an alternative interface to extents (*note
+Extents::), and are built on top of them.  They are useful when you
+want to view textual properties as being attached to the characters
+themselves rather than to intervals of characters.  The text property
+interface is compatible with FSF Emacs.
+
+   Each character position in a buffer or a string can have a "text
+property list", much like the property list of a symbol (*note Property
+Lists::).  The properties belong to a particular character at a
+particular place, such as, the letter `T' at the beginning of this
+sentence or the first `o' in `foo'--if the same character occurs in two
+different places, the two occurrences generally have different
+properties.
+
+   Each property has a name and a value.  Both of these can be any Lisp
+object, but the name is normally a symbol.  The usual way to access the
+property list is to specify a name and ask what value corresponds to it.
+
+   Note that FSF Emacs also looks at the `category' property to find
+defaults for text properties.  We consider this too bogus to implement.
+
+   Copying text between strings and buffers preserves the properties
+along with the characters; this includes such diverse functions as
+`substring', `insert', and `buffer-substring'.
+
+* Menu:
+
+* Examining Properties::       Looking at the properties of one character.
+* Changing Properties::                Setting the properties of a range of text.
+* Property Search::            Searching for where a property changes value.
+* Special Properties::         Particular properties with special meanings.
+* Saving Properties::           Saving text properties in files, and reading
+                                  them back.
+
+\1f
+File: lispref.info,  Node: Examining Properties,  Next: Changing Properties,  Up: Text Properties
+
+Examining Text Properties
+-------------------------
+
+The simplest way to examine text properties is to ask for the value of
+a particular property of a particular character.  For that, use
+`get-text-property'.  Use `text-properties-at' to get the entire
+property list of a character.  *Note Property Search::, for functions
+to examine the properties of a number of characters at once.
+
+   These functions handle both strings and buffers.  (Keep in mind that
+positions in a string start from 0, whereas positions in a buffer start
+from 1.)
+
+ - Function: get-text-property pos prop &optional object at-flag
+     This function returns the value of the PROP property of the
+     character after position POS in OBJECT (a buffer or string).  The
+     argument OBJECT is optional and defaults to the current buffer.
+
+ - Function: get-char-property pos prop &optional object at-flag
+     This function is like `get-text-property', except that it checks
+     all extents, not just text-property extents.
+
+
+ - Function: text-properties-at position &optional object
+     This function returns the entire property list of the character at
+     POSITION in the string or buffer OBJECT.  If OBJECT is `nil', it
+     defaults to the current buffer.
+
+ - Variable: default-text-properties
+     This variable holds a property list giving default values for text
+     properties.  Whenever a character does not specify a value for a
+     property, the value stored in this list is used instead.  Here is
+     an example:
+
+          (setq default-text-properties '(foo 69))
+          ;; Make sure character 1 has no properties of its own.
+          (set-text-properties 1 2 nil)
+          ;; What we get, when we ask, is the default value.
+          (get-text-property 1 'foo)
+               => 69
+
+\1f
+File: lispref.info,  Node: Changing Properties,  Next: Property Search,  Prev: Examining Properties,  Up: Text Properties
+
+Changing Text Properties
+------------------------
+
+The primitives for changing properties apply to a specified range of
+text.  The function `set-text-properties' (see end of section) sets the
+entire property list of the text in that range; more often, it is
+useful to add, change, or delete just certain properties specified by
+name.
+
+   Since text properties are considered part of the buffer's contents,
+and can affect how the buffer looks on the screen, any change in the
+text properties is considered a buffer modification.  Buffer text
+property changes are undoable (*note Undo::).
+
+ - Function: put-text-property start end prop value &optional object
+     This function sets the PROP property to VALUE for the text between
+     START and END in the string or buffer OBJECT.  If OBJECT is `nil',
+     it defaults to the current buffer.
+
+ - Function: add-text-properties start end props &optional object
+     This function modifies the text properties for the text between
+     START and END in the string or buffer OBJECT.  If OBJECT is `nil',
+     it defaults to the current buffer.
+
+     The argument PROPS specifies which properties to change.  It
+     should have the form of a property list (*note Property Lists::):
+     a list whose elements include the property names followed
+     alternately by the corresponding values.
+
+     The return value is `t' if the function actually changed some
+     property's value; `nil' otherwise (if PROPS is `nil' or its values
+     agree with those in the text).
+
+     For example, here is how to set the `comment' and `face'
+     properties of a range of text:
+
+          (add-text-properties START END
+                               '(comment t face highlight))
+
+ - Function: remove-text-properties start end props &optional object
+     This function deletes specified text properties from the text
+     between START and END in the string or buffer OBJECT.  If OBJECT
+     is `nil', it defaults to the current buffer.
+
+     The argument PROPS specifies which properties to delete.  It
+     should have the form of a property list (*note Property Lists::):
+     a list whose elements are property names alternating with
+     corresponding values.  But only the names matter--the values that
+     accompany them are ignored.  For example, here's how to remove the
+     `face' property.
+
+          (remove-text-properties START END '(face nil))
+
+     The return value is `t' if the function actually changed some
+     property's value; `nil' otherwise (if PROPS is `nil' or if no
+     character in the specified text had any of those properties).
+
+ - Function: set-text-properties start end props &optional object
+     This function completely replaces the text property list for the
+     text between START and END in the string or buffer OBJECT.  If
+     OBJECT is `nil', it defaults to the current buffer.
+
+     The argument PROPS is the new property list.  It should be a list
+     whose elements are property names alternating with corresponding
+     values.
+
+     After `set-text-properties' returns, all the characters in the
+     specified range have identical properties.
+
+     If PROPS is `nil', the effect is to get rid of all properties from
+     the specified range of text.  Here's an example:
+
+          (set-text-properties START END nil)
+
+   See also the function `buffer-substring-without-properties' (*note
+Buffer Contents::) which copies text from the buffer but does not copy
+its properties.
+
+\1f
+File: lispref.info,  Node: Property Search,  Next: Special Properties,  Prev: Changing Properties,  Up: Text Properties
+
+Property Search Functions
+-------------------------
+
+In typical use of text properties, most of the time several or many
+consecutive characters have the same value for a property.  Rather than
+writing your programs to examine characters one by one, it is much
+faster to process chunks of text that have the same property value.
+
+   Here are functions you can use to do this.  They use `eq' for
+comparing property values.  In all cases, OBJECT defaults to the
+current buffer.
+
+   For high performance, it's very important to use the LIMIT argument
+to these functions, especially the ones that search for a single
+property--otherwise, they may spend a long time scanning to the end of
+the buffer, if the property you are interested in does not change.
+
+   Remember that a position is always between two characters; the
+position returned by these functions is between two characters with
+different properties.
+
+ - Function: next-property-change pos &optional object limit
+     The function scans the text forward from position POS in the
+     string or buffer OBJECT till it finds a change in some text
+     property, then returns the position of the change.  In other
+     words, it returns the position of the first character beyond POS
+     whose properties are not identical to those of the character just
+     after POS.
+
+     If LIMIT is non-`nil', then the scan ends at position LIMIT.  If
+     there is no property change before that point,
+     `next-property-change' returns LIMIT.
+
+     The value is `nil' if the properties remain unchanged all the way
+     to the end of OBJECT and LIMIT is `nil'.  If the value is
+     non-`nil', it is a position greater than or equal to POS.  The
+     value equals POS only when LIMIT equals POS.
+
+     Here is an example of how to scan the buffer by chunks of text
+     within which all properties are constant:
+
+          (while (not (eobp))
+            (let ((plist (text-properties-at (point)))
+                  (next-change
+                   (or (next-property-change (point) (current-buffer))
+                       (point-max))))
+              Process text from point to NEXT-CHANGE...
+              (goto-char next-change)))
+
+ - Function: next-single-property-change pos prop &optional object limit
+     The function scans the text forward from position POS in the
+     string or buffer OBJECT till it finds a change in the PROP
+     property, then returns the position of the change.  In other
+     words, it returns the position of the first character beyond POS
+     whose PROP property differs from that of the character just after
+     POS.
+
+     If LIMIT is non-`nil', then the scan ends at position LIMIT.  If
+     there is no property change before that point,
+     `next-single-property-change' returns LIMIT.
+
+     The value is `nil' if the property remains unchanged all the way to
+     the end of OBJECT and LIMIT is `nil'.  If the value is non-`nil',
+     it is a position greater than or equal to POS; it equals POS only
+     if LIMIT equals POS.
+
+ - Function: previous-property-change pos &optional object limit
+     This is like `next-property-change', but scans backward from POS
+     instead of forward.  If the value is non-`nil', it is a position
+     less than or equal to POS; it equals POS only if LIMIT equals POS.
+
+ - Function: previous-single-property-change pos prop &optional object
+          limit
+     This is like `next-single-property-change', but scans backward from
+     POS instead of forward.  If the value is non-`nil', it is a
+     position less than or equal to POS; it equals POS only if LIMIT
+     equals POS.
+
+ - Function: text-property-any start end prop value &optional object
+     This function returns non-`nil' if at least one character between
+     START and END has a property PROP whose value is VALUE.  More
+     precisely, it returns the position of the first such character.
+     Otherwise, it returns `nil'.
+
+     The optional fifth argument, OBJECT, specifies the string or
+     buffer to scan.  Positions are relative to OBJECT.  The default
+     for OBJECT is the current buffer.
+
+ - Function: text-property-not-all start end prop value &optional object
+     This function returns non-`nil' if at least one character between
+     START and END has a property PROP whose value differs from VALUE.
+     More precisely, it returns the position of the first such
+     character.  Otherwise, it returns `nil'.
+
+     The optional fifth argument, OBJECT, specifies the string or
+     buffer to scan.  Positions are relative to OBJECT.  The default
+     for OBJECT is the current buffer.
+
+\1f
+File: lispref.info,  Node: Special Properties,  Next: Saving Properties,  Prev: Property Search,  Up: Text Properties
+
+Properties with Special Meanings
+--------------------------------
+
+The predefined properties are the same as those for extents.  *Note
+Extent Properties::.
+
+\1f
+File: lispref.info,  Node: Saving Properties,  Prev: Special Properties,  Up: Text Properties
+
+Saving Text Properties in Files
+-------------------------------
+
+You can save text properties in files, and restore text properties when
+inserting the files, using these two hooks:
+
+ - Variable: write-region-annotate-functions
+     This variable's value is a list of functions for `write-region' to
+     run to encode text properties in some fashion as annotations to
+     the text being written in the file.  *Note Writing to Files::.
+
+     Each function in the list is called with two arguments: the start
+     and end of the region to be written.  These functions should not
+     alter the contents of the buffer.  Instead, they should return
+     lists indicating annotations to write in the file in addition to
+     the text in the buffer.
+
+     Each function should return 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.
+
+     Each list returned by one of these functions must be already
+     sorted in increasing order by POSITION.  If there is more than one
+     function, `write-region' merges the lists destructively into one
+     sorted list.
+
+     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.
+
+ - Variable: after-insert-file-functions
+     This variable holds a list of functions for `insert-file-contents'
+     to call after inserting a file's contents.  These functions should
+     scan the inserted text for annotations, and convert them to the
+     text properties they stand for.
+
+     Each function receives one argument, the length of the inserted
+     text; point indicates the start of that text.  The function should
+     scan that text for annotations, delete them, and create the text
+     properties that the annotations specify.  The function should
+     return the updated length of the inserted text, as it stands after
+     those changes.  The value returned by one function becomes the
+     argument to the next function.
+
+     These functions should always return with point at the beginning of
+     the inserted text.
+
+     The intended use of `after-insert-file-functions' is for converting
+     some sort of textual annotations into actual text properties.  But
+     other uses may be possible.
+
+   We invite users to write Lisp programs to store and retrieve text
+properties in files, using these hooks, and thus to experiment with
+various data formats and find good ones.  Eventually we hope users will
+produce good, general extensions we can install in Emacs.
+
+   We suggest not trying to handle arbitrary Lisp objects as property
+names or property values--because a program that general is probably
+difficult to write, and slow.  Instead, choose a set of possible data
+types that are reasonably flexible, and not too hard to encode.
+
+   *Note Format Conversion::, for a related feature.
+
+\1f
+File: lispref.info,  Node: Substitution,  Next: Registers,  Prev: Text Properties,  Up: Text
+
+Substituting for a Character Code
+=================================

 
 

-     Note that `rassq' cannot search for a value stored in the CAR of
-     the CDR of an element:
+The following functions replace characters within a specified region
+based on their character codes.

 
 

-          (setq colors '((rose red) (lily white) (buttercup yellow)))
+ - Function: subst-char-in-region start end old-char new-char &optional
+          noundo
+     This function replaces all occurrences of the character OLD-CHAR
+     with the character NEW-CHAR in the region of the current buffer
+     defined by START and END.
+
+     If NOUNDO is non-`nil', then `subst-char-in-region' does not
+     record the change for undo and does not mark the buffer as
+     modified.  This feature is used for controlling selective display
+     (*note Selective Display::).
+
+     `subst-char-in-region' does not move point and returns `nil'.
+
+          ---------- Buffer: foo ----------
+          This is the contents of the buffer before.
+          ---------- Buffer: foo ----------

           
           

-          (rassq 'white colors)
+          (subst-char-in-region 1 20 ?i ?X)

                => nil
                => nil

-
-     In this case, the CDR of the association `(lily white)' is not the
-     symbol `white', but rather the list `(white)'.  This becomes
-     clearer if the association is written in dotted pair notation:
-
-          (lily white) == (lily . (white))
-
- - Function: remassoc key alist
-     This function deletes by side effect any associations with key KEY
-     in ALIST--i.e. it removes any elements from ALIST whose `car' is
-     `equal' to KEY.  The modified ALIST is returned.
-
-     If the first member of ALIST has a `car' that is `equal' to KEY,
-     there is no way to remove it by side effect; therefore, write
-     `(setq foo (remassoc key foo))' to be sure of changing the value
-     of `foo'.
-
- - Function: remassq key alist
-     This function deletes by side effect any associations with key KEY
-     in ALIST--i.e. it removes any elements from ALIST whose `car' is
-     `eq' to KEY.  The modified ALIST is returned.
-
-     This function is exactly like `remassoc', but comparisons between
-     KEY and keys in ALIST are done using `eq' instead of `equal'.
-
- - Function: remrassoc value alist
-     This function deletes by side effect any associations with value
-     VALUE in ALIST--i.e. it removes any elements from ALIST whose
-     `cdr' is `equal' to VALUE.  The modified ALIST is returned.
-
-     If the first member of ALIST has a `car' that is `equal' to VALUE,
-     there is no way to remove it by side effect; therefore, write
-     `(setq foo (remassoc value foo))' to be sure of changing the value
-     of `foo'.
-
-     `remrassoc' is like `remassoc' except that it compares the CDR of
-     each ALIST association instead of the CAR.  You can think of this
-     as "reverse `remassoc'", removing an association based on its
-     value instead of its key.
-
- - Function: remrassq value alist
-     This function deletes by side effect any associations with value
-     VALUE in ALIST--i.e. it removes any elements from ALIST whose
-     `cdr' is `eq' to VALUE.  The modified ALIST is returned.
-
-     This function is exactly like `remrassoc', but comparisons between
-     VALUE and values in ALIST are done using `eq' instead of `equal'.
-
- - Function: copy-alist alist
-     This function returns a two-level deep copy of ALIST: it creates a
-     new copy of each association, so that you can alter the
-     associations of the new alist without changing the old one.
-
-          (setq needles-per-cluster
-                '((2 . ("Austrian Pine" "Red Pine"))
-                  (3 . ("Pitch Pine"))
-                  (5 . ("White Pine"))))
-          =>
-          ((2 "Austrian Pine" "Red Pine")
-           (3 "Pitch Pine")
-           (5 "White Pine"))

           
           

-          (setq copy (copy-alist needles-per-cluster))
-          =>
-          ((2 "Austrian Pine" "Red Pine")
-           (3 "Pitch Pine")
-           (5 "White Pine"))
+          ---------- Buffer: foo ----------
+          ThXs Xs the contents of the buffer before.
+          ---------- Buffer: foo ----------
+
+ - Function: translate-region start end table
+     This function applies a translation table to the characters in the
+     buffer between positions START and END.  The translation table
+     TABLE can be either a string, a vector, or a char-table.
+
+     If TABLE is a string, its Nth element is the mapping for the
+     character with code N.
+
+     If TABLE is a vector, its Nth element is the mapping for character
+     with code N.  Legal mappings are characters, strings, or `nil'
+     (meaning don't replace.)
+
+     If TABLE is a char-table, its elements describe the mapping
+     between characters and their replacements.  The char-table should
+     be of type `char' or `generic'.
+
+     When the TABLE is a string or vector and its length is less than
+     the total number of characters (256 without Mule), any characters
+     with codes larger than the length of TABLE are not altered by the
+     translation.
+
+     The return value of `translate-region' is the number of characters
+     that were actually changed by the translation.  This does not
+     count characters that were mapped into themselves in the
+     translation table.
+
+     *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
+     to be a string.  This is still the case in FSF Emacs.
+
+     The following example creates a char-table that is passed to
+     `translate-region', which translates character `a' to `the letter
+     a', removes character `b', and translates character `c' to newline.
+
+          ---------- Buffer: foo ----------
+          Here is a sentence in the buffer.
+          ---------- Buffer: foo ----------

           
           

-          (eq needles-per-cluster copy)
-               => nil
-          (equal needles-per-cluster copy)
-               => t
-          (eq (car needles-per-cluster) (car copy))
-               => nil
-          (cdr (car (cdr needles-per-cluster)))
-               => ("Pitch Pine")
-          (eq (cdr (car (cdr needles-per-cluster)))
-              (cdr (car (cdr copy))))
-               => t
+          (let ((table (make-char-table 'generic)))
+            (put-char-table ?a "the letter a" table)
+            (put-char-table ?b "" table)
+            (put-char-table ?c ?\n table)
+            (translate-region (point-min) (point-max) table))
+               => 3
+          
+          ---------- Buffer: foo ----------
+          Here is the letter a senten
+          e in the uffer.
+          ---------- Buffer: foo ----------
+
+\1f
+File: lispref.info,  Node: Registers,  Next: Transposition,  Prev: Substitution,  Up: Text
+
+Registers
+=========
+
+A register is a sort of variable used in XEmacs editing that can hold a
+marker, a string, a rectangle, a window configuration (of one frame), or
+a frame configuration (of all frames).  Each register is named by a
+single character.  All characters, including control and meta characters
+(but with the exception of `C-g'), can be used to name registers.
+Thus, there are 255 possible registers.  A register is designated in
+Emacs Lisp by a character that is its name.
+
+   The functions in this section return unpredictable values unless
+otherwise stated.
+
+ - Variable: register-alist
+     This variable is an alist of elements of the form `(NAME .
+     CONTENTS)'.  Normally, there is one element for each XEmacs
+     register that has been used.
+
+     The object NAME is a character (an integer) identifying the
+     register.  The object CONTENTS is a string, marker, or list
+     representing the register contents.  A string represents text
+     stored in the register.  A marker represents a position.  A list
+     represents a rectangle; its elements are strings, one per line of
+     the rectangle.
+
+ - Function: get-register register
+     This function returns the contents of the register REGISTER, or
+     `nil' if it has no contents.
+
+ - Function: set-register register value
+     This function sets the contents of register REGISTER to VALUE.  A
+     register can be set to any value, but the other register functions
+     expect only certain data types.  The return value is VALUE.
+
+ - Command: view-register register
+     This command displays what is contained in register REGISTER.
+
+ - Command: insert-register register &optional beforep
+     This command inserts contents of register REGISTER into the current
+     buffer.
+
+     Normally, this command puts point before the inserted text, and the
+     mark after it.  However, if the optional second argument BEFOREP
+     is non-`nil', it puts the mark before and point after.  You can
+     pass a non-`nil' second argument BEFOREP to this function
+     interactively by supplying any prefix argument.
+
+     If the register contains a rectangle, then the rectangle is
+     inserted with its upper left corner at point.  This means that
+     text is inserted in the current line and underneath it on
+     successive lines.
+
+     If the register contains something other than saved text (a
+     string) or a rectangle (a list), currently useless things happen.
+     This may be changed in the future.

 
 

-     This example shows how `copy-alist' makes it possible to change
-     the associations of one copy without affecting the other:
+\1f
+File: lispref.info,  Node: Transposition,  Next: Change Hooks,  Prev: Registers,  Up: Text
+
+Transposition of Text
+=====================

 
 

-          (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
-          (cdr (assq 3 needles-per-cluster))
-               => ("Pitch Pine")
+This subroutine is used by the transposition commands.

 
 

-   ---------- Footnotes ----------
+ - Function: transpose-regions start1 end1 start2 end2 &optional
+          leave-markers
+     This function exchanges two nonoverlapping portions of the buffer.
+     Arguments START1 and END1 specify the bounds of one portion and
+     arguments START2 and END2 specify the bounds of the other portion.

 
 

-   (1) This usage of "key" is not related to the term "key sequence";
-it means a value used to look up an item in a table.  In this case, the
-table is the alist, and the alist associations are the items.
+     Normally, `transpose-regions' relocates markers with the transposed
+     text; a marker previously positioned within one of the two
+     transposed portions moves along with that portion, thus remaining
+     between the same two characters in their new position.  However,
+     if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
+     this--it leaves all markers unrelocated.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Property Lists,  Next: Weak Lists,  Prev: Association Lists,  Up: Lists
+File: lispref.info,  Node: Change Hooks,  Next: Transformations,  Prev: Transposition,  Up: Text
+
+Change Hooks
+============
+
+These hook variables let you arrange to take notice of all changes in
+all buffers (or in a particular buffer, if you make them buffer-local).
+
+   The functions you use in these hooks should save and restore the
+match data if they do anything that uses regular expressions;
+otherwise, they will interfere in bizarre ways with the editing
+operations that call them.
+
+   Buffer changes made while executing the following hooks don't
+themselves cause any change hooks to be invoked.
+
+ - Variable: before-change-functions
+     This variable holds a list of a functions to call before any buffer
+     modification.  Each function gets two arguments, the beginning and
+     end of the region that is about to change, represented as
+     integers.  The buffer that is about to change is always the
+     current buffer.
+
+ - Variable: after-change-functions
+     This variable holds a list of a functions to call after any buffer
+     modification.  Each function receives three arguments: the
+     beginning and end of the region just changed, and the length of
+     the text that existed before the change.  (To get the current
+     length, subtract the region beginning from the region end.)  All
+     three arguments are integers.  The buffer that's about to change
+     is always the current buffer.
+
+ - Variable: before-change-function
+     This obsolete variable holds one function to call before any buffer
+     modification (or `nil' for no function).  It is called just like
+     the functions in `before-change-functions'.
+
+ - Variable: after-change-function
+     This obsolete variable holds one function to call after any buffer
+     modification (or `nil' for no function).  It is called just like
+     the functions in `after-change-functions'.
+
+ - Variable: first-change-hook
+     This variable is a normal hook that is run whenever a buffer is
+     changed that was previously in the unmodified state.

 
 

-Property Lists
-==============
+\1f
+File: lispref.info,  Node: Transformations,  Prev: Change Hooks,  Up: Text
+
+Textual transformations--MD5 and base64 support
+===============================================
+
+Some textual operations inherently require examining each character in
+turn, and performing arithmetic operations on them.  Such operations
+can, of course, be implemented in Emacs Lisp, but tend to be very slow
+for large portions of text or data.  This is why some of them are
+implemented in C, with an appropriate interface for Lisp programmers.
+Examples of algorithms thus provided are MD5 and base64 support.
+
+   MD5 is an algorithm for calculating message digests, as described in
+rfc1321.  Given a message of arbitrary length, MD5 produces a 128-bit
+"fingerprint" ("message digest") corresponding to that message.  It is
+considered computationally infeasible to produce two messages having
+the same MD5 digest, or to produce a message having a prespecified
+target digest.  MD5 is used heavily by various authentication schemes.
+
+   Emacs Lisp interface to MD5 consists of a single function `md5':
+
+ - Function: md5 object &optional start end coding noerror
+     This function returns the MD5 message digest of OBJECT, a buffer
+     or string.
+
+     Optional arguments START and END denote positions for computing
+     the digest of a portion of OBJECT.
+
+     The optional CODING argument specifies the coding system the text
+     is to be represented in while computing the digest.  If
+     unspecified, it defaults to the current format of the data, or is
+     guessed.
+
+     If NOERROR is non-`nil', silently assume binary coding if the
+     guesswork fails.  Normally, an error is signaled in such case.
+
+     CODING and NOERROR arguments are meaningful only in XEmacsen with
+     file-coding or Mule support.  Otherwise, they are ignored.  Some
+     examples of usage:
+
+          ;; Calculate the digest of the entire buffer
+          (md5 (current-buffer))
+               => "8842b04362899b1cda8d2d126dc11712"
+          
+          ;; Calculate the digest of the current line
+          (md5 (current-buffer) (point-at-bol) (point-at-eol))
+               => "60614d21e9dee27dfdb01fa4e30d6d00"
+          
+          ;; Calculate the digest of your name and email address
+          (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address)))
+               => "0a2188c40fd38922d941fe6032fce516"
+
+   Base64 is a portable encoding for arbitrary sequences of octets, in a
+form that need not be readable by humans.  It uses a 65-character subset
+of US-ASCII, as described in rfc2045.  Base64 is used by MIME to encode
+binary bodies, and to encode binary characters in message headers.
+
+   The Lisp interface to base64 consists of four functions:
+
+ - Command: base64-encode-region start end &optional no-line-break
+     This function encodes the region between START and END of the
+     current buffer to base64 format.  This means that the original
+     region is deleted, and replaced with its base64 equivalent.
+
+     Normally, encoded base64 output is multi-line, with 76-character
+     lines.  If NO-LINE-BREAK is non-`nil', newlines will not be
+     inserted, resulting in single-line output.

 
 

-   A "property list" (or "plist") is another way of representing a
-mapping from keys to values.  Instead of the list consisting of conses
-of a key and a value, the keys and values alternate as successive
-entries in the list.  Thus, the association list
+     Mule note: you should make sure that you convert the multibyte
+     characters (those that do not fit into 0-255 range) to something
+     else, because they cannot be meaningfully converted to base64.  If
+     the `base64-encode-region' encounters such characters, it will
+     signal an error.

 
 

-     ((a . 1) (b . 2) (c . 3))
+     `base64-encode-region' returns the length of the encoded text.

 
 

-   has the equivalent property list form
+          ;; Encode the whole buffer in base64
+          (base64-encode-region (point-min) (point-max))

 
 

-     (a 1 b 2 c 3)
+     The function can also be used interactively, in which case it
+     works on the currently active region.

 
 

-   Property lists are used to represent the properties associated with
-various sorts of objects, such as symbols, strings, frames, etc.  The
-convention is that property lists can be modified in-place, while
-association lists generally are not.
+ - Function: base64-encode-string string &optional no-line-break
+     This function encodes STRING to base64, and returns the encoded
+     string.

 
 

-   Plists come in two varieties: "normal" plists, whose keys are
-compared with `eq', and "lax" plists, whose keys are compared with
-`equal',
+     Normally, encoded base64 output is multi-line, with 76-character
+     lines.  If NO-LINE-BREAK is non-`nil', newlines will not be
+     inserted, resulting in single-line output.

 
 

- - Function: valid-plist-p plist
-     Given a plist, this function returns non-`nil' if its format is
-     correct.  If it returns `nil', `check-valid-plist' will signal an
-     error when given the plist; that means it's a malformed or circular
-     plist or has non-symbols as keywords.
+     For Mule, the same considerations apply as for
+     `base64-encode-region'.

 
 

- - Function: check-valid-plist plist
-     Given a plist, this function signals an error if there is anything
-     wrong with it.  This means that it's a malformed or circular plist.
+          (base64-encode-string "fubar")
+              => "ZnViYXI="
+
+ - Command: base64-decode-region start end
+     This function decodes the region between START and END of the
+     current buffer.  The region should be in base64 encoding.
+
+     If the region was decoded correctly, `base64-decode-region' returns
+     the length of the decoded region.  If the decoding failed, `nil' is
+     returned.
+
+          ;; Decode a base64 buffer, and replace it with the decoded version
+          (base64-decode-region (point-min) (point-max))
+
+ - Function: base64-decode-string string
+     This function decodes STRING to base64, and returns the decoded
+     string.  STRING should be valid base64-encoded text.
+
+     If encoding was not possible, `nil' is returned.
+
+          (base64-decode-string "ZnViYXI=")
+              => "fubar"
+          
+          (base64-decode-string "totally bogus")
+              => nil
+
+\1f
+File: lispref.info,  Node: Searching and Matching,  Next: Syntax Tables,  Prev: Text,  Up: Top
+
+Searching and Matching
+**********************
+
+XEmacs provides two ways to search through a buffer for specified text:
+exact string searches and regular expression searches.  After a regular
+expression search, you can examine the "match data" to determine which
+text matched the whole regular expression or various portions of it.

 
 * Menu:
 
 
 * Menu:
 

-* Working With Normal Plists::       Functions for normal plists.
-* Working With Lax Plists::          Functions for lax plists.
-* Converting Plists To/From Alists:: Alist to plist and vice-versa.
+* String Search::         Search for an exact match.
+* Regular Expressions::   Describing classes of strings.
+* Regexp Search::         Searching for a match for a regexp.
+* POSIX Regexps::         Searching POSIX-style for the longest match.
+* Search and Replace::   Internals of `query-replace'.
+* Match Data::            Finding out which part of the text matched
+                            various parts of a regexp, after regexp search.
+* Searching and Case::    Case-independent or case-significant searching.
+* Standard Regexps::      Useful regexps for finding sentences, pages,...
+
+   The `skip-chars...' functions also perform a kind of searching.
+*Note Skipping Characters::.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Working With Normal Plists,  Next: Working With Lax Plists,  Up: Property Lists
+File: lispref.info,  Node: String Search,  Next: Regular Expressions,  Up: Searching and Matching

 
 

-Working With Normal Plists
---------------------------
+Searching for Strings
+=====================
+
+These are the primitive functions for searching through the text in a
+buffer.  They are meant for use in programs, but you may call them
+interactively.  If you do so, they prompt for the search string; LIMIT
+and NOERROR are set to `nil', and COUNT is set to 1.

 
 

- - Function: plist-get plist property &optional default
-     This function extracts a value from a property list.  The function
-     returns the value corresponding to the given PROPERTY, or DEFAULT
-     if PROPERTY is not one of the properties on the list.
+ - Command: search-forward string &optional limit noerror count buffer
+     This function searches forward from point for an exact match for
+     STRING.  If successful, it sets point to the end of the occurrence
+     found, and returns the new value of point.  If no match is found,
+     the value and side effects depend on NOERROR (see below).

 
 

- - Function: plist-put plist property value
-     This function changes the value in PLIST of PROPERTY to VALUE.  If
-     PROPERTY is already a property on the list, its value is set to
-     VALUE, otherwise the new PROPERTY VALUE pair is added.  The new
-     plist is returned; use `(setq x (plist-put x property value))' to
-     be sure to use the new value.  The PLIST is modified by side
-     effects.
+     In the following example, point is initially at the beginning of
+     the line.  Then `(search-forward "fox")' moves point after the last
+     letter of `fox':

 
 

- - Function: plist-remprop plist property
-     This function removes from PLIST the property PROPERTY and its
-     value.  The new plist is returned; use `(setq x (plist-remprop x
-     property))' to be sure to use the new value.  The PLIST is
-     modified by side effects.
+          ---------- Buffer: foo ----------
+          -!-The quick brown fox jumped over the lazy dog.
+          ---------- Buffer: foo ----------
+          
+          (search-forward "fox")
+               => 20
+          
+          ---------- Buffer: foo ----------
+          The quick brown fox-!- jumped over the lazy dog.
+          ---------- Buffer: foo ----------
+
+     The argument LIMIT specifies the upper bound to the search.  (It
+     must be a position in the current buffer.)  No match extending
+     after that position is accepted.  If LIMIT is omitted or `nil', it
+     defaults to the end of the accessible portion of the buffer.
+
+     What happens when the search fails depends on the value of
+     NOERROR.  If NOERROR is `nil', a `search-failed' error is
+     signaled.  If NOERROR is `t', `search-forward' returns `nil' and
+     does nothing.  If NOERROR is neither `nil' nor `t', then
+     `search-forward' moves point to the upper bound and returns `nil'.
+     (It would be more consistent now to return the new position of
+     point in that case, but some programs may depend on a value of
+     `nil'.)
+
+     If COUNT is supplied (it must be an integer), then the search is
+     repeated that many times (each time starting at the end of the
+     previous time's match).  If COUNT is negative, the search
+     direction is backward.  If the successive searches succeed, the
+     function succeeds, moving point and returning its new value.
+     Otherwise the search fails.
+
+     BUFFER is the buffer to search in, and defaults to the current
+     buffer.
+
+ - Command: search-backward string &optional limit noerror count buffer
+     This function searches backward from point for STRING.  It is just
+     like `search-forward' except that it searches backwards and leaves
+     point at the beginning of the match.
+
+ - Command: word-search-forward string &optional limit noerror count
+          buffer
+     This function searches forward from point for a "word" match for
+     STRING.  If it finds a match, it sets point to the end of the
+     match found, and returns the new value of point.
+
+     Word matching regards STRING as a sequence of words, disregarding
+     punctuation that separates them.  It searches the buffer for the
+     same sequence of words.  Each word must be distinct in the buffer
+     (searching for the word `ball' does not match the word `balls'),
+     but the details of punctuation and spacing are ignored (searching
+     for `ball boy' does match `ball.  Boy!').
+
+     In this example, point is initially at the beginning of the
+     buffer; the search leaves it between the `y' and the `!'.
+
+          ---------- Buffer: foo ----------
+          -!-He said "Please!  Find
+          the ball boy!"
+          ---------- Buffer: foo ----------
+          
+          (word-search-forward "Please find the ball, boy.")
+               => 35
+          
+          ---------- Buffer: foo ----------
+          He said "Please!  Find
+          the ball boy-!-!"
+          ---------- Buffer: foo ----------
+
+     If LIMIT is non-`nil' (it must be a position in the current
+     buffer), then it is the upper bound to the search.  The match
+     found must not extend after that position.
+
+     If NOERROR is `nil', then `word-search-forward' signals an error
+     if the search fails.  If NOERROR is `t', then it returns `nil'
+     instead of signaling an error.  If NOERROR is neither `nil' nor
+     `t', it moves point to LIMIT (or the end of the buffer) and
+     returns `nil'.
+
+     If COUNT is non-`nil', then the search is repeated that many
+     times.  Point is positioned at the end of the last match.
+
+     BUFFER is the buffer to search in, and defaults to the current
+     buffer.
+
+ - Command: word-search-backward string &optional limit noerror count
+          buffer
+     This function searches backward from point for a word match to
+     STRING.  This function is just like `word-search-forward' except
+     that it searches backward and normally leaves point at the
+     beginning of the match.

 
 

- - Function: plist-member plist property
-     This function returns `t' if PROPERTY has a value specified in
-     PLIST.
+\1f
+File: lispref.info,  Node: Regular Expressions,  Next: Regexp Search,  Prev: String Search,  Up: Searching and Matching

 
 

-   In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
-non-`nil', then a property with a `nil' value is ignored or removed.
-This feature is a virus that has infected old Lisp implementations (and
-thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
-used except for backward compatibility.
+Regular Expressions
+===================

 
 

- - Function: plists-eq a b &optional nil-means-not-present
-     This function returns non-`nil' if property lists A and B are `eq'
-     (i.e. their values are `eq').
+A "regular expression" ("regexp", for short) is a pattern that denotes
+a (possibly infinite) set of strings.  Searching for matches for a
+regexp is a very powerful operation.  This section explains how to write
+regexps; the following section says how to search for them.
+
+   To gain a thorough understanding of regular expressions and how to
+use them to best advantage, we recommend that you study `Mastering
+Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
+1997'. (It's known as the "Hip Owls" book, because of the picture on its
+cover.)  You might also read the manuals to *Note (gawk)Top::, *Note
+(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
+(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
+regular expressions.
+
+   The XEmacs regular expression syntax most closely resembles that of
+`ed', or `grep', the GNU versions of which all utilize the GNU `regex'
+library.  XEmacs' version of `regex' has recently been extended with
+some Perl-like capabilities, described in the next section.

 
 

- - Function: plists-equal a b &optional nil-means-not-present
-     This function returns non-`nil' if property lists A and B are
-     `equal' (i.e. their values are `equal'; their keys are still
-     compared using `eq').
+* Menu:

 
 

- - Function: canonicalize-plist plist &optional nil-means-not-present
-     This function destructively removes any duplicate entries from a
-     plist.  In such cases, the first entry applies.
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.

 
 

-     The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
-     return value may not be `eq' to the passed-in value, so make sure
-     to `setq' the value back into where it came from.
+\1f
+File: lispref.info,  Node: Syntax of Regexps,  Next: Regexp Example,  Up: Regular Expressions
+
+Syntax of Regular Expressions
+-----------------------------
+
+Regular expressions have a syntax in which a few characters are special
+constructs and the rest are "ordinary".  An ordinary character is a
+simple regular expression that matches that character and nothing else.
+The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and
+`\'; no new special characters will be defined in the future.  Any
+other character appearing in a regular expression is ordinary, unless a
+`\' precedes it.
+
+   For example, `f' is not a special character, so it is ordinary, and
+therefore `f' is a regular expression that matches the string `f' and
+no other string.  (It does _not_ match the string `ff'.)  Likewise, `o'
+is a regular expression that matches only `o'.
+
+   Any two regular expressions A and B can be concatenated.  The result
+is a regular expression that matches a string if A matches some amount
+of the beginning of that string and B matches the rest of the string.
+
+   As a simple example, we can concatenate the regular expressions `f'
+and `o' to get the regular expression `fo', which matches only the
+string `fo'.  Still trivial.  To do something more powerful, you need
+to use one of the special characters.  Here is a list of them:
+
+`. (Period)'
+     is a special character that matches any single character except a
+     newline.  Using concatenation, we can make regular expressions
+     like `a.b', which matches any three-character string that begins
+     with `a' and ends with `b'.
+
+`*'
+     is not a construct by itself; it is a quantifying suffix operator
+     that means to repeat the preceding regular expression as many
+     times as possible.  In `fo*', the `*' applies to the `o', so `fo*'
+     matches one `f' followed by any number of `o's.  The case of zero
+     `o's is allowed: `fo*' does match `f'.
+
+     `*' always applies to the _smallest_ possible preceding
+     expression.  Thus, `fo*' has a repeating `o', not a repeating `fo'.
+
+     The matcher processes a `*' construct by matching, immediately, as
+     many repetitions as can be found; it is "greedy".  Then it
+     continues with the rest of the pattern.  If that fails,
+     backtracking occurs, discarding some of the matches of the
+     `*'-modified construct in case that makes it possible to match the
+     rest of the pattern.  For example, in matching `ca*ar' against the
+     string `caaar', the `a*' first tries to match all three `a's; but
+     the rest of the pattern is `ar' and there is only `r' left to
+     match, so this try fails.  The next alternative is for `a*' to
+     match only two `a's.  With this choice, the rest of the regexp
+     matches successfully.
+
+     Nested repetition operators can be extremely slow if they specify
+     backtracking loops.  For example, it could take hours for the
+     regular expression `\(x+y*\)*a' to match the sequence
+     `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'.  The slowness is because
+     Emacs must try each imaginable way of grouping the 35 `x''s before
+     concluding that none of them can work.  To make sure your regular
+     expressions run fast, check nested repetitions carefully.
+
+`+'
+     is a quantifying suffix operator similar to `*' except that the
+     preceding expression must match at least once.  It is also
+     "greedy".  So, for example, `ca+r' matches the strings `car' and
+     `caaaar' but not the string `cr', whereas `ca*r' matches all three
+     strings.
+
+`?'
+     is a quantifying suffix operator similar to `*', except that the
+     preceding expression can match either once or not at all.  For
+     example, `ca?r' matches `car' or `cr', but does not match anything
+     else.
+
+`*?'
+     works just like `*', except that rather than matching the longest
+     match, it matches the shortest match.  `*?' is known as a
+     "non-greedy" quantifier, a regexp construct borrowed from Perl.
+
+     This construct is very useful for when you want to match the text
+     inside a pair of delimiters.  For instance, `/\*.*?\*/' will match
+     C comments in a string.  This could not easily be achieved without
+     the use of a non-greedy quantifier.
+
+     This construct has not been available prior to XEmacs 20.4.  It is
+     not available in FSF Emacs.
+
+`+?'
+     is the non-greedy version of `+'.
+
+`??'
+     is the non-greedy version of `?'.
+
+`\{n,m\}'
+     serves as an interval quantifier, analogous to `*' or `+', but
+     specifies that the expression must match at least N times, but no
+     more than M times.  This syntax is supported by most Unix regexp
+     utilities, and has been introduced to XEmacs for the version 20.3.
+
+     Unfortunately, the non-greedy version of this quantifier does not
+     exist currently, although it does in Perl.
+
+`[ ... ]'
+     `[' begins a "character set", which is terminated by a `]'.  In
+     the simplest case, the characters between the two brackets form
+     the set.  Thus, `[ad]' matches either one `a' or one `d', and
+     `[ad]*' matches any string composed of just `a's and `d's
+     (including the empty string), from which it follows that `c[ad]*r'
+     matches `cr', `car', `cdr', `caddaar', etc.
+
+     The usual regular expression special characters are not special
+     inside a character set.  A completely different set of special
+     characters exists inside character sets: `]', `-' and `^'.
+
+     `-' is used for ranges of characters.  To write a range, write two
+     characters with a `-' between them.  Thus, `[a-z]' matches any
+     lower case letter.  Ranges may be intermixed freely with individual
+     characters, as in `[a-z$%.]', which matches any lower case letter
+     or `$', `%', or a period.
+
+     To include a `]' in a character set, make it the first character.
+     For example, `[]a]' matches `]' or `a'.  To include a `-', write
+     `-' as the first character in the set, or put it immediately after
+     a range.  (You can replace one individual character C with the
+     range `C-C' to make a place to put the `-'.)  There is no way to
+     write a set containing just `-' and `]'.
+
+     To include `^' in a set, put it anywhere but at the beginning of
+     the set.
+
+`[^ ... ]'
+     `[^' begins a "complement character set", which matches any
+     character except the ones specified.  Thus, `[^a-z0-9A-Z]' matches
+     all characters _except_ letters and digits.
+
+     `^' is not special in a character set unless it is the first
+     character.  The character following the `^' is treated as if it
+     were first (thus, `-' and `]' are not special there).
+
+     Note that a complement character set can match a newline, unless
+     newline is mentioned as one of the characters not to match.
+
+`^'
+     is a special character that matches the empty string, but only at
+     the beginning of a line in the text being matched.  Otherwise it
+     fails to match anything.  Thus, `^foo' matches a `foo' that occurs
+     at the beginning of a line.
+
+     When matching a string instead of a buffer, `^' matches at the
+     beginning of the string or after a newline character `\n'.
+
+`$'
+     is similar to `^' but matches only at the end of a line.  Thus,
+     `x+$' matches a string of one `x' or more at the end of a line.
+
+     When matching a string instead of a buffer, `$' matches at the end
+     of the string or before a newline character `\n'.
+
+`\'
+     has two functions: it quotes the special characters (including
+     `\'), and it introduces additional special constructs.
+
+     Because `\' quotes special characters, `\$' is a regular
+     expression that matches only `$', and `\[' is a regular expression
+     that matches only `[', and so on.
+
+     Note that `\' also has special meaning in the read syntax of Lisp
+     strings (*note String Type::), and must be quoted with `\'.  For
+     example, the regular expression that matches the `\' character is
+     `\\'.  To write a Lisp string that contains the characters `\\',
+     Lisp syntax requires you to quote each `\' with another `\'.
+     Therefore, the read syntax for a regular expression matching `\'
+     is `"\\\\"'.
+
+   *Please note:* For historical compatibility, special characters are
+treated as ordinary ones if they are in contexts where their special
+meanings make no sense.  For example, `*foo' treats `*' as ordinary
+since there is no preceding expression on which the `*' can act.  It is
+poor practice to depend on this behavior; quote the special character
+anyway, regardless of where it appears.
+
+   For the most part, `\' followed by any character matches only that
+character.  However, there are several exceptions: characters that,
+when preceded by `\', are special constructs.  Such characters are
+always ordinary when encountered on their own.  Here is a table of `\'
+constructs:
+
+`\|'
+     specifies an alternative.  Two regular expressions A and B with
+     `\|' in between form an expression that matches anything that
+     either A or B matches.
+
+     Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
+
+     `\|' applies to the largest possible surrounding expressions.
+     Only a surrounding `\( ... \)' grouping can limit the grouping
+     power of `\|'.
+
+     Full backtracking capability exists to handle multiple uses of
+     `\|'.
+
+`\( ... \)'
+     is a grouping construct that serves three purposes:
+
+       1. To enclose a set of `\|' alternatives for other operations.
+          Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
+
+       2. To enclose an expression for a suffix operator such as `*' to
+          act on.  Thus, `ba\(na\)*' matches `bananana', etc., with any
+          (zero or more) number of `na' strings.
+
+       3. To record a matched substring for future reference.
+
+     This last application is not a consequence of the idea of a
+     parenthetical grouping; it is a separate feature that happens to be
+     assigned as a second meaning to the same `\( ... \)' construct
+     because there is no conflict in practice between the two meanings.
+     Here is an explanation of this feature:
+
+`\DIGIT'
+     matches the same text that matched the DIGITth occurrence of a `\(
+     ... \)' construct.
+
+     In other words, after the end of a `\( ... \)' construct.  the
+     matcher remembers the beginning and end of the text matched by that
+     construct.  Then, later on in the regular expression, you can use
+     `\' followed by DIGIT to match that same text, whatever it may
+     have been.
+
+     The strings matching the first nine `\( ... \)' constructs
+     appearing in a regular expression are assigned numbers 1 through 9
+     in the order that the open parentheses appear in the regular
+     expression.  So you can use `\1' through `\9' to refer to the text
+     matched by the corresponding `\( ... \)' constructs.
+
+     For example, `\(.*\)\1' matches any newline-free string that is
+     composed of two identical halves.  The `\(.*\)' matches the first
+     half, which may be anything, but the `\1' that follows must match
+     the same exact text.
+
+`\(?: ... \)'
+     is called a "shy" grouping operator, and it is used just like `\(
+     ... \)', except that it does not cause the matched substring to be
+     recorded for future reference.
+
+     This is useful when you need a lot of grouping `\( ... \)'
+     constructs, but only want to remember one or two - or if you have
+     more than nine groupings and need to use backreferences to refer to
+     the groupings at the end.
+
+     Using `\(?: ... \)' rather than `\( ... \)' when you don't need
+     the captured substrings ought to speed up your programs some,
+     since it shortens the code path followed by the regular expression
+     engine, as well as the amount of memory allocation and string
+     copying it must do.  The actual performance gain to be observed
+     has not been measured or quantified as of this writing.
+
+     The shy grouping operator has been borrowed from Perl, and has not
+     been available prior to XEmacs 20.3, nor is it available in FSF
+     Emacs.
+
+`\w'
+     matches any word-constituent character.  The editor syntax table
+     determines which characters these are.  *Note Syntax Tables::.
+
+`\W'
+     matches any character that is not a word constituent.
+
+`\sCODE'
+     matches any character whose syntax is CODE.  Here CODE is a
+     character that represents a syntax code: thus, `w' for word
+     constituent, `-' for whitespace, `(' for open parenthesis, etc.
+     *Note Syntax Tables::, for a list of syntax codes and the
+     characters that stand for them.
+
+`\SCODE'
+     matches any character whose syntax is not CODE.
+
+   The following regular expression constructs match the empty
+string--that is, they don't use up any characters--but whether they
+match depends on the context.
+
+`\`'
+     matches the empty string, but only at the beginning of the buffer
+     or string being matched against.
+
+`\''
+     matches the empty string, but only at the end of the buffer or
+     string being matched against.
+
+`\='
+     matches the empty string, but only at point.  (This construct is
+     not defined when matching against a string.)
+
+`\b'
+     matches the empty string, but only at the beginning or end of a
+     word.  Thus, `\bfoo\b' matches any occurrence of `foo' as a
+     separate word.  `\bballs?\b' matches `ball' or `balls' as a
+     separate word.
+
+`\B'
+     matches the empty string, but _not_ at the beginning or end of a
+     word.
+
+`\<'
+     matches the empty string, but only at the beginning of a word.
+
+`\>'
+     matches the empty string, but only at the end of a word.
+
+   Not every string is a valid regular expression.  For example, a
+string with unbalanced square brackets is invalid (with a few
+exceptions, such as `[]]'), and so is a string that ends with a single
+`\'.  If an invalid regular expression is passed to any of the search
+functions, an `invalid-regexp' error is signaled.
+
+ - Function: regexp-quote string
+     This function returns a regular expression string that matches
+     exactly STRING and nothing else.  This allows you to request an
+     exact string match when calling a function that wants a regular
+     expression.
+
+          (regexp-quote "^The cat$")
+               => "\\^The cat\\$"
+
+     One use of `regexp-quote' is to combine an exact string match with
+     context described as a regular expression.  For example, this
+     searches for the string that is the value of `string', surrounded
+     by whitespace:
+
+          (re-search-forward
+           (concat "\\s-" (regexp-quote string) "\\s-"))

 
 \1f
 
 \1f

-File: lispref.info,  Node: Working With Lax Plists,  Next: Converting Plists To/From Alists,  Prev: Working With Normal Plists,  Up: Property Lists
+File: lispref.info,  Node: Regexp Example,  Prev: Syntax of Regexps,  Up: Regular Expressions

 
 

-Working With Lax Plists
------------------------
+Complex Regexp Example
+----------------------
+
+Here is a complicated regexp, used by XEmacs to recognize the end of a
+sentence together with any whitespace that follows.  It is the value of
+the variable `sentence-end'.

 
 

-   Recall that a "lax plist" is a property list whose keys are compared
-using `equal' instead of `eq'.
+   First, we show the regexp as a string in Lisp syntax to distinguish
+spaces from tab characters.  The string constant begins and ends with a
+double-quote.  `\"' stands for a double-quote as part of the string,
+`\\' for a backslash as part of the string, `\t' for a tab and `\n' for
+a newline.

 
 

- - Function: lax-plist-get lax-plist property &optional default
-     This function extracts a value from a lax property list.  The
-     function returns the value corresponding to the given PROPERTY, or
-     DEFAULT if PROPERTY is not one of the properties on the list.
+     "[.?!][]\"')}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"

 
 

- - Function: lax-plist-put lax-plist property value
-     This function changes the value in LAX-PLIST of PROPERTY to VALUE.
+   In contrast, if you evaluate the variable `sentence-end', you will
+see the following:

 
 

- - Function: lax-plist-remprop lax-plist property
-     This function removes from LAX-PLIST the property PROPERTY and its
-     value.  The new plist is returned; use `(setq x (lax-plist-remprop
-     x property))' to be sure to use the new value.  The LAX-PLIST is
-     modified by side effects.
+     sentence-end
+     =>
+     "[.?!][]\"')}]*\\($\\| $\\|  \\|  \\)[
+     ]*"

 
 

- - Function: lax-plist-member lax-plist property
-     This function returns `t' if PROPERTY has a value specified in
-     LAX-PLIST.
+In this output, tab and newline appear as themselves.

 
 

-   In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
-non-`nil', then a property with a `nil' value is ignored or removed.
-This feature is a virus that has infected old Lisp implementations (and
-thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
-used except for backward compatibility.
+   This regular expression contains four parts in succession and can be
+deciphered as follows:

 
 

- - Function: lax-plists-eq a b &optional nil-means-not-present
-     This function returns non-`nil' if lax property lists A and B are
-     `eq' (i.e. their values are `eq'; their keys are still compared
-     using `equal').
+`[.?!]'
+     The first part of the pattern is a character set that matches any
+     one of three characters: period, question mark, and exclamation
+     mark.  The match must begin with one of these three characters.

 
 

- - Function: lax-plists-equal a b &optional nil-means-not-present
-     This function returns non-`nil' if lax property lists A and B are
-     `equal' (i.e. their values are `equal').
+`[]\"')}]*'
+     The second part of the pattern matches any closing braces and
+     quotation marks, zero or more of them, that may follow the period,
+     question mark or exclamation mark.  The `\"' is Lisp syntax for a
+     double-quote in a string.  The `*' at the end indicates that the
+     immediately preceding regular expression (a character set, in this
+     case) may be repeated zero or more times.

 
 

- - Function: canonicalize-lax-plist lax-plist &optional
-          nil-means-not-present
-     This function destructively removes any duplicate entries from a
-     lax plist.  In such cases, the first entry applies.
+`\\($\\| $\\|\t\\|  \\)'
+     The third part of the pattern matches the whitespace that follows
+     the end of a sentence: the end of a line, or a tab, or two spaces.
+     The double backslashes mark the parentheses and vertical bars as
+     regular expression syntax; the parentheses delimit a group and the
+     vertical bars separate alternatives.  The dollar sign is used to
+     match the end of a line.

 
 

-     The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
-     return value may not be `eq' to the passed-in value, so make sure
-     to `setq' the value back into where it came from.
+`[ \t\n]*'
+     Finally, the last part of the pattern matches any additional
+     whitespace beyond the minimum needed to end a sentence.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Converting Plists To/From Alists,  Prev: Working With Lax Plists,  Up: Property Lists
+File: lispref.info,  Node: Regexp Search,  Next: POSIX Regexps,  Prev: Regular Expressions,  Up: Searching and Matching
+
+Regular Expression Searching
+============================
+
+In XEmacs, you can search for the next match for a regexp either
+incrementally or not.  Incremental search commands are described in the
+`The XEmacs Lisp Reference Manual'.  *Note Regular Expression Search:
+(xemacs)Regexp Search.  Here we describe only the search functions
+useful in programs.  The principal one is `re-search-forward'.
+
+ - Command: re-search-forward regexp &optional limit noerror count
+          buffer
+     This function searches forward in the current buffer for a string
+     of text that is matched by the regular expression REGEXP.  The
+     function skips over any amount of text that is not matched by
+     REGEXP, and leaves point at the end of the first match found.  It
+     returns the new value of point.
+
+     If LIMIT is non-`nil' (it must be a position in the current
+     buffer), then it is the upper bound to the search.  No match
+     extending after that position is accepted.
+
+     What happens when the search fails depends on the value of
+     NOERROR.  If NOERROR is `nil', a `search-failed' error is
+     signaled.  If NOERROR is `t', `re-search-forward' does nothing and
+     returns `nil'.  If NOERROR is neither `nil' nor `t', then
+     `re-search-forward' moves point to LIMIT (or the end of the
+     buffer) and returns `nil'.
+
+     If COUNT is supplied (it must be a positive number), then the
+     search is repeated that many times (each time starting at the end
+     of the previous time's match).  If these successive searches
+     succeed, the function succeeds, moving point and returning its new
+     value.  Otherwise the search fails.
+
+     In the following example, point is initially before the `T'.
+     Evaluating the search call moves point to the end of that line
+     (between the `t' of `hat' and the newline).
+
+          ---------- Buffer: foo ----------
+          I read "-!-The cat in the hat
+          comes back" twice.
+          ---------- Buffer: foo ----------
+          
+          (re-search-forward "[a-z]+" nil t 5)
+               => 27
+          
+          ---------- Buffer: foo ----------
+          I read "The cat in the hat-!-
+          comes back" twice.
+          ---------- Buffer: foo ----------
+
+ - Command: re-search-backward regexp &optional limit noerror count
+          buffer
+     This function searches backward in the current buffer for a string
+     of text that is matched by the regular expression REGEXP, leaving
+     point at the beginning of the first text found.
+
+     This function is analogous to `re-search-forward', but they are not
+     simple mirror images.  `re-search-forward' finds the match whose
+     beginning is as close as possible to the starting point.  If
+     `re-search-backward' were a perfect mirror image, it would find the
+     match whose end is as close as possible.  However, in fact it
+     finds the match whose beginning is as close as possible.  The
+     reason is that matching a regular expression at a given spot
+     always works from beginning to end, and starts at a specified
+     beginning position.
+
+     A true mirror-image of `re-search-forward' would require a special
+     feature for matching regexps from end to beginning.  It's not
+     worth the trouble of implementing that.
+
+ - Function: string-match regexp string &optional start buffer
+     This function returns the index of the start of the first match for
+     the regular expression REGEXP in STRING, or `nil' if there is no
+     match.  If START is non-`nil', the search starts at that index in
+     STRING.
+
+     Optional arg BUFFER controls how case folding is done (according
+     to the value of `case-fold-search' in BUFFER and BUFFER's case
+     tables) and defaults to the current buffer.
+
+     For example,
+
+          (string-match
+           "quick" "The quick brown fox jumped quickly.")
+               => 4
+          (string-match
+           "quick" "The quick brown fox jumped quickly." 8)
+               => 27

 
 

-Converting Plists To/From Alists
---------------------------------
+     The index of the first character of the string is 0, the index of
+     the second character is 1, and so on.
+
+     After this function returns, the index of the first character
+     beyond the match is available as `(match-end 0)'.  *Note Match
+     Data::.
+
+          (string-match
+           "quick" "The quick brown fox jumped quickly." 8)
+               => 27
+          
+          (match-end 0)
+               => 32
+
+ - Function: split-string string &optional pattern
+     This function splits STRING to substrings delimited by PATTERN,
+     and returns a list of substrings.  If PATTERN is omitted, it
+     defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
+     white-space.

 
 

- - Function: alist-to-plist alist
-     This function converts association list ALIST into the equivalent
-     property-list form.  The plist is returned.  This converts from
+          (split-string "foo bar")
+               => ("foo" "bar")
+          
+          (split-string "something")
+               => ("something")
+          
+          (split-string "a:b:c" ":")
+               => ("a" "b" "c")
+          
+          (split-string ":a::b:c" ":")
+               => ("" "a" "" "b" "c")
+
+ - Function: split-path path
+     This function splits a search path into a list of strings.  The
+     path components are separated with the characters specified with
+     `path-separator'.  Under Unix, `path-separator' will normally be
+     `:', while under Windows, it will be `;'.
+
+ - Function: looking-at regexp &optional buffer
+     This function determines whether the text in the current buffer
+     directly following point matches the regular expression REGEXP.
+     "Directly following" means precisely that: the search is
+     "anchored" and it can succeed only starting with the first
+     character following point.  The result is `t' if so, `nil'
+     otherwise.
+
+     This function does not move point, but it updates the match data,
+     which you can access using `match-beginning' and `match-end'.
+     *Note Match Data::.
+
+     In this example, point is located directly before the `T'.  If it
+     were anywhere else, the result would be `nil'.
+
+          ---------- Buffer: foo ----------
+          I read "-!-The cat in the hat
+          comes back" twice.
+          ---------- Buffer: foo ----------
+          
+          (looking-at "The cat in the hat$")
+               => t
+
+\1f
+File: lispref.info,  Node: POSIX Regexps,  Next: Search and Replace,  Prev: Regexp Search,  Up: Searching and Matching
+
+POSIX Regular Expression Searching
+==================================
+
+The usual regular expression functions do backtracking when necessary
+to handle the `\|' and repetition constructs, but they continue this
+only until they find _some_ match.  Then they succeed and report the
+first match found.
+
+   This section describes alternative search functions which perform the
+full backtracking specified by the POSIX standard for regular expression
+matching.  They continue backtracking until they have tried all
+possibilities and found all matches, so they can report the longest
+match, as required by POSIX.  This is much slower, so use these
+functions only when you really need the longest match.
+
+   In Emacs versions prior to 19.29, these functions did not exist, and
+the functions described above implemented full POSIX backtracking.
+
+ - Command: posix-search-forward regexp &optional limit noerror count
+          buffer
+     This is like `re-search-forward' except that it performs the full
+     backtracking specified by the POSIX standard for regular expression
+     matching.
+
+ - Command: posix-search-backward regexp &optional limit noerror count
+          buffer
+     This is like `re-search-backward' except that it performs the full
+     backtracking specified by the POSIX standard for regular expression
+     matching.
+
+ - Function: posix-looking-at regexp &optional buffer
+     This is like `looking-at' except that it performs the full
+     backtracking specified by the POSIX standard for regular expression
+     matching.
+
+ - Function: posix-string-match regexp string &optional start buffer
+     This is like `string-match' except that it performs the full
+     backtracking specified by the POSIX standard for regular expression
+     matching.
+
+     Optional arg BUFFER controls how case folding is done (according
+     to the value of `case-fold-search' in BUFFER and BUFFER's case
+     tables) and defaults to the current buffer.
+
+\1f
+File: lispref.info,  Node: Search and Replace,  Next: Match Data,  Prev: POSIX Regexps,  Up: Searching and Matching
+
+Search and Replace
+==================
+
+ - Function: perform-replace from-string replacements query-flag
+          regexp-flag delimited-flag &optional repeat-count map
+     This function is the guts of `query-replace' and related commands.
+     It searches for occurrences of FROM-STRING and replaces some or
+     all of them.  If QUERY-FLAG is `nil', it replaces all occurrences;
+     otherwise, it asks the user what to do about each one.
+
+     If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
+     regular expression; otherwise, it must match literally.  If
+     DELIMITED-FLAG is non-`nil', then only replacements surrounded by
+     word boundaries are considered.
+
+     The argument REPLACEMENTS specifies what to replace occurrences
+     with.  If it is a string, that string is used.  It can also be a
+     list of strings, to be used in cyclic order.
+
+     If REPEAT-COUNT is non-`nil', it should be an integer.  Then it
+     specifies how many times to use each of the strings in the
+     REPLACEMENTS list before advancing cyclicly to the next one.
+
+     Normally, the keymap `query-replace-map' defines the possible user
+     responses for queries.  The argument MAP, if non-`nil', is a
+     keymap to use instead of `query-replace-map'.

 
 

-          ((a . 1) (b . 2) (c . 3))
+ - Variable: query-replace-map
+     This variable holds a special keymap that defines the valid user
+     responses for `query-replace' and related functions, as well as
+     `y-or-n-p' and `map-y-or-n-p'.  It is unusual in two ways:

 
 

-     into
+        * The "key bindings" are not commands, just symbols that are
+          meaningful to the functions that use this map.

 
 

-          (a 1 b 2 c 3)
+        * Prefix keys are not supported; each key binding must be for a
+          single event key sequence.  This is because the functions
+          don't use read key sequence to get the input; instead, they
+          read a single event and look it up "by hand."

 
 

-     The original alist is not modified.
+   Here are the meaningful "bindings" for `query-replace-map'.  Several
+of them are meaningful only for `query-replace' and friends.

 
 

- - Function: plist-to-alist plist
-     This function converts property list PLIST into the equivalent
-     association-list form.  The alist is returned.  This converts from
+`act'
+     Do take the action being considered--in other words, "yes."

 
 

-          (a 1 b 2 c 3)
+`skip'
+     Do not take action for this question--in other words, "no."

 
 

-     into
+`exit'
+     Answer this question "no," and give up on the entire series of
+     questions, assuming that the answers will be "no."

 
 

-          ((a . 1) (b . 2) (c . 3))
+`act-and-exit'
+     Answer this question "yes," and give up on the entire series of
+     questions, assuming that subsequent answers will be "no."

 
 

-     The original plist is not modified.
+`act-and-show'
+     Answer this question "yes," but show the results--don't advance yet
+     to the next question.

 
 

-   The following two functions are equivalent to the preceding two
-except that they destructively modify their arguments, using cons cells
-from the original list to form the new list rather than allocating new
-cons cells.
+`automatic'
+     Answer this question and all subsequent questions in the series
+     with "yes," without further user interaction.

 
 

- - Function: destructive-alist-to-plist alist
-     This function destructively converts association list ALIST into
-     the equivalent property-list form.  The plist is returned.
+`backup'
+     Move back to the previous place that a question was asked about.

 
 

- - Function: destructive-plist-to-alist plist
-     This function destructively converts property list PLIST into the
-     equivalent association-list form.  The alist is returned.
+`edit'
+     Enter a recursive edit to deal with this question--instead of any
+     other action that would normally be taken.
+
+`delete-and-edit'
+     Delete the text being considered, then enter a recursive edit to
+     replace it.
+
+`recenter'
+     Redisplay and center the window, then ask the same question again.
+
+`quit'
+     Perform a quit right away.  Only `y-or-n-p' and related functions
+     use this answer.
+
+`help'
+     Display some help, then ask again.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Weak Lists,  Prev: Property Lists,  Up: Lists
+File: lispref.info,  Node: Match Data,  Next: Searching and Case,  Prev: Search and Replace,  Up: Searching and Matching
+
+The Match Data
+==============
+
+XEmacs keeps track of the positions of the start and end of segments of
+text found during a regular expression search.  This means, for example,
+that you can search for a complex pattern, such as a date in an Rmail
+message, and then extract parts of the match under control of the
+pattern.
+
+   Because the match data normally describe the most recent search only,
+you must be careful not to do another search inadvertently between the
+search you wish to refer back to and the use of the match data.  If you
+can't avoid another intervening search, you must save and restore the
+match data around it, to prevent it from being overwritten.

 
 

-Weak Lists
-==========
+* Menu:
+
+* Simple Match Data::     Accessing single items of match data,
+                           such as where a particular subexpression started.
+* Replacing Match::      Replacing a substring that was matched.
+* Entire Match Data::     Accessing the entire match data at once, as a list.
+* Saving Match Data::     Saving and restoring the match data.
+
+\1f
+File: lispref.info,  Node: Simple Match Data,  Next: Replacing Match,  Up: Match Data
+
+Simple Match Data Access
+------------------------
+
+This section explains how to use the match data to find out what was
+matched by the last search or match operation.
+
+   You can ask about the entire matching text, or about a particular
+parenthetical subexpression of a regular expression.  The COUNT
+argument in the functions below specifies which.  If COUNT is zero, you
+are asking about the entire match.  If COUNT is positive, it specifies
+which subexpression you want.
+
+   Recall that the subexpressions of a regular expression are those
+expressions grouped with escaped parentheses, `\(...\)'.  The COUNTth
+subexpression is found by counting occurrences of `\(' from the
+beginning of the whole regular expression.  The first subexpression is
+numbered 1, the second 2, and so on.  Only regular expressions can have
+subexpressions--after a simple string search, the only information
+available is about the entire match.
+
+ - Function: match-string count &optional in-string
+     This function returns, as a string, the text matched in the last
+     search or match operation.  It returns the entire text if COUNT is
+     zero, or just the portion corresponding to the COUNTth
+     parenthetical subexpression, if COUNT is positive.  If COUNT is
+     out of range, or if that subexpression didn't match anything, the
+     value is `nil'.
+
+     If the last such operation was done against a string with
+     `string-match', then you should pass the same string as the
+     argument IN-STRING.  Otherwise, after a buffer search or match,
+     you should omit IN-STRING or pass `nil' for it; but you should
+     make sure that the current buffer when you call `match-string' is
+     the one in which you did the searching or matching.
+
+ - Function: match-beginning count
+     This function returns the position of the start of text matched by
+     the last regular expression searched for, or a subexpression of it.
+
+     If COUNT is zero, then the value is the position of the start of
+     the entire match.  Otherwise, COUNT specifies a subexpression in
+     the regular expression, and the value of the function is the
+     starting position of the match for that subexpression.
+
+     The value is `nil' for a subexpression inside a `\|' alternative
+     that wasn't used in the match.
+
+ - Function: match-end count
+     This function is like `match-beginning' except that it returns the
+     position of the end of the match, rather than the position of the
+     beginning.
+
+   Here is an example of using the match data, with a comment showing
+the positions within the text:
+
+     (string-match "\\(qu\\)\\(ick\\)"
+                   "The quick fox jumped quickly.")
+                   ;0123456789
+          => 4
+     
+     (match-string 0 "The quick fox jumped quickly.")
+          => "quick"
+     (match-string 1 "The quick fox jumped quickly.")
+          => "qu"
+     (match-string 2 "The quick fox jumped quickly.")
+          => "ick"
+     
+     (match-beginning 1)       ; The beginning of the match
+          => 4                 ;   with `qu' is at index 4.
+     
+     (match-beginning 2)       ; The beginning of the match
+          => 6                 ;   with `ick' is at index 6.
+     
+     (match-end 1)             ; The end of the match
+          => 6                 ;   with `qu' is at index 6.
+     
+     (match-end 2)             ; The end of the match
+          => 9                 ;   with `ick' is at index 9.
+
+   Here is another example.  Point is initially located at the beginning
+of the line.  Searching moves point to between the space and the word
+`in'.  The beginning of the entire match is at the 9th character of the
+buffer (`T'), and the beginning of the match for the first
+subexpression is at the 13th character (`c').
+
+     (list
+       (re-search-forward "The \\(cat \\)")
+       (match-beginning 0)
+       (match-beginning 1))
+         => (9 9 13)
+     
+     ---------- Buffer: foo ----------
+     I read "The cat -!-in the hat comes back" twice.
+             ^   ^
+             9  13
+     ---------- Buffer: foo ----------

 
 

-   A "weak list" is a special sort of list whose members are not counted
-as references for the purpose of garbage collection.  This means that,
-for any object in the list, if there are no references to the object
-anywhere outside of the list (or other weak list or weak hash table),
-that object will disappear the next time a garbage collection happens.
-Weak lists can be useful for keeping track of things such as unobtrusive
-lists of another function's buffers or markers.  When that function is
-done with the elements, they will automatically disappear from the list.
+(In this case, the index returned is a buffer position; the first
+character of the buffer counts as 1.)

 
 

-   Weak lists are used internally, for example, to manage the list
-holding the children of an extent--an extent that is unused but has a
-parent will still be reclaimed, and will automatically be removed from
-its parent's list of children.
+\1f
+File: lispref.info,  Node: Replacing Match,  Next: Entire Match Data,  Prev: Simple Match Data,  Up: Match Data
+
+Replacing the Text That Matched
+-------------------------------
+
+This function replaces the text matched by the last search with
+REPLACEMENT.
+
+ - Function: replace-match replacement &optional fixedcase literal
+          string strbuffer
+     This function replaces the text in the buffer (or in STRING) that
+     was matched by the last search.  It replaces that text with
+     REPLACEMENT.
+
+     If you did the last search in a buffer, you should specify `nil'
+     for STRING.  Then `replace-match' does the replacement by editing
+     the buffer; it leaves point at the end of the replacement text,
+     and returns `t'.
+
+     If you did the search in a string, pass the same string as STRING.
+     Then `replace-match' does the replacement by constructing and
+     returning a new string.
+
+     If the fourth argument STRING is a string, fifth argument
+     STRBUFFER specifies the buffer to be used for syntax-table and
+     case-table lookup and defaults to the current buffer.  When STRING
+     is not a string, the buffer that the match occurred in has
+     automatically been remembered and you do not need to specify it.
+
+     If FIXEDCASE is non-`nil', then the case of the replacement text
+     is not changed; otherwise, the replacement text is converted to a
+     different case depending upon the capitalization of the text to be
+     replaced.  If the original text is all upper case, the replacement
+     text is converted to upper case.  If the first word of the
+     original text is capitalized, then the first word of the
+     replacement text is capitalized.  If the original text contains
+     just one word, and that word is a capital letter, `replace-match'
+     considers this a capitalized first word rather than all upper case.
+
+     If `case-replace' is `nil', then case conversion is not done,
+     regardless of the value of FIXEDCASE.  *Note Searching and Case::.
+
+     If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
+     it is, the only alterations being case changes as needed.  If it
+     is `nil' (the default), then the character `\' is treated
+     specially.  If a `\' appears in REPLACEMENT, then it must be part
+     of one of the following sequences:
+
+    `\&'
+          `\&' stands for the entire text being replaced.
+
+    `\N'
+          `\N', where N is a digit, stands for the text that matched
+          the Nth subexpression in the original regexp.  Subexpressions
+          are those expressions grouped inside `\(...\)'.
+
+    `\\'
+          `\\' stands for a single `\' in the replacement text.

 
 

-   Weak lists are similar to weak hash tables (*note Weak Hash
-Tables::).
+\1f
+File: lispref.info,  Node: Entire Match Data,  Next: Saving Match Data,  Prev: Replacing Match,  Up: Match Data
+
+Accessing the Entire Match Data
+-------------------------------
+
+The functions `match-data' and `set-match-data' read or write the
+entire match data, all at once.
+
+ - Function: match-data &optional integers reuse
+     This function returns a newly constructed list containing all the
+     information on what text the last search matched.  Element zero is
+     the position of the beginning of the match for the whole
+     expression; element one is the position of the end of the match
+     for the expression.  The next two elements are the positions of
+     the beginning and end of the match for the first subexpression,
+     and so on.  In general, element number 2N corresponds to
+     `(match-beginning N)'; and element number 2N + 1 corresponds to
+     `(match-end N)'.
+
+     All the elements are markers or `nil' if matching was done on a
+     buffer, and all are integers or `nil' if matching was done on a
+     string with `string-match'.  However, if the optional first
+     argument INTEGERS is non-`nil', always use integers (rather than
+     markers) to represent buffer positions.
+
+     If the optional second argument REUSE is a list, reuse it as part
+     of the value.  If REUSE is long enough to hold all the values, and
+     if INTEGERS is non-`nil', no new lisp objects are created.
+
+     As always, there must be no possibility of intervening searches
+     between the call to a search function and the call to `match-data'
+     that is intended to access the match data for that search.
+
+          (match-data)
+               =>  (#<marker at 9 in foo>
+                    #<marker at 17 in foo>
+                    #<marker at 13 in foo>
+                    #<marker at 17 in foo>)
+
+ - Function: set-match-data match-list
+     This function sets the match data from the elements of MATCH-LIST,
+     which should be a list that was the value of a previous call to
+     `match-data'.
+
+     If MATCH-LIST refers to a buffer that doesn't exist, you don't get
+     an error; that sets the match data in a meaningless but harmless
+     way.
+
+     `store-match-data' is an alias for `set-match-data'.

 
 

- - Function: weak-list-p object
-     This function returns non-`nil' if OBJECT is a weak list.
+\1f
+File: lispref.info,  Node: Saving Match Data,  Prev: Entire Match Data,  Up: Match Data

 
 

-   Weak lists come in one of four types:
+Saving and Restoring the Match Data
+-----------------------------------

 
 

-`simple'
-     Objects in the list disappear if not referenced outside of the
-     list.
+When you call a function that may do a search, you may need to save and
+restore the match data around that call, if you want to preserve the
+match data from an earlier search for later use.  Here is an example
+that shows the problem that arises if you fail to save the match data:

 
 

-`assoc'
-     Objects in the list disappear if they are conses and either the
-     car or the cdr of the cons is not referenced outside of the list.
+     (re-search-forward "The \\(cat \\)")
+          => 48
+     (foo)                   ; Perhaps `foo' does
+                             ;   more searching.
+     (match-end 0)
+          => 61              ; Unexpected result--not 48!

 
 

-`key-assoc'
-     Objects in the list disappear if they are conses and the car is not
-     referenced outside of the list.
+   You can save and restore the match data with `save-match-data':

 
 

-`value-assoc'
-     Objects in the list disappear if they are conses and the cdr is not
-     referenced outside of the list.
+ - Special Form: save-match-data body...
+     This special form executes BODY, saving and restoring the match
+     data around it.

 
 

- - Function: make-weak-list &optional type
-     This function creates a new weak list of type TYPE.  TYPE is a
-     symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
-     as described above) and defaults to `simple'.
+   You can use `set-match-data' together with `match-data' to imitate
+the effect of the special form `save-match-data'.  This is useful for
+writing code that can run in Emacs 18.  Here is how:

 
 

- - Function: weak-list-type weak
-     This function returns the type of the given weak-list object.
+     (let ((data (match-data)))
+       (unwind-protect
+           ...   ; May change the original match data.
+         (set-match-data data)))

 
 

- - Function: weak-list-list weak
-     This function returns the list contained in a weak-list object.
+   Emacs automatically saves and restores the match data when it runs
+process filter functions (*note Filter Functions::) and process
+sentinels (*note Sentinels::).

 
 

- - Function: set-weak-list-list weak new-list
-     This function changes the list contained in a weak-list object.
+\1f
+File: lispref.info,  Node: Searching and Case,  Next: Standard Regexps,  Prev: Match Data,  Up: Searching and Matching
+
+Searching and Case
+==================
+
+By default, searches in Emacs ignore the case of the text they are
+searching through; if you specify searching for `FOO', then `Foo' or
+`foo' is also considered a match.  Regexps, and in particular character
+sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'.
+
+   If you do not want this feature, set the variable `case-fold-search'
+to `nil'.  Then all letters must match exactly, including case.  This
+is a buffer-local variable; altering the variable affects only the
+current buffer.  (*Note Intro to Buffer-Local::.)  Alternatively, you
+may change the value of `default-case-fold-search', which is the
+default value of `case-fold-search' for buffers that do not override it.
+
+   Note that the user-level incremental search feature handles case
+distinctions differently.  When given a lower case letter, it looks for
+a match of either case, but when given an upper case letter, it looks
+for an upper case letter only.  But this has nothing to do with the
+searching functions Lisp functions use.
+
+ - User Option: case-replace
+     This variable determines whether the replacement functions should
+     preserve case.  If the variable is `nil', that means to use the
+     replacement text verbatim.  A non-`nil' value means to convert the
+     case of the replacement text according to the text being replaced.
+
+     The function `replace-match' is where this variable actually has
+     its effect.  *Note Replacing Match::.
+
+ - User Option: case-fold-search
+     This buffer-local variable determines whether searches should
+     ignore case.  If the variable is `nil' they do not ignore case;
+     otherwise they do ignore case.
+
+ - Variable: default-case-fold-search
+     The value of this variable is the default value for
+     `case-fold-search' in buffers that do not override it.  This is the
+     same as `(default-value 'case-fold-search)'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Sequences Arrays Vectors,  Next: Symbols,  Prev: Lists,  Up: Top
+File: lispref.info,  Node: Standard Regexps,  Prev: Searching and Case,  Up: Searching and Matching
+
+Standard Regular Expressions Used in Editing
+============================================
+
+This section describes some variables that hold regular expressions
+used for certain purposes in editing:
+
+ - Variable: page-delimiter
+     This is the regexp describing line-beginnings that separate pages.
+     The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this
+     matches a line that starts with a formfeed character.
+
+   The following two regular expressions should _not_ assume the match
+always starts at the beginning of a line; they should not use `^' to
+anchor the match.  Most often, the paragraph commands do check for a
+match only at the beginning of a line, which means that `^' would be
+superfluous.  When there is a nonzero left margin, they accept matches
+that start after the left margin.  In that case, a `^' would be
+incorrect.  However, a `^' is harmless in modes where a left margin is
+never used.
+
+ - Variable: paragraph-separate
+     This is the regular expression for recognizing the beginning of a
+     line that separates paragraphs.  (If you change this, you may have
+     to change `paragraph-start' also.)  The default value is
+     `"[ \t\f]*$"', which matches a line that consists entirely of
+     spaces, tabs, and form feeds (after its left margin).
+
+ - Variable: paragraph-start
+     This is the regular expression for recognizing the beginning of a
+     line that starts _or_ separates paragraphs.  The default value is
+     `"[ \t\n\f]"', which matches a line starting with a space, tab,
+     newline, or form feed (after its left margin).
+
+ - Variable: sentence-end
+     This is the regular expression describing the end of a sentence.
+     (All paragraph boundaries also end sentences, regardless.)  The
+     default value is:
+
+          "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
+
+     This means a period, question mark or exclamation mark, followed
+     optionally by a closing parenthetical character, followed by tabs,
+     spaces or new lines.
+
+     For a detailed explanation of this regular expression, see *Note
+     Regexp Example::.

 
 

-Sequences, Arrays, and Vectors
-******************************
+\1f
+File: lispref.info,  Node: Syntax Tables,  Next: Abbrevs,  Prev: Searching and Matching,  Up: Top

 
 

-   Recall that the "sequence" type is the union of four other Lisp
-types: lists, vectors, bit vectors, and strings.  In other words, any
-list is a sequence, any vector is a sequence, any bit vector is a
-sequence, and any string is a sequence.  The common property that all
-sequences have is that each is an ordered collection of elements.
+Syntax Tables
+*************

 
 

-   An "array" is a single primitive object that has a slot for each
-elements.  All the elements are accessible in constant time, but the
-length of an existing array cannot be changed.  Strings, vectors, and
-bit vectors are the three types of arrays.
+A "syntax table" specifies the syntactic textual function of each
+character.  This information is used by the parsing commands, the
+complex movement commands, and others to determine where words, symbols,
+and other syntactic constructs begin and end.  The current syntax table
+controls the meaning of the word motion functions (*note Word Motion::)
+and the list motion functions (*note List Motion::) as well as the
+functions in this chapter.

 
 

-   A list is a sequence of elements, but it is not a single primitive
-object; it is made of cons cells, one cell per element.  Finding the
-Nth element requires looking through N cons cells, so elements farther
-from the beginning of the list take longer to access.  But it is
-possible to add elements to the list, or remove elements.
+* Menu:

 
 

-   The following diagram shows the relationship between these types:
+* Basics: Syntax Basics.     Basic concepts of syntax tables.
+* Desc: Syntax Descriptors.  How characters are classified.
+* Syntax Table Functions::   How to create, examine and alter syntax tables.
+* Motion and Syntax::       Moving over characters with certain syntaxes.
+* 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.

 
 

-               ___________________________________
-              |                                   |
-              |          Sequence                 |
-              |  ______   ______________________  |
-              | |      | |                      | |
-              | | List | |         Array        | |
-              | |      | |  ________   _______  | |
-              | |______| | |        | |       | | |
-              |          | | Vector | | String| | |
-              |          | |________| |_______| | |
-              |          |  __________________  | |
-              |          | |                  | | |
-              |          | |    Bit Vector    | | |
-              |          | |__________________| | |
-              |          |______________________| |
-              |___________________________________|
+\1f
+File: lispref.info,  Node: Syntax Basics,  Next: Syntax Descriptors,  Up: Syntax Tables
+
+Syntax Table Concepts
+=====================
+
+A "syntax table" provides Emacs with the information that determines
+the syntactic use of each character in a buffer.  This information is
+used by the parsing commands, the complex movement commands, and others
+to determine where words, symbols, and other syntactic constructs begin
+and end.  The current syntax table controls the meaning of the word
+motion functions (*note Word Motion::) and the list motion functions
+(*note List Motion::) as well as the functions in this chapter.
+
+Under XEmacs 20 and later, a syntax table is a particular subtype of the
+primitive char table type (*note Char Tables::), and each element of the
+char table is an integer that encodes the syntax of the character in
+question, or a cons of such an integer and a matching character (for
+characters with parenthesis syntax).
+
+   Under XEmacs 19, a syntax table is a vector of 256 elements; it
+contains one entry for each of the 256 possible characters in an 8-bit
+byte.  Each element is an integer that encodes the syntax of the
+character in question. (The matching character, if any, is embedded in
+the bits of this integer.)
+
+   Syntax tables are used only for moving across text, not for the Emacs
+Lisp reader.  XEmacs Lisp uses built-in syntactic rules when reading
+Lisp expressions, and these rules cannot be changed.
+
+   Each buffer has its own major mode, and each major mode has its own
+idea of the syntactic class of various characters.  For example, in Lisp
+mode, the character `;' begins a comment, but in C mode, it terminates
+a statement.  To support these variations, XEmacs makes the choice of
+syntax table local to each buffer.  Typically, each major mode has its
+own syntax table and installs that table in each buffer that uses that
+mode.  Changing this table alters the syntax in all those buffers as
+well as in any buffers subsequently put in that mode.  Occasionally
+several similar modes share one syntax table.  *Note Example Major
+Modes::, for an example of how to set up a syntax table.
+
+   A syntax table can inherit the data for some characters from the
+standard syntax table, while specifying other characters itself.  The
+"inherit" syntax class means "inherit this character's syntax from the
+standard syntax table."  Most major modes' syntax tables inherit the
+syntax of character codes 0 through 31 and 128 through 255.  This is
+useful with character sets such as ISO Latin-1 that have additional
+alphabetic characters in the range 128 to 255.  Just changing the
+standard syntax for these characters affects all major modes.
+
+ - Function: syntax-table-p object
+     This function returns `t' if OBJECT is a vector of length 256
+     elements.  This means that the vector may be a syntax table.
+     However, according to this test, any vector of length 256 is
+     considered to be a syntax table, no matter what its contents.

 
 

-   The elements of vectors and lists may be any Lisp objects.  The
-elements of strings are all characters.  The elements of bit vectors
-are the numbers 0 and 1.
+\1f
+File: lispref.info,  Node: Syntax Descriptors,  Next: Syntax Table Functions,  Prev: Syntax Basics,  Up: Syntax Tables
+
+Syntax Descriptors
+==================
+
+This section describes the syntax classes and flags that denote the
+syntax of a character, and how they are represented as a "syntax
+descriptor", which is a Lisp string that you pass to
+`modify-syntax-entry' to specify the desired syntax.
+
+   XEmacs defines a number of "syntax classes".  Each syntax table puts
+each character into one class.  There is no necessary relationship
+between the class of a character in one syntax table and its class in
+any other table.
+
+   Each class is designated by a mnemonic character, which serves as the
+name of the class when you need to specify a class.  Usually the
+designator character is one that is frequently in that class; however,
+its meaning as a designator is unvarying and independent of what syntax
+that character currently has.
+
+   A syntax descriptor is a Lisp string that specifies a syntax class, a
+matching character (used only for the parenthesis classes) and flags.
+The first character is the designator for a syntax class.  The second
+character is the character to match; if it is unused, put a space there.
+Then come the characters for any desired flags.  If no matching
+character or flags are needed, one character is sufficient.
+
+   For example, the descriptor for the character `*' in C mode is
+`. 23' (i.e., punctuation, matching character slot unused, second
+character of a comment-starter, first character of an comment-ender),
+and the entry for `/' is `. 14' (i.e., punctuation, matching character
+slot unused, first character of a comment-starter, second character of
+a comment-ender).

 
 * Menu:
 
 
 * Menu:
 

-* Sequence Functions::    Functions that accept any kind of sequence.
-* Arrays::                Characteristics of arrays in XEmacs Lisp.
-* Array Functions::       Functions specifically for arrays.
-* Vectors::               Special characteristics of XEmacs Lisp vectors.
-* Vector Functions::      Functions specifically for vectors.
-* Bit Vectors::           Special characteristics of XEmacs Lisp bit vectors.
-* Bit Vector Functions::  Functions specifically for bit vectors.
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+
+\1f
+File: lispref.info,  Node: Syntax Class Table,  Next: Syntax Flags,  Up: Syntax Descriptors
+
+Table of Syntax Classes
+-----------------------
+
+Here is a table of syntax classes, the characters that stand for them,
+their meanings, and examples of their use.
+
+ - Syntax class: whitespace character
+     "Whitespace characters" (designated with `-') separate symbols and
+     words from each other.  Typically, whitespace characters have no
+     other syntactic significance, and multiple whitespace characters
+     are syntactically equivalent to a single one.  Space, tab, newline
+     and formfeed are almost always classified as whitespace.  (The
+     designator ` ' is accepted for backwards compatibility with older
+     versions of XEmacs, but is deprecated.  It is invalid in GNU
+     Emacs.)
+
+ - Syntax class: word constituent
+     "Word constituents" (designated with `w') are parts of normal
+     English words and are typically used in variable and command names
+     in programs.  All upper- and lower-case letters, and the digits,
+     are typically word constituents.
+
+ - Syntax class: symbol constituent
+     "Symbol constituents" (designated with `_') are the extra
+     characters that are used in variable and command names along with
+     word constituents.  For example, the symbol constituents class is
+     used in Lisp mode to indicate that certain characters may be part
+     of symbol names even though they are not part of English words.
+     These characters are `$&*+-_<>'.  In standard C, the only
+     non-word-constituent character that is valid in symbols is
+     underscore (`_').
+
+ - Syntax class: punctuation character
+     "Punctuation characters" (`.') are those characters that are used
+     as punctuation in English, or are used in some way in a programming
+     language to separate symbols from one another.  Most programming
+     language modes, including Emacs Lisp mode, have no characters in
+     this class since the few characters that are not symbol or word
+     constituents all have other uses.
+
+ - Syntax class: open parenthesis character
+ - Syntax class: close parenthesis character
+     Open and close "parenthesis characters" are characters used in
+     dissimilar pairs to surround sentences or expressions.  Such a
+     grouping is begun with an open parenthesis character and
+     terminated with a close.  Each open parenthesis character matches
+     a particular close parenthesis character, and vice versa.
+     Normally, XEmacs indicates momentarily the matching open
+     parenthesis when you insert a close parenthesis.  *Note Blinking::.
+
+     The class of open parentheses is designated with `(', and that of
+     close parentheses with `)'.
+
+     In English text, and in C code, the parenthesis pairs are `()',
+     `[]', and `{}'.  In XEmacs Lisp, the delimiters for lists and
+     vectors (`()' and `[]') are classified as parenthesis characters.
+
+ - Syntax class: string quote
+     "String quote characters" (designated with `"') are used in many
+     languages, including Lisp and C, to delimit string constants.  The
+     same string quote character appears at the beginning and the end
+     of a string.  Such quoted strings do not nest.
+
+     The parsing facilities of XEmacs consider a string as a single
+     token.  The usual syntactic meanings of the characters in the
+     string are suppressed.
+
+     The Lisp modes have two string quote characters: double-quote (`"')
+     and vertical bar (`|').  `|' is not used in XEmacs Lisp, but it is
+     used in Common Lisp.  C also has two string quote characters:
+     double-quote for strings, and single-quote (`'') for character
+     constants.
+
+     English text has no string quote characters because English is not
+     a programming language.  Although quotation marks are used in
+     English, we do not want them to turn off the usual syntactic
+     properties of other characters in the quotation.
+
+ - Syntax class: escape
+     An "escape character" (designated with `\') starts an escape
+     sequence such as is used in C string and character constants.  The
+     character `\' belongs to this class in both C and Lisp.  (In C, it
+     is used thus only inside strings, but it turns out to cause no
+     trouble to treat it this way throughout C code.)
+
+     Characters in this class count as part of words if
+     `words-include-escapes' is non-`nil'.  *Note Word Motion::.
+
+ - Syntax class: character quote
+     A "character quote character" (designated with `/') quotes the
+     following character so that it loses its normal syntactic meaning.
+     This differs from an escape character in that only the character
+     immediately following is ever affected.
+
+     Characters in this class count as part of words if
+     `words-include-escapes' is non-`nil'.  *Note Word Motion::.
+
+     This class is used for backslash in TeX mode.
+
+ - Syntax class: paired delimiter
+     "Paired delimiter characters" (designated with `$') are like
+     string quote characters except that the syntactic properties of the
+     characters between the delimiters are not suppressed.  Only TeX
+     mode uses a paired delimiter presently--the `$' that both enters
+     and leaves math mode.
+
+ - Syntax class: expression prefix
+     An "expression prefix operator" (designated with `'') is used for
+     syntactic operators that are part of an expression if they appear
+     next to one.  These characters in Lisp include the apostrophe, `''
+     (used for quoting), the comma, `,' (used in macros), and `#' (used
+     in the read syntax for certain data types).
+
+ - Syntax class: comment starter
+ - Syntax class: comment ender
+     The "comment starter" and "comment ender" characters are used in
+     various languages to delimit comments.  These classes are
+     designated with `<' and `>', respectively.
+
+     English text has no comment characters.  In Lisp, the semicolon
+     (`;') starts a comment and a newline or formfeed ends one.
+
+ - Syntax class: inherit
+     This syntax class does not specify a syntax.  It says to look in
+     the standard syntax table to find the syntax of this character.
+     The designator for this syntax code is `@'.
+
+\1f
+File: lispref.info,  Node: Syntax Flags,  Prev: Syntax Class Table,  Up: Syntax Descriptors
+
+Syntax Flags
+------------
+
+In addition to the classes, entries for characters in a syntax table
+can include flags.  There are eleven possible flags, represented by the
+digits `1'-`8', and the lowercase letters `a', `b', and `p'.
+
+   All the flags except `p' are used to describe comment delimiters.
+The digit flags indicate that a character can _also_ be part of a
+multi-character comment sequence, in addition to the syntactic
+properties associated with its character class.  The flags must be
+independent of the class and each other for the sake of characters such
+as `*' in C mode, which is a punctuation character, _and_ the second
+character of a start-of-comment sequence (`/*'), _and_ the first
+character of an end-of-comment sequence (`*/').
+
+   Emacs supports two comment styles simultaneously in any one syntax
+table.  This is for the sake of C++.  Each style of comment syntax has
+its own comment-start sequence and its own comment-end sequence.  Each
+comment must stick to one style or the other; thus, if it starts with
+the comment-start sequence of style "b", it must also end with the
+comment-end sequence of style "b".
+
+   As an extension to GNU Emacs 19 and 20, XEmacs supports two arbitrary
+comment-start sequences and two arbitrary comment-end sequences.  (Thus
+the need for 8 flags.)  GNU Emacs restricts the comment-start sequences
+to start with the same character, XEmacs does not.  This means that for
+two-character sequences, where GNU Emacs uses the `b' flag, XEmacs uses
+the digit flags `5'-`8'.
+
+   A one character comment-end sequence applies to the "b" style if its
+first character has the `b' flag set; otherwise, it applies to the "a"
+style.  The `a' flag is optional.  These flags have no effect on
+non-comment characters; two-character styles are determined by the
+digit flags.
+
+   The flags for a character C are:
+
+   * `1' means C is the start of a two-character comment-start sequence
+     of style "a".
+
+   * `2' means C is the second character of such a sequence.
+
+   * `3' means C is the start of a two-character comment-end sequence
+     of style "a".
+
+   * `4' means C is the second character of such a sequence.
+
+   * `5' means C is the start of a two-character comment-start sequence
+     of style "b".
+
+   * `6' means C is the second character of such a sequence.
+
+   * `7' means C is the start of a two-character comment-end sequence
+     of style "b".
+
+   * `8' means C is the second character of such a sequence.
+
+   * `a' means that C as a comment delimiter belongs to the default "a"
+     comment style.  (This flag is optional.)
+
+   * `b' means that C as a comment delimiter belongs to the alternate
+     "b" comment style.
+
+   * `p' identifies an additional "prefix character" for Lisp syntax.
+     These characters are treated as whitespace when they appear between
+     expressions.  When they appear within an expression, they are
+     handled according to their usual syntax codes.
+
+     The function `backward-prefix-chars' moves back over these
+     characters, as well as over characters whose primary syntax class
+     is prefix (`'').  *Note Motion and Syntax::.
+
+   Lisp (as you would expect) has a simple comment syntax.
+
+`;'
+     `<'
+
+newline
+     `>'
+
+   Note that no flags are used.  This defines two comment-delimiting
+sequences:
+
+`;'
+     This is a single-character comment-start sequence because the
+     syntax class is `<'.
+
+newline
+     This is a single character comment-end sequence because the syntax
+     class is `>' and the `b' flag is not set.
+
+   C++ (again, as you would expect) has a baroque, overrich, and
+excessively complex comment syntax.
+
+`/'
+     `1456'
+
+`*'
+     `23'
+
+newline
+     `>b'
+
+   Note that the "b" style mixes one-character and two-character
+sequences.  The table above defines four comment-delimiting sequences:
+
+`/*'
+     This is a comment-start sequence for "a" style because the `1'
+     flag is set on `/' and the `2' flag is set on `*'.
+
+`//'
+     This is a comment-start sequence for "b" style because both the `5'
+     and the `6' flags are set on `/'.
+
+`*/'
+     This is a comment-end sequence for "a" style because the `3' flag
+     is set on `*' and the `4' flag is set on `/'.
+
+newline
+     This is a comment-end sequence for "b" style, because the newline
+     character has the `b' flag.
+
+\1f
+File: lispref.info,  Node: Syntax Table Functions,  Next: Motion and Syntax,  Prev: Syntax Descriptors,  Up: Syntax Tables
+
+Syntax Table Functions
+======================
+
+In this section we describe functions for creating, accessing and
+altering syntax tables.
+
+ - Function: make-syntax-table &optional oldtable
+     This function creates a new syntax table.  Character codes 0
+     through 31 and 128 through 255 are set up to inherit from the
+     standard syntax table.  The other character codes are set up by
+     copying what the standard syntax table says about them.
+
+     Most major mode syntax tables are created in this way.
+
+ - Function: copy-syntax-table &optional syntax-table
+     This function constructs a copy of SYNTAX-TABLE and returns it.
+     If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy
+     of the current syntax table.  Otherwise, an error is signaled if
+     SYNTAX-TABLE is not a syntax table.
+
+ - Command: modify-syntax-entry char-range syntax-descriptor &optional
+          syntax-table
+     This function sets the syntax entry for CHAR-RANGE according to
+     SYNTAX-DESCRIPTOR.  CHAR-RANGE is either a single character or a
+     range of characters, as used with `put-char-table'. The syntax is
+     changed only for SYNTAX-TABLE, which defaults to the current
+     buffer's syntax table, and not in any other syntax table.  The
+     argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a
+     string beginning with a class designator character, and optionally
+     containing a matching character and flags as well.  *Note Syntax
+     Descriptors::.
+
+     This function always returns `nil'.  The old syntax information in
+     the table for CHAR-RANGE is discarded.
+
+     An error is signaled if the first character of the syntax
+     descriptor is not one of the twelve syntax class designator
+     characters.
+
+     Examples:
+          
+          ;; Put the space character in class whitespace.
+          (modify-syntax-entry ?\  " ")
+               => nil
+          
+          ;; Make `$' an open parenthesis character,
+          ;;   with `^' as its matching close.
+          (modify-syntax-entry ?$ "(^")
+               => nil
+          
+          ;; Make `^' a close parenthesis character,
+          ;;   with `$' as its matching open.
+          (modify-syntax-entry ?^ ")$")
+               => nil
+          
+          ;; Make `/' a punctuation character,
+          ;;   the first character of a start-comment sequence,
+          ;;   and the second character of an end-comment sequence.
+          ;;   This is used in C mode.
+          (modify-syntax-entry ?/ ". 14")
+               => nil
+
+ - Function: char-syntax character &optional syntax-table
+     This function returns the syntax class of CHARACTER, represented
+     by its mnemonic designator character.  This _only_ returns the
+     class, not any matching parenthesis or flags.
+
+     An error is signaled if CHARACTER is not a character.
+
+     The characters that correspond to various syntax codes are listed
+     in the documentation of `modify-syntax-entry'.
+
+     Optional second argument SYNTAX-TABLE is the syntax table to be
+     used, and defaults to the current buffer's syntax table.
+
+     The following examples apply to C mode.  The first example shows
+     that the syntax class of space is whitespace (represented by a
+     space).  The second example shows that the syntax of `/' is
+     punctuation.  This does not show the fact that it is also part of
+     comment-start and -end sequences.  The third example shows that
+     open parenthesis is in the class of open parentheses.  This does
+     not show the fact that it has a matching character, `)'.
+
+          (char-to-string (char-syntax ?\ ))
+               => " "
+          
+          (char-to-string (char-syntax ?/))
+               => "."
+          
+          (char-to-string (char-syntax ?\())
+               => "("
+
+ - Function: set-syntax-table syntax-table &optional buffer
+     This function makes SYNTAX-TABLE the syntax table for BUFFER, which
+     defaults to the current buffer if omitted.  It returns
+     SYNTAX-TABLE.
+
+ - Function: syntax-table &optional buffer
+     This function returns the syntax table for BUFFER, which defaults
+     to the current buffer if omitted.
+
+\1f
+File: lispref.info,  Node: Motion and Syntax,  Next: Parsing Expressions,  Prev: Syntax Table Functions,  Up: Syntax Tables
+
+Motion and Syntax
+=================
+
+This section describes functions for moving across characters in
+certain syntax classes.  None of these functions exists in Emacs
+version 18 or earlier.
+
+ - Function: skip-syntax-forward syntaxes &optional limit buffer
+     This function moves point forward across characters having syntax
+     classes mentioned in SYNTAXES.  It stops when it encounters the
+     end of the buffer, or position LIMIT (if specified), or a
+     character it is not supposed to skip.  Optional argument BUFFER
+     defaults to the current buffer if omitted.
+
+ - Function: skip-syntax-backward syntaxes &optional limit buffer
+     This function moves point backward across characters whose syntax
+     classes are mentioned in SYNTAXES.  It stops when it encounters
+     the beginning of the buffer, or position LIMIT (if specified), or a
+     character it is not supposed to skip.  Optional argument BUFFER
+     defaults to the current buffer if omitted.
+
+
+ - Function: backward-prefix-chars &optional buffer
+     This function moves point backward over any number of characters
+     with expression prefix syntax.  This includes both characters in
+     the expression prefix syntax class, and characters with the `p'
+     flag.  Optional argument BUFFER defaults to the current buffer if
+     omitted.
+
+\1f
+File: lispref.info,  Node: Parsing Expressions,  Next: Standard Syntax Tables,  Prev: Motion and Syntax,  Up: Syntax Tables
+
+Parsing Balanced Expressions
+============================
+
+Here are several functions for parsing and scanning balanced
+expressions, also known as "sexps", in which parentheses match in
+pairs.  The syntax table controls the interpretation of characters, so
+these functions can be used for Lisp expressions when in Lisp mode and
+for C expressions when in C mode.  *Note List Motion::, for convenient
+higher-level functions for moving over balanced expressions.
+
+ - Function: parse-partial-sexp start limit &optional target-depth
+          stop-before state stop-comment buffer
+     This function parses a sexp in the current buffer starting at
+     START, not scanning past LIMIT.  It stops at position LIMIT or
+     when certain criteria described below are met, and sets point to
+     the location where parsing stops.  It returns a value describing
+     the status of the parse at the point where it stops.
+
+     If STATE is `nil', START is assumed to be at the top level of
+     parenthesis structure, such as the beginning of a function
+     definition.  Alternatively, you might wish to resume parsing in the
+     middle of the structure.  To do this, you must provide a STATE
+     argument that describes the initial status of parsing.
+
+     If the third argument TARGET-DEPTH is non-`nil', parsing stops if
+     the depth in parentheses becomes equal to TARGET-DEPTH.  The depth
+     starts at 0, or at whatever is given in STATE.
+
+     If the fourth argument STOP-BEFORE is non-`nil', parsing stops
+     when it comes to any character that starts a sexp.  If
+     STOP-COMMENT is non-`nil', parsing stops when it comes to the
+     start of a comment.
+
+     The fifth argument STATE is an eight-element list of the same form
+     as the value of this function, described below.  The return value
+     of one call may be used to initialize the state of the parse on
+     another call to `parse-partial-sexp'.
+
+     The result is a list of eight elements describing the final state
+     of the parse:
+
+       0. The depth in parentheses, counting from 0.
+
+       1. The character position of the start of the innermost
+          parenthetical grouping containing the stopping point; `nil'
+          if none.
+
+       2. The character position of the start of the last complete
+          subexpression terminated; `nil' if none.
+
+       3. Non-`nil' if inside a string.  More precisely, this is the
+          character that will terminate the string.
+
+       4. `t' if inside a comment (of either style).
+
+       5. `t' if point is just after a quote character.
+
+       6. The minimum parenthesis depth encountered during this scan.
+
+       7. `t' if inside a comment of style "b".
+
+     Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
+
+     This function is most often used to compute indentation for
+     languages that have nested parentheses.
+
+ - Function: scan-lists from count depth &optional buffer noerror
+     This function scans forward COUNT balanced parenthetical groupings
+     from character number FROM.  It returns the character position
+     where the scan stops.
+
+     If DEPTH is nonzero, parenthesis depth counting begins from that
+     value.  The only candidates for stopping are places where the
+     depth in parentheses becomes zero; `scan-lists' counts COUNT such
+     places and then stops.  Thus, a positive value for DEPTH means go
+     out DEPTH levels of parenthesis.
+
+     Scanning ignores comments if `parse-sexp-ignore-comments' is
+     non-`nil'.
+
+     If the scan reaches the beginning or end of the buffer (or its
+     accessible portion), and the depth is not zero, an error is
+     signaled.  If the depth is zero but the count is not used up,
+     `nil' is returned.
+
+     If optional arg BUFFER is non-`nil', scanning occurs in that
+     buffer instead of in the current buffer.
+
+     If optional arg NOERROR is non-`nil', `scan-lists' will return
+     `nil' instead of signalling an error.
+
+ - Function: scan-sexps from count &optional buffer noerror
+     This function scans forward COUNT sexps from character position
+     FROM.  It returns the character position where the scan stops.
+
+     Scanning ignores comments if `parse-sexp-ignore-comments' is
+     non-`nil'.
+
+     If the scan reaches the beginning or end of (the accessible part
+     of) the buffer in the middle of a parenthetical grouping, an error
+     is signaled.  If it reaches the beginning or end between groupings
+     but before count is used up, `nil' is returned.
+
+     If optional arg BUFFER is non-`nil', scanning occurs in that
+     buffer instead of in the current buffer.
+
+     If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
+     instead of signalling an error.
+
+ - Variable: parse-sexp-ignore-comments
+     If the value is non-`nil', then comments are treated as whitespace
+     by the functions in this section and by `forward-sexp'.
+
+     In older Emacs versions, this feature worked only when the comment
+     terminator is something like `*/', and appears only to end a
+     comment.  In languages where newlines terminate comments, it was
+     necessary make this variable `nil', since not every newline is the
+     end of a comment.  This limitation no longer exists.
+
+   You can use `forward-comment' to move forward or backward over one
+comment or several comments.
+
+ - Function: forward-comment &optional count buffer
+     This function moves point forward across COUNT comments (backward,
+     if COUNT is negative).  If it finds anything other than a comment
+     or whitespace, it stops, leaving point at the place where it
+     stopped.  It also stops after satisfying COUNT.  COUNT defaults to
+     `1'.
+
+     Optional argument BUFFER defaults to the current buffer.
+
+   To move forward over all comments and whitespace following point, use
+`(forward-comment (buffer-size))'.  `(buffer-size)' is a good argument
+to use, because the number of comments in the buffer cannot exceed that
+many.
+
+\1f
+File: lispref.info,  Node: Standard Syntax Tables,  Next: Syntax Table Internals,  Prev: Parsing Expressions,  Up: Syntax Tables
+
+Some Standard Syntax Tables
+===========================
+
+Most of the major modes in XEmacs have their own syntax tables.  Here
+are several of them:
+
+ - Function: standard-syntax-table
+     This function returns the standard syntax table, which is the
+     syntax table used in Fundamental mode.
+
+ - Variable: text-mode-syntax-table
+     The value of this variable is the syntax table used in Text mode.
+
+ - Variable: c-mode-syntax-table
+     The value of this variable is the syntax table for C-mode buffers.
+
+ - Variable: emacs-lisp-mode-syntax-table
+     The value of this variable is the syntax table used in Emacs Lisp
+     mode by editing commands.  (It has no effect on the Lisp `read'
+     function.)
+
+\1f
+File: lispref.info,  Node: Syntax Table Internals,  Prev: Standard Syntax Tables,  Up: Syntax Tables
+
+Syntax Table Internals
+======================
+
+Each element of a syntax table is an integer that encodes the syntax of
+one character: the syntax class, possible matching character, and
+flags.  Lisp programs don't usually work with the elements directly; the
+Lisp-level syntax table functions usually work with syntax descriptors
+(*note Syntax Descriptors::).
+
+   The low 8 bits of each element of a syntax table indicate the syntax
+class.
+
+Integer
+     Class
+
+0
+     whitespace
+
+1
+     punctuation
+
+2
+     word
+
+3
+     symbol
+
+4
+     open parenthesis
+
+5
+     close parenthesis
+
+6
+     expression prefix
+
+7
+     string quote
+
+8
+     paired delimiter
+
+9
+     escape
+
+10
+     character quote
+
+11
+     comment-start
+
+12
+     comment-end
+
+13
+     inherit
+
+   The next 8 bits are the matching opposite parenthesis (if the
+character has parenthesis syntax); otherwise, they are not meaningful.
+The next 6 bits are the flags.
+
+\1f
+File: lispref.info,  Node: Abbrevs,  Next: Extents,  Prev: Syntax Tables,  Up: Top
+
+Abbrevs And Abbrev Expansion
+****************************
+
+An abbreviation or "abbrev" is a string of characters that may be
+expanded to a longer string.  The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev.  This
+saves typing.
+
+   The set of abbrevs currently in effect is recorded in an "abbrev
+table".  Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table.  There is also a global
+abbrev table.  Normally both are used.
+
+   An abbrev table is represented as an obarray containing a symbol for
+each abbreviation.  The symbol's name is the abbreviation; its value is
+the expansion; its function definition is the hook function to do the
+expansion (*note Defining Abbrevs::); its property list cell contains
+the use count, the number of times the abbreviation has been expanded.
+Because these symbols are not interned in the usual obarray, they will
+never appear as the result of reading a Lisp expression; in fact,
+normally they are never used except by the code that handles abbrevs.
+Therefore, it is safe to use them in an extremely nonstandard way.
+*Note Creating Symbols::.
+
+   For the user-level commands for abbrevs, see *Note Abbrev Mode:
+(xemacs)Abbrevs.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Abbrev Mode,  Next: Abbrev Tables,  Up: Abbrevs
+
+Setting Up Abbrev Mode
+======================
+
+Abbrev mode is a minor mode controlled by the value of the variable
+`abbrev-mode'.
+
+ - Variable: abbrev-mode
+     A non-`nil' value of this variable turns on the automatic expansion
+     of abbrevs when their abbreviations are inserted into a buffer.
+     If the value is `nil', abbrevs may be defined, but they are not
+     expanded automatically.
+
+     This variable automatically becomes local when set in any fashion.
+
+ - Variable: default-abbrev-mode
+     This is the value of `abbrev-mode' for buffers that do not
+     override it.  This is the same as `(default-value 'abbrev-mode)'.
+
+\1f
+File: lispref.info,  Node: Abbrev Tables,  Next: Defining Abbrevs,  Prev: Abbrev Mode,  Up: Abbrevs
+
+Abbrev Tables
+=============
+
+This section describes how to create and manipulate abbrev tables.
+
+ - Function: make-abbrev-table
+     This function creates and returns a new, empty abbrev table--an
+     obarray containing no symbols.  It is a vector filled with zeros.
+
+ - Function: clear-abbrev-table table
+     This function undefines all the abbrevs in abbrev table TABLE,
+     leaving it empty.  The function returns `nil'.
+
+ - Function: define-abbrev-table table-name definitions
+     This function defines TABLE-NAME (a symbol) as an abbrev table
+     name, i.e., as a variable whose value is an abbrev table.  It
+     defines abbrevs in the table according to DEFINITIONS, a list of
+     elements of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'.  The
+     value is always `nil'.
+
+ - Variable: abbrev-table-name-list
+     This is a list of symbols whose values are abbrev tables.
+     `define-abbrev-table' adds the new abbrev table name to this list.
+
+ - Function: insert-abbrev-table-description name &optional human
+     This function inserts before point a description of the abbrev
+     table named NAME.  The argument NAME is a symbol whose value is an
+     abbrev table.  The value is always `nil'.
+
+     If HUMAN is non-`nil', the description is human-oriented.
+     Otherwise the description is a Lisp expression--a call to
+     `define-abbrev-table' that would define NAME exactly as it is
+     currently defined.
+
+\1f
+File: lispref.info,  Node: Defining Abbrevs,  Next: Abbrev Files,  Prev: Abbrev Tables,  Up: Abbrevs
+
+Defining Abbrevs
+================
+
+These functions define an abbrev in a specified abbrev table.
+`define-abbrev' is the low-level basic function, while `add-abbrev' is
+used by commands that ask for information from the user.
+
+ - Function: add-abbrev table type arg
+     This function adds an abbreviation to abbrev table TABLE based on
+     information from the user.  The argument TYPE is a string
+     describing in English the kind of abbrev this will be (typically,
+     `"global"' or `"mode-specific"'); this is used in prompting the
+     user.  The argument ARG is the number of words in the expansion.
+
+     The return value is the symbol that internally represents the new
+     abbrev, or `nil' if the user declines to confirm redefining an
+     existing abbrev.
+
+ - Function: define-abbrev table name &optional expansion hook count
+     This function defines an abbrev in TABLE named NAME, to expand to
+     EXPANSION, and call HOOK.  The return value is an uninterned
+     symbol that represents the abbrev inside XEmacs; its name is NAME.
+
+     The argument NAME should be a string.  The argument EXPANSION
+     should be a string, or `nil' to undefine the abbrev.
+
+     The argument HOOK is a function or `nil'.  If HOOK is non-`nil',
+     then it is called with no arguments after the abbrev is replaced
+     with EXPANSION; point is located at the end of EXPANSION when HOOK
+     is called.
+
+     The use count of the abbrev is initialized to zero.
+
+ - User Option: only-global-abbrevs
+     If this variable is non-`nil', it means that the user plans to use
+     global abbrevs only.  This tells the commands that define
+     mode-specific abbrevs to define global ones instead.  This
+     variable does not alter the behavior of the functions in this
+     section; it is examined by their callers.
+
+\1f
+File: lispref.info,  Node: Abbrev Files,  Next: Abbrev Expansion,  Prev: Defining Abbrevs,  Up: Abbrevs
+
+Saving Abbrevs in Files
+=======================
+
+A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents.  Therefore, you can load the file
+with `load' (*note How Programs Do Loading::).  However, the function
+`quietly-read-abbrev-file' is provided as a more convenient interface.
+
+   User-level facilities such as `save-some-buffers' can save abbrevs
+in a file automatically, under the control of variables described here.
+
+ - User Option: abbrev-file-name
+     This is the default file name for reading and saving abbrevs.
+
+ - Function: quietly-read-abbrev-file &optional filename
+     This function reads abbrev definitions from a file named FILENAME,
+     previously written with `write-abbrev-file'.  If FILENAME is
+     `nil', the file specified in `abbrev-file-name' is used.
+     `save-abbrevs' is set to `t' so that changes will be saved.
+
+     This function does not display any messages.  It returns `nil'.
+
+ - User Option: save-abbrevs
+     A non-`nil' value for `save-abbrev' means that XEmacs should save
+     abbrevs when files are saved.  `abbrev-file-name' specifies the
+     file to save the abbrevs in.
+
+ - Variable: abbrevs-changed
+     This variable is set non-`nil' by defining or altering any
+     abbrevs.  This serves as a flag for various XEmacs commands to
+     offer to save your abbrevs.
+
+ - Command: write-abbrev-file filename
+     Save all abbrev definitions, in all abbrev tables, in the file
+     FILENAME, in the form of a Lisp program that when loaded will
+     define the same abbrevs.  This function returns `nil'.
+
+\1f
+File: lispref.info,  Node: Abbrev Expansion,  Next: Standard Abbrev Tables,  Prev: Abbrev Files,  Up: Abbrevs
+
+Looking Up and Expanding Abbreviations
+======================================
+
+Abbrevs are usually expanded by commands for interactive use, including
+`self-insert-command'.  This section describes the subroutines used in
+writing such functions, as well as the variables they use for
+communication.
+
+ - Function: abbrev-symbol abbrev &optional table
+     This function returns the symbol representing the abbrev named
+     ABBREV.  The value returned is `nil' if that abbrev is not
+     defined.  The optional second argument TABLE is the abbrev table
+     to look it up in.  If TABLE is `nil', this function tries first
+     the current buffer's local abbrev table, and second the global
+     abbrev table.
+
+ - Function: abbrev-expansion abbrev &optional table
+     This function returns the string that ABBREV would expand into (as
+     defined by the abbrev tables used for the current buffer).  The
+     optional argument TABLE specifies the abbrev table to use, as in
+     `abbrev-symbol'.
+
+ - Command: expand-abbrev
+     This command expands the abbrev before point, if any.  If point
+     does not follow an abbrev, this command does nothing.  The command
+     returns `t' if it did expansion, `nil' otherwise.
+
+ - Command: abbrev-prefix-mark &optional arg
+     Mark current point as the beginning of an abbrev.  The next call to
+     `expand-abbrev' will use the text from here to point (where it is
+     then) as the abbrev to expand, rather than using the previous word
+     as usual.
+
+ - User Option: abbrev-all-caps
+     When this is set non-`nil', an abbrev entered entirely in upper
+     case is expanded using all upper case.  Otherwise, an abbrev
+     entered entirely in upper case is expanded by capitalizing each
+     word of the expansion.
+
+ - Variable: abbrev-start-location
+     This is the buffer position for `expand-abbrev' to use as the start
+     of the next abbrev to be expanded.  (`nil' means use the word
+     before point instead.)  `abbrev-start-location' is set to `nil'
+     each time `expand-abbrev' is called.  This variable is also set by
+     `abbrev-prefix-mark'.
+
+ - Variable: abbrev-start-location-buffer
+     The value of this variable is the buffer for which
+     `abbrev-start-location' has been set.  Trying to expand an abbrev
+     in any other buffer clears `abbrev-start-location'.  This variable
+     is set by `abbrev-prefix-mark'.
+
+ - Variable: last-abbrev
+     This is the `abbrev-symbol' of the last abbrev expanded.  This
+     information is left by `expand-abbrev' for the sake of the
+     `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-location
+     This is the location of the last abbrev expanded.  This contains
+     information left by `expand-abbrev' for the sake of the
+     `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-text
+     This is the exact expansion text of the last abbrev expanded,
+     after case conversion (if any).  Its value is `nil' if the abbrev
+     has already been unexpanded.  This contains information left by
+     `expand-abbrev' for the sake of the `unexpand-abbrev' command.
+
+ - Variable: pre-abbrev-expand-hook
+     This is a normal hook whose functions are executed, in sequence,
+     just before any expansion of an abbrev.  *Note Hooks::.  Since it
+     is a normal hook, the hook functions receive no arguments.
+     However, they can find the abbrev to be expanded by looking in the
+     buffer before point.
+
+   The following sample code shows a simple use of
+`pre-abbrev-expand-hook'.  If the user terminates an abbrev with a
+punctuation character, the hook function asks for confirmation.  Thus,
+this hook allows the user to decide whether to expand the abbrev, and
+aborts expansion if it is not confirmed.
+
+     (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
+     
+     ;; This is the function invoked by `pre-abbrev-expand-hook'.
+     
+     ;; If the user terminated the abbrev with a space, the function does
+     ;; nothing (that is, it returns so that the abbrev can expand).  If the
+     ;; user entered some other character, this function asks whether
+     ;; expansion should continue.
+     
+     ;; If the user answers the prompt with `y', the function returns
+     ;; `nil' (because of the `not' function), but that is
+     ;; acceptable; the return value has no effect on expansion.
+     
+     (defun query-if-not-space ()
+       (if (/= ?\  (preceding-char))
+           (if (not (y-or-n-p "Do you want to expand this abbrev? "))
+               (error "Not expanding this abbrev"))))
+
+\1f
+File: lispref.info,  Node: Standard Abbrev Tables,  Prev: Abbrev Expansion,  Up: Abbrevs
+
+Standard Abbrev Tables
+======================
+
+Here we list the variables that hold the abbrev tables for the
+preloaded major modes of XEmacs.
+
+ - Variable: global-abbrev-table
+     This is the abbrev table for mode-independent abbrevs.  The abbrevs
+     defined in it apply to all buffers.  Each buffer may also have a
+     local abbrev table, whose abbrev definitions take precedence over
+     those in the global table.
+
+ - Variable: local-abbrev-table
+     The value of this buffer-local variable is the (mode-specific)
+     abbreviation table of the current buffer.
+
+ - Variable: fundamental-mode-abbrev-table
+     This is the local abbrev table used in Fundamental mode; in other
+     words, it is the local abbrev table in all buffers in Fundamental
+     mode.
+
+ - Variable: text-mode-abbrev-table
+     This is the local abbrev table used in Text mode.
+
+ - Variable: c-mode-abbrev-table
+     This is the local abbrev table used in C mode.
+
+ - Variable: lisp-mode-abbrev-table
+     This is the local abbrev table used in Lisp mode and Emacs Lisp
+     mode.
+
+\1f
+File: lispref.info,  Node: Extents,  Next: Specifiers,  Prev: Abbrevs,  Up: Top
+
+Extents
+*******
+
+An "extent" is a region of text (a start position and an end position)
+that is displayed in a particular face and can have certain other
+properties such as being read-only.  Extents can overlap each other.
+XEmacs efficiently handles buffers with large numbers of extents in
+them.
+
+ - Function: extentp object
+     This returns `t' if OBJECT is an extent.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Intro to Extents,  Next: Creating and Modifying Extents,  Up: Extents
+
+Introduction to Extents
+=======================
+
+An extent is a region of text within a buffer or string that has
+certain properties associated with it.  The properties of an extent
+primarily affect the way the text contained in the extent is displayed.
+Extents can freely overlap each other in a buffer or string.  Extents
+are invisible to functions that merely examine the text of a buffer or
+string.
+
+   _Please note:_ An alternative way to add properties to a buffer or
+string is to use text properties.  *Note Text Properties::.
+
+   An extent is logically a Lisp object consisting of a start position,
+an end position, a buffer or string to which these positions refer, and
+a property list.  As text is inserted into a buffer, the start and end
+positions of the extent are automatically adjusted as necessary to keep
+the extent referring to the same text in the buffer.  If text is
+inserted at the boundary of an extent, the extent's `start-open' and
+`end-open' properties control whether the text is included as part of
+the extent.  If the text bounded by an extent is deleted, the extent
+becomes "detached"; its start and end positions are no longer
+meaningful, but it maintains all its other properties and can later be
+reinserted into a buffer. (None of these considerations apply to
+strings, because text cannot be inserted into or deleted from a string.)
+
+   Each extent has a face or list of faces associated with it, which
+controls the way in which the text bounded by the extent is displayed.
+If an extent's face is `nil' or its properties are partially undefined,
+the corresponding properties from the default face for the frame is
+used.  If two or more extents overlap, or if a list of more than one
+face is specified for a particular extent, the corresponding faces are
+merged to determine the text's displayed properties.  Every extent has
+a "priority" that determines which face takes precedence if the faces
+conflict. (If two extents have the same priority, the one that comes
+later in the display order takes precedence.  *Note display order:
+Extent Endpoints.) Higher-numbered priority values correspond to a
+higher priority, and priority values can be negative.  Every extent is
+created with a priority of 0, but this can be changed with
+`set-extent-priority'.  Within a single extent with a list of faces,
+faces earlier in the list have a higher priority than faces later in
+the list.
+
+   Extents can be set to respond specially to key and mouse events
+within the extent.  An extent's `keymap' property controls the effect of
+key and mouse strokes within the extent's text, and the `mouse-face'
+property controls whether the extent is highlighted when the mouse moves
+over it.  *Note Extents and Events::.
+
+   An extent can optionally have a "begin-glyph" or "end-glyph"
+associated with it.  A begin-glyph or end-glyph is a pixmap or string
+that will be displayed either at the start or end of an extent or in the
+margin of the line that the start or end of the extent lies in,
+depending on the extent's layout policy.  Begin-glyphs and end-glyphs
+are used to implement annotations, and you should use the annotation API
+functions in preference to the lower-level extent functions.  For more
+information, *Note Annotations::.
+
+   If an extent has its `detachable' property set, it will become
+"detached" (i.e. no longer in the buffer) when all its text is deleted.
+Otherwise, it will simply shrink down to zero-length and sit in the
+same place in the buffer.  By default, the `detachable' property is set
+on newly-created extents.  *Note Detached Extents::.
+
+   If an extent has its `duplicable' property set, it will be
+remembered when a string is created from text bounded by the extent.
+When the string is re-inserted into a buffer, the extent will also be
+re-inserted.  This mechanism is used in the kill, yank, and undo
+commands.  *Note Duplicable Extents::.
+
+\1f
+File: lispref.info,  Node: Creating and Modifying Extents,  Next: Extent Endpoints,  Prev: Intro to Extents,  Up: Extents
+
+Creating and Modifying Extents
+==============================
+
+ - Function: make-extent from to &optional buffer-or-string
+     This function makes an extent for the range [FROM, TO) in
+     BUFFER-OR-STRING (a buffer or string).  BUFFER-OR-STRING defaults
+     to the current buffer.  Insertions at point TO will be outside of
+     the extent; insertions at FROM will be inside the extent, causing
+     the extent to grow (*note Extent Endpoints::).  This is the same
+     way that markers behave.  The extent is initially detached if both
+     FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults
+     to `nil', meaning the extent is in no buffer or string (*note
+     Detached Extents::).
+
+ - Function: delete-extent extent
+     This function removes EXTENT from its buffer and destroys it.
+     This does not modify the buffer's text, only its display
+     properties.  The extent cannot be used thereafter.  To remove an
+     extent in such a way that it can be re-inserted later, use
+     `detach-extent'.  *Note Detached Extents::.
+
+ - Function: extent-object extent
+     This function returns the buffer or string that EXTENT is in.  If
+     the return value is `nil', this means that the extent is detached;
+     however, a detached extent will not necessarily return a value of
+     `nil'.
+
+ - Function: extent-live-p object
+     This function returns `t' if OBJECT is an extent that has not been
+     deleted, and `nil' otherwise.
+
+\1f
+File: lispref.info,  Node: Extent Endpoints,  Next: Finding Extents,  Prev: Creating and Modifying Extents,  Up: Extents
+
+Extent Endpoints
+================
+
+Every extent has a start position and an end position, and logically
+affects the characters between those positions.  Normally the start and
+end positions must both be valid positions in the extent's buffer or
+string.  However, both endpoints can be `nil', meaning the extent is
+detached.  *Note Detached Extents::.
+
+   Whether the extent overlaps its endpoints is governed by its
+`start-open' and `end-open' properties.  Insertion of a character at a
+closed endpoint will expand the extent to include that character;
+insertion at an open endpoint will not.  Similarly, functions such as
+`extent-at' that scan over all extents overlapping a particular
+position will include extents with a closed endpoint at that position,
+but not extents with an open endpoint.
+
+   Note that the `start-closed' and `end-closed' properties are
+equivalent to `start-open' and `end-open' with the opposite sense.
+
+   Both endpoints can be equal, in which case the extent includes no
+characters but still exists in the buffer or string.  Zero-length
+extents are used to represent annotations (*note Annotations::) and can
+be used as a more powerful form of a marker.  Deletion of all the
+characters in an extent may or may not result in a zero-length extent;
+this depends on the `detachable' property (*note Detached Extents::).
+Insertion at the position of a zero-length extent expands the extent if
+both endpoints are closed; goes before the extent if it has the
+`start-open' property; and goes after the extent if it has the
+`end-open' property.  Zero-length extents with both the `start-open'
+and `end-open' properties are treated as if their starting point were
+closed.  Deletion of a character on a side of a zero-length extent
+whose corresponding endpoint is closed causes the extent to be detached
+if its `detachable' property is set; if the corresponding endpoint is
+open, the extent remains in the buffer, moving as necessary.
+
+   Extents are ordered within a buffer or string by increasing start
+position, and then by decreasing end position (this is called the
+"display order").
+
+ - Function: extent-start-position extent
+     This function returns the start position of EXTENT.
+
+ - Function: extent-end-position extent
+     This function returns the end position of EXTENT.
+
+ - Function: extent-length extent
+     This function returns the length of EXTENT in characters.  If the
+     extent is detached, this returns `0'.  If the extent is not
+     detached, this is equivalent to
+          (- (extent-end-position EXTENT) (extent-start-position EXTENT))
+
+ - Function: set-extent-endpoints extent start end &optional
+          buffer-or-string
+     This function sets the start and end position of EXTENT to START
+     and END.  If both are `nil', this is equivalent to `detach-extent'.
+
+     BUFFER-OR-STRING specifies the new buffer or string that the
+     extent should be in, and defaults to EXTENT's buffer or string.
+     (If `nil', and EXTENT is in no buffer and no string, it defaults
+     to the current buffer.)
+
+     See documentation on `detach-extent' for a discussion of undo
+     recording.
+
+\1f
+File: lispref.info,  Node: Finding Extents,  Next: Mapping Over Extents,  Prev: Extent Endpoints,  Up: Extents
+
+Finding Extents
+===============
+
+The following functions provide a simple way of determining the extents
+in a buffer or string.  A number of more sophisticated primitives for
+mapping over the extents in a range of a buffer or string are also
+provided (*note Mapping Over Extents::).  When reading through this
+section, keep in mind the way that extents are ordered (*note Extent
+Endpoints::).
+
+ - Function: extent-list &optional buffer-or-string from to flags
+          property value
+     This function returns a list of the extents in BUFFER-OR-STRING.
+     BUFFER-OR-STRING defaults to the current buffer if omitted.  FROM
+     and TO can be used to limit the range over which extents are
+     returned; if omitted, all extents in the buffer or string are
+     returned.
+
+     More specifically, if a range is specified using FROM and TO, only
+     extents that overlap the range (i.e. begin or end inside of the
+     range) are included in the list.  FROM and TO default to the
+     beginning and end of BUFFER-OR-STRING, respectively.
+
+     FLAGS controls how end cases are treated.  For a discussion of
+     this, and exactly what "overlap" means, see `map-extents'.
+
+     The optional arguments PROPERTY and VALUE can be used to further
+     restrict which extents are returned.  They have the same meaning
+     as for `map-extents'.
+
+     If you want to map a function over the extents in a buffer or
+     string, consider using `map-extents' or `mapcar-extents' instead.
+
+     See also the function `extents-at'.
+
+   Functions that create extents must be prepared for the possibility
+that there are other extents in the same area, created by other
+functions.  To deal with this, functions typically mark their own
+extents by setting a particular property on them.  The following
+function makes it easier to locate those extents.
+
+ - Function: extent-at pos &optional object property before at-flag
+     This function finds the "smallest" extent (i.e., the last one in
+     the display order) at (i.e., overlapping) POS in OBJECT (a buffer
+     or string) having PROPERTY set.  OBJECT defaults to the current
+     buffer.  PROPERTY defaults to `nil', meaning that any extent will
+     do.  Returns `nil' if there is no matching extent at POS.  If the
+     fourth argument BEFORE is not `nil', it must be an extent; any
+     returned extent will precede that extent.  This feature allows
+     `extent-at' to be used by a loop over extents.
+
+     AT-FLAG controls how end cases are handled (i.e. what "at" really
+     means), and should be one of:
+
+    `nil'
+
+    `after'
+          An extent is at POS if it covers the character after POS.
+          This is consistent with the way that text properties work.
+
+    `before'
+          An extent is at POS if it covers the character before POS.
+
+    `at'
+          An extent is at POS if it overlaps or abuts POS.  This
+          includes all zero-length extents at POS.
+
+     Note that in all cases, the start-openness and end-openness of the
+     extents considered is ignored.  If you want to pay attention to
+     those properties, you should use `map-extents', which gives you
+     more control.
+
+   The following low-level functions are provided for explicitly
+traversing the extents in a buffer according to the display order.
+These functions are mostly intended for debugging--in normal operation,
+you should probably use `mapcar-extents' or `map-extents', or loop
+using the BEFORE argument to `extent-at', rather than creating a loop
+using `next-extent'.
+
+ - Function: next-extent extent
+     Given an extent EXTENT, this function returns the next extent in
+     the buffer or string's display order.  If EXTENT is a buffer or
+     string, this returns the first extent in the buffer or string.
+
+ - Function: previous-extent extent
+     Given an extent EXTENT, this function returns the previous extent
+     in the buffer or string's display order.  If EXTENT is a buffer or
+     string, this returns the last extent in the buffer or string.
+
+\1f
+File: lispref.info,  Node: Mapping Over Extents,  Next: Extent Properties,  Prev: Finding Extents,  Up: Extents
+
+Mapping Over Extents
+====================
+
+The most basic and general function for mapping over extents is called
+`map-extents'.  You should read through the definition of this function
+to familiarize yourself with the concepts and optional arguments
+involved.  However, in practice you may find it more convenient to use
+the function `mapcar-extents' or to create a loop using the `before'
+argument to `extent-at' (*note Finding Extents::).
+
+ - Function: map-extents function &optional object from to maparg flags
+          property value
+     This function maps FUNCTION over the extents which overlap a
+     region in OBJECT.  OBJECT is normally a buffer or string but could
+     be an extent (see below).  The region is normally bounded by
+     [FROM, TO) (i.e. the beginning of the region is closed and the end
+     of the region is open), but this can be changed with the FLAGS
+     argument (see below for a complete discussion).
+
+     FUNCTION is called with the arguments (extent, MAPARG).  The
+     arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
+     default to the current buffer, the beginning of OBJECT, the end of
+     OBJECT, `nil', and `nil', respectively.  `map-extents' returns the
+     first non-`nil' result produced by FUNCTION, and no more calls to
+     FUNCTION are made after it returns non-`nil'.
+
+     If OBJECT is an extent, FROM and TO default to the extent's
+     endpoints, and the mapping omits that extent and its predecessors.
+     This feature supports restarting a loop based on `map-extents'.
+     Note: OBJECT must be attached to a buffer or string, and the
+     mapping is done over that buffer or string.
+
+     An extent overlaps the region if there is any point in the extent
+     that is also in the region. (For the purpose of overlap,
+     zero-length extents and regions are treated as closed on both ends
+     regardless of their endpoints' specified open/closedness.) Note
+     that the endpoints of an extent or region are considered to be in
+     that extent or region if and only if the corresponding end is
+     closed.  For example, the extent [5,7] overlaps the region [2,5]
+     because 5 is in both the extent and the region.  However, (5,7]
+     does not overlap [2,5] because 5 is not in the extent, and neither
+     [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
+     region.
+
+     The optional FLAGS can be a symbol or a list of one or more
+     symbols, modifying the behavior of `map-extents'.  Allowed symbols
+     are:
+
+    `end-closed'
+          The region's end is closed.
+
+    `start-open'
+          The region's start is open.
+
+    `all-extents-closed'
+          Treat all extents as closed on both ends for the purpose of
+          determining whether they overlap the region, irrespective of
+          their actual open- or closedness.
+
+    `all-extents-open'
+          Treat all extents as open on both ends.
+
+    `all-extents-closed-open'
+          Treat all extents as start-closed, end-open.
+
+    `all-extents-open-closed'
+          Treat all extents as start-open, end-closed.
+
+    `start-in-region'
+          In addition to the above conditions for extent overlap, the
+          extent's start position must lie within the specified region.
+          Note that, for this condition, open start positions are
+          treated as if 0.5 was added to the endpoint's value, and open
+          end positions are treated as if 0.5 was subtracted from the
+          endpoint's value.
+
+    `end-in-region'
+          The extent's end position must lie within the region.
+
+    `start-and-end-in-region'
+          Both the extent's start and end positions must lie within the
+          region.
+
+    `start-or-end-in-region'
+          Either the extent's start or end position must lie within the
+          region.
+
+    `negate-in-region'
+          The condition specified by a `*-in-region' flag must _not_
+          hold for the extent to be considered.
+
+     At most one of `all-extents-closed', `all-extents-open',
+     `all-extents-closed-open', and `all-extents-open-closed' may be
+     specified.
+
+     At most one of `start-in-region', `end-in-region',
+     `start-and-end-in-region', and `start-or-end-in-region' may be
+     specified.
+
+     If optional arg PROPERTY is non-`nil', only extents with that
+     property set on them will be visited.  If optional arg VALUE is
+     non-`nil', only extents whose value for that property is `eq' to
+     VALUE will be visited.
+
+   If you want to map over extents and accumulate a list of results,
+the following function may be more convenient than `map-extents'.
+
+ - Function: mapcar-extents function &optional predicate
+          buffer-or-string from to flags property value
+     This function applies FUNCTION to all extents which overlap a
+     region in BUFFER-OR-STRING.  The region is delimited by FROM and
+     TO.  FUNCTION is called with one argument, the extent.  A list of
+     the values returned by FUNCTION is returned.  An optional
+     PREDICATE may be used to further limit the extents over which
+     FUNCTION is mapped.  The optional arguments FLAGS, PROPERTY, and
+     VALUE may also be used to control the extents passed to PREDICATE
+     or FUNCTION, and have the same meaning as in `map-extents'.
+
+ - Function: map-extent-children function &optional object from to
+          maparg flags property value
+     This function is similar to `map-extents', but differs in that:
+
+        * It only visits extents which start in the given region.
+
+        * After visiting an extent E, it skips all other extents which
+          start inside E but end before E's end.
+
+     Thus, this function may be used to walk a tree of extents in a
+     buffer:
+          (defun walk-extents (buffer &optional ignore)
+            (map-extent-children 'walk-extents buffer))
+
+ - Function: extent-in-region-p extent &optional from to flags
+     This function returns `t' if `map-extents' would visit EXTENT if
+     called with the given arguments.
+
+\1f
+File: lispref.info,  Node: Extent Properties,  Next: Detached Extents,  Prev: Mapping Over Extents,  Up: Extents
+
+Properties of Extents
+=====================
+
+Each extent has a property list associating property names with values.
+Some property names have predefined meanings, and can usually only
+assume particular values.  Assigning other values to such a property
+either cause the value to be converted into a legal value (e.g.,
+assigning anything but `nil' to a Boolean property will cause the value
+of `t' to be assigned to the property) or will cause an error.
+Property names without predefined meanings can be assigned any value.
+An undefined property is equivalent to a property with a value of
+`nil', or with a particular default value in the case of properties
+with predefined meanings.  Note that, when an extent is created, the
+`end-open' and `detachable' properties are set on it.
+
+   If an extent has a parent, all of its properties actually derive
+from that parent (or from the root ancestor if the parent in turn has a
+parent), and setting a property of the extent actually sets that
+property on the parent.  *Note Extent Parents::.
+
+ - Function: extent-property extent property &optional default
+     This function returns EXTENT's value for PROPERTY, or DEFAULT if
+     no such property exists.
+
+ - Function: extent-properties extent
+     This function returns a list of all of EXTENT's properties that do
+     not have the value of `nil' (or the default value, for properties
+     with predefined meanings).
+
+ - Function: set-extent-property extent property value
+     This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
+     predefined meaning, only certain values are allowed, and some
+     values may be converted to others before being stored.)
+
+ - Function: set-extent-properties extent plist
+     Change some properties of EXTENT.  PLIST is a property list.  This
+     is useful to change many extent properties at once.
+
+   The following table lists the properties with predefined meanings,
+along with their allowable values.
+
+`detached'
+     (Boolean) Whether the extent is detached.   Setting this is the
+     same as calling `detach-extent'.  *Note Detached Extents::.
+
+`destroyed'
+     (Boolean) Whether the extent has been deleted.  Setting this is
+     the same as calling `delete-extent'.
+
+`priority'
+     (integer) The extent's redisplay priority.  Defaults to 0.  *Note
+     priority: Intro to Extents.  This property can also be set with
+     `set-extent-priority' and accessed with `extent-priority'.
+
+`start-open'
+     (Boolean) Whether the start position of the extent is open,
+     meaning that characters inserted at that position go outside of
+     the extent.  *Note Extent Endpoints::.
+
+`start-closed'
+     (Boolean) Same as `start-open' but with the opposite sense.
+     Setting this property clears `start-open' and vice-versa.
+
+`end-open'
+     (Boolean) Whether the end position of the extent is open, meaning
+     that characters inserted at that position go outside of the
+     extent.  This is `t' by default.  *Note Extent Endpoints::.
+
+`end-closed'
+     (Boolean) Same as `end-open' but with the opposite sense.  Setting
+     this property clears `end-open' and vice-versa.
+
+`read-only'
+     (Boolean) Whether text within this extent will be unmodifiable.
+
+`face'
+     (face, face name, list of faces or face names, or `nil') The face
+     in which to display the extent's text.  This property can also be
+     set with `set-extent-face' and accessed with `extent-face'.  Note
+     that if a list of faces is specified, the faces are merged
+     together, with faces earlier in the list having priority over
+     faces later in the list.
+
+`mouse-face'
+     (face, face name, list of faces or face names, or `nil') The face
+     used to display the extent when the mouse moves over it.  This
+     property can also be set with `set-extent-mouse-face' and accessed
+     with `extent-mouse-face'.  Note that if a list of faces is
+     specified, the faces are merged together, with faces earlier in
+     the list having priority over faces later in the list.  *Note
+     Extents and Events::.
+
+`pointer'
+     (pointer glyph)  The glyph used as the pointer when the mouse
+     moves over the extent.  This takes precedence over the
+     `text-pointer-glyph' and `nontext-pointer-glyph' variables.  If
+     for any reason this glyph is an invalid pointer, the standard
+     glyphs will be used as fallbacks.  *Note Mouse Pointer::.
+
+`detachable'
+     (Boolean) Whether this extent becomes detached when all of the
+     text it covers is deleted.  This is `t' by default.  *Note
+     Detached Extents::.
+
+`duplicable'
+     (Boolean) Whether this extent should be copied into strings, so
+     that kill, yank, and undo commands will restore or copy it.  *Note
+     Duplicable Extents::.
+
+`unique'
+     (Boolean) Meaningful only in conjunction with `duplicable'.  When
+     this is set, there may be only one instance of this extent
+     attached at a time.  *Note Duplicable Extents::.
+
+`invisible'
+     (Boolean) If `t', text under this extent will not be displayed -
+     it will look as if the text and the begin-glyph is not there at
+     all.  The end-glyph will still be displayed.
+
+`keymap'
+     (keymap or `nil') This keymap is consulted for mouse clicks on this
+     extent or keypresses made while `point' is within the extent.
+     *Note Extents and Events::.
+
+`copy-function'
+     This is a hook that is run when a duplicable extent is about to be
+     copied from a buffer to a string (or the kill ring).  *Note
+     Duplicable Extents::.
+
+`paste-function'
+     This is a hook that is run when a duplicable extent is about to be
+     copied from a string (or the kill ring) into a buffer.  *Note
+     Duplicable Extents::.
+
+`begin-glyph'
+     (glyph or `nil') This extent's begin glyph.  *Note Annotations::.
+
+`end-glyph'
+     (glyph or `nil') This extent's end glyph.  *Note Annotations::.
+
+`begin-glyph-layout'
+     (`text', `whitespace', `inside-margin', or `outside-margin') The
+     layout policy for this extent's begin glyph.  Defaults to `text'.
+     *Note Annotations::.
+
+`end-glyph-layout'
+     (`text', `whitespace', `inside-margin', or `outside-margin') The
+     layout policy for this extent's end glyph.  Defaults to `text'.
+     *Note Annotations::.
+
+`initial-redisplay-function'
+     (any funcallable object) The function to be called the first time
+     (a part of) the extent is redisplayed.  It will be called with the
+     extent as its argument.
+
+     This is used by `lazy-shot' to implement lazy font-locking.  The
+     functionality is still experimental, and may change without further
+     notice.
+
+   The following convenience functions are provided for accessing
+particular properties of an extent.
+
+ - Function: extent-face extent
+     This function returns the `face' property of EXTENT.  This might
+     also return a list of face names.  Do not modify this list
+     directly!  Instead, use `set-extent-face'.
+
+     Note that you can use `eq' to compare lists of faces as returned
+     by `extent-face'.  In other words, if you set the face of two
+     different extents to two lists that are `equal' but not `eq', then
+     the return value of `extent-face' on the two extents will return
+     the identical list.
+
+ - Function: extent-mouse-face extent
+     This function returns the `mouse-face' property of EXTENT.  This
+     might also return a list of face names.  Do not modify this list
+     directly!  Instead, use `set-extent-mouse-face'.
+
+     Note that you can use `eq' to compare lists of faces as returned
+     by `extent-mouse-face', just like for `extent-face'.
+
+ - Function: extent-priority extent
+     This function returns the `priority' property of EXTENT.
+
+ - Function: extent-keymap extent
+     This function returns the `keymap' property of EXTENT.
+
+ - Function: extent-begin-glyph-layout extent
+     This function returns the `begin-glyph-layout' property of EXTENT,
+     i.e. the layout policy associated with the EXTENT's begin glyph.
+
+ - Function: extent-end-glyph-layout extent
+     This function returns the `end-glyph-layout' property of EXTENT,
+     i.e. the layout policy associated with the EXTENT's end glyph.
+
+ - Function: extent-begin-glyph extent
+     This function returns the `begin-glyph' property of EXTENT, i.e.
+     the glyph object displayed at the beginning of EXTENT.  If there
+     is none, `nil' is returned.
+
+ - Function: extent-end-glyph extent
+     This function returns the `end-glyph' property of EXTENT, i.e. the
+     glyph object displayed at the end of EXTENT.  If there is none,
+     `nil' is returned.
+
+   The following convenience functions are provided for setting
+particular properties of an extent.
+
+ - Function: set-extent-priority extent priority
+     This function sets the `priority' property of EXTENT to PRIORITY.
+
+ - Function: set-extent-face extent face
+     This function sets the `face' property of EXTENT to FACE.
+
+ - Function: set-extent-mouse-face extent face
+     This function sets the `mouse-face' property of EXTENT to FACE.
+
+ - Function: set-extent-keymap extent keymap
+     This function sets the `keymap' property of EXTENT to KEYMAP.
+     KEYMAP must be either a keymap object, or `nil'.
+
+ - Function: set-extent-begin-glyph-layout extent layout
+     This function sets the `begin-glyph-layout' property of EXTENT to
+     LAYOUT.
+
+ - Function: set-extent-end-glyph-layout extent layout
+     This function sets the `end-glyph-layout' property of EXTENT to
+     LAYOUT.
+
+ - Function: set-extent-begin-glyph extent begin-glyph &optional layout
+     This function sets the `begin-glyph' and `glyph-layout' properties
+     of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
+     defaults to `text' if not specified.)
+
+ - Function: set-extent-end-glyph extent end-glyph &optional layout
+     This function sets the `end-glyph' and `glyph-layout' properties
+     of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
+     to `text' if not specified.)
+
+ - Function: set-extent-initial-redisplay-function extent function
+     This function sets the `initial-redisplay-function' property of the
+     extent to FUNCTION.
+
+\1f
+File: lispref.info,  Node: Detached Extents,  Next: Extent Parents,  Prev: Extent Properties,  Up: Extents
+
+Detached Extents
+================
+
+A detached extent is an extent that is not attached to a buffer or
+string but can be re-inserted.  Detached extents have a start position
+and end position of `nil'.  Extents can be explicitly detached using
+`detach-extent'.  An extent is also detached when all of its characters
+are all killed by a deletion, if its `detachable' property is set; if
+this property is not set, the extent becomes a zero-length extent.
+(Zero-length extents with the `detachable' property set behave
+specially.  *Note zero-length extents: Extent Endpoints.)
+
+ - Function: detach-extent extent
+     This function detaches EXTENT from its buffer or string.  If
+     EXTENT has the `duplicable' property, its detachment is tracked by
+     the undo mechanism.  *Note Duplicable Extents::.
+
+ - Function: extent-detached-p extent
+     This function returns `nil' if EXTENT is detached, and `t'
+     otherwise.
+
+ - Function: copy-extent extent &optional object
+     This function makes a copy of EXTENT.  It is initially detached.
+     Optional argument OBJECT defaults to EXTENT's object (normally a
+     buffer or string, but could be `nil').
+
+ - Function: insert-extent extent &optional start end no-hooks object
+     This function inserts EXTENT from START to END in OBJECT (a buffer
+     or string).  If EXTENT is detached from a different buffer or
+     string, or in most cases when EXTENT is already attached, the
+     extent will first be copied as if with `copy-extent'.  This
+     function operates the same as if `insert' were called on a string
+     whose extent data calls for EXTENT to be inserted, except that if
+     NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
+     invoked.  *Note Duplicable Extents::.
+
+\1f
+File: lispref.info,  Node: Extent Parents,  Next: Duplicable Extents,  Prev: Detached Extents,  Up: Extents
+
+Extent Parents
+==============
+
+An extent can have a parent extent set for it.  If this is the case,
+the extent derives all its properties from that extent and has no
+properties of its own.  The only "properties" that the extent keeps are
+the buffer or string it refers to and the start and end points.  (More
+correctly, the extent's own properties are shadowed.  If you later
+change the extent to have no parent, its own properties will become
+visible again.)
+
+   It is possible for an extent's parent to itself have a parent, and
+so on.  Through this, a whole tree of extents can be created, all
+deriving their properties from one root extent.  Note, however, that
+you cannot create an inheritance loop--this is explicitly disallowed.
+
+   Parent extents are used to implement the extents over the modeline.
+
+ - Function: set-extent-parent extent parent
+     This function sets the parent of EXTENT to PARENT.  If PARENT is
+     `nil', the extent is set to have no parent.
+
+ - Function: extent-parent extent
+     This function return the parents (if any) of EXTENT, or `nil'.
+
+ - Function: extent-children extent
+     This function returns a list of the children (if any) of EXTENT.
+     The children of an extent are all those extents whose parent is
+     that extent.  This function does not recursively trace children of
+     children.
+
+ - Function: extent-descendants extent
+     This function returns a list of all descendants of EXTENT,
+     including EXTENT.  This recursively applies `extent-children' to
+     any children of EXTENT, until no more children can be found.
+
+\1f
+File: lispref.info,  Node: Duplicable Extents,  Next: Extents and Events,  Prev: Extent Parents,  Up: Extents
+
+Duplicable Extents
+==================
+
+If an extent has the `duplicable' property, it will be copied into
+strings, so that kill, yank, and undo commands will restore or copy it.
+
+   Specifically:
+
+   * When a string is created using `buffer-substring' or
+     `buffer-string', any duplicable extents in the region corresponding
+     to the string will be copied into the string (*note Buffer
+     Contents::).  When the string is inserted into a buffer using
+     `insert', `insert-before-markers', `insert-buffer' or
+     `insert-buffer-substring', the extents in the string will be copied
+     back into the buffer (*note Insertion::).  The extents in a string
+     can, of course, be retrieved explicitly using the standard extent
+     primitives over the string.
+
+   * Similarly, when text is copied or cut into the kill ring, any
+     duplicable extents will be remembered and reinserted later when
+     the text is pasted back into a buffer.
+
+   * When `concat' is called on strings, the extents in the strings are
+     copied into the resulting string.
+
+   * When `substring' is called on a string, the relevant extents are
+     copied into the resulting string.
+
+   * When a duplicable extent is detached by `detach-extent' or string
+     deletion, or inserted by `insert-extent' or string insertion, the
+     action is recorded by the undo mechanism so that it can be undone
+     later.  Note that if an extent gets detached and then a later undo
+     causes the extent to get reinserted, the new extent will not be
+     `eq' to the original extent.
+
+   * Extent motion, face changes, and attachment via `make-extent' are
+     not recorded by the undo mechanism.  This means that extent changes
+     which are to be undo-able must be performed by character editing,
+     or by insertion and detachment of duplicable extents.
+
+   * A duplicable extent's `copy-function' property, if non-`nil',
+     should be a function, and will be run when a duplicable extent is
+     about to be copied from a buffer to a string (or the kill ring).
+     It is called with three arguments: the extent and the buffer
+     positions within it which are being copied.  If this function
+     returns `nil', then the extent will not be copied; otherwise it
+     will.
+
+   * A duplicable extent's `paste-function' property, if non-`nil',
+     should be a function, and will be run when a duplicable extent is
+     about to be copied from a string (or the kill ring) into a buffer.
+     It is called with three arguments: the original extent and the
+     buffer positions which the copied extent will occupy. (This hook
+     is run after the corresponding text has already been inserted into
+     the buffer.) Note that the extent argument may be detached when
+     this function is run.  If this function returns `nil', no extent
+     will be inserted.  Otherwise, there will be an extent covering the
+     range in question.
+
+     Note: if the extent to be copied is already attached to the buffer
+     and overlaps the new range, the extent will simply be extended and
+     the `paste-function' will not be called.
+
+\1f
+File: lispref.info,  Node: Extents and Events,  Next: Atomic Extents,  Prev: Duplicable Extents,  Up: Extents
+
+Interaction of Extents with Keyboard and Mouse Events
+=====================================================
+
+If an extent has the `mouse-face' property set, it will be highlighted
+when the mouse passes over it.  This includes the begin-glyph, but not
+the end-glyph.  Highlighting is accomplished by merging the extent's
+face with the face or faces specified by the `mouse-face' property.
+The effect is as if a pseudo-extent with the `mouse-face' face were
+inserted after the extent in the display order (*note Extent
+Endpoints::, display order).
+
+ - Variable: mouse-highlight-priority
+     This variable holds the priority to use when merging in the
+     highlighting pseudo-extent.  The default is 1000.  This is
+     purposely set very high so that the highlighting pseudo-extent
+     shows up even if there are other extents with various priorities
+     at the same location.
+
+   You can also explicitly cause an extent to be highlighted.  Only one
+extent at a time can be highlighted in this fashion, and any other
+highlighted extent will be de-highlighted.
+
+ - Function: highlight-extent extent &optional highlight-p
+     This function highlights (if HIGHLIGHT-P is non-`nil') or
+     de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
+     `mouse-face' property. (Nothing happens if EXTENT does not have
+     the `mouse-face' property.)
+
+ - Function: force-highlight-extent extent &optional highlight-p
+     This function is similar to `highlight-extent' but highlights or
+     de-highlights the extent regardless of whether it has the
+     `mouse-face' property.
+
+   If an extent has a `keymap' property, this keymap will be consulted
+for mouse clicks on the extent and keypresses made while `point' is
+within the extent.  The behavior of mouse clicks and keystrokes not
+defined in the keymap is as normal for the buffer.
+
+\1f
+File: lispref.info,  Node: Atomic Extents,  Prev: Extents and Events,  Up: Extents
+
+Atomic Extents
+==============
+
+If the Lisp file `atomic-extents' is loaded, then the atomic extent
+facility is available.  An "atomic extent" is an extent for which
+`point' cannot be positioned anywhere within it.  This ensures that
+when selecting text, either all or none of the extent is selected.
+
+   To make an extent atomic, set its `atomic' property.
+
+\1f
+File: lispref.info,  Node: Specifiers,  Next: Faces and Window-System Objects,  Prev: Extents,  Up: Top
+
+Specifiers
+**********
+
+A specifier is an object used to keep track of a property whose value
+should vary according to _display context_, a window, a frame, or
+device.  The value of many built-in properties, such as the font,
+foreground, background, and such properties of a face and variables
+such as `modeline-shadow-thickness' and `top-toolbar-height', is
+actually a specifier object.  The specifier object, in turn, is
+"instanced" in a particular situation to yield the real value of the
+property in the current context.
+
+ - Function: specifierp object
+     This function returns non-`nil' if OBJECT is a specifier.
+
+* Menu:
+
+* Introduction to Specifiers::  Specifiers provide a clean way for
+                                display and other properties to vary
+                                (under user control) in a wide variety
+                                of contexts.
+* Simple Specifier Usage::      Getting started with specifiers.
+* 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 Tag Functions::     Working with specifier tags.
+* Specifier Instancing Functions::
+                                Functions to instance a specifier.
+* Specifier Examples::          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.
+
+\1f
+File: lispref.info,  Node: Introduction to Specifiers,  Next: Simple Specifier Usage,  Up: Specifiers
+
+Introduction to Specifiers
+==========================
+
+Perhaps the most useful way to explain specifiers is via an analogy.
+Emacs Lisp programmers are used to _buffer-local variables_ *Note
+Buffer-Local Variables::. For example, the variable `modeline-format',
+which controls the format of the modeline, can have different values
+depending on the particular buffer being edited.  The variable has a
+default value which most modes will use, but a specialized package such
+as Calendar might change the variable so as to tailor the modeline to
+its own purposes. Other variables are perhaps best thought of as "mode
+local," such as font-lock keywords, but they are implemented as buffer
+locals.
+
+   Other properties (such as those that can be changed by the
+`modify-frame-parameters' function, for example the color of the text
+cursor) can have frame-local values, although it might also make sense
+for them to have buffer-local values.  In other cases, you might want
+the property to vary depending on the particular window within the
+frame that applies (e.g. the top or bottom window in a split frame), the
+device type that that frame appears on (X or tty), etc.  Perhaps you can
+envision some more complicated scenario where you want a particular
+value in a specified buffer, another value in all other buffers
+displayed on a particular frame, another value in all other buffers
+displayed in all other frames on any mono (two-color, e.g. black and
+white only) displays, and a default value in all other circumstances.
+
+   Specifiers generalize both buffer- and frame-local properties.
+Specifiers vary according to the _display_ context.  Font-lock keywords
+in a buffer will be the same no matter which window the buffer is
+displayed in, but windows on TTY devices will simply not be capable of
+the flexibility that windows on modern GUI devices are.  Specifiers
+provide a way for the programmer to _declare_ that an emphasized text
+should be italic on GUI devices and inverse video on TTYs.  They also
+provide a way for the programmer to declare fallbacks, so that a color
+specified as "chartreuse" where possible can fall back to "yellow" on
+devices where only ANSI (4-bit) color is available.  The complex
+calculations and device querying are transparent to both user and
+programmer.  You ask for what you want; it's up to XEmacs to provide
+it, or a reasonable approximation.
+
+   We call such a declaration a "specification".  A "specification"
+applies in a particular "locale", which is a window, buffer, frame,
+device, or the global locale.  The value part of the specification is
+called an "instantiator".  The process of determining the value in a
+particular context, or "domain", is called "instantiation" or
+"instancing".  A domain is a window, frame, or device.
+
+   The difference between "locale" and "domain" is somewhat subtle.
+You may think of a locale as a class of domains, which may span
+different devices.  Since the specification is abstract (a Lisp form),
+you can state it without reference to a device.  On the other hand, when
+you instantiate a specification, you must know the type of the device.
+It is useless to specify that "blue means emphasis" on a monochrome
+device.  Thus instantiation requires specification of the device on
+which it will be rendered.
+
+   Thus a "specifier" allows a great deal of flexibility in controlling
+exactly what value a property has in which circumstances.  Specifiers
+are most commonly used for display properties, such as an image or the
+foreground color of a face.  As a simple example, you can specify that
+the foreground of the default face be
+
+   * blue for a particular buffer
+
+   * green for all other buffers
+
+   As a more complicated example, you could specify that the foreground
+of the default face be
+
+   * forest green for all buffers displayed in a particular Emacs
+     window, or green if the X server doesn't recognize the color
+     `forest green'
+
+   * blue for all buffers displayed in a particular frame
+
+   * red for all other buffers displayed on a color device
+
+   * white for all other buffers
+
+\1f
+File: lispref.info,  Node: Simple Specifier Usage,  Next: Specifiers In-Depth,  Prev: Introduction to Specifiers,  Up: Specifiers
+
+Simple Specifier Usage
+======================
+
+A useful specifier application is adding a button to a toolbar.  XEmacs
+provides several toolbars, one along each edge of the frame.  Normally
+only one is used at a time, the default.  The default toolbar is
+actually a specifier object which is the value of `default-toolbar'.
+*Note Toolbar Intro::.
+
+   The specification of a toolbar is simple:  it is a list of buttons.
+Each button is a vector with four elements:  an icon, a command, the
+enabled flag, and a help string.  Let's retrieve the instance of the
+toolbar you see in the selected frame.
+
+     (specifier-instance default-toolbar)
+
+   The value returned is, as promised, a list of vectors.  Now let's
+build up a button, and add it to the toolbar.  Our button will invoke
+the last defined keyboard macro.  This is an alternative to
+`name-last-kbd-macro' for creating a persistent macro, rather than an
+alias for `C-x e'.
+
+   A toolbar button icon can be quite sophisticated, with different
+images for button up, button down, and disabled states, and a similar
+set with captions.  We'll use a very simple icon, but we have to jump
+through a few non-obvious hoops designed to support the sophisticated
+applications.  The rest of the button descriptor is straightforward.
+
+     (setq toolbar-my-kbd-macro-button
+       `[ (list (make-glyph "MyKbdMac"))
+          (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
+          t
+          "Execute a previously defined keyboard macro." ])
+     
+     (set-specifier default-toolbar
+                    (cons toolbar-my-kbd-macro-button
+                          (specifier-specs default-toolbar 'global))
+                    'global)
+
+   To remove the button, just substitute the function `delete' for the
+`cons' above.
+
+   What is the difference between `specifier-instance', which we used
+in the example of retrieving the toolbar descriptor, and
+`specifier-specs', which was used in the toolbar manipulating code?
+`specifier-specs' retrieves a copy of the instantiator, which is
+abstract and does not depend on context.  `specifier-instance', on the
+other hand, actually instantiates the specification, and returns the
+result for the given context.  Another way to express this is:
+`specifier-specs' takes a _locale_ as an argument, while
+`specifier-instance' takes a _domain_.  The reason for providing
+`specifier-instance' is that sometimes you wish to see the object that
+XEmacs will actually use.  `specifier-specs', on the other hand, shows
+you what the programmer (or user) requested.  When a program
+manipulates specifications, clearly it's the latter that is desirable.
+
+   In the case of the toolbar descriptor, it turns out that these are
+the same:  the instancing process is trivial.  However, many
+specifications have non-trivial instancing.  Compare the results of the
+following forms on my system.  (The `(cdr (first ...))' form is due to
+my use of Mule.  On non-Mule XEmacsen, just use `specifier-specs'.)
+
+     (cdr (first (specifier-specs (face-font 'default) 'global)))
+     => "-*--14-*jisx0208*-0"
+     
+     (specifier-instance (face-font 'default))
+     #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
+
+   In this case, `specifier-instance' returns an opaque object;
+programs can't work on it, they can only pass it around.  Worse, in some
+environments the instantiation will fail, resulting in a different value
+(when another instantiation succeeds), or worse yet, an error, if all
+attempts to instance the specifier fail.  `specifier-instance' is
+context-dependent, even for the exact same specification.
+`specifier-specs' is deterministic, and only depends on the
+specifications.
+
+   Note that in the toolbar-changing code we operate in the global
+locale.  This means that narrower locales, if they have specifications,
+will shadow our changes.  (Specifier instancing does not merge
+specifications.  It selects the "highest-priority successful
+specification" and instances that.)
+
+   In fact, in our example, it seems pretty likely that different
+buffers _should_ have different buttons.  (The icon can be the same, but
+the keyboard macro you create in a Dired buffer is highly unlikely to be
+useful in a LaTeX buffer!)  Here's one way to implement this:
+
+     (setq toolbar-my-kbd-macro-button
+       `[ (list (make-glyph "MyKbdMac"))
+          (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
+          t
+          "Execute a previously defined keyboard macro." ])
+     
+     (set-specifier default-toolbar
+                    (cons toolbar-my-kbd-macro-button
+                          (cond ((specifier-specs default-toolbar
+                                                  (current-buffer)))
+                                ((specifier-specs default-toolbar
+                                                  'global)))
+                    (current-buffer))
+
+   Finally, a cautionary note: the use of `specifier-specs' in the code
+above is for expository purposes.  Don't use it in production code.  In
+fact, the `set-specifier' form above is likely to fail occasionally,
+because you can add many specifications for the same locale.
+
+   In these cases, `specifier-specs' will return a list.  A further
+refinement is that a specification may be associated with a set of
+"specifier tags".  If the list of specifier tags is non-nil, then
+`specifier-specs' will return a cons of the tag set and the
+instantiator.  Evidently `specifier-specs' is a bit unreliable.  (For
+toolbars, the code above should work 99% of the time, because toolbars
+are rarely changed.  Since instantiation is trivial, multiple specs are
+not useful--the first one always succeeds.)
+
+   In fact, `specifier-specs' is intended to be used to display specs
+to humans with a minimum of clutter. The robust way to access
+specifications is via `specifier-spec-list'. *Note Adding
+Specifications::, for the definition of "spec-list". *Note Retrieving
+Specifications::, for documentation of `specifier-specs' and
+`specifier-spec-list'. To get the desired effect, replace the form
+`(specifier-spec default-toolbar 'global)' with
+
+     (cdr (second (first (specifier-spec-list default-toolbar 'global))))
+
+   (It should be obvious why the example uses the lazy unreliable
+method!)
+
+\1f
+File: lispref.info,  Node: Specifiers In-Depth,  Next: Specifier Instancing,  Prev: Simple Specifier Usage,  Up: Specifiers
+
+In-Depth Overview of a Specifier
+================================
+
+Having variables vary according the editing context is very useful, and
+the buffer is the natural "atomic" unit of editing context.  In a GUI
+environment, it can be similarly useful to have variables whose values
+vary according to display context.  The atomic unit of display context
+is the Emacs window.  Buffers are cleanly grouped by modes, but windows
+are not so easily pigeonholed.  On the one hand, a window displays a
+buffer, and thus one possible hierarchy is window, buffer, mode.  On the
+other, a window is a component of a frame.  This generates the window,
+frame, device hierarchy.  Finally, there are objects such as toolbars
+whose properties are described by specifiers.  These do not fit
+naturally into either hierarchy.  This problem is as yet not cleanly
+solved.
+
+   Another potential source of conceptual confusion is the instantiation
+process.  Instantiating a buffer-local variable is simple: at any given
+point in time there is a current buffer, and its local values are used
+and set whenever the variable is accessed, unless the programmer goes to
+some special effort (uses `default-value' and `set-default'.  However,
+a specifier object encapsulates a set of "specifications", each of
+which says what its value should be if a particular condition applies.
+Several such conditions might apply simultaneously in a given window.
+
+   For example, one specification might be "The value should be
+darkseagreen2 on X devices" another might be "The value should be blue
+in the *Help* buffer".  So what do we do for "the *Help* buffer on an X
+device"?  The answer is simple: give each type of locale a priority and
+check them in priority order, returning the first instantiator that
+successfully instantiates a value.
+
+   Given a specifier, a logical question is "What is its value in a
+particular situation?" This involves looking through the specifications
+to see which ones apply to this particular situation, and perhaps
+preferring one over another if more than one applies.  In specifier
+terminology, a "particular situation" is called a "domain", and
+determining its value in a particular domain is called "instancing".
+Most of the time, a domain is identified by a particular window.  For
+example, if the redisplay engine is drawing text in the default face in
+a particular window, it retrieves the specifier for the foreground color
+of the default face and "instances" it in the domain given by that
+window; in other words, it asks the specifier, "What is your value in
+this window?".
+
+   Note that the redisplay example is in a sense canonical.  That is,
+specifiers are designed to present a uniform and _efficient_ API to
+redisplay.  It is the efficiency constraint that motivates the
+introduction of specifier tags, and many restrictions on access (for
+example, a buffer is not a domain, and you cannot instantiate a
+specifier over a buffer).
+
+   More specifically, a specifier contains a set of "specifications",
+each of which associates a "locale" (a window object, a buffer object,
+a frame object, a device object, or the symbol `global') with an
+"inst-list", which is a list of one or more "inst-pairs". (For each
+possible locale, there can be at most one specification containing that
+locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
+zero or more symbols, or "tags") and an "instantiator" (the allowed
+form of this varies depending on the type of specifier).  In a given
+specification, there may be more than one inst-pair with the same tag
+set; this is unlike for locales.
+
+   The tag set is used to restrict the sorts of devices over which the
+instantiator is valid and to uniquely identify instantiators added by a
+particular application, so that different applications can work on the
+same specifier and not interfere with each other.  Each tag can have a
+"predicate" associated with it, which is a function of one argument (a
+device) that specifies whether the tag matches that particular device.
+(If a tag does not have a predicate, it matches all devices.)  All tags
+in a tag set must match a device for the associated inst-pair to be
+instantiable over that device.  (A null tag set is perfectly valid, and
+trivially matches all devices.)
+
+   The valid device types (normally `x', `tty', and `stream') and
+device classes (normally `color', `grayscale', and `mono') can always
+be used as tags, and match devices of the associated type or class
+(*note Consoles and Devices::).  User-defined tags may be defined, with
+an optional predicate specified.  An application can create its own
+tag, use it to mark all its instantiators, and be fairly confident that
+it will not interfere with other applications that modify the same
+specifier--Functions that add a specification to a specifier usually
+only overwrite existing inst-pairs with the same tag set as was given,
+and a particular tag or tag set can be specified when removing
+instantiators.
+
+   When a specifier is instanced in a domain, both the locale and the
+tag set can be viewed as specifying necessary conditions that must
+apply in that domain for an instantiator to be considered as a possible
+result of the instancing.  More specific locales always override more
+general locales (thus, there is no particular ordering of the
+specifications in a specifier); however, the tag sets are simply
+considered in the order that the inst-pairs occur in the
+specification's inst-list.
+
+   Note also that the actual object that results from the instancing
+(called an "instance object") may not be the same as the instantiator
+from which it was derived.  For some specifier types (such as integer
+specifiers and boolean specifiers), the instantiator will be returned
+directly as the instance object.  For other types, however, this is not
+the case.  For example, for font specifiers, the instantiator is a
+font-description string and the instance object is a font-instance
+object, which describes how the font is displayed on a particular
+device.  A font-instance object encapsulates such things as the actual
+font name used to display the font on that device (a font-description
+string under X is usually a wildcard specification that may resolve to
+different font names, with possibly different foundries, widths, etc.,
+on different devices), the extra properties of that font on that
+device, etc.  Furthermore, this conversion (called "instantiation")
+might fail--a font or color might not exist on a particular device, for
+example.
+
+\1f
+File: lispref.info,  Node: Specifier Instancing,  Next: Specifier Types,  Prev: Specifiers In-Depth,  Up: Specifiers
+
+How a Specifier Is Instanced
+============================
+
+Instancing of a specifier in a particular window domain proceeds as
+follows:
+
+   * First, XEmacs searches for a specification whose locale is the
+     same as the window.  If that fails, the search is repeated,
+     looking for a locale that is the same as the window's buffer.  If
+     that fails, the search is repeated using the window's frame, then
+     using the device that frame is on.  Finally, the specification
+     whose locale is the symbol `global' (if there is such a
+     specification) is considered.
+
+   * The inst-pairs contained in the specification that was found are
+     considered in their order in the inst-list, looking for one whose
+     tag set matches the device that is derived from the window domain.
+     (The tag set is an unordered list of zero or more tag symbols.
+     For all tags that have predicates associated with them, the
+     predicate must match the device.)
+
+   * If a matching tag set is found, the corresponding instantiator is
+     passed to the specifier's instantiation method, which is specific
+     to the type of the specifier.  If it succeeds, the resulting
+     instance object is returned as the result of the instancing and
+     the instancing is done.  Otherwise, the operation continues,
+     looking for another matching inst-pair in the current
+     specification.
+
+   * When there are no more inst-pairs to be considered in the current
+     specification, the search starts over, looking for another
+     specification as in the first step above.
+
+   * If all specifications are exhausted and no instance object can be
+     derived, the instancing fails. (Actually, this is not completely
+     true.  Some specifier objects for built-in properties have a
+     "fallback" value, which is either an inst-list or another
+     specifier object, that is consulted if the instancing is about to
+     fail.  If it is an inst-list, the searching proceeds using the
+     inst-pairs in that list.  If it is a specifier, the entire
+     instancing starts over using that specifier instead of the given
+     one.  Fallback values are set by the C code and cannot be
+     modified, except perhaps indirectly, using any Lisp functions.
+     The purpose of them is to supply some values to make sure that
+     instancing of built-in properties can't fail and to implement some
+     basic specifier inheritance, such as the fact that faces inherit
+     their properties from the `default' face.)
+
+   It is also possible to instance a specifier over a frame domain or
+device domain instead of over a window domain.  The C code, for example,
+instances the `top-toolbar-height' variable over a frame domain in
+order to determine the height of a frame's top toolbar.  Instancing over
+a frame or device is similar to instancing over a window except that
+specifications for locales that cannot be derived from the domain are
+ignored.  Specifically, instancing over a frame looks first for frame
+locales, then device locales, then the `global' locale.  Instancing
+over a device domain looks only for device locales and the `global'
+locale.
+
+\1f
+File: lispref.info,  Node: Specifier Types,  Next: Adding Specifications,  Prev: Specifier Instancing,  Up: Specifiers
+
+Specifier Types
+===============
+
+There are various different types of specifiers.  The type of a
+specifier controls what sorts of instantiators are valid, how an
+instantiator is instantiated, etc.  Here is a list of built-in specifier
+types:
+
+`boolean'
+     The valid instantiators are the symbols `t' and `nil'.  Instance
+     objects are the same as instantiators so no special instantiation
+     function is needed.
+
+`integer'
+     The valid instantiators are integers.  Instance objects are the
+     same as instantiators so no special instantiation function is
+     needed.  `modeline-shadow-thickness' is an example of an integer
+     specifier (negative thicknesses indicate that the shadow is drawn
+     recessed instead of raised).
+
+`natnum'
+     The valid instantiators are natnums (non-negative integers).
+     Instance objects are the same as instantiators so no special
+     instantiation function is needed.  Natnum specifiers are used for
+     dimension variables such as `top-toolbar-height'.
+
+`generic'
+     All Lisp objects are valid instantiators.  Instance objects are
+     the same as instantiators so no special instantiation function is
+     needed.
+
+`font'
+     The valid instantiators are strings describing fonts or vectors
+     indicating inheritance from the font of some face.  Instance
+     objects are font-instance objects, which are specific to a
+     particular device.  The instantiation method for font specifiers
+     can fail, unlike for integer, natnum, boolean, and generic
+     specifiers.
+
+`color'
+     The valid instantiators are strings describing colors or vectors
+     indicating inheritance from the foreground or background of some
+     face.  Instance objects are color-instance objects, which are
+     specific to a particular device.  The instantiation method for
+     color specifiers can fail, as for font specifiers.
+
+`image'
+     Images are perhaps the most complicated type of built-in
+     specifier.  The valid instantiators are strings (a filename,
+     inline data for a pixmap, or text to be displayed in a text glyph)
+     or vectors describing inline data of various sorts or indicating
+     inheritance from the background-pixmap property of some face.
+     Instance objects are either strings (for text images),
+     image-instance objects (for pixmap images), or subwindow objects
+     (for subwindow images).  The instantiation method for image
+     specifiers can fail, as for font and color specifiers.
+
+`face-boolean'
+     The valid instantiators are the symbols `t' and `nil' and vectors
+     indicating inheritance from a boolean property of some face.
+     Specifiers of this sort are used for all of the built-in boolean
+     properties of faces.  Instance objects are either the symbol `t'
+     or the symbol `nil'.
+
+`toolbar'
+     The valid instantiators are toolbar descriptors, which are lists
+     of toolbar-button descriptors (each of which is a vector of two or
+     four elements).  *Note Toolbar::, for more information.
+
+   Color and font instance objects can also be used in turn as
+instantiators for a new color or font instance object.  Since these
+instance objects are device-specific, the instantiator can be used
+directly as the new instance object, but only if they are of the same
+device.  If the devices differ, the base color or font of the
+instantiating object is effectively used instead as the instantiator.
+
+   *Note Faces and Window-System Objects::, for more information on
+fonts, colors, and face-boolean specifiers.  *Note Glyphs::, for more
+information about image specifiers.  *Note Toolbar::, for more
+information on toolbar specifiers.
+
+ - Function: specifier-type specifier
+     This function returns the type of SPECIFIER.  The returned value
+     will be a symbol: one of `integer', `boolean', etc., as listed in
+     the above table.
+
+   Functions are also provided to query whether an object is a
+particular kind of specifier:
+
+ - Function: boolean-specifier-p object
+     This function returns non-`nil' if OBJECT is a boolean specifier.
+
+ - Function: integer-specifier-p object
+     This function returns non-`nil' if OBJECT is an integer specifier.
+
+ - Function: natnum-specifier-p object
+     This function returns non-`nil' if OBJECT is a natnum specifier.
+
+ - Function: generic-specifier-p object
+     This function returns non-`nil' if OBJECT is a generic specifier.
+
+ - Function: face-boolean-specifier-p object
+     This function returns non-`nil' if OBJECT is a face-boolean
+     specifier.
+
+ - Function: toolbar-specifier-p object
+     This function returns non-`nil' if OBJECT is a toolbar specifier.
+
+ - Function: font-specifier-p object
+     This function returns non-`nil' if OBJECT is a font specifier.
+
+ - Function: color-specifier-p object
+     This function returns non-`nil' if OBJECT is a color specifier.
+
+ - Function: image-specifier-p object
+     This function returns non-`nil' if OBJECT is an image specifier.
+
+\1f
+File: lispref.info,  Node: Adding Specifications,  Next: Retrieving Specifications,  Prev: Specifier Types,  Up: Specifiers
+
+Adding specifications to a Specifier
+====================================
+
+ - Function: add-spec-to-specifier specifier instantiator &optional
+          locale tag-set how-to-add
+     This function adds a specification to SPECIFIER.  The
+     specification maps from LOCALE (which should be a window, buffer,
+     frame, device, or the symbol `global', and defaults to `global')
+     to INSTANTIATOR, whose allowed values depend on the type of the
+     specifier.  Optional argument TAG-SET limits the instantiator to
+     apply only to the specified tag set, which should be a list of
+     tags all of which must match the device being instantiated over
+     (tags are a device type, a device class, or tags defined with
+     `define-specifier-tag').  Specifying a single symbol for TAG-SET
+     is equivalent to specifying a one-element list containing that
+     symbol.  Optional argument HOW-TO-ADD specifies what to do if
+     there are already specifications in the specifier.  It should be
+     one of
+
+    `prepend'
+          Put at the beginning of the current list of instantiators for
+          LOCALE.
+
+    `append'
+          Add to the end of the current list of instantiators for
+          LOCALE.
+
+    `remove-tag-set-prepend'
+          This is the default.  Remove any existing instantiators whose
+          tag set is the same as TAG-SET; then put the new instantiator
+          at the beginning of the current list.
+
+    `remove-tag-set-append'
+          Remove any existing instantiators whose tag set is the same as
+          TAG-SET; then put the new instantiator at the end of the
+          current list.
+
+    `remove-locale'
+          Remove all previous instantiators for this locale before
+          adding the new spec.
+
+    `remove-locale-type'
+          Remove all specifications for all locales of the same type as
+          LOCALE (this includes LOCALE itself) before adding the new
+          spec.
+
+    `remove-all'
+          Remove all specifications from the specifier before adding
+          the new spec.
+
+     `remove-tag-set-prepend' is the default.
+
+     You can retrieve the specifications for a particular locale or
+     locale type with the function `specifier-spec-list' or
+     `specifier-specs'.
+
+ - Function: add-spec-list-to-specifier specifier spec-list &optional
+          how-to-add
+     This function adds a "spec-list" (a list of specifications) to
+     SPECIFIER.  The format of a spec-list is
+
+            `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
+
+     where
+
+        * LOCALE := a window, a buffer, a frame, a device, or `global'
+
+        * TAG-SET := an unordered list of zero or more TAGS, each of
+          which is a symbol
+
+        * TAG := a device class (*note Consoles and Devices::), a
+          device type, or a tag defined with `define-specifier-tag'
+
+        * INSTANTIATOR := format determined by the type of specifier
+
+     The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair".  A
+     list of inst-pairs is called an "inst-list".  The pair `(LOCALE .
+     INST-LIST)' is called a "specification".  A spec-list, then, can
+     be viewed as a list of specifications.
+
+     HOW-TO-ADD specifies how to combine the new specifications with
+     the existing ones, and has the same semantics as for
+     `add-spec-to-specifier'.
+
+     The higher-level function `set-specifier' is often more convenient
+     because it allows abbreviations of spec-lists to be used instead
+     of the heavily nested canonical syntax.  However, one should take
+     great care in using them with specifiers types which can have lists
+     as instantiators, such as toolbar specifiers and generic
+     specifiers.  In those cases it's probably best to use
+     `add-spec-to-specifier' or `add-spec-list-to-specifier'.
+
+ - Special Form: let-specifier specifier-list &rest body
+     This special form temporarily adds specifications to specifiers,
+     evaluates forms in BODY and restores the specifiers to their
+     previous states.  The specifiers and their temporary
+     specifications are listed in SPECIFIER-LIST.
+
+     The format of SPECIFIER-LIST is
+
+          ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
+
+     SPECIFIER is the specifier to be temporarily modified.  VALUE is
+     the instantiator to be temporarily added to specifier in LOCALE.
+     LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
+     `add-spec-to-specifier'.
+
+     This special form is implemented as a macro; the code resulting
+     from macro expansion will add specifications to specifiers using
+     `add-spec-to-specifier'.  After forms in BODY are evaluated, the
+     temporary specifications are removed and old specifier spec-lists
+     are restored.
+
+     LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
+     `nil'.  The value of the last form in BODY is returned.
+
+     NOTE: If you want the specifier's instance to change in all
+     circumstances, use `(selected-window)' as the LOCALE.  If LOCALE
+     is `nil' or omitted, it defaults to `global'.
+
+     The following example removes the 3D modeline effect in the
+     currently selected window for the duration of a second:
+
+          (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
+            (sit-for 1))
+
+ - Function: set-specifier specifier value &optional locale tag-set
+          how-to-add
+     This function adds some specifications to SPECIFIER.  VALUE can be
+     a single instantiator or tagged instantiator (added as a global
+     specification), a list of tagged and/or untagged instantiators
+     (added as a global specification), a cons of a locale and
+     instantiator or locale and instantiator list, a list of such
+     conses, or nearly any other reasonable form.  More specifically,
+     VALUE can be anything accepted by `canonicalize-spec-list'
+     (described below).
+
+     LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
+     `add-spec-to-specifier'.
+
+     Note that `set-specifier' is exactly complementary to
+     `specifier-specs' except in the case where SPECIFIER has no specs
+     at all in it but `nil' is a valid instantiator (in that case,
+     `specifier-specs' will return `nil' (meaning no specs) and
+     `set-specifier' will interpret the `nil' as meaning "I'm adding a
+     global instantiator and its value is `nil'"), or in strange cases
+     where there is an ambiguity between a spec-list and an inst-list,
+     etc. (The built-in specifier types are designed in such a way as
+     to avoid any such ambiguities.)  For robust code, `set-specifier'
+     should probably be avoided for specifier types which accept lists
+     as instantiators (currently toolbar specifiers and generic
+     specifiers).
+
+     If you want to work with spec-lists, you should probably not use
+     these functions, but should use the lower-level functions
+     `specifier-spec-list' and `add-spec-list-to-specifier'.  These
+     functions always work with fully-qualified spec-lists; thus, there
+     is no ambiguity.
+
+ - Function: canonicalize-inst-pair inst-pair specifier-type &optional
+          noerror
+     This function canonicalizes the given INST-PAIR.
+
+     SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+     will be used for.
+
+     Canonicalizing means converting to the full form for an inst-pair,
+     i.e.  `(TAG-SET . INSTANTIATOR)'.  A single, untagged instantiator
+     is given a tag set of `nil' (the empty set), and a single tag is
+     converted into a tag set consisting only of that tag.
+
+     If NOERROR is non-`nil', signal an error if the inst-pair is
+     invalid; otherwise return `t'.
+
+ - Function: canonicalize-inst-list inst-list specifier-type &optional
+          noerror
+     This function canonicalizes the given INST-LIST (a list of
+     inst-pairs).
+
+     SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
+     will be used for.
+
+     Canonicalizing means converting to the full form for an inst-list,
+     i.e.  `((TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
+     single inst-pair or any abbreviation thereof or a list of
+     (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
+
+     If NOERROR is non-`nil', signal an error if the inst-list is
+     invalid; otherwise return `t'.
+
+ - Function: canonicalize-spec spec specifier-type &optional noerror
+     This function canonicalizes the given SPEC (a specification).
+
+     SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+     will be used for.
+
+     Canonicalizing means converting to the full form for a spec, i.e.
+     `(LOCALE (TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
+     possibly abbreviated inst-list or a cons of a locale and a
+     possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
+
+     If NOERROR is `nil', signal an error if the specification is
+     invalid; otherwise return `t'.
+
+ - Function: canonicalize-spec-list spec-list specifier-type &optional
+          noerror
+     This function canonicalizes the given SPEC-LIST (a list of
+     specifications).
+
+     SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+     will be used for.
+
+     If NOERROR is `nil', signal an error if the spec-list is invalid;
+     otherwise return `t' for an invalid spec-list.  (Note that this
+     cannot be confused with a canonical spec-list.)
+
+     Canonicalizing means converting to the full form for a spec-list,
+     i.e.  `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'.  This
+     function accepts a possibly abbreviated specification or a list of
+     such things. (See `canonicalize-spec'.) This is the function used
+     to convert spec-lists accepted by `set-specifier' and such into a
+     form suitable for `add-spec-list-to-specifier'.
+
+     This function tries extremely hard to resolve any ambiguities, and
+     the built-in specifier types (font, image, toolbar, etc.) are
+     designed so that there won't be any ambiguities.
+
+     The canonicalization algorithm is as follows:
+
+       1. Attempt to parse SPEC-LIST as a single, possibly abbreviated,
+          specification.
+
+       2. If that fails, attempt to parse SPEC-LIST as a list of
+          (abbreviated) specifications.
+
+       3. If that fails, SPEC-LIST is invalid.
+
+     A possibly abbreviated specification SPEC is parsed by
+
+       1. Attempt to parse SPEC as a possibly abbreviated inst-list.
+
+       2. If that fails, attempt to parse SPEC as a cons of a locale
+          and an (abbreviated) inst-list.
+
+       3. If that fails, SPEC is invalid.
+
+     A possibly abbreviated inst-list INST-LIST is parsed by
+
+       1. Attempt to parse INST-LIST as a possibly abbreviated
+          inst-pair.
+
+       2. If that fails, attempt to parse INST-LIST as a list of
+          (abbreviated) inst-pairs.
+
+       3. If that fails, INST-LIST is invalid.
+
+     A possibly abbreviated inst-pair INST-PAIR is parsed by
+
+       1. Check if INST-PAIR is `valid-instantiator-p'.
+
+       2. If not, check if INST-PAIR is a cons of something that is a
+          tag, ie, `valid-specifier-tag-p', and something that is
+          `valid-instantiator-p'.
+
+       3. If not, check if INST-PAIR is a cons of a list of tags and
+          something that is `valid-instantiator-p'.
+
+       4. Otherwise, INST-PAIR is invalid.
+
+     In summary, this function generally prefers more abbreviated forms.
+
+\1f
+File: lispref.info,  Node: Retrieving Specifications,  Next: Specifier Tag Functions,  Prev: Adding Specifications,  Up: Specifiers
+
+Retrieving the Specifications from a Specifier
+==============================================
+
+ - Function: specifier-spec-list specifier &optional locale tag-set
+          exact-p
+     This function returns the spec-list of specifications for
+     SPECIFIER in LOCALE.
+
+     If LOCALE is a particular locale (a window, buffer, frame, device,
+     or the symbol `global'), a spec-list consisting of the
+     specification for that locale will be returned.
+
+     If LOCALE is a locale type (i.e. one of the symbols `window',
+     `buffer', `frame', or `device'), a spec-list of the specifications
+     for all locales of that type will be returned.
+
+     If LOCALE is `nil' or the symbol `all', a spec-list of all
+     specifications in SPECIFIER will be returned.
+
+     LOCALE can also be a list of locales, locale types, and/or `all';
+     the result is as if `specifier-spec-list' were called on each
+     element of the list and the results concatenated together.
+
+     Only instantiators where TAG-SET (a list of zero or more tags) is
+     a subset of (or possibly equal to) the instantiator's tag set are
+     returned.  (The default value of `nil' is a subset of all tag sets,
+     so in this case no instantiators will be screened out.) If EXACT-P
+     is non-`nil', however, TAG-SET must be equal to an instantiator's
+     tag set for the instantiator to be returned.
+
+ - Function: specifier-specs specifier &optional locale tag-set exact-p
+     This function returns the specification(s) for SPECIFIER in LOCALE.
+
+     If LOCALE is a single locale or is a list of one element
+     containing a single locale, then a "short form" of the
+     instantiators for that locale will be returned.  Otherwise, this
+     function is identical to `specifier-spec-list'.
+
+     The "short form" is designed for readability and not for ease of
+     use in Lisp programs, and is as follows:
+
+       1. If there is only one instantiator, then an inst-pair (i.e.
+          cons of tag and instantiator) will be returned; otherwise a
+          list of inst-pairs will be returned.
+
+       2. For each inst-pair returned, if the instantiator's tag is
+          `any', the tag will be removed and the instantiator itself
+          will be returned instead of the inst-pair.
+
+       3. If there is only one instantiator, its value is `nil', and
+          its tag is `any', a one-element list containing `nil' will be
+          returned rather than just `nil', to distinguish this case
+          from there being no instantiators at all.
+
+
+ - Function: specifier-fallback specifier
+     This function returns the fallback value for SPECIFIER.  Fallback
+     values are provided by the C code for certain built-in specifiers
+     to make sure that instancing won't fail even if all specs are
+     removed from the specifier, or to implement simple inheritance
+     behavior (e.g. this method is used to ensure that faces other than
+     `default' inherit their attributes from `default').  By design,
+     you cannot change the fallback value, and specifiers created with
+     `make-specifier' will never have a fallback (although a similar,
+     Lisp-accessible capability may be provided in the future to allow
+     for inheritance).
+
+     The fallback value will be an inst-list that is instanced like any
+     other inst-list, a specifier of the same type as SPECIFIER
+     (results in inheritance), or `nil' for no fallback.
+
+     When you instance a specifier, you can explicitly request that the
+     fallback not be consulted. (The C code does this, for example, when
+     merging faces.) See `specifier-instance'.
+
+\1f
+File: lispref.info,  Node: Specifier Tag Functions,  Next: Specifier Instancing Functions,  Prev: Retrieving Specifications,  Up: Specifiers
+
+Working With Specifier Tags
+===========================
+
+A specifier tag set is an entity that is attached to an instantiator
+and can be used to restrict the scope of that instantiator to a
+particular device class or device type and/or to mark instantiators
+added by a particular package so that they can be later removed.
+
+   A specifier tag set consists of a list of zero or more specifier
+tags, each of which is a symbol that is recognized by XEmacs as a tag.
+(The valid device types and device classes are always tags, as are any
+tags defined by `define-specifier-tag'.) It is called a "tag set" (as
+opposed to a list) because the order of the tags or the number of times
+a particular tag occurs does not matter.
+
+   Each tag has a predicate associated with it, which specifies whether
+that tag applies to a particular device.  The tags which are device
+types and classes match devices of that type or class.  User-defined
+tags can have any predicate, or none (meaning that all devices match).
+When attempting to instance a specifier, a particular instantiator is
+only considered if the device of the domain being instanced over matches
+all tags in the tag set attached to that instantiator.
+
+   Most of the time, a tag set is not specified, and the instantiator
+gets a null tag set, which matches all devices.
+
+ - Function: valid-specifier-tag-p tag
+     This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-specifier-tag-set-p tag-set
+     This function returns non-`nil' if TAG-SET is a valid specifier
+     tag set.
+
+ - Function: canonicalize-tag-set tag-set
+     This function canonicalizes the given tag set.  Two canonicalized
+     tag sets can be compared with `equal' to see if they represent the
+     same tag set. (Specifically, canonicalizing involves sorting by
+     symbol name and removing duplicates.)
+
+ - Function: device-matches-specifier-tag-set-p device tag-set
+     This function returns non-`nil' if DEVICE matches specifier tag
+     set TAG-SET.  This means that DEVICE matches each tag in the tag
+     set.
+
+ - Function: define-specifier-tag tag &optional predicate
+     This function defines a new specifier tag.  If PREDICATE is
+     specified, it should be a function of one argument (a device) that
+     specifies whether the tag matches that particular device.  If
+     PREDICATE is omitted, the tag matches all devices.
+
+     You can redefine an existing user-defined specifier tag.  However,
+     you cannot redefine the built-in specifier tags (the device types
+     and classes) or the symbols `nil', `t', `all', or `global'.
+
+ - Function: device-matching-specifier-tag-list &optional device
+     This function returns a list of all specifier tags matching
+     DEVICE.  DEVICE defaults to the selected device if omitted.
+
+ - Function: specifier-tag-list
+     This function returns a list of all currently-defined specifier
+     tags.  This includes the built-in ones (the device types and
+     classes).
+
+ - Function: specifier-tag-predicate tag
+     This function returns the predicate for the given specifier tag.
+
+\1f
+File: lispref.info,  Node: Specifier Instancing Functions,  Next: Specifier Examples,  Prev: Specifier Tag Functions,  Up: Specifiers
+
+Functions for Instancing a Specifier
+====================================
+
+ - Function: specifier-instance specifier &optional domain default
+          no-fallback
+     This function instantiates SPECIFIER (returns its value) in
+     DOMAIN.  If no instance can be generated for this domain, return
+     DEFAULT.
+
+     DOMAIN should be a window, frame, or device.  Other values that
+     are legal as a locale (e.g. a buffer) are not valid as a domain
+     because they do not provide enough information to identify a
+     particular device (see `valid-specifier-domain-p').  DOMAIN
+     defaults to the selected window if omitted.
+
+     "Instantiating" a specifier in a particular domain means
+     determining the specifier's "value" in that domain.  This is
+     accomplished by searching through the specifications in the
+     specifier that correspond to all locales that can be derived from
+     the given domain, from specific to general.  In most cases, the
+     domain is an Emacs window.  In that case specifications are
+     searched for as follows:
+
+       1. A specification whose locale is the window itself;
+
+       2. A specification whose locale is the window's buffer;
+
+       3. A specification whose locale is the window's frame;
+
+       4. A specification whose locale is the window's frame's device;
+
+       5. A specification whose locale is the symbol `global'.
+
+     If all of those fail, then the C-code-provided fallback value for
+     this specifier is consulted (see `specifier-fallback').  If it is
+     an inst-list, then this function attempts to instantiate that list
+     just as when a specification is located in the first five steps
+     above.  If the fallback is a specifier, `specifier-instance' is
+     called recursively on this specifier and the return value used.
+     Note, however, that if the optional argument NO-FALLBACK is
+     non-`nil', the fallback value will not be consulted.
+
+     Note that there may be more than one specification matching a
+     particular locale; all such specifications are considered before
+     looking for any specifications for more general locales.  Any
+     particular specification that is found may be rejected because it
+     is tagged to a particular device class (e.g. `color') or device
+     type (e.g. `x') or both and the device for the given domain does
+     not match this, or because the specification is not valid for the
+     device of the given domain (e.g.  the font or color name does not
+     exist for this particular X server).
+
+     The returned value is dependent on the type of specifier.  For
+     example, for a font specifier (as returned by the `face-font'
+     function), the returned value will be a font-instance object.  For
+     images, the returned value will be a string, pixmap, or subwindow.
+
+ - Function: specifier-matching-instance specifier matchspec &optional
+          domain default no-fallback
+     This function returns an instance for SPECIFIER in DOMAIN that
+     matches MATCHSPEC.  If no instance can be generated for DOMAIN,
+     return DEFAULT.
+
+     This function is identical to `specifier-instance' except that a
+     specification will only be considered if it matches MATCHSPEC.
+     The definition of "match," and allowed values for MATCHSPEC, are
+     dependent on the particular type of specifier.  Here are some
+     examples:
+
+        * For chartable (e.g. display table) specifiers, MATCHSPEC
+          should be a character, and the specification (a chartable)
+          must give a value for that character in order to be
+          considered.  This allows you to specify, _e.g._, a
+          buffer-local display table that only gives values for
+          particular characters.  All other characters are handled as
+          if the buffer-local display table is not there. (Chartable
+          specifiers are not yet implemented.)
+
+        * For font specifiers, MATCHSPEC should be a charset, and the
+          specification (a font string) must have a registry that
+          matches the charset's registry.  (This only makes sense with
+          Mule support.)  This makes it easy to choose a font that can
+          display a particular character.  (This is what redisplay
+          does, in fact.)
+
+ - Function: specifier-instance-from-inst-list specifier domain
+          inst-list &optional default
+     This function attempts to convert a particular inst-list into an
+     instance.  This attempts to instantiate INST-LIST in the given
+     DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
+     If the instantiation fails, DEFAULT is returned.  In most
+     circumstances, you should not use this function; use
+     `specifier-instance' instead.
+
+\1f
+File: lispref.info,  Node: Specifier Examples,  Next: Creating Specifiers,  Prev: Specifier Instancing Functions,  Up: Specifiers
+
+Examples of Specifier Usage
+===========================
+
+Now let us present an example to clarify the theoretical discussions we
+have been through.  In this example, we will use the general specifier
+functions for clarity.  Keep in mind that many types of specifiers, and
+some other types of objects that are associated with specifiers (e.g.
+faces), provide convenience functions making it easier to work with
+objects of that type.
+
+   Let us consider the background color of the default face.  A
+specifier is used to specify how that color will appear in different
+domains.  First, let's retrieve the specifier:
+
+     (setq sp (face-property 'default 'background))
+         =>   #<color-specifier 0x3da>
+
+     (specifier-specs sp)
+         =>   ((#<buffer "device.c"> (nil . "forest green"))
+                      (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
+                      (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
+                                                (nil . "moccasin"))
+                      (#<x-frame "VM" 0x4ac> (nil . "magenta"))
+                      (global ((tty) . "cyan") (nil . "white"))
+                     )
+
+   Then, say we want to determine what the background color of the
+default face is for the window currently displaying the buffer
+`*scratch*'.  We call
+
+     (get-buffer-window "*scratch*")
+         => #<window on "*scratch*" 0x4ad>
+     (window-frame (get-buffer-window "*scratch*"))
+         => #<x-frame "emacs" 0x4ac>
+     (specifier-instance sp (get-buffer-window "*scratch*"))
+         => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
+
+   Note that we passed a window to `specifier-instance', not a buffer.
+We cannot pass a buffer because a buffer by itself does not provide
+enough information.  The buffer might not be displayed anywhere at all,
+or could be displayed in many different frames on different devices.
+
+   The result is arrived at like this:
+
+  1. First, we look for a specification matching the buffer displayed
+     in the window, i.e. `*scratch*'.  There are none, so we proceed.
+
+  2. Then, we look for a specification matching the window itself.
+     Again, there are none.
+
+  3. Then, we look for a specification matching the window's frame.  The
+     specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
+     found.  We call the instantiation method for colors, passing it the
+     locale we were searching over (i.e. the window, in this case) and
+     the instantiator (`"puke orange"').  However, the particular device
+     which this window is on (let's say it's an X connection) doesn't
+     recognize the color `"puke orange"', so the specification is
+     rejected.
+
+  4. So we continue looking for a specification matching the window's
+     frame.  We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'.  Again,
+     we call the instantiation method for colors.  This time, the X
+     server our window is on recognizes the color `moccasin', and so the
+     instantiation method succeeds and returns a color instance.
+
+   Here's another example, which implements something like GNU Emacs's
+"frame-local" variables.
+
+     ;; Implementation
+     
+     ;; There are probably better ways to write this macro
+     ;; Heaven help you if VAR is a buffer-local; you will become very
+     ;; confused.  Probably should error on that.
+     (defmacro define-frame-local-variable (var)
+       "Make the unbound symbol VAR become a frame-local variable."
+       (let ((val (if (boundp var) (symbol-value var) nil)))
+         `(progn
+           (setq ,var (make-specifier 'generic))
+           (add-spec-to-specifier ,var ',val 'global))))
+     
+     ;; I'm not real happy about this terminology, how can `setq' be a defun?
+     ;; But `frame-set' would have people writing "(frame-set 'foo value)".
+     (defun frame-setq (var value &optional frame)
+       "Set the local value of VAR to VALUE in FRAME.
+     
+     FRAME defaults to the selected frame."
+       (and frame (not (framep frame))
+            (error 'invalid-argument "FRAME must be a frame", frame))
+       (add-spec-to-specifier var value (or frame (selected-frame))))
+     
+     (defun frame-value (var &optional frame)
+       "Get the local value of VAR in FRAME.
+     
+     FRAME defaults to the selected frame."
+       (and frame (not (framep frame))
+            (error 'invalid-argument "FRAME must be a frame", frame))
+       ;; this is not just a map from frames to values; it also falls back
+       ;; to the global value
+       (specifier-instance var (or frame (selected-frame))))
+     
+     ;; for completeness
+     (defun frame-set-default (var value)
+       "Set the default value of frame-local variable VAR to VALUE."
+       (add-spec-to-specifier var value 'global))
+     
+     (defun frame-get-default (var)
+       "Get the default value of frame-local variable VAR."
+       (car (specifier-specs var 'global)))
+
+   Now you can execute the above definitions (eg, with `eval-last-sexp')
+and switch to `*scratch*' to play.  Things will work differently if you
+already have a variable named `foo'.
+
+     ;; Usage
+     
+     foo
+     error--> Symbol's value as variable is void: foo
+     
+     (define-frame-local-variable foo)
+     => nil
+     
+     ;; the value of foo is a specifier, which is an opaque object;
+     ;; you must use accessor functions to get values
+     
+     foo
+     => #<generic-specifier global=(nil) 0x4f5cb>
+     
+     ;; since no frame-local value is set, the global value (which is the
+     ;; constant `nil') is returned
+     (frame-value foo)
+     => nil
+     
+     ;; get the default explicitly
+     (frame-get-default foo)
+     => nil
+     
+     ;; get the whole specification list
+     (specifier-specs foo 'global)
+     => (nil)
+     
+     ;; give foo a frame-local value
+     
+     (frame-setq foo 'bar)
+     => nil
+     
+     ;; access foo in several ways
+     
+     ;; Note that the print function for this kind of specifier only
+     ;; gives you the global setting.  To get the full list of specs for
+     ;; debugging or study purposes, you must use specifier-specs or
+     ;; specifier-spec-list.
+     foo
+     => #<generic-specifier global=(nil) 0x4f5cb>
+     
+     ;; get the whole specification list
+     (specifier-specs foo)
+     => ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))
+     
+     ;; get the frame-local value
+     (frame-value foo)
+     => bar
+     
+     ;; get the default explicitly
+     (frame-get-default foo)
+     => nil
+     
+     ;; Switch to another frame and evaluate:
+     ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
+     => baz
+     
+     ;; Switch back.
+     ;; C-x 5 o
+     (specifier-specs foo)
+     => ((#<x-frame "emacs" 0x28ec> (nil . baz))
+         (#<x-frame "Message" 0x1bd66> (nil . bar))
+         (global (nil)))
+     
+     (frame-value foo)
+     => bar
+     
+     (frame-get-default foo)
+     => nil
+
+   Note that since specifiers generalize both frame-local and
+buffer-local variables in a sensible way, XEmacs is not likely to put a
+high priority on implementing frame-local variables.  In fact, some
+developers think that frame-local variables are evil for the same
+reason that buffer-local variables are evil: the declaration is both
+global and invisible.  That is, you cannot tell whether a variable is
+"normal," buffer-local, or frame-local just by looking at it.  So if
+you have namespace management problems, and some other Lisp package
+happens to use a variable name that you already declared frame- or
+buffer-local, weird stuff happens, and it is extremely hard to track
+down.
+
+\1f
+File: lispref.info,  Node: Creating Specifiers,  Next: Specifier Validation Functions,  Prev: Specifier Examples,  Up: Specifiers
+
+Creating New Specifier Objects
+==============================
+
+ - Function: make-specifier type
+     This function creates a new specifier.
+
+     A specifier is an object that can be used to keep track of a
+     property whose value can be per-buffer, per-window, per-frame, or
+     per-device, and can further be restricted to a particular
+     device-type or device-class.  Specifiers are used, for example,
+     for the various built-in properties of a face; this allows a face
+     to have different values in different frames, buffers, etc.  For
+     more information, see `specifier-instance', `specifier-specs', and
+     `add-spec-to-specifier'; or, for a detailed description of
+     specifiers, including how they are instantiated over a particular
+     domain (i.e. how their value in that domain is determined), see
+     the chapter on specifiers in the XEmacs Lisp Reference Manual.
+
+     TYPE specifies the particular type of specifier, and should be one
+     of the symbols `generic', `integer', `natnum', `boolean', `color',
+     `font', `image', `face-boolean', or `toolbar'.
+
+     For more information on particular types of specifiers, see the
+     functions `make-generic-specifier', `make-integer-specifier',
+     `make-natnum-specifier', `make-boolean-specifier',
+     `make-color-specifier', `make-font-specifier',
+     `make-image-specifier', `make-face-boolean-specifier', and
+     `make-toolbar-specifier'.
+
+ - Function: make-specifier-and-init type spec-list &optional
+          dont-canonicalize
+     This function creates and initializes a new specifier.
+
+     This is a convenience API combining `make-specifier' and
+     `set-specifier' that allows you to create a specifier and add
+     specs to it at the same time.  TYPE specifies the specifier type.
+     Allowed types are as for `make-specifier'.
+
+     SPEC-LIST supplies the specification(s) to be added to the
+     specifier.  Any abbreviation of the full spec-list form accepted
+     by `canonicalize-spec-list' may be used.  However, if the optional
+     argument DONT-CANONICALIZE is non-`nil', canonicalization is not
+     performed, and the SPEC-LIST must already be in full form.
+
+ - Function: make-integer-specifier spec-list
+     Return a new `integer' 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.
+
+     Valid instantiators for integer specifiers are integers.
+
+ - Function: make-boolean-specifier spec-list
+     Return a new `boolean' 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.
+
+     Valid instantiators for boolean specifiers are `t' and `nil'.
+
+ - Function: make-natnum-specifier spec-list
+     Return a new `natnum' 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.
+
+     Valid instantiators for natnum specifiers are non-negative
+     integers.
+
+ - Function: make-generic-specifier spec-list
+     Return a new `generic' 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.
+
+     Valid instantiators for generic specifiers are all Lisp values.
+     They are returned back unchanged when a specifier is instantiated.
+
+ - Function: make-display-table-specifier spec-list
+     Return a new `display-table' 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.
+
+     Valid instantiators for display-table specifiers are described in
+     detail in the doc string for `current-display-table' (*note Active
+     Display Table::).
+
+\1f
+File: lispref.info,  Node: Specifier Validation Functions,  Next: Other Specification Functions,  Prev: Creating Specifiers,  Up: Specifiers
+
+Functions for Checking the Validity of Specifier Components
+===========================================================
+
+ - Function: valid-specifier-domain-p domain
+     This function returns non-`nil' if DOMAIN is a valid specifier
+     domain.  A domain is used to instance a specifier (i.e. determine
+     the specifier's value in that domain).  Valid domains are a
+     window, frame, or device.  (`nil' is not valid.)
+
+ - Function: valid-specifier-locale-p locale
+     This function returns non-`nil' if LOCALE is a valid specifier
+     locale.  Valid locales are a device, a frame, a window, a buffer,
+     and `global'.  (`nil' is not valid.)
+
+ - Function: valid-specifier-locale-type-p locale-type
+     Given a specifier LOCALE-TYPE, this function returns non-`nil' if
+     it is valid.  Valid locale types are the symbols `global',
+     `device', `frame', `window', and `buffer'. (Note, however, that in
+     functions that accept either a locale or a locale type, `global'
+     is considered an individual locale.)
+
+ - Function: valid-specifier-type-p specifier-type
+     Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
+     valid.  Valid types are `generic', `integer', `boolean', `color',
+     `font', `image', `face-boolean', and `toolbar'.
+
+ - Function: valid-specifier-tag-p tag
+     This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-instantiator-p instantiator specifier-type
+     This function returns non-`nil' if INSTANTIATOR is valid for
+     SPECIFIER-TYPE.
+
+ - Function: valid-inst-list-p inst-list type
+     This function returns non-`nil' if INST-LIST is valid for
+     specifier type TYPE.
+
+ - Function: valid-spec-list-p spec-list type
+     This function returns non-`nil' if SPEC-LIST is valid for
+     specifier type TYPE.
+
+ - Function: check-valid-instantiator instantiator specifier-type
+     This function signals an error if INSTANTIATOR is invalid for
+     SPECIFIER-TYPE.
+
+ - Function: check-valid-inst-list inst-list type
+     This function signals an error if INST-LIST is invalid for
+     specifier type TYPE.
+
+ - Function: check-valid-spec-list spec-list type
+     This function signals an error if SPEC-LIST is invalid for
+     specifier type TYPE.
+
+\1f
+File: lispref.info,  Node: Other Specification Functions,  Prev: Specifier Validation Functions,  Up: Specifiers
+
+Other Functions for Working with Specifications in a Specifier
+==============================================================
+
+ - Function: copy-specifier specifier &optional dest locale tag-set
+          exact-p how-to-add
+     This function copies SPECIFIER to DEST, or creates a new one if
+     DEST is `nil'.
+
+     If DEST is `nil' or omitted, a new specifier will be created and
+     the specifications copied into it.  Otherwise, the specifications
+     will be copied into the existing specifier in DEST.
+
+     If LOCALE is `nil' or the symbol `all', all specifications will be
+     copied.  If LOCALE is a particular locale, the specification for
+     that particular locale will be copied.  If LOCALE is a locale
+     type, the specifications for all locales of that type will be
+     copied.  LOCALE can also be a list of locales, locale types,
+     and/or `all'; this is equivalent to calling `copy-specifier' for
+     each of the elements of the list.  See `specifier-spec-list' for
+     more information about LOCALE.
+
+     Only instantiators where TAG-SET (a list of zero or more tags) is
+     a subset of (or possibly equal to) the instantiator's tag set are
+     copied.  (The default value of `nil' is a subset of all tag sets,
+     so in this case no instantiators will be screened out.) If EXACT-P
+     is non-`nil', however, TAG-SET must be equal to an instantiator's
+     tag set for the instantiator to be copied.
+
+     Optional argument HOW-TO-ADD specifies what to do with existing
+     specifications in DEST.  If `nil', then whichever locales or locale
+     types are copied will first be completely erased in DEST.
+     Otherwise, it is the same as in `add-spec-to-specifier'.
+
+ - Function: remove-specifier specifier &optional locale tag-set exact-p
+     This function removes specification(s) for SPECIFIER.
+
+     If LOCALE is a particular locale (a buffer, window, frame, device,
+     or the symbol `global'), the specification for that locale will be
+     removed.
+
+     If instead, LOCALE is a locale type (i.e. a symbol `buffer',
+     `window', `frame', or `device'), the specifications for all
+     locales of that type will be removed.
+
+     If LOCALE is `nil' or the symbol `all', all specifications will be
+     removed.
+
+     LOCALE can also be a list of locales, locale types, and/or `all';
+     this is equivalent to calling `remove-specifier' for each of the
+     elements in the list.
+
+     Only instantiators where TAG-SET (a list of zero or more tags) is
+     a subset of (or possibly equal to) the instantiator's tag set are
+     removed.  (The default value of `nil' is a subset of all tag sets,
+     so in this case no instantiators will be screened out.) If EXACT-P
+     is non-`nil', however, TAG-SET must be equal to an instantiator's
+     tag set for the instantiator to be removed.
+
+ - Function: map-specifier specifier func &optional locale maparg
+     This function applies FUNC to the specification(s) for LOCALE in
+     SPECIFIER.
+
+     If optional LOCALE is a locale, FUNC will be called for that
+     locale.  If LOCALE is a locale type, FUNC will be mapped over all
+     locales of that type.  If LOCALE is `nil' or the symbol `all',
+     FUNC will be mapped over all locales in SPECIFIER.
+
+     Optional MS-MAPARG will be passed to MS-FUNC.
+
+     FUNC is called with four arguments: the SPECIFIER, the locale
+     being mapped over, the inst-list for that locale, and the optional
+     MAPARG.  If any invocation of FUNC returns non-`nil', the mapping
+     will stop and the returned value becomes the value returned from
+     `map-specifier'.  Otherwise, `map-specifier' returns `nil'.
+
+ - Function: specifier-locale-type-from-locale locale
+     Given a specifier LOCALE, this function returns its type.
+
+\1f
+File: lispref.info,  Node: Faces and Window-System Objects,  Next: Glyphs,  Prev: Specifiers,  Up: Top
+
+Faces and Window-System Objects
+*******************************
+
+* Menu:
+
+* Faces::              Controlling the way text looks.
+* Fonts::              Controlling the typeface of text.
+* Colors::             Controlling the color of text and pixmaps.
+
+\1f
+File: lispref.info,  Node: Faces,  Next: Fonts,  Up: Faces and Window-System Objects
+
+Faces
+=====
+
+A "face" is a named collection of graphical properties: font,
+foreground color, background color, background pixmap, optional
+underlining, and (on TTY devices) whether the text is to be highlighted,
+dimmed, blinking, or displayed in reverse video.  Faces control the
+display of text on the screen.  Every face has a name, which is a symbol
+such as `default' or `modeline'.
+
+   Each built-in property of a face is controlled using a specifier,
+which allows it to have separate values in particular buffers, frames,
+windows, and devices and to further vary according to device type (X or
+TTY) and device class (color, mono, or grayscale).  *Note Specifiers::,
+for more information.
+
+   The face named `default' is used for ordinary text.  The face named
+`modeline' is used for displaying the modeline.  The face named
+`highlight' is used for highlighted extents (*note Extents::).  The
+faces named `left-margin' and `right-margin' are used for the left and
+right margin areas, respectively (*note Annotations::).  The face named
+`zmacs-region' is used for the highlighted region between point and
+mark.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Merging Faces,  Next: Basic Face Functions,  Up: Faces
+
+Merging Faces for Display
+-------------------------
+
+Here are all the ways to specify which face to use for display of text:
+
+   * With defaults.  Each frame has a "default face", which is used for
+     all text that doesn't somehow specify another face.  The face named
+     `default' applies to the text area, while the faces `left-margin'
+     and `right-margin' apply to the left and right margin areas.
+
+   * With text properties.  A character may have a `face' property; if
+     so, it's displayed with that face. (Text properties are actually
+     implemented in terms of extents.) *Note Text Properties::.
+
+   * With extents.  An extent may have a `face' property, which applies
+     to all the text covered by the extent; in addition, if the
+     `highlight' property is set, the `highlight' property applies when
+     the mouse moves over the extent or if the extent is explicitly
+     highlighted.  *Note Extents::.
+
+   * With annotations.  Annotations that are inserted into a buffer can
+     specify their own face. (Annotations are actually implemented in
+     terms of extents.)  *Note Annotations::.
+
+   If these various sources together specify more than one face for a
+particular character, XEmacs merges the properties of the various faces
+specified.  Extents, text properties, and annotations all use the same
+underlying representation (as extents).  When multiple extents cover one
+character, an extent with higher priority overrides those with lower
+priority.  *Note Extents::.  If no extent covers a particular character,
+the `default' face is used.
+
+   If a background pixmap is specified, it determines what will be
+displayed in the background of text characters.  If the background
+pixmap is actually a pixmap, with its colors specified, those colors are
+used; if it is a bitmap, the face's foreground and background colors are
+used to color it.
+
+\1f
+File: lispref.info,  Node: Basic Face Functions,  Next: Face Properties,  Prev: Merging Faces,  Up: Faces
+
+Basic Functions for Working with Faces
+--------------------------------------
+
+The properties a face can specify include the font, the foreground
+color, the background color, the background pixmap, the underlining,
+the display table, and (for TTY devices) whether the text is to be
+highlighted, dimmed, blinking, or displayed in reverse video.  The face
+can also leave these unspecified, causing them to assume the value of
+the corresponding property of the `default' face.
+
+   Here are the basic primitives for working with faces.
+
+ - Function: make-face name &optional doc-string temporary
+     This function defines and returns a new face named NAME, initially
+     with all properties unspecified.  It does nothing if there is
+     already a face named NAME.  Optional argument DOC-STRING specifies
+     an explanatory string used for descriptive purposes.  If optional
+     argument TEMPORARY is non-`nil', the face will automatically
+     disappear when there are no more references to it anywhere in text
+     or Lisp code (otherwise, the face will continue to exist
+     indefinitely even if it is not used).
+
+ - Function: face-list &optional temporary
+     This function returns a list of the names of all defined faces.  If
+     TEMPORARY is `nil', only the permanent faces are included.  If it
+     is `t', only the temporary faces are included.  If it is any other
+     non-`nil' value both permanent and temporary are included.
+
+ - Function: facep object
+     This function returns `t' if OBJECT is a face, else `nil'.
+
+ - Function: copy-face old-face new-name &optional locale tag-set
+          exact-p how-to-add
+     This function defines a new face named NEW-NAME which is a copy of
+     the existing face named OLD-FACE.  If there is already a face
+     named NEW-NAME, then it alters the face to have the same
+     properties as OLD-FACE.
+
+     LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of
+     the old face rather than the whole face, and are as in
+     `copy-specifier' (*note Specifiers::).
+
+\1f
+File: lispref.info,  Node: Face Properties,  Next: Face Convenience Functions,  Prev: Basic Face Functions,  Up: Faces
+
+Face Properties
+---------------
+
+You can examine and modify the properties of an existing face with the
+following functions.
+
+   The following symbols have predefined meanings:
+
+`foreground'
+     The foreground color of the face.
+
+`background'
+     The background color of the face.
+
+`font'
+     The font used to display text covered by this face.
+
+`display-table'
+     The display table of the face.
+
+`background-pixmap'
+     The pixmap displayed in the background of the face.  Only used by
+     faces on X devices.
+
+`underline'
+     Underline all text covered by this face.
+
+`highlight'
+     Highlight all text covered by this face.  Only used by faces on TTY
+     devices.
+
+`dim'
+     Dim all text covered by this face.  Only used by faces on TTY
+     devices.
+
+`blinking'
+     Blink all text covered by this face.  Only used by faces on TTY
+     devices.
+
+`reverse'
+     Reverse the foreground and background colors.  Only used by faces
+     on TTY devices.
+
+`doc-string'
+     Description of what the face's normal use is.  NOTE: This is not a
+     specifier, unlike all the other built-in properties, and cannot
+     contain locale-specific values.
+
+ - Function: set-face-property face property value &optional locale
+          tag-set how-to-add
+     This function changes a property of a FACE.
+
+     For built-in properties, the actual value of the property is a
+     specifier and you cannot change this; but you can change the
+     specifications within the specifier, and that is what this
+     function will do.  For user-defined properties, you can use this
+     function to either change the actual value of the property or, if
+     this value is a specifier, change the specifications within it.
+
+     If PROPERTY is a built-in property, the specifications to be added
+     to this property can be supplied in many different ways:
+
+          If VALUE is a simple instantiator (e.g. a string naming a
+          font or color) or a list of instantiators, then the
+          instantiator(s) will be added as a specification of the
+          property for the given LOCALE (which defaults to `global' if
+          omitted).
+
+          If VALUE is a list of specifications (each of which is a cons
+          of a locale and a list of instantiators), then LOCALE must be
+          `nil' (it does not make sense to explicitly specify a locale
+          in this case), and specifications will be added as given.
+
+          If VALUE is a specifier (as would be returned by
+          `face-property' if no LOCALE argument is given), then some or
+          all of the specifications in the specifier will be added to
+          the property.  In this case, the function is really
+          equivalent to `copy-specifier' and LOCALE has the same
+          semantics (if it is a particular locale, the specification
+          for the locale will be copied; if a locale type,
+          specifications for all locales of that type will be copied;
+          if `nil' or `all', then all specifications will be copied).
+
+     HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+     `append', `remove-tag-set-prepend', `remove-tag-set-append',
+     `remove-locale', `remove-locale-type', or `remove-all'.  See
+     `copy-specifier' and `add-spec-to-specifier' for a description of
+     what each of these means.  Most of the time, you do not need to
+     worry about this argument; the default behavior usually is fine.
+
+     In general, it is OK to pass an instance object (e.g. as returned
+     by `face-property-instance') as an instantiator in place of an
+     actual instantiator.  In such a case, the instantiator used to
+     create that instance object will be used (for example, if you set
+     a font-instance object as the value of the `font' property, then
+     the font name used to create that object will be used instead).
+     If some cases, however, doing this conversion does not make sense,
+     and this will be noted in the documentation for particular types
+     of instance objects.
+
+     If PROPERTY is not a built-in property, then this function will
+     simply set its value if LOCALE is `nil'.  However, if LOCALE is
+     given, then this function will attempt to add VALUE as the
+     instantiator for the given LOCALE, using `add-spec-to-specifier'.
+     If the value of the property is not a specifier, it will
+     automatically be converted into a `generic' specifier.
+
+ - Function: remove-face-property face property &optional locale
+          tag-set exact-p
+     This function removes a property of a FACE.
+
+     For built-in properties, this is analogous to `remove-specifier'.
+     For more information, *Note Other Specification Functions::.
+
+     When PROPERTY is not a built-in property, this function will just
+     remove its value if LOCALE is `nil' or `all'.  However, if LOCALE
+     is other than that, this function will attempt to remove VALUE as
+     the instantiator for the given LOCALE with `remove-specifier'.  If
+     the value of the property is not a specifier, it will be converted
+     into a `generic' specifier automatically.
+
+ - Function: face-property face property &optional locale tag-set
+          exact-p
+     This function returns FACE's value of the given PROPERTY.
+
+     If LOCALE is omitted, the FACE's actual value for PROPERTY will be
+     returned.  For built-in properties, this will be a specifier
+     object of a type appropriate to the property (e.g. a font or color
+     specifier).  For other properties, this could be anything.
+
+     If LOCALE is supplied, then instead of returning the actual value,
+     the specification(s) for the given locale or locale type will be
+     returned.  This will only work if the actual value of PROPERTY is
+     a specifier (this will always be the case for built-in properties,
+     but not or not may apply to user-defined properties).  If the
+     actual value of PROPERTY is not a specifier, this value will
+     simply be returned regardless of LOCALE.
+
+     The return value will be a list of instantiators (e.g. strings
+     specifying a font or color name), or a list of specifications,
+     each of which is a cons of a locale and a list of instantiators.
+     Specifically, if LOCALE is a particular locale (a buffer, window,
+     frame, device, or `global'), a list of instantiators for that
+     locale will be returned.  Otherwise, if LOCALE is a locale type
+     (one of the symbols `buffer', `window', `frame', or `device'), the
+     specifications for all locales of that type will be returned.
+     Finally, if LOCALE is `all', the specifications for all locales of
+     all types will be returned.
+
+     The specifications in a specifier determine what the value of
+     PROPERTY will be in a particular "domain" or set of circumstances,
+     which is typically a particular Emacs window along with the buffer
+     it contains and the frame and device it lies within.  The value is
+     derived from the instantiator associated with the most specific
+     locale (in the order buffer, window, frame, device, and `global')
+     that matches the domain in question.  In other words, given a
+     domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+     will first be searched for a specification whose locale is the
+     buffer contained within that window; then for a specification
+     whose locale is the window itself; then for a specification whose
+     locale is the frame that the window is contained within; etc.  The
+     first instantiator that is valid for the domain (usually this
+     means that the instantiator is recognized by the device [i.e. the
+     X server or TTY device] that the domain is on).  The function
+     `face-property-instance' actually does all this, and is used to
+     determine how to display the face.
+
+ - Function: face-property-instance face property &optional domain
+          default no-fallback
+     This function returns the instance of FACE's PROPERTY in the
+     specified DOMAIN.
+
+     Under most circumstances, DOMAIN will be a particular window, and
+     the returned instance describes how the specified property
+     actually is displayed for that window and the particular buffer in
+     it.  Note that this may not be the same as how the property
+     appears when the buffer is displayed in a different window or
+     frame, or how the property appears in the same window if you
+     switch to another buffer in that window; and in those cases, the
+     returned instance would be different.
+
+     The returned instance will typically be a color-instance,
+     font-instance, or pixmap-instance object, and you can query it
+     using the appropriate object-specific functions.  For example, you
+     could use `color-instance-rgb-components' to find out the RGB
+     (red, green, and blue) components of how the `background' property
+     of the `highlight' face is displayed in a particular window.  The
+     results might be different from the results you would get for
+     another window (perhaps the user specified a different color for
+     the frame that window is on; or perhaps the same color was
+     specified but the window is on a different X server, and that X
+     server has different RGB values for the color from this one).
+
+     DOMAIN defaults to the selected window if omitted.
+
+     DOMAIN can be a frame or device, instead of a window.  The value
+     returned for a such a domain is used in special circumstances when
+     a more specific domain does not apply; for example, a frame value
+     might be used for coloring a toolbar, which is conceptually
+     attached to a frame rather than a particular window.  The value is
+     also useful in determining what the value would be for a
+     particular window within the frame or device, if it is not
+     overridden by a more specific specification.
+
+     If PROPERTY does not name a built-in property, its value will
+     simply be returned unless it is a specifier object, in which case
+     it will be instanced using `specifier-instance'.
+
+     Optional arguments DEFAULT and NO-FALLBACK are the same as in
+     `specifier-instance'.  *Note Specifiers::.
+
+\1f
+File: lispref.info,  Node: Face Convenience Functions,  Next: Other Face Display Functions,  Prev: Face Properties,  Up: Faces
+
+Face Convenience Functions
+--------------------------
+
+ - Command: set-face-foreground face color &optional locale tag-set
+          how-to-add
+ - Command: set-face-background face color &optional locale tag-set
+          how-to-add
+     These functions set the foreground (respectively, background)
+     color of face FACE to COLOR.  The argument COLOR should be a
+     string (the name of a color) or a color object as returned by
+     `make-color' (*note Colors::).
+
+ - Command: set-face-background-pixmap face pixmap &optional locale
+          tag-set how-to-add
+     This function sets the background pixmap of face FACE to PIXMAP.
+     The argument PIXMAP should be a string (the name of a bitmap or
+     pixmap file; the directories listed in the variable
+     `x-bitmap-file-path' will be searched) or a glyph object as
+     returned by `make-glyph' (*note Glyphs::).  The argument may also
+     be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
+     are the size in pixels, and DATA is a string, containing the raw
+     bits of the bitmap.
+
+ - Command: set-face-font face font &optional locale tag-set how-to-add
+     This function sets the font of face FACE.  The argument FONT
+     should be a string or a font object as returned by `make-font'
+     (*note Fonts::).
+
+ - Command: set-face-underline-p face underline-p &optional locale
+          tag-set how-to-add
+     This function sets the underline property of face FACE.
+
+ - Function: face-foreground face &optional locale tag-set exact-p
+ - Function: face-background face &optional locale tag-set exact-p
+     These functions return the foreground (respectively, background)
+     color specifier of face FACE.  *Note Colors::.
+
+ - Function: face-background-pixmap face &optional locale tag-set
+          exact-p
+     This function return the background-pixmap glyph object of face
+     FACE.
+
+ - Function: face-font face &optional locale tag-set exact-p
+     This function returns the font specifier of face FACE.  (Note:
+     This is not the same as the function `face-font' in FSF Emacs.)
+
+     *Note Fonts::.
+
+ - Function: face-font-name face &optional domain
+     This function returns the name of the font of face FACE, or `nil'
+     if it is unspecified.  This is basically equivalent to `(font-name
+     (face-font FACE) DOMAIN)' except that it does not cause an error
+     if FACE's font is `nil'. (This function is named `face-font' in
+     FSF Emacs.)
+
+ - Function: face-underline-p face &optional locale
+     This function returns the underline property of face FACE.
+
+ - Function: face-foreground-instance face &optional domain
+ - Function: face-background-instance face &optional domain
+     These functions return the foreground (respectively, background)
+     color specifier of face FACE.  *Note Colors::.
+
+ - Function: face-background-pixmap-instance face &optional domain
+     This function return the background-pixmap glyph object of face
+     FACE.
+
+ - Function: face-font-instance face &optional domain
+     This function returns the font specifier of face FACE.  *Note
+     Fonts::.
+
+\1f
+File: lispref.info,  Node: Other Face Display Functions,  Prev: Face Convenience Functions,  Up: Faces
+
+Other Face Display Functions
+----------------------------
+
+ - Command: invert-face face &optional locale
+     Swap the foreground and background colors of face FACE.  If the
+     face doesn't specify both foreground and background, then its
+     foreground and background are set to the default background and
+     foreground.
+
+ - Function: face-equal face1 face2 &optional domain
+     This returns `t' if the faces FACE1 and FACE2 will display in the
+     same way.  DOMAIN is as in `face-property-instance'.
+
+ - Function: face-differs-from-default-p face &optional domain
+     This returns `t' if the face FACE displays differently from the
+     default face.  DOMAIN is as in `face-property-instance'.
+
+\1f
+File: lispref.info,  Node: Fonts,  Next: Colors,  Prev: Faces,  Up: Faces and Window-System Objects
+
+Fonts
+=====
+
+This section describes how to work with font specifier and font
+instance objects, which encapsulate fonts in the window system.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Font Specifiers,  Next: Font Instances,  Up: Fonts
+
+Font Specifiers
+---------------
+
+ - Function: font-specifier-p object
+     This predicate returns `t' if OBJECT is a font specifier, and
+     `nil' otherwise.
+
+ - Function: make-font-specifier spec-list
+     Return a new `font' 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.
+
+     Valid instantiators for font specifiers are:
+
+        * A string naming a font (e.g. under X this might be
+          "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
+          14-point upright medium-weight Courier font).
+
+        * A font instance (use that instance directly if the device
+          matches, or use the string that generated it).
+
+        * A vector of no elements (only on TTY's; this means to set no
+          font at all, thus using the "natural" font of the terminal's
+          text).
+
+        * A vector of one element (a face to inherit from).
+
+\1f
+File: lispref.info,  Node: Font Instances,  Next: Font Instance Names,  Prev: Font Specifiers,  Up: Fonts
+
+Font Instances
+--------------
+
+ - Function: font-instance-p object
+     This predicate returns `t' if OBJECT is a font instance, and `nil'
+     otherwise.
+
+ - Function: make-font-instance name &optional device noerror
+     This function creates a new font-instance object of the specified
+     name.  DEVICE specifies the device this object applies to and
+     defaults to the selected device.  An error is signalled if the
+     font is unknown or cannot be allocated; however, if NOERROR is
+     non-`nil', `nil' is simply returned in this case.
+
+     The returned object is a normal, first-class lisp object.  The way
+     you "deallocate" the font is the way you deallocate any other lisp
+     object: you drop all pointers to it and allow it to be garbage
+     collected.  When these objects are GCed, the underlying X data is
+     deallocated as well.
+
+\1f
+File: lispref.info,  Node: Font Instance Names,  Next: Font Instance Size,  Prev: Font Instances,  Up: Fonts
+
+Font Instance Names
+-------------------
+
+ - Function: list-fonts pattern &optional device
+     This function returns a list of font names matching the given
+     pattern.  DEVICE specifies which device to search for names, and
+     defaults to the currently selected device.
+
+ - Function: font-instance-name font-instance
+     This function returns the name used to allocate FONT-INSTANCE.
+
+ - Function: font-instance-truename font-instance
+     This function returns the canonical name of the given font
+     instance.  Font names are patterns which may match any number of
+     fonts, of which the first found is used.  This returns an
+     unambiguous name for that font (but not necessarily its only
+     unambiguous name).

 
 

diff --git a/info/lispref.info-7 b/info/lispref.info-7
index f680a25..b3dfd60 100644 (file)
--- a/info/lispref.info-7
+++ b/info/lispref.info-7
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1218 +50,7045 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: Sequence Functions,  Next: Arrays,  Up: Sequences Arrays Vectors
-
-Sequences
-=========
-
-   In XEmacs Lisp, a "sequence" is either a list, a vector, a bit
-vector, or a string.  The common property that all sequences have is
-that each is an ordered collection of elements.  This section describes
-functions that accept any kind of sequence.
-
- - Function: sequencep object
-     Returns `t' if OBJECT is a list, vector, bit vector, or string,
-     `nil' otherwise.
-
- - Function: copy-sequence sequence
-     Returns a copy of SEQUENCE.  The copy is the same type of object
-     as the original sequence, and it has the same elements in the same
-     order.
-
-     Storing a new element into the copy does not affect the original
-     SEQUENCE, and vice versa.  However, the elements of the new
-     sequence are not copies; they are identical (`eq') to the elements
-     of the original.  Therefore, changes made within these elements, as
-     found via the copied sequence, are also visible in the original
-     sequence.
-
-     If the sequence is a string with extents or text properties, the
-     extents and text properties in the copy are also copied, not
-     shared with the original. (This means that modifying the extents
-     or text properties of the original will not affect the copy.)
-     However, the actual values of the properties are shared.  *Note
-     Extents::, *Note Text Properties::.
-
-     See also `append' in *Note Building Lists::, `concat' in *Note
-     Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
-     in *Note Bit Vectors::, for other ways to copy sequences.
-
-          (setq bar '(1 2))
-               => (1 2)
-          (setq x (vector 'foo bar))
-               => [foo (1 2)]
-          (setq y (copy-sequence x))
-               => [foo (1 2)]
+File: lispref.info,  Node: Font Instance Size,  Next: Font Instance Characteristics,  Prev: Font Instance Names,  Up: Fonts
+
+Font Instance Size
+------------------
+
+ - Function: x-font-size font
+     This function returns the nominal size of the given font.  This is
+     done by parsing its name, so it's likely to lose.  X fonts can be
+     specified (by the user) in either pixels or 10ths of points, and
+     this returns the first one it finds, so you have to decide which
+     units the returned value is measured in yourself ...
+
+ - Function: x-find-larger-font font &optional device
+     This function loads a new, slightly larger version of the given
+     font (or font name).  Returns the font if it succeeds, `nil'
+     otherwise.  If scalable fonts are available, this returns a font
+     which is 1 point larger.  Otherwise, it returns the next larger
+     version of this font that is defined.
+
+ - Function: x-find-smaller-font font &optional device
+     This function loads a new, slightly smaller version of the given
+     font (or font name).  Returns the font if it succeeds, `nil'
+     otherwise.  If scalable fonts are available, this returns a font
+     which is 1 point smaller.  Otherwise, it returns the next smaller
+     version of this font that is defined.
+
+\1f
+File: lispref.info,  Node: Font Instance Characteristics,  Next: Font Convenience Functions,  Prev: Font Instance Size,  Up: Fonts
+
+Font Instance Characteristics
+-----------------------------
+
+ - Function: font-instance-properties font-instance
+     This function returns the properties (an alist or `nil') of
+     FONT-INSTANCE.
+
+ - Function: x-make-font-bold font &optional device
+     Given an X font specification, this attempts to make a "bold" font.
+     If it fails, it returns `nil'.
+
+ - Function: x-make-font-unbold font &optional device
+     Given an X font specification, this attempts to make a non-bold
+     font.  If it fails, it returns `nil'.
+
+ - Function: x-make-font-italic font &optional device
+     Given an X font specification, this attempts to make an "italic"
+     font.  If it fails, it returns `nil'.
+
+ - Function: x-make-font-unitalic font &optional device
+     Given an X font specification, this attempts to make a non-italic
+     font.  If it fails, it returns `nil'.
+
+ - Function: x-make-font-bold-italic font &optional device
+     Given an X font specification, this attempts to make a
+     "bold-italic" font.  If it fails, it returns `nil'.
+
+\1f
+File: lispref.info,  Node: Font Convenience Functions,  Prev: Font Instance Characteristics,  Up: Fonts
+
+Font Convenience Functions
+--------------------------
+
+ - Function: font-name font &optional domain
+     This function returns the name of the FONT in the specified
+     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
+     is normally a window and defaults to the selected window if
+     omitted.  This is equivalent to using `specifier-instance' and
+     applying `font-instance-name' to the result.
+
+ - Function: font-truename font &optional domain
+     This function returns the truename of the FONT in the specified
+     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
+     is normally a window and defaults to the selected window if
+     omitted.  This is equivalent to using `specifier-instance' and
+     applying `font-instance-truename' to the result.
+
+ - Function: font-properties font &optional domain
+     This function returns the properties of the FONT in the specified
+     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
+     is normally a window and defaults to the selected window if
+     omitted.  This is equivalent to using `specifier-instance' and
+     applying `font-instance-properties' to the result.
+
+\1f
+File: lispref.info,  Node: Colors,  Prev: Fonts,  Up: Faces and Window-System Objects
+
+Colors
+======
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Color Specifiers,  Next: Color Instances,  Up: Colors
+
+Color Specifiers
+----------------
+
+ - Function: color-specifier-p object
+     This function returns non-`nil' if OBJECT is a color specifier.
+
+ - Function: make-color-specifier spec-list
+     Return a new `color' 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
+     a detailed description of how specifiers work.
+
+     Valid instantiators for color specifiers are:
+
+        * A string naming a color (e.g. under X this might be
+          "lightseagreen2" or "#F534B2").
+
+        * A color instance (use that instance directly if the device
+          matches, or use the string that generated it).
+
+        * A vector of no elements (only on TTY's; this means to set no
+          color at all, thus using the "natural" color of the
+          terminal's text).
+
+        * A vector of one or two elements: a face to inherit from, and
+          optionally a symbol naming which property of that face to
+          inherit, either `foreground' or `background' (if omitted,
+          defaults to the same property that this color specifier is
+          used for; if this specifier is not part of a face, the
+          instantiator would not be valid).
+
+ - Function: make-face-boolean-specifier spec-list
+     Return a new `face-boolean' 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
+     a detailed description of how specifiers work.
+
+     Valid instantiators for face-boolean specifiers are
+
+        * t or nil.
+
+        * A vector of two or three elements: a face to inherit from,
+          optionally a symbol naming the property of that face to
+          inherit from (if omitted, defaults to the same property that
+          this face-boolean specifier is used for; if this specifier is
+          not part of a face, the instantiator would not be valid), and
+          optionally a value which, if non-`nil', means to invert the
+          sense of the inherited property.
+
+
+\1f
+File: lispref.info,  Node: Color Instances,  Next: Color Instance Properties,  Prev: Color Specifiers,  Up: Colors
+
+Color Instances
+---------------
+
+A "color-instance object" is an object describing the way a color
+specifier is instanced in a particular domain.  Functions such as
+`face-background-instance' return a color-instance object.  For example,
+
+     (face-background-instance 'default (next-window))
+         => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+
+   The color-instance object returned describes the way the background
+color of the `default' face is displayed in the next window after the
+selected one.
+
+ - Function: color-instance-p object
+     This function returns non-`nil' if OBJECT is a color-instance.
+
+\1f
+File: lispref.info,  Node: Color Instance Properties,  Next: Color Convenience Functions,  Prev: Color Instances,  Up: Colors
+
+Color Instance Properties
+-------------------------
+
+ - Function: color-instance-name color-instance
+     This function returns the name used to allocate COLOR-INSTANCE.
+
+ - Function: color-instance-rgb-components color-instance
+     This function returns a three element list containing the red,
+     green, and blue color components of COLOR-INSTANCE.
+
+          (color-instance-rgb-components
+            (face-background-instance 'default (next-window)))
+              => (65535 58596 46517)
+
+\1f
+File: lispref.info,  Node: Color Convenience Functions,  Prev: Color Instance Properties,  Up: Colors
+
+Color Convenience Functions
+---------------------------
+
+ - Function: color-name color &optional domain
+     This function returns the name of the COLOR in the specified
+     DOMAIN, if any.  COLOR should be a color specifier object and
+     DOMAIN is normally a window and defaults to the selected window if
+     omitted.  This is equivalent to using `specifier-instance' and
+     applying `color-instance-name' to the result.
+
+ - Function: color-rgb-components color &optional domain
+     This function returns the RGB components of the COLOR in the
+     specified DOMAIN, if any.  COLOR should be a color specifier
+     object and DOMAIN is normally a window and defaults to the
+     selected window if omitted.  This is equivalent to using
+     `specifier-instance' and applying `color-instance-rgb-components'
+     to the result.
+
+          (color-rgb-components (face-background 'default (next-window)))
+              => (65535 58596 46517)
+
+\1f
+File: lispref.info,  Node: Glyphs,  Next: Annotations,  Prev: Faces and Window-System Objects,  Up: Top
+
+Glyphs
+******
+
+A "glyph" is an object that is used for pixmaps, widgets and images of
+all sorts, as well as for things that "act" like pixmaps, such as
+non-textual strings ("annotations") displayed in a buffer or in the
+margins.  It is used in begin-glyphs and end-glyphs attached to
+extents, marginal and textual annotations, overlay arrows
+(`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
+icons, truncation and continuation markers, and the like. (Basically,
+any place there is an image or something that acts like an image, there
+will be a glyph object representing it.)
+
+   The actual image that is displayed (as opposed to its position or
+clipping) is defined by an "image specifier" object contained within
+the glyph.  The separation between an image specifier object and a
+glyph object is made because the glyph includes other properties than
+just the actual image: e.g. the face it is displayed in (for text
+images), the alignment of the image (when it is in a buffer), etc.
+
+ - Function: glyphp object
+     This function returns `t' if OBJECT is a glyph.
+
+* Menu:
+
+* 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 Examples::      Examples of how to work with glyphs.
+
+\1f
+File: lispref.info,  Node: Glyph Functions,  Next: Images,  Up: Glyphs
+
+Glyph Functions
+===============
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Creating Glyphs,  Next: Glyph Properties,  Up: Glyph Functions
+
+Creating Glyphs
+---------------
+
+ - Function: make-glyph &optional spec-list type
+     This function creates a new glyph object of type TYPE.
+
+     SPEC-LIST is used to initialize the glyph's image.  It is
+     typically an image instantiator (a string or a vector; *Note Image
+     Specifiers::), but can also be a list of such instantiators (each
+     one in turn is tried until an image is successfully produced), a
+     cons of a locale (frame, buffer, etc.) and an instantiator, a list
+     of such conses, or any other form accepted by
+     `canonicalize-spec-list'.  *Note Specifiers::, for more
+     information about specifiers.
+
+     TYPE specifies the type of the glyph, which specifies in which
+     contexts the glyph can be used, and controls the allowable image
+     types into which the glyph's image can be instantiated.  TYPE
+     should be one of `buffer' (used for glyphs in an extent, the
+     modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
+     for the mouse-pointer), or `icon' (used for a frame's icon), and
+     defaults to `buffer'.  *Note Glyph Types::.
+
+     A glyph in XEmacs does *NOT* refer to a single unit of textual
+     display (the XEmacs term for this is "rune"), but rather is an
+     object encapsulating a graphical element, such as an image or
+     widget (an element such as a button or text field; "widget" is the
+     term for this under X Windows, and it's called a "control" under
+     MS Windows).  This graphical element could appear in a buffer, a
+     margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
+     for example.
+
+     Creating a glyph using `make-glyph' does not specify _where_ the
+     glyph will be used, but it does specify _what_ the glyph will look
+     like.  In particular, SPEC-LIST is used to specify this, and it's
+     used to initialize the glyph's `image' property, which is an image
+     specifier. (Note that "image" as used in the context of a glyph's
+     `image' property or in the terms "image specifier", "image
+     instantiator", or "image instance" does not refer to what people
+     normally think of as an image (which in XEmacs is called a
+     "pixmap"), but to any graphical element--a pixmap, a widget, or
+     even a block of text, when used in the places that call for a
+     glyph.)  The format of the SPEC-LIST is typically an image
+     instantiator (a string or a vector; *Note Image Specifiers::), but
+     can also be a list of such instantiators (each one in turn is
+     tried until an image is successfully produced), a cons of a locale
+     (frame, buffer, etc.)  and an instantiator, a list of such conses,
+     or any other form accepted by `canonicalize-spec-list'. *Note
+     Specifiers::, for more information about specifiers.
+
+     If you're not familiar with specifiers, you should be in order to
+     understand how glyphs work.  The clearest introduction to
+     specifiers is in the Lispref manual, available under Info. (Choose
+     Help->Info->Info Contents on the menubar or type C-h i.) You can
+     also see `make-specifier' for a capsule summary.  What's important
+     to keep in mind is that a specifier lets you set a different value
+     for any particular buffer, window, frame, device, or console.
+     This allows for a great deal of flexibility; in particular, only
+     one global glyph needs to exist for a particular purpose (e.g. the
+     icon used to represent an iconified frame, the mouse pointer used
+     over particular areas of a frame, etc.), and in these cases you do
+     not create your own glyph, but rather modify the existing one.
+
+     As well as using SPEC-LIST to initialize the glyph, you can set
+     specifications using `set-glyph-image'.  Note that, due to a
+     possibly questionable historical design decision, a glyph itself
+     is not actually a specifier, but rather is an object containing an
+     image specifier (as well as other, seldom-used properties).
+     Therefore, you cannot set or access specifications for the glyph's
+     image by directly using `set-specifier', `specifier-instance' or
+     the like on the glyph; instead use them on `(glyph-image GLYPH)'
+     or use the convenience functions `set-glyph-image',
+     `glyph-image-instance', and `glyph-image'.
+
+     Once you have created a glyph, you specify where it will be used as
+     follows:
+
+        * To insert a glyph into a buffer, create an extent in the
+          buffer and then use `set-extent-begin-glyph' or
+          `set-extent-end-glyph' to set a glyph to be displayed at the
+          corresponding edge of the extent. (It is common to create
+          zero-width extents for this purpose.)
+
+        * To insert a glyph into the left or right margin of a buffer,
+          first make sure the margin is visible by setting a value for
+          the specifiers `left-margin-width' or `right-margin-width'.
+          (Not strictly necessary when using margin glyphs with layout
+          policy `whitespace'.) Then follow the same procedure above
+          for inserting a glyph in a buffer, and then set a non-default
+          layout policy for the glyph using
+          `set-extent-begin-glyph-layout' or
+          `set-extent-end-glyph-layout'.  Alternatively, use the
+          high-level annotations API (see `make-annotation'). (In point
+          of fact, you can also use the annotations API for glyphs in a
+          buffer, by setting a layout policy of `text'.)
+
+        * To insert a glyph into the modeline, just put the glyph
+          directly as one of the modeline elements. (Unfortunately you
+          can't currently put a begin glyph or end glyph on one of the
+          modeline extents--they're ignored.)
+
+        * To insert a glyph into a toolbar, specify it as part of a
+          toolbar instantiator (typically set on the specifier
+          `default-toolbar').  See `default-toolbar' for more
+          information. (Note that it is standard practice to use a
+          symbol in place of the glyph list in the toolbar
+          instantiator; the symbol is evalled to get the glyph list.
+          This facilitates both creating the toolbar instantiator and
+          modifying individual glyphs in a toolbar later on.  For
+          example, you can change the way that the Mail toolbar button
+          looks by modifying the value of the variable
+          `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
+          calling `(set-specifier-dirty-flag default-toolbar)'.  (####
+          Unfortunately this doesn't quite work the way it should; the
+          change will appear in new frames, but not existing ones.
+
+        * To insert a glyph into a gutter, create or modify a gutter
+          instantiator (typically set on the specifier
+          `default-gutter').  Gutter instantiators consist of strings
+          or lists of strings, so to insert a glyph, create an extent
+          over the string, and use `set-extent-begin-glyph' or
+          `set-extent-end-glyph' to set a glyph to be displayed at the
+          corresponding edge of the extent, just like for glyphs in a
+          buffer.
+
+        * To use a glyph as the icon for a frame, you do not actually
+          create a new glyph; rather, you change the specifications for
+          the existing glyph `frame-icon-glyph'. (Remember that,
+          because of the specifier nature of glyphs, you can set
+          different values for any particular buffer or frame.)
+
+        * To use a glyph as the mouse pointer, in general you do not
+          create a new glyph, but rather you change the specifications
+          of various existing glyphs, such as `text-pointer-glyph' for
+          the pointer used over text, `modeline-pointer-glyph' for the
+          pointer used over the modeline, etc.  Do an apropos over
+          `*-pointer-glyph' to find all of them. (Note also that you
+          can temporarily set the mouse pointer to some specific shape
+          by using `set-frame-pointer', which takes an image instance,
+          as obtained from calling `glyph-image-instance' on a glyph of
+          type `pointer' - either one of the above-mentioned variables
+          or one you created yourself.  (See below for what it means to
+          create a glyph of type `pointer'.)  This pointer will last
+          only until the next mouse motion event is processed or
+          certain other things happen, such as creating or deleting a
+          window. (In fact, the above-mentioned pointer glyph variables
+          are implemented as part of the default handler for mouse
+          motion events.  If you want to customize this behavior, take a
+          look at `mode-motion-hook', or `mouse-motion-handler' if you
+          really want to get low-level.)
+
+        * To use a glyph to control the shape of miscellaneous
+          redisplay effects such as the truncation and continuation
+          markers, set the appropriate existing glyph variables, as for
+          icons and pointers above.  See `continuation-glyph',
+          `control-arrow-glyph', `hscroll-glyph',
+          `invisible-text-glyph', `octal-escape-glyph', and
+          `truncation-glyph'.  See also `overlay-arrow-string', an odd
+          redisplay leftover which can be set to a glyph you created,
+          and will cause the glyph to be displayed on top of the text
+          position specified in the marker stored in
+          `overlay-arrow-position'.
+
+        * To use a glyph in a display table (i.e. to control the
+          appearance of any individual character), create the
+          appropriate character glyphs and then set a specification for
+          the specifier `current-display-table', which controls the
+          appearance of characters.  You can also set an overriding
+          display table for use with text displayed in a particular
+          face; see `set-face-display-table' and `make-display-table'.
+          #### Note: Display tables do not currently support general
+          Mule characters.  They will be overhauled at some point to
+          support this and to provide other features required under
+          Mule.
+
+        * To use a glyph as the background pixmap of a face: Note that
+          the background pixmap of a face is actually an image
+          specifier - probably the only place in XEmacs where an image
+          specifier occurs outside of a glyph.  Similarly to how the
+          glyph's image specifier works, you don't create your own
+          image specifier, but rather add specifications to the
+          existing one (using `set-face-background-pixmap').  Note that
+          the image instance that is generated in order to actually
+          display the background pixmap is of type `mono-pixmap',
+          meaning that it's a two-color image and the foreground and
+          background of the image get filled in with the corresponding
+          colors from the face.
+
+     It is extremely rare that you will ever have to specify a value for
+     TYPE, which should be one of `buffer' (used for glyphs in an
+     extent, the modeline, the toolbar, or elsewhere in a buffer),
+     `pointer' (used for the mouse-pointer), or `icon' (used for a
+     frame's icon), and defaults to `buffer'.  The only cases where it
+     needs to be specified is when creating icon or pointer glyphs, and
+     in both cases the necessary glyphs have already been created at
+     startup and are accessed through the appropriate variables, e.g.
+     `text-pointer-glyph' (or in general, `*-pointer-glyph') and
+     `frame-icon-glyph'.  *Note Glyph Types::.
+
+ - Function: make-glyph-internal &optional type
+     This function creates a new, uninitialized glyph of type TYPE.
+
+ - Function: make-pointer-glyph &optional spec-list
+     Return a new `pointer-glyph' object with the specification list
+     SPEC-LIST.  This function is equivalent to calling `make-glyph'
+     with a TYPE of `pointer'.
+
+     It is extremely unlikely that you will ever need to create a
+     pointer glyph.  Instead, you probably want to be calling
+     `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+
+ - Function: make-icon-glyph &optional spec-list
+     Return a new `pointer-glyph' object with the specification list
+     SPEC-LIST.  This function is equivalent to calling `make-glyph'
+     with a TYPE of `icon'.
+
+     It is extremely unlikely that you will ever need to create a
+     pointer glyph.  Instead, you probably want to be calling
+     `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+
+\1f
+File: lispref.info,  Node: Glyph Properties,  Next: Glyph Convenience Functions,  Prev: Creating Glyphs,  Up: Glyph Functions
+
+Glyph Properties
+----------------
+
+Each glyph has a list of properties, which control all of the aspects of
+the glyph's appearance.  The following symbols have predefined meanings:
+
+`image'
+     The image used to display the glyph.
+
+`baseline'
+     Percent above baseline that glyph is to be displayed.  Only for
+     glyphs displayed inside of a buffer.
+
+`contrib-p'
+     Whether the glyph contributes to the height of the line it's on.
+     Only for glyphs displayed inside of a buffer.
+
+`face'
+     Face of this glyph (_not_ a specifier).
+
+ - Function: set-glyph-property glyph property value &optional locale
+          tag-set how-to-add
+     This function changes a property of a GLYPH.
+
+     For built-in properties, the actual value of the property is a
+     specifier and you cannot change this; but you can change the
+     specifications within the specifier, and that is what this
+     function will do.  For user-defined properties, you can use this
+     function to either change the actual value of the property or, if
+     this value is a specifier, change the specifications within it.
+
+     If PROPERTY is a built-in property, the specifications to be added
+     to this property can be supplied in many different ways:
+
+        * If VALUE is a simple instantiator (e.g. a string naming a
+          pixmap filename) or a list of instantiators, then the
+          instantiator(s) will be added as a specification of the
+          property for the given LOCALE (which defaults to `global' if
+          omitted).
+
+        * If VALUE is a list of specifications (each of which is a cons
+          of a locale and a list of instantiators), then LOCALE must be
+          `nil' (it does not make sense to explicitly specify a locale
+          in this case), and specifications will be added as given.
+
+        * If VALUE is a specifier (as would be returned by
+          `glyph-property' if no LOCALE argument is given), then some
+          or all of the specifications in the specifier will be added
+          to the property.  In this case, the function is really
+          equivalent to `copy-specifier' and LOCALE has the same
+          semantics (if it is a particular locale, the specification
+          for the locale will be copied; if a locale type,
+          specifications for all locales of that type will be copied;
+          if `nil' or `all', then all specifications will be copied).
+
+     HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+     `append', `remove-tag-set-prepend', `remove-tag-set-append',
+     `remove-locale', `remove-locale-type', or `remove-all'.  See
+     `copy-specifier' and `add-spec-to-specifier' for a description of
+     what each of these means.  Most of the time, you do not need to
+     worry about this argument; the default behavior usually is fine.
+
+     In general, it is OK to pass an instance object (e.g. as returned
+     by `glyph-property-instance') as an instantiator in place of an
+     actual instantiator.  In such a case, the instantiator used to
+     create that instance object will be used (for example, if you set
+     a font-instance object as the value of the `font' property, then
+     the font name used to create that object will be used instead).
+     If some cases, however, doing this conversion does not make sense,
+     and this will be noted in the documentation for particular types
+     of instance objects.
+
+     If PROPERTY is not a built-in property, then this function will
+     simply set its value if LOCALE is `nil'.  However, if LOCALE is
+     given, then this function will attempt to add VALUE as the
+     instantiator for the given LOCALE, using `add-spec-to-specifier'.
+     If the value of the property is not a specifier, it will
+     automatically be converted into a `generic' specifier.
+
+ - Function: glyph-property glyph property &optional locale
+     This function returns GLYPH's value of the given PROPERTY.
+
+     If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
+     be returned.  For built-in properties, this will be a specifier
+     object of a type appropriate to the property (e.g. a font or color
+     specifier).  For other properties, this could be anything.
+
+     If LOCALE is supplied, then instead of returning the actual value,
+     the specification(s) for the given locale or locale type will be
+     returned.  This will only work if the actual value of PROPERTY is
+     a specifier (this will always be the case for built-in properties,
+     but may or may not apply to user-defined properties).  If the
+     actual value of PROPERTY is not a specifier, this value will
+     simply be returned regardless of LOCALE.
+
+     The return value will be a list of instantiators (e.g. vectors
+     specifying pixmap data), or a list of specifications, each of
+     which is a cons of a locale and a list of instantiators.
+     Specifically, if LOCALE is a particular locale (a buffer, window,
+     frame, device, or `global'), a list of instantiators for that
+     locale will be returned.  Otherwise, if LOCALE is a locale type
+     (one of the symbols `buffer', `window', `frame', or `device'), the
+     specifications for all locales of that type will be returned.
+     Finally, if LOCALE is `all', the specifications for all locales of
+     all types will be returned.
+
+     The specifications in a specifier determine what the value of
+     PROPERTY will be in a particular "domain" or set of circumstances,
+     which is typically a particular Emacs window along with the buffer
+     it contains and the frame and device it lies within.  The value is
+     derived from the instantiator associated with the most specific
+     locale (in the order buffer, window, frame, device, and `global')
+     that matches the domain in question.  In other words, given a
+     domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+     will first be searched for a specification whose locale is the
+     buffer contained within that window; then for a specification
+     whose locale is the window itself; then for a specification whose
+     locale is the frame that the window is contained within; etc.  The
+     first instantiator that is valid for the domain (usually this
+     means that the instantiator is recognized by the device [i.e. the
+     X server or TTY device] that the domain is on).  The function
+     `glyph-property-instance' actually does all this, and is used to
+     determine how to display the glyph.
+
+ - Function: glyph-property-instance glyph property &optional domain
+          default no-fallback
+     This function returns the instance of GLYPH's PROPERTY in the
+     specified DOMAIN.
+
+     Under most circumstances, DOMAIN will be a particular window, and
+     the returned instance describes how the specified property
+     actually is displayed for that window and the particular buffer in
+     it.  Note that this may not be the same as how the property
+     appears when the buffer is displayed in a different window or
+     frame, or how the property appears in the same window if you
+     switch to another buffer in that window; and in those cases, the
+     returned instance would be different.
+
+     The returned instance is an image-instance object, and you can
+     query it using the appropriate image instance functions.  For
+     example, you could use `image-instance-depth' to find out the
+     depth (number of color planes) of a pixmap displayed in a
+     particular window.  The results might be different from the
+     results you would get for another window (perhaps the user
+     specified a different image for the frame that window is on; or
+     perhaps the same image was specified but the window is on a
+     different X server, and that X server has different color
+     capabilities from this one).
+
+     DOMAIN defaults to the selected window if omitted.
+
+     DOMAIN can be a frame or device, instead of a window.  The value
+     returned for such a domain is used in special circumstances when a
+     more specific domain does not apply; for example, a frame value
+     might be used for coloring a toolbar, which is conceptually
+     attached to a frame rather than a particular window.  The value is
+     also useful in determining what the value would be for a
+     particular window within the frame or device, if it is not
+     overridden by a more specific specification.
+
+     If PROPERTY does not name a built-in property, its value will
+     simply be returned unless it is a specifier object, in which case
+     it will be instanced using `specifier-instance'.
+
+     Optional arguments DEFAULT and NO-FALLBACK are the same as in
+     `specifier-instance'.  *Note Specifiers::.
+
+ - Function: remove-glyph-property glyph property &optional locale
+          tag-set exact-p
+     This function removes a property from a glyph.  For built-in
+     properties, this is analogous to `remove-specifier'.  *Note
+     remove-specifier-p: Specifiers, for the meaning of the LOCALE,
+     TAG-SET, and EXACT-P arguments.
+
+\1f
+File: lispref.info,  Node: Glyph Convenience Functions,  Next: Glyph Dimensions,  Prev: Glyph Properties,  Up: Glyph Functions
+
+Glyph Convenience Functions
+---------------------------
+
+The following functions are provided for working with specific
+properties of a glyph.  Note that these are exactly like calling the
+general functions described above and passing in the appropriate value
+for PROPERTY.
+
+   Remember that if you want to determine the "value" of a specific
+glyph property, you probably want to use the `*-instance' functions.
+For example, to determine whether a glyph contributes to its line
+height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
+latter will return a boolean specifier or a list of specifications, and
+you probably aren't concerned with these.)
+
+ - Function: glyph-image glyph &optional locale
+     This function is equivalent to calling `glyph-property' with a
+     property of `image'.  The return value will be an image specifier
+     if LOCALE is `nil' or omitted; otherwise, it will be a
+     specification or list of specifications.
+
+ - Function: set-glyph-image glyph spec &optional locale tag-set
+          how-to-add
+     This function is equivalent to calling `set-glyph-property' with a
+     property of `image'.
+
+ - Function: glyph-image-instance glyph &optional domain default
+          no-fallback
+     This function returns the instance of GLYPH's image in the given
+     DOMAIN, and is equivalent to calling `glyph-property-instance'
+     with a property of `image'.  The return value will be an image
+     instance.
+
+     Normally DOMAIN will be a window or `nil' (meaning the selected
+     window), and an instance object describing how the image appears
+     in that particular window and buffer will be returned.
+
+ - Function: glyph-contrib-p glyph &optional locale
+     This function is equivalent to calling `glyph-property' with a
+     property of `contrib-p'.  The return value will be a boolean
+     specifier if LOCALE is `nil' or omitted; otherwise, it will be a
+     specification or list of specifications.
+
+ - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
+          how-to-add
+     This function is equivalent to calling `set-glyph-property' with a
+     property of `contrib-p'.
+
+ - Function: glyph-contrib-p-instance glyph &optional domain default
+          no-fallback
+     This function returns whether the glyph contributes to its line
+     height in the given DOMAIN, and is equivalent to calling
+     `glyph-property-instance' with a property of `contrib-p'.  The
+     return value will be either `nil' or `t'. (Normally DOMAIN will be
+     a window or `nil', meaning the selected window.)
+
+ - Function: glyph-baseline glyph &optional locale
+     This function is equivalent to calling `glyph-property' with a
+     property of `baseline'.  The return value will be a specifier if
+     LOCALE is `nil' or omitted; otherwise, it will be a specification
+     or list of specifications.
+
+ - Function: set-glyph-baseline glyph spec &optional locale tag-set
+          how-to-add
+     This function is equivalent to calling `set-glyph-property' with a
+     property of `baseline'.
+
+ - Function: glyph-baseline-instance glyph &optional domain default
+          no-fallback
+     This function returns the instance of GLYPH's baseline value in
+     the given DOMAIN, and is equivalent to calling
+     `glyph-property-instance' with a property of `baseline'.  The
+     return value will be an integer or `nil'.
+
+     Normally DOMAIN will be a window or `nil' (meaning the selected
+     window), and an instance object describing the baseline value
+     appears in that particular window and buffer will be returned.
+
+ - Function: glyph-face glyph
+     This function returns the face of GLYPH. (Remember, this is not a
+     specifier, but a simple property.)
+
+ - Function: set-glyph-face glyph face
+     This function changes the face of GLYPH to FACE.
+
+\1f
+File: lispref.info,  Node: Glyph Dimensions,  Prev: Glyph Convenience Functions,  Up: Glyph Functions
+
+Glyph Dimensions
+----------------
+
+ - Function: glyph-width glyph &optional window
+     This function returns the width of GLYPH on WINDOW.  This may not
+     be exact as it does not take into account all of the context that
+     redisplay will.
+
+ - Function: glyph-ascent glyph &optional window
+     This function returns the ascent value of GLYPH on WINDOW.  This
+     may not be exact as it does not take into account all of the
+     context that redisplay will.
+
+ - Function: glyph-descent glyph &optional window
+     This function returns the descent value of GLYPH on WINDOW.  This
+     may not be exact as it does not take into account all of the
+     context that redisplay will.
+
+ - Function: glyph-height glyph &optional window
+     This function returns the height of GLYPH on WINDOW.  (This is
+     equivalent to the sum of the ascent and descent values.)  This may
+     not be exact as it does not take into account all of the context
+     that redisplay will.
+
+\1f
+File: lispref.info,  Node: Images,  Next: Glyph Types,  Prev: Glyph Functions,  Up: Glyphs
+
+Images
+======
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Image Specifiers,  Next: Image Instantiator Conversion,  Up: Images
+
+Image Specifiers
+----------------
+
+An image specifier is used to describe the actual image of a glyph.  It
+works like other specifiers (*note Specifiers::), in that it contains a
+number of specifications describing how the image should appear in a
+variety of circumstances.  These specifications are called "image
+instantiators".  When XEmacs wants to display the image, it instantiates
+the image into an "image instance".  Image instances are their own
+primitive object type (similar to font instances and color instances),
+describing how the image appears in a particular domain. (On the other
+hand, image instantiators, which are just descriptions of how the image
+should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p object
+     This function returns non-`nil' if OBJECT is an image specifier.
+     Usually, an image specifier results from calling `glyph-image' on
+     a glyph.
+
+ - Function: make-image-specifier spec-list
+     This function creates a new image specifier object and initializes
+     it according to SPEC-LIST. *Note Specifiers::.
+
+     Note that, in practice, you rarely, if ever, need to actually
+     create an image specifier! (This function exists mainly for
+     completeness.) Pretty much the only use for image specifiers is to
+     control how glyphs are displayed, and the image specifier
+     associated with a glyph (the `image' property of a glyph) is
+     created automatically when a glyph is created and need not (and
+     cannot, for that matter) ever be changed (*note Glyphs::).  In
+     fact, the design decision to create a separate image specifier
+     type, rather than make glyphs themselves be specifiers, is
+     debatable--the other properties of glyphs are rarely used and could
+     conceivably have been incorporated into the glyph's instantiator.
+     The rarely used glyph types (buffer, pointer, icon) could also
+     have been incorporated into the instantiator.
+
+   Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc.  This describes the format of the data describing the
+image.  The resulting image instances also come in many
+types--`mono-pixmap', `color-pixmap', `text', `pointer', etc.  This
+refers to the behavior of the image and the sorts of places it can
+appear. (For example, a color-pixmap image has fixed colors specified
+for it, while a mono-pixmap image comes in two unspecified shades
+"foreground" and "background" that are determined from the face of the
+glyph or surrounding text; a text image appears as a string of text and
+has an unspecified foreground, background, and font; a pointer image
+behaves like a mono-pixmap image but can only be used as a mouse
+pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
+is important to keep the distinction between image instantiator format
+and image instance type in mind.  Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different image
+instantiator formats (e.g.  `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+   *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+   An image instantiator should be a string or a vector of the form
+
+      `[FORMAT :KEYWORD VALUE ...]'
+
+   i.e. a format symbol followed by zero or more alternating
+keyword-value pairs.  The "format" field should be a symbol, one of
+
+`nothing'
+     Don't display anything; no keywords are valid for this.  Can only
+     be instanced as `nothing'.
+
+`string'
+     Display this image as a text string.  Can only be instanced as
+     `text', although support for instancing as `mono-pixmap' should be
+     added.
+
+`formatted-string'
+     Display this image as a text string with replaceable fields,
+     similar to a modeline format string; not currently implemented.
+
+`xbm'
+     An X bitmap; only if X support was compiled into this XEmacs.  Can
+     be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`xpm'
+     An XPM pixmap; only if XPM support was compiled into this XEmacs.
+     Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+     XPM is an add-on library for X that was designed to rectify the
+     shortcomings of the XBM format.  Most implementations of X include
+     the XPM library as a standard part.  If your vendor does not, it
+     is highly recommended that you download it and install it.  You
+     can get it from the standard XEmacs FTP site, among other places.
+
+`xface'
+     An X-Face bitmap, used to encode people's faces in e-mail messages;
+     only if X-Face support was compiled into this XEmacs.  Can be
+     instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`gif'
+     A GIF87 or GIF89 image; only if GIF support was compiled into this
+     XEmacs.  Can be instanced as `color-pixmap'.  Note that XEmacs
+     includes GIF decoding functions as a standard part of it, so if
+     you have X support, you will normally have GIF support, unless you
+     explicitly disable it at configure time.
+
+`jpeg'
+     A JPEG-format image; only if JPEG support was compiled into this
+     XEmacs.  Can be instanced as `color-pixmap'.  If you have the JPEG
+     libraries present on your system when XEmacs is built, XEmacs will
+     automatically detect this and use them, unless you explicitly
+     disable it at configure time.
+
+`png'
+     A PNG/GIF24 image; only if PNG support was compiled into this
+     XEmacs.  Can be instanced as `color-pixmap'.
+
+`tiff'
+     A TIFF-format image; only if TIFF support was compiled into this
+     XEmacs.
+
+`cursor-font'
+     One of the standard cursor-font names, such as `watch' or
+     `right_ptr' under X.  Under X, this is, more specifically, any of
+     the standard cursor names from appendix B of the Xlib manual [also
+     known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix.  On
+     other window systems, the valid names will be specific to the type
+     of window system.  Can only be instanced as `pointer'.
+
+`font'
+     A glyph from a font; i.e. the name of a font, and glyph index into
+     it of the form `FONT fontname index [[mask-font] mask-index]'.
+     Only if X support was compiled into this XEmacs.  Currently can
+     only be instanced as `pointer', although this should probably be
+     fixed.
+
+`mswindows-resource'
+     An MS Windows pointer resource.  Specifies a resource to retrieve
+     directly from the system (an OEM resource) or from a file,
+     particularly an executable file.  If the resource is to be
+     retrieved from a file, use :file and optionally :resource-id.
+     Otherwise use :resource-id.  Always specify :resource-type to
+     specify the type (cursor, bitmap or icon) of the resource.
+     Possible values for :resource-id are listed below.  Can be
+     instanced as `pointer' or `color-pixmap'.
+
+`subwindow'
+     An embedded windowing system window.  Can only be instanced as
+     `subwindow'.
+
+`button'
+     A button widget; either a push button, radio button or toggle
+     button.  Can only be instanced as `widget'.
+
+`combo-box'
+     A drop list of selectable items in a widget, for editing text.
+     Can only be instanced as `widget'.
+
+`edit-field'
+     A text editing widget.  Can only be instanced as `widget'.
+
+`label'
+     A static, text-only, widget; for displaying text.  Can only be
+     instanced as `widget'.
+
+`layout'
+     A widget for controlling the positioning of children underneath it.
+     Through the use of nested layouts, a widget hierarchy can be
+     created which can have the appearance of any standard dialog box
+     or similar arrangement; all of this is counted as one "glyph" and
+     could appear in many of the places that expect a single glyph.
+     Can only be instanced as `widget'.
+
+`native-layout'
+     The native version of a layout widget.  Can only be instanced as
+     `widget'.
+
+`progress-gauge'
+     A sliding widget, for showing progress.  Can only be instanced as
+     `widget'.
+
+`tab-control'
+     A tab widget; a series of user selectable tabs.  Can only be
+     instanced as `widget'.
+
+`tree-view'
+     A folding widget.  Can only be instanced as `widget'.
+
+`scrollbar'
+     A scrollbar widget.  Can only be instanced as `widget'.
+
+`autodetect'
+     XEmacs tries to guess what format the data is in.  If X support
+     exists, the data string will be checked to see if it names a
+     filename.  If so, and this filename contains XBM or XPM data, the
+     appropriate sort of pixmap or pointer will be created. [This
+     includes picking up any specified hotspot or associated mask
+     file.] Otherwise, if `pointer' is one of the allowable
+     image-instance types and the string names a valid cursor-font
+     name, the image will be created as a pointer.  Otherwise, the
+     image will be displayed as text.  If no X support exists, the
+     image will always be displayed as text.
+
+`inherit'
+     Inherit from the background-pixmap property of a face.  Can only be
+     instanced as `mono-pixmap'.
+
+   The valid keywords are:
+
+`:data'
+     Inline data.  For most formats above, this should be a string.  For
+     XBM images, this should be a list of three elements: width,
+     height, and a string of bit data.  This keyword is not valid for
+     instantiator format `nothing'.
+
+`:file'
+     Data is contained in a file.  The value is the name of this file.
+     If both `:data' and `:file' are specified, the image is created
+     from what is specified in `:data' and the string in `:file'
+     becomes the value of the `image-instance-file-name' function when
+     applied to the resulting image-instance.  This keyword is not
+     valid for instantiator formats `nothing', `string',
+     `formatted-string', `cursor-font', `font', and `autodetect'.
+
+`:foreground'
+`:background'
+     For `xbm', `xface', `cursor-font', and `font'.  These keywords
+     allow you to explicitly specify foreground and background colors.
+     The argument should be anything acceptable to
+     `make-color-instance'.  This will cause what would be a
+     `mono-pixmap' to instead be colorized as a two-color color-pixmap,
+     and specifies the foreground and/or background colors for a pointer
+     instead of black and white.
+
+`:mask-data'
+     For `xbm' and `xface'.  This specifies a mask to be used with the
+     bitmap.  The format is a list of width, height, and bits, like for
+     `:data'.
+
+`:mask-file'
+     For `xbm' and `xface'.  This specifies a file containing the mask
+     data.  If neither a mask file nor inline mask data is given for an
+     XBM image, and the XBM image comes from a file, XEmacs will look
+     for a mask file with the same name as the image file but with
+     `Mask' or `msk' appended.  For example, if you specify the XBM file
+     `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
+     associated mask file `left_ptrmsk' will automatically be picked up.
+
+`:hotspot-x'
+`:hotspot-y'
+     For `xbm' and `xface'.  These keywords specify a hotspot if the
+     image is instantiated as a `pointer'.  Note that if the XBM image
+     file specifies a hotspot, it will automatically be picked up if no
+     explicit hotspot is given.
+
+`:color-symbols'
+     Only for `xpm'.  This specifies an alist that maps strings that
+     specify symbolic color names to the actual color to be used for
+     that symbolic color (in the form of a string or a color-specifier
+     object).  If this is not specified, the contents of
+     `xpm-color-symbols' are used to generate the alist.
+
+`:resource-id'
+     Only for `mswindows-resource'.  This must be either an integer
+     (which directly specifies a resource number) or a string.  Valid
+     strings are
+
+     For bitmaps:
+
+     "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
+     "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
+     "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
+     "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
+     "check", "checkboxes", and "btncorners".
+
+     For cursors:
+
+     "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
+     "sizewe", "sizens", "sizeall", and "no".
+
+     For icons:
+
+     "sample", "hand", "ques", "bang", "note", and "winlogo".
+
+`:resource-type'
+     Only for `mswindows-resource'.  This must be a symbol, either
+     `cursor', `icon', or `bitmap', specifying the type of resource to
+     be retrieved.
+
+`:face'
+     Only for `inherit'.  This specifies the face to inherit from.  For
+     widgets this also specifies the face to use for display. It
+     defaults to gui-element-face.
+
+   Keywords accepted as menu item specs are also accepted by widgets.
+These are `:selected', `:active', `:suffix', `:keys', `:style',
+`:filter', `:config', `:included', `:key-sequence', `:accelerator',
+`:label' and `:callback'.
+
+   If instead of a vector, the instantiator is a string, it will be
+converted into a vector by looking it up according to the specs in the
+`console-type-image-conversion-list' for the console type of the domain
+(usually a window; sometimes a frame or device) over which the image is
+being instantiated.
+
+   If the instantiator specifies data from a file, the data will be
+read in at the time that the instantiator is added to the image
+specifier (which may be well before the image is actually displayed),
+and the instantiator will be converted into one of the inline-data
+forms, with the filename retained using a `:file' keyword.  This
+implies that the file must exist when the instantiator is added to the
+image, but does not need to exist at any other time (e.g. it may safely
+be a temporary file).
+
+ - Function: valid-image-instantiator-format-p format &optional locale
+     This function returns non-`nil' if FORMAT is a valid image
+     instantiator format.
+
+     If LOCALE is non-`nil' then the format is checked in that locale.
+     If LOCALE is `nil' the current console is used.
+
+     Note that the return value for many formats listed above depends on
+     whether XEmacs was compiled with support for that format.
+
+ - Function: image-instantiator-format-list
+     This function return a list of valid image-instantiator formats.
+
+ - Variable: xpm-color-symbols
+     This variable holds definitions of logical color-names used when
+     reading XPM files.  Elements of this list should be of the form
+     `(COLOR-NAME FORM-TO-EVALUATE)'.  The COLOR-NAME should be a
+     string, which is the name of the color to define; the
+     FORM-TO-EVALUATE should evaluate to a color specifier object, or a
+     string to be passed to `make-color-instance' (*note Colors::).  If
+     a loaded XPM file references a symbolic color called COLOR-NAME,
+     it will display as the computed color instead.
+
+     The default value of this variable defines the logical color names
+     `"foreground"' and `"background"' to be the colors of the
+     `default' face.
+
+ - Variable: x-bitmap-file-path
+     A list of the directories in which X bitmap files may be found.
+     If `nil', this is initialized from the `"*bitmapFilePath"'
+     resource.  This is used by the `make-image-instance' function
+     (however, note that if the environment variable `XBMLANGPATH' is
+     set, it is consulted first).
+
+\1f
+File: lispref.info,  Node: Image Instantiator Conversion,  Next: Image Instances,  Prev: Image Specifiers,  Up: Images
+
+Image Instantiator Conversion
+-----------------------------
+
+ - Function: set-console-type-image-conversion-list console-type list
+     This function sets the image-conversion-list for consoles of the
+     given CONSOLE-TYPE.  The image-conversion-list specifies how image
+     instantiators that are strings should be interpreted.  Each
+     element of the list should be a list of two elements (a regular
+     expression string and a vector) or a list of three elements (the
+     preceding two plus an integer index into the vector).  The string
+     is converted to the vector associated with the first matching
+     regular expression.  If a vector index is specified, the string
+     itself is substituted into that position in the vector.
+
+     Note: The conversion above is applied when the image instantiator
+     is added to an image specifier, not when the specifier is actually
+     instantiated.  Therefore, changing the image-conversion-list only
+     affects newly-added instantiators.  Existing instantiators in
+     glyphs and image specifiers will not be affected.
+
+ - Function: console-type-image-conversion-list console-type
+     This function returns the image-conversion-list for consoles of
+     the given CONSOLE-TYPE.
+
+\1f
+File: lispref.info,  Node: Image Instances,  Prev: Image Instantiator Conversion,  Up: Images
+
+Image Instances
+---------------
+
+Image-instance objects encapsulate the way a particular image (pixmap,
+etc.) is displayed on a particular device.
+
+   In most circumstances, you do not need to directly create image
+instances; use a glyph instead.  However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+ - Function: image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance.
+
+* Menu:
+
+* Image Instance Types::         Each image instances has a particular type.
+* Image Instance Functions::    Functions for working with image instances.
+
+\1f
+File: lispref.info,  Node: Image Instance Types,  Next: Image Instance Functions,  Up: Image Instances
+
+Image Instance Types
+....................
+
+Image instances come in a number of different types.  The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
+
+   The valid image instance types are
+
+`nothing'
+     Nothing is displayed.
+
+`text'
+     Displayed as text.  The foreground and background colors and the
+     font of the text are specified independent of the pixmap.
+     Typically these attributes will come from the face of the
+     surrounding text, unless a face is specified for the glyph in
+     which the image appears.
+
+`mono-pixmap'
+     Displayed as a mono pixmap (a pixmap with only two colors where the
+     foreground and background can be specified independent of the
+     pixmap; typically the pixmap assumes the foreground and background
+     colors of the text around it, unless a face is specified for the
+     glyph in which the image appears).
+
+`color-pixmap'
+     Displayed as a color pixmap.
+
+`pointer'
+     Used as the mouse pointer for a window.
+
+`subwindow'
+     A child window that is treated as an image.  This allows (e.g.)
+     another program to be responsible for drawing into the window.
+     Not currently implemented.
+
+ - Function: valid-image-instance-type-p type
+     This function returns non-`nil' if TYPE is a valid image instance
+     type.
+
+ - Function: image-instance-type-list
+     This function returns a list of the valid image instance types.
+
+ - Function: image-instance-type image-instance
+     This function returns the type of the given image instance.  The
+     return value will be one of `nothing', `text', `mono-pixmap',
+     `color-pixmap', `pointer', or `subwindow'.
+
+ - Function: text-image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance of
+     type `text'.
+
+ - Function: mono-pixmap-image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance of
+     type `mono-pixmap'.
+
+ - Function: color-pixmap-image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance of
+     type `color-pixmap'.
+
+ - Function: pointer-image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance of
+     type `pointer'.
+
+ - Function: subwindow-image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance of
+     type `subwindow'.
+
+ - Function: nothing-image-instance-p object
+     This function returns non-`nil' if OBJECT is an image instance of
+     type `nothing'.
+
+ - Function: widget-image-instance-p object
+     Return `t' if OBJECT is an image instance of type `widget'.
+
+\1f
+File: lispref.info,  Node: Image Instance Functions,  Prev: Image Instance Types,  Up: Image Instances
+
+Image Instance Functions
+........................
+
+ - Function: make-image-instance data &optional domain dest-types
+          noerror
+     This function creates a new image-instance object.
+
+     DATA is an image instantiator, which describes the image (*note
+     Image Specifiers::).
+
+     DEST-TYPES should be a list of allowed image instance types that
+     can be generated.  The DEST-TYPES list is unordered.  If multiple
+     destination types are possible for a given instantiator, the "most
+     natural" type for the instantiator's format is chosen. (For XBM,
+     the most natural types are `mono-pixmap', followed by
+     `color-pixmap', followed by `pointer'.  For the other normal image
+     formats, the most natural types are `color-pixmap', followed by
+     `mono-pixmap', followed by `pointer'.  For the string and
+     formatted-string formats, the most natural types are `text',
+     followed by `mono-pixmap' (not currently implemented), followed by
+     `color-pixmap' (not currently implemented).  For MS Windows
+     resources, the most natural type for pointer resources is
+     `pointer', and for the others it's `color-pixmap'.  The other
+     formats can only be instantiated as one type. (If you want to
+     control more specifically the order of the types into which an
+     image is instantiated, just call `make-image-instance' repeatedly
+     until it succeeds, passing less and less preferred destination
+     types each time.
+
+     If DEST-TYPES is omitted, all possible types are allowed.
+
+     DOMAIN specifies the domain to which the image instance will be
+     attached.  This domain is termed the "governing domain".  The type
+     of the governing domain depends on the image instantiator format.
+     (Although, more correctly, it should probably depend on the image
+     instance type.) For example, pixmap image instances are specific
+     to a device, but widget image instances are specific to a
+     particular XEmacs window because in order to display such a widget
+     when two windows onto the same buffer want to display the widget,
+     two separate underlying widgets must be created. (That's because a
+     widget is actually a child window-system window, and all
+     window-system windows have a unique existence on the screen.) This
+     means that the governing domain for a pixmap image instance will
+     be some device (most likely, the only existing device), whereas
+     the governing domain for a widget image instance will be some
+     XEmacs window.
+
+     If you specify an overly general DOMAIN (e.g. a frame when a
+     window was wanted), an error is signaled.  If you specify an overly
+     specific DOMAIN (e.g. a window when a device was wanted), the
+     corresponding general domain is fetched and used instead.  For
+     `make-image-instance', it makes no difference whether you specify
+     an overly specific domain or the properly general domain derived
+     from it.  However, it does matter when creating an image instance
+     by instantiating a specifier or glyph (e.g. with
+     `glyph-image-instance'), because the more specific domain causes
+     spec lookup to start there and proceed to more general domains. (It
+     would also matter when creating an image instance with an
+     instantiator format of `inherit', but we currently disallow this.
+     #### We should fix this.)  n If omitted, DOMAIN defaults to the
+     selected window.
+
+     NOERROR controls what happens when the image cannot be generated.
+     If `nil', an error message is generated.  If `t', no messages are
+     generated and this function returns `nil'.  If anything else, a
+     warning message is generated and this function returns `nil'.
+
+ - Function: colorize-image-instance image-instance foreground
+          background
+     This function makes the image instance be displayed in the given
+     colors.  Image instances come in two varieties: bitmaps, which are
+     1 bit deep which are rendered in the prevailing foreground and
+     background colors; and pixmaps, which are of arbitrary depth
+     (including 1) and which have the colors explicitly specified.
+     This function converts a bitmap to a pixmap.  If the image
+     instance was a pixmap already, nothing is done (and `nil' is
+     returned).  Otherwise `t' is returned.
+
+ - Function: image-instance-name image-instance
+     This function returns the name of the given image instance.
+
+ - Function: image-instance-domain image-instance
+     Return the governing domain of the given IMAGE-INSTANCE.  The
+     governing domain of an image instance is the domain that the image
+     instance is specific to.  It is _NOT_ necessarily the domain that
+     was given to the call to `specifier-instance' that resulted in the
+     creation of this image instance.  See `make-image-instance' for
+     more information on governing domains.
+
+ - Function: image-instance-string image-instance
+     This function returns the string of the given image instance.
+     This will only be non-`nil' for text image instances.
+
+ - Function: image-instance-file-name image-instance
+     This function returns the file name from which IMAGE-INSTANCE was
+     read, if known.
+
+ - Function: image-instance-mask-file-name image-instance
+     This function returns the file name from which IMAGE-INSTANCE's
+     mask was read, if known.
+
+ - Function: image-instance-depth image-instance
+     This function returns the depth of the image instance.  This is 0
+     for a mono pixmap, or a positive integer for a color pixmap.
+
+ - Function: image-instance-height image-instance
+     This function returns the height of the image instance, in pixels.
+
+ - Function: image-instance-width image-instance
+     This function returns the width of the image instance, in pixels.
+
+ - Function: image-instance-hotspot-x image-instance
+     This function returns the X coordinate of the image instance's
+     hotspot, if known.  This is a point relative to the origin of the
+     pixmap.  When an image is used as a mouse pointer, the hotspot is
+     the point on the image that sits over the location that the
+     pointer points to.  This is, for example, the tip of the arrow or
+     the center of the crosshairs.
+
+     This will always be `nil' for a non-pointer image instance.
+
+ - Function: image-instance-hotspot-y image-instance
+     This function returns the Y coordinate of the image instance's
+     hotspot, if known.
+
+ - Function: image-instance-foreground image-instance
+     This function returns the foreground color of IMAGE-INSTANCE, if
+     applicable.  This will be a color instance or `nil'. (It will only
+     be non-`nil' for colorized mono pixmaps and for pointers.)
+
+ - Function: image-instance-background image-instance
+     This function returns the background color of IMAGE-INSTANCE, if
+     applicable.  This will be a color instance or `nil'. (It will only
+     be non-`nil' for colorized mono pixmaps and for pointers.)
+
+\1f
+File: lispref.info,  Node: Glyph Types,  Next: Mouse Pointer,  Prev: Images,  Up: Glyphs
+
+Glyph Types
+===========
+
+Each glyph has a particular type, which controls how the glyph's image
+is generated.  Each glyph type has a corresponding list of allowable
+image instance types that can be generated.  When you call
+`glyph-image-instance' to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling `make-image-instance' and passing
+in DEST-TYPES the list of allowable image instance types for the
+glyph's type.
+
+   * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
+     extent, in the modeline, and in the toolbar.  Their image can be
+     instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
+     and `subwindow'.
+
+   * `pointer' glyphs can be used to specify the mouse pointer.  Their
+     image can be instantiated as `pointer'.
+
+   * `icon' glyphs can be used to specify the icon used when a frame is
+     iconified.  Their image can be instantiated as `mono-pixmap' and
+     `color-pixmap'.
+
+ - Function: glyph-type glyph
+     This function returns the type of the given glyph.  The return
+     value will be a symbol, one of `buffer', `pointer', or `icon'.
+
+ - Function: valid-glyph-type-p glyph-type
+     Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+
+ - Function: glyph-type-list
+     This function returns a list of valid glyph types.
+
+ - Function: buffer-glyph-p object
+     This function returns non-`nil' if OBJECT is a glyph of type
+     `buffer'.
+
+ - Function: icon-glyph-p object
+     This function returns non-`nil' if OBJECT is a glyph of type
+     `icon'.
+
+ - Function: pointer-glyph-p object
+     This function returns non-`nil' if OBJECT is a glyph of type
+     `pointer'.
+
+\1f
+File: lispref.info,  Node: Mouse Pointer,  Next: Redisplay Glyphs,  Prev: Glyph Types,  Up: Glyphs
+
+Mouse Pointer
+=============
+
+The shape of the mouse pointer when over a particular section of a frame
+is controlled using various glyph variables.  Since the image of a glyph
+is a specifier, it can be controlled on a per-buffer, per-frame,
+per-window, or per-device basis.
+
+   You should use `set-glyph-image' to set the following variables,
+_not_ `setq'.
+
+ - Glyph: text-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over
+     text.
+
+ - Glyph: nontext-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over a
+     buffer, but not over text.  If unspecified in a particular domain,
+     `text-pointer-glyph' is used.
+
+ - Glyph: modeline-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over
+     the modeline.  If unspecified in a particular domain,
+     `nontext-pointer-glyph' is used.
+
+ - Glyph: selection-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over a
+     selectable text region.  If unspecified in a particular domain,
+     `text-pointer-glyph' is used.
+
+ - Glyph: gc-pointer-glyph
+     This variable specifies the shape of the mouse pointer when a
+     garbage collection is in progress.  If the selected window is on a
+     window system and this glyph specifies a value (i.e. a pointer
+     image instance) in the domain of the selected window, the pointer
+     will be changed as specified during garbage collection.
+     Otherwise, a message will be printed in the echo area, as
+     controlled by `gc-message'.
+
+ - Glyph: busy-pointer-glyph
+     This variable specifies the shape of the mouse pointer when XEmacs
+     is busy.  If unspecified in a particular domain, the pointer is
+     not changed when XEmacs is busy.
+
+ - Glyph: menubar-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over
+     the menubar.  If unspecified in a particular domain, the
+     window-system-provided default pointer is used.
+
+ - Glyph: scrollbar-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over a
+     scrollbar.  If unspecified in a particular domain, the
+     window-system-provided default pointer is used.
+
+ - Glyph: toolbar-pointer-glyph
+     This variable specifies the shape of the mouse pointer when over a
+     toolbar.  If unspecified in a particular domain,
+     `nontext-pointer-glyph' is used.
+
+   Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves.  That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
+
+ - Function: set-frame-pointer frame image-instance
+     This function sets the mouse pointer of FRAME to the given pointer
+     image instance.  You should not call this function directly.  (If
+     you do, the pointer will change again the next time the mouse
+     moves.)
+
+\1f
+File: lispref.info,  Node: Redisplay Glyphs,  Next: Subwindows,  Prev: Mouse Pointer,  Up: Glyphs
+
+Redisplay Glyphs
+================
+
+ - Glyph: truncation-glyph
+     This variable specifies what is displayed at the end of truncated
+     lines.
+
+ - Glyph: continuation-glyph
+     This variable specifies what is displayed at the end of wrapped
+     lines.
+
+ - Glyph: octal-escape-glyph
+     This variable specifies what to prefix character codes displayed
+     in octal with.
+
+ - Glyph: hscroll-glyph
+     This variable specifies what to display at the beginning of
+     horizontally scrolled lines.
+
+ - Glyph: invisible-text-glyph
+     This variable specifies what to use to indicate the presence of
+     invisible text.  This is the glyph that is displayed when an
+     ellipsis is called for, according to `selective-display-ellipses'
+     or `buffer-invisibility-spec').  Normally this is three dots
+     ("...").
+
+ - Glyph: control-arrow-glyph
+     This variable specifies what to use as an arrow for control
+     characters.
+
+\1f
+File: lispref.info,  Node: Subwindows,  Next: Glyph Examples,  Prev: Redisplay Glyphs,  Up: Glyphs
+
+Subwindows
+==========
+
+Subwindows are not currently implemented.
+
+ - Function: subwindowp object
+     This function returns non-`nil' if OBJECT is a subwindow.
+
+\1f
+File: lispref.info,  Node: Glyph Examples,  Prev: Subwindows,  Up: Glyphs
+
+Glyph Examples
+==============
+
+For many applications, displaying graphics is a simple process: you
+create a glyph, and then you insert it into a buffer.
+
+   The easiest way to create a glyph is to use a file that contains a
+graphical image, such as a JPEG, TIFF, or PNG file:
+
+     ;; Create a glyph from a JPEG file:
+     (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+
+     ;; Create a glyph from a XPM file:
+     (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
+
+     ;; Create a glyph from a PNG file:
+     (setq foo (make-glyph [png :file "/tmp/file3.png"]))
+
+     ;; Create a glyph from a TIFF file:
+     (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
+
+   The parameters passed to `make-glyph' are called "Image Specifiers",
+and can handle more image types than those shown above.  You can also
+put the raw image data into a string (e.g., if you put the contents of
+a JPEG file into a string), and use that to create a glyph.  *Note
+Image Specifiers::, for more information.
+
+     *Caution*: In order for XEmacs to read a particular graphics file
+     format, support for that format must have been compiled into
+     XEmacs.  It's possible, although somewhat unlikely, for XEmacs to
+     have been compiled without support for any of the various graphics
+     file formats.  To see what graphics formats your particular
+     version of XEmacs supports, use `M-x describe-installation'.
+
+     To programmatically query whether or not a particular file format
+     is supported, you can use the `featurep' function, with one of:
+     `gif', `tiff', `jpeg', `xpm', `xbm', `png', or `xface'.  For an
+     up-to-date list, *Note Image Specifiers::.  Example:
+
+          ;; Returns `t' if TIFF is supported:
+          (featurep 'tiff)
+
+     Another example is:
+
+          ;; Returns a list of `t' or `nil', depending on whether or not the
+          ;; corresponding feature is supported:
+          (mapcar #'(lambda (format-symbol) (featurep format-symbol))
+                  '(gif tiff jpeg xpm png))
+
+
+   Once you have a glyph, you can then insert it into a buffer.
+Example:
+
+     ;; Use this function to insert a glyph at the left edge of point in the
+     ;; current buffer.  Any existing glyph at this location is replaced.
+     (defun insert-glyph (gl)
+       "Insert a glyph at the left edge of point."
+       (let ( (prop 'myimage)        ;; myimage is an arbitrary name, chosen
+                                     ;; to (hopefully) not conflict with any
+                                     ;; other properties.  Change it if
+                                     ;; necessary.
+              extent )
+         ;; First, check to see if one of our extents already exists at
+         ;; point.  For ease-of-programming, we are creating and using our
+         ;; own extents (multiple extents are allowed to exist/overlap at the
+         ;; same point, and it's quite possible for other applications to
+         ;; embed extents in the current buffer without your knowledge).
+         ;; Basically, if an extent, with the property stored in "prop",
+         ;; exists at point, we assume that it is one of ours, and we re-use
+         ;; it (this is why it is important for the property stored in "prop"
+         ;; to be unique, and only used by us).
+         (if (not (setq extent (extent-at (point) (current-buffer) prop)))
+           (progn
+             ;; If an extent does not already exist, create a zero-length
+             ;; extent, and give it our special property.
+             (setq extent (make-extent (point) (point) (current-buffer)))
+             (set-extent-property extent prop t)
+             ))
+         ;; Display the glyph by storing it as the extent's "begin-glyph".
+         (set-extent-property extent 'begin-glyph gl)
+         ))
+     
+     ;; You can then use this function like:
+     (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+     ;; This will insert the glyph at point.
+     
+     ;; Here's an example of how to insert two glyphs side-by-side, at point
+     ;; (using the above code):
+     (progn
+       (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+       ;; Create a new extent at point.  We can't simply call "insert-glyph",
+       ;; as "insert-glyph" will simply replace the first glyph with the
+       ;; second.
+       (setq extent (make-extent (point) (point) (current-buffer)))
+       ;; Here, we're only setting the 'myimage property in case we need
+       ;; to later identify/locate/reuse this particular extent.
+       (set-extent-property extent 'myimage t)
+       (set-extent-property extent 'begin-glyph
+                            (make-glyph [jpeg :file "/tmp/file2.jpg"]))
+       )
+
+   Here are the gory details:
+
+   * Glyphs are displayed by attaching them to extents (see *Note
+     Extents::), either to the beginning or the end of extents.
+
+     Note that extents can be used for many things, and not just for
+     displaying images (although, in the above example, we are creating
+     our own extent for the sole purpose of displaying an image).
+     Also, note that multiple extents are allowed to exist at the same
+     position, and they can overlap.
+
+   * Glyphs are often displayed inside the text area (alongside text).
+     This is the default.
+
+     Although glyphs can also be displayed in the margins, how to do
+     this will not be described here.  For more information on this, see
+     *Note Annotation Basics:: (look for information on "layout types")
+     and *Note Extent Properties:: (look for `begin-glyph-layout' and
+     `end-glyph-layout').
+
+   * The easiest way to insert a glyph into text is to create a
+     zero-length extent at the point where you want the glyph to appear.
+
+     Note that zero-length extents are attached to the character to the
+     right of the extent; deleting this character will also delete the
+     extent.
+
+   * It's often a good idea to assign a unique property to the
+     newly-created extent, in case you later want to locate it, and
+     replace any existing glyph with a different one (or just delete
+     the existing one).  In the above example, we are using "myimage"
+     as our (hopefully) unique property name.
+
+     If you need to locate all of the extents, you'll have to use
+     functions like `extent-list' or `next-extent', or provide
+     additional parameters to the `extent-at' function.  Assigning a
+     unique property to the extent makes it easy to locate your
+     extents; for example, `extent-list' can return only those extents
+     with a particular property.  *Note Finding Extents::, and *Note
+     Mapping Over Extents::, for more information.
+
+   * Glyphs are displayed by assigning then to the `begin-glyph' or
+     `end-glyph' property of the extent.  For zero-length extents, it
+     doesn't really matter if you assign the glyph to the `begin-glyph'
+     or `end-glyph' property, as they are both at the same location;
+     however, for non-zero-length extents (extents that cover one or
+     more characters of text), it does matter which one you use.
+
+     Assigning `nil' to the `begin-glyph' or `end-glyph' property will
+     delete any existing glyph.  In this case, you may also want to
+     delete the extent, assuming that the extent is used for no other
+     purpose.
+
+   * If you happen to insert two glyphs, side-by-side, note that the
+     example `insert-glyph' function will have trouble, if it's again
+     used at the same point (it can only locate one of the two extents).
+     *Note Finding Extents::, and *Note Mapping Over Extents::, for more
+     information on locating extents in a buffer.
+
+   * Among other things, glyphs provide a way of displaying graphics
+     alongside text.  Note, however, that glyphs only provide a way of
+     displaying graphics; glyphs are not actually part of the text, and
+     are only displayed alongside the text.  If you save the text in
+     the buffer, the graphics are not saved.  The low-level glyph code
+     does not provide a way of saving graphics with the text.  If you
+     need to save graphics and text, you have to write your own code to
+     do this, and this topic is outside the scope of this discussion.
+
+
+\1f
+File: lispref.info,  Node: Annotations,  Next: Display,  Prev: Glyphs,  Up: Top
+
+Annotations
+***********
+
+An "annotation" is a pixmap or string that is not part of a buffer's
+text but is displayed next to a particular location in a buffer.
+Annotations can be displayed intermixed with text, in any whitespace at
+the beginning or end of a line, or in a special area at the left or
+right side of the frame called a "margin", whose size is controllable.
+Annotations are implemented using extents (*note Extents::); but you
+can work with annotations without knowing how extents work.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Annotation Basics,  Next: Annotation Primitives,  Up: Annotations
+
+Annotation Basics
+=================
+
+Marginal annotations are notes associated with a particular location in
+a buffer.  They may be displayed in a margin created on the left-hand or
+right-hand side of the frame, in any whitespace at the beginning or end
+of a line, or inside of the text itself.  Every annotation may have an
+associated action to be performed when the annotation is selected.  The
+term "annotation" is used to refer to an individual note.  The term
+"margin" is generically used to refer to the whitespace before the
+first character on a line or after the last character on a line.
+
+   Each annotation has the following characteristics:
+GLYPH
+     This is a glyph object and is used as the displayed representation
+     of the annotation.
+
+DOWN-GLYPH
+     If given, this glyph is used as the displayed representation of
+     the annotation when the mouse is pressed down over the annotation.
+
+FACE
+     The face with which to display the glyph.
+
+SIDE
+     Which side of the text (left or right) the annotation is displayed
+     at.
+
+ACTION
+     If non-`nil', this field must contain a function capable of being
+     the first argument to `funcall'.  This function is normally
+     evaluated with a single argument, the value of the DATA field,
+     each time the annotation is selected.  However, if the WITH-EVENT
+     parameter to `make-annotation' is non-`nil', the function is
+     called with two arguments.  The first argument is the same as
+     before, and the second argument is the event (a button-up event,
+     usually) that activated the annotation.
+
+DATA
+     Not used internally.  This field can contain any E-Lisp object.
+     It is passed as the first argument to ACTION described above.
+
+MENU
+     A menu displayed when the right mouse button is pressed over the
+     annotation.
+
+   The margin is divided into "outside" and "inside".  The outside
+margin is space on the left or right side of the frame which normal text
+cannot be displayed in.  The inside margin is that space between the
+leftmost or rightmost point at which text can be displayed and where the
+first or last character actually is.
+
+   There are four different "layout types" which affect the exact
+location an annotation appears.
+
+`outside-margin'
+     The annotation is placed in the outside margin area. as close as
+     possible to the edge of the frame.  If the outside margin is not
+     wide enough for an annotation to fit, it is not displayed.
+
+`inside-margin'
+     The annotation is placed in the inside margin area, as close as
+     possible to the edge of the frame.  If the inside margin is not
+     wide enough for the annotation to fit, it will be displayed using
+     any available outside margin space if and only if the specifier
+     `use-left-overflow' or `use-right-overflow' (depending on which
+     side the annotation appears in) is non-`nil'.
+
+`whitespace'
+     The annotation is placed in the inside margin area, as close as
+     possible to the first or last non-whitespace character on a line.
+     If the inside margin is not wide enough for the annotation to fit,
+     it will be displayed if and only if the specifier
+     `use-left-overflow' or `use-right-overflow' (depending on which
+     side the annotation appears in) is non-`nil'.
+
+`text'
+     The annotation is placed at the position it is inserted.  It will
+     create enough space for itself inside of the text area.  It does
+     not take up a place in the logical buffer, only in the display of
+     the buffer.
+
+   The current layout policy is that all `whitespace' annotations are
+displayed first.  Next, all `inside-margin' annotations are displayed
+using any remaining space.  Finally as many `outside-margin'
+annotations are displayed as possible.  The `text' annotations will
+always display as they create their own space to display in.
+
+\1f
+File: lispref.info,  Node: Annotation Primitives,  Next: Annotation Properties,  Prev: Annotation Basics,  Up: Annotations
+
+Annotation Primitives
+=====================
+
+ - Function: make-annotation glyph &optional position layout buffer
+          with-event d-glyph rightp
+     This function creates a marginal annotation at position POSITION in
+     BUFFER.  The annotation is displayed using GLYPH, which should be
+     a glyph object or a string, and is positioned using layout policy
+     LAYOUT.  If POSITION is `nil', point is used.  If LAYOUT is `nil',
+     `whitespace' is used.  If BUFFER is `nil', the current buffer is
+     used.
+
+     If WITH-EVENT is non-`nil', then when an annotation is activated,
+     the triggering event is passed as the second arg to the annotation
+     function.  If D-GLYPH is non-`nil' then it is used as the glyph
+     that will be displayed when button1 is down.  If RIGHTP is
+     non-`nil' then the glyph will be displayed on the right side of
+     the buffer instead of the left.
+
+     The newly created annotation is returned.
+
+ - Function: delete-annotation annotation
+     This function removes ANNOTATION from its buffer.  This does not
+     modify the buffer text.
+
+ - Function: annotationp annotation
+     This function returns `t' if ANNOTATION is an annotation, `nil'
+     otherwise.
+
+\1f
+File: lispref.info,  Node: Annotation Properties,  Next: Margin Primitives,  Prev: Annotation Primitives,  Up: Annotations
+
+Annotation Properties
+=====================
+
+ - Function: annotation-glyph annotation
+     This function returns the glyph object used to display ANNOTATION.
+
+ - Function: set-annotation-glyph annotation glyph &optional layout side
+     This function sets the glyph of ANNOTATION to GLYPH, which should
+     be a glyph object.  If LAYOUT is non-`nil', set the layout policy
+     of ANNOTATION to LAYOUT.  If SIDE is `left' or `right', change the
+     side of the buffer at which the annotation is displayed to the
+     given side.  The new value of `annotation-glyph' is returned.
+
+ - Function: annotation-down-glyph annotation
+     This function returns the glyph used to display ANNOTATION when
+     the left mouse button is depressed on the annotation.
+
+ - Function: set-annotation-down-glyph annotation glyph
+     This function returns the glyph used to display ANNOTATION when
+     the left mouse button is depressed on the annotation to GLYPH,
+     which should be a glyph object.
+
+ - Function: annotation-face annotation
+     This function returns the face associated with ANNOTATION.
+
+ - Function: set-annotation-face annotation face
+     This function sets the face associated with ANNOTATION to FACE.
+
+ - Function: annotation-layout annotation
+     This function returns the layout policy of ANNOTATION.
+
+ - Function: set-annotation-layout annotation layout
+     This function sets the layout policy of ANNOTATION to LAYOUT.
+
+ - Function: annotation-side annotation
+     This function returns the side of the buffer that ANNOTATION is
+     displayed on.  Return value is a symbol, either `left' or `right'.
+
+ - Function: annotation-data annotation
+     This function returns the data associated with ANNOTATION.
+
+ - Function: set-annotation-data annotation data
+     This function sets the data field of ANNOTATION to DATA.  DATA is
+     returned.
+
+ - Function: annotation-action annotation
+     This function returns the action associated with ANNOTATION.
+
+ - Function: set-annotation-action annotation action
+     This function sets the action field of ANNOTATION to ACTION.
+     ACTION is returned..
+
+ - Function: annotation-menu annotation
+     This function returns the menu associated with ANNOTATION.
+
+ - Function: set-annotation-menu annotation menu
+     This function sets the menu associated with ANNOTATION to MENU.
+     This menu will be displayed when the right mouse button is pressed
+     over the annotation.
+
+ - Function: annotation-visible annotation
+     This function returns `t' if there is enough available space to
+     display ANNOTATION, `nil' otherwise.
+
+ - Function: annotation-width annotation
+     This function returns the width of ANNOTATION in pixels.
+
+ - Function: hide-annotation annotation
+     This function removes ANNOTATION's glyph, making it invisible.
+
+ - Function: reveal-annotation annotation
+     This function restores ANNOTATION's glyph, making it visible.
+
+\1f
+File: lispref.info,  Node: Locating Annotations,  Next: Annotation Hooks,  Prev: Margin Primitives,  Up: Annotations
+
+Locating Annotations
+====================
+
+ - Function: annotations-in-region start end buffer
+     This function returns a list of all annotations in BUFFER which
+     are between START and END inclusively.
+
+ - Function: annotations-at &optional position buffer
+     This function returns a list of all annotations at POSITION in
+     BUFFER.  If POSITION is `nil' point is used.  If BUFFER is `nil'
+     the current buffer is used.
+
+ - Function: annotation-list &optional buffer
+     This function returns a list of all annotations in BUFFER.  If
+     BUFFER is `nil', the current buffer is used.
+
+ - Function: all-annotations
+     This function returns a list of all annotations in all buffers in
+     existence.
+
+\1f
+File: lispref.info,  Node: Margin Primitives,  Next: Locating Annotations,  Prev: Annotation Properties,  Up: Annotations
+
+Margin Primitives
+=================
+
+The margin widths are controllable on a buffer-local, window-local,
+frame-local, device-local, or device-type-local basis through the use
+of specifiers.  *Note Specifiers::.
+
+ - Specifier: left-margin-width
+     This is a specifier variable controlling the width of the left
+     outside margin, in characters.  Use `set-specifier' to change its
+     value.
+
+ - Specifier: right-margin-width
+     This is a specifier variable controlling the width of the right
+     outside margin, in characters.  Use `set-specifier' to change its
+     value.
+
+ - Specifier: use-left-overflow
+     If non-`nil', use the left outside margin as extra whitespace when
+     displaying `whitespace' and `inside-margin' annotations.  Defaults
+     to `nil'.  This is a specifier variable; use `set-specifier' to
+     change its value.
+
+ - Specifier: use-right-overflow
+     If non-`nil', use the right outside margin as extra whitespace when
+     displaying `whitespace' and `inside-margin' annotations.  Defaults
+     to `nil'.  This is a specifier variable; use `set-specifier' to
+     change its value.
+
+ - Function: window-left-margin-pixel-width &optional window
+     This function returns the width in pixels of the left outside
+     margin of WINDOW.  If WINDOW is `nil', the selected window is
+     assumed.
+
+ - Function: window-right-margin-pixel-width &optional window
+     This function returns the width in pixels of the right outside
+     margin of WINDOW.  If WINDOW is `nil', the selected window is
+     assumed.
+
+   The margin colors are controlled by the faces `left-margin' and
+`right-margin'.  These can be set using the X resources
+`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
+likewise for the right margin.
+
+\1f
+File: lispref.info,  Node: Annotation Hooks,  Prev: Locating Annotations,  Up: Annotations
+
+Annotation Hooks
+================
+
+The following three hooks are provided for use with the marginal
+annotations:
+
+`before-delete-annotation-hook'
+     This hook is called immediately before an annotation is destroyed.
+     It is passed a single argument, the annotation being destroyed.
+
+`after-delete-annotation-hook'
+     This normal hook is called immediately after an annotation is
+     destroyed.
+
+`make-annotation-hook'
+     This hook is called immediately after an annotation is created.
+     It is passed a single argument, the newly created annotation.
+
+\1f
+File: lispref.info,  Node: Display,  Next: Hash Tables,  Prev: Annotations,  Up: Top
+
+Emacs Display
+*************
+
+This chapter describes a number of other features related to the display
+that XEmacs presents to the user.
+
+* Menu:
+
+* Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Truncation::          Folding or wrapping long text lines.
+* The Echo Area::       Where messages are displayed.
+* Warnings::            Display of Warnings.
+* Invisible Text::      Hiding part of the buffer text.
+* Selective Display::   Hiding part of the buffer text (the old way).
+* 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.
+
+\1f
+File: lispref.info,  Node: Refresh Screen,  Next: Truncation,  Up: Display
+
+Refreshing the Screen
+=====================
+
+The function `redraw-frame' redisplays the entire contents of a given
+frame.  *Note Frames::.
+
+ - Function: redraw-frame &optional frame no-preempt
+     This function clears and redisplays frame FRAME.
+
+     FRAME defaults to the selected frame if omitted.
+
+     Normally, redisplay is preempted as normal if input arrives.
+     However, if optional second arg NO-PREEMPT is non-`nil', redisplay
+     will not stop for input and is guaranteed to proceed to completion.
+
+   Even more powerful is `redraw-display':
+
+ - Command: redraw-display &optional device
+     This function redraws all frames on DEVICE marked as having their
+     image garbled.  DEVICE defaults to the selected device.  If DEVICE
+     is `t', all devices will have their frames checked.
+
+   Processing user input takes absolute priority over redisplay.  If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually--after all the
+input has been processed.
+
+   Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display.  If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption.  *Note Suspending XEmacs::.
+
+ - Variable: no-redraw-on-reenter
+     This variable controls whether XEmacs redraws the entire screen
+     after it has been suspended and resumed.  Non-`nil' means yes,
+     `nil' means no.
+
+   The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch.  Normally this occurs the next time that
+`next-event' or `sit-for' is called; however, a display update will not
+occur if there is input pending.  *Note Command Loop::.
+
+ - Function: force-cursor-redisplay &optional frame
+     This function causes an immediate update of the cursor on FRAME,
+     which defaults to the selected frame.
+
+\1f
+File: lispref.info,  Node: Truncation,  Next: The Echo Area,  Prev: Refresh Screen,  Up: Display
+
+Truncation
+==========
+
+When a line of text extends beyond the right edge of a window, the line
+can either be truncated or continued on the next line.  When a line is
+truncated, this is normally shown with a `\' in the rightmost column of
+the window on X displays, and with a `$' on TTY devices.  When a line
+is continued or "wrapped" onto the next line, this is shown with a
+curved arrow in the rightmost column of the window (or with a `\' on
+TTY devices).  The additional screen lines used to display a long text
+line are called "continuation" lines.
+
+   Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars.  *Note Scrollbars::.
+
+   Note that continuation is different from filling; continuation
+happens on the screen only, not in the buffer contents, and it breaks a
+line precisely at the right margin, not at a word boundary.  *Note
+Filling::.
+
+ - User Option: truncate-lines
+     This buffer-local variable controls how XEmacs displays lines that
+     extend beyond the right edge of the window.  If it is non-`nil',
+     then XEmacs does not display continuation lines; rather each line
+     of text occupies exactly one screen line, and a backslash appears
+     at the edge of any line that extends to or beyond the edge of the
+     window.  The default is `nil'.
+
+     If the variable `truncate-partial-width-windows' is non-`nil',
+     then truncation is always used for side-by-side windows (within one
+     frame) regardless of the value of `truncate-lines'.
+
+ - User Option: default-truncate-lines
+     This variable is the default value for `truncate-lines', for
+     buffers that do not have local values for it.
+
+ - User Option: truncate-partial-width-windows
+     This variable controls display of lines that extend beyond the
+     right edge of the window, in side-by-side windows (*note Splitting
+     Windows::).  If it is non-`nil', these lines are truncated;
+     otherwise, `truncate-lines' says what to do with them.
+
+   The backslash and curved arrow used to indicate truncated or
+continued lines are only defaults, and can be changed.  These images
+are actually glyphs (*note Glyphs::).  XEmacs provides a great deal of
+flexibility in how glyphs can be controlled. (This differs from FSF
+Emacs, which uses display tables to control these images.)
+
+   For details, *Note Redisplay Glyphs::.
+
+\1f
+File: lispref.info,  Node: The Echo Area,  Next: Warnings,  Prev: Truncation,  Up: Display
+
+The Echo Area
+=============
+
+The "echo area" is used for displaying messages made with the `message'
+primitive, and for echoing keystrokes.  It is not the same as the
+minibuffer, despite the fact that the minibuffer appears (when active)
+in the same place on the screen as the echo area.  The `XEmacs Lisp
+Reference Manual' specifies the rules for resolving conflicts between
+the echo area and the minibuffer for use of that screen space (*note
+The Minibuffer: (xemacs)Minibuffer.).  Error messages appear in the
+echo area; see *Note Errors::.
+
+   You can write output in the echo area by using the Lisp printing
+functions with `t' as the stream (*note Output Functions::), or as
+follows:
+
+ - Function: message string &rest arguments
+     This function displays a one-line message in the echo area.  The
+     argument STRING is similar to a C language `printf' control
+     string.  See `format' in *Note String Conversion::, for the details
+     on the conversion specifications.  `message' returns the
+     constructed string.
+
+     In batch mode, `message' prints the message text on the standard
+     error stream, followed by a newline.
+
+     If STRING is `nil', `message' clears the echo area.  If the
+     minibuffer is active, this brings the minibuffer contents back onto
+     the screen immediately.
+
+          (message "Minibuffer depth is %d."
+                   (minibuffer-depth))
+           -| Minibuffer depth is 0.
+          => "Minibuffer depth is 0."
+          
+          ---------- Echo Area ----------
+          Minibuffer depth is 0.
+          ---------- Echo Area ----------
+
+   In addition to only displaying a message, XEmacs allows you to
+"label" your messages, giving you fine-grained control of their
+display.  Message label is a symbol denoting the message type.  Some
+standard labels are:
+
+   * `message'--default label used by the `message' function;
+
+   * `error'--default label used for reporting errors;
+
+   * `progress'--progress indicators like `Converting... 45%' (not
+     logged by default);
+
+   * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+     default);
+
+   * `command'--helper command messages like `Mark set' (not logged by
+     default);
+
+   * `no-log'--messages that should never be logged
+
+   Several messages may be stacked in the echo area at once.  Lisp
+programs may access these messages, or remove them as appropriate, via
+the message stack.
+
+ - Function: display-message label message &optional frame stdout-p
+     This function displays MESSAGE (a string) labeled as LABEL, as
+     described above.
+
+     The FRAME argument specifies the frame to whose minibuffer the
+     message should be printed.  This is currently unimplemented.  The
+     STDOUT-P argument is used internally.
+
+          (display-message 'command "Mark set")
+
+ - Function: lmessage label string &rest arguments
+     This function displays a message STRING with label LABEL.  It is
+     similar to `message' in that it accepts a `printf'-like strings
+     and any number of arguments.
+
+          ;; Display a command message.
+          (lmessage 'command "Comment column set to %d" comment-column)
+          
+          ;; Display a progress message.
+          (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
+          
+          ;; Display a message that should not be logged.
+          (lmessage 'no-log "Done")
+
+ - Function: clear-message &optional label frame stdout-p no-restore
+     This function remove any message with the given LABEL from the
+     message-stack, erasing it from the echo area if it's currently
+     displayed there.
+
+     If a message remains at the head of the message-stack and
+     NO-RESTORE is `nil', it will be displayed.  The string which
+     remains in the echo area will be returned, or `nil' if the
+     message-stack is now empty.  If LABEL is `nil', the entire
+     message-stack is cleared.
+
+          ;; Show a message, wait for 2 seconds, and restore old minibuffer
+          ;; contents.
+          (message "A message")
+           -| A message
+          => "A Message"
+          (lmessage 'my-label "Newsflash!  Newsflash!")
+           -| Newsflash!  Newsflash!
+          => "Newsflash!  Newsflash!"
+          (sit-for 2)
+          (clear-message 'my-label)
+           -| A message
+          => "A message"
+
+     Unless you need the return value or you need to specify a label,
+     you should just use `(message nil)'.
+
+ - Function: current-message &optional frame
+     This function returns the current message in the echo area, or
+     `nil'.  The FRAME argument is currently unused.
+
+   Some of the messages displayed in the echo area are also recorded in
+the ` *Message-Log*' buffer.  Exactly which messages will be recorded
+can be tuned using the following variables.
+
+ - User Option: log-message-max-size
+     This variable specifies the maximum size of the ` *Message-log*'
+     buffer.
+
+ - Variable: log-message-ignore-labels
+     This variable specifies the labels whose messages will not be
+     logged.  It should be a list of symbols.
+
+ - Variable: log-message-ignore-regexps
+     This variable specifies the regular expressions matching messages
+     that will not be logged.  It should be a list of regular
+     expressions.
+
+     Normally, packages that generate messages that might need to be
+     ignored should label them with `progress', `prompt', or `no-log',
+     so they can be filtered by `log-message-ignore-labels'.
+
+ - Variable: echo-keystrokes
+     This variable determines how much time should elapse before command
+     characters echo.  Its value must be a number, which specifies the
+     number of seconds to wait before echoing.  If the user types a
+     prefix key (such as `C-x') and then delays this many seconds
+     before continuing, the prefix key 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.
+
+ - Variable: cursor-in-echo-area
+     This variable controls where the cursor appears when a message is
+     displayed in the echo area.  If it is non-`nil', then the cursor
+     appears at the end of the message.  Otherwise, the cursor appears
+     at point--not in the echo area at all.
+
+     The value is normally `nil'; Lisp programs bind it to `t' for
+     brief periods of time.
+
+\1f
+File: lispref.info,  Node: Warnings,  Next: Invisible Text,  Prev: The Echo Area,  Up: Display
+
+Warnings
+========
+
+XEmacs contains a facility for unified display of various warnings.
+Unlike errors, warnings are displayed in the situations when XEmacs
+encounters a problem that is recoverable, but which should be fixed for
+safe future operation.
+
+   For example, warnings are printed by the startup code when it
+encounters problems with X keysyms, when there is an error in `.emacs',
+and in other problematic situations.  Unlike messages, warnings are
+displayed in a separate buffer, and include an explanatory message that
+may span across several lines.  Here is an example of how a warning is
+displayed:
+
+     (1) (initialization/error) An error has occurred while loading ~/.emacs:
+     
+     Symbol's value as variable is void: bogus-variable
+     
+     To ensure normal operation, you should investigate the cause of the error
+     in your initialization file and remove it.  Use the `-debug-init' option
+     to XEmacs to view a complete error backtrace.
+
+   Each warning has a "class" and a "priority level".  The class is a
+symbol describing what sort of warning this is, such as
+`initialization', `resource' or `key-mapping'.
+
+   The warning priority level specifies how important the warning is.
+The recognized warning levels, in increased order of priority, are:
+`debug', `info', `notice', `warning', `error', `critical', `alert' and
+`emergency'.
+
+ - Function: display-warning class message &optional level
+     This function displays a warning message MESSAGE (a string).
+     CLASS should be a warning class symbol, as described above, or a
+     list of such symbols.  LEVEL describes the warning priority level.
+     If unspecified, it default to `warning'.
+
+          (display-warning 'resource
+            "Bad resource specification encountered:
+          something like
+          
+              Emacs*foo: bar
+          
+          You should replace the * with a . in order to get proper behavior when
+          you use the specifier and/or `set-face-*' functions.")
+          
+          ---------- Warning buffer ----------
+          (1) (resource/warning) Bad resource specification encountered:
+          something like
+          
+              Emacs*foo: bar
+          
+          You should replace the * with a . in order to get proper behavior when
+          you use the specifier and/or `set-face-*' functions.
+          ---------- Warning buffer ----------
+
+ - Function: lwarn class level message &rest args
+     This function displays a formatted labeled warning message.  As
+     above, CLASS should be the warning class symbol, or a list of such
+     symbols, and LEVEL should specify the warning priority level
+     (`warning' by default).
+
+     Unlike in `display-warning', MESSAGE may be a formatted message,
+     which will be, together with the rest of the arguments, passed to
+     `format'.
+
+          (lwarn 'message-log 'warning
+            "Error caught in `remove-message-hook': %s"
+            (error-message-string e))
+
+ - Variable: log-warning-minimum-level
+     This variable specifies the minimum level of warnings that should
+     be generated.  Warnings with level lower than defined by this
+     variable are completely ignored, as if they never happened.
+
+ - Variable: display-warning-minimum-level
+     This variable specifies the minimum level of warnings that should
+     be displayed.  Unlike `log-warning-minimum-level', setting this
+     function does not suppress warnings entirely--they are still
+     generated in the `*Warnings*' buffer, only they are not displayed
+     by default.
+
+ - Variable: log-warning-suppressed-classes
+     This variable specifies a list of classes that should not be
+     logged or displayed.  If any of the class symbols associated with
+     a warning is the same as any of the symbols listed here, the
+     warning will be completely ignored, as it they never happened.
+
+ - Variable: display-warning-suppressed-classes
+     This variable specifies a list of classes that should not be
+     logged or displayed.  If any of the class symbols associated with
+     a warning is the same as any of the symbols listed here, the
+     warning will not be displayed.  The warning will still logged in
+     the *Warnings* buffer (unless also contained in
+     `log-warning-suppressed-classes'), but the buffer will not be
+     automatically popped up.
+
+\1f
+File: lispref.info,  Node: Invisible Text,  Next: Selective Display,  Prev: Warnings,  Up: Display
+
+Invisible Text
+==============
+
+You can make characters "invisible", so that they do not appear on the
+screen, with the `invisible' property.  This can be either a text
+property or a property of an overlay.
+
+   In the simplest case, any non-`nil' `invisible' property makes a
+character invisible.  This is the default case--if you don't alter the
+default value of `buffer-invisibility-spec', this is how the
+`invisibility' property works.  This feature is much like selective
+display (*note Selective Display::), but more general and cleaner.
+
+   More generally, you can use the variable `buffer-invisibility-spec'
+to control which values of the `invisible' property make text
+invisible.  This permits you to classify the text into different subsets
+in advance, by giving them different `invisible' values, and
+subsequently make various subsets visible or invisible by changing the
+value of `buffer-invisibility-spec'.
+
+   Controlling visibility with `buffer-invisibility-spec' is especially
+useful in a program to display the list of entries in a data base.  It
+permits the implementation of convenient filtering commands to view
+just a part of the entries in the data base.  Setting this variable is
+very fast, much faster than scanning all the text in the buffer looking
+for properties to change.
+
+ - Variable: buffer-invisibility-spec
+     This variable specifies which kinds of `invisible' properties
+     actually make a character invisible.
+
+    `t'
+          A character is invisible if its `invisible' property is
+          non-`nil'.  This is the default.
+
+    a list
+          Each element of the list makes certain characters invisible.
+          Ultimately, a character is invisible if any of the elements
+          of this list applies to it.  The list can have two kinds of
+          elements:
+
+         `ATOM'
+               A character is invisible if its `invisible' property
+               value is ATOM or if it is a list with ATOM as a member.
+
+         `(ATOM . t)'
+               A character is invisible if its `invisible' property
+               value is ATOM or if it is a list with ATOM as a member.
+               Moreover, if this character is at the end of a line and
+               is followed by a visible newline, it displays an
+               ellipsis.
+
+   Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible.  However, the user-level line motion
+commands explicitly ignore invisible newlines.  Since this causes a
+slow-down of these commands it is turned off by default, controlled by
+the variable `line-move-ignore-invisible'.
+
+\1f
+File: lispref.info,  Node: Selective Display,  Next: Overlay Arrow,  Prev: Invisible Text,  Up: Display
+
+Selective Display
+=================
+
+"Selective display" is a pair of features that hide certain lines on
+the screen.
+
+   The first variant, explicit selective display, is designed for use in
+a Lisp program.  The program controls which lines are hidden by altering
+the text.  Outline mode has traditionally used this variant.  It has
+been partially replaced by the invisible text feature (*note Invisible
+Text::); there is a new version of Outline mode which uses that instead.
+
+   In the second variant, the choice of lines to hide is made
+automatically based on indentation.  This variant is designed to be a
+user-level feature.
+
+   The way you control explicit selective display is by replacing a
+newline (control-j) with a carriage return (control-m).  The text that
+was formerly a line following that newline is now invisible.  Strictly
+speaking, it is temporarily no longer a line at all, since only newlines
+can separate lines; it is now part of the previous line.
+
+   Selective display does not directly affect editing commands.  For
+example, `C-f' (`forward-char') moves point unhesitatingly into
+invisible text.  However, the replacement of newline characters with
+carriage return characters affects some editing commands.  For example,
+`next-line' skips invisible lines, since it searches only for newlines.
+Modes that use selective display can also define commands that take
+account of the newlines, or that make parts of the text visible or
+invisible.
+
+   When you write a selectively displayed buffer into a file, all the
+control-m's are output as newlines.  This means that when you next read
+in the file, it looks OK, with nothing invisible.  The selective display
+effect is seen only within XEmacs.
+
+ - Variable: selective-display
+     This buffer-local variable enables selective display.  This means
+     that lines, or portions of lines, may be made invisible.
+
+        * If the value of `selective-display' is `t', then any portion
+          of a line that follows a control-m is not displayed.
+
+        * If the value of `selective-display' is a positive integer,
+          then lines that start with more than that many columns of
+          indentation are not displayed.
+
+     When some portion of a buffer is invisible, the vertical movement
+     commands operate as if that portion did not exist, allowing a
+     single `next-line' command to skip any number of invisible lines.
+     However, character movement commands (such as `forward-char') do
+     not skip the invisible portion, and it is possible (if tricky) to
+     insert or delete text in an invisible portion.
+
+     In the examples below, we show the _display appearance_ of the
+     buffer `foo', which changes with the value of `selective-display'.
+     The _contents_ of the buffer do not change.
+
+          (setq selective-display nil)
+               => nil
+          
+          ---------- Buffer: foo ----------
+          1 on this column
+           2on this column
+            3n this column
+            3n this column
+           2on this column
+          1 on this column
+          ---------- Buffer: foo ----------
+          
+          (setq selective-display 2)
+               => 2
+          
+          ---------- Buffer: foo ----------
+          1 on this column
+           2on this column
+           2on this column
+          1 on this column
+          ---------- Buffer: foo ----------
+
+ - Variable: selective-display-ellipses
+     If this buffer-local variable is non-`nil', then XEmacs displays
+     `...' at the end of a line that is followed by invisible text.
+     This example is a continuation of the previous one.
+
+          (setq selective-display-ellipses t)
+               => t
+          
+          ---------- Buffer: foo ----------
+          1 on this column
+           2on this column ...
+           2on this column
+          1 on this column
+          ---------- Buffer: foo ----------
+
+     You can use a display table to substitute other text for the
+     ellipsis (`...').  *Note Display Tables::.
+
+\1f
+File: lispref.info,  Node: Overlay Arrow,  Next: Temporary Displays,  Prev: Selective Display,  Up: Display
+
+The Overlay Arrow
+=================
+
+The "overlay arrow" is useful for directing the user's attention to a
+particular line in a buffer.  For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed.
+
+ - Variable: overlay-arrow-string
+     This variable holds the string to display to call attention to a
+     particular line, or `nil' if the arrow feature is not in use.
+     Despite its name, the value of this variable can be either a string
+     or a glyph (*note Glyphs::).
+
+ - Variable: overlay-arrow-position
+     This variable holds a marker that indicates where to display the
+     overlay arrow.  It should point at the beginning of a line.  The
+     arrow text appears at the beginning of that line, overlaying any
+     text that would otherwise appear.  Since the arrow is usually
+     short, and the line usually begins with indentation, normally
+     nothing significant is overwritten.
+
+     The overlay string is displayed only in the buffer that this marker
+     points into.  Thus, only one buffer can have an overlay arrow at
+     any given time.
+
+   You can do the same job by creating an extent with a `begin-glyph'
+property.  *Note Extent Properties::.
+
+\1f
+File: lispref.info,  Node: Temporary Displays,  Next: Blinking,  Prev: Overlay Arrow,  Up: Display
+
+Temporary Displays
+==================
+
+Temporary displays are used by commands to put output into a buffer and
+then present it to the user for perusal rather than for editing.  Many
+of the help commands use this feature.
+
+ - Special Form: with-output-to-temp-buffer buffer-name forms...
+     This function executes FORMS while arranging to insert any output
+     they print into the buffer named BUFFER-NAME.  The buffer is then
+     shown in some window for viewing, displayed but not selected.
+
+     The string BUFFER-NAME specifies the temporary buffer, which need
+     not already exist.  The argument must be a string, not a buffer.
+     The buffer is erased initially (with no questions asked), and it is
+     marked as unmodified after `with-output-to-temp-buffer' exits.
+
+     `with-output-to-temp-buffer' binds `standard-output' to the
+     temporary buffer, then it evaluates the forms in FORMS.  Output
+     using the Lisp output functions within FORMS goes by default to
+     that buffer (but screen display and messages in the echo area,
+     although they are "output" in the general sense of the word, are
+     not affected).  *Note Output Functions::.
+
+     The value of the last form in FORMS is returned.
+
+          ---------- Buffer: foo ----------
+           This is the contents of foo.
+          ---------- Buffer: foo ----------
+          
+          (with-output-to-temp-buffer "foo"
+              (print 20)
+              (print standard-output))
+          => #<buffer foo>
+          
+          ---------- Buffer: foo ----------
+          20
+          
+          #<buffer foo>
+          
+          ---------- Buffer: foo ----------
+
+ - Variable: temp-buffer-show-function
+     If this variable is non-`nil', `with-output-to-temp-buffer' calls
+     it as a function to do the job of displaying a help buffer.  The
+     function gets one argument, which is the buffer it should display.
+
+     In Emacs versions 18 and earlier, this variable was called
+     `temp-buffer-show-hook'.
+
+ - Function: momentary-string-display string position &optional char
+          message
+     This function momentarily displays STRING in the current buffer at
+     POSITION.  It has no effect on the undo list or on the buffer's
+     modification status.
+
+     The momentary display remains until the next input event.  If the
+     next input event is CHAR, `momentary-string-display' ignores it
+     and returns.  Otherwise, that event remains buffered for
+     subsequent use as input.  Thus, typing CHAR will simply remove the
+     string from the display, while typing (say) `C-f' will remove the
+     string from the display and later (presumably) move point forward.
+     The argument CHAR is a space by default.
+
+     The return value of `momentary-string-display' is not meaningful.
+
+     You can do the same job in a more general way by creating an extent
+     with a begin-glyph property.  *Note Extent Properties::.
+
+     If MESSAGE is non-`nil', it is displayed in the echo area while
+     STRING is displayed in the buffer.  If it is `nil', a default
+     message says to type CHAR to continue.
+
+     In this example, point is initially located at the beginning of the
+     second line:
+
+          ---------- Buffer: foo ----------
+          This is the contents of foo.
+          -!-Second line.
+          ---------- Buffer: foo ----------
+          
+          (momentary-string-display
+            "**** Important Message! ****"
+            (point) ?\r
+            "Type RET when done reading")
+          => t
+          
+          ---------- Buffer: foo ----------
+          This is the contents of foo.
+          **** Important Message! ****Second line.
+          ---------- Buffer: foo ----------
+          
+          ---------- Echo Area ----------
+          Type RET when done reading
+          ---------- Echo Area ----------
+
+     This function works by actually changing the text in the buffer.
+     As a result, if you later undo in this buffer, you will see the
+     message come and go.
+
+\1f
+File: lispref.info,  Node: Blinking,  Next: Usual Display,  Prev: Temporary Displays,  Up: Display
+
+Blinking Parentheses
+====================
+
+This section describes the mechanism by which XEmacs shows a matching
+open parenthesis when the user inserts a close parenthesis.
+
+ - Variable: blink-paren-function
+     The value of this variable should be a function (of no arguments)
+     to be called whenever a character with close parenthesis syntax is
+     inserted.  The value of `blink-paren-function' may be `nil', in
+     which case nothing is done.
+
+          *Please note:* This variable was named `blink-paren-hook' in
+          older Emacs versions, but since it is not called with the
+          standard convention for hooks, it was renamed to
+          `blink-paren-function' in version 19.
+
+ - Variable: blink-matching-paren
+     If this variable is `nil', then `blink-matching-open' does nothing.
+
+ - Variable: blink-matching-paren-distance
+     This variable specifies the maximum distance to scan for a matching
+     parenthesis before giving up.
+
+ - Variable: blink-matching-paren-delay
+     This variable specifies the number of seconds for the cursor to
+     remain at the matching parenthesis.  A fraction of a second often
+     gives good results, but the default is 1, which works on all
+     systems.
+
+ - Command: blink-matching-open
+     This function is the default value of `blink-paren-function'.  It
+     assumes that point follows a character with close parenthesis
+     syntax and moves the cursor momentarily to the matching opening
+     character.  If that character is not already on the screen, it
+     displays the character's context in the echo area.  To avoid long
+     delays, this function does not search farther than
+     `blink-matching-paren-distance' characters.
+
+     Here is an example of calling this function explicitly.
+
+          (defun interactive-blink-matching-open ()
+            "Indicate momentarily the start of sexp before point."
+            (interactive)
+            (let ((blink-matching-paren-distance
+                   (buffer-size))
+                  (blink-matching-paren t))
+              (blink-matching-open)))
+
+\1f
+File: lispref.info,  Node: Usual Display,  Next: Display Tables,  Prev: Blinking,  Up: Display
+
+Usual Display Conventions
+=========================
+
+The usual display conventions define how to display each character
+code.  You can override these conventions by setting up a display table
+(*note Display Tables::).  Here are the usual display conventions:
+
+   * Character codes 32 through 126 map to glyph codes 32 through 126.
+     Normally this means they display as themselves.
+
+   * Character code 9 is a horizontal tab.  It displays as whitespace
+     up to a position determined by `tab-width'.
+
+   * Character code 10 is a newline.
+
+   * All other codes in the range 0 through 31, and code 127, display
+     in one of two ways according to the value of `ctl-arrow'.  If it is
+     non-`nil', these codes map to sequences of two glyphs, where the
+     first glyph is the ASCII code for `^'.  (A display table can
+     specify a glyph to use instead of `^'.)  Otherwise, these codes map
+     just like the codes in the range 128 to 255.
+
+   * Character codes 128 through 255 map to sequences of four glyphs,
+     where the first glyph is the ASCII code for `\', and the others are
+     digit characters representing the code in octal.  (A display table
+     can specify a glyph to use instead of `\'.)
+
+   The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+`nil'.  Thus, when you set up a display table, you need only specify
+the characters for which you want unusual behavior.
+
+   These variables affect the way certain characters are displayed on
+the screen.  Since they change the number of columns the characters
+occupy, they also affect the indentation functions.
+
+ - User Option: ctl-arrow
+     This buffer-local variable controls how control characters are
+     displayed.  If it is non-`nil', they are displayed as a caret
+     followed by the character: `^A'.  If it is `nil', they are
+     displayed as a backslash followed by three octal digits: `\001'.
+
+ - Variable: default-ctl-arrow
+     The value of this variable is the default value for `ctl-arrow' in
+     buffers that do not override it.  *Note Default Value::.
+
+ - User Option: tab-width
+     The value of this variable is the spacing between tab stops used
+     for displaying tab characters in Emacs buffers.  The default is 8.
+     Note that this feature is completely independent from the
+     user-settable tab stops used by the command `tab-to-tab-stop'.
+     *Note Indent Tabs::.
+
+\1f
+File: lispref.info,  Node: Display Tables,  Next: Beeping,  Prev: Usual Display,  Up: Display
+
+Display Tables
+==============
+
+You can use the "display table" feature to control how all 256 possible
+character codes display on the screen.  This is useful for displaying
+European languages that have letters not in the ASCII character set.
+
+   The display table maps each character code into a sequence of
+"runes", each rune being an image that takes up one character position
+on the screen.  You can also define how to display each rune on your
+terminal, using the "rune table".
+
+* Menu:
+
+* Display Table Format::       What a display table consists of.
+* Active Display Table::       How XEmacs selects a display table to use.
+* Character Descriptors::      Format of an individual element of a
+                                 display table.
+
+\1f
+File: lispref.info,  Node: Display Table Format,  Next: Active Display Table,  Up: Display Tables
+
+Display Table Format
+--------------------
+
+A display table is an array of 256 elements. (In FSF Emacs, a display
+table is 262 elements.  The six extra elements specify the truncation
+and continuation glyphs, etc.  This method is very kludgey, and in
+XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
+used.  *Note Truncation::.)
+
+ - Function: make-display-table
+     This creates and returns a display table.  The table initially has
+     `nil' in all elements.
+
+   The 256 elements correspond to character codes; the Nth element says
+how to display the character code N.  The value should be `nil', a
+string, a glyph, or a vector of strings and glyphs (*note Character
+Descriptors::).  If an element is `nil', it says to display that
+character according to the usual display conventions (*note Usual
+Display::).
+
+   If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long "line."
+
+   For example, here is how to construct a display table that mimics the
+effect of setting `ctl-arrow' to a non-`nil' value:
+
+     (setq disptab (make-display-table))
+     (let ((i 0))
+       (while (< i 32)
+         (or (= i ?\t) (= i ?\n)
+             (aset disptab i (concat "^" (char-to-string (+ i 64)))))
+         (setq i (1+ i)))
+       (aset disptab 127 "^?"))
+
+\1f
+File: lispref.info,  Node: Active Display Table,  Next: Character Descriptors,  Prev: Display Table Format,  Up: Display Tables
+
+Active Display Table
+--------------------
+
+The active display table is controlled by the variable
+`current-display-table'.  This is a specifier, which means that you can
+specify separate values for it in individual buffers, windows, frames,
+and devices, as well as a global value.  It also means that you cannot
+set this variable using `setq'; use `set-specifier' instead.  *Note
+Specifiers::. (FSF Emacs uses `window-display-table',
+`buffer-display-table', `standard-display-table', etc. to control the
+display table.  However, specifiers are a cleaner and more powerful way
+of doing the same thing.  FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection to a
+"glyph table" and such.  Note that "glyph" has a different meaning in
+XEmacs.)
+
+ - Variable: current-display-table
+     The display table currently in use.  This is a specifier.
+
+     Display tables are used to control how characters are displayed.
+     Each time that redisplay processes a character, it is looked up in
+     all the display tables that apply (obtained by calling
+     `specifier-instance' on `current-display-table' and any overriding
+     display tables specified in currently active faces).  The first
+     entry found that matches the character determines how the
+     character is displayed.  If there is no matching entry, the
+     default display method is used. (Non-control characters are
+     displayed as themselves and control characters are displayed
+     according to the buffer-local variable `ctl-arrow'.  Control
+     characters are further affected by `control-arrow-glyph' and
+     `octal-escape-glyph'.)
+
+     Each instantiator in this specifier and the display-table
+     specifiers in faces is a display table or a list of such tables.
+     If a list, each table will be searched in turn for an entry
+     matching a particular character.  Each display table is one of
+
+        * A vector, specifying values for characters starting at 0.
+
+        * A char table, either of type `char' or `generic'.
+
+        * A range table.
+
+     Each entry in a display table should be one of
+
+        * nil (this entry is ignored and the search continues).
+
+        * A character (use this character; if it happens to be the same
+          as the original character, default processing happens,
+          otherwise redisplay attempts to display this character
+          directly; #### At some point recursive display-table lookup
+          will be implemented).
+
+        * A string (display each character in the string directly; ####
+          At some point recursive display-table lookup will be
+          implemented).
+
+        * A glyph (display the glyph; #### At some point recursive
+          display-table lookup will be implemented when a string glyph
+          is being processed).
+
+        * A cons of the form (format "STRING") where STRING is a
+          printf-like spec used to process the character. ####
+          Unfortunately no formatting directives other than %% are
+          implemented.
+
+        * A vector (each element of the vector is processed recursively;
+          in such a case, nil elements in the vector are simply
+          ignored).
+
+          #### At some point in the near future, display tables are
+          likely to be expanded to include other features, such as
+          referencing characters in particular fonts and allowing the
+          character search to continue all the way up the chain of
+          specifier instantiators.  These features are necessary to
+          properly display Unicode characters.
+
+   Individual faces can also specify an overriding display table; this
+is set using `set-face-display-table'.  *Note Faces::.
+
+   If no display table can be determined for a particular window, then
+XEmacs uses the usual display conventions.  *Note Usual Display::.
+
+\1f
+File: lispref.info,  Node: Character Descriptors,  Prev: Active Display Table,  Up: Display Tables
+
+Character Descriptors
+---------------------
+
+Each element of the display-table vector describes how to display a
+particular character and is called a "character descriptor".  A
+character descriptor can be:
+
+a string
+     Display this particular string wherever the character is to be
+     displayed.
+
+a glyph
+     Display this particular glyph wherever the character is to be
+     displayed.
+
+a vector
+     The vector may contain strings and/or glyphs.  Display the
+     elements of the vector one after another wherever the character is
+     to be displayed.
+
+`nil'
+     Display according to the standard interpretation (*note Usual
+     Display::).
+
+\1f
+File: lispref.info,  Node: Beeping,  Prev: Display Tables,  Up: Display
+
+Beeping
+=======
+
+You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention.  Be conservative about how often you do
+this; frequent bells can become irritating.  Also be careful not to use
+beeping alone when signaling an error is appropriate.  (*Note Errors::.)
+
+ - Function: ding &optional dont-terminate sound device
+     This function beeps, or flashes the screen (see `visible-bell'
+     below).  It also terminates any keyboard macro currently executing
+     unless DONT-TERMINATE is non-`nil'.  If SOUND is specified, it
+     should be a symbol specifying which sound to make.  This sound
+     will be played if `visible-bell' is `nil'. (This only works if
+     sound support was compiled into the executable and you are running
+     on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+     PC. Otherwise you just get a beep.) The optional third argument
+     specifies what device to make the sound on, and defaults to the
+     selected device.
+
+ - Function: beep &optional dont-terminate sound device
+     This is a synonym for `ding'.
+
+ - User Option: visible-bell
+     This variable determines whether XEmacs should flash the screen to
+     represent a bell.  Non-`nil' means yes, `nil' means no.  On TTY
+     devices, this is effective only if the Termcap entry for the
+     terminal type has the visible bell flag (`vb') set.
+
+ - Variable: sound-alist
+     This variable holds an alist associating names with sounds.  When
+     `beep' or `ding' is called with one of the name symbols, the
+     associated sound will be generated instead of the standard beep.
+
+     Each element of `sound-alist' is a list describing a sound.  The
+     first element of the list is the name of the sound being defined.
+     Subsequent elements of the list are alternating keyword/value
+     pairs:
+
+    `sound'
+          A string of raw sound data, or the name of another sound to
+          play.  The symbol `t' here means use the default X beep.
+
+    `volume'
+          An integer from 0-100, defaulting to `bell-volume'.
+
+    `pitch'
+          If using the default X beep, the pitch (Hz) to generate.
+
+    `duration'
+          If using the default X beep, the duration (milliseconds).
+
+     For compatibility, elements of `sound-alist' may also be:
+
+        * `( sound-name . <sound> )'
+
+        * `( sound-name <volume> <sound> )'
+
+     You should probably add things to this list by calling the function
+     `load-sound-file'.
+
+     Caveats:
+
+        - You can only play audio data if running on the console screen
+          of a Sun SparcStation, SGI, or HP9000s700.
+
+        - The pitch, duration, and volume options are available
+          everywhere, but many X servers ignore the `pitch' option.
+
+     The following beep-types are used by XEmacs itself:
+
+    `auto-save-error'
+          when an auto-save does not succeed
+
+    `command-error'
+          when the XEmacs command loop catches an error
+
+    `undefined-key'
+          when you type a key that is undefined
+
+    `undefined-click'
+          when you use an undefined mouse-click combination
+
+    `no-completion'
+          during completing-read
+
+    `y-or-n-p'
+          when you type something other than 'y' or 'n'
+
+    `yes-or-no-p'
+          when you type something other than 'yes' or 'no'
+
+    `default'
+          used when nothing else is appropriate.
+
+     Other lisp packages may use other beep types, but these are the
+     ones that the C kernel of XEmacs uses.
+
+ - User Option: bell-volume
+     This variable specifies the default volume for sounds, from 0 to
+     100.
+
+ - Command: load-default-sounds
+     This function loads and installs some sound files as beep-types.
+
+ - Command: load-sound-file filename sound-name &optional volume
+     This function reads in an audio file and adds it to `sound-alist'.
+     The sound file must be in the Sun/NeXT U-LAW format.  SOUND-NAME
+     should be a symbol, specifying the name of the sound.  If VOLUME
+     is specified, the sound will be played at that volume; otherwise,
+     the value of `bell-volume' will be used.
+
+ - Function: play-sound sound &optional volume device
+     This function plays sound SOUND, which should be a symbol
+     mentioned in `sound-alist'.  If VOLUME is specified, it overrides
+     the value (if any) specified in `sound-alist'.  DEVICE specifies
+     the device to play the sound on, and defaults to the selected
+     device.
+
+ - Command: play-sound-file file &optional volume device
+     This function plays the named sound file at volume VOLUME, which
+     defaults to `bell-volume'.  DEVICE specifies the device to play
+     the sound on, and defaults to the selected device.
+
+\1f
+File: lispref.info,  Node: Hash Tables,  Next: Range Tables,  Prev: Display,  Up: Top
+
+Hash Tables
+***********
+
+ - Function: hash-table-p object
+     This function returns `t' if OBJECT is a hash table, else `nil'.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Introduction to Hash Tables,  Next: Working With Hash Tables,  Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values".  A key/value pair is sometimes called an "entry" in
+the hash table.  There are many ways other than hash tables of
+implementing the same sort of mapping, e.g.  association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping.  Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+   Internally, hash tables are hashed using the "linear probing" hash
+table implementation method.  This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found.  To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search.  This method is used in preference to
+double hashing because of changes in recent hardware.  The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+   When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+   Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table.  But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower.  Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection.  If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+   Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table.  For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0.  For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+   Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+     #s(hash-table size 20 data (foo 1 bar 2))
+
+   The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+          `rehash-threshold' `weakness'
+     This function returns a new empty hash table object.
+
+     Keyword `:test' can be `eq', `eql' (default) or `equal'.
+     Comparison between keys is done using this function.  If speed is
+     important, consider using `eq'.  When storing strings in the hash
+     table, you will likely need to use `equal'.
+
+     Keyword `:size' specifies the number of keys likely to be inserted.
+     This number of entries can be inserted without enlarging the hash
+     table.
+
+     Keyword `:rehash-size' must be a float greater than 1.0, and
+     specifies the factor by which to increase the size of the hash
+     table when enlarging.
+
+     Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+     and specifies the load factor of the hash table which triggers
+     enlarging.
+
+     Non-standard keyword `:weakness' can be `nil' (default), `t',
+     `key-and-value', `key', `value' or `key-or-value'.  `t' is an
+     alias for `key-and-value'.
+
+     A key-and-value-weak hash table, also known as a fully-weak or
+     simply as a weak hash table, is one whose pointers do not count as
+     GC referents: for any key-value pair in the hash table, if the only
+     remaining pointer to either the key or the value is in a weak hash
+     table, then the pair will be removed from the hash table, and the
+     key and value collected.  A non-weak hash table (or any other
+     pointer) would prevent the object from being collected.
+
+     A key-weak hash table is similar to a fully-weak hash table except
+     that a key-value pair will be removed only if the key remains
+     unmarked outside of weak hash tables.  The pair will remain in the
+     hash table if the key is pointed to by something other than a weak
+     hash table, even if the value is not.
+
+     A value-weak hash table is similar to a fully-weak hash table
+     except that a key-value pair will be removed only if the value
+     remains unmarked outside of weak hash tables.  The pair will
+     remain in the hash table if the value is pointed to by something
+     other than a weak hash table, even if the key is not.
+
+     A key-or-value-weak hash table is similar to a fully-weak hash
+     table except that a key-value pair will be removed only if the
+     value and the key remain unmarked outside of weak hash tables.
+     The pair will remain in the hash table if the value or key are
+     pointed to by something other than a weak hash table, even if the
+     other is not.
+
+ - Function: copy-hash-table hash-table
+     This function returns a new hash table which contains the same
+     keys and values as HASH-TABLE.  The keys and values will not
+     themselves be copied.
+
+ - Function: hash-table-count hash-table
+     This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test hash-table
+     This function returns the test function of HASH-TABLE.  This can
+     be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size hash-table
+     This function returns the current number of slots in HASH-TABLE,
+     whether occupied or not.
+
+ - Function: hash-table-rehash-size hash-table
+     This function returns the current rehash size of HASH-TABLE.  This
+     is a float greater than 1.0; the factor by which HASH-TABLE is
+     enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold hash-table
+     This function returns the current rehash threshold of HASH-TABLE.
+     This is a float between 0.0 and 1.0; the maximum "load factor" of
+     HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness hash-table
+     This function returns the weakness of HASH-TABLE.  This can be one
+     of `nil', `t', `key' or `value'.
+
+\1f
+File: lispref.info,  Node: Working With Hash Tables,  Next: Weak Hash Tables,  Prev: Introduction to Hash Tables,  Up: Hash Tables
+
+Working With Hash Tables
+========================
+
+ - Function: puthash key value hash-table
+     This function hashes KEY to VALUE in HASH-TABLE.
+
+ - Function: gethash key hash-table &optional default
+     This function finds the hash value for KEY in HASH-TABLE.  If
+     there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+     (which in turn defaults to `nil').
+
+ - Function: remhash key hash-table
+     This function removes the entry for KEY from HASH-TABLE.  Does
+     nothing if there is no entry for KEY in HASH-TABLE.
+
+ - Function: clrhash hash-table
+     This function removes all entries from HASH-TABLE, leaving it
+     empty.
+
+ - Function: maphash function hash-table
+     This function maps FUNCTION over entries in HASH-TABLE, calling it
+     with two args, each key and value in the hash table.
+
+     FUNCTION may not modify HASH-TABLE, with the one exception that
+     FUNCTION may remhash or puthash the entry currently being
+     processed by FUNCTION.
+
+\1f
+File: lispref.info,  Node: Weak Hash Tables,  Prev: Working With Hash Tables,  Up: Hash Tables
+
+Weak Hash Tables
+================
+
+A "weak hash table" is a special variety of hash table whose elements
+do not count as GC referents.  For any key-value pair in such a hash
+table, if either the key or value (or in some cases, if one particular
+one of the two) has no references to it outside of weak hash tables
+(and similar structures such as weak lists), the pair will be removed
+from the table, and the key and value collected.  A non-weak hash table
+(or any other pointer) would prevent the objects from being collected.
+
+   Weak hash tables are useful for keeping track of information in a
+non-obtrusive way, for example to implement caching.  If the cache
+contains objects such as buffers, markers, image instances, etc. that
+will eventually disappear and get garbage-collected, using a weak hash
+table ensures that these objects are collected normally rather than
+remaining around forever, long past their actual period of use.
+(Otherwise, you'd have to explicitly map over the hash table every so
+often and remove unnecessary elements.)
+
+   There are four types of weak hash tables:
+
+key-and-value-weak hash tables
+     In these hash tables, also known as fully weak or simply as weak
+     hash tables, a pair disappears if either the key or the value is
+     unreferenced outside of the table.
+
+key-weak hash tables
+     In these hash tables, a pair disappears if the key is unreferenced
+     outside of the table, regardless of how the value is referenced.
+
+value-weak hash tables
+     In these hash tables, a pair disappears if the value is
+     unreferenced outside of the table, regardless of how the key is
+     referenced.
+
+key-or-value-weak hash tables
+     In these hash tables, a pair disappears if both the key and the
+     value are unreferenced outside of the table.
+
+   Also see *Note Weak Lists::.
+
+   Weak hash tables are created by specifying the `:weakness' keyword to
+`make-hash-table'.
+
+\1f
+File: lispref.info,  Node: Range Tables,  Next: Databases,  Prev: Hash Tables,  Up: Top
+
+Range Tables
+************
+
+A range table is a table that efficiently associated values with ranges
+of integers.
+
+   Note that range tables have a read syntax, like this:
+
+     #s(range-table data ((-3 2) foo (5 20) bar))
+
+   This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
+
+ - Function: range-table-p object
+     Return non-`nil' if OBJECT is a range table.
+
+* Menu:
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+                                 integers to values.
+* Working With Range Tables::    Range table functions.
+
+\1f
+File: lispref.info,  Node: Introduction to Range Tables,  Next: Working With Range Tables,  Up: Range Tables
+
+Introduction to Range Tables
+============================
+
+ - Function: make-range-table
+     Make a new, empty range table.
+
+ - Function: copy-range-table range-table
+     This function returns a new range table which contains the same
+     values for the same ranges as RANGE-TABLE.  The values will not
+     themselves be copied.
+
+\1f
+File: lispref.info,  Node: Working With Range Tables,  Prev: Introduction to Range Tables,  Up: Range Tables
+
+Working With Range Tables
+=========================
+
+ - Function: get-range-table pos range-table &optional default
+     This function finds value for position POS in RANGE-TABLE.  If
+     there is no corresponding value, return DEFAULT (defaults to
+     `nil').
+
+ - Function: put-range-table start end value range-table
+     This function sets the value for range (START, END) to be VALUE in
+     RANGE-TABLE.
+
+ - Function: remove-range-table start end range-table
+     This function removes the value for range (START, END) in
+     RANGE-TABLE.
+
+ - Function: clear-range-table range-table
+     This function flushes RANGE-TABLE.
+
+ - Function: map-range-table function range-table
+     This function maps FUNCTION over entries in RANGE-TABLE, calling
+     it with three args, the beginning and end of the range and the
+     corresponding value.
+
+\1f
+File: lispref.info,  Node: Databases,  Next: Processes,  Prev: Range Tables,  Up: Top
+
+Databases
+*********
+
+ - Function: databasep object
+     This function returns non-`nil' if OBJECT is a database.
+
+* Menu:
+
+* Connecting to a Database::
+* Working With a Database::
+* Other Database Functions::
+
+\1f
+File: lispref.info,  Node: Connecting to a Database,  Next: Working With a Database,  Up: Databases
+
+Connecting to a Database
+========================
+
+ - Function: open-database file &optional type subtype access mode
+     This function opens database FILE, using database method TYPE and
+     SUBTYPE, with access rights ACCESS and permissions MODE.  ACCESS
+     can be any combination of `r' `w' and `+', for read, write, and
+     creation flags.
+
+     TYPE can have the value `'dbm' or `'berkeley-db' to select the
+     type of database file to use.  (Note:  XEmacs may not support both
+     of these types.)
+
+     For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
+     `nil'.
+
+     For a TYPE of `'berkeley-db', the following subtypes are
+     available:  `'hash', `'btree', and `'recno'.  See the manpages for
+     the Berkeley DB functions for more information about these types.
+
+ - Function: close-database database
+     This function closes database DATABASE.
+
+ - Function: database-live-p object
+     This function returns `t' if OBJECT is an active database, else
+     `nil'.
+
+\1f
+File: lispref.info,  Node: Working With a Database,  Next: Other Database Functions,  Prev: Connecting to a Database,  Up: Databases
+
+Working With a Database
+=======================
+
+ - Function: get-database key database &optional default
+     This function finds the value for KEY in DATABASE.  If there is no
+     corresponding value, DEFAULT is returned (`nil' if DEFAULT is
+     omitted).
+
+ - Function: map-database function database
+     This function maps FUNCTION over entries in DATABASE, calling it
+     with two args, each key and value in the database.
+
+ - Function: put-database key value database &optional replace
+     This function stores KEY and VALUE in DATABASE.  If optional
+     fourth arg REPLACE is non-`nil', replace any existing entry in the
+     database.
+
+ - Function: remove-database key database
+     This function removes KEY from DATABASE.
+
+\1f
+File: lispref.info,  Node: Other Database Functions,  Prev: Working With a Database,  Up: Databases
+
+Other Database Functions
+========================
+
+ - Function: database-file-name database
+     This function returns the filename associated with DATABASE.
+
+ - Function: database-last-error &optional database
+     This function returns the last error associated with DATABASE.
+
+ - Function: database-subtype database
+     This function returns the subtype of DATABASE, if any.
+
+ - Function: database-type database
+     This function returns the type of DATABASE.
+
+\1f
+File: lispref.info,  Node: Processes,  Next: System Interface,  Prev: Databases,  Up: Top
+
+Processes
+*********
+
+In the terminology of operating systems, a "process" is a space in
+which a program can execute.  XEmacs runs in a process.  XEmacs Lisp
+programs can invoke other programs in processes of their own.  These are
+called "subprocesses" or "child processes" of the XEmacs process, which
+is their "parent process".
+
+   A subprocess of XEmacs may be "synchronous" or "asynchronous",
+depending on how it is created.  When you create a synchronous
+subprocess, the Lisp program waits for the subprocess to terminate
+before continuing execution.  When you create an asynchronous
+subprocess, it can run in parallel with the Lisp program.  This kind of
+subprocess is represented within XEmacs by a Lisp object which is also
+called a "process".  Lisp programs can use this object to communicate
+with the subprocess or to control it.  For example, you can send
+signals, obtain status information, receive output from the process, or
+send input to it.
+
+ - Function: processp object
+     This function returns `t' if OBJECT is a process, `nil' otherwise.
+
+* Menu:
+
+* Subprocess Creation::      Functions that start subprocesses.
+* Synchronous Processes::    Details of using synchronous subprocesses.
+* MS-DOS Subprocesses::      On MS-DOS, you must indicate text vs binary
+                                for data sent to and from a subprocess.
+* 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.
+* Process Window Size::      Changing the logical window size of a process.
+* Transaction Queues::      Transaction-based communication with subprocesses.
+* Network::                  Opening network connections.
+
+\1f
+File: lispref.info,  Node: Subprocess Creation,  Next: Synchronous Processes,  Up: Processes
+
+Functions that Create Subprocesses
+==================================
+
+There are three functions that create a new subprocess in which to run
+a program.  One of them, `start-process', creates an asynchronous
+process and returns a process object (*note Asynchronous Processes::).
+The other two, `call-process' and `call-process-region', create a
+synchronous process and do not return a process object (*note
+Synchronous Processes::).
+
+   Synchronous and asynchronous processes are explained in the following
+sections.  Since the three functions are all called in a similar
+fashion, their common arguments are described here.
+
+   In all cases, the function's PROGRAM argument specifies the program
+to be run.  An error is signaled if the file is not found or cannot be
+executed.  If the file name is relative, the variable `exec-path'
+contains a list of directories to search.  Emacs initializes
+`exec-path' when it starts up, based on the value of the environment
+variable `PATH'.  The standard file name constructs, `~', `.', and
+`..', are interpreted as usual in `exec-path', but environment variable
+substitutions (`$HOME', etc.) are not recognized; use
+`substitute-in-file-name' to perform them (*note File Name Expansion::).
+
+   Each of the subprocess-creating functions has a BUFFER-OR-NAME
+argument which specifies where the standard output from the program will
+go.  If BUFFER-OR-NAME is `nil', that says to discard the output unless
+a filter function handles it.  (*Note Filter Functions::, and *Note
+Read and Print::.)  Normally, you should avoid having multiple
+processes send output to the same buffer because their output would be
+intermixed randomly.
+
+   All three of the subprocess-creating functions have a `&rest'
+argument, ARGS.  The ARGS must all be strings, and they are supplied to
+PROGRAM as separate command line arguments.  Wildcard characters and
+other shell constructs are not allowed in these strings, since they are
+passed directly to the specified program.
+
+   *Please note:* The argument PROGRAM contains only the name of the
+program; it may not contain any command-line arguments.  You must use
+ARGS to provide those.
+
+   If you want to use features of the shell, then invoke the shell
+directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
+"COMMAND LINE...".
+
+   The subprocess gets its current directory from the value of
+`default-directory' (*note File Name Expansion::).
+
+   The subprocess inherits its environment from XEmacs; but you can
+specify overrides for it with `process-environment'.  *Note System
+Environment::.
+
+ - Variable: exec-directory
+     The value of this variable is the name of a directory (a string)
+     that contains programs that come with XEmacs, that are intended
+     for XEmacs to invoke.  The program `wakeup' is an example of such
+     a program; the `display-time' command uses it to get a reminder
+     once per minute.
+
+ - User Option: exec-path
+     The value of this variable is a list of directories to search for
+     programs to run in subprocesses.  Each element is either the name
+     of a directory (i.e., a string), or `nil', which stands for the
+     default directory (which is the value of `default-directory').
+
+     The value of `exec-path' is used by `call-process' and
+     `start-process' when the PROGRAM argument is not an absolute file
+     name.
+
+\1f
+File: lispref.info,  Node: Synchronous Processes,  Next: MS-DOS Subprocesses,  Prev: Subprocess Creation,  Up: Processes
+
+Creating a Synchronous Process
+==============================
+
+After a "synchronous process" is created, XEmacs waits for the process
+to terminate before continuing.  Starting Dired is an example of this:
+it runs `ls' in a synchronous process, then modifies the output
+slightly.  Because the process is synchronous, the entire directory
+listing arrives in the buffer before XEmacs tries to do anything with
+it.
+
+   While Emacs waits for the synchronous subprocess to terminate, the
+user can quit by typing `C-g'.  The first `C-g' tries to kill the
+subprocess with a `SIGINT' signal; but it waits until the subprocess
+actually terminates before quitting.  If during that time the user
+types another `C-g', that kills the subprocess instantly with `SIGKILL'
+and quits immediately.  *Note Quitting::.
+
+   The synchronous subprocess functions returned `nil' in version 18.
+In version 19, they return an indication of how the process terminated.
+
+ - Function: call-process program &optional infile destination display
+          &rest args
+     This function calls PROGRAM in a separate process and waits for it
+     to finish.
+
+     The standard input for the process comes from file INFILE if
+     INFILE is not `nil' and from `/dev/null' otherwise.  The argument
+     DESTINATION says where to put the process output.  Here are the
+     possibilities:
+
+    a buffer
+          Insert the output in that buffer, before point.  This
+          includes both the standard output stream and the standard
+          error stream of the process.
+
+    a string
+          Find or create a buffer with that name, then insert the
+          output in that buffer, before point.
+
+    `t'
+          Insert the output in the current buffer, before point.
+
+    `nil'
+          Discard the output.
+
+    0
+          Discard the output, and return immediately without waiting
+          for the subprocess to finish.
+
+          In this case, the process is not truly synchronous, since it
+          can run in parallel with Emacs; but you can think of it as
+          synchronous in that Emacs is essentially finished with the
+          subprocess as soon as this function returns.
+
+    (REAL-DESTINATION ERROR-DESTINATION)
+          Keep the standard output stream separate from the standard
+          error stream; deal with the ordinary output as specified by
+          REAL-DESTINATION, and dispose of the error output according
+          to ERROR-DESTINATION.  The value `nil' means discard it, `t'
+          means mix it with the ordinary output, and a string specifies
+          a file name to redirect error output into.
+
+          You can't directly specify a buffer to put the error output
+          in; that is too difficult to implement.  But you can achieve
+          this result by sending the error output to a temporary file
+          and then inserting the file into a buffer.
+
+     If DISPLAY is non-`nil', then `call-process' redisplays the buffer
+     as output is inserted.  Otherwise the function does no redisplay,
+     and the results become visible on the screen only when XEmacs
+     redisplays that buffer in the normal course of events.
+
+     The remaining arguments, ARGS, are strings that specify command
+     line arguments for the program.
+
+     The value returned by `call-process' (unless you told it not to
+     wait) indicates the reason for process termination.  A number
+     gives the exit status of the subprocess; 0 means success, and any
+     other value means failure.  If the process terminated with a
+     signal, `call-process' returns a string describing the signal.
+
+     In the examples below, the buffer `foo' is current.
+
+          (call-process "pwd" nil t)
+               => nil
+          
+          ---------- Buffer: foo ----------
+          /usr/user/lewis/manual
+          ---------- Buffer: foo ----------
+          
+          (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
+               => nil
+          
+          ---------- Buffer: bar ----------
+          lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+          
+          ---------- Buffer: bar ----------
+
+     The `insert-directory' function contains a good example of the use
+     of `call-process':
+
+          (call-process insert-directory-program nil t nil switches
+                        (if full-directory-p
+                            (concat (file-name-as-directory file) ".")
+                          file))
+
+ - Function: call-process-region start end program &optional deletep
+          destination displayp &rest args
+     This function sends the text between START to END as standard
+     input to a process running PROGRAM.  It deletes the text sent if
+     DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
+     the output in the current buffer.
+
+     The arguments DESTINATION and DISPLAYP control what to do with the
+     output from the subprocess, and whether to update the display as
+     it comes in.  For details, see the description of `call-process',
+     above.  If DESTINATION is the integer 0, `call-process-region'
+     discards the output and returns `nil' immediately, without waiting
+     for the subprocess to finish.
+
+     The remaining arguments, ARGS, are strings that specify command
+     line arguments for the program.
+
+     The return value of `call-process-region' is just like that of
+     `call-process': `nil' if you told it to return without waiting;
+     otherwise, a number or string which indicates how the subprocess
+     terminated.
+
+     In the following example, we use `call-process-region' to run the
+     `cat' utility, with standard input being the first five characters
+     in buffer `foo' (the word `input').  `cat' copies its standard
+     input into its standard output.  Since the argument DESTINATION is
+     `t', this output is inserted in the current buffer.
+
+          ---------- Buffer: foo ----------
+          input-!-
+          ---------- Buffer: foo ----------
+          
+          (call-process-region 1 6 "cat" nil t)
+               => nil
+          
+          ---------- Buffer: foo ----------
+          inputinput-!-
+          ---------- Buffer: foo ----------
+
+     The `shell-command-on-region' command uses `call-process-region'
+     like this:
+
+          (call-process-region
+           start end
+           shell-file-name      ; Name of program.
+           nil                  ; Do not delete region.
+           buffer               ; Send output to `buffer'.
+           nil                  ; No redisplay during output.
+           "-c" command)        ; Arguments for the shell.
+
+\1f
+File: lispref.info,  Node: MS-DOS Subprocesses,  Next: Asynchronous Processes,  Prev: Synchronous Processes,  Up: Processes
+
+MS-DOS Subprocesses
+===================
+
+On MS-DOS, you must indicate whether the data going to and from a
+synchronous subprocess are text or binary.  Text data requires
+translation between the end-of-line convention used within Emacs (a
+single newline character) and the convention used outside Emacs (the
+two-character sequence, CRLF).
+
+   The variable `binary-process-input' applies to input sent to the
+subprocess, and `binary-process-output' applies to output received from
+it.  A non-`nil' value means the data is non-text; `nil' means the data
+is text, and calls for conversion.
+
+ - Variable: binary-process-input
+     If this variable is `nil', convert newlines to CRLF sequences in
+     the input to a synchronous subprocess.
+
+ - Variable: binary-process-output
+     If this variable is `nil', convert CRLF sequences to newlines in
+     the output from a synchronous subprocess.
+
+   *Note Files and MS-DOS::, for related information.
+
+\1f
+File: lispref.info,  Node: Asynchronous Processes,  Next: Deleting Processes,  Prev: MS-DOS Subprocesses,  Up: Processes
+
+Creating an Asynchronous Process
+================================
+
+After an "asynchronous process" is created, Emacs and the Lisp program
+both continue running immediately.  The process may thereafter run in
+parallel with Emacs, and the two may communicate with each other using
+the functions described in following sections.  Here we describe how to
+create an asynchronous process with `start-process'.
+
+ - Function: start-process name buffer-or-name program &rest args
+     This function creates a new asynchronous subprocess and starts the
+     program PROGRAM running in it.  It returns a process object that
+     stands for the new subprocess in Lisp.  The argument NAME
+     specifies the name for the process object; if a process with this
+     name already exists, then NAME is modified (by adding `<1>', etc.)
+     to be unique.  The buffer BUFFER-OR-NAME is the buffer to
+     associate with the process.
+
+     The remaining arguments, ARGS, are strings that specify command
+     line arguments for the program.
+
+     In the example below, the first process is started and runs
+     (rather, sleeps) for 100 seconds.  Meanwhile, the second process
+     is started, and given the name `my-process<1>' for the sake of
+     uniqueness.  It inserts the directory listing at the end of the
+     buffer `foo', before the first process finishes.  Then it
+     finishes, and a message to that effect is inserted in the buffer.
+     Much later, the first process finishes, and another message is
+     inserted in the buffer for it.
+
+          (start-process "my-process" "foo" "sleep" "100")
+               => #<process my-process>
+          
+          (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+               => #<process my-process<1>>
+          
+          ---------- Buffer: foo ----------
+          total 2
+          lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
+          -rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon
+          
+          Process my-process<1> finished
+          
+          Process my-process finished
+          ---------- Buffer: foo ----------
+
+ - Function: start-process-shell-command name buffer-or-name command
+          &rest command-args
+     This function is like `start-process' except that it uses a shell
+     to execute the specified command.  The argument COMMAND is a shell
+     command name, and COMMAND-ARGS are the arguments for the shell
+     command.
+
+ - Variable: process-connection-type
+     This variable controls the type of device used to communicate with
+     asynchronous subprocesses.  If it is non-`nil', then PTYs are
+     used, when available.  Otherwise, pipes are used.
+
+     PTYs are usually preferable for processes visible to the user, as
+     in Shell mode, because they allow job control (`C-c', `C-z', etc.)
+     to work between the process and its children whereas pipes do not.
+     For subprocesses used for internal purposes by programs, it is
+     often better to use a pipe, because they are more efficient.  In
+     addition, the total number of PTYs is limited on many systems and
+     it is good not to waste them.  A rule of thumb is to use ptys for
+     processes the user interacts with directly, and pipes for
+     processes that are hidden from the user.
+
+     The value `process-connection-type' is used when `start-process'
+     is called.  So you can specify how to communicate with one
+     subprocess by binding the variable around the call to
+     `start-process'.
+
+          (let ((process-connection-type nil))  ; Use a pipe.
+            (start-process ...))
+
+     To determine whether a given subprocess actually got a pipe or a
+     PTY, use the function `process-tty-name' (*note Process
+     Information::).
+
+   Lisp functions that manipulate processes usually accept a PROCESS
+argument.  Besides using an actual process object for this argument, you
+can use a process name, a buffer object, the name of a buffer, or
+`nil'.  Specifying a buffer or buffer name for the PROCESS argument
+means use the process associated with the buffer (or the most recent
+one, if there is more than one).  `nil' means use the process
+associated with the current buffer.  *Note Process Information::.
+*Note Process Buffers::.
+
+\1f
+File: lispref.info,  Node: Deleting Processes,  Next: Process Information,  Prev: Asynchronous Processes,  Up: Processes
+
+Deleting Processes
+==================
+
+"Deleting a process" disconnects XEmacs immediately from the
+subprocess, and removes it from the list of active processes.  It sends
+a signal to the subprocess to make the subprocess terminate, but this is
+not guaranteed to happen immediately.  The process object itself
+continues to exist as long as other Lisp objects point to it.
+
+   You can delete a process explicitly at any time.  Processes are
+deleted automatically after they terminate, but not necessarily right
+away.  If you delete a terminated process explicitly before it is
+deleted automatically, no harm results.
+
+ - Variable: delete-exited-processes
+     This variable controls automatic deletion of processes that have
+     terminated (due to calling `exit' or to a signal).  If it is
+     `nil', then they continue to exist until the user runs
+     `list-processes'.  Otherwise, they are deleted immediately after
+     they exit.
+
+ - Function: delete-process name
+     This function deletes the process associated with NAME, killing it
+     with a `SIGHUP' signal.  The argument NAME may be a process, the
+     name of a process, a buffer, or the name of a buffer.
+
+          (delete-process "*shell*")
+               => nil
+
+ - Function: process-kill-without-query process &optional
+          require-query-p
+     This function declares that XEmacs need not query the user if
+     PROCESS is still running when XEmacs is exited.  The process will
+     be deleted silently.  If REQUIRE-QUERY-P is non-`nil', then XEmacs
+     _will_ query the user (this is the default).  The return value is
+     `t' if a query was formerly required, and `nil' otherwise.
+
+          (process-kill-without-query (get-process "shell"))
+               => t
+
+\1f
+File: lispref.info,  Node: Process Information,  Next: Input to Processes,  Prev: Deleting Processes,  Up: Processes
+
+Process Information
+===================
+
+Several functions return information about processes.  `list-processes'
+is provided for interactive use.
+
+ - Command: list-processes
+     This command displays a listing of all living processes.  In
+     addition, it finally deletes any process whose status was `Exited'
+     or `Signaled'.  It returns `nil'.
+
+ - Function: process-list
+     This function returns a list of all processes that have not been
+     deleted.
+
+          (process-list)
+               => (#<process display-time> #<process shell>)
+
+ - Function: get-process process-name
+     This function returns the process named PROCESS-NAME.  If
+     PROCESS-NAME is a string and there is no process with that name,
+     the value is `nil'.  If PROCESS-NAME is actually a process, it is
+     returned as given.  (That is not very useful, so the argument is
+     usually a name.) For example:
+
+          (get-process "shell")
+               => #<process shell>
+
+ - Function: process-command process
+     This function returns the command that was executed to start
+     PROCESS.  This is a list of strings, the first string being the
+     program executed and the rest of the strings being the arguments
+     that were given to the program.
+
+          (process-command (get-process "shell"))
+               => ("/bin/csh" "-i")
+
+ - Function: process-id process
+     This function returns the PID of PROCESS.  This is an integer that
+     distinguishes the process PROCESS from all other processes running
+     on the same computer at the current time.  The PID of a process is
+     chosen by the operating system kernel when the process is started
+     and remains constant as long as the process exists.
+
+ - Function: process-name process
+     This function returns the name of PROCESS.
+
+ - Function: process-status process
+     This function returns the status of PROCESS as a symbol.  The
+     argument PROCESS must be a process, a buffer, a process name
+     (string) or a buffer name (string).
+
+     The possible values for an actual subprocess are:
+
+    `run'
+          for a process that is running.
+
+    `stop'
+          for a process that is stopped but continuable.
+
+    `exit'
+          for a process that has exited.
+
+    `signal'
+          for a process that has received a fatal signal.
+
+    `open'
+          for a network connection that is open.
+
+    `closed'
+          for a network connection that is closed.  Once a connection
+          is closed, you cannot reopen it, though you might be able to
+          open a new connection to the same place.
+
+    `nil'
+          if PROCESS does not identify an existing process.
+
+          (process-status "shell")
+               => run
+          (process-status (get-buffer "*shell*"))
+               => run
+          x
+               => #<process xx<1>>
+          (process-status x)
+               => exit
+
+     For a network connection, `process-status' returns one of the
+     symbols `open' or `closed'.  The latter means that the other side
+     closed the connection, or XEmacs did `delete-process'.
+
+     In earlier Emacs versions (prior to version 19), the status of a
+     network connection was `run' if open, and `exit' if closed.
+
+ - Function: process-kill-without-query-p process
+     This function returns whether PROCESS will be killed without
+     querying the user, if it is running when XEmacs is exited.  The
+     default value is `nil'.
+
+ - Function: process-exit-status process
+     This function returns the exit status of PROCESS or the signal
+     number that killed it.  (Use the result of `process-status' to
+     determine which of those it is.)  If PROCESS has not yet
+     terminated, the value is 0.
+
+ - Function: process-tty-name process
+     This function returns the terminal name that PROCESS is using for
+     its communication with Emacs--or `nil' if it is using pipes
+     instead of a terminal (see `process-connection-type' in *Note
+     Asynchronous Processes::).
+
+\1f
+File: lispref.info,  Node: Input to Processes,  Next: Signals to Processes,  Prev: Process Information,  Up: Processes
+
+Sending Input to Processes
+==========================
+
+Asynchronous subprocesses receive input when it is sent to them by
+XEmacs, which is done with the functions in this section.  You must
+specify the process to send input to, and the input data to send.  The
+data appears on the "standard input" of the subprocess.
+
+   Some operating systems have limited space for buffered input in a
+PTY.  On these systems, XEmacs sends long input in chunks, with EOF
+characters added amidst the other characters, to force the operating
+system to periodically drain the input buffer.  For most programs,
+these EOFs do no harm.
+
+ - Function: process-send-string process string &optional start end
+     This function sends PROCESS the contents of STRING as standard
+     input.
+
+     The argument PROCESS may be a process or the name of a process, or
+     a buffer or the name of a buffer, in which case the buffer's
+     process is used.  If it is `nil', the current buffer's process is
+     used.
+
+     Optional arguments START and END specify part of STRING; see
+     `substring'.
+
+     The function returns `nil'.
+
+          (process-send-string "shell<1>" "ls\n")
+               => nil

           
           

-          (eq x y)
+          
+          ---------- Buffer: *shell* ----------
+          ...
+          introduction.texi               syntax-tables.texi~
+          introduction.texi~              text.texi
+          introduction.txt                text.texi~
+          ...
+          ---------- Buffer: *shell* ----------
+
+ - Function: process-send-region process start end &optional buffer
+     This function sends the text in the region defined by START and
+     END as standard input to PROCESS.
+
+     The argument PROCESS may be a process or the name of a process, or
+     a buffer or the name of a buffer, in which case the buffer's
+     process is used.  If it is `nil', the current buffer's process is
+     used.
+
+     An error is signaled unless both START and END are integers or
+     markers that indicate positions in the current buffer.  (It is
+     unimportant which number is larger.)
+
+ - Function: process-send-eof &optional process
+     This function makes PROCESS see an end-of-file in its input.  The
+     EOF comes after any text already sent to it.
+
+     PROCESS may be a process, a buffer, the name of a process or
+     buffer, or `nil', indicating the current buffer's process.  An
+     error is signaled if PROCESS does not identify any process.
+
+     The function returns the process object identified by PROCESS.
+
+          (process-send-eof "shell")
+               => "shell"
+
+\1f
+File: lispref.info,  Node: Signals to Processes,  Next: Output from Processes,  Prev: Input to Processes,  Up: Processes
+
+Sending Signals to Processes
+============================
+
+"Sending a signal" to a subprocess is a way of interrupting its
+activities.  There are several different signals, each with its own
+meaning.  The set of signals and their names is defined by the operating
+system.  For example, the signal `SIGINT' means that the user has typed
+`C-c', or that some analogous thing has happened.
+
+   Each signal has a standard effect on the subprocess.  Most signals
+kill the subprocess, but some stop or resume execution instead.  Most
+signals can optionally be handled by programs; if the program handles
+the signal, then we can say nothing in general about its effects.
+
+   The set of signals and their names is defined by the operating
+system; XEmacs has facilities for sending only a few of the signals
+that are defined.  XEmacs can send signals only to its own subprocesses.
+
+   You can send signals explicitly by calling the functions in this
+section.  XEmacs also sends signals automatically at certain times:
+killing a buffer sends a `SIGHUP' signal to all its associated
+processes; killing XEmacs sends a `SIGHUP' signal to all remaining
+processes.  (`SIGHUP' is a signal that indicates that the connection
+between the user and the process is broken, for example if a connection
+via a telephone line is hung up.)
+
+   Each of the signal-sending functions takes two optional arguments:
+PROCESS and CURRENT-GROUP.
+
+   The argument PROCESS must be either a process or a buffer, the name
+of one, or `nil'.  If it is `nil', the process defaults to the process
+associated with the current buffer.  An error is signaled if PROCESS
+does not identify a process.
+
+   The argument CURRENT-GROUP is a flag that makes a difference when
+you are running a job-control shell as an XEmacs subprocess.  If it is
+non-`nil', then the signal is sent to the current foreground process
+group of the terminal that XEmacs uses to communicate with the
+subprocess.  If the process is a job-control shell, this means the
+shell's current subjob.  If it is `nil', the signal is sent to the
+process group of the immediate subprocess of XEmacs.  If the subprocess
+is a job-control shell, this is the shell itself.
+
+   The flag CURRENT-GROUP has no effect when a pipe is used to
+communicate with the subprocess, because the operating system does not
+support the distinction in the case of pipes.  For the same reason,
+job-control shells won't work when a pipe is used.  See
+`process-connection-type' in *Note Asynchronous Processes::.
+
+   Some of the functions below take a SIGNAL argument, which identifies
+a signal to be sent.  It must be either an integer or a symbol which
+names the signal, like `SIGSEGV'.
+
+ - Function: process-send-signal signal &optional process current-group
+     This function sends the signal SIGNAL to the process PROCESS.  The
+     following functions can be implemented in terms of
+     `process-send-signal'.
+
+ - Function: interrupt-process &optional process current-group
+     This function interrupts the process PROCESS by sending the signal
+     `SIGINT'.  Outside of XEmacs, typing the "interrupt character"
+     (normally `C-c') sends this signal.  When the argument
+     CURRENT-GROUP is non-`nil', you can think of this function as
+     "typing `C-c'" on the terminal by which XEmacs talks to the
+     subprocess.
+
+ - Function: kill-process &optional process current-group
+     This function kills the process PROCESS by sending the signal
+     `SIGKILL'.  This signal kills the subprocess immediately, and
+     cannot be handled by the subprocess.
+
+ - Function: quit-process &optional process current-group
+     This function sends the signal `SIGQUIT' to the process PROCESS.
+     This signal is the one sent by the "quit character" (usually
+     `C-\') when you are not inside XEmacs.
+
+ - Function: stop-process &optional process current-group
+     This function stops the process PROCESS by sending the signal
+     `SIGTSTP'.  Use `continue-process' to resume its execution.
+
+     On systems with job control, the "stop character" (usually `C-z')
+     sends this signal (outside of XEmacs).  When CURRENT-GROUP is
+     non-`nil', you can think of this function as "typing `C-z'" on the
+     terminal XEmacs uses to communicate with the subprocess.
+
+ - Function: continue-process &optional process current-group
+     This function resumes execution of the process PROCESS by sending
+     it the signal `SIGCONT'.  This presumes that PROCESS was stopped
+     previously.
+
+ - Command: signal-process pid signal
+     This function sends a signal to the process with process id PID,
+     which need not be a child of XEmacs.  The argument SIGNAL
+     specifies which signal to send.
+
+\1f
+File: lispref.info,  Node: Output from Processes,  Next: Sentinels,  Prev: Signals to Processes,  Up: Processes
+
+Receiving Output from Processes
+===============================
+
+There are two ways to receive the output that a subprocess writes to
+its standard output stream.  The output can be inserted in a buffer,
+which is called the associated buffer of the process, or a function
+called the "filter function" can be called to act on the output.  If
+the process has no buffer and no filter function, its output is
+discarded.
+
+* Menu:
+
+* Process Buffers::       If no filter, output is put in a buffer.
+* Filter Functions::      Filter functions accept output from the process.
+* Accepting Output::      Explicitly permitting subprocess output.
+                            Waiting for subprocess output.
+
+\1f
+File: lispref.info,  Node: Process Buffers,  Next: Filter Functions,  Up: Output from Processes
+
+Process Buffers
+---------------
+
+A process can (and usually does) have an "associated buffer", which is
+an ordinary Emacs buffer that is used for two purposes: storing the
+output from the process, and deciding when to kill the process.  You
+can also use the buffer to identify a process to operate on, since in
+normal practice only one process is associated with any given buffer.
+Many applications of processes also use the buffer for editing input to
+be sent to the process, but this is not built into XEmacs Lisp.
+
+   Unless the process has a filter function (*note Filter Functions::),
+its output is inserted in the associated buffer.  The position to insert
+the output is determined by the `process-mark', which is then updated
+to point to the end of the text just inserted.  Usually, but not
+always, the `process-mark' is at the end of the buffer.
+
+ - Function: process-buffer process
+     This function returns the associated buffer of the process PROCESS.
+
+          (process-buffer (get-process "shell"))
+               => #<buffer *shell*>
+
+ - Function: process-mark process
+     This function returns the process marker for PROCESS, which is the
+     marker that says where to insert output from the process.
+
+     If PROCESS does not have a buffer, `process-mark' returns a marker
+     that points nowhere.
+
+     Insertion of process output in a buffer uses this marker to decide
+     where to insert, and updates it to point after the inserted text.
+     That is why successive batches of output are inserted
+     consecutively.
+
+     Filter functions normally should use this marker in the same
+     fashion as is done by direct insertion of output in the buffer.  A
+     good example of a filter function that uses `process-mark' is
+     found at the end of the following section.
+
+     When the user is expected to enter input in the process buffer for
+     transmission to the process, the process marker is useful for
+     distinguishing the new input from previous output.
+
+ - Function: set-process-buffer process buffer
+     This function sets the buffer associated with PROCESS to BUFFER.
+     If BUFFER is `nil', the process becomes associated with no buffer.
+
+ - Function: get-buffer-process buffer-or-name
+     This function returns the process associated with BUFFER-OR-NAME.
+     If there are several processes associated with BUFFER-OR-NAME,
+     then one is chosen.  (Presently, the one chosen is the one most
+     recently created.)  It is usually a bad idea to have more than one
+     process associated with the same buffer.
+
+          (get-buffer-process "*shell*")
+               => #<process shell>
+
+     Killing the process's buffer deletes the process, which kills the
+     subprocess with a `SIGHUP' signal (*note Signals to Processes::).
+
+\1f
+File: lispref.info,  Node: Filter Functions,  Next: Accepting Output,  Prev: Process Buffers,  Up: Output from Processes
+
+Process Filter Functions
+------------------------
+
+A process "filter function" is a function that receives the standard
+output from the associated process.  If a process has a filter, then
+_all_ output from that process is passed to the filter.  The process
+buffer is used directly for output from the process only when there is
+no filter.
+
+   A filter function must accept two arguments: the associated process
+and a string, which is the output.  The function is then free to do
+whatever it chooses with the output.
+
+   A filter function runs only while XEmacs is waiting (e.g., for
+terminal input, or for time to elapse, or for process output).  This
+avoids the timing errors that could result from running filters at
+random places in the middle of other Lisp programs.  You may explicitly
+cause Emacs to wait, so that filter functions will run, by calling
+`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
+(*note Accepting Output::).  Emacs is also waiting when the command loop
+is reading input.
+
+   Quitting is normally inhibited within a filter function--otherwise,
+the effect of typing `C-g' at command level or to quit a user command
+would be unpredictable.  If you want to permit quitting inside a filter
+function, bind `inhibit-quit' to `nil'.  *Note Quitting::.
+
+   If an error happens during execution of a filter function, it is
+caught automatically, so that it doesn't stop the execution of whatever
+program was running when the filter function was started.  However, if
+`debug-on-error' is non-`nil', the error-catching is turned off.  This
+makes it possible to use the Lisp debugger to debug the filter
+function.  *Note Debugger::.
+
+   Many filter functions sometimes or always insert the text in the
+process's buffer, mimicking the actions of XEmacs when there is no
+filter.  Such filter functions need to use `set-buffer' in order to be
+sure to insert in that buffer.  To avoid setting the current buffer
+semipermanently, these filter functions must use `unwind-protect' to
+make sure to restore the previous current buffer.  They should also
+update the process marker, and in some cases update the value of point.
+Here is how to do these things:
+
+     (defun ordinary-insertion-filter (process string)
+       (let ((old-buffer (current-buffer)))
+         (unwind-protect
+             (let (moving)
+               (set-buffer (process-buffer process))
+               (setq moving (= (point) (process-mark process)))
+               (save-excursion
+                 ;; Insert the text, moving the process-marker.
+                 (goto-char (process-mark process))
+                 (insert string)
+                 (set-marker (process-mark process) (point)))
+               (if moving (goto-char (process-mark process))))
+           (set-buffer old-buffer))))
+
+The reason to use an explicit `unwind-protect' rather than letting
+`save-excursion' restore the current buffer is so as to preserve the
+change in point made by `goto-char'.
+
+   To make the filter force the process buffer to be visible whenever
+new text arrives, insert the following line just before the
+`unwind-protect':
+
+     (display-buffer (process-buffer process))
+
+   To force point to move to the end of the new output no matter where
+it was previously, eliminate the variable `moving' and call `goto-char'
+unconditionally.
+
+   In earlier Emacs versions, every filter function that did regexp
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically; filter functions never need to do it
+explicitly.  *Note Match Data::.
+
+   A filter function that writes the output into the buffer of the
+process should check whether the buffer is still alive.  If it tries to
+insert into a dead buffer, it will get an error.  If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+   The output to the function may come in chunks of any size.  A program
+that produces the same output twice in a row may send it as one batch
+of 200 characters one time, and five batches of 40 characters the next.
+
+ - Function: set-process-filter process filter
+     This function gives PROCESS the filter function FILTER.  If FILTER
+     is `nil', then the process will have no filter.  If FILTER is `t',
+     then no output from the process will be accepted until the filter
+     is changed. (Output received during this time is not discarded,
+     but is queued, and will be processed as soon as the filter is
+     changed.)
+
+ - Function: process-filter process
+     This function returns the filter function of PROCESS, or `nil' if
+     it has none.  `t' means that output processing has been stopped.
+
+   Here is an example of use of a filter function:
+
+     (defun keep-output (process output)
+        (setq kept (cons output kept)))
+          => keep-output
+     (setq kept nil)
+          => nil
+     (set-process-filter (get-process "shell") 'keep-output)
+          => keep-output
+     (process-send-string "shell" "ls ~/other\n")
+          => nil
+     kept
+          => ("lewis@slug[8] % "
+     "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
+     address.txt             backup.psf              kolstad.psf
+     backup.bib~             david.mss               resume-Dec-86.mss~
+     backup.err              david.psf               resume-Dec.psf
+     backup.mss              dland                   syllabus.mss
+     "
+     "#backups.mss#          backup.mss~             kolstad.mss
+     ")
+
+\1f
+File: lispref.info,  Node: Accepting Output,  Prev: Filter Functions,  Up: Output from Processes
+
+Accepting Output from Processes
+-------------------------------
+
+Output from asynchronous subprocesses normally arrives only while
+XEmacs is waiting for some sort of external event, such as elapsed time
+or terminal input.  Occasionally it is useful in a Lisp program to
+explicitly permit output to arrive at a specific point, or even to wait
+until output arrives from a process.
+
+ - Function: accept-process-output &optional process seconds millisec
+     This function allows XEmacs to read pending output from processes.
+     The output is inserted in the associated buffers or given to
+     their filter functions.  If PROCESS is non-`nil' then this
+     function does not return until some output has been received from
+     PROCESS.
+
+     The arguments SECONDS and MILLISEC let you specify timeout
+     periods.  The former specifies a period measured in seconds and the
+     latter specifies one measured in milliseconds.  The two time
+     periods thus specified are added together, and
+     `accept-process-output' returns after that much time whether or
+     not there has been any subprocess output.  Note that SECONDS is
+     allowed to be a floating-point number; thus, there is no need to
+     ever use MILLISEC. (It is retained for compatibility purposes.)
+
+     The function `accept-process-output' returns non-`nil' if it did
+     get some output, or `nil' if the timeout expired before output
+     arrived.
+
+\1f
+File: lispref.info,  Node: Sentinels,  Next: Process Window Size,  Prev: Output from Processes,  Up: Processes
+
+Sentinels: Detecting Process Status Changes
+===========================================
+
+A "process sentinel" is a function that is called whenever the
+associated process changes status for any reason, including signals
+(whether sent by XEmacs or caused by the process's own actions) that
+terminate, stop, or continue the process.  The process sentinel is also
+called if the process exits.  The sentinel receives two arguments: the
+process for which the event occurred, and a string describing the type
+of event.
+
+   The string describing the event looks like one of the following:
+
+   * `"finished\n"'.
+
+   * `"exited abnormally with code EXITCODE\n"'.
+
+   * `"NAME-OF-SIGNAL\n"'.
+
+   * `"NAME-OF-SIGNAL (core dumped)\n"'.
+
+   A sentinel runs only while XEmacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output).  This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs.  A program can wait, so that
+sentinels will run, by calling `sit-for' or `sleep-for' (*note
+Waiting::), or `accept-process-output' (*note Accepting Output::).
+Emacs is also waiting when the command loop is reading input.
+
+   Quitting is normally inhibited within a sentinel--otherwise, the
+effect of typing `C-g' at command level or to quit a user command would
+be unpredictable.  If you want to permit quitting inside a sentinel,
+bind `inhibit-quit' to `nil'.  *Note Quitting::.
+
+   A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive.  If it tries to insert
+into a dead buffer, it will get an error.  If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+   If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started.  However, if
+`debug-on-error' is non-`nil', the error-catching is turned off.  This
+makes it possible to use the Lisp debugger to debug the sentinel.
+*Note Debugger::.
+
+   In earlier Emacs versions, every sentinel that did regexp searching
+or matching had to explicitly save and restore the match data.  Now
+Emacs does this automatically; sentinels never need to do it explicitly.
+*Note Match Data::.
+
+ - Function: set-process-sentinel process sentinel
+     This function associates SENTINEL with PROCESS.  If SENTINEL is
+     `nil', then the process will have no sentinel.  The default
+     behavior when there is no sentinel is to insert a message in the
+     process's buffer when the process status changes.
+
+          (defun msg-me (process event)
+             (princ
+               (format "Process: %s had the event `%s'" process event)))
+          (set-process-sentinel (get-process "shell") 'msg-me)
+               => msg-me
+          (kill-process (get-process "shell"))
+               -| Process: #<process shell> had the event `killed'
+               => #<process shell>
+
+ - Function: process-sentinel process
+     This function returns the sentinel of PROCESS, or `nil' if it has
+     none.
+
+ - Function: waiting-for-user-input-p
+     While a sentinel or filter function is running, this function
+     returns non-`nil' if XEmacs was waiting for keyboard input from
+     the user at the time the sentinel or filter function was called,
+     `nil' if it was not.
+
+\1f
+File: lispref.info,  Node: Process Window Size,  Next: Transaction Queues,  Prev: Sentinels,  Up: Processes
+
+Process Window Size
+===================
+
+ - Function: set-process-window-size process height width
+     This function tells PROCESS that its logical window size is HEIGHT
+     by WIDTH characters.  This is principally useful with pty's.
+
+\1f
+File: lispref.info,  Node: Transaction Queues,  Next: Network,  Prev: Process Window Size,  Up: Processes
+
+Transaction Queues
+==================
+
+You can use a "transaction queue" for more convenient communication
+with subprocesses using transactions.  First use `tq-create' to create
+a transaction queue communicating with a specified process.  Then you
+can call `tq-enqueue' to send a transaction.
+
+ - Function: tq-create process
+     This function creates and returns a transaction queue
+     communicating with PROCESS.  The argument PROCESS should be a
+     subprocess capable of sending and receiving streams of bytes.  It
+     may be a child process, or it may be a TCP connection to a server,
+     possibly on another machine.
+
+ - Function: tq-enqueue queue question regexp closure fn
+     This function sends a transaction to queue QUEUE.  Specifying the
+     queue has the effect of specifying the subprocess to talk to.
+
+     The argument QUESTION is the outgoing message that starts the
+     transaction.  The argument FN is the function to call when the
+     corresponding answer comes back; it is called with two arguments:
+     CLOSURE, and the answer received.
+
+     The argument REGEXP is a regular expression that should match the
+     entire answer, but nothing less; that's how `tq-enqueue' determines
+     where the answer ends.
+
+     The return value of `tq-enqueue' itself is not meaningful.
+
+ - Function: tq-close queue
+     Shut down transaction queue QUEUE, waiting for all pending
+     transactions to complete, and then terminate the connection or
+     child process.
+
+   Transaction queues are implemented by means of a filter function.
+*Note Filter Functions::.
+
+\1f
+File: lispref.info,  Node: Network,  Prev: Transaction Queues,  Up: Processes
+
+Network Connections
+===================
+
+XEmacs Lisp programs can open TCP network connections to other
+processes on the same machine or other machines.  A network connection
+is handled by Lisp much like a subprocess, and is represented by a
+process object.  However, the process you are communicating with is not
+a child of the XEmacs process, so you can't kill it or send it signals.
+All you can do is send and receive data.  `delete-process' closes the
+connection, but does not kill the process at the other end; that
+process must decide what to do about closure of the connection.
+
+   You can distinguish process objects representing network connections
+from those representing subprocesses with the `process-status'
+function.  It always returns either `open' or `closed' for a network
+connection, and it never returns either of those values for a real
+subprocess.  *Note Process Information::.
+
+ - Function: open-network-stream name buffer-or-name host service
+          &optional protocol
+     This function opens a TCP connection for a service to a host.  It
+     returns a process object to represent the connection.
+
+     Input and output work as for other process objects.
+     `delete-process' closes the connection.
+
+     The NAME argument specifies the name for the process object.  It
+     is modified as necessary to make it unique.
+
+     The BUFFER-OR-NAME argument is the buffer to associate with the
+     connection.  It can be a buffer or the name of one.  Output from
+     the connection is inserted in the buffer, unless you specify a
+     filter function to handle the output.  If BUFFER-OR-NAME is `nil',
+     it means that the connection is not associated with any buffer.
+
+     The arguments HOST and SERVICE specify where to connect to; HOST
+     is the host name or IP address (a string), and SERVICE is the name
+     of a defined network service (a string) or a port number (an
+     integer).
+
+     Optional fifth arg PROTOCOL is the network protocol to use.
+     Currently only `tcp' (Transmission Control Protocol) and `udp'
+     (User Datagram Protocol) are supported.  When omitted, `tcp' is
+     assumed.
+
+     Output via `process-send-string' and input via buffer or filter
+     (see `set-process-filter') are stream-oriented.  That means UDP
+     datagrams are not guaranteed to be sent and received in discrete
+     packets. (But small datagrams around 500 bytes that are not
+     truncated by `process-send-string' are usually fine.)  Note further
+     that the UDP protocol does not guard against lost packets.
+
+\1f
+File: lispref.info,  Node: System Interface,  Next: X-Windows,  Prev: Processes,  Up: Top
+
+Operating System Interface
+**************************
+
+This chapter is about starting and getting out of Emacs, access to
+values in the operating system environment, and terminal input, output,
+and flow control.
+
+   *Note Building XEmacs::, for related information.  See also *Note
+Display::, for additional operating system status information
+pertaining to the terminal and the screen.
+
+* Menu:
+
+* Starting Up::         Customizing XEmacs start-up processing.
+* Getting Out::         How exiting works (permanent or temporary).
+* System Environment::  Distinguish the name and kind of system.
+* User Identification:: Finding the name and user id of the user.
+* Time of Day::                Getting the current time.
+* Time Conversion::     Converting a time from numeric form to a string, or
+                          to calendrical data (or vice versa).
+* Timers::             Setting a timer to call a function at a certain time.
+* 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.
+
+\1f
+File: lispref.info,  Node: Starting Up,  Next: Getting Out,  Up: System Interface
+
+Starting Up XEmacs
+==================
+
+This section describes what XEmacs does when it is started, and how you
+can customize these actions.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Start-up Summary,  Next: Init File,  Up: Starting Up
+
+Summary: Sequence of Actions at Start Up
+----------------------------------------
+
+The order of operations performed (in `startup.el') by XEmacs when it
+is started up is as follows:
+
+  1. It loads the initialization library for the window system, if you
+     are using a window system.  This library's name is
+     `term/WINDOWSYSTEM-win.el'.
+
+  2. It processes the initial options.  (Some of them are handled even
+     earlier than this.)
+
+  3. It initializes the X window frame and faces, if appropriate.
+
+  4. It runs the normal hook `before-init-hook'.
+
+  5. It loads the library `site-start', unless the option
+     `-no-site-file' was specified.  The library's file name is usually
+     `site-start.el'.
+
+  6. It loads the file `~/.emacs' unless `-q' was specified on the
+     command line.  (This is not done in `-batch' mode.)  The `-u'
+     option can specify the user name whose home directory should be
+     used instead of `~'.
+
+  7. It loads the library `default' unless `inhibit-default-init' is
+     non-`nil'.  (This is not done in `-batch' mode or if `-q' was
+     specified on the command line.)  The library's file name is
+     usually `default.el'.
+
+  8. It runs the normal hook `after-init-hook'.
+
+  9. It sets the major mode according to `initial-major-mode', provided
+     the buffer `*scratch*' is still current and still in Fundamental
+     mode.
+
+ 10. It loads the terminal-specific Lisp file, if any, except when in
+     batch mode or using a window system.
+
+ 11. It displays the initial echo area message, unless you have
+     suppressed that with `inhibit-startup-echo-area-message'.
+
+ 12. It processes the action arguments from the command line.
+
+ 13. It runs `term-setup-hook'.
+
+ 14. It calls `frame-notice-user-settings', which modifies the
+     parameters of the selected frame according to whatever the init
+     files specify.
+
+ 15. It runs `window-setup-hook'.  *Note Terminal-Specific::.
+
+ 16. It displays copyleft, nonwarranty, and basic use information,
+     provided there were no remaining command line arguments (a few
+     steps above) and the value of `inhibit-startup-message' is `nil'.
+
+ - User Option: inhibit-startup-message
+     This variable inhibits the initial startup messages (the
+     nonwarranty, etc.).  If it is non-`nil', then the messages are not
+     printed.
+
+     This variable exists so you can set it in your personal init file,
+     once you are familiar with the contents of the startup message.
+     Do not set this variable in the init file of a new user, or in a
+     way that affects more than one user, because that would prevent
+     new users from receiving the information they are supposed to see.
+
+ - User Option: inhibit-startup-echo-area-message
+     This variable controls the display of the startup echo area
+     message.  You can suppress the startup echo area message by adding
+     text with this form to your `.emacs' file:
+
+          (setq inhibit-startup-echo-area-message
+                "YOUR-LOGIN-NAME")
+
+     Simply setting `inhibit-startup-echo-area-message' to your login
+     name is not sufficient to inhibit the message; Emacs explicitly
+     checks whether `.emacs' contains an expression as shown above.
+     Your login name must appear in the expression as a Lisp string
+     constant.
+
+     This way, you can easily inhibit the message for yourself if you
+     wish, but thoughtless copying of your `.emacs' file will not
+     inhibit the message for someone else.
+
+\1f
+File: lispref.info,  Node: Init File,  Next: Terminal-Specific,  Prev: Start-up Summary,  Up: Starting Up
+
+The Init File: `.emacs'
+-----------------------
+
+When you start XEmacs, it normally attempts to load the file `.emacs'
+from your home directory.  This file, if it exists, must contain Lisp
+code.  It is called your "init file".  The command line switches `-q'
+and `-u' affect the use of the init file; `-q' says not to load an init
+file, and `-u' says to load a specified user's init file instead of
+yours.  *Note Entering XEmacs: (xemacs)Entering XEmacs.
+
+   A site may have a "default init file", which is the library named
+`default.el'.  XEmacs finds the `default.el' file through the standard
+search path for libraries (*note How Programs Do Loading::).  The
+XEmacs distribution does not come with this file; sites may provide one
+for local customizations.  If the default init file exists, it is
+loaded whenever you start Emacs, except in batch mode or if `-q' is
+specified.  But your own personal init file, if any, is loaded first; if
+it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
+not subsequently load the `default.el' file.
+
+   Another file for site-customization is `site-start.el'.  Emacs loads
+this _before_ the user's init file.  You can inhibit the loading of
+this file with the option `-no-site-file'.
+
+ - Variable: site-run-file
+     This variable specifies the site-customization file to load before
+     the user's init file.  Its normal value is `"site-start"'.
+
+   If there is a great deal of code in your `.emacs' file, you should
+move it into another file named `SOMETHING.el', byte-compile it (*note
+Byte Compilation::), and make your `.emacs' file load the other file
+using `load' (*note Loading::).
+
+   *Note Init File Examples: (xemacs)Init File Examples, for examples
+of how to make various commonly desired customizations in your `.emacs'
+file.
+
+ - User Option: inhibit-default-init
+     This variable prevents XEmacs from loading the default
+     initialization library file for your session of XEmacs.  If its
+     value is non-`nil', then the default library is not loaded.  The
+     default value is `nil'.
+
+ - Variable: before-init-hook
+ - Variable: after-init-hook
+     These two normal hooks are run just before, and just after,
+     loading of the user's init file, `default.el', and/or
+     `site-start.el'.
+
+\1f
+File: lispref.info,  Node: Terminal-Specific,  Next: Command Line Arguments,  Prev: Init File,  Up: Starting Up
+
+Terminal-Specific Initialization
+--------------------------------
+
+Each terminal type can have its own Lisp library that XEmacs loads when
+run on that type of terminal.  For a terminal type named TERMTYPE, the
+library is called `term/TERMTYPE'.  XEmacs finds the file by searching
+the `load-path' directories as it does for other files, and trying the
+`.elc' and `.el' suffixes.  Normally, terminal-specific Lisp library is
+located in `emacs/lisp/term', a subdirectory of the `emacs/lisp'
+directory in which most XEmacs Lisp libraries are kept.
+
+   The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type.  Normally,
+`term-file-prefix' has the value `"term/"'; changing this is not
+recommended.
+
+   The usual function of a terminal-specific library is to enable
+special keys to send sequences that XEmacs can recognize.  It may also
+need to set or add to `function-key-map' if the Termcap entry does not
+specify all the terminal's function keys.  *Note Terminal Input::.
+
+   When the name of the terminal type contains a hyphen, only the part
+of the name before the first hyphen is significant in choosing the
+library name.  Thus, terminal types `aaa-48' and `aaa-30-rv' both use
+the `term/aaa' library.  If necessary, the library can evaluate
+`(getenv "TERM")' to find the full name of the terminal type.
+
+   Your `.emacs' file can prevent the loading of the terminal-specific
+library by setting the variable `term-file-prefix' to `nil'.  This
+feature is useful when experimenting with your own peculiar
+customizations.
+
+   You can also arrange to override some of the actions of the
+terminal-specific library by setting the variable `term-setup-hook'.
+This is a normal hook which XEmacs runs using `run-hooks' at the end of
+XEmacs initialization, after loading both your `.emacs' file and any
+terminal-specific libraries.  You can use this variable to define
+initializations for terminals that do not have their own libraries.
+*Note Hooks::.
+
+ - Variable: term-file-prefix
+     If the `term-file-prefix' variable is non-`nil', XEmacs loads a
+     terminal-specific initialization file as follows:
+
+          (load (concat term-file-prefix (getenv "TERM")))
+
+     You may set the `term-file-prefix' variable to `nil' in your
+     `.emacs' file if you do not wish to load the
+     terminal-initialization file.  To do this, put the following in
+     your `.emacs' file: `(setq term-file-prefix nil)'.
+
+ - Variable: term-setup-hook
+     This variable is a normal hook that XEmacs runs after loading your
+     `.emacs' file, the default initialization file (if any) and the
+     terminal-specific Lisp file.
+
+     You can use `term-setup-hook' to override the definitions made by a
+     terminal-specific file.
+
+ - Variable: window-setup-hook
+     This variable is a normal hook which XEmacs runs after loading your
+     `.emacs' file and the default initialization file (if any), after
+     loading terminal-specific Lisp code, and after running the hook
+     `term-setup-hook'.
+
+\1f
+File: lispref.info,  Node: Command Line Arguments,  Prev: Terminal-Specific,  Up: Starting Up
+
+Command Line Arguments
+----------------------
+
+You can use command line arguments to request various actions when you
+start XEmacs.  Since you do not need to start XEmacs more than once per
+day, and will often leave your XEmacs session running longer than that,
+command line arguments are hardly ever used.  As a practical matter, it
+is best to avoid making the habit of using them, since this habit would
+encourage you to kill and restart XEmacs unnecessarily often.  These
+options exist for two reasons: to be compatible with other editors (for
+invocation by other programs) and to enable shell scripts to run
+specific Lisp programs.
+
+   This section describes how Emacs processes command line arguments,
+and how you can customize them.
+
+ - Function: command-line
+     This function parses the command line that XEmacs was called with,
+     processes it, loads the user's `.emacs' file and displays the
+     startup messages.
+
+ - Variable: command-line-processed
+     The value of this variable is `t' once the command line has been
+     processed.
+
+     If you redump XEmacs by calling `dump-emacs', you may wish to set
+     this variable to `nil' first in order to cause the new dumped
+     XEmacs to process its new command line arguments.
+
+ - Variable: command-switch-alist
+     The value of this variable is an alist of user-defined command-line
+     options and associated handler functions.  This variable exists so
+     you can add elements to it.
+
+     A "command line option" is an argument on the command line of the
+     form:
+
+          -OPTION
+
+     The elements of the `command-switch-alist' look like this:
+
+          (OPTION . HANDLER-FUNCTION)
+
+     The HANDLER-FUNCTION is called to handle OPTION and receives the
+     option name as its sole argument.
+
+     In some cases, the option is followed in the command line by an
+     argument.  In these cases, the HANDLER-FUNCTION can find all the
+     remaining command-line arguments in the variable
+     `command-line-args-left'.  (The entire list of command-line
+     arguments is in `command-line-args'.)
+
+     The command line arguments are parsed by the `command-line-1'
+     function in the `startup.el' file.  See also *Note Command Line
+     Switches and Arguments: (xemacs)Command Switches.
+
+ - Variable: command-line-args
+     The value of this variable is the list of command line arguments
+     passed to XEmacs.
+
+ - Variable: command-line-functions
+     This variable's value is a list of functions for handling an
+     unrecognized command-line argument.  Each time the next argument
+     to be processed has no special meaning, the functions in this list
+     are called, in order of appearance, until one of them returns a
+     non-`nil' value.
+
+     These functions are called with no arguments.  They can access the
+     command-line argument under consideration through the variable
+     `argi'.  The remaining arguments (not including the current one)
+     are in the variable `command-line-args-left'.
+
+     When a function recognizes and processes the argument in `argi', it
+     should return a non-`nil' value to say it has dealt with that
+     argument.  If it has also dealt with some of the following
+     arguments, it can indicate that by deleting them from
+     `command-line-args-left'.
+
+     If all of these functions return `nil', then the argument is used
+     as a file name to visit.
+
+\1f
+File: lispref.info,  Node: Getting Out,  Next: System Environment,  Prev: Starting Up,  Up: System Interface
+
+Getting out of XEmacs
+=====================
+
+There are two ways to get out of XEmacs: you can kill the XEmacs job,
+which exits permanently, or you can suspend it, which permits you to
+reenter the XEmacs process later.  As a practical matter, you seldom
+kill XEmacs--only when you are about to log out.  Suspending is much
+more common.
+
+* Menu:
+
+* Killing XEmacs::        Exiting XEmacs irreversibly.
+* Suspending XEmacs::     Exiting XEmacs reversibly.
+
+\1f
+File: lispref.info,  Node: Killing XEmacs,  Next: Suspending XEmacs,  Up: Getting Out
+
+Killing XEmacs
+--------------
+
+Killing XEmacs means ending the execution of the XEmacs process.  The
+parent process normally resumes control.  The low-level primitive for
+killing XEmacs is `kill-emacs'.
+
+ - Command: kill-emacs &optional exit-data
+     This function exits the XEmacs process and kills it.
+
+     If EXIT-DATA is an integer, then it is used as the exit status of
+     the XEmacs process.  (This is useful primarily in batch operation;
+     see *Note Batch Mode::.)
+
+     If EXIT-DATA is a string, its contents are stuffed into the
+     terminal input buffer so that the shell (or whatever program next
+     reads input) can read them.
+
+   All the information in the XEmacs process, aside from files that have
+been saved, is lost when the XEmacs is killed.  Because killing XEmacs
+inadvertently can lose a lot of work, XEmacs queries for confirmation
+before actually terminating if you have buffers that need saving or
+subprocesses that are running.  This is done in the function
+`save-buffers-kill-emacs'.
+
+ - Variable: kill-emacs-query-functions
+     After asking the standard questions, `save-buffers-kill-emacs'
+     calls the functions in the list `kill-buffer-query-functions', in
+     order of appearance, with no arguments.  These functions can ask
+     for additional confirmation from the user.  If any of them returns
+     non-`nil', XEmacs is not killed.
+
+ - Variable: kill-emacs-hook
+     This variable is a normal hook; once `save-buffers-kill-emacs' is
+     finished with all file saving and confirmation, it runs the
+     functions in this hook.
+
+\1f
+File: lispref.info,  Node: Suspending XEmacs,  Prev: Killing XEmacs,  Up: Getting Out
+
+Suspending XEmacs
+-----------------
+
+"Suspending XEmacs" means stopping XEmacs temporarily and returning
+control to its superior process, which is usually the shell.  This
+allows you to resume editing later in the same XEmacs process, with the
+same buffers, the same kill ring, the same undo history, and so on.  To
+resume XEmacs, use the appropriate command in the parent shell--most
+likely `fg'.
+
+   Some operating systems do not support suspension of jobs; on these
+systems, "suspension" actually creates a new shell temporarily as a
+subprocess of XEmacs.  Then you would exit the shell to return to
+XEmacs.
+
+   Suspension is not useful with window systems such as X, because the
+XEmacs job may not have a parent that can resume it again, and in any
+case you can give input to some other job such as a shell merely by
+moving to a different window.  Therefore, suspending is not allowed
+when XEmacs is an X client.
+
+ - Command: suspend-emacs &optional stuffstring
+     This function stops XEmacs and returns control to the superior
+     process.  If and when the superior process resumes XEmacs,
+     `suspend-emacs' returns `nil' to its caller in Lisp.
+
+     If optional arg STUFFSTRING is non-`nil', its characters are sent
+     to be read as terminal input by XEmacs's superior shell.  The
+     characters in STUFFSTRING are not echoed by the superior shell;
+     only the results appear.
+
+     Before suspending, `suspend-emacs' runs the normal hook
+     `suspend-hook'.  In Emacs version 18, `suspend-hook' was not a
+     normal hook; its value was a single function, and if its value was
+     non-`nil', then `suspend-emacs' returned immediately without
+     actually suspending anything.
+
+     After the user resumes XEmacs, `suspend-emacs' runs the normal hook
+     `suspend-resume-hook'.  *Note Hooks::.
+
+     The next redisplay after resumption will redraw the entire screen,
+     unless the variable `no-redraw-on-reenter' is non-`nil' (*note
+     Refresh Screen::).
+
+     In the following example, note that `pwd' is not echoed after
+     XEmacs is suspended.  But it is read and executed by the shell.
+
+          (suspend-emacs)

                => nil
                => nil

-          (equal x y)
-               => t
-          (eq (elt x 1) (elt y 1))
-               => t

           
           

-          ;; Replacing an element of one sequence.
-          (aset x 0 'quux)
-          x => [quux (1 2)]
-          y => [foo (1 2)]
+          (add-hook 'suspend-hook
+                    (function (lambda ()
+                                (or (y-or-n-p
+                                      "Really suspend? ")
+                                    (error "Suspend cancelled")))))
+               => (lambda nil
+                    (or (y-or-n-p "Really suspend? ")
+                        (error "Suspend cancelled")))
+          (add-hook 'suspend-resume-hook
+                    (function (lambda () (message "Resumed!"))))
+               => (lambda nil (message "Resumed!"))
+          (suspend-emacs "pwd")
+               => nil
+          ---------- Buffer: Minibuffer ----------
+          Really suspend? y
+          ---------- Buffer: Minibuffer ----------

           
           

-          ;; Modifying the inside of a shared element.
-          (setcar (aref x 1) 69)
-          x => [quux (69 2)]
-          y => [foo (69 2)]
+          ---------- Parent Shell ----------
+          lewis@slug[23] % /user/lewis/manual
+          lewis@slug[24] % fg

           
           

-          ;; Creating a bit vector.
-          (bit-vector 1 0 1 1 0 1 0 0)
-               => #*10110100
-
- - Function: length sequence
-     Returns the number of elements in SEQUENCE.  If SEQUENCE is a cons
-     cell that is not a list (because the final CDR is not `nil'), a
-     `wrong-type-argument' error is signaled.
-
-          (length '(1 2 3))
-              => 3
-          (length ())
-              => 0
-          (length "foobar")
-              => 6
-          (length [1 2 3])
-              => 3
-          (length #*01101)
-              => 5
-
- - Function: elt sequence index
-     This function returns the element of SEQUENCE indexed by INDEX.
-     Legitimate values of INDEX are integers ranging from 0 up to one
-     less than the length of SEQUENCE.  If SEQUENCE is a list, then
-     out-of-range values of INDEX return `nil'; otherwise, they trigger
-     an `args-out-of-range' error.
-
-          (elt [1 2 3 4] 2)
-               => 3
-          (elt '(1 2 3 4) 2)
-               => 3
-          (char-to-string (elt "1234" 2))
-               => "3"
-          (elt #*00010000 3)
-               => 1
-          (elt [1 2 3 4] 4)
-               error-->Args out of range: [1 2 3 4], 4
-          (elt [1 2 3 4] -1)
-               error-->Args out of range: [1 2 3 4], -1
-
-     This function generalizes `aref' (*note Array Functions::) and
-     `nth' (*note List Elements::).
-
-\1f
-File: lispref.info,  Node: Arrays,  Next: Array Functions,  Prev: Sequence Functions,  Up: Sequences Arrays Vectors
-
-Arrays
-======
+          ---------- Echo Area ----------
+          Resumed!

 
 

-   An "array" object has slots that hold a number of other Lisp
-objects, called the elements of the array.  Any element of an array may
-be accessed in constant time.  In contrast, an element of a list
-requires access time that is proportional to the position of the element
-in the list.
+ - Variable: suspend-hook
+     This variable is a normal hook run before suspending.

 
 

-   When you create an array, you must specify how many elements it has.
-The amount of space allocated depends on the number of elements.
-Therefore, it is impossible to change the size of an array once it is
-created; you cannot add or remove elements.  However, you can replace an
-element with a different value.
+ - Variable: suspend-resume-hook
+     This variable is a normal hook run after suspending.

 
 

-   XEmacs defines three types of array, all of which are
-one-dimensional: "strings", "vectors", and "bit vectors".  A vector is a
-general array; its elements can be any Lisp objects.  A string is a
-specialized array; its elements must be characters.  A bit vector is
-another specialized array; its elements must be bits (an integer, either
-0 or 1).  Each type of array has its own read syntax.  *Note String
-Type::, *Note Vector Type::, and *Note Bit Vector Type::.
+\1f
+File: lispref.info,  Node: System Environment,  Next: User Identification,  Prev: Getting Out,  Up: System Interface

 
 

-   All kinds of array share these characteristics:
+Operating System Environment
+============================

 
 

-   * The first element of an array has index zero, the second element
-     has index 1, and so on.  This is called "zero-origin" indexing.
-     For example, an array of four elements has indices 0, 1, 2, and 3.
+XEmacs provides access to variables in the operating system environment
+through various functions.  These variables include the name of the
+system, the user's UID, and so on.

 
 

-   * The elements of an array may be referenced or changed with the
-     functions `aref' and `aset', respectively (*note Array
-     Functions::).
+ - Variable: system-type
+     The value of this variable is a symbol indicating the type of
+     operating system XEmacs is operating on.  Here is a table of the
+     possible values:

 
 

-   In principle, if you wish to have an array of text characters, you
-could use either a string or a vector.  In practice, we always choose
-strings for such applications, for four reasons:
+    `aix-v3'
+          AIX.

 
 

-   * They usually occupy one-fourth the space of a vector of the same
-     elements.  (This is one-eighth the space for 64-bit machines such
-     as the DEC Alpha, and may also be different when MULE support is
-     compiled into XEmacs.)
+    `berkeley-unix'
+          Berkeley BSD.

 
 

-   * Strings are printed in a way that shows the contents more clearly
-     as characters.
+    `dgux'
+          Data General DGUX operating system.

 
 

-   * Strings can hold extent and text properties.  *Note Extents::,
-     *Note Text Properties::.
+    `gnu'
+          A GNU system using the GNU HURD and Mach.

 
 

-   * Many of the specialized editing and I/O facilities of XEmacs
-     accept only strings.  For example, you cannot insert a vector of
-     characters into a buffer the way you can insert a string.  *Note
-     Strings and Characters::.
+    `hpux'
+          Hewlett-Packard HPUX operating system.

 
 

-   By contrast, for an array of keyboard input characters (such as a key
-sequence), a vector may be necessary, because many keyboard input
-characters are non-printable and are represented with symbols rather
-than with characters.  *Note Key Sequence Input::.
+    `irix'
+          Silicon Graphics Irix system.

 
 

-   Similarly, when representing an array of bits, a bit vector has the
-following advantages over a regular vector:
+    `linux'
+          A GNU system using the Linux kernel.

 
 

-   * They occupy 1/32nd the space of a vector of the same elements.
-     (1/64th on 64-bit machines such as the DEC Alpha.)
+    `ms-dos'
+          Microsoft MS-DOS "operating system."

 
 

-   * Bit vectors are printed in a way that shows the contents more
-     clearly as bits.
+    `next-mach'
+          NeXT Mach-based system.

 
 

-\1f
-File: lispref.info,  Node: Array Functions,  Next: Vectors,  Prev: Arrays,  Up: Sequences Arrays Vectors
+    `rtu'
+          Masscomp RTU, UCB universe.

 
 

-Functions that Operate on Arrays
-================================
+    `unisoft-unix'
+          UniSoft UniPlus.

 
 

-   In this section, we describe the functions that accept strings,
-vectors, and bit vectors.
+    `usg-unix-v'
+          AT&T System V.

 
 

- - Function: arrayp object
-     This function returns `t' if OBJECT is an array (i.e., a string,
-     vector, or bit vector).
+    `windows-nt'
+          Microsoft windows NT.

 
 

-          (arrayp "asdf")
-          => t
-          (arrayp [a])
-          => t
-          (arrayp #*101)
-          => t
+    `xenix'
+          SCO Xenix 386.

 
 

- - Function: aref array index
-     This function returns the INDEXth element of ARRAY.  The first
-     element is at index zero.
+     We do not wish to add new symbols to make finer distinctions
+     unless it is absolutely necessary!  In fact, we hope to eliminate
+     some of these alternatives in the future.  We recommend using
+     `system-configuration' to distinguish between different operating
+     systems.

 
 

-          (setq primes [2 3 5 7 11 13])
-               => [2 3 5 7 11 13]
-          (aref primes 4)
-               => 11
-          (elt primes 4)
-               => 11
-          
-          (aref "abcdefg" 1)
-               => ?b
-          
-          (aref #*1101 2)
-               => 0
+ - Variable: system-configuration
+     This variable holds the three-part configuration name for the
+     hardware/software configuration of your system, as a string.  The
+     convenient way to test parts of this string is with `string-match'.

 
 

-     See also the function `elt', in *Note Sequence Functions::.
+ - Function: system-name
+     This function returns the name of the machine you are running on.
+          (system-name)
+               => "prep.ai.mit.edu"

 
 

- - Function: aset array index object
-     This function sets the INDEXth element of ARRAY to be OBJECT.  It
-     returns OBJECT.
+   The symbol `system-name' is a variable as well as a function.  In
+fact, the function returns whatever value the variable `system-name'
+currently holds.  Thus, you can set the variable `system-name' in case
+Emacs is confused about the name of your system.  The variable is also
+useful for constructing frame titles (*note Frame Titles::).

 
 

-          (setq w [foo bar baz])
-               => [foo bar baz]
-          (aset w 0 'fu)
-               => fu
-          w
-               => [fu bar baz]
-          
-          (setq x "asdfasfd")
-               => "asdfasfd"
-          (aset x 3 ?Z)
-               => ?Z
-          x
-               => "asdZasfd"
-          
-          (setq bv #*1111)
-               => #*1111
-          (aset bv 2 0)
-               => 0
-          bv
-               => #*1101
-
-     If ARRAY is a string and OBJECT is not a character, a
-     `wrong-type-argument' error results.
-
- - Function: fillarray array object
-     This function fills the array ARRAY with OBJECT, so that each
-     element of ARRAY is OBJECT.  It returns ARRAY.
-
-          (setq a [a b c d e f g])
-               => [a b c d e f g]
-          (fillarray a 0)
-               => [0 0 0 0 0 0 0]
-          a
-               => [0 0 0 0 0 0 0]
+ - Variable: mail-host-address
+     If this variable is non-`nil', it is used instead of `system-name'
+     for purposes of generating email addresses.  For example, it is
+     used when constructing the default value of `user-mail-address'.
+     *Note User Identification::.  (Since this is done when XEmacs
+     starts up, the value actually used is the one saved when XEmacs
+     was dumped.  *Note Building XEmacs::.)
+
+ - Command: getenv var &optional interactivep
+     This function returns the value of the environment variable VAR,
+     as a string.  Within XEmacs, the environment variable values are
+     kept in the Lisp variable `process-environment'.
+
+     When invoked interactively, `getenv' prints the value in the echo
+     area.
+
+          (getenv "USER")
+               => "lewis"

           
           

-          (setq s "When in the course")
-               => "When in the course"
-          (fillarray s ?-)
-               => "------------------"
+          lewis@slug[10] % printenv
+          PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
+          USER=lewis
+          TERM=ibmapa16
+          SHELL=/bin/csh
+          HOME=/user/lewis
+
+ - Command: setenv variable &optional value unset
+     This command sets the value of the environment variable named
+     VARIABLE to VALUE.  Both arguments should be strings.  This
+     function works by modifying `process-environment'; binding that
+     variable with `let' is also reasonable practice.
+
+ - Variable: process-environment
+     This variable is a list of strings, each describing one environment
+     variable.  The functions `getenv' and `setenv' work by
+     manipulating this variable.
+
+          process-environment
+          => ("l=/usr/stanford/lib/gnuemacs/lisp"
+              "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
+              "USER=lewis"
+              "TERM=ibmapa16"
+              "SHELL=/bin/csh"
+              "HOME=/user/lewis")
+
+ - Variable: path-separator
+     This variable holds a string which says which character separates
+     directories in a search path (as found in an environment
+     variable).  Its value is `":"' for Unix and GNU systems, and `";"'
+     for MS-DOS and Windows NT.
+
+ - Variable: invocation-name
+     This variable holds the program name under which Emacs was
+     invoked.  The value is a string, and does not include a directory
+     name.
+
+ - Variable: invocation-directory
+     This variable holds the directory from which the Emacs executable
+     was invoked, or perhaps `nil' if that directory cannot be
+     determined.
+
+ - Variable: installation-directory
+     If non-`nil', this is a directory within which to look for the
+     `lib-src' and `etc' subdirectories.  This is non-`nil' when Emacs
+     can't find those directories in their standard installed
+     locations, but can find them in a directory related somehow to the
+     one containing the Emacs executable.
+
+ - Function: load-average &optional use-floats
+     This function returns a list of the current 1-minute, 5-minute and
+     15-minute load averages.  The values are integers that are 100
+     times the system load averages.  (The load averages indicate the
+     number of processes trying to run.)
+
+     When USE-FLOATS is non-`nil', floats will be returned instead of
+     integers.  These floats are not multiplied by 100.
+
+          (load-average)
+               => (169 158 164)
+          (load-average t)
+               => (1.69921875 1.58984375 1.640625)

           
           

-          (setq bv #*1101)
-               => #*1101
-          (fillarray bv 0)
-               => #*0000
+          lewis@rocky[5] % uptime
+            8:06pm  up 16 day(s), 21:57,  40 users,
+           load average: 1.68, 1.59, 1.64
+
+     If the 5-minute or 15-minute load averages are not available,
+     return a shortened list, containing only those averages which are
+     available.

 
 

-     If ARRAY is a string and OBJECT is not a character, a
-     `wrong-type-argument' error results.
+     On some systems, this function may require special privileges to
+     run, or it may be unimplemented for the particular system type.
+     In that case, the function will signal an error.

 
 

-   The general sequence functions `copy-sequence' and `length' are
-often useful for objects known to be arrays.  *Note Sequence
-Functions::.
+ - Function: emacs-pid
+     This function returns the process ID of the Emacs process.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Vectors,  Next: Vector Functions,  Prev: Array Functions,  Up: Sequences Arrays Vectors
+File: lispref.info,  Node: User Identification,  Next: Time of Day,  Prev: System Environment,  Up: System Interface

 
 

-Vectors
-=======
+User Identification
+===================

 
 

-   Arrays in Lisp, like arrays in most languages, are blocks of memory
-whose elements can be accessed in constant time.  A "vector" is a
-general-purpose array; its elements can be any Lisp objects.  (The other
-kind of array in XEmacs Lisp is the "string", whose elements must be
-characters.)  Vectors in XEmacs serve as obarrays (vectors of symbols),
-although this is a shortcoming that should be fixed.  They are also used
-internally as part of the representation of a byte-compiled function; if
-you print such a function, you will see a vector in it.
-
-   In XEmacs Lisp, the indices of the elements of a vector start from
-zero and count up from there.
-
-   Vectors are printed with square brackets surrounding the elements.
-Thus, a vector whose elements are the symbols `a', `b' and `a' is
-printed as `[a b a]'.  You can write vectors in the same way in Lisp
-input.
-
-   A vector, like a string or a number, is considered a constant for
-evaluation: the result of evaluating it is the same vector.  This does
-not evaluate or even examine the elements of the vector.  *Note
-Self-Evaluating Forms::.
-
-   Here are examples of these principles:
-
-     (setq avector [1 two '(three) "four" [five]])
-          => [1 two (quote (three)) "four" [five]]
-     (eval avector)
-          => [1 two (quote (three)) "four" [five]]
-     (eq avector (eval avector))
-          => t
+ - Variable: user-mail-address
+     This holds the nominal email address of the user who is using
+     Emacs.  When Emacs starts up, it computes a default value that is
+     usually right, but users often set this themselves when the
+     default value is not right.

 
 

-\1f
-File: lispref.info,  Node: Vector Functions,  Next: Bit Vectors,  Prev: Vectors,  Up: Sequences Arrays Vectors
+ - Function: user-login-name &optional uid
+     If you don't specify UID, this function returns the name under
+     which the user is logged in.  If the environment variable `LOGNAME'
+     is set, that value is used.  Otherwise, if the environment variable
+     `USER' is set, that value is used.  Otherwise, the value is based
+     on the effective UID, not the real UID.

 
 

-Functions That Operate on Vectors
-=================================
+     If you specify UID, the value is the user name that corresponds to
+     UID (which should be an integer).

 
 

-   Here are some functions that relate to vectors:
+          (user-login-name)
+               => "lewis"

 
 

- - Function: vectorp object
-     This function returns `t' if OBJECT is a vector.
+ - Function: user-real-login-name
+     This function returns the user name corresponding to Emacs's real
+     UID.  This ignores the effective UID and ignores the environment
+     variables `LOGNAME' and `USER'.

 
 

-          (vectorp [a])
-               => t
-          (vectorp "asdf")
-               => nil
+ - Variable: user-full-name
+     This variable holds the name of the user running this Emacs.  It is
+     initialized at startup time from the value of `NAME' environment
+     variable.  You can change the value of this variable to alter the
+     result of the `user-full-name' function.

 
 

- - Function: vector &rest objects
-     This function creates and returns a vector whose elements are the
-     arguments, OBJECTS.
+ - Function: user-full-name &optional user
+     This function returns the full name of USER.  If USER is `nil', it
+     defaults to the user running this Emacs.  In that case, the value
+     of `user-full-name' variable, if non-`nil', will be used.

 
 

-          (vector 'foo 23 [bar baz] "rats")
-               => [foo 23 [bar baz] "rats"]
-          (vector)
-               => []
+     If USER is specified explicitly, `user-full-name' variable is
+     ignored.

 
 

- - Function: make-vector length object
-     This function returns a new vector consisting of LENGTH elements,
-     each initialized to OBJECT.
+          (user-full-name)
+               => "Hrvoje Niksic"
+          (setq user-full-name "Hrvoje \"Niksa\" Niksic")
+          (user-full-name)
+               => "Hrvoje \"Niksa\" Niksic"
+          (user-full-name "hniksic")
+               => "Hrvoje Niksic"

 
 

-          (setq sleepy (make-vector 9 'Z))
-               => [Z Z Z Z Z Z Z Z Z]
+   The symbols `user-login-name', `user-real-login-name' and
+`user-full-name' are variables as well as functions.  The functions
+return the same values that the variables hold.  These variables allow
+you to "fake out" Emacs by telling the functions what to return.  The
+variables are also useful for constructing frame titles (*note Frame
+Titles::).

 
 

- - Function: vconcat &rest sequences
-     This function returns a new vector containing all the elements of
-     the SEQUENCES.  The arguments SEQUENCES may be lists, vectors, or
-     strings.  If no SEQUENCES are given, an empty vector is returned.
+ - Function: user-real-uid
+     This function returns the real UID of the user.

 
 

-     The value is a newly constructed vector that is not `eq' to any
-     existing vector.
+          (user-real-uid)
+               => 19

 
 

-          (setq a (vconcat '(A B C) '(D E F)))
-               => [A B C D E F]
-          (eq a (vconcat a))
-               => nil
-          (vconcat)
-               => []
-          (vconcat [A B C] "aa" '(foo (6 7)))
-               => [A B C 97 97 foo (6 7)]
+ - Function: user-uid
+     This function returns the effective UID of the user.
+
+ - Function: user-home-directory
+     This function returns the "`HOME'" directory of the user, and is
+     intended to replace occurrences of "`(getenv "HOME")'".  Under
+     Unix systems, the following is done:
+
+       1. Return the value of "`(getenv "HOME")'", if set.
+
+       2. Return "/", as a fallback, but issue a warning.  (Future
+          versions of XEmacs will also attempt to lookup the `HOME'
+          directory via `getpwent()', but this has not yet been
+          implemented.)

 
 

-     The `vconcat' function also allows integers as arguments.  It
-     converts them to strings of digits, making up the decimal print
-     representation of the integer, and then uses the strings instead
-     of the original integers.  *Don't use this feature; we plan to
-     eliminate it.  If you already use this feature, change your
-     programs now!*  The proper way to convert an integer to a decimal
-     number in this way is with `format' (*note Formatting Strings::)
-     or `number-to-string' (*note String Conversion::).
+     Under MS Windows, this is done:

 
 

-     For other concatenation functions, see `mapconcat' in *Note
-     Mapping Functions::, `concat' in *Note Creating Strings::, `append'
-     in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
-     Functions::.
+       1. Return the value of "`(getenv "HOME")'", if set.

 
 

-   The `append' function provides a way to convert a vector into a list
-with the same elements (*note Building Lists::):
+       2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
+          both set, return the concatenation (the following description
+          uses MS Windows environment variable substitution syntax):
+          `%HOMEDRIVE%%HOMEDIR%'.

 
 

-     (setq avector [1 two (quote (three)) "four" [five]])
-          => [1 two (quote (three)) "four" [five]]
-     (append avector nil)
-          => (1 two (quote (three)) "four" [five])
+       3. Return "C:\", as a fallback, but issue a warning.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Bit Vectors,  Next: Bit Vector Functions,  Prev: Vector Functions,  Up: Sequences Arrays Vectors
+File: lispref.info,  Node: Time of Day,  Next: Time Conversion,  Prev: User Identification,  Up: System Interface

 
 

-Bit Vectors
+Time of Day

 ===========
 
 ===========
 

-   Bit vectors are specialized vectors that can only represent arrays
-of 1's and 0's.  Bit vectors have a very efficient representation and
-are useful for representing sets of boolean (true or false) values.
+This section explains how to determine the current time and the time
+zone.
+
+ - Function: current-time-string &optional time-value
+     This function returns the current time and date as a
+     humanly-readable string.  The format of the string is unvarying;
+     the number of characters used for each part is always the same, so
+     you can reliably use `substring' to extract pieces of it.  It is
+     wise to count the characters from the beginning of the string
+     rather than from the end, as additional information may be added
+     at the end.
+
+     The argument TIME-VALUE, if given, specifies a time to format
+     instead of the current time.  The argument should be a list whose
+     first two elements are integers.  Thus, you can use times obtained
+     from `current-time' (see below) and from `file-attributes' (*note
+     File Attributes::).
+
+          (current-time-string)
+               => "Wed Oct 14 22:21:05 1987"
+
+ - Function: current-time
+     This function returns the system's time value as a list of three
+     integers: `(HIGH LOW MICROSEC)'.  The integers HIGH and LOW
+     combine to give the number of seconds since 0:00 January 1, 1970,
+     which is HIGH * 2**16 + LOW.
+
+     The third element, MICROSEC, gives the microseconds since the
+     start of the current second (or 0 for systems that return time
+     only on the resolution of a second).
+
+     The first two elements can be compared with file time values such
+     as you get with the function `file-attributes'.  *Note File
+     Attributes::.
+
+ - Function: current-time-zone &optional time-value
+     This function returns a list describing the time zone that the
+     user is in.
+
+     The value has the form `(OFFSET NAME)'.  Here OFFSET is an integer
+     giving the number of seconds ahead of UTC (east of Greenwich).  A
+     negative value means west of Greenwich.  The second element, NAME
+     is a string giving the name of the time zone.  Both elements
+     change when daylight savings time begins or ends; if the user has
+     specified a time zone that does not use a seasonal time
+     adjustment, then the value is constant through time.
+
+     If the operating system doesn't supply all the information
+     necessary to compute the value, both elements of the list are
+     `nil'.
+
+     The argument TIME-VALUE, if given, specifies a time to analyze
+     instead of the current time.  The argument should be a cons cell
+     containing two integers, or a list whose first two elements are
+     integers.  Thus, you can use times obtained from `current-time'
+     (see above) and from `file-attributes' (*note File Attributes::).

 
 

-   There is no limit on the size of a bit vector.  You could, for
-example, create a bit vector with 100,000 elements if you really wanted
-to.
+\1f
+File: lispref.info,  Node: Time Conversion,  Next: Timers,  Prev: Time of Day,  Up: System Interface

 
 

-   Bit vectors have a special printed representation consisting of `#*'
-followed by the bits of the vector.  For example, a bit vector whose
-elements are 0, 1, 1, 0, and 1, respectively, is printed as
+Time Conversion
+===============

 
 

-     #*01101
+These functions convert time values (lists of two or three integers) to
+strings or to calendrical information.  There is also a function to
+convert calendrical information to a time value.  You can get time
+values from the functions `current-time' (*note Time of Day::) and
+`file-attributes' (*note File Attributes::).

 
 

-   Bit vectors are considered constants for evaluation, like vectors,
-strings, and numbers.  *Note Self-Evaluating Forms::.
+ - Function: format-time-string format-string &optional time
+     This function converts TIME to a string according to
+     FORMAT-STRING.  If TIME is omitted, it defaults to the current
+     time.  The argument FORMAT-STRING may contain `%'-sequences which
+     say to substitute parts of the time.  Here is a table of what the
+     `%'-sequences mean:

 
 

-\1f
-File: lispref.info,  Node: Bit Vector Functions,  Prev: Bit Vectors,  Up: Sequences Arrays Vectors
+    `%a'
+          This stands for the abbreviated name of the day of week.

 
 

-Functions That Operate on Bit Vectors
-=====================================
+    `%A'
+          This stands for the full name of the day of week.

 
 

-   Here are some functions that relate to bit vectors:
+    `%b'
+          This stands for the abbreviated name of the month.

 
 

- - Function: bit-vector-p object
-     This function returns `t' if OBJECT is a bit vector.
+    `%B'
+          This stands for the full name of the month.

 
 

-          (bit-vector-p #*01)
-               => t
-          (bit-vector-p [0 1])
-               => nil
-          (bit-vector-p "01")
-               => nil
+    `%c'
+          This is a synonym for `%x %X'.

 
 

- - Function: bitp object
-     This function returns `t' if OBJECT is either 0 or 1.
+    `%C'
+          This has a locale-specific meaning.  In the default locale
+          (named C), it is equivalent to `%A, %B %e, %Y'.

 
 

- - Function: bit-vector &rest bits
-     This function creates and returns a bit vector whose elements are
-     the arguments BITS.  Each argument must be a bit, i.e. one of the
-     two integers 0 or 1.
+    `%d'
+          This stands for the day of month, zero-padded.

 
 

-          (bit-vector 0 0 0 1 0 0 0 0 1 0)
-               => #*0001000010
-          (bit-vector)
-               => #*
+    `%D'
+          This is a synonym for `%m/%d/%y'.

 
 

- - Function: make-bit-vector length bit
-     This function creates and returns a bit vector consisting of
-     LENGTH elements, each initialized to BIT, which must be one of the
-     two integers 0 or 1.
+    `%e'
+          This stands for the day of month, blank-padded.

 
 

-          (setq picket-fence (make-bit-vector 9 1))
-               => #*111111111
+    `%h'
+          This is a synonym for `%b'.

 
 

- - Function: bvconcat &rest sequences
-     This function returns a new bit vector containing all the elements
-     of the SEQUENCES.  The arguments SEQUENCES may be lists, vectors,
-     or bit vectors, all of whose elements are the integers 0 or 1.  If
-     no SEQUENCES are given, an empty bit vector is returned.
+    `%H'
+          This stands for the hour (00-23).

 
 

-     The value is a newly constructed bit vector that is not `eq' to any
-     existing bit vector.
+    `%I'
+          This stands for the hour (00-12).

 
 

-          (setq a (bvconcat '(1 1 0) '(0 0 1)))
-               => #*110001
-          (eq a (bvconcat a))
-               => nil
-          (bvconcat)
-               => #*
-          (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
-               => #*1000011100001
+    `%j'
+          This stands for the day of the year (001-366).

 
 

-     For other concatenation functions, see `mapconcat' in *Note
-     Mapping Functions::, `concat' in *Note Creating Strings::,
-     `vconcat' in *Note Vector Functions::, and `append' in *Note
-     Building Lists::.
+    `%k'
+          This stands for the hour (0-23), blank padded.

 
 

-   The `append' function provides a way to convert a bit vector into a
-list with the same elements (*note Building Lists::):
+    `%l'
+          This stands for the hour (1-12), blank padded.

 
 

-     (setq bv #*00001110)
-          => #*00001110
-     (append bv nil)
-          => (0 0 0 0 1 1 1 0)
+    `%m'
+          This stands for the month (01-12).

 
 

-\1f
-File: lispref.info,  Node: Symbols,  Next: Evaluation,  Prev: Sequences Arrays Vectors,  Up: Top
+    `%M'
+          This stands for the minute (00-59).
+
+    `%n'
+          This stands for a newline.
+
+    `%p'
+          This stands for `AM' or `PM', as appropriate.
+
+    `%r'
+          This is a synonym for `%I:%M:%S %p'.
+
+    `%R'
+          This is a synonym for `%H:%M'.
+
+    `%S'
+          This stands for the seconds (00-60).
+
+    `%t'
+          This stands for a tab character.
+
+    `%T'
+          This is a synonym for `%H:%M:%S'.
+
+    `%U'
+          This stands for the week of the year (01-52), assuming that
+          weeks start on Sunday.
+
+    `%w'
+          This stands for the numeric day of week (0-6).  Sunday is day
+          0.

 
 

-Symbols
-*******
+    `%W'
+          This stands for the week of the year (01-52), assuming that
+          weeks start on Monday.

 
 

-   A "symbol" is an object with a unique name.  This chapter describes
-symbols, their components, their property lists, and how they are
-created and interned.  Separate chapters describe the use of symbols as
-variables and as function names; see *Note Variables::, and *Note
-Functions::.  For the precise read syntax for symbols, see *Note Symbol
-Type::.
+    `%x'
+          This has a locale-specific meaning.  In the default locale
+          (named C), it is equivalent to `%D'.

 
 

-   You can test whether an arbitrary Lisp object is a symbol with
-`symbolp':
+    `%X'
+          This has a locale-specific meaning.  In the default locale
+          (named C), it is equivalent to `%T'.

 
 

- - Function: symbolp object
-     This function returns `t' if OBJECT is a symbol, `nil' otherwise.
+    `%y'
+          This stands for the year without century (00-99).
+
+    `%Y'
+          This stands for the year with century.
+
+    `%Z'
+          This stands for the time zone abbreviation.
+
+ - Function: decode-time &optional specified-time
+     This function converts a time value into calendrical information.
+     The optional SPECIFIED-TIME should be a list of (HIGH LOW .
+     IGNORED) or (HIGH . LOW), as from `current-time' and
+     `file-attributes', or `nil' to use the current time.
+
+     The return value is a list of nine elements, as follows:
+
+          (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
+
+     Here is what the elements mean:
+
+    SEC
+          The number of seconds past the minute, as an integer between
+          0 and 59.
+
+    MINUTE
+          The number of minutes past the hour, as an integer between 0
+          and 59.
+
+    HOUR
+          The hour of the day, as an integer between 0 and 23.
+
+    DAY
+          The day of the month, as an integer between 1 and 31.
+
+    MONTH
+          The month of the year, as an integer between 1 and 12.
+
+    YEAR
+          The year, an integer typically greater than 1900.
+
+    DOW
+          The day of week, as an integer between 0 and 6, where 0
+          stands for Sunday.
+
+    DST
+          `t' if daylight savings time is effect, otherwise `nil'.
+
+    ZONE
+          An integer indicating the time zone, as the number of seconds
+          east of Greenwich.
+
+     Note that Common Lisp has different meanings for DOW and ZONE.
+
+ - Function: encode-time seconds minutes hour day month year &optional
+          zone
+     This function is the inverse of `decode-time'.  It converts seven
+     items of calendrical data into a time value.  For the meanings of
+     the arguments, see the table above under `decode-time'.
+
+     Year numbers less than 100 are treated just like other year
+     numbers.  If you want them to stand for years above 1900, you must
+     alter them yourself before you call `encode-time'.
+
+     The optional argument ZONE defaults to the current time zone and
+     its daylight savings time rules.  If specified, it can be either a
+     list (as you would get from `current-time-zone') or an integer (as
+     you would get from `decode-time').  The specified zone is used
+     without any further alteration for daylight savings time.
+
+\1f
+File: lispref.info,  Node: Timers,  Next: Terminal Input,  Prev: Time Conversion,  Up: System Interface
+
+Timers for Delayed Execution
+============================
+
+You can set up a timer to call a function at a specified future time.
+
+ - Function: add-timeout secs function object &optional resignal
+     This function adds a timeout, to be signaled after the timeout
+     period has elapsed.  SECS is a number of seconds, expressed as an
+     integer or a float.  FUNCTION will be called after that many
+     seconds have elapsed, with one argument, the given OBJECT.  If the
+     optional RESIGNAL argument is provided, then after this timeout
+     expires, `add-timeout' will automatically be called again with
+     RESIGNAL as the first argument.
+
+     This function returns an object which is the "id" of this
+     particular timeout.  You can pass that object to `disable-timeout'
+     to turn off the timeout before it has been signalled.
+
+     The number of seconds may be expressed as a floating-point number,
+     in which case some fractional part of a second will be used.
+     Caveat: the usable timeout granularity will vary from system to
+     system.
+
+     Adding a timeout causes a timeout event to be returned by
+     `next-event', and the function will be invoked by
+     `dispatch-event', so if XEmacs is in a tight loop, the function
+     will not be invoked until the next call to sit-for or until the
+     return to top-level (the same is true of process filters).
+
+     WARNING: if you are thinking of calling add-timeout from inside of
+     a callback function as a way of resignalling a timeout, think
+     again.  There is a race condition.  That's why the RESIGNAL
+     argument exists.
+
+     (NOTE: In FSF Emacs, this function is called `run-at-time' and has
+     different semantics.)
+
+ - Function: disable-timeout id
+     Cancel the requested action for ID, which should be a value
+     previously returned by `add-timeout'.  This cancels the effect of
+     that call to `add-timeout'; the arrival of the specified time will
+     not cause anything special to happen.  (NOTE: In FSF Emacs, this
+     function is called `cancel-timer'.)
+
+\1f
+File: lispref.info,  Node: Terminal Input,  Next: Terminal Output,  Prev: Timers,  Up: System Interface
+
+Terminal Input
+==============
+
+This section describes functions and variables for recording or
+manipulating terminal input.  See *Note Display::, for related
+functions.

 
 * Menu:
 
 
 * Menu:
 

-* 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.
+* Input Modes::                Options for how input is processed.
+* Translating Input::   Low level conversion of some characters or events
+                         into others.
+* Recording Input::    Saving histories of recent or all input events.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Symbol Components,  Next: Definitions,  Up: Symbols
+File: lispref.info,  Node: Input Modes,  Next: Translating Input,  Up: Terminal Input
+
+Input Modes
+-----------
+
+ - Function: set-input-mode interrupt flow meta &optional quit-char
+          console
+     This function sets the mode for reading keyboard input.  If
+     INTERRUPT is non-null, then XEmacs uses input interrupts.  If it is
+     `nil', then it uses CBREAK mode.  When XEmacs communicates
+     directly with X, it ignores this argument and uses interrupts if
+     that is the way it knows how to communicate.
+
+     If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
+     flow control for output to the terminal.  This has no effect except
+     in CBREAK mode.  *Note Flow Control::.
+
+     The default setting is system dependent.  Some systems always use
+     CBREAK mode regardless of what is specified.
+
+     The argument META controls support for input character codes above
+     127.  If META is `t', XEmacs converts characters with the 8th bit
+     set into Meta characters.  If META is `nil', XEmacs disregards the
+     8th bit; this is necessary when the terminal uses it as a parity
+     bit.  If META is neither `t' nor `nil', XEmacs uses all 8 bits of
+     input unchanged.  This is good for terminals using European 8-bit
+     character sets.
+
+     If QUIT-CHAR is non-`nil', it specifies the character to use for
+     quitting.  Normally this character is `C-g'.  *Note Quitting::.
+
+   The `current-input-mode' function returns the input mode settings
+XEmacs is currently using.
+
+ - Function: current-input-mode &optional console
+     This function returns current mode for reading keyboard input.  It
+     returns a list, corresponding to the arguments of `set-input-mode',
+     of the form `(INTERRUPT FLOW META QUIT)' in which:
+    INTERRUPT
+          is non-`nil' when XEmacs is using interrupt-driven input.  If
+          `nil', Emacs is using CBREAK mode.
+
+    FLOW
+          is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
+          control for output to the terminal.  This value has no effect
+          unless INTERRUPT is non-`nil'.
+
+    META
+          is `t' if XEmacs treats the eighth bit of input characters as
+          the meta bit; `nil' means XEmacs clears the eighth bit of
+          every input character; any other value means XEmacs uses all
+          eight bits as the basic character code.
+
+    QUIT
+          is the character XEmacs currently uses for quitting, usually
+          `C-g'.

 
 

-Symbol Components
-=================
+\1f
+File: lispref.info,  Node: Translating Input,  Next: Recording Input,  Prev: Input Modes,  Up: Terminal Input
+
+Translating Input Events
+------------------------
+
+This section describes features for translating input events into other
+input events before they become part of key sequences.
+
+ - Variable: function-key-map
+     This variable holds a keymap that describes the character sequences
+     sent by function keys on an ordinary character terminal.  This
+     keymap uses the same data structure as other keymaps, but is used
+     differently: it specifies translations to make while reading
+     events.
+
+     If `function-key-map' "binds" a key sequence K to a vector V, then
+     when K appears as a subsequence _anywhere_ in a key sequence, it
+     is replaced with the events in V.
+
+     For example, VT100 terminals send `<ESC> O P' when the keypad PF1
+     key is pressed.  Therefore, we want XEmacs to translate that
+     sequence of events into the single event `pf1'.  We accomplish
+     this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
+     when using a VT100.
+
+     Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+     P'; later the function `read-key-sequence' translates this back
+     into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
+
+     Entries in `function-key-map' are ignored if they conflict with
+     bindings made in the minor mode, local, or global keymaps.  The
+     intent is that the character sequences that function keys send
+     should not have command bindings in their own right.
+
+     The value of `function-key-map' is usually set up automatically
+     according to the terminal's Terminfo or Termcap entry, but
+     sometimes those need help from terminal-specific Lisp files.
+     XEmacs comes with terminal-specific files for many common
+     terminals; their main purpose is to make entries in
+     `function-key-map' beyond those that can be deduced from Termcap
+     and Terminfo.  *Note Terminal-Specific::.
+
+     Emacs versions 18 and earlier used totally different means of
+     detecting the character sequences that represent function keys.
+
+ - Variable: key-translation-map
+     This variable is another keymap used just like `function-key-map'
+     to translate input events into other events.  It differs from
+     `function-key-map' in two ways:
+
+        * `key-translation-map' goes to work after `function-key-map' is
+          finished; it receives the results of translation by
+          `function-key-map'.
+
+        * `key-translation-map' overrides actual key bindings.
+
+     The intent of `key-translation-map' is for users to map one
+     character set to another, including ordinary characters normally
+     bound to `self-insert-command'.
+
+   You can use `function-key-map' or `key-translation-map' for more
+than simple aliases, by using a function, instead of a key sequence, as
+the "translation" of a key.  Then this function is called to compute
+the translation of that key.
+
+   The key translation function receives one argument, which is the
+prompt that was specified in `read-key-sequence'--or `nil' if the key
+sequence is being read by the editor command loop.  In most cases you
+can ignore the prompt value.
+
+   If the function reads input itself, it can have the effect of
+altering the event that follows.  For example, here's how to define
+`C-c h' to turn the character that follows into a Hyper character:
+
+     (defun hyperify (prompt)
+       (let ((e (read-event)))
+         (vector (if (numberp e)
+                     (logior (lsh 1 20) e)
+                   (if (memq 'hyper (event-modifiers e))
+                       e
+                     (add-event-modifier "H-" e))))))
+     
+     (defun add-event-modifier (string e)
+       (let ((symbol (if (symbolp e) e (car e))))
+         (setq symbol (intern (concat string
+                                      (symbol-name symbol))))
+         (if (symbolp e)
+             symbol
+           (cons symbol (cdr e)))))
+     
+     (define-key function-key-map "\C-ch" 'hyperify)
+
+   The `iso-transl' library uses this feature to provide a way of
+inputting non-ASCII Latin-1 characters.

 
 

-   Each symbol has four components (or "cells"), each of which
-references another object:
-
-Print name
-     The "print name cell" holds a string that names the symbol for
-     reading and printing.  See `symbol-name' in *Note Creating
-     Symbols::.
-
-Value
-     The "value cell" holds the current value of the symbol as a
-     variable.  When a symbol is used as a form, the value of the form
-     is the contents of the symbol's value cell.  See `symbol-value' in
-     *Note Accessing Variables::.
-
-Function
-     The "function cell" holds the function definition of the symbol.
-     When a symbol is used as a function, its function definition is
-     used in its place.  This cell is also used to make a symbol stand
-     for a keymap or a keyboard macro, for editor command execution.
-     Because each symbol has separate value and function cells,
-     variables and function names do not conflict.  See
-     `symbol-function' in *Note Function Cells::.
-
-Property list
-     The "property list cell" holds the property list of the symbol.
-     See `symbol-plist' in *Note Symbol Properties::.
-
-   The print name cell always holds a string, and cannot be changed.
-The other three cells can be set individually to any specified Lisp
-object.
-
-   The print name cell holds the string that is the name of the symbol.
-Since symbols are represented textually by their names, it is important
-not to have two symbols with the same name.  The Lisp reader ensures
-this: every time it reads a symbol, it looks for an existing symbol with
-the specified name before it creates a new one.  (In XEmacs Lisp, this
-lookup uses a hashing algorithm and an obarray; see *Note Creating
-Symbols::.)
-
-   In normal usage, the function cell usually contains a function or
-macro, as that is what the Lisp interpreter expects to see there (*note
-Evaluation::).  Keyboard macros (*note Keyboard Macros::), keymaps
-(*note Keymaps::) and autoload objects (*note Autoloading::) are also
-sometimes stored in the function cell of symbols.  We often refer to
-"the function `foo'" when we really mean the function stored in the
-function cell of the symbol `foo'.  We make the distinction only when
-necessary.
-
-   The property list cell normally should hold a correctly formatted
-property list (*note Property Lists::), as a number of functions expect
-to see a property list there.
-
-   The function cell or the value cell may be "void", which means that
-the cell does not reference any object.  (This is not the same thing as
-holding the symbol `void', nor the same as holding the symbol `nil'.)
-Examining a cell that is void results in an error, such as `Symbol's
-value as variable is void'.
-
-   The four functions `symbol-name', `symbol-value', `symbol-plist',
-and `symbol-function' return the contents of the four cells of a
-symbol.  Here as an example we show the contents of the four cells of
-the symbol `buffer-file-name':
-
-     (symbol-name 'buffer-file-name)
-          => "buffer-file-name"
-     (symbol-value 'buffer-file-name)
-          => "/gnu/elisp/symbols.texi"
-     (symbol-plist 'buffer-file-name)
-          => (variable-documentation 29529)
-     (symbol-function 'buffer-file-name)
-          => #<subr buffer-file-name>
-
-Because this symbol is the variable which holds the name of the file
-being visited in the current buffer, the value cell contents we see are
-the name of the source file of this chapter of the XEmacs Lisp Reference
-Manual.  The property list cell contains the list
-`(variable-documentation 29529)' which tells the documentation
-functions where to find the documentation string for the variable
-`buffer-file-name' in the `DOC' file.  (29529 is the offset from the
-beginning of the `DOC' file to where that documentation string begins.)
-The function cell contains the function for returning the name of the
-file.  `buffer-file-name' names a primitive function, which has no read
-syntax and prints in hash notation (*note Primitive Function Type::).  A
-symbol naming a function written in Lisp would have a lambda expression
-(or a byte-code object) in this cell.
-
-\1f
-File: lispref.info,  Node: Definitions,  Next: Creating Symbols,  Prev: Symbol Components,  Up: Symbols
-
-Defining Symbols
-================
+\1f
+File: lispref.info,  Node: Recording Input,  Prev: Translating Input,  Up: Terminal Input

 
 

-   A "definition" in Lisp is a special form that announces your
-intention to use a certain symbol in a particular way.  In XEmacs Lisp,
-you can define a symbol as a variable, or define it as a function (or
-macro), or both independently.
-
-   A definition construct typically specifies a value or meaning for the
-symbol for one kind of use, plus documentation for its meaning when used
-in this way.  Thus, when you define a symbol as a variable, you can
-supply an initial value for the variable, plus documentation for the
-variable.
-
-   `defvar' and `defconst' are special forms that define a symbol as a
-global variable.  They are documented in detail in *Note Defining
-Variables::.
-
-   `defun' defines a symbol as a function, creating a lambda expression
-and storing it in the function cell of the symbol.  This lambda
-expression thus becomes the function definition of the symbol.  (The
-term "function definition", meaning the contents of the function cell,
-is derived from the idea that `defun' gives the symbol its definition
-as a function.)  `defsubst', `define-function' and `defalias' are other
-ways of defining a function.  *Note Functions::.
-
-   `defmacro' defines a symbol as a macro.  It creates a macro object
-and stores it in the function cell of the symbol.  Note that a given
-symbol can be a macro or a function, but not both at once, because both
-macro and function definitions are kept in the function cell, and that
-cell can hold only one Lisp object at any given time.  *Note Macros::.
-
-   In XEmacs Lisp, a definition is not required in order to use a symbol
-as a variable or function.  Thus, you can make a symbol a global
-variable with `setq', whether you define it first or not.  The real
-purpose of definitions is to guide programmers and programming tools.
-They inform programmers who read the code that certain symbols are
-_intended_ to be used as variables, or as functions.  In addition,
-utilities such as `etags' and `make-docfile' recognize definitions, and
-add appropriate information to tag tables and the `DOC' file. *Note
-Accessing Documentation::.
-
-\1f
-File: lispref.info,  Node: Creating Symbols,  Next: Symbol Properties,  Prev: Definitions,  Up: Symbols
-
-Creating and Interning Symbols
-==============================
+Recording Input
+---------------

 
 

-   To understand how symbols are created in XEmacs Lisp, you must know
-how Lisp reads them.  Lisp must ensure that it finds the same symbol
-every time it reads the same set of characters.  Failure to do so would
-cause complete confusion.
-
-   When the Lisp reader encounters a symbol, it reads all the characters
-of the name.  Then it "hashes" those characters to find an index in a
-table called an "obarray".  Hashing is an efficient method of looking
-something up.  For example, instead of searching a telephone book cover
-to cover when looking up Jan Jones, you start with the J's and go from
-there.  That is a simple version of hashing.  Each element of the
-obarray is a "bucket" which holds all the symbols with a given hash
-code; to look for a given name, it is sufficient to look through all
-the symbols in the bucket for that name's hash code.
-
-   If a symbol with the desired name is found, the reader uses that
-symbol.  If the obarray does not contain a symbol with that name, the
-reader makes a new symbol and adds it to the obarray.  Finding or adding
-a symbol with a certain name is called "interning" it, and the symbol
-is then called an "interned symbol".
-
-   Interning ensures that each obarray has just one symbol with any
-particular name.  Other like-named symbols may exist, but not in the
-same obarray.  Thus, the reader gets the same symbols for the same
-names, as long as you keep reading with the same obarray.
-
-   No obarray contains all symbols; in fact, some symbols are not in any
-obarray.  They are called "uninterned symbols".  An uninterned symbol
-has the same four cells as other symbols; however, the only way to gain
-access to it is by finding it in some other object or as the value of a
-variable.
-
-   In XEmacs Lisp, an obarray is actually a vector.  Each element of the
-vector is a bucket; its value is either an interned symbol whose name
-hashes to that bucket, or 0 if the bucket is empty.  Each interned
-symbol has an internal link (invisible to the user) to the next symbol
-in the bucket.  Because these links are invisible, there is no way to
-find all the symbols in an obarray except using `mapatoms' (below).
-The order of symbols in a bucket is not significant.
-
-   In an empty obarray, every element is 0, and you can create an
-obarray with `(make-vector LENGTH 0)'.  *This is the only valid way to
-create an obarray.*  Prime numbers as lengths tend to result in good
-hashing; lengths one less than a power of two are also good.
-
-   *Do not try to put symbols in an obarray yourself.*  This does not
-work--only `intern' can enter a symbol in an obarray properly.  *Do not
-try to intern one symbol in two obarrays.*  This would garble both
-obarrays, because a symbol has just one slot to hold the following
-symbol in the obarray bucket.  The results would be unpredictable.
-
-   It is possible for two different symbols to have the same name in
-different obarrays; these symbols are not `eq' or `equal'.  However,
-this normally happens only as part of the abbrev mechanism (*note
-Abbrevs::).
-
-     Common Lisp note: In Common Lisp, a single symbol may be interned
-     in several obarrays.
-
-   Most of the functions below take a name and sometimes an obarray as
-arguments.  A `wrong-type-argument' error is signaled if the name is
-not a string, or if the obarray is not a vector.
-
- - Function: symbol-name symbol
-     This function returns the string that is SYMBOL's name.  For
-     example:
-
-          (symbol-name 'foo)
-               => "foo"
-
-     Changing the string by substituting characters, etc, does change
-     the name of the symbol, but fails to update the obarray, so don't
-     do it!
-
- - Function: make-symbol name
-     This function returns a newly-allocated, uninterned symbol whose
-     name is NAME (which must be a string).  Its value and function
-     definition are void, and its property list is `nil'.  In the
-     example below, the value of `sym' is not `eq' to `foo' because it
-     is a distinct uninterned symbol whose name is also `foo'.
-
-          (setq sym (make-symbol "foo"))
-               => foo
-          (eq sym 'foo)
-               => nil
+ - Function: recent-keys &optional number
+     This function returns a vector containing recent input events from
+     the keyboard or mouse.  By default, 100 events are recorded, which
+     is how many `recent-keys' returns.

 
 

- - Function: intern name &optional obarray
-     This function returns the interned symbol whose name is NAME.  If
-     there is no such symbol in the obarray OBARRAY, `intern' creates a
-     new one, adds it to the obarray, and returns it.  If OBARRAY is
-     omitted, the value of the global variable `obarray' is used.
+     All input events are included, whether or not they were used as
+     parts of key sequences.  Thus, you always get the last 100 inputs,
+     not counting keyboard macros.  (Events from keyboard macros are
+     excluded because they are less interesting for debugging; it
+     should be enough to see the events that invoked the macros.)

 
 

-          (setq sym (intern "foo"))
-               => foo
-          (eq sym 'foo)
-               => t
-          
-          (setq sym1 (intern "foo" other-obarray))
-               => foo
-          (eq sym 'foo)
-               => nil
+     If NUMBER is specified, not more than NUMBER events will be
+     returned.  You may change the number of stored events using
+     `set-recent-keys-ring-size'.
+
+ - Function: recent-keys-ring-size
+     This function returns the number of recent events stored
+     internally.  This is also the maximum number of events
+     `recent-keys' can return.  By default, 100 events are stored.
+
+ - Function: set-recent-keys-ring-size size
+     This function changes the number of events stored by XEmacs and
+     returned by `recent-keys'.
+
+     For example, `(set-recent-keys-ring-size 250)' will make XEmacs
+     remember last 250 events and will make `recent-keys' return last
+     250 events by default.
+
+ - Command: open-dribble-file filename
+     This function opens a "dribble file" named FILENAME.  When a
+     dribble file is open, each input event from the keyboard or mouse
+     (but not those from keyboard macros) is written in that file.  A
+     non-character event is expressed using its printed representation
+     surrounded by `<...>'.
+
+     You close the dribble file by calling this function with an
+     argument of `nil'.

 
 

- - Function: intern-soft name &optional obarray
-     This function returns the symbol in OBARRAY whose name is NAME, or
-     `nil' if OBARRAY has no symbol with that name.  Therefore, you can
-     use `intern-soft' to test whether a symbol with a given name is
-     already interned.  If OBARRAY is omitted, the value of the global
-     variable `obarray' is used.
+     This function is normally used to record the input necessary to
+     trigger an XEmacs bug, for the sake of a bug report.

 
 

-          (intern-soft "frazzle")        ; No such symbol exists.
+          (open-dribble-file "~/dribble")

                => nil
                => nil

-          (make-symbol "frazzle")        ; Create an uninterned one.
-               => frazzle
-          (intern-soft "frazzle")        ; That one cannot be found.
+
+   See also the `open-termscript' function (*note Terminal Output::).
+
+\1f
+File: lispref.info,  Node: Terminal Output,  Next: Flow Control,  Prev: Terminal Input,  Up: System Interface
+
+Terminal Output
+===============
+
+The terminal output functions send output to the terminal or keep track
+of output sent to the terminal.  The function `device-baud-rate' tells
+you what XEmacs thinks is the output speed of the terminal.
+
+ - Function: device-baud-rate &optional device
+     This function's value is the output speed of the terminal
+     associated with DEVICE, as far as XEmacs knows.  DEVICE defaults
+     to the selected device (usually the only device) if omitted.
+     Changing this value does not change the speed of actual data
+     transmission, but the value is used for calculations such as
+     padding.  This value has no effect for window-system devices.
+     (This is different in FSF Emacs, where the baud rate also affects
+     decisions about whether to scroll part of the screen or repaint,
+     even when using a window system.)
+
+     The value is measured in bits per second.
+
+   XEmacs attempts to automatically initialize the baud rate by querying
+the terminal.  If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal.  Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+the proper value, but others do not.  If XEmacs has the wrong value, it
+makes decisions that are less than optimal.  To fix the problem, use
+`set-device-baud-rate'.
+
+ - Function: set-device-baud-rate device baud-rate
+     This function sets the output speed of DEVICE.  See
+     `device-baud-rate'.  DEVICE defaults to the selected device
+     (usually the only device) if `nil'.
+
+ - Function: send-string-to-terminal char-or-string &optional stdout-p
+          device
+     This function sends CHAR-OR-STRING to the terminal without
+     alteration.  Control characters in CHAR-OR-STRING have
+     terminal-dependent effects.
+
+     If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+     stdout if STDOUT-P is non-`nil'.  Otherwise, DEVICE should be a
+     tty or stream device, and the function writes to the device's
+     normal or error output, according to STDOUT-P.
+
+     One use of this function is to define function keys on terminals
+     that have downloadable function key definitions.  For example,
+     this is how on certain terminals to define function key 4 to move
+     forward four characters (by transmitting the characters `C-u C-f'
+     to the computer):
+
+          (send-string-to-terminal "\eF4\^U\^F")

                => nil
                => nil

-          (setq sym (intern "frazzle"))  ; Create an interned one.
-               => frazzle
-          (intern-soft "frazzle")        ; That one can be found!
-               => frazzle
-          (eq sym 'frazzle)              ; And it is the same one.
-               => t

 
 

- - Variable: obarray
-     This variable is the standard obarray for use by `intern' and
-     `read'.
-
- - Function: mapatoms function &optional obarray
-     This function calls FUNCTION for each symbol in the obarray
-     OBARRAY.  It returns `nil'.  If OBARRAY is omitted, it defaults to
-     the value of `obarray', the standard obarray for ordinary symbols.
-
-          (setq count 0)
-               => 0
-          (defun count-syms (s)
-            (setq count (1+ count)))
-               => count-syms
-          (mapatoms 'count-syms)
+ - Command: open-termscript filename
+     This function is used to open a "termscript file" that will record
+     all the characters sent by XEmacs to the terminal. (If there are
+     multiple tty or stream devices, all characters sent to all such
+     devices are recorded.) The function returns `nil'.  Termscript
+     files are useful for investigating problems where XEmacs garbles
+     the screen, problems that are due to incorrect Termcap entries or
+     to undesirable settings of terminal options more often than to
+     actual XEmacs bugs.  Once you are certain which characters were
+     actually output, you can determine reliably whether they
+     correspond to the Termcap specifications in use.
+
+     A `nil' value for FILENAME stops recording terminal output.
+
+     See also `open-dribble-file' in *Note Terminal Input::.
+
+          (open-termscript "../junk/termscript")

                => nil
                => nil

-          count
-               => 1871

 
 

-     See `documentation' in *Note Accessing Documentation::, for another
-     example using `mapatoms'.
+\1f
+File: lispref.info,  Node: Flow Control,  Next: Batch Mode,  Prev: Terminal Output,  Up: System Interface
+
+Flow Control
+============
+
+This section attempts to answer the question "Why does XEmacs choose to
+use flow-control characters in its command character set?"  For a
+second view on this issue, read the comments on flow control in the
+`emacs/INSTALL' file from the distribution; for help with Termcap
+entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
+
+   At one time, most terminals did not need flow control, and none used
+`C-s' and `C-q' for flow control.  Therefore, the choice of `C-s' and
+`C-q' as command characters was uncontroversial.  XEmacs, for economy
+of keystrokes and portability, used nearly all the ASCII control
+characters, with mnemonic meanings when possible; thus, `C-s' for
+search and `C-q' for quote.
+
+   Later, some terminals were introduced which required these characters
+for flow control.  They were not very good terminals for full-screen
+editing, so XEmacs maintainers did not pay attention.  In later years,
+flow control with `C-s' and `C-q' became widespread among terminals,
+but by this time it was usually an option.  And the majority of users,
+who can turn flow control off, were unwilling to switch to less
+mnemonic key bindings for the sake of flow control.
+
+   So which usage is "right", XEmacs's or that of some terminal and
+concentrator manufacturers?  This question has no simple answer.
+
+   One reason why we are reluctant to cater to the problems caused by
+`C-s' and `C-q' is that they are gratuitous.  There are other
+techniques (albeit less common in practice) for flow control that
+preserve transparency of the character stream.  Note also that their use
+for flow control is not an official standard.  Interestingly, on the
+model 33 teletype with a paper tape punch (which is very old), `C-s'
+and `C-q' were sent by the computer to turn the punch on and off!
+
+   As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured.  For the mean time,
+XEmacs provides a convenient way of enabling flow control if you want
+it: call the function `enable-flow-control'.
+
+ - Command: enable-flow-control &optional argument
+     This function enables use of `C-s' and `C-q' for output flow
+     control, and provides the characters `C-\' and `C-^' as aliases
+     for them using `keyboard-translate-table' (*note Translating
+     Input::).
+
+     With optional argument ARGUMENT (interactively the prefix
+     argument), enable flow control mode if ARGUMENT is positive; else
+     disable it.
+
+   You can use the function `enable-flow-control-on' in your `.emacs'
+file to enable flow control automatically on certain terminal types.
+
+ - Function: enable-flow-control-on &rest termtypes
+     This function enables flow control, and the aliases `C-\' and
+     `C-^', if the terminal type is one of TERMTYPES.  For example:
+
+          (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
+
+   Here is how `enable-flow-control' does its job:
+
+  1. It sets CBREAK mode for terminal input, and tells the operating
+     system to handle flow control, with `(set-input-mode nil t)'.
+
+  2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
+     into `C-s' and `C-q'.  Except at its very lowest level, XEmacs
+     never knows that the characters typed were anything but `C-s' and
+     `C-q', so you can in effect type them as `C-\' and `C-^' even when
+     they are input for other commands.  *Note Translating Input::.
+
+   If the terminal is the source of the flow control characters, then
+once you enable kernel flow control handling, you probably can make do
+with less padding than normal for that terminal.  You can reduce the
+amount of padding by customizing the Termcap entry.  You can also
+reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
+a smaller speed when calculating the padding needed.  *Note Terminal
+Output::.
+
+\1f
+File: lispref.info,  Node: Batch Mode,  Prev: Flow Control,  Up: System Interface
+
+Batch Mode
+==========
+
+The command line option `-batch' causes XEmacs to run noninteractively.
+In this mode, XEmacs does not read commands from the terminal, it does
+not alter the terminal modes, and it does not expect to be outputting
+to an erasable screen.  The idea is that you specify Lisp programs to
+run; when they are finished, XEmacs should exit.  The way to specify
+the programs to run is with `-l FILE', which loads the library named
+FILE, and `-f FUNCTION', which calls FUNCTION with no arguments.
+
+   Any Lisp program output that would normally go to the echo area,
+either using `message' or using `prin1', etc., with `t' as the stream,
+goes instead to XEmacs's standard error descriptor when in batch mode.
+Thus, XEmacs behaves much like a noninteractive application program.
+(The echo area output that XEmacs itself normally generates, such as
+command echoing, is suppressed entirely.)
+
+ - Function: noninteractive
+     This function returns non-`nil' when XEmacs is running in batch
+     mode.
+
+ - Variable: noninteractive
+     This variable is non-`nil' when XEmacs is running in batch mode.
+     Setting this variable to `nil', however, will not change whether
+     XEmacs is running in batch mode, and will not change the return
+     value of the `noninteractive' function.
+
+\1f
+File: lispref.info,  Node: X-Windows,  Next: ToolTalk Support,  Prev: System Interface,  Up: Top
+
+Functions Specific to the X Window System
+*****************************************

 
 

- - Function: unintern symbol &optional obarray
-     This function deletes SYMBOL from the obarray OBARRAY.  If
-     `symbol' is not actually in the obarray, `unintern' does nothing.
-     If OBARRAY is `nil', the current obarray is used.
+XEmacs provides the concept of "devices", which generalizes connections
+to an X server, a TTY device, etc.  Most information about an X server
+that XEmacs is connected to can be determined through general console
+and device functions.  *Note Consoles and Devices::.  However, there
+are some features of the X Window System that do not generalize well,
+and they are covered specially here.

 
 

-     If you provide a string instead of a symbol as SYMBOL, it stands
-     for a symbol name.  Then `unintern' deletes the symbol (if any) in
-     the obarray which has that name.  If there is no such symbol,
-     `unintern' does nothing.
+* Menu:

 
 

-     If `unintern' does delete a symbol, it returns `t'.  Otherwise it
-     returns `nil'.
+* X Selections::                Transferring text to and from other X clients.
+* X Server::                    Information about the X server connected to
+                                  a particular device.
+* X Miscellaneous::             Other X-specific functions and variables.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Symbol Properties,  Prev: Creating Symbols,  Up: Symbols
+File: lispref.info,  Node: X Selections,  Next: X Server,  Up: X-Windows
+
+X Selections
+============
+
+The X server records a set of "selections" which permit transfer of
+data between application programs.  The various selections are
+distinguished by "selection types", represented in XEmacs by symbols.
+X clients including XEmacs can read or set the selection for any given
+type.
+
+ - Function: x-own-selection data &optional type
+     This function sets a "selection" in the X server.  It takes two
+     arguments: a value, DATA, and the selection type TYPE to assign it
+     to.  DATA may be a string, a cons of two markers, or an extent.
+     In the latter cases, the selection is considered to be the text
+     between the markers, or between the extent's endpoints.
+
+     Each possible TYPE has its own selection value, which changes
+     independently.  The usual values of TYPE are `PRIMARY' and
+     `SECONDARY'; these are symbols with upper-case names, in accord
+     with X Windows conventions.  The default is `PRIMARY'.
+
+     (In FSF Emacs, this function is called `x-set-selection' and takes
+     different arguments.)
+
+ - Function: x-get-selection
+     This function accesses selections set up by XEmacs or by other X
+     clients.  It returns the value of the current primary selection.
+
+ - Function: x-disown-selection &optional secondary-p
+     Assuming we own the selection, this function disowns it.  If
+     SECONDARY-P is non-`nil', the secondary selection instead of the
+     primary selection is discarded.
+
+   The X server also has a set of numbered "cut buffers" which can
+store text or other data being moved between applications.  Cut buffers
+are considered obsolete, but XEmacs supports them for the sake of X
+clients that still use them.
+
+ - Function: x-get-cutbuffer &optional n
+     This function returns the contents of cut buffer number N. (This
+     function is called `x-get-cut-buffer' in FSF Emacs.)
+
+ - Function: x-store-cutbuffer string &optional push
+     This function stores STRING into the first cut buffer (cut buffer
+     0).
+
+     Normally, the contents of the first cut buffer are simply replaced
+     by STRING.  However, if optional argument PUSH is non-`nil', the
+     cut buffers are rotated.  This means that the previous value of
+     the first cut buffer moves to the second cut buffer, and the
+     second to the third, and so on, moving the other values down
+     through the series of cut buffers, kill-ring-style.  There are 8
+     cut buffers altogether.
+
+     Cut buffers are considered obsolete; you should use selections
+     instead.
+
+     This function has no effect if support for cut buffers was not
+     compiled in.
+
+     This function is called `x-set-cut-buffer' in FSF Emacs.

 
 

-Symbol Properties
-=================
+\1f
+File: lispref.info,  Node: X Server,  Next: X Miscellaneous,  Prev: X Selections,  Up: X-Windows
+
+X Server
+========
+
+This section describes how to access and change the overall status of
+the X server XEmacs is using.
+
+* Menu:
+
+* Resources::                   Getting resource values from the server.
+* Server Data::                 Getting info about the X server.
+* Grabs::                       Restricting access to the server by other apps.
+
+\1f
+File: lispref.info,  Node: Resources,  Next: Server Data,  Up: X Server
+
+Resources
+---------
+
+ - Function: default-x-device
+     This function return the default X device for resourcing.  This is
+     the first-created X device that still exists.
+
+ - Function: x-get-resource name class type &optional locale device
+          noerror
+     This function retrieves a resource value from the X resource
+     manager.
+
+        * The first arg is the name of the resource to retrieve, such as
+          `"font"'.
+
+        * The second arg is the class of the resource to retrieve, like
+          `"Font"'.
+
+        * The third arg should be one of the symbols `string',
+          `integer', `natnum', or `boolean', specifying the type of
+          object that the database is searched for.
+
+        * The fourth arg is the locale to search for the resources on,
+          and can currently be a buffer, a frame, a device, or the
+          symbol `global'.  If omitted, it defaults to `global'.
+
+        * The fifth arg is the device to search for the resources on.
+          (The resource database for a particular device is constructed
+          by combining non-device- specific resources such any
+          command-line resources specified and any app-defaults files
+          found [or the fallback resources supplied by XEmacs, if no
+          app-defaults file is found] with device-specific resources
+          such as those supplied using `xrdb'.) If omitted, it defaults
+          to the device of LOCALE, if a device can be derived (i.e. if
+          LOCALE is a frame or device), and otherwise defaults to the
+          value of `default-x-device'.
+
+        * The sixth arg NOERROR, if non-`nil', means do not signal an
+          error if a bogus resource specification was retrieved (e.g.
+          if a non-integer was given when an integer was requested).
+          In this case, a warning is issued instead.
+
+     The resource names passed to this function are looked up relative
+     to the locale.
+
+     If you want to search for a subresource, you just need to specify
+     the resource levels in NAME and CLASS.  For example, NAME could be
+     `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
+
+     Specifically,
+
+       1. If LOCALE is a buffer, a call
+
+                   `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
+
+          is an interface to a C call something like
+
+                   `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
+                                       "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
+                                       "String");'
+
+       2. If LOCALE is a frame, a call
+
+                   `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
+
+          is an interface to a C call something like
+
+                   `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
+                                       "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
+                                       "String");'
+
+       3. If LOCALE is a device, a call
+
+                   `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
+
+          is an interface to a C call something like
+
+                   `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
+                                       "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
+                                       "String");'
+
+       4. If LOCALE is the symbol `global', a call
+
+                   `(x-get-resource "foreground" "Foreground" 'string 'global)'
+
+          is an interface to a C call something like
+
+                   `XrmGetResource (db, "xemacs.foreground",
+                                       "Emacs.Foreground",
+                                       "String");'
+
+     Note that for `global', no prefix is added other than that of the
+     application itself; thus, you can use this locale to retrieve
+     arbitrary application resources, if you really want to.
+
+     The returned value of this function is `nil' if the queried
+     resource is not found.  If TYPE is `string', a string is returned,
+     and if it is `integer', an integer is returned.  If TYPE is
+     `boolean', then the returned value is the list `(t)' for true,
+     `(nil)' for false, and is `nil' to mean "unspecified".
+
+ - Function: x-put-resource resource-line &optional device
+     This function adds a resource to the resource database for DEVICE.
+     RESOURCE-LINE specifies the resource to add and should be a
+     standard resource specification.
+
+ - Variable: x-emacs-application-class
+     This variable holds The X application class of the XEmacs process.
+     This controls, among other things, the name of the "app-defaults"
+     file that XEmacs will use.  For changes to this variable to take
+     effect, they must be made before the connection to the X server is
+     initialized, that is, this variable may only be changed before
+     XEmacs is dumped, or by setting it in the file
+     `lisp/term/x-win.el'.
+
+     By default, this variable is `nil' at startup.  When the connection
+     to the X server is first initialized, the X resource database will
+     be consulted and the value will be set according to whether any
+     resources are found for the application class "XEmacs".

 
 

-   A "property list" ("plist" for short) is a list of paired elements,
-often stored in the property list cell of a symbol.  Each of the pairs
-associates a property name (usually a symbol) with a property or value.
-Property lists are generally used to record information about a
-symbol, such as its documentation as a variable, the name of the file
-where it was defined, or perhaps even the grammatical class of the
-symbol (representing a word) in a language-understanding system.
+\1f
+File: lispref.info,  Node: Server Data,  Next: Grabs,  Prev: Resources,  Up: X Server
+
+Data about the X Server
+-----------------------
+
+This section describes functions and a variable that you can use to get
+information about the capabilities and origin of the X server
+corresponding to a particular device.  The device argument is generally
+optional and defaults to the selected device.
+
+ - Function: x-server-version &optional device
+     This function returns the list of version numbers of the X server
+     DEVICE is on.  The returned value is a list of three integers: the
+     major and minor version numbers of the X protocol in use, and the
+     vendor-specific release number.
+
+ - Function: x-server-vendor &optional device
+     This function returns the vendor supporting the X server DEVICE is
+     on.
+
+ - Function: x-display-visual-class &optional device
+     This function returns the visual class of the display DEVICE is
+     on.  The value is one of the symbols `static-gray', `gray-scale',
+     `static-color', `pseudo-color', `true-color', and `direct-color'.
+     (Note that this is different from previous versions of XEmacs,
+     which returned `StaticGray', `GrayScale', etc.)
+
+\1f
+File: lispref.info,  Node: Grabs,  Prev: Server Data,  Up: X Server
+
+Restricting Access to the Server by Other Apps
+----------------------------------------------
+
+ - Function: x-grab-keyboard &optional device
+     This function grabs the keyboard on the given device (defaulting
+     to the selected one).  So long as the keyboard is grabbed, all
+     keyboard events will be delivered to XEmacs--it is not possible
+     for other X clients to eavesdrop on them.  Ungrab the keyboard
+     with `x-ungrab-keyboard' (use an `unwind-protect').  Returns `t'
+     if the grab was successful; `nil' otherwise.
+
+ - Function: x-ungrab-keyboard &optional device
+     This function releases a keyboard grab made with `x-grab-keyboard'.
+
+ - Function: x-grab-pointer &optional device cursor ignore-keyboard
+     This function grabs the pointer and restricts it to its current
+     window.  If optional DEVICE argument is `nil', the selected device
+     will be used.  If optional CURSOR argument is non-`nil', change
+     the pointer shape to that until `x-ungrab-pointer' is called (it
+     should be an object returned by the `make-cursor' function).  If
+     the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
+     all keyboard events during the grab.  Returns `t' if the grab is
+     successful, `nil' otherwise.
+
+ - Function: x-ungrab-pointer &optional device
+     This function releases a pointer grab made with `x-grab-pointer'.
+     If optional first arg DEVICE is `nil' the selected device is used.
+     If it is `t' the pointer will be released on all X devices.
+
+\1f
+File: lispref.info,  Node: X Miscellaneous,  Prev: X Server,  Up: X-Windows
+
+Miscellaneous X Functions and Variables
+=======================================
+
+ - Variable: x-bitmap-file-path
+     This variable holds a list of the directories in which X bitmap
+     files may be found.  If `nil', this is initialized from the
+     `"*bitmapFilePath"' resource.  This is used by the
+     `make-image-instance' function (however, note that if the
+     environment variable `XBMLANGPATH' is set, it is consulted first).
+
+ - Variable: x-library-search-path
+     This variable holds the search path used by `read-color' to find
+     `rgb.txt'.
+
+ - Function: x-valid-keysym-name-p keysym
+     This function returns true if KEYSYM names a keysym that the X
+     library knows about.  Valid keysyms are listed in the files
+     `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
+     whatever the equivalents are on your system.
+
+ - Function: x-window-id &optional frame
+     This function returns the ID of the X11 window.  This gives us a
+     chance to manipulate the Emacs window from within a different
+     program.  Since the ID is an unsigned long, we return it as a
+     string.
+
+ - Variable: x-allow-sendevents
+     If non-`nil', synthetic events are allowed.  `nil' means they are
+     ignored.  Beware: allowing XEmacs to process SendEvents opens a
+     big security hole.
+
+ - Function: x-debug-mode arg &optional device
+     With a true arg, make the connection to the X server synchronous.
+     With false, make it asynchronous.  Synchronous connections are
+     much slower, but are useful for debugging. (If you get X errors,
+     make the connection synchronous, and use a debugger to set a
+     breakpoint on `x_error_handler'.  Your backtrace of the C stack
+     will now be useful.  In asynchronous mode, the stack above
+     `x_error_handler' isn't helpful because of buffering.)  If DEVICE
+     is not specified, the selected device is assumed.
+
+     Calling this function is the same as calling the C function
+     `XSynchronize', or starting the program with the `-sync' command
+     line argument.
+
+ - Variable: x-debug-events
+     If non-zero, debug information about events that XEmacs sees is
+     displayed.  Information is displayed on stderr.  Currently defined
+     values are:
+
+        * 1 == non-verbose output
+
+        * 2 == verbose output
+
+\1f
+File: lispref.info,  Node: ToolTalk Support,  Next: LDAP Support,  Prev: X-Windows,  Up: Top
+
+ToolTalk Support
+****************
+
+* Menu:
+
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::

 
 

-   Some objects which are not symbols also have property lists
-associated with them, and XEmacs provides a full complement of
-functions for working with property lists.  *Note Property Lists::.
+\1f
+File: lispref.info,  Node: XEmacs ToolTalk API Summary,  Next: Sending Messages,  Up: ToolTalk Support
+
+XEmacs ToolTalk API Summary
+===========================
+
+The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
+to the standard C ToolTalk API.  Only the message and pattern parts of
+the API are supported at present; more of the API could be added if
+needed.  The Lisp interface departs from the C API in a few ways:
+
+   * ToolTalk is initialized automatically at XEmacs startup-time.
+     Messages can only be sent other ToolTalk applications connected to
+     the same X11 server that XEmacs is running on.

 
 

-   The property names and values in a property list can be any Lisp
-objects, but the names are usually symbols.  They are compared using
-`eq'.  Here is an example of a property list, found on the symbol
-`progn' when the compiler is loaded:
+   * There are fewer entry points; polymorphic functions with keyword
+     arguments are used instead.

 
 

-     (lisp-indent-function 0 byte-compile byte-compile-progn)
+   * The callback interface is simpler and marginally less functional.
+     A single callback may be associated with a message or a pattern;
+     the callback is specified with a Lisp symbol (the symbol should
+     have a function binding).
+
+   * The session attribute for messages and patterns is always
+     initialized to the default session.
+
+   * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
+     can substitute the corresponding symbol, e.g. `'TT_SESSION'.  This
+     simplifies building lists that represent messages and patterns.
+
+\1f
+File: lispref.info,  Node: Sending Messages,  Next: Receiving Messages,  Prev: XEmacs ToolTalk API Summary,  Up: ToolTalk Support

 
 

-Here `lisp-indent-function' and `byte-compile' are property names, and
-the other two elements are the corresponding values.
+Sending Messages
+================

 
 * Menu:
 
 
 * Menu:
 

-* Plists and Alists::           Comparison of the advantages of property
-                                  lists and association lists.
-* Object Plists::               Functions to access objects' property lists.
-* Other Plists::                Accessing property lists stored elsewhere.
+* Example of Sending Messages::
+* Elisp Interface for Sending Messages::
+
+\1f
+File: lispref.info,  Node: Example of Sending Messages,  Next: Elisp Interface for Sending Messages,  Up: Sending Messages
+
+Example of Sending Messages
+---------------------------
+
+Here's a simple example that sends a query to another application and
+then displays its reply.  Both the query and the reply are stored in
+the first argument of the message.
+
+     (defun tooltalk-random-query-handler (msg)
+       (let ((state (get-tooltalk-message-attribute msg 'state)))
+         (cond
+           ((eq state 'TT_HANDLED)
+            (message (get-tooltalk-message-attribute msg arg_val 0)))
+           ((memq state '(TT_FAILED TT_REJECTED))
+            (message "Random query turns up nothing")))))
+     
+     (defvar random-query-message
+       '(   class TT_REQUEST
+            scope TT_SESSION
+          address TT_PROCEDURE
+               op "random-query"
+             args '((TT_INOUT "?" "string"))
+         callback tooltalk-random-query-handler))
+     
+     (let ((m (make-tooltalk-message random-query-message)))
+       (send-tooltalk-message m))

 
 \1f
 
 \1f

-File: lispref.info,  Node: Plists and Alists,  Next: Object Plists,  Up: Symbol Properties
+File: lispref.info,  Node: Elisp Interface for Sending Messages,  Prev: Example of Sending Messages,  Up: Sending Messages

 
 

-Property Lists and Association Lists
+Elisp Interface for Sending Messages

 ------------------------------------
 
 ------------------------------------
 

-   Association lists (*note Association Lists::) are very similar to
-property lists.  In contrast to association lists, the order of the
-pairs in the property list is not significant since the property names
-must be distinct.
-
-   Property lists are better than association lists for attaching
-information to various Lisp function names or variables.  If all the
-associations are recorded in one association list, the program will need
-to search that entire list each time a function or variable is to be
-operated on.  By contrast, if the information is recorded in the
-property lists of the function names or variables themselves, each
-search will scan only the length of one property list, which is usually
-short.  This is why the documentation for a variable is recorded in a
-property named `variable-documentation'.  The byte compiler likewise
-uses properties to record those functions needing special treatment.
-
-   However, association lists have their own advantages.  Depending on
-your application, it may be faster to add an association to the front of
-an association list than to update a property.  All properties for a
-symbol are stored in the same property list, so there is a possibility
-of a conflict between different uses of a property name.  (For this
-reason, it is a good idea to choose property names that are probably
-unique, such as by including the name of the library in the property
-name.)  An association list may be used like a stack where associations
-are pushed on the front of the list and later discarded; this is not
-possible with a property list.
-
-\1f
-File: lispref.info,  Node: Object Plists,  Next: Other Plists,  Prev: Plists and Alists,  Up: Symbol Properties
-
-Property List Functions for Objects
------------------------------------
-
-   Once upon a time, only symbols had property lists.  Now, several
-other object types, including strings, extents, faces and glyphs also
-have property lists.
-
- - Function: symbol-plist symbol
-     This function returns the property list of SYMBOL.
-
- - Function: object-plist object
-     This function returns the property list of OBJECT.  If OBJECT is a
-     symbol, this is identical to `symbol-plist'.
-
- - Function: setplist symbol plist
-     This function sets SYMBOL's property list to PLIST.  Normally,
-     PLIST should be a well-formed property list, but this is not
-     enforced.
-
-          (setplist 'foo '(a 1 b (2 3) c nil))
-               => (a 1 b (2 3) c nil)
-          (symbol-plist 'foo)
-               => (a 1 b (2 3) c nil)
-
-     For symbols in special obarrays, which are not used for ordinary
-     purposes, it may make sense to use the property list cell in a
-     nonstandard fashion; in fact, the abbrev mechanism does so (*note
-     Abbrevs::).  But generally, its use is discouraged.  Use `put'
-     instead.  `setplist' can only be used with symbols, not other
-     object types.
-
- - Function: get object property &optional default
-     This function finds the value of the property named PROPERTY in
-     OBJECT's property list.  If there is no such property, `default'
-     (which itself defaults to `nil') is returned.
-
-     PROPERTY is compared with the existing properties using `eq', so
-     any object is a legitimate property.
-
-     See `put' for an example.
-
- - Function: put object property value
-     This function puts VALUE onto OBJECT's property list under the
-     property name PROPERTY, replacing any previous property value.
-     The `put' function returns VALUE.
-
-          (put 'fly 'verb 'transitive)
-               =>'transitive
-          (put 'fly 'noun '(a buzzing little bug))
-               => (a buzzing little bug)
-          (get 'fly 'verb)
-               => transitive
-          (object-plist 'fly)
-               => (verb transitive noun (a buzzing little bug))
-
- - Function: remprop object property
-     This function removes the entry for PROPERTY from the property
-     list of OBJECT.  It returns `t' if the property was indeed found
-     and removed, or `nil' if there was no such property.  (This
-     function was probably omitted from Emacs originally because, since
-     `get' did not allow a DEFAULT, it was very difficult to
-     distinguish between a missing property and a property whose value
-     was `nil'; thus, setting a property to `nil' was close enough to
-     `remprop' for most purposes.)
-
-\1f
-File: lispref.info,  Node: Other Plists,  Prev: Object Plists,  Up: Symbol Properties
-
-Property Lists Not Associated with Objects
-------------------------------------------
-
-   These functions are useful for manipulating property lists that are
-stored in places other than symbols:
-
- - Function: getf plist property &optional default
-     This returns the value of the PROPERTY property stored in the
-     property list PLIST.  For example,
-
-          (getf '(foo 4) 'foo)
-               => 4
-
- - Macro: putf plist property value
-     This stores VALUE as the value of the PROPERTY property in the
-     property list PLIST.  It may modify PLIST destructively, or it may
-     construct a new list structure without altering the old.  The
-     function returns the modified property list, so you can store that
-     back in the place where you got PLIST.  For example,
-
-          (setq my-plist '(bar t foo 4))
-               => (bar t foo 4)
-          (setq my-plist (putf my-plist 'foo 69))
-               => (bar t foo 69)
-          (setq my-plist (putf my-plist 'quux '(a)))
-               => (quux (a) bar t foo 5)
-
- - Function: plists-eq a b
-     This function returns non-`nil' if property lists A and B are
-     `eq'.  This means that the property lists have the same values for
-     all the same properties, where comparison between values is done
-     using `eq'.
-
- - Function: plists-equal a b
-     This function returns non-`nil' if property lists A and B are
-     `equal'.
-
-   Both of the above functions do order-insensitive comparisons.
-
-     (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
-          => t
-     (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
-          => nil
-     (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
-          => t
+ - Function: make-tooltalk-message attributes
+     Create a ToolTalk message and initialize its attributes.  The
+     value of ATTRIBUTES must be a list of alternating keyword/values,
+     where keywords are symbols that name valid message attributes.
+     For example:
+
+            (make-tooltalk-message
+              '(class TT_NOTICE
+                scope TT_SESSION
+                address TT_PROCEDURE
+                op "do-something"
+                args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+     Values must always be strings, integers, or symbols that represent
+     ToolTalk constants.  Attribute names are the same as those
+     supported by `set-tooltalk-message-attribute', plus `args'.
+
+     The value of `args' should be a list of message arguments where
+     each message argument has the following form:
+
+             `(mode [value [type]])' or just `value'
+
+     Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+     a string.  If TYPE isn't specified then `int' is used if VALUE is
+     a number; otherwise `string' is used.  If TYPE is `string' then
+     VALUE is converted to a string (if it isn't a string already) with
+     `prin1-to-string'.  If only a value is specified then MODE
+     defaults to `TT_IN'.  If MODE is `TT_OUT' then VALUE and TYPE
+     don't need to be specified.  You can find out more about the
+     semantics and uses of ToolTalk message arguments in chapter 4 of
+     the `ToolTalk Programmer's Guide'.
+
+
+ - Function: send-tooltalk-message msg
+     Send the message on its way.  Once the message has been sent it's
+     almost always a good idea to get rid of it with
+     `destroy-tooltalk-message'.
+
+
+ - Function: return-tooltalk-message msg &optional mode
+     Send a reply to this message.  The second argument can be `reply',
+     `reject' or `fail'; the default is `reply'.  Before sending a
+     reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
+     should have been filled in--see `set-tooltalk-message-attribute'.
+
+
+ - Function: get-tooltalk-message-attribute msg attribute &optional argn
+     Returns the indicated ToolTalk message attribute.  Attributes are
+     identified by symbols with the same name (underscores and all) as
+     the suffix of the ToolTalk `tt_message_<attribute>' function that
+     extracts the value.  String attribute values are copied and
+     enumerated type values (except disposition) are converted to
+     symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
+     represented by fixnums (small integers), `opnum' is converted to a
+     string, and `disposition' is converted to a fixnum.  We convert
+     `opnum' (a C int) to a string (e.g. `123' => `"123"') because
+     there's no guarantee that opnums will fit within the range of
+     XEmacs Lisp integers.
+
+     [TBD] Use the `plist' attribute instead of C API `user' attribute
+     for user-defined message data.  To retrieve the value of a message
+     property, specify the indicator for ARGN.  For example, to get the
+     value of a property called `rflag', use
+
+             (get-tooltalk-message-attribute msg 'plist 'rflag)
+
+     To get the value of a message argument use one of the `arg_val'
+     (strings), `arg_ival' (integers), or `arg_bval' (strings with
+     embedded nulls), attributes.  For example, to get the integer
+     value of the third argument:
+
+             (get-tooltalk-message-attribute msg 'arg_ival 2)
+
+     As you can see, argument numbers are zero-based.  The type of each
+     arguments can be retrieved with the `arg_type' attribute; however
+     ToolTalk doesn't define any semantics for the string value of
+     `arg_type'.  Conventionally `string' is used for strings and `int'
+     for 32 bit integers.  Note that XEmacs Lisp stores the lengths of
+     strings explicitly (unlike C) so treating the value returned by
+     `arg_bval' like a string is fine.
+
+
+ - Function: set-tooltalk-message-attribute value msg attribute
+          &optional argn
+     Initialize one ToolTalk message attribute.
+
+     Attribute names and values are the same as for
+     `get-tooltalk-message-attribute'.  A property list is provided for
+     user data (instead of the `user' message attribute); see
+     `get-tooltalk-message-attribute'.
+
+     Callbacks are handled slightly differently than in the C ToolTalk
+     API.  The value of CALLBACK should be the name of a function of one
+     argument.  It will be called each time the state of the message
+     changes.  This is usually used to notice when the message's state
+     has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
+     argument values can be used.
+
+     If one of the argument attributes is specified as `arg_val',
+     `arg_ival', or `arg_bval', then ARGN must be the number of an
+     already created argument.  Arguments can be added to a message
+     with `add-tooltalk-message-arg'.
+
+
+ - Function: add-tooltalk-message-arg msg mode type &optional value
+     Append one new argument to the message.  MODE must be one of
+     `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
+     can be a string or an integer.  ToolTalk doesn't define any
+     semantics for TYPE, so only the participants in the protocol
+     you're using need to agree what types mean (if anything).
+     Conventionally `string' is used for strings and `int' for 32 bit
+     integers.  Arguments can initialized by providing a value or with
+     `set-tooltalk-message-attribute'; the latter is necessary if you
+     want to initialize the argument with a string that can contain
+     embedded nulls (use `arg_bval').
+
+
+ - Function: create-tooltalk-message &optional no-callback
+     Create a new ToolTalk message.  The message's session attribute is
+     initialized to the default session.  Other attributes can be
+     initialized with `set-tooltalk-message-attribute'.
+     `make-tooltalk-message' is the preferred way to create and
+     initialize a message.
+
+     Optional arg NO-CALLBACK says don't add a C-level callback at all.
+     Normally don't do that; just don't specify the Lisp callback when
+     calling `make-tooltalk-message'.
+
+
+ - Function: destroy-tooltalk-message msg
+     Apply `tt_message_destroy' to the message.  It's not necessary to
+     destroy messages after they've been processed by a message or
+     pattern callback, the Lisp/ToolTalk callback machinery does this
+     for you.
+
+\1f
+File: lispref.info,  Node: Receiving Messages,  Prev: Sending Messages,  Up: ToolTalk Support
+
+Receiving Messages
+==================
+
+* Menu:
+
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
+
+\1f
+File: lispref.info,  Node: Example of Receiving Messages,  Next: Elisp Interface for Receiving Messages,  Up: Receiving Messages
+
+Example of Receiving Messages
+-----------------------------
+
+Here's a simple example of a handler for a message that tells XEmacs to
+display a string in the mini-buffer area.  The message operation is
+called `emacs-display-string'.  Its first (0th) argument is the string
+to display.
+
+     (defun tooltalk-display-string-handler (msg)
+       (message (get-tooltalk-message-attribute msg 'arg_val 0)))
+     
+     (defvar display-string-pattern
+       '(category TT_HANDLE
+            scope TT_SESSION
+               op "emacs-display-string"
+         callback tooltalk-display-string-handler))
+     
+     (let ((p (make-tooltalk-pattern display-string-pattern)))
+       (register-tooltalk-pattern p))
+
+\1f
+File: lispref.info,  Node: Elisp Interface for Receiving Messages,  Prev: Example of Receiving Messages,  Up: Receiving Messages
+
+Elisp Interface for Receiving Messages
+--------------------------------------
+
+ - Function: make-tooltalk-pattern attributes
+     Create a ToolTalk pattern and initialize its attributes.  The
+     value of attributes must be a list of alternating keyword/values,
+     where keywords are symbols that name valid pattern attributes or
+     lists of valid attributes.  For example:
+
+            (make-tooltalk-pattern
+              '(category TT_OBSERVE
+                   scope TT_SESSION
+                      op ("operation1" "operation2")
+                    args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+     Attribute names are the same as those supported by
+     `add-tooltalk-pattern-attribute', plus `'args'.
+
+     Values must always be strings, integers, or symbols that represent
+     ToolTalk constants or lists of same.  When a list of values is
+     provided all of the list elements are added to the attribute.  In
+     the example above, messages whose `op' attribute is `"operation1"'
+     or `"operation2"' would match the pattern.
+
+     The value of ARGS should be a list of pattern arguments where each
+     pattern argument has the following form:
+
+             `(mode [value [type]])' or just `value'
+
+     Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+     a string.  If TYPE isn't specified then `int' is used if VALUE is
+     a number; otherwise `string' is used.  If TYPE is `string' then
+     VALUE is converted to a string (if it isn't a string already) with
+     `prin1-to-string'.  If only a value is specified then MODE
+     defaults to `TT_IN'.  If MODE is `TT_OUT' then VALUE and TYPE
+     don't need to be specified.  You can find out more about the
+     semantics and uses of ToolTalk pattern arguments in chapter 3 of
+     the `ToolTalk Programmer's Guide'.
+
+
+ - Function: register-tooltalk-pattern pattern
+     XEmacs will begin receiving messages that match this pattern.
+
+ - Function: unregister-tooltalk-pattern pattern
+     XEmacs will stop receiving messages that match this pattern.
+
+ - Function: add-tooltalk-pattern-attribute value pattern indicator
+     Add one value to the indicated pattern attribute. The names of
+     attributes are the same as the ToolTalk accessors used to set them
+     less the `tooltalk_pattern_' prefix and the `_add' suffix.  For
+     example, the name of the attribute for the
+     `tt_pattern_disposition_add' attribute is `disposition'.  The
+     `category' attribute is handled specially, since a pattern can only
+     be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
+
+     Callbacks are handled slightly differently than in the C ToolTalk
+     API.  The value of CALLBACK should be the name of a function of one
+     argument.  It will be called each time the pattern matches an
+     incoming message.
+
+ - Function: add-tooltalk-pattern-arg pattern mode vtype &optional value
+     Add one fully-specified argument to a ToolTalk pattern.  MODE must
+     be one of `TT_IN', `TT_INOUT', or `TT_OUT'.  VTYPE must be a
+     string.  VALUE can be an integer, string or `nil'.  If VALUE is an
+     integer then an integer argument (`tt_pattern_iarg_add') is added;
+     otherwise a string argument is added.  At present there's no way
+     to add a binary data argument.
+
+
+ - Function: create-tooltalk-pattern
+     Create a new ToolTalk pattern and initialize its session attribute
+     to be the default session.
+
+ - Function: destroy-tooltalk-pattern pattern
+     Apply `tt_pattern_destroy' to the pattern.  This effectively
+     unregisters the pattern.
+
+ - Function: describe-tooltalk-message msg &optional stream
+     Print the message's attributes and arguments to STREAM.  This is
+     often useful for debugging.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Evaluation,  Next: Control Structures,  Prev: Symbols,  Up: Top
+File: lispref.info,  Node: LDAP Support,  Next: PostgreSQL Support,  Prev: ToolTalk Support,  Up: Top

 
 

-Evaluation
-**********
+LDAP Support
+************

 
 

-   The "evaluation" of expressions in XEmacs Lisp is performed by the
-"Lisp interpreter"--a program that receives a Lisp object as input and
-computes its "value as an expression".  How it does this depends on the
-data type of the object, according to rules described in this chapter.
-The interpreter runs automatically to evaluate portions of your
-program, but can also be called explicitly via the Lisp primitive
-function `eval'.
+XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.

 
 * Menu:
 
 
 * Menu:
 

-* 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).
+* 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

 
 \1f
 
 \1f

-File: lispref.info,  Node: Intro Eval,  Next: Eval,  Up: Evaluation
+File: lispref.info,  Node: Building XEmacs with LDAP support,  Next: XEmacs LDAP API,  Prev: LDAP Support,  Up: LDAP Support

 
 

-Introduction to Evaluation
-==========================
+Building XEmacs with LDAP support
+=================================

 
 

-   The Lisp interpreter, or evaluator, is the program that computes the
-value of an expression that is given to it.  When a function written in
-Lisp is called, the evaluator computes the value of the function by
-evaluating the expressions in the function body.  Thus, running any
-Lisp program really means running the Lisp interpreter.
-
-   How the evaluator handles an object depends primarily on the data
-type of the object.
-
-   A Lisp object that is intended for evaluation is called an
-"expression" or a "form".  The fact that expressions are data objects
-and not merely text is one of the fundamental differences between
-Lisp-like languages and typical programming languages.  Any object can
-be evaluated, but in practice only numbers, symbols, lists and strings
-are evaluated very often.
-
-   It is very common to read a Lisp expression and then evaluate the
-expression, but reading and evaluation are separate activities, and
-either can be performed alone.  Reading per se does not evaluate
-anything; it converts the printed representation of a Lisp object to the
-object itself.  It is up to the caller of `read' whether this object is
-a form to be evaluated, or serves some entirely different purpose.
-*Note Input Functions::.
-
-   Do not confuse evaluation with command key interpretation.  The
-editor command loop translates keyboard input into a command (an
-interactively callable function) using the active keymaps, and then
-uses `call-interactively' to invoke the command.  The execution of the
-command itself involves evaluation if the command is written in Lisp,
-but that is not a part of command key interpretation itself.  *Note
-Command Loop::.
-
-   Evaluation is a recursive process.  That is, evaluation of a form may
-call `eval' to evaluate parts of the form.  For example, evaluation of
-a function call first evaluates each argument of the function call, and
-then evaluates each form in the function body.  Consider evaluation of
-the form `(car x)': the subform `x' must first be evaluated
-recursively, so that its value can be passed as an argument to the
-function `car'.
-
-   Evaluation of a function call ultimately calls the function specified
-in it.  *Note Functions::.  The execution of the function may itself
-work by evaluating the function definition; or the function may be a
-Lisp primitive implemented in C, or it may be a byte-compiled function
-(*note Byte Compilation::).
-
-   The evaluation of forms takes place in a context called the
-"environment", which consists of the current values and bindings of all
-Lisp variables.(1)  Whenever the form refers to a variable without
-creating a new binding for it, the value of the binding in the current
-environment is used.  *Note Variables::.
-
-   Evaluation of a form may create new environments for recursive
-evaluation by binding variables (*note Local Variables::).  These
-environments are temporary and vanish by the time evaluation of the form
-is complete.  The form may also make changes that persist; these changes
-are called "side effects".  An example of a form that produces side
-effects is `(setq foo 1)'.
-
-   The details of what evaluation means for each kind of form are
-described below (*note Forms::).
-
-   ---------- Footnotes ----------
-
-   (1) This definition of "environment" is specifically not intended to
-include all the data that can affect the result of a program.
-
-\1f
-File: lispref.info,  Node: Eval,  Next: Forms,  Prev: Intro Eval,  Up: Evaluation
-
-Eval
-====
-
-   Most often, forms are evaluated automatically, by virtue of their
-occurrence in a program being run.  On rare occasions, you may need to
-write code that evaluates a form that is computed at run time, such as
-after reading a form from text being edited or getting one from a
-property list.  On these occasions, use the `eval' function.
-
-   *Please note:* it is generally cleaner and more flexible to call
-functions that are stored in data structures, rather than to evaluate
-expressions stored in data structures.  Using functions provides the
-ability to pass information to them as arguments.
-
-   The functions and variables described in this section evaluate forms,
-specify limits to the evaluation process, or record recently returned
-values.  Loading a file also does evaluation (*note Loading::).
-
- - Function: eval form
-     This is the basic function for performing evaluation.  It evaluates
-     FORM in the current environment and returns the result.  How the
-     evaluation proceeds depends on the type of the object (*note
-     Forms::).
-
-     Since `eval' is a function, the argument expression that appears
-     in a call to `eval' is evaluated twice: once as preparation before
-     `eval' is called, and again by the `eval' function itself.  Here
-     is an example:
-
-          (setq foo 'bar)
-               => bar
-          (setq bar 'baz)
-               => baz
-          ;; `eval' receives argument `bar', which is the value of `foo'
-          (eval foo)
-               => baz
-          (eval 'foo)
-               => bar
-
-     The number of currently active calls to `eval' is limited to
-     `max-lisp-eval-depth' (see below).
-
- - Command: eval-region start end &optional stream
-     This function evaluates the forms in the current buffer in the
-     region defined by the positions START and END.  It reads forms from
-     the region and calls `eval' on them until the end of the region is
-     reached, or until an error is signaled and not handled.
-
-     If STREAM is supplied, `standard-output' is bound to it during the
-     evaluation.
-
-     You can use the variable `load-read-function' to specify a function
-     for `eval-region' to use instead of `read' for reading
-     expressions.  *Note How Programs Do Loading::.
-
-     `eval-region' always returns `nil'.
-
- - Command: eval-buffer buffer &optional stream
-     This is like `eval-region' except that it operates on the whole
-     contents of BUFFER.
-
- - Variable: max-lisp-eval-depth
-     This variable defines the maximum depth allowed in calls to `eval',
-     `apply', and `funcall' before an error is signaled (with error
-     message `"Lisp nesting exceeds max-lisp-eval-depth"').  This counts
-     internal uses of those functions, such as for calling the functions
-     mentioned in Lisp expressions, and recursive evaluation of
-     function call arguments and function body forms.
-
-     This limit, with the associated error when it is exceeded, is one
-     way that Lisp avoids infinite recursion on an ill-defined function.
-
-     The default value of this variable is 1000.  If you set it to a
-     value less than 100, Lisp will reset it to 100 if the given value
-     is reached.
-
-     `max-specpdl-size' provides another limit on nesting.  *Note Local
-     Variables::.
-
- - Variable: values
-     The value of this variable is a list of the values returned by all
-     the expressions that were read from buffers (including the
-     minibuffer), evaluated, and printed.  The elements are ordered
-     most recent first.
-
-          (setq x 1)
-               => 1
-          (list 'A (1+ 2) auto-save-default)
-               => (A 3 t)
-          values
-               => ((A 3 t) 1 ...)
-
-     This variable is useful for referring back to values of forms
-     recently evaluated.  It is generally a bad idea to print the value
-     of `values' itself, since this may be very long.  Instead, examine
-     particular elements, like this:
-
-          ;; Refer to the most recent evaluation result.
-          (nth 0 values)
-               => (A 3 t)
-          ;; That put a new element on,
-          ;;   so all elements move back one.
-          (nth 1 values)
-               => (A 3 t)
-          ;; This gets the element that was next-to-most-recent
-          ;;   before this example.
-          (nth 3 values)
-               => 1
-
-\1f
-File: lispref.info,  Node: Forms,  Next: Quoting,  Prev: Eval,  Up: Evaluation
-
-Kinds of Forms
-==============
+LDAP support must be added to XEmacs at build time since it requires
+linking to an external LDAP client library.  As of 21.2, XEmacs has been
+successfully built and tested with
+
+   * OpenLDAP 1.2 (<http://www.openldap.org/>)
+
+   * University of Michigan's LDAP 3.3
+     (<http://www.umich.edu/~dirsvcs/ldap/>)
+
+   * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
+
+   Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
+
+   The standard XEmacs configure script auto-detects an installed LDAP
+library provided the library itself and the corresponding header files
+can be found in the library and include paths.  A successful detection
+will be signalled in the final output of the configure script.
+
+\1f
+File: lispref.info,  Node: XEmacs LDAP API,  Next: Syntax of Search Filters,  Prev: Building XEmacs with LDAP support,  Up: LDAP Support
+
+XEmacs LDAP API
+===============
+
+XEmacs LDAP API consists of two layers:  a low-level layer which tries
+to stay as close as possible to the C API (where practical) and a
+higher-level layer which provides more convenient primitives to
+effectively use LDAP.
+
+   The low-level API should be used directly for very specific purposes
+(such as multiple operations on a connection) only.  The higher-level
+functions provide a more convenient way to access LDAP directories
+hiding the subtleties of handling the connection, translating arguments
+and ensuring compliance with LDAP internationalization rules and formats
+(currently partly implemented only).
+
+* Menu:
+
+* 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
+
+\1f
+File: lispref.info,  Node: LDAP Variables,  Next: The High-Level LDAP API,  Prev: XEmacs LDAP API,  Up: XEmacs LDAP API
+
+LDAP Variables
+--------------
+
+ - Variable: ldap-default-host
+     The default LDAP server hostname.  A TCP port number can be
+     appended to that name using a colon as a separator.
+
+ - Variable: ldap-default-port
+     Default TCP port for LDAP connections.  Initialized from the LDAP
+     library. Default value is 389.
+
+ - Variable: ldap-default-base
+     Default base for LDAP searches.  This is a string using the syntax
+     of RFC 1779.  For instance, "o=ACME, c=US" limits the search to the
+     Acme organization in the United States.
+
+ - Variable: ldap-host-parameters-alist
+     An alist of per host options for LDAP transactions.  The list
+     elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
+     name of an LDAP server. A TCP port number can be appended to that
+     name using a colon as a separator.  PROPN and VALN are
+     property/value pairs describing parameters for the server.  Valid
+     properties:
+    `binddn'
+          The distinguished name of the user to bind as.  This may look
+          like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details.
+
+    `passwd'
+          The password to use for authentication.
+
+    `auth'
+          The authentication method to use, possible values depend on
+          the LDAP library XEmacs was compiled with, they may include
+          `simple', `krbv41' and `krbv42'.
+
+    `base'
+          The base for the search. This may look like `cÿ, o¬me', see
+          RFC 1779 for syntax details.
+
+    `scope'
+          One of the symbols `base', `onelevel' or `subtree' indicating
+          the scope of the search limited to a base object, to a single
+          level or to the whole subtree.
+
+    `deref'
+          The dereference policy is one of the symbols `never',
+          `always', `search' or `find' and defines how aliases are
+          dereferenced.
+         `never'
+               Aliases are never dereferenced
+
+         `always'
+               Aliases are always dereferenced
+
+         `search'
+               Aliases are dereferenced when searching
+
+         `find'
+               Aliases are dereferenced when locating the base object
+               for the search
+
+    `timelimit'
+          The timeout limit for the connection in seconds.
+
+    `sizelimit'
+          The maximum number of matches to return for searches
+          performed on this connection.
+
+ - Variable: ldap-verbose
+     If non-`nil', LDAP operations will echo progress messages.
+     Defaults to `nil'.
+
+\1f
+File: lispref.info,  Node: The High-Level LDAP API,  Next: The Low-Level LDAP API,  Prev: LDAP Variables,  Up: XEmacs LDAP API
+
+The High-Level LDAP API
+-----------------------
+
+The following functions provide the most convenient interface to perform
+LDAP operations.  All of them open a connection to a host, perform an
+operation (add/search/modify/delete) on one or several entries and
+cleanly close the connection thus insulating the user from all the
+details of the low-level interface such as LDAP Lisp objects *note The
+Low-Level LDAP API::.
+
+   Note that `ldap-search' which used to be the name of the high-level
+search function in XEmacs 21.1 is now obsolete.  For consistency  in the
+naming as well as backward compatibility, that function now acts as a
+wrapper that calls either `ldap-search-basic' (low-level search
+function) or `ldap-search-entries' (high-level search function)
+according to the actual parameters.  A direct call to one of these two
+functions is preferred since it is faster and unambiguous.
+
+ - Command: ldap-search-entries filter &optional host attributes
+          attrsonly withdn
+     Perform an LDAP search.  FILTER is the search filter *note Syntax
+     of Search Filters:: HOST is the LDAP host on which to perform the
+     search.  ATTRIBUTES is the specific attributes to retrieve, `nil'
+     means retrieve all.  ATTRSONLY if non-`nil' retrieves the
+     attributes only without their associated values.  If WITHDN is
+     non-`nil' each entry in the result will be prepended with its
+     distinguished name DN.  Additional search parameters can be
+     specified through `ldap-host-parameters-alist'.  The function
+     returns a list of matching entries.  Each entry is itself an alist
+     of attribute/value pairs optionally preceded by the DN of the
+     entry according to the value of WITHDN.
+
+ - Function: ldap-add-entries entries &optional host binddn passwd
+     Add entries to an LDAP directory.  ENTRIES is a list of entry
+     specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)'
+     where DN the distinguished name of an entry to add, the following
+     are cons cells containing attribute/value string pairs.  HOST is
+     the LDAP host, defaulting to `ldap-default-host'.  BINDDN is the
+     DN to bind as to the server.  PASSWD is the corresponding password.
+
+ - Function: ldap-modify-entries entry-mods &optional host binddn passwd
+     Modify entries of an LDAP directory.  ENTRY_MODS is a list of
+     entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)'
+     where DN is the distinguished name of the entry to modify, the
+     following are modification specifications.  A modification
+     specification is itself a list of the form `(MOD-OP ATTR VALUE1
+     VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional
+     depending on MOD-OP.  MOD-OP is the type of modification, one of
+     the symbols `add', `delete' or `replace'. ATTR is the LDAP
+     attribute type to modify.  HOST is the LDAP host, defaulting to
+     `ldap-default-host'.  BINDDN is the DN to bind as to the server.
+     PASSWD is the corresponding password.
+
+ - Function: ldap-delete-entries dn &optional host binddn passwd
+     Delete an entry from an LDAP directory.  DN is the distinguished
+     name of an entry to delete or a list of those.  HOST is the LDAP
+     host, defaulting to `ldap-default-host'.  BINDDN is the DN to bind
+     as to the server.  PASSWD is the corresponding password.
+
+\1f
+File: lispref.info,  Node: The Low-Level LDAP API,  Next: LDAP Internationalization,  Prev: The High-Level LDAP API,  Up: XEmacs LDAP API
+
+The Low-Level LDAP API
+----------------------
+
+The low-level API should be used directly for very specific purposes
+(such as multiple operations on a connection) only.  The higher-level
+functions provide a more convenient way to access LDAP directories
+hiding the subtleties of handling the connection, translating arguments
+and ensuring compliance with LDAP internationalization rules and formats
+(currently partly implemented only). See *note The High-Level LDAP API::

 
 

-   A Lisp object that is intended to be evaluated is called a "form".
-How XEmacs evaluates a form depends on its data type.  XEmacs has three
-different kinds of form that are evaluated differently: symbols, lists,
-and "all other types".  This section describes all three kinds,
-starting with "all other types" which are self-evaluating forms.
+   Note that the former functions `ldap-*-internal' functions have been
+renamed in XEmacs 21.2

 
 * Menu:
 
 
 * Menu:
 

-* 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 Indirection::    When a symbol appears as the car of a list,
-                             we find the real function via the symbol.
-* 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.
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Low-level Operations on a LDAP Server::

 
 

diff --git a/info/lispref.info-8 b/info/lispref.info-8
index 333739c..74c0357 100644 (file)
--- a/info/lispref.info-8
+++ b/info/lispref.info-8
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1173 +50,5564 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: Self-Evaluating Forms,  Next: Symbol Forms,  Up: Forms
+File: lispref.info,  Node: The LDAP Lisp Object,  Next: Opening and Closing a LDAP Connection,  Prev: The Low-Level LDAP API,  Up: The Low-Level LDAP API

 
 

-Self-Evaluating Forms
----------------------
+The LDAP Lisp Object
+....................

 
 

-   A "self-evaluating form" is any form that is not a list or symbol.
-Self-evaluating forms evaluate to themselves: the result of evaluation
-is the same object that was evaluated.  Thus, the number 25 evaluates to
-25, and the string `"foo"' evaluates to the string `"foo"'.  Likewise,
-evaluation of a vector does not cause evaluation of the elements of the
-vector--it returns the same vector with its contents unchanged.
-
-     '123               ; An object, shown without evaluation.
-          => 123
-     123                ; Evaluated as usual--result is the same.
-          => 123
-     (eval '123)        ; Evaluated "by hand"--result is the same.
-          => 123
-     (eval (eval '123)) ; Evaluating twice changes nothing.
-          => 123
-
-   It is common to write numbers, characters, strings, and even vectors
-in Lisp code, taking advantage of the fact that they self-evaluate.
-However, it is quite unusual to do this for types that lack a read
-syntax, because there's no way to write them textually.  It is possible
-to construct Lisp expressions containing these types by means of a Lisp
-program.  Here is an example:
-
-     ;; Build an expression containing a buffer object.
-     (setq buffer (list 'print (current-buffer)))
-          => (print #<buffer eval.texi>)
-     ;; Evaluate it.
-     (eval buffer)
-          -| #<buffer eval.texi>
-          => #<buffer eval.texi>
-
-\1f
-File: lispref.info,  Node: Symbol Forms,  Next: Classifying Lists,  Prev: Self-Evaluating Forms,  Up: Forms
-
-Symbol Forms
-------------
+An internal built-in `ldap' lisp object represents a LDAP connection.
+
+ - Function: ldapp object
+     This function returns non-`nil' if OBJECT is a `ldap' object.
+
+ - Function: ldap-host ldap
+     Return the server host of the connection represented by LDAP.
+
+ - Function: ldap-live-p ldap
+     Return non-`nil' if LDAP is an active LDAP connection.
+
+\1f
+File: lispref.info,  Node: Opening and Closing a LDAP Connection,  Next: Low-level Operations on a LDAP Server,  Prev: The LDAP Lisp Object,  Up: The Low-Level LDAP API
+
+Opening and Closing a LDAP Connection
+.....................................

 
 

-   When a symbol is evaluated, it is treated as a variable.  The result
-is the variable's value, if it has one.  If it has none (if its value
-cell is void), an error is signaled.  For more information on the use of
-variables, see *Note Variables::.
+ - Function: ldap-open host &optional plist
+     Open a LDAP connection to HOST.  PLIST is a property list
+     containing additional parameters for the connection.  Valid keys
+     in that list are:
+    `port'
+          The TCP port to use for the connection if different from
+          `ldap-default-port' or the library builtin value

 
 

-   In the following example, we set the value of a symbol with `setq'.
-Then we evaluate the symbol, and get back the value that `setq' stored.
+    `auth'
+          The authentication method to use, possible values depend on
+          the LDAP library XEmacs was compiled with, they may include
+          `simple', `krbv41' and `krbv42'.

 
 

-     (setq a 123)
-          => 123
-     (eval 'a)
-          => 123
-     a
-          => 123
+    `binddn'
+          The distinguished name of the user to bind as.  This may look
+          like `c=com, o=Acme, cn=Babs Jensen', see RFC 1779 for
+          details.

 
 

-   The symbols `nil' and `t' are treated specially, so that the value
-of `nil' is always `nil', and the value of `t' is always `t'; you
-cannot set or bind them to any other values.  Thus, these two symbols
-act like self-evaluating forms, even though `eval' treats them like any
-other symbol.
+    `passwd'
+          The password to use for authentication.
+
+    `deref'
+          The dereference policy is one of the symbols `never',
+          `always', `search' or `find' and defines how aliases are
+          dereferenced.
+         `never'
+               Aliases are never dereferenced.
+
+         `always'
+               Aliases are always dereferenced.
+
+         `search'
+               Aliases are dereferenced when searching.
+
+         `find'
+               Aliases are dereferenced when locating the base object
+               for the search.
+          The default is `never'.
+
+    `timelimit'
+          The timeout limit for the connection in seconds.
+
+    `sizelimit'
+          The maximum number of matches to return for searches
+          performed on this connection.
+
+ - Function: ldap-close ldap
+     Close the connection represented by LDAP.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Classifying Lists,  Next: Function Indirection,  Prev: Symbol Forms,  Up: Forms
+File: lispref.info,  Node: Low-level Operations on a LDAP Server,  Prev: Opening and Closing a LDAP Connection,  Up: The Low-Level LDAP API
+
+Low-level Operations on a LDAP Server
+.....................................
+
+`ldap-search-basic' is the low-level primitive to perform a search on a
+LDAP server.  It works directly on an open LDAP connection thus
+requiring a preliminary call to `ldap-open'.  Multiple searches can be
+made on the same connection, then the session must be closed with
+`ldap-close'.
+
+ - Function: ldap-search-basic ldap filter &optional base scope attrs
+          attrsonly withdn verbose
+     Perform a search on an open connection LDAP created with
+     `ldap-open'.  FILTER is a filter string for the search *note
+     Syntax of Search Filters:: BASE is the distinguished name at which
+     to start the search.  SCOPE is one of the symbols `base',
+     `onelevel' or `subtree' indicating the scope of the search limited
+     to a base object, to a single level or to the whole subtree.  The
+     default is `subtree'.  ATTRS is a list of strings indicating which
+     attributes to retrieve for each matching entry. If `nil' all
+     available attributes are returned.  If ATTRSONLY is non-`nil' then
+     only the attributes are retrieved, not their associated values.
+     If WITHDN is non-`nil' then each entry in the result is prepended
+     with its distinguished name DN.  If VERBOSE is non-`nil' then
+     progress messages are echoed The function returns a list of
+     matching entries.  Each entry  is itself an alist of
+     attribute/value pairs optionally preceded by the DN of the entry
+     according to the value of WITHDN.
+
+ - Function: ldap-add ldap dn entry
+     Add ENTRY to a LDAP directory which a connection LDAP has been
+     opened to with `ldap-open'.  DN is the distinguished name of the
+     entry to add.  ENTRY is an entry specification, i.e., a list of
+     cons cells containing attribute/value string pairs.
+
+ - Function: ldap-modify ldap dn mods
+     Modify an entry in an LDAP directory.  LDAP is an LDAP connection
+     object created with `ldap-open'.  DN is the distinguished name of
+     the entry to modify.  MODS is a list of modifications to apply.  A
+     modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2
+     ...)'  MOD-OP and ATTR are mandatory, VALUES are optional
+     depending on MOD-OP.  MOD-OP is the type of modification, one of
+     the symbols `add', `delete' or `replace'. ATTR is the LDAP
+     attribute type to modify.
+
+ - Function: ldap-delete ldap dn
+     Delete an entry to an LDAP directory.  LDAP is an LDAP connection
+     object created with `ldap-open'.  DN is the distinguished name of
+     the entry to delete.

 
 

-Classification of List Forms
-----------------------------
+\1f
+File: lispref.info,  Node: LDAP Internationalization,  Prev: The Low-Level LDAP API,  Up: XEmacs LDAP API

 
 

-   A form that is a nonempty list is either a function call, a macro
-call, or a special form, according to its first element.  These three
-kinds of forms are evaluated in different ways, described below.  The
-remaining list elements constitute the "arguments" for the function,
-macro, or special form.
-
-   The first step in evaluating a nonempty list is to examine its first
-element.  This element alone determines what kind of form the list is
-and how the rest of the list is to be processed.  The first element is
-_not_ evaluated, as it would be in some Lisp dialects such as Scheme.
-
-\1f
-File: lispref.info,  Node: Function Indirection,  Next: Function Forms,  Prev: Classifying Lists,  Up: Forms
-
-Symbol Function Indirection
----------------------------
-
-   If the first element of the list is a symbol then evaluation examines
-the symbol's function cell, and uses its contents instead of the
-original symbol.  If the contents are another symbol, this process,
-called "symbol function indirection", is repeated until it obtains a
-non-symbol.  *Note Function Names::, for more information about using a
-symbol as a name for a function stored in the function cell of the
-symbol.
-
-   One possible consequence of this process is an infinite loop, in the
-event that a symbol's function cell refers to the same symbol.  Or a
-symbol may have a void function cell, in which case the subroutine
-`symbol-function' signals a `void-function' error.  But if neither of
-these things happens, we eventually obtain a non-symbol, which ought to
-be a function or other suitable object.
-
-   More precisely, we should now have a Lisp function (a lambda
-expression), a byte-code function, a primitive function, a Lisp macro, a
-special form, or an autoload object.  Each of these types is a case
-described in one of the following sections.  If the object is not one of
-these types, the error `invalid-function' is signaled.
-
-   The following example illustrates the symbol indirection process.  We
-use `fset' to set the function cell of a symbol and `symbol-function'
-to get the function cell contents (*note Function Cells::).
-Specifically, we store the symbol `car' into the function cell of
-`first', and the symbol `first' into the function cell of `erste'.
-
-     ;; Build this function cell linkage:
-     ;;   -------------       -----        -------        -------
-     ;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
-     ;;   -------------       -----        -------        -------
-
-     (symbol-function 'car)
-          => #<subr car>
-     (fset 'first 'car)
-          => car
-     (fset 'erste 'first)
-          => first
-     (erste '(1 2 3))   ; Call the function referenced by `erste'.
-          => 1
-
-   By contrast, the following example calls a function without any
-symbol function indirection, because the first element is an anonymous
-Lisp function, not a symbol.
-
-     ((lambda (arg) (erste arg))
-      '(1 2 3))
-          => 1
-
-Executing the function itself evaluates its body; this does involve
-symbol function indirection when calling `erste'.
-
-   The built-in function `indirect-function' provides an easy way to
-perform symbol function indirection explicitly.
-
- - Function: indirect-function object
-     This function returns the meaning of OBJECT as a function.  If
-     OBJECT is a symbol, then it finds OBJECT's function definition and
-     starts over with that value.  If OBJECT is not a symbol, then it
-     returns OBJECT itself.
-
-     Here is how you could define `indirect-function' in Lisp:
-
-          (defun indirect-function (function)
-            (if (symbolp function)
-                (indirect-function (symbol-function function))
-              function))
-
-\1f
-File: lispref.info,  Node: Function Forms,  Next: Macro Forms,  Prev: Function Indirection,  Up: Forms
-
-Evaluation of Function Forms
-----------------------------
+LDAP Internationalization
+-------------------------
+
+The XEmacs LDAP API provides basic internationalization features based
+on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 Attribute
+Syntax Definitions").  Unfortunately since there is currently no free
+LDAP v3 server software, this part has not received much testing and
+should be considered experimental.  The framework is in place though.
+
+ - Function: ldap-decode-attribute attr
+     Decode the attribute/value pair ATTR according to LDAP rules.  The
+     attribute name is looked up in `ldap-attribute-syntaxes-alist' and
+     the corresponding decoder is then retrieved from
+     `ldap-attribute-syntax-decoders'' and applied on the value(s).

 
 

-   If the first element of a list being evaluated is a Lisp function
-object, byte-code object or primitive function object, then that list is
-a "function call".  For example, here is a call to the function `+':
+* Menu:

 
 

-     (+ 1 x)
+* LDAP Internationalization Variables::
+* Encoder/Decoder Functions::

 
 

-   The first step in evaluating a function call is to evaluate the
-remaining elements of the list from left to right.  The results are the
-actual argument values, one value for each list element.  The next step
-is to call the function with this list of arguments, effectively using
-the function `apply' (*note Calling Functions::).  If the function is
-written in Lisp, the arguments are used to bind the argument variables
-of the function (*note Lambda Expressions::); then the forms in the
-function body are evaluated in order, and the value of the last body
-form becomes the value of the function call.
+\1f
+File: lispref.info,  Node: LDAP Internationalization Variables,  Next: Encoder/Decoder Functions,  Prev: LDAP Internationalization,  Up: LDAP Internationalization
+
+LDAP Internationalization Variables
+...................................
+
+ - Variable: ldap-ignore-attribute-codings
+     If non-`nil', no encoding/decoding will be performed LDAP
+     attribute values
+
+ - Variable: ldap-coding-system
+     Coding system of LDAP string values.  LDAP v3 specifies the coding
+     system of strings to be UTF-8.  You need an XEmacs with Mule
+     support for this.
+
+ - Variable: ldap-default-attribute-decoder
+     Decoder function to use for attributes whose syntax is unknown.
+     Such a function receives an encoded attribute value as a string
+     and should return the decoded value as a string.
+
+ - Variable: ldap-attribute-syntax-encoders
+     A vector of functions used to encode LDAP attribute values.  The
+     sequence of functions corresponds to the sequence of LDAP
+     attribute syntax object identifiers of the form
+     1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2.
+     As of this writing, only a few encoder functions are available.
+
+ - Variable: ldap-attribute-syntax-decoders
+     A vector of functions used to decode LDAP attribute values.  The
+     sequence of functions corresponds to the sequence of LDAP
+     attribute syntax object identifiers of the form
+     1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2.
+     As of this writing, only a few decoder functions are available.
+
+ - Variable: ldap-attribute-syntaxes-alist
+     A map of LDAP attribute names to their type object id minor number.
+     This table is built from RFC2252 Section 5 and RFC2256 Section 5.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Macro Forms,  Next: Special Forms,  Prev: Function Forms,  Up: Forms
+File: lispref.info,  Node: Encoder/Decoder Functions,  Prev: LDAP Internationalization Variables,  Up: LDAP Internationalization

 
 

-Lisp Macro Evaluation
----------------------
+Encoder/Decoder Functions
+.........................
+
+ - Function: ldap-encode-boolean bool
+     A function that encodes an elisp boolean BOOL into a LDAP boolean
+     string representation.
+
+ - Function: ldap-decode-boolean str
+     A function that decodes a LDAP boolean string representation STR
+     into an elisp boolean.
+
+ - Function: ldap-decode-string str
+     Decode a string STR according to `ldap-coding-system'.
+
+ - Function: ldap-encode-string str
+     Encode a string STR according to `ldap-coding-system'.
+
+ - Function: ldap-decode-address str
+     Decode an address STR according to `ldap-coding-system' and
+     replacing $ signs with newlines as specified by LDAP encoding
+     rules for addresses.
+
+ - Function: ldap-encode-address str
+     Encode an address STR according to `ldap-coding-system' and
+     replacing newlines with $ signs as specified by LDAP encoding
+     rules for addresses.
+
+\1f
+File: lispref.info,  Node: Syntax of Search Filters,  Prev: XEmacs LDAP API,  Up: LDAP Support
+
+Syntax of Search Filters
+========================

 
 

-   If the first element of a list being evaluated is a macro object,
-then the list is a "macro call".  When a macro call is evaluated, the
-elements of the rest of the list are _not_ initially evaluated.
-Instead, these elements themselves are used as the arguments of the
-macro.  The macro definition computes a replacement form, called the
-"expansion" of the macro, to be evaluated in place of the original
-form.  The expansion may be any sort of form: a self-evaluating
-constant, a symbol, or a list.  If the expansion is itself a macro call,
-this process of expansion repeats until some other sort of form results.
+LDAP search functions use RFC1558 syntax to describe the search filter.
+In that syntax simple filters have the form:

 
 

-   Ordinary evaluation of a macro call finishes by evaluating the
-expansion.  However, the macro expansion is not necessarily evaluated
-right away, or at all, because other programs also expand macro calls,
-and they may or may not evaluate the expansions.
+     (<attr> <filtertype> <value>)

 
 

-   Normally, the argument expressions are not evaluated as part of
-computing the macro expansion, but instead appear as part of the
-expansion, so they are computed when the expansion is computed.
+   `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...

 
 

-   For example, given a macro defined as follows:
+   `<value>' is the corresponding value.  This is generally an exact
+string but may also contain `*' characters as wildcards

 
 

-     (defmacro cadr (x)
-       (list 'car (list 'cdr x)))
+   `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.

 
 

-an expression such as `(cadr (assq 'handler list))' is a macro call,
-and its expansion is:
+   Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.

 
 

-     (car (cdr (assq 'handler list)))
+   A special case is the presence filter `(<attr>=*' which matches
+records containing a particular attribute.  For instance `(mail=*)'
+matches all records containing a `mail' attribute.

 
 

-Note that the argument `(assq 'handler list)' appears in the expansion.
+   Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.

 
 

-   *Note Macros::, for a complete description of XEmacs Lisp macros.
+   `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
+matches records of class `Person' containing a `mail' attribute and
+corresponding to people whose last name is `Smith' or whose first name
+is `John'.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Special Forms,  Next: Autoloading,  Prev: Macro Forms,  Up: Forms
+File: lispref.info,  Node: PostgreSQL Support,  Next: Internationalization,  Prev: LDAP Support,  Up: Top

 
 

-Special Forms
--------------
+PostgreSQL Support
+******************
+
+XEmacs can be linked with PostgreSQL libpq run-time support to provide
+relational database access from Emacs Lisp code.
+
+* Menu:
+
+* Building XEmacs with PostgreSQL support::
+* XEmacs PostgreSQL libpq API::
+* XEmacs PostgreSQL libpq Examples::
+
+\1f
+File: lispref.info,  Node: Building XEmacs with PostgreSQL support,  Next: XEmacs PostgreSQL libpq API,  Up: PostgreSQL Support
+
+Building XEmacs with PostgreSQL support
+=======================================

 
 

-   A "special form" is a primitive function specially marked so that
-its arguments are not all evaluated.  Most special forms define control
-structures or perform variable bindings--things which functions cannot
-do.
+XEmacs PostgreSQL support requires linking to the PostgreSQL libpq
+library.  Describing how to build and install PostgreSQL is beyond the
+scope of this document.  See the PostgreSQL manual for details.

 
 

-   Each special form has its own rules for which arguments are evaluated
-and which are used without evaluation.  Whether a particular argument is
-evaluated may depend on the results of evaluating other arguments.
+   If you have installed XEmacs from one of the binary kits on
+(<ftp://ftp.xemacs.org/>), or are using an XEmacs binary from a CD ROM,
+you may have XEmacs PostgreSQL support by default.  `M-x
+describe-installation' will tell you if you do.

 
 

-   Here is a list, in alphabetical order, of all of the special forms in
-XEmacs Lisp with a reference to where each is described.
+   If you are building XEmacs from source, you need to install
+PostgreSQL first.  On some systems, PostgreSQL will come pre-installed
+in /usr.  In this case, it should be autodetected when you run
+configure.  If PostgreSQL is installed into its default location,
+`/usr/local/pgsql', you must specify `--site-prefixes=/usr/local/pgsql'
+when you run configure.  If PostgreSQL is installed into another
+location, use that instead of `/usr/local/pgsql' when specifying
+`--site-prefixes'.

 
 

-`and'
-     *note Combining Conditions::
+   As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported.
+XEmacs Lisp support for V7.0 is somewhat more extensive than support for
+V6.5.  In particular, asynchronous queries are supported.

 
 

-`catch'
-     *note Catch and Throw::
+\1f
+File: lispref.info,  Node: XEmacs PostgreSQL libpq API,  Next: XEmacs PostgreSQL libpq Examples,  Prev: Building XEmacs with PostgreSQL support,  Up: PostgreSQL Support
+
+XEmacs PostgreSQL libpq API
+===========================
+
+The XEmacs PostgreSQL API is intended to be a policy-free, low-level
+binding to libpq.  The intent is to provide all the basic functionality
+and then let high level Lisp code decide its own policies.
+
+   This documentation assumes that the reader has knowledge of SQL, but
+requires no prior knowledge of libpq.
+
+   There are many examples in this manual and some setup will be
+required.  In order to run most of the following examples, the
+following code needs to be executed.  In addition to the data is in
+this table, nearly all of the examples will assume that the free
+variable `P' refers to this database connection.  The examples in the
+original edition of this manual were run against Postgres 7.0beta1.
+
+     (progn
+       (setq P (pq-connectdb ""))
+       ;; id is the primary key, shikona is a Japanese word that
+       ;; means `the professional name of a Sumo wrestler', and
+       ;; rank is the Sumo rank name.
+       (pq-exec P (concat "CREATE TABLE xemacs_test"
+                          " (id int, shikona text, rank text);"))
+       (pq-exec P "COPY xemacs_test FROM stdin;")
+       (pq-put-line P "1\tMusashimaru\tYokuzuna\n")
+       (pq-put-line P "2\tDejima\tOozeki\n")
+       (pq-put-line P "3\tMusoyama\tSekiwake\n")
+       (pq-put-line P "4\tMiyabiyama\tSekiwake\n")
+       (pq-put-line P "5\tWakanoyama\tMaegashira\n")
+       (pq-put-line P "\\.\n")
+       (pq-end-copy P))
+          => nil

 
 

-`cond'
-     *note Conditionals::
+* Menu:

 
 

-`condition-case'
-     *note Handling Errors::
+* libpq Lisp Variables::
+* libpq Lisp Symbols and DataTypes::
+* Synchronous Interface Functions::
+* Asynchronous Interface Functions::
+* Large Object Support::
+* Other libpq Functions::
+* Unimplemented libpq Functions::

 
 

-`defconst'
-     *note Defining Variables::
+\1f
+File: lispref.info,  Node: libpq Lisp Variables,  Next: libpq Lisp Symbols and DataTypes,  Prev: XEmacs PostgreSQL libpq API,  Up: XEmacs PostgreSQL libpq API

 
 

-`defmacro'
-     *note Defining Macros::
+libpq Lisp Variables
+--------------------

 
 

-`defun'
-     *note Defining Functions::
+Various Unix environment variables are used by libpq to provide defaults
+to the many different parameters.  In the XEmacs Lisp API, these
+environment variables are bound to Lisp variables to provide more
+convenient access to Lisp Code.  These variables are passed to the
+backend database server during the establishment of a database
+connection and when the `pq-setenv' call is made.

 
 

-`defvar'
-     *note Defining Variables::
+ - Variable: pg:host
+     Initialized from the `PGHOST' environment variable.  The default
+     host to connect to.

 
 

-`function'
-     *note Anonymous Functions::
+ - Variable: pg:user
+     Initialized from the `PGUSER' environment variable.  The default
+     database user name.

 
 

-`if'
-     *note Conditionals::
+ - Variable: pg:options
+     Initialized from the `PGOPTIONS' environment variable.  Default
+     additional server options.

 
 

-`interactive'
-     *note Interactive Call::
+ - Variable: pg:port
+     Initialized from the `PGPORT' environment variable.  The default
+     TCP port to connect to.

 
 

-`let'
-`let*'
-     *note Local Variables::
+ - Variable: pg:tty
+     Initialized from the `PGTTY' environment variable.  The default
+     debugging TTY.

 
 

-`or'
-     *note Combining Conditions::
+     Compatibility note:  Debugging TTYs are turned off in the XEmacs
+     Lisp binding.

 
 

-`prog1'
-`prog2'
-`progn'
-     *note Sequencing::
+ - Variable: pg:database
+     Initialized from the `PGDATABASE' environment variable.  The
+     default database to connect to.

 
 

-`quote'
-     *note Quoting::
+ - Variable: pg:realm
+     Initialized from the `PGREALM' environment variable.  The default
+     Kerberos realm.

 
 

-`save-current-buffer'
-     *note Excursions::
+ - Variable: pg:client-encoding
+     Initialized from the `PGCLIENTENCODING' environment variable.  The
+     default client encoding.

 
 

-`save-excursion'
-     *note Excursions::
+     Compatibility note:  This variable is not present in non-Mule
+     XEmacsen.  This variable is not present in versions of libpq prior
+     to 7.0.  In the current implementation, client encoding is
+     equivalent to the `file-name-coding-system' format.

 
 

-`save-restriction'
-     *note Narrowing::
+ - Variable: pg:authtype
+     Initialized from the `PGAUTHTYPE' environment variable.  The
+     default authentication scheme used.

 
 

-`save-selected-window'
-     *note Excursions::
+     Compatibility note:  This variable is unused in versions of libpq
+     after 6.5.  It is not implemented at all in the XEmacs Lisp
+     binding.

 
 

-`save-window-excursion'
-     *note Window Configurations::
+ - Variable: pg:geqo
+     Initialized from the `PGGEQO' environment variable.  Genetic
+     optimizer options.

 
 

-`setq'
-     *note Setting Variables::
+ - Variable: pg:cost-index
+     Initialized from the `PGCOSTINDEX' environment variable.  Cost
+     index options.

 
 

-`setq-default'
-     *note Creating Buffer-Local::
+ - Variable: pg:cost-heap
+     Initialized from the `PGCOSTHEAP' environment variable.  Cost heap
+     options.

 
 

-`unwind-protect'
-     *note Nonlocal Exits::
+ - Variable: pg:tz
+     Initialized from the `PGTZ' environment variable.  Default
+     timezone.

 
 

-`while'
-     *note Iteration::
+ - Variable: pg:date-style
+     Initialized from the `PGDATESTYLE' environment variable.  Default
+     date style in returned date objects.

 
 

-`with-output-to-temp-buffer'
-     *note Temporary Displays::
+ - Variable: pg-coding-system
+     This is a variable controlling which coding system is used to
+     encode non-ASCII strings sent to the database.

 
 

-     Common Lisp note: here are some comparisons of special forms in
-     XEmacs Lisp and Common Lisp.  `setq', `if', and `catch' are
-     special forms in both XEmacs Lisp and Common Lisp.  `defun' is a
-     special form in XEmacs Lisp, but a macro in Common Lisp.
-     `save-excursion' is a special form in XEmacs Lisp, but doesn't
-     exist in Common Lisp.  `throw' is a special form in Common Lisp
-     (because it must be able to throw multiple values), but it is a
-     function in XEmacs Lisp (which doesn't have multiple values).
+     Compatibility Note: This variable is not present in InfoDock.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Autoloading,  Prev: Special Forms,  Up: Forms
+File: lispref.info,  Node: libpq Lisp Symbols and DataTypes,  Next: Synchronous Interface Functions,  Prev: libpq Lisp Variables,  Up: XEmacs PostgreSQL libpq API

 
 

-Autoloading
------------
+libpq Lisp Symbols and Datatypes
+--------------------------------
+
+The following set of symbols are used to represent the intermediate
+states involved in the asynchronous interface.
+
+ - Symbol: pgres::polling-failed
+     Undocumented.  A fatal error has occurred during processing of an
+     asynchronous operation.
+
+ - Symbol: pgres::polling-reading
+     An intermediate status return during an asynchronous operation.  It
+     indicates that one may use `select' before polling again.
+
+ - Symbol: pgres::polling-writing
+     An intermediate status return during an asynchronous operation.  It
+     indicates that one may use `select' before polling again.
+
+ - Symbol: pgres::polling-ok
+     An asynchronous operation has successfully completed.
+
+ - Symbol: pgres::polling-active
+     An intermediate status return during an asynchronous operation.
+     One can call the poll function again immediately.
+
+ - Function: pq-pgconn conn field
+     CONN A database connection object.  FIELD A symbol indicating
+     which field of PGconn to fetch.  Possible values are shown in the
+     following table.
+    `pq::db'
+          Database name
+
+    `pq::user'
+          Database user name
+
+    `pq::pass'
+          Database user's password
+
+    `pq::host'
+          Hostname database server is running on
+
+    `pq::port'
+          TCP port number used in the connection
+
+    `pq::tty'
+          Debugging TTY
+
+          Compatibility note:  Debugging TTYs are not used in the
+          XEmacs Lisp API.
+
+    `pq::options'
+          Additional server options
+
+    `pq::status'
+          Connection status.  Possible return values are shown in the
+          following table.
+         `pg::connection-ok'
+               The normal, connected status.
+
+         `pg::connection-bad'
+               The connection is not open and the PGconn object needs
+               to be deleted by `pq-finish'.
+
+         `pg::connection-started'
+               An asynchronous connection has been started, but is not
+               yet complete.
+
+         `pg::connection-made'
+               An asynchronous connect has been made, and there is data
+               waiting to be sent.
+
+         `pg::connection-awaiting-response'
+               Awaiting data from the backend during an asynchronous
+               connection.

 
 

-   The "autoload" feature allows you to call a function or macro whose
-function definition has not yet been loaded into XEmacs.  It specifies
-which file contains the definition.  When an autoload object appears as
-a symbol's function definition, calling that symbol as a function
-automatically loads the specified file; then it calls the real
-definition loaded from that file.  *Note Autoload::.
+         `pg::connection-auth-ok'
+               Received authentication, waiting for the backend to
+               start up.
+
+         `pg::connection-setenv'
+               Negotiating environment during an asynchronous
+               connection.
+
+    `pq::error-message'
+          The last error message that was delivered to this connection.
+
+    `pq::backend-pid'
+          The process ID of the backend database server.
+
+   The `PGresult' object is used by libpq to encapsulate the results of
+queries.  The printed representation takes on four forms.  When the
+PGresult object contains tuples from an SQL `SELECT' it will look like:
+
+     (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+          => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+
+   The number in brackets indicates how many rows of data are available.
+When the PGresult object is the result of a command query that doesn't
+return anything, it will look like:
+
+     (pq-exec P "CREATE TABLE a_new_table (i int);")
+          => #<PGresult PGRES_COMMAND_OK - CREATE>
+
+   When either the query is a command-type query that can affect a
+number of different rows, but doesn't return any of them it will look
+like:
+
+     (progn
+       (pq-exec P "INSERT INTO a_new_table VALUES (1);")
+       (pq-exec P "INSERT INTO a_new_table VALUES (2);")
+       (pq-exec P "INSERT INTO a_new_table VALUES (3);")
+       (setq R (pq-exec P "DELETE FROM a_new_table;")))
+          => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
+
+   Lastly, when the underlying PGresult object has been deallocated
+directly by `pq-clear' the printed representation will look like:
+
+     (progn
+       (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+       (pq-clear R)
+       R)
+          => #<PGresult DEAD>
+
+   The following set of functions are accessors to various data in the
+PGresult object.
+
+ - Function: pq-result-status result
+     Return status of a query result.  RESULT is a PGresult object.
+     The return value is one of the symbols in the following table.
+    `pgres::empty-query'
+          A query contained no text.  This is usually the result of a
+          recoverable error, or a minor programming error.
+
+    `pgres::command-ok'
+          A query command that doesn't return anything was executed
+          properly by the backend.
+
+    `pgres::tuples-ok'
+          A query command that returns tuples was executed properly by
+          the backend.
+
+    `pgres::copy-out'
+          Copy Out data transfer is in progress.
+
+    `pgres::copy-in'
+          Copy In data transfer is in progress.
+
+    `pgres::bad-response'
+          An unexpected response was received from the backend.
+
+    `pgres::nonfatal-error'
+          Undocumented.  This value is returned when the libpq function
+          `PQresultStatus' is called with a `NULL' pointer.
+
+    `pgres::fatal-error'
+          Undocumented.  An error has occurred in processing the query
+          and the operation was not completed.
+
+ - Function: pq-res-status result
+     Return the query result status as a string, not a symbol.  RESULT
+     is a PGresult object.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-res-status R)
+               => "PGRES_TUPLES_OK"
+
+ - Function: pq-result-error-message result
+     Return an error message generated by the query, if any.  RESULT is
+     a PGresult object.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
+               => <A fatal error is signaled in the echo area>
+          (pq-result-error-message R)
+               => "ERROR:  parser: parse error at or near \"-\"
+          "
+
+ - Function: pq-ntuples result
+     Return the number of tuples in the query result.  RESULT is a
+     PGresult object.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-ntuples R)
+               => 5
+
+ - Function: pq-nfields result
+     Return the number of fields in each tuple of the query result.
+     RESULT is a PGresult object.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-nfields R)
+               => 3
+
+ - Function: pq-binary-tuples result
+     Returns t if binary tuples are present in the results, nil
+     otherwise.  RESULT is a PGresult object.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-binary-tuples R)
+               => nil
+
+ - Function: pq-fname result field-index
+     Returns the name of a specific field.  RESULT is a PGresult object.
+     FIELD-INDEX is the number of the column to select from.  The first
+     column is number zero.
+
+          (let (i l)
+            (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+            (setq i (pq-nfields R))
+            (while (>= (decf i) 0)
+              (push (pq-fname R i) l))
+            l)
+               => ("id" "shikona" "rank")
+
+ - Function: pq-fnumber result field-name
+     Return the field number corresponding to the given field name.  -1
+     is returned on a bad field name.  RESULT is a PGresult object.
+     FIELD-NAME is a string representing the field name to find.
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-fnumber R "id")
+               => 0
+          (pq-fnumber R "Not a field")
+               => -1
+
+ - Function: pq-ftype result field-num
+     Return an integer code representing the data type of the specified
+     column.  RESULT is a PGresult object.  FIELD-NUM is the field
+     number.
+
+     The return value of this function is the Object ID (Oid) in the
+     database of the type.  Further queries need to be made to various
+     system tables in order to convert this value into something useful.
+
+ - Function: pq-fmod result field-num
+     Return the type modifier code associated with a field.  Field
+     numbers start at zero.  RESULT is a PGresult object.  FIELD-INDEX
+     selects which field to use.
+
+ - Function: pq-fsize result field-index
+     Return size of the given field.  RESULT is a PGresult object.
+     FIELD-INDEX selects which field to use.
+
+          (let (i l)
+            (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+            (setq i (pq-nfields R))
+            (while (>= (decf i) 0)
+              (push (list (pq-ftype R i) (pq-fsize R i)) l))
+            l)
+               => ((23 23) (25 25) (25 25))
+
+ - Function: pq-get-value result tup-num field-num
+     Retrieve a return value.  RESULT is a PGresult object.  TUP-NUM
+     selects which tuple to fetch from.  FIELD-NUM selects which field
+     to fetch from.
+
+     Both tuples and fields are numbered from zero.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-get-value R 0 1)
+               => "Musashimaru"
+          (pq-get-value R 1 1)
+               => "Dejima"
+          (pq-get-value R 2 1)
+               => "Musoyama"
+
+ - Function: pq-get-length result tup-num field-num
+     Return the length of a specific value.  RESULT is a PGresult
+     object.  TUP-NUM selects which tuple to fetch from.  FIELD-NUM
+     selects which field to fetch from.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+          (pq-get-length R 0 1)
+               => 11
+          (pq-get-length R 1 1)
+               => 6
+          (pq-get-length R 2 1)
+               => 8
+
+ - Function: pq-get-is-null result tup-num field-num
+     Return t if the specific value is the SQL `NULL'.  RESULT is a
+     PGresult object.  TUP-NUM selects which tuple to fetch from.
+     FIELD-NUM selects which field to fetch from.
+
+ - Function: pq-cmd-status result
+     Return a summary string from the query.  RESULT is a PGresult
+     object.
+          (setq R (pq-exec P "INSERT INTO xemacs_test
+                             VALUES (6, 'Wakanohana', 'Yokozuna');"))
+               => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
+          (pq-cmd-status R)
+               => "INSERT 542086 1"
+          (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
+                              WHERE shikona='Wakanohana';"))
+               => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
+          (pq-cmd-status R)
+               => "UPDATE 1"
+
+     Note that the first number returned from an insertion, like in the
+     example, is an object ID number and will almost certainly vary from
+     system to system since object ID numbers in Postgres must be unique
+     across all databases.
+
+ - Function: pq-cmd-tuples result
+     Return the number of tuples if the last command was an
+     INSERT/UPDATE/DELETE.  If the last command was something else, the
+     empty string is returned.  RESULT is a PGresult object.
+
+          (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
+                              (7, 'Takanohana', 'Yokuzuna');"))
+               => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
+          (pq-cmd-tuples R)
+               => "1"
+          (setq R (pq-exec P "SELECT * from xemacs_test;"))
+               => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
+          (pq-cmd-tuples R)
+               => ""
+          (setq R (pq-exec P "DELETE FROM xemacs_test
+                              WHERE shikona LIKE '%hana';"))
+               => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
+          (pq-cmd-tuples R)
+               => "2"
+
+ - Function: pq-oid-value result
+     Return the object id of the insertion if the last command was an
+     INSERT.  0 is returned if the last command was not an insertion.
+     RESULT is a PGresult object.
+
+     In the first example, the numbers you will see on your local
+     system will almost certainly be different, however the second
+     number from the right in the unprintable PGresult object and the
+     number returned by `pq-oid-value' should match.
+          (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
+                              (8, 'Terao', 'Maegashira');"))
+               => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
+          (pq-oid-value R)
+               => 542089
+          (setq R (pq-exec P "SELECT shikona FROM xemacs_test
+                              WHERE rank='Maegashira';"))
+               => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
+          (pq-oid-value R)
+               => 0
+
+ - Function: pq-make-empty-pgresult conn status
+     Create an empty pgresult with the given status.  CONN a database
+     connection object STATUS a value that can be returned by
+     `pq-result-status'.
+
+     The caller is responsible for making sure the return value gets
+     properly freed.
+
+\1f
+File: lispref.info,  Node: Synchronous Interface Functions,  Next: Asynchronous Interface Functions,  Prev: libpq Lisp Symbols and DataTypes,  Up: XEmacs PostgreSQL libpq API
+
+Synchronous Interface Functions
+-------------------------------
+
+ - Function: pq-connectdb conninfo
+     Establish a (synchronous) database connection.  CONNINFO A string
+     of blank separated options.  Options are of the form "OPTION =
+     VALUE".  If VALUE contains blanks, it must be single quoted.
+     Blanks around the equal sign are optional.  Multiple option
+     assignments are blank separated.
+          (pq-connectdb "dbname=japanese port = 25432")
+               => #<PGconn localhost:25432 steve/japanese>
+     The printed representation of a database connection object has four
+     fields.  The first field is the hostname where the database server
+     is running (in this case localhost), the second field is the port
+     number, the third field is the database user name, and the fourth
+     field is the name of the database.
+
+     Database connection objects which have been disconnected and will
+     generate an immediate error if they are used look like:
+            #<PGconn BAD>
+     Bad connections can be reestablished with `pq-reset', or deleted
+     entirely with `pq-finish'.
+
+     A database connection object that has been deleted looks like:
+          (let ((P1 (pq-connectdb "")))
+            (pq-finish P1)
+            P1)
+               => #<PGconn DEAD>
+
+     Note that database connection objects are the most heavy weight
+     objects in XEmacs Lisp at this writing, usually representing as
+     much as several megabytes of virtual memory on the machine the
+     database server is running on.  It is wisest to explicitly delete
+     them when you are finished with them, rather than letting garbage
+     collection do it.  An example idiom is:
+
+          (let ((P (pq-connectiondb "")))
+            (unwind-protect
+                (progn
+               (...)) ; access database here
+              (pq-finish P)))
+
+     The following options are available in the options string:
+    `authtype'
+          Authentication type.  Same as `PGAUTHTYPE'.  This is no
+          longer used.
+
+    `user'
+          Database user name.  Same as `PGUSER'.
+
+    `password'
+          Database password.
+
+    `dbname'
+          Database name.  Same as `PGDATABASE'
+
+    `host'
+          Symbolic hostname.  Same as `PGHOST'.
+
+    `hostaddr'
+          Host address as four octets (eg. like 192.168.1.1).
+
+    `port'
+          TCP port to connect to.  Same as `PGPORT'.
+
+    `tty'
+          Debugging TTY.  Same as `PGTTY'.  This value is suppressed in
+          the XEmacs Lisp API.
+
+    `options'
+          Extra backend database options.  Same as `PGOPTIONS'.
+     A database connection object is returned regardless of whether a
+     connection was established or not.
+
+ - Function: pq-reset conn
+     Reestablish database connection.  CONN A database connection
+     object.
+
+     This function reestablishes a database connection using the
+     original connection parameters.  This is useful if something has
+     happened to the TCP link and it has become broken.
+
+ - Function: pq-exec conn query
+     Make a synchronous database query.  CONN A database connection
+     object.  QUERY A string containing an SQL query.  A PGresult
+     object is returned, which in turn may be queried by its many
+     accessor functions to retrieve state out of it.  If the query
+     string contains multiple SQL commands, only results from the final
+     command are returned.
+
+          (setq R (pq-exec P "SELECT * FROM xemacs_test;
+          DELETE FROM xemacs_test WHERE id=8;"))
+               => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
+
+ - Function: pq-notifies conn
+     Return the latest async notification that has not yet been handled.
+     CONN A database connection object.  If there has been a
+     notification, then a list of two elements will be returned.  The
+     first element contains the relation name being notified, the second
+     element contains the backend process ID number.  nil is returned
+     if there aren't any notifications to process.
+
+ - Function: PQsetenv conn
+     Synchronous transfer of environment variables to a backend CONN A
+     database connection object.
+
+     Environment variable transfer is done as a normal part of database
+     connection.
+
+     Compatibility note: This function was present but not documented
+     in versions of libpq prior to 7.0.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Quoting,  Prev: Forms,  Up: Evaluation
+File: lispref.info,  Node: Asynchronous Interface Functions,  Next: Large Object Support,  Prev: Synchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
+
+Asynchronous Interface Functions
+--------------------------------
+
+Making command by command examples is too complex with the asynchronous
+interface functions.  See the examples section for complete calling
+sequences.
+
+ - Function: pq-connect-start conninfo
+     Begin establishing an asynchronous database connection.  CONNINFO
+     A string containing the connection options.  See the documentation
+     of `pq-connectdb' for a listing of all the available flags.
+
+ - Function: pq-connect-poll conn
+     An intermediate function to be called during an asynchronous
+     database connection.  CONN A database connection object.  The
+     result codes are documented in a previous section.
+
+ - Function: pq-is-busy conn
+     Returns t if `pq-get-result' would block waiting for input.  CONN
+     A database connection object.
+
+ - Function: pq-consume-input conn
+     Consume any available input from the backend.  CONN A database
+     connection object.
+
+     Nil is returned if anything bad happens.

 
 

-Quoting
-=======
+ - Function: pq-reset-start conn
+     Reset connection to the backend asynchronously.  CONN A database
+     connection object.

 
 

-   The special form `quote' returns its single argument, as written,
-without evaluating it.  This provides a way to include constant symbols
-and lists, which are not self-evaluating objects, in a program.  (It is
-not necessary to quote self-evaluating objects such as numbers, strings,
-and vectors.)
+ - Function: pq-reset-poll conn
+     Poll an asynchronous reset for completion CONN A database
+     connection object.

 
 

- - Special Form: quote object
-     This special form returns OBJECT, without evaluating it.
+ - Function: pq-reset-cancel conn
+     Attempt to request cancellation of the current operation.  CONN A
+     database connection object.

 
 

-   Because `quote' is used so often in programs, Lisp provides a
-convenient read syntax for it.  An apostrophe character (`'') followed
-by a Lisp object (in read syntax) expands to a list whose first element
-is `quote', and whose second element is the object.  Thus, the read
-syntax `'x' is an abbreviation for `(quote x)'.
+     The return value is t if the cancel request was successfully
+     dispatched, nil if not (in which case conn->errorMessage is set).
+     Note: successful dispatch is no guarantee that there will be any
+     effect at the backend.  The application must read the operation
+     result as usual.

 
 

-   Here are some examples of expressions that use `quote':
+ - Function: pq-send-query conn query
+     Submit a query to Postgres and don't wait for the result.  CONN A
+     database connection object.  Returns: t if successfully submitted
+            nil if error (conn->errorMessage is set)

 
 

-     (quote (+ 1 2))
-          => (+ 1 2)
-     (quote foo)
-          => foo
-     'foo
-          => foo
-     ''foo
-          => (quote foo)
-     '(quote foo)
-          => (quote foo)
-     ['foo]
-          => [(quote foo)]
+ - Function: pq-get-result conn
+     Retrieve an asynchronous result from a query.  CONN A database
+     connection object.

 
 

-   Other quoting constructs include `function' (*note Anonymous
-Functions::), which causes an anonymous lambda expression written in
-Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
-only part of a list, while computing and substituting other parts.
+     `nil' is returned when no more query work remains.
+
+ - Function: pq-set-nonblocking conn arg
+     Sets the PGconn's database connection non-blocking if the arg is
+     TRUE or makes it non-blocking if the arg is FALSE, this will not
+     protect you from PQexec(), you'll only be safe when using the
+     non-blocking API.  CONN A database connection object.
+
+ - Function: pq-is-nonblocking conn
+     Return the blocking status of the database connection CONN A
+     database connection object.
+
+ - Function: pq-flush conn
+     Force the write buffer to be written (or at least try) CONN A
+     database connection object.
+
+ - Function: PQsetenvStart conn
+     Start asynchronously passing environment variables to a backend.
+     CONN A database connection object.
+
+     Compatibility note: this function is only available with libpq-7.0.
+
+ - Function: PQsetenvPoll conn
+     Check an asynchronous environment variables transfer for
+     completion.  CONN A database connection object.
+
+     Compatibility note: this function is only available with libpq-7.0.
+
+ - Function: PQsetenvAbort conn
+     Attempt to terminate an asynchronous environment variables
+     transfer.  CONN A database connection object.
+
+     Compatibility note: this function is only available with libpq-7.0.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Control Structures,  Next: Variables,  Prev: Evaluation,  Up: Top
+File: lispref.info,  Node: Large Object Support,  Next: Other libpq Functions,  Prev: Asynchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API

 
 

-Control Structures
-******************
+Large Object Support
+--------------------

 
 

-   A Lisp program consists of expressions or "forms" (*note Forms::).
-We control the order of execution of the forms by enclosing them in
-"control structures".  Control structures are special forms which
-control when, whether, or how many times to execute the forms they
-contain.
-
-   The simplest order of execution is sequential execution: first form
-A, then form B, and so on.  This is what happens when you write several
-forms in succession in the body of a function, or at top level in a
-file of Lisp code--the forms are executed in the order written.  We
-call this "textual order".  For example, if a function body consists of
-two forms A and B, evaluation of the function evaluates first A and
-then B, and the function's value is the value of B.
-
-   Explicit control structures make possible an order of execution other
-than sequential.
-
-   XEmacs Lisp provides several kinds of control structure, including
-other varieties of sequencing, conditionals, iteration, and (controlled)
-jumps--all discussed below.  The built-in control structures are
-special forms since their subforms are not necessarily evaluated or not
-evaluated sequentially.  You can use macros to define your own control
-structure constructs (*note Macros::).
+ - Function: pq-lo-import conn filename
+     Import a file as a large object into the database.  CONN a
+     database connection object FILENAME filename to import

 
 

-* Menu:
+     On success, the object id is returned.

 
 

-* Sequencing::             Evaluation in textual order.
-* Conditionals::           `if', `cond'.
-* Combining Conditions::   `and', `or', `not'.
-* Iteration::              `while' loops.
-* Nonlocal Exits::         Jumping out of a sequence.
+ - Function: pq-lo-export conn oid filename
+     Copy a large object in the database into a file.  CONN a database
+     connection object.  OID object id number of a large object.
+     FILENAME filename to export to.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Sequencing,  Next: Conditionals,  Up: Control Structures
+File: lispref.info,  Node: Other libpq Functions,  Next: Unimplemented libpq Functions,  Prev: Large Object Support,  Up: XEmacs PostgreSQL libpq API
+
+Other libpq Functions
+---------------------
+
+ - Function: pq-finish conn
+     Destroy a database connection object by calling free on it.  CONN
+     a database connection object
+
+     It is possible to not call this routine because the usual XEmacs
+     garbage collection mechanism will call the underlying libpq
+     routine whenever it is releasing stale `PGconn' objects.  However,
+     this routine is useful in `unwind-protect' clauses to make
+     connections go away quickly when unrecoverable errors have
+     occurred.
+
+     After calling this routine, the printed representation of the
+     XEmacs wrapper object will contain the string "DEAD".

 
 

-Sequencing
-==========
+ - Function: pq-client-encoding conn
+     Return the client encoding as an integer code.  CONN a database
+     connection object

 
 

-   Evaluating forms in the order they appear is the most common way
-control passes from one form to another.  In some contexts, such as in a
-function body, this happens automatically.  Elsewhere you must use a
-control structure construct to do this: `progn', the simplest control
-construct of Lisp.
+          (pq-client-encoding P)
+               => 1

 
 

-   A `progn' special form looks like this:
+     Compatibility note: This function did not exist prior to libpq-7.0
+     and does not exist in a non-Mule XEmacs.

 
 

-     (progn A B C ...)
+ - Function: pq-set-client-encoding conn encoding
+     Set client coding system.  CONN a database connection object
+     ENCODING a string representing the desired coding system

 
 

-and it says to execute the forms A, B, C and so on, in that order.
-These forms are called the body of the `progn' form.  The value of the
-last form in the body becomes the value of the entire `progn'.
+          (pq-set-client-encoding P "EUC_JP")
+               => 0
+
+     The current idiom for ensuring proper coding system conversion is
+     the following (illustrated for EUC Japanese encoding):
+          (setq P (pq-connectdb "..."))
+          (let ((file-name-coding-system 'euc-jp)
+                (pg-coding-system 'euc-jp))
+            (pq-set-client-encoding "EUC_JP")
+            ...)
+          (pq-finish P)
+     Compatibility note: This function did not exist prior to libpq-7.0
+     and does not exist in a non-Mule XEmacs.
+
+ - Function: pq-env-2-encoding
+     Return the integer code representing the coding system in
+     `PGCLIENTENCODING'.
+
+          (pq-env-2-encoding)
+               => 0
+     Compatibility note: This function did not exist prior to libpq-7.0
+     and does not exist in a non-Mule XEmacs.
+
+ - Function: pq-clear res
+     Destroy a query result object by calling free() on it.  RES a
+     query result object
+
+     Note:  The memory allocation systems of libpq and XEmacs are
+     different.  The XEmacs representation of a query result object
+     will have both the XEmacs version and the libpq version freed at
+     the next garbage collection when the object is no longer being
+     referenced.  Calling this function does not release the XEmacs
+     object, it is still subject to the usual rules for Lisp objects.
+     The printed representation of the XEmacs object will contain the
+     string "DEAD" after this routine is called indicating that it is no
+     longer useful for anything.
+
+ - Function: pq-conn-defaults
+     Return a data structure that represents the connection defaults.
+     The data is returned as a list of lists, where each sublist
+     contains info regarding a single option.
+
+\1f
+File: lispref.info,  Node: Unimplemented libpq Functions,  Prev: Other libpq Functions,  Up: XEmacs PostgreSQL libpq API
+
+Unimplemented libpq Functions
+-----------------------------
+
+ - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char
+          *pgport, char *pgoptions, char *pgtty, char *dbName, char
+          *login, char *pwd)
+     Synchronous database connection.  PGHOST is the hostname of the
+     PostgreSQL backend to connect to.  PGPORT is the TCP port number
+     to use.  PGOPTIONS specifies other backend options.  PGTTY
+     specifies the debugging tty to use.  DBNAME specifies the database
+     name to use.  LOGIN specifies the database user name.  PWD
+     specifies the database user's password.
+
+     This routine is deprecated as of libpq-7.0, and its functionality
+     can be replaced by external Lisp code if needed.
+
+ - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport,
+          char *pgoptions, char *pgtty, char *dbName)
+     Synchronous database connection.  PGHOST is the hostname of the
+     PostgreSQL backend to connect to.  PGPORT is the TCP port number
+     to use.  PGOPTIONS specifies other backend options.  PGTTY
+     specifies the debugging tty to use.  DBNAME specifies the database
+     name to use.
+
+     This routine was deprecated in libpq-6.5.
+
+ - Unimplemented Function: int PQsocket (PGconn *conn)
+     Return socket file descriptor to a backend database process.  CONN
+     database connection object.
+
+ - Unimplemented Function: void PQprint (FILE *fout, PGresult *res,
+          PGprintOpt *ps)
+     Print out the results of a query to a designated C stream.  FOUT C
+     stream to print to RES the query result object to print PS the
+     print options structure.
+
+     This routine is deprecated as of libpq-7.0 and cannot be sensibly
+     exported to XEmacs Lisp.
+
+ - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE
+          *fp, int fillAlign, char *fieldSep, int printHeader, int
+          quiet)
+     RES query result object to print FP C stream to print to FILLALIGN
+     pad the fields with spaces FIELDSEP field separator PRINTHEADER
+     display headers?  QUIET
+
+     This routine was deprecated in libpq-6.5.
+
+ - Unimplemented Function: void PQprintTuples (PGresult *res, FILE
+          *fout, int printAttName, int terseOutput, int width)
+     RES query result object to print FOUT C stream to print to
+     PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars
+     WIDTH width of column, if 0, use variable width
+
+     This routine was deprecated in libpq-6.5.
+
+ - Unimplemented Function: int PQmblen (char *s, int encoding)
+     Determine length of a multibyte encoded char at `*s'.  S encoded
+     string ENCODING type of encoding
+
+     Compatibility note:  This function was introduced in libpq-7.0.
+
+ - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port)
+     Enable tracing on `debug_port'.  CONN database connection object.
+     DEBUG_PORT C output stream to use.
+
+ - Unimplemented Function: void PQuntrace (PGconn *conn)
+     Disable tracing.  CONN database connection object.
+
+ - Unimplemented Function: char *PQoidStatus (PGconn *conn)
+     Return the object id as a string of the last tuple inserted.  CONN
+     database connection object.
+
+     Compatibility note: This function is deprecated in libpq-7.0,
+     however it is used internally by the XEmacs binding code when
+     linked against versions prior to 7.0.
+
+ - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int
+          *result_buf, int *result_len, int result_is_int, PQArgBlock
+          *args, int nargs)
+     "Fast path" interface -- not really recommended for application use
+     CONN A database connection object.  FNID RESULT_BUF RESULT_LEN
+     RESULT_IS_INT ARGS NARGS
+
+   The following set of very low level large object functions aren't
+appropriate to be exported to Lisp.
+
+ - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid,
+          int mode)
+     CONN a database connection object.  LOBJID a large object ID.
+     MODE opening modes.
+
+ - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd)
+     CONN a database connection object.  FD a large object file
+     descriptor
+
+ - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char
+          *buf, int len)
+     CONN a database connection object.  FD a large object file
+     descriptor.  BUF buffer to read into.  LEN size of buffer.
+
+ - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char
+          *buf, size_t len)
+     CONN a database connection object.  FD a large object file
+     descriptor.  BUF buffer to write from.  LEN size of buffer.
+
+ - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int
+          offset, int whence)
+     CONN a database connection object.  FD a large object file
+     descriptor.  OFFSET WHENCE

 
 

-   In the early days of Lisp, `progn' was the only way to execute two
-or more forms in succession and use the value of the last of them.  But
-programmers found they often needed to use a `progn' in the body of a
-function, where (at that time) only one form was allowed.  So the body
-of a function was made into an "implicit `progn'": several forms are
-allowed just as in the body of an actual `progn'.  Many other control
-structures likewise contain an implicit `progn'.  As a result, `progn'
-is not used as often as it used to be.  It is needed now most often
-inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
+ - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode)
+     CONN a database connection object.  MODE opening modes.
+
+ - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd)
+     CONN a database connection object.  FD a large object file
+     descriptor.
+
+ - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid)
+     CONN a database connection object.  LBOJID a large object ID.

 
 

- - Special Form: progn forms...
-     This special form evaluates all of the FORMS, in textual order,
-     returning the result of the final form.
+\1f
+File: lispref.info,  Node: XEmacs PostgreSQL libpq Examples,  Prev: XEmacs PostgreSQL libpq API,  Up: PostgreSQL Support
+
+XEmacs PostgreSQL libpq Examples
+================================
+
+This is an example of one method of establishing an asynchronous
+connection.
+
+     (defun database-poller (P)
+       (message "%S before poll" (pq-pgconn P 'pq::status))
+       (pq-connect-poll P)
+       (message "%S after poll" (pq-pgconn P 'pq::status))
+       (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
+           (message "Done!")
+         (add-timeout .1 'database-poller P)))
+          => database-poller
+     (progn
+       (setq P (pq-connect-start ""))
+       (add-timeout .1 'database-poller P))
+          => pg::connection-started before poll
+          => pg::connection-made after poll
+          => pg::connection-made before poll
+          => pg::connection-awaiting-response after poll
+          => pg::connection-awaiting-response before poll
+          => pg::connection-auth-ok after poll
+          => pg::connection-auth-ok before poll
+          => pg::connection-setenv after poll
+          => pg::connection-setenv before poll
+          => pg::connection-ok after poll
+          => Done!
+     P
+          => #<PGconn localhost:25432 steve/steve>
+
+   Here is an example of one method of doing an asynchronous reset.
+
+     (defun database-poller (P)
+       (let (PS)
+         (message "%S before poll" (pq-pgconn P 'pq::status))
+         (setq PS (pq-reset-poll P))
+         (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS)
+         (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
+       (message "Done!")
+           (add-timeout .1 'database-poller P))))
+          => database-poller
+     (progn
+       (pq-reset-start P)
+       (add-timeout .1 'database-poller P))
+          => pg::connection-started before poll
+          => pg::connection-made after poll [pgres::polling-writing]
+          => pg::connection-made before poll
+          => pg::connection-awaiting-response after poll [pgres::polling-reading]
+          => pg::connection-awaiting-response before poll
+          => pg::connection-setenv after poll [pgres::polling-reading]
+          => pg::connection-setenv before poll
+          => pg::connection-ok after poll [pgres::polling-ok]
+          => Done!
+     P
+          => #<PGconn localhost:25432 steve/steve>
+
+   And finally, an asynchronous query.
+
+     (defun database-poller (P)
+       (let (R)
+         (pq-consume-input P)
+         (if (pq-is-busy P)
+       (add-timeout .1 'database-poller P)
+           (setq R (pq-get-result P))
+           (if R
+         (progn
+           (push R result-list)
+           (add-timeout .1 'database-poller P))))))
+          => database-poller
+     (when (pq-send-query P "SELECT * FROM xemacs_test;")
+       (setq result-list nil)
+       (add-timeout .1 'database-poller P))
+          => 885
+     ;; wait a moment
+     result-list
+          => (#<PGresult PGRES_TUPLES_OK - SELECT>)
+
+   Here is an example showing how multiple SQL statements in a single
+query can have all their results collected.
+     ;; Using the same `database-poller' function from the previous example
+     (when (pq-send-query P "SELECT * FROM xemacs_test;
+     SELECT * FROM pg_database;
+     SELECT * FROM pg_user;")
+       (setq result-list nil)
+       (add-timeout .1 'database-poller P))
+          => 1782
+     ;; wait a moment
+     result-list
+          => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
+
+   Here is an example which illustrates collecting all data from a
+query, including the field names.
+
+     (defun pg-util-query-results (results)
+       "Retrieve results of last SQL query into a list structure."
+       (let ((i (1- (pq-ntuples R)))
+       j l1 l2)
+         (while (>= i 0)
+           (setq j (1- (pq-nfields R)))
+           (setq l2 nil)
+           (while (>= j 0)
+       (push (pq-get-value R i j) l2)
+       (decf j))
+           (push l2 l1)
+           (decf i))
+         (setq j (1- (pq-nfields R)))
+         (setq l2 nil)
+         (while (>= j 0)
+           (push (pq-fname R j) l2)
+           (decf j))
+         (push l2 l1)
+         l1))
+          => pg-util-query-results
+     (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;"))
+          => #<PGresult PGRES_TUPLES_OK - SELECT>
+     (pg-util-query-results R)
+          => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1"))
+
+   Here is an example of a query that uses a database cursor.
+
+     (let (data R)
+       (setq R (pq-exec P "BEGIN;"))
+       (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;"))
+     
+       (setq R (pq-exec P "FETCH k_cursor;"))
+       (while (eq (pq-ntuples R) 1)
+         (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data)
+         (setq R (pq-exec P "FETCH k_cursor;")))
+       (setq R (pq-exec P "END;"))
+       data)
+          => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
+
+   Here's another example of cursors, this time with a Lisp macro to
+implement a mapping function over a table.
+
+     (defmacro map-db (P table condition callout)
+       `(let (R)
+          (pq-exec ,P "BEGIN;")
+          (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
+                        ,table
+                        " "
+                        ,condition
+                        " ORDER BY f1 DESC;"))
+          (setq R (pq-exec P "FETCH k_cursor;"))
+          (while (eq (pq-ntuples R) 1)
+            (,callout (pq-get-value R 0 0) (pq-get-value R 0 1))
+            (setq R (pq-exec P "FETCH k_cursor;")))
+          (pq-exec P "END;")))
+          => map-db
+     (defun callback (arg1 arg2)
+       (message "arg1 = %s, arg2 = %s" arg1 arg2))
+          => callback
+     (map-db P "xemacs_test" "WHERE field2 > 10" callback)
+          => arg1 = stuff, arg2 = 42
+          => arg1 = b, arg2 = 97
+          => arg1 = a string, arg2 = 12
+          => arg1 = a, arg2 = 97
+          => #<PGresult PGRES_COMMAND_OK - COMMIT>

 
 

-          (progn (print "The first form")
-                 (print "The second form")
-                 (print "The third form"))
-               -| "The first form"
-               -| "The second form"
-               -| "The third form"
-          => "The third form"
+\1f
+File: lispref.info,  Node: Internationalization,  Next: MULE,  Prev: PostgreSQL Support,  Up: Top

 
 

-   Two other control constructs likewise evaluate a series of forms but
-return a different value:
+Internationalization
+********************

 
 

- - Special Form: prog1 form1 forms...
-     This special form evaluates FORM1 and all of the FORMS, in textual
-     order, returning the result of FORM1.
+* Menu:

 
 

-          (prog1 (print "The first form")
-                 (print "The second form")
-                 (print "The third form"))
-               -| "The first form"
-               -| "The second form"
-               -| "The third form"
-          => "The first form"
+* 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.

 
 

-     Here is a way to remove the first element from a list in the
-     variable `x', then return the value of that former element:
+\1f
+File: lispref.info,  Node: I18N Levels 1 and 2,  Next: I18N Level 3,  Up: Internationalization

 
 

-          (prog1 (car x) (setq x (cdr x)))
+I18N Levels 1 and 2
+===================

 
 

- - Special Form: prog2 form1 form2 forms...
-     This special form evaluates FORM1, FORM2, and all of the following
-     FORMS, in textual order, returning the result of FORM2.
+XEmacs is now compliant with I18N levels 1 and 2.  Specifically, this
+means that it is 8-bit clean and correctly handles time and date
+functions.  XEmacs will correctly display the entire ISO-Latin 1
+character set.

 
 

-          (prog2 (print "The first form")
-                 (print "The second form")
-                 (print "The third form"))
-               -| "The first form"
-               -| "The second form"
-               -| "The third form"
-          => "The second form"
+   The compose key may now be used to create any character in the
+ISO-Latin 1 character set not directly available via the keyboard..  In
+order for the compose key to work it is necessary to load the file
+`x-compose.el'.  At any time while composing a character, `C-h' will
+display all valid completions and the character which would be produced.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Conditionals,  Next: Combining Conditions,  Prev: Sequencing,  Up: Control Structures
+File: lispref.info,  Node: I18N Level 3,  Next: I18N Level 4,  Prev: I18N Levels 1 and 2,  Up: Internationalization

 
 

-Conditionals
+I18N Level 3

 ============
 
 ============
 

-   Conditional control structures choose among alternatives.  XEmacs
-Lisp has two conditional forms: `if', which is much the same as in other
-languages, and `cond', which is a generalized case statement.
+* Menu:
+
+* Level 3 Basics::
+* Level 3 Primitives::
+* Dynamic Messaging::
+* Domain Specification::
+* Documentation String Extraction::
+
+\1f
+File: lispref.info,  Node: Level 3 Basics,  Next: Level 3 Primitives,  Up: I18N Level 3
+
+Level 3 Basics
+--------------
+
+XEmacs now provides alpha-level functionality for I18N Level 3.  This
+means that everything necessary for full messaging is available, but
+not every file has been converted.
+
+   The two message files which have been created are `src/emacs.po' and
+`lisp/packages/mh-e.po'.  Both files need to be converted using
+`msgfmt', and the resulting `.mo' files placed in some locale's
+`LC_MESSAGES' directory.  The test "translations" in these files are
+the original messages prefixed by `TRNSLT_'.
+
+   The domain for a variable is stored on the variable's property list
+under the property name VARIABLE-DOMAIN.  The function
+`documentation-property' uses this information when translating a
+variable's documentation.
+
+\1f
+File: lispref.info,  Node: Level 3 Primitives,  Next: Dynamic Messaging,  Prev: Level 3 Basics,  Up: I18N Level 3
+
+Level 3 Primitives
+------------------
+
+ - Function: gettext string
+     This function looks up STRING in the default message domain and
+     returns its translation.  If `I18N3' was not enabled when XEmacs
+     was compiled, it just returns STRING.
+
+ - Function: dgettext domain string
+     This function looks up STRING in the specified message domain and
+     returns its translation.  If `I18N3' was not enabled when XEmacs
+     was compiled, it just returns STRING.
+
+ - Function: bind-text-domain domain pathname
+     This function associates a pathname with a message domain.  Here's
+     how the path to message file is constructed under SunOS 5.x:
+
+          `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
+
+     If `I18N3' was not enabled when XEmacs was compiled, this function
+     does nothing.
+
+ - Special Form: domain string
+     This function specifies the text domain used for translating
+     documentation strings and interactive prompts of a function.  For
+     example, write:
+
+          (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
+
+     to specify `emacs-foo' as the text domain of the function `foo'.
+     The "call" to `domain' is actually a declaration rather than a
+     function; when actually called, `domain' just returns `nil'.

 
 

- - Special Form: if condition then-form else-forms...
-     `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
-     value of CONDITION.  If the evaluated CONDITION is non-`nil',
-     THEN-FORM is evaluated and the result returned.  Otherwise, the
-     ELSE-FORMS are evaluated in textual order, and the value of the
-     last one is returned.  (The ELSE part of `if' is an example of an
-     implicit `progn'.  *Note Sequencing::.)
+ - Function: domain-of function
+     This function returns the text domain of FUNCTION; it returns
+     `nil' if it is the default domain.  If `I18N3' was not enabled
+     when XEmacs was compiled, it always returns `nil'.

 
 

-     If CONDITION has the value `nil', and no ELSE-FORMS are given,
-     `if' returns `nil'.
+\1f
+File: lispref.info,  Node: Dynamic Messaging,  Next: Domain Specification,  Prev: Level 3 Primitives,  Up: I18N Level 3

 
 

-     `if' is a special form because the branch that is not selected is
-     never evaluated--it is ignored.  Thus, in the example below,
-     `true' is not printed because `print' is never called.
+Dynamic Messaging
+-----------------

 
 

-          (if nil
-              (print 'true)
-            'very-false)
-          => very-false
+The `format' function has been extended to permit you to change the
+order of parameter insertion.  For example, the conversion format
+`%1$s' inserts parameter one as a string, while `%2$s' inserts
+parameter two.  This is useful when creating translations which require
+you to change the word order.

 
 

- - Special Form: cond clause...
-     `cond' chooses among an arbitrary number of alternatives.  Each
-     CLAUSE in the `cond' must be a list.  The CAR of this list is the
-     CONDITION; the remaining elements, if any, the BODY-FORMS.  Thus,
-     a clause looks like this:
+\1f
+File: lispref.info,  Node: Domain Specification,  Next: Documentation String Extraction,  Prev: Dynamic Messaging,  Up: I18N Level 3

 
 

-          (CONDITION BODY-FORMS...)
+Domain Specification
+--------------------

 
 

-     `cond' tries the clauses in textual order, by evaluating the
-     CONDITION of each clause.  If the value of CONDITION is non-`nil',
-     the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
-     the value of the last of BODY-FORMS becomes the value of the
-     `cond'.  The remaining clauses are ignored.
+The default message domain of XEmacs is `emacs'.  For add-on packages,
+it is best to use a different domain.  For example, let us say we want
+to convert the "gorilla" package to use the domain `emacs-gorilla'.  To
+translate the message "What gorilla?", use `dgettext' as follows:

 
 

-     If the value of CONDITION is `nil', the clause "fails", so the
-     `cond' moves on to the following clause, trying its CONDITION.
+     (dgettext "emacs-gorilla" "What gorilla?")

 
 

-     If every CONDITION evaluates to `nil', so that every clause fails,
-     `cond' returns `nil'.
+   A function (or macro) which has a documentation string or an
+interactive prompt needs to be associated with the domain in order for
+the documentation or prompt to be translated.  This is done with the
+`domain' special form as follows:

 
 

-     A clause may also look like this:
+     (defun scratch (location)
+       "Scratch the specified location."
+       (domain "emacs-gorilla")
+       (interactive "sScratch: ")
+       ... )

 
 

-          (CONDITION)
+   It is most efficient to specify the domain in the first line of the
+function body, before the `interactive' form.

 
 

-     Then, if CONDITION is non-`nil' when tested, the value of
-     CONDITION becomes the value of the `cond' form.
+   For variables and constants which have documentation strings,
+specify the domain after the documentation.

 
 

-     The following example has four clauses, which test for the cases
-     where the value of `x' is a number, string, buffer and symbol,
-     respectively:
+ - Special Form: defvar symbol [value [doc-string [domain]]]
+     Example:
+          (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")

 
 

-          (cond ((numberp x) x)
-                ((stringp x) x)
-                ((bufferp x)
-                 (setq temporary-hack x) ; multiple body-forms
-                 (buffer-name x))        ; in one clause
-                ((symbolp x) (symbol-value x)))
+ - Special Form: defconst symbol [value [doc-string [domain]]]
+     Example:
+          (defconst limbs 4 "Number of limbs" "emacs-gorilla")

 
 

-     Often we want to execute the last clause whenever none of the
-     previous clauses was successful.  To do this, we use `t' as the
-     CONDITION of the last clause, like this: `(t BODY-FORMS)'.  The
-     form `t' evaluates to `t', which is never `nil', so this clause
-     never fails, provided the `cond' gets to it at all.
+ - Function: autoload function filename &optional docstring interactive
+          type
+     This function defines FUNCTION to autoload from FILENAME Example:
+          (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")

 
 

-     For example,
+\1f
+File: lispref.info,  Node: Documentation String Extraction,  Prev: Domain Specification,  Up: I18N Level 3

 
 

-          (cond ((eq a 'hack) 'foo)
-                (t "default"))
-          => "default"
+Documentation String Extraction
+-------------------------------

 
 

-     This expression is a `cond' which returns `foo' if the value of
-     `a' is 1, and returns the string `"default"' otherwise.
+The utility `etc/make-po' scans the file `DOC' to extract documentation
+strings and creates a message file `doc.po'.  This file may then be
+inserted within `emacs.po'.

 
 

-   Any conditional construct can be expressed with `cond' or with `if'.
-Therefore, the choice between them is a matter of style.  For example:
+   Currently, `make-po' is hard-coded to read from `DOC' and write to
+`doc.po'.  In order to extract documentation strings from an add-on
+package, first run `make-docfile' on the package to produce the `DOC'
+file.  Then run `make-po -p' with the `-p' argument to indicate that we
+are extracting documentation for an add-on package.

 
 

-     (if A B C)
-     ==
-     (cond (A B) (t C))
+   (The `-p' argument is a kludge to make up for a subtle difference
+between pre-loaded documentation and add-on documentation:  For add-on
+packages, the final carriage returns in the strings produced by
+`make-docfile' must be ignored.)

 
 \1f
 
 \1f

-File: lispref.info,  Node: Combining Conditions,  Next: Iteration,  Prev: Conditionals,  Up: Control Structures
+File: lispref.info,  Node: I18N Level 4,  Prev: I18N Level 3,  Up: Internationalization

 
 

-Constructs for Combining Conditions
-===================================
+I18N Level 4
+============

 
 

-   This section describes three constructs that are often used together
-with `if' and `cond' to express complicated conditions.  The constructs
-`and' and `or' can also be used individually as kinds of multiple
-conditional constructs.
+The Asian-language support in XEmacs is called "MULE".  *Note MULE::.

 
 

- - Function: not condition
-     This function tests for the falsehood of CONDITION.  It returns
-     `t' if CONDITION is `nil', and `nil' otherwise.  The function
-     `not' is identical to `null', and we recommend using the name
-     `null' if you are testing for an empty list.
+\1f
+File: lispref.info,  Node: MULE,  Next: Tips,  Prev: Internationalization,  Up: Top

 
 

- - Special Form: and conditions...
-     The `and' special form tests whether all the CONDITIONS are true.
-     It works by evaluating the CONDITIONS one by one in the order
-     written.
+MULE
+****

 
 

-     If any of the CONDITIONS evaluates to `nil', then the result of
-     the `and' must be `nil' regardless of the remaining CONDITIONS; so
-     `and' returns right away, ignoring the remaining CONDITIONS.
+"MULE" is the name originally given to the version of GNU Emacs
+extended for multi-lingual (and in particular Asian-language) support.
+"MULE" is short for "MUlti-Lingual Emacs".  It is an extension and
+complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese
+word for "Japan"), which only provided support for Japanese.  XEmacs
+refers to its multi-lingual support as "MULE support" since it is based
+on "MULE".

 
 

-     If all the CONDITIONS turn out non-`nil', then the value of the
-     last of them becomes the value of the `and' form.
+* Menu:

 
 

-     Here is an example.  The first condition returns the integer 1,
-     which is not `nil'.  Similarly, the second condition returns the
-     integer 2, which is not `nil'.  The third condition is `nil', so
-     the remaining condition is never evaluated.
+* 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.
+* 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.

 
 

-          (and (print 1) (print 2) nil (print 3))
-               -| 1
-               -| 2
-          => nil
+\1f
+File: lispref.info,  Node: Internationalization Terminology,  Next: Charsets,  Up: MULE
+
+Internationalization Terminology
+================================
+
+In internationalization terminology, a string of text is divided up
+into "characters", which are the printable units that make up the text.
+A single character is (for example) a capital `A', the number `2', a
+Katakana character, a Hangul character, a Kanji ideograph (an
+"ideograph" is a "picture" character, such as is used in Japanese
+Kanji, Chinese Hanzi, and Korean Hanja; typically there are thousands
+of such ideographs in each language), etc.  The basic property of a
+character is that it is the smallest unit of text with semantic
+significance in text processing.
+
+   Human beings normally process text visually, so to a first
+approximation a character may be identified with its shape.  Note that
+the same character may be drawn by two different people (or in two
+different fonts) in slightly different ways, although the "basic shape"
+will be the same.  But consider the works of Scott Kim; human beings
+can recognize hugely variant shapes as the "same" character.
+Sometimes, especially where characters are extremely complicated to
+write, completely different shapes may be defined as the "same"
+character in national standards.  The Taiwanese variant of Hanzi is
+generally the most complicated; over the centuries, the Japanese,
+Koreans, and the People's Republic of China have adopted
+simplifications of the shape, but the line of descent from the original
+shape is recorded, and the meanings and pronunciation of different
+forms of the same character are considered to be identical within each
+language.  (Of course, it may take a specialist to recognize the
+related form; the point is that the relations are standardized, despite
+the differing shapes.)
+
+   In some cases, the differences will be significant enough that it is
+actually possible to identify two or more distinct shapes that both
+represent the same character.  For example, the lowercase letters `a'
+and `g' each have two distinct possible shapes--the `a' can optionally
+have a curved tail projecting off the top, and the `g' can be formed
+either of two loops, or of one loop and a tail hanging off the bottom.
+Such distinct possible shapes of a character are called "glyphs".  The
+important characteristic of two glyphs making up the same character is
+that the choice between one or the other is purely stylistic and has no
+linguistic effect on a word (this is the reason why a capital `A' and
+lowercase `a' are different characters rather than different
+glyphs--e.g.  `Aspen' is a city while `aspen' is a kind of tree).
+
+   Note that "character" and "glyph" are used differently here than
+elsewhere in XEmacs.
+
+   A "character set" is essentially a set of related characters.  ASCII,
+for example, is a set of 94 characters (or 128, if you count
+non-printing characters).  Other character sets are ISO8859-1 (ASCII
+plus various accented characters and other international symbols), JIS
+X 0201 (ASCII, more or less, plus half-width Katakana), JIS X 0208
+(Japanese Kanji), JIS X 0212 (a second set of less-used Japanese Kanji),
+GB2312 (Mainland Chinese Hanzi), etc.
+
+   The definition of a character set will implicitly or explicitly give
+it an "ordering", a way of assigning a number to each character in the
+set.  For many character sets, there is a natural ordering, for example
+the "ABC" ordering of the Roman letters.  But it is not clear whether
+digits should come before or after the letters, and in fact different
+European languages treat the ordering of accented characters
+differently.  It is useful to use the natural order where available, of
+course.  The number assigned to any particular character is called the
+character's "code point".  (Within a given character set, each
+character has a unique code point.  Thus the word "set" is ill-chosen;
+different orderings of the same characters are different character sets.
+Identifying characters is simple enough for alphabetic character sets,
+but the difference in ordering can cause great headaches when the same
+thousands of characters are used by different cultures as in the Hanzi.)
+
+   A code point may be broken into a number of "position codes".  The
+number of position codes required to index a particular character in a
+character set is called the "dimension" of the character set.  For
+practical purposes, a position code may be thought of as a byte-sized
+index.  The printing characters of ASCII, being a relatively small
+character set, is of dimension one, and each character in the set is
+indexed using a single position code, in the range 1 through 94.  Use of
+this unusual range, rather than the familiar 33 through 126, is an
+intentional abstraction; to understand the programming issues you must
+break the equation between character sets and encodings.
+
+   JIS X 0208, i.e. Japanese Kanji, has thousands of characters, and is
+of dimension two - every character is indexed by two position codes,
+each in the range 1 through 94.  (This number "94" is not a
+coincidence; we shall see that the JIS position codes were chosen so
+that JIS kanji could be encoded without using codes that in ASCII are
+associated with device control functions.)  Note that the choice of the
+range here is somewhat arbitrary.  You could just as easily index the
+printing characters in ASCII using numbers in the range 0 through 93, 2
+through 95, 3 through 96, etc.  In fact, the standardized _encoding_
+for the ASCII _character set_ uses the range 33 through 126.
+
+   An "encoding" is a way of numerically representing characters from
+one or more character sets into a stream of like-sized numerical values
+called "words"; typically these are 8-bit, 16-bit, or 32-bit
+quantities.  If an encoding encompasses only one character set, then the
+position codes for the characters in that character set could be used
+directly.  (This is the case with the trivial cipher used by children,
+assigning 1 to `A', 2 to `B', and so on.)  However, even with ASCII,
+other considerations intrude.  For example, why are the upper- and
+lowercase alphabets separated by 8 characters?  Why do the digits start
+with `0' being assigned the code 48?  In both cases because semantically
+interesting operations (case conversion and numerical value extraction)
+become convenient masking operations.  Other artificial aspects (the
+control characters being assigned to codes 0-31 and 127) are historical
+accidents.  (The use of 127 for `DEL' is an artifact of the "punch
+once" nature of paper tape, for example.)
+
+   Naive use of the position code is not possible, however, if more than
+one character set is to be used in the encoding.  For example, printed
+Japanese text typically requires characters from multiple character sets
+- ASCII, JIS X 0208, and JIS X 0212, to be specific.  Each of these is
+indexed using one or more position codes in the range 1 through 94, so
+the position codes could not be used directly or there would be no way
+to tell which character was meant.  Different Japanese encodings handle
+this differently - JIS uses special escape characters to denote
+different character sets; EUC sets the high bit of the position codes
+for JIS X 0208 and JIS X 0212, and puts a special extra byte before each
+JIS X 0212 character; etc.  (JIS, EUC, and most of the other encodings
+you will encounter in files are 7-bit or 8-bit encodings.  There is one
+common 16-bit encoding, which is Unicode; this strives to represent all
+the world's characters in a single large character set.  32-bit
+encodings are often used internally in programs, such as XEmacs with
+MULE support, to simplify the code that manipulates them; however, they
+are not used externally because they are not very space-efficient.)
+
+   A general method of handling text using multiple character sets
+(whether for multilingual text, or simply text in an extremely
+complicated single language like Japanese) is defined in the
+international standard ISO 2022.  ISO 2022 will be discussed in more
+detail later (*note ISO 2022::), but for now suffice it to say that text
+needs control functions (at least spacing), and if escape sequences are
+to be used, an escape sequence introducer.  It was decided to make all
+text streams compatible with ASCII in the sense that the codes 0-31
+(and 128-159) would always be control codes, never graphic characters,
+and where defined by the character set the `SPC' character would be
+assigned code 32, and `DEL' would be assigned 127.  Thus there are 94
+code points remaining if 7 bits are used.  This is the reason that most
+character sets are defined using position codes in the range 1 through
+94.  Then ISO 2022 compatible encodings are produced by shifting the
+position codes 1 to 94 into character codes 33 to 126, or (if 8 bit
+codes are available) into character codes 161 to 254.
+
+   Encodings are classified as either "modal" or "non-modal".  In a
+"modal encoding", there are multiple states that the encoding can be
+in, and the interpretation of the values in the stream depends on the
+current global state of the encoding.  Special values in the encoding,
+called "escape sequences", are used to change the global state.  JIS,
+for example, is a modal encoding.  The bytes `ESC $ B' indicate that,
+from then on, bytes are to be interpreted as position codes for JIS X
+0208, rather than as ASCII.  This effect is cancelled using the bytes
+`ESC ( B', which mean "switch from whatever the current state is to
+ASCII".  To switch to JIS X 0212, the escape sequence `ESC $ ( D'.
+(Note that here, as is common, the escape sequences do in fact begin
+with `ESC'.  This is not necessarily the case, however.  Some encodings
+use control characters called "locking shifts" (effect persists until
+cancelled) to switch character sets.)
+
+   A "non-modal encoding" has no global state that extends past the
+character currently being interpreted.  EUC, for example, is a
+non-modal encoding.  Characters in JIS X 0208 are encoded by setting
+the high bit of the position codes, and characters in JIS X 0212 are
+encoded by doing the same but also prefixing the character with the
+byte 0x8F.
+
+   The advantage of a modal encoding is that it is generally more
+space-efficient, and is easily extendible because there are essentially
+an arbitrary number of escape sequences that can be created.  The
+disadvantage, however, is that it is much more difficult to work with
+if it is not being processed in a sequential manner.  In the non-modal
+EUC encoding, for example, the byte 0x41 always refers to the letter
+`A'; whereas in JIS, it could either be the letter `A', or one of the
+two position codes in a JIS X 0208 character, or one of the two
+position codes in a JIS X 0212 character.  Determining exactly which
+one is meant could be difficult and time-consuming if the previous
+bytes in the string have not already been processed, or impossible if
+they are drawn from an external stream that cannot be rewound.
+
+   Non-modal encodings are further divided into "fixed-width" and
+"variable-width" formats.  A fixed-width encoding always uses the same
+number of words per character, whereas a variable-width encoding does
+not.  EUC is a good example of a variable-width encoding: one to three
+bytes are used per character, depending on the character set.  16-bit
+and 32-bit encodings are nearly always fixed-width, and this is in fact
+one of the main reasons for using an encoding with a larger word size.
+The advantages of fixed-width encodings should be obvious.  The
+advantages of variable-width encodings are that they are generally more
+space-efficient and allow for compatibility with existing 8-bit
+encodings such as ASCII.  (For example, in Unicode ASCII characters are
+simply promoted to a 16-bit representation.  That means that every
+ASCII character contains a `NUL' byte; evidently all of the standard
+string manipulation functions will lose badly in a fixed-width Unicode
+environment.)
+
+   The bytes in an 8-bit encoding are often referred to as "octets"
+rather than simply as bytes.  This terminology dates back to the days
+before 8-bit bytes were universal, when some computers had 9-bit bytes,
+others had 10-bit bytes, etc.
+
+\1f
+File: lispref.info,  Node: Charsets,  Next: MULE Characters,  Prev: Internationalization Terminology,  Up: MULE
+
+Charsets
+========
+
+A "charset" in MULE is an object that encapsulates a particular
+character set as well as an ordering of those characters.  Charsets are
+permanent objects and are named using symbols, like faces.
+
+ - Function: charsetp object
+     This function returns non-`nil' if OBJECT is a charset.
+
+* Menu:

 
 

-     Here is a more realistic example of using `and':
+* Charset Properties::          Properties of a charset.
+* Basic Charset Functions::     Functions for working with charsets.
+* Charset Property Functions::  Functions for accessing charset properties.
+* Predefined Charsets::         Predefined charset objects.

 
 

-          (if (and (consp foo) (eq (car foo) 'x))
-              (message "foo is a list starting with x"))
+\1f
+File: lispref.info,  Node: Charset Properties,  Next: Basic Charset Functions,  Up: Charsets
+
+Charset Properties
+------------------
+
+Charsets have the following properties:
+
+`name'
+     A symbol naming the charset.  Every charset must have a different
+     name; this allows a charset to be referred to using its name
+     rather than the actual charset object.
+
+`doc-string'
+     A documentation string describing the charset.
+
+`registry'
+     A regular expression matching the font registry field for this
+     character set.  For example, both the `ascii' and `latin-iso8859-1'
+     charsets use the registry `"ISO8859-1"'.  This field is used to
+     choose an appropriate font when the user gives a general font
+     specification such as `-*-courier-medium-r-*-140-*', i.e. a
+     14-point upright medium-weight Courier font.
+
+`dimension'
+     Number of position codes used to index a character in the
+     character set.  XEmacs/MULE can only handle character sets of
+     dimension 1 or 2.  This property defaults to 1.
+
+`chars'
+     Number of characters in each dimension.  In XEmacs/MULE, the only
+     allowed values are 94 or 96. (There are a couple of pre-defined
+     character sets, such as ASCII, that do not follow this, but you
+     cannot define new ones like this.) Defaults to 94.  Note that if
+     the dimension is 2, the character set thus described is 94x94 or
+     96x96.
+
+`columns'
+     Number of columns used to display a character in this charset.
+     Only used in TTY mode. (Under X, the actual width of a character
+     can be derived from the font used to display the characters.)  If
+     unspecified, defaults to the dimension. (This is almost always the
+     correct value, because character sets with dimension 2 are usually
+     ideograph character sets, which need two columns to display the
+     intricate ideographs.)
+
+`direction'
+     A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left).
+     Defaults to `l2r'.  This specifies the direction that the text
+     should be displayed in, and will be left-to-right for most
+     charsets but right-to-left for Hebrew and Arabic. (Right-to-left
+     display is not currently implemented.)
+
+`final'
+     Final byte of the standard ISO 2022 escape sequence designating
+     this charset.  Must be supplied.  Each combination of (DIMENSION,
+     CHARS) defines a separate namespace for final bytes, and each
+     charset within a particular namespace must have a different final
+     byte.  Note that ISO 2022 restricts the final byte to the range
+     0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2.
+     Note also that final bytes in the range 0x30 - 0x3F are reserved
+     for user-defined (not official) character sets.  For more
+     information on ISO 2022, see *Note Coding Systems::.
+
+`graphic'
+     0 (use left half of font on output) or 1 (use right half of font on
+     output).  Defaults to 0.  This specifies how to convert the
+     position codes that index a character in a character set into an
+     index into the font used to display the character set.  With
+     `graphic' set to 0, position codes 33 through 126 map to font
+     indices 33 through 126; with it set to 1, position codes 33
+     through 126 map to font indices 161 through 254 (i.e. the same
+     number but with the high bit set).  For example, for a font whose
+     registry is ISO8859-1, the left half of the font (octets 0x20 -
+     0x7F) is the `ascii' charset, while the right half (octets 0xA0 -
+     0xFF) is the `latin-iso8859-1' charset.
+
+`ccl-program'
+     A compiled CCL program used to convert a character in this charset
+     into an index into the font.  This is in addition to the `graphic'
+     property.  If a CCL program is defined, the position codes of a
+     character will first be processed according to `graphic' and then
+     passed through the CCL program, with the resulting values used to
+     index the font.
+
+     This is used, for example, in the Big5 character set (used in
+     Taiwan).  This character set is not ISO-2022-compliant, and its
+     size (94x157) does not fit within the maximum 96x96 size of
+     ISO-2022-compliant character sets.  As a result, XEmacs/MULE
+     splits it (in a rather complex fashion, so as to group the most
+     commonly used characters together) into two charset objects
+     (`big5-1' and `big5-2'), each of size 94x94, and each charset
+     object uses a CCL program to convert the modified position codes
+     back into standard Big5 indices to retrieve a character from a
+     Big5 font.
+
+   Most of the above properties can only be set when the charset is
+initialized, and cannot be changed later.  *Note Charset Property
+Functions::.
+
+\1f
+File: lispref.info,  Node: Basic Charset Functions,  Next: Charset Property Functions,  Prev: Charset Properties,  Up: Charsets
+
+Basic Charset Functions
+-----------------------
+
+ - Function: find-charset charset-or-name
+     This function retrieves the charset of the given name.  If
+     CHARSET-OR-NAME is a charset object, it is simply returned.
+     Otherwise, CHARSET-OR-NAME should be a symbol.  If there is no
+     such charset, `nil' is returned.  Otherwise the associated charset
+     object is returned.
+
+ - Function: get-charset name
+     This function retrieves the charset of the given name.  Same as
+     `find-charset' except an error is signalled if there is no such
+     charset instead of returning `nil'.
+
+ - Function: charset-list
+     This function returns a list of the names of all defined charsets.
+
+ - Function: make-charset name doc-string props
+     This function defines a new character set.  This function is for
+     use with MULE support.  NAME is a symbol, the name by which the
+     character set is normally referred.  DOC-STRING is a string
+     describing the character set.  PROPS is a property list,
+     describing the specific nature of the character set.  The
+     recognized properties are `registry', `dimension', `columns',
+     `chars', `final', `graphic', `direction', and `ccl-program', as
+     previously described.
+
+ - Function: make-reverse-direction-charset charset new-name
+     This function makes a charset equivalent to CHARSET but which goes
+     in the opposite direction.  NEW-NAME is the name of the new
+     charset.  The new charset is returned.
+
+ - Function: charset-from-attributes dimension chars final &optional
+          direction
+     This function returns a charset with the given DIMENSION, CHARS,
+     FINAL, and DIRECTION.  If DIRECTION is omitted, both directions
+     will be checked (left-to-right will be returned if character sets
+     exist for both directions).
+
+ - Function: charset-reverse-direction-charset charset
+     This function returns the charset (if any) with the same dimension,
+     number of characters, and final byte as CHARSET, but which is
+     displayed in the opposite direction.
+
+\1f
+File: lispref.info,  Node: Charset Property Functions,  Next: Predefined Charsets,  Prev: Basic Charset Functions,  Up: Charsets
+
+Charset Property Functions
+--------------------------
+
+All of these functions accept either a charset name or charset object.
+
+ - Function: charset-property charset prop
+     This function returns property PROP of CHARSET.  *Note Charset
+     Properties::.

 
 

-     Note that `(car foo)' is not executed if `(consp foo)' returns
-     `nil', thus avoiding an error.
+   Convenience functions are also provided for retrieving individual
+properties of a charset.

 
 

-     `and' can be expressed in terms of either `if' or `cond'.  For
-     example:
+ - Function: charset-name charset
+     This function returns the name of CHARSET.  This will be a symbol.

 
 

-          (and ARG1 ARG2 ARG3)
-          ==
-          (if ARG1 (if ARG2 ARG3))
-          ==
-          (cond (ARG1 (cond (ARG2 ARG3))))
+ - Function: charset-description charset
+     This function returns the documentation string of CHARSET.

 
 

- - Special Form: or conditions...
-     The `or' special form tests whether at least one of the CONDITIONS
-     is true.  It works by evaluating all the CONDITIONS one by one in
-     the order written.
+ - Function: charset-registry charset
+     This function returns the registry of CHARSET.

 
 

-     If any of the CONDITIONS evaluates to a non-`nil' value, then the
-     result of the `or' must be non-`nil'; so `or' returns right away,
-     ignoring the remaining CONDITIONS.  The value it returns is the
-     non-`nil' value of the condition just evaluated.
+ - Function: charset-dimension charset
+     This function returns the dimension of CHARSET.

 
 

-     If all the CONDITIONS turn out `nil', then the `or' expression
-     returns `nil'.
+ - Function: charset-chars charset
+     This function returns the number of characters per dimension of
+     CHARSET.

 
 

-     For example, this expression tests whether `x' is either 0 or
-     `nil':
+ - Function: charset-width charset
+     This function returns the number of display columns per character
+     (in TTY mode) of CHARSET.

 
 

-          (or (eq x nil) (eq x 0))
+ - Function: charset-direction charset
+     This function returns the display direction of CHARSET--either
+     `l2r' or `r2l'.

 
 

-     Like the `and' construct, `or' can be written in terms of `cond'.
-     For example:
+ - Function: charset-iso-final-char charset
+     This function returns the final byte of the ISO 2022 escape
+     sequence designating CHARSET.

 
 

-          (or ARG1 ARG2 ARG3)
-          ==
-          (cond (ARG1)
-                (ARG2)
-                (ARG3))
+ - Function: charset-iso-graphic-plane charset
+     This function returns either 0 or 1, depending on whether the
+     position codes of characters in CHARSET map to the left or right
+     half of their font, respectively.

 
 

-     You could almost write `or' in terms of `if', but not quite:
+ - Function: charset-ccl-program charset
+     This function returns the CCL program, if any, for converting
+     position codes of characters in CHARSET into font indices.

 
 

-          (if ARG1 ARG1
-            (if ARG2 ARG2
-              ARG3))
+   The two properties of a charset that can currently be set after the
+charset has been created are the CCL program and the font registry.

 
 

-     This is not completely equivalent because it can evaluate ARG1 or
-     ARG2 twice.  By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
-     any argument more than once.
+ - Function: set-charset-ccl-program charset ccl-program
+     This function sets the `ccl-program' property of CHARSET to
+     CCL-PROGRAM.
+
+ - Function: set-charset-registry charset registry
+     This function sets the `registry' property of CHARSET to REGISTRY.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Iteration,  Next: Nonlocal Exits,  Prev: Combining Conditions,  Up: Control Structures
+File: lispref.info,  Node: Predefined Charsets,  Prev: Charset Property Functions,  Up: Charsets
+
+Predefined Charsets
+-------------------
+
+The following charsets are predefined in the C code.
+
+     Name                    Type  Fi Gr Dir Registry
+     --------------------------------------------------------------
+     ascii                    94    B  0  l2r ISO8859-1
+     control-1                94       0  l2r ---
+     latin-iso8859-1          94    A  1  l2r ISO8859-1
+     latin-iso8859-2          96    B  1  l2r ISO8859-2
+     latin-iso8859-3          96    C  1  l2r ISO8859-3
+     latin-iso8859-4          96    D  1  l2r ISO8859-4
+     cyrillic-iso8859-5       96    L  1  l2r ISO8859-5
+     arabic-iso8859-6         96    G  1  r2l ISO8859-6
+     greek-iso8859-7          96    F  1  l2r ISO8859-7
+     hebrew-iso8859-8         96    H  1  r2l ISO8859-8
+     latin-iso8859-9          96    M  1  l2r ISO8859-9
+     thai-tis620              96    T  1  l2r TIS620
+     katakana-jisx0201        94    I  1  l2r JISX0201.1976
+     latin-jisx0201           94    J  0  l2r JISX0201.1976
+     japanese-jisx0208-1978   94x94 @  0  l2r JISX0208.1978
+     japanese-jisx0208        94x94 B  0  l2r JISX0208.19(83|90)
+     japanese-jisx0212        94x94 D  0  l2r JISX0212
+     chinese-gb2312           94x94 A  0  l2r GB2312
+     chinese-cns11643-1       94x94 G  0  l2r CNS11643.1
+     chinese-cns11643-2       94x94 H  0  l2r CNS11643.2
+     chinese-big5-1           94x94 0  0  l2r Big5
+     chinese-big5-2           94x94 1  0  l2r Big5
+     korean-ksc5601           94x94 C  0  l2r KSC5601
+     composite                96x96    0  l2r ---
+
+   The following charsets are predefined in the Lisp code.
+
+     Name                     Type  Fi Gr Dir Registry
+     --------------------------------------------------------------
+     arabic-digit             94    2  0  l2r MuleArabic-0
+     arabic-1-column          94    3  0  r2l MuleArabic-1
+     arabic-2-column          94    4  0  r2l MuleArabic-2
+     sisheng                  94    0  0  l2r sisheng_cwnn\|OMRON_UDC_ZH
+     chinese-cns11643-3       94x94 I  0  l2r CNS11643.1
+     chinese-cns11643-4       94x94 J  0  l2r CNS11643.1
+     chinese-cns11643-5       94x94 K  0  l2r CNS11643.1
+     chinese-cns11643-6       94x94 L  0  l2r CNS11643.1
+     chinese-cns11643-7       94x94 M  0  l2r CNS11643.1
+     ethiopic                 94x94 2  0  l2r Ethio
+     ascii-r2l                94    B  0  r2l ISO8859-1
+     ipa                      96    0  1  l2r MuleIPA
+     vietnamese-viscii-lower  96    1  1  l2r VISCII1.1
+     vietnamese-viscii-upper  96    2  1  l2r VISCII1.1
+
+   For all of the above charsets, the dimension and number of columns
+are the same.
+
+   Note that ASCII, Control-1, and Composite are handled specially.
+This is why some of the fields are blank; and some of the filled-in
+fields (e.g. the type) are not really accurate.

 
 

-Iteration
-=========
+\1f
+File: lispref.info,  Node: MULE Characters,  Next: Composite Characters,  Prev: Charsets,  Up: MULE

 
 

-   Iteration means executing part of a program repetitively.  For
-example, you might want to repeat some computation once for each element
-of a list, or once for each integer from 0 to N.  You can do this in
-XEmacs Lisp with the special form `while':
+MULE Characters
+===============

 
 

- - Special Form: while condition forms...
-     `while' first evaluates CONDITION.  If the result is non-`nil', it
-     evaluates FORMS in textual order.  Then it reevaluates CONDITION,
-     and if the result is non-`nil', it evaluates FORMS again.  This
-     process repeats until CONDITION evaluates to `nil'.
+ - Function: make-char charset arg1 &optional arg2
+     This function makes a multi-byte character from CHARSET and octets
+     ARG1 and ARG2.

 
 

-     There is no limit on the number of iterations that may occur.  The
-     loop will continue until either CONDITION evaluates to `nil' or
-     until an error or `throw' jumps out of it (*note Nonlocal Exits::).
+ - Function: char-charset character
+     This function returns the character set of char CHARACTER.

 
 

-     The value of a `while' form is always `nil'.
+ - Function: char-octet character &optional n
+     This function returns the octet (i.e. position code) numbered N
+     (should be 0 or 1) of char CHARACTER.  N defaults to 0 if omitted.

 
 

-          (setq num 0)
-               => 0
-          (while (< num 4)
-            (princ (format "Iteration %d." num))
-            (setq num (1+ num)))
-               -| Iteration 0.
-               -| Iteration 1.
-               -| Iteration 2.
-               -| Iteration 3.
-               => nil
+ - Function: find-charset-region start end &optional buffer
+     This function returns a list of the charsets in the region between
+     START and END.  BUFFER defaults to the current buffer if omitted.
+
+ - Function: find-charset-string string
+     This function returns a list of the charsets in STRING.
+
+\1f
+File: lispref.info,  Node: Composite Characters,  Next: Coding Systems,  Prev: MULE Characters,  Up: MULE
+
+Composite Characters
+====================

 
 

-     If you would like to execute something on each iteration before the
-     end-test, put it together with the end-test in a `progn' as the
-     first argument of `while', as shown here:
+Composite characters are not yet completely implemented.

 
 

-          (while (progn
-                   (forward-line 1)
-                   (not (looking-at "^$"))))
+ - Function: make-composite-char string
+     This function converts a string into a single composite character.
+     The character is the result of overstriking all the characters in
+     the string.

 
 

-     This moves forward one line and continues moving by lines until it
-     reaches an empty.  It is unusual in that the `while' has no body,
-     just the end test (which also does the real work of moving point).
+ - Function: composite-char-string character
+     This function returns a string of the characters comprising a
+     composite character.
+
+ - Function: compose-region start end &optional buffer
+     This function composes the characters in the region from START to
+     END in BUFFER into one composite character.  The composite
+     character replaces the composed characters.  BUFFER defaults to
+     the current buffer if omitted.
+
+ - Function: decompose-region start end &optional buffer
+     This function decomposes any composite characters in the region
+     from START to END in BUFFER.  This converts each composite
+     character into one or more characters, the individual characters
+     out of which the composite character was formed.  Non-composite
+     characters are left as-is.  BUFFER defaults to the current buffer
+     if omitted.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Nonlocal Exits,  Prev: Iteration,  Up: Control Structures
+File: lispref.info,  Node: Coding Systems,  Next: CCL,  Prev: Composite Characters,  Up: MULE

 
 

-Nonlocal Exits
+Coding Systems

 ==============
 
 ==============
 

-   A "nonlocal exit" is a transfer of control from one point in a
-program to another remote point.  Nonlocal exits can occur in XEmacs
-Lisp as a result of errors; you can also use them under explicit
-control.  Nonlocal exits unbind all variable bindings made by the
-constructs being exited.
+A coding system is an object that defines how text containing multiple
+character sets is encoded into a stream of (typically 8-bit) bytes.  The
+coding system is used to decode the stream into a series of characters
+(which may be from multiple charsets) when the text is read from a file
+or process, and is used to encode the text back into the same format
+when it is written out to a file or process.
+
+   For example, many ISO-2022-compliant coding systems (such as Compound
+Text, which is used for inter-client data under the X Window System) use
+escape sequences to switch between different charsets - Japanese Kanji,
+for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC (
+B'; and Cyrillic is invoked with `ESC - L'.  See `make-coding-system'
+for more information.
+
+   Coding systems are normally identified using a symbol, and the
+symbol is accepted in place of the actual coding system object whenever
+a coding system is called for. (This is similar to how faces and
+charsets work.)
+
+ - Function: coding-system-p object
+     This function returns non-`nil' if OBJECT is a coding system.

 
 * Menu:
 
 
 * Menu:
 

-* 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.
-
-\1f
-File: lispref.info,  Node: Catch and Throw,  Next: Examples of Catch,  Up: Nonlocal Exits
-
-Explicit Nonlocal Exits: `catch' and `throw'
---------------------------------------------
-
-   Most control constructs affect only the flow of control within the
-construct itself.  The function `throw' is the exception to this rule
-of normal program execution: it performs a nonlocal exit on request.
-(There are other exceptions, but they are for error handling only.)
-`throw' is used inside a `catch', and jumps back to that `catch'.  For
-example:
-
-     (catch 'foo
-       (progn
-         ...
-         (throw 'foo t)
-         ...))
-
-The `throw' transfers control straight back to the corresponding
-`catch', which returns immediately.  The code following the `throw' is
-not executed.  The second argument of `throw' is used as the return
-value of the `catch'.
-
-   The `throw' and the `catch' are matched through the first argument:
-`throw' searches for a `catch' whose first argument is `eq' to the one
-specified.  Thus, in the above example, the `throw' specifies `foo',
-and the `catch' specifies the same symbol, so that `catch' is
-applicable.  If there is more than one applicable `catch', the
-innermost one takes precedence.
-
-   Executing `throw' exits all Lisp constructs up to the matching
-`catch', including function calls.  When binding constructs such as
-`let' or function calls are exited in this way, the bindings are
-unbound, just as they are when these constructs exit normally (*note
-Local Variables::).  Likewise, `throw' restores the buffer and position
-saved by `save-excursion' (*note Excursions::), and the narrowing
-status saved by `save-restriction' and the window selection saved by
-`save-window-excursion' (*note Window Configurations::).  It also runs
-any cleanups established with the `unwind-protect' special form when it
-exits that form (*note Cleanups::).
-
-   The `throw' need not appear lexically within the `catch' that it
-jumps to.  It can equally well be called from another function called
-within the `catch'.  As long as the `throw' takes place chronologically
-after entry to the `catch', and chronologically before exit from it, it
-has access to that `catch'.  This is why `throw' can be used in
-commands such as `exit-recursive-edit' that throw back to the editor
-command loop (*note Recursive Editing::).
-
-     Common Lisp note: Most other versions of Lisp, including Common
-     Lisp, have several ways of transferring control nonsequentially:
-     `return', `return-from', and `go', for example.  XEmacs Lisp has
-     only `throw'.
-
- - Special Form: catch tag body...
-     `catch' establishes a return point for the `throw' function.  The
-     return point is distinguished from other such return points by TAG,
-     which may be any Lisp object.  The argument TAG is evaluated
-     normally before the return point is established.
-
-     With the return point in effect, `catch' evaluates the forms of the
-     BODY in textual order.  If the forms execute normally, without
-     error or nonlocal exit, the value of the last body form is
-     returned from the `catch'.
-
-     If a `throw' is done within BODY specifying the same value TAG,
-     the `catch' exits immediately; the value it returns is whatever
-     was specified as the second argument of `throw'.
-
- - Function: throw tag value
-     The purpose of `throw' is to return from a return point previously
-     established with `catch'.  The argument TAG is used to choose
-     among the various existing return points; it must be `eq' to the
-     value specified in the `catch'.  If multiple return points match
-     TAG, the innermost one is used.
-
-     The argument VALUE is used as the value to return from that
-     `catch'.
-
-     If no return point is in effect with tag TAG, then a `no-catch'
-     error is signaled with data `(TAG VALUE)'.
-
-\1f
-File: lispref.info,  Node: Examples of Catch,  Next: Errors,  Prev: Catch and Throw,  Up: Nonlocal Exits
-
-Examples of `catch' and `throw'
--------------------------------
+* Coding System Types::               Classifying coding systems.
+* ISO 2022::                          An international standard for
+                                        charsets and encodings.
+* EOL Conversion::                    Dealing with different ways of denoting
+                                        the end of a line.
+* Coding System Properties::          Properties of a coding system.
+* Basic Coding System Functions::     Working with coding systems.
+* Coding System Property Functions::  Retrieving a coding system's properties.
+* Encoding and Decoding Text::        Encoding and decoding text.
+* Detection of Textual Encoding::     Determining how text is encoded.
+* Big5 and Shift-JIS Functions::      Special functions for these non-standard
+                                        encodings.
+* Predefined Coding Systems::         Coding systems implemented by MULE.
+
+\1f
+File: lispref.info,  Node: Coding System Types,  Next: ISO 2022,  Up: Coding Systems
+
+Coding System Types
+-------------------
+
+The coding system type determines the basic algorithm XEmacs will use to
+decode or encode a data stream.  Character encodings will be converted
+to the MULE encoding, escape sequences processed, and newline sequences
+converted to XEmacs's internal representation.  There are three basic
+classes of coding system type: no-conversion, ISO-2022, and special.
+
+   No conversion allows you to look at the file's internal
+representation.  Since XEmacs is basically a text editor, "no
+conversion" does convert newline conventions by default.  (Use the
+'binary coding-system if this is not desired.)
+
+   ISO 2022 (*note ISO 2022::) is the basic international standard
+regulating use of "coded character sets for the exchange of data", ie,
+text streams.  ISO 2022 contains functions that make it possible to
+encode text streams to comply with restrictions of the Internet mail
+system and de facto restrictions of most file systems (eg, use of the
+separator character in file names).  Coding systems which are not ISO
+2022 conformant can be difficult to handle.  Perhaps more important,
+they are not adaptable to multilingual information interchange, with
+the obvious exception of ISO 10646 (Unicode).  (Unicode is partially
+supported by XEmacs with the addition of the Lisp package ucs-conv.)
+
+   The special class of coding systems includes automatic detection,
+CCL (a "little language" embedded as an interpreter, useful for
+translating between variants of a single character set),
+non-ISO-2022-conformant encodings like Unicode, Shift JIS, and Big5,
+and MULE internal coding.  (NB: this list is based on XEmacs 21.2.
+Terminology may vary slightly for other versions of XEmacs and for GNU
+Emacs 20.)
+
+`no-conversion'
+     No conversion, for binary files, and a few special cases of
+     non-ISO-2022 coding systems where conversion is done by hook
+     functions (usually implemented in CCL).  On output, graphic
+     characters that are not in ASCII or Latin-1 will be replaced by a
+     `?'. (For a no-conversion-encoded buffer, these characters will
+     only be present if you explicitly insert them.)
+
+`iso2022'
+     Any ISO-2022-compliant encoding.  Among others, this includes JIS
+     (the Japanese encoding commonly used for e-mail), national
+     variants of EUC (the standard Unix encoding for Japanese and other
+     languages), and Compound Text (an encoding used in X11).  You can
+     specify more specific information about the conversion with the
+     FLAGS argument.
+
+`ucs-4'
+     ISO 10646 UCS-4 encoding.  A 31-bit fixed-width superset of
+     Unicode.
+
+`utf-8'
+     ISO 10646 UTF-8 encoding.  A "file system safe" transformation
+     format that can be used with both UCS-4 and Unicode.
+
+`undecided'
+     Automatic conversion.  XEmacs attempts to detect the coding system
+     used in the file.
+
+`shift-jis'
+     Shift-JIS (a Japanese encoding commonly used in PC operating
+     systems).
+
+`big5'
+     Big5 (the encoding commonly used for Taiwanese).
+
+`ccl'
+     The conversion is performed using a user-written pseudo-code
+     program.  CCL (Code Conversion Language) is the name of this
+     pseudo-code.  For example, CCL is used to map KOI8-R characters
+     (an encoding for Russian Cyrillic) to ISO8859-5 (the form used
+     internally by MULE).
+
+`internal'
+     Write out or read in the raw contents of the memory representing
+     the buffer's text.  This is primarily useful for debugging
+     purposes, and is only enabled when XEmacs has been compiled with
+     `DEBUG_XEMACS' set (the `--debug' configure option).  *Warning*:
+     Reading in a file using `internal' conversion can result in an
+     internal inconsistency in the memory representing a buffer's text,
+     which will produce unpredictable results and may cause XEmacs to
+     crash.  Under normal circumstances you should never use `internal'
+     conversion.
+
+\1f
+File: lispref.info,  Node: ISO 2022,  Next: EOL Conversion,  Prev: Coding System Types,  Up: Coding Systems
+
+ISO 2022
+========
+
+This section briefly describes the ISO 2022 encoding standard.  A more
+thorough treatment is available in the original document of ISO 2022 as
+well as various national standards (such as JIS X 0202).
+
+   Character sets ("charsets") are classified into the following four
+categories, according to the number of characters in the charset:
+94-charset, 96-charset, 94x94-charset, and 96x96-charset.  This means
+that although an ISO 2022 coding system may have variable width
+characters, each charset used is fixed-width (in contrast to the MULE
+character set and UTF-8, for example).
+
+   ISO 2022 provides for switching between character sets via escape
+sequences.  This switching is somewhat complicated, because ISO 2022
+provides for both legacy applications like Internet mail that accept
+only 7 significant bits in some contexts (RFC 822 headers, for example),
+and more modern "8-bit clean" applications.  It also provides for
+compact and transparent representation of languages like Japanese which
+mix ASCII and a national script (even outside of computer programs).
+
+   First, ISO 2022 codified prevailing practice by dividing the code
+space into "control" and "graphic" regions.  The code points 0x00-0x1F
+and 0x80-0x9F are reserved for "control characters", while "graphic
+characters" must be assigned to code points in the regions 0x20-0x7F and
+0xA0-0xFF.  The positions 0x20 and 0x7F are special, and under some
+circumstances must be assigned the graphic character "ASCII SPACE" and
+the control character "ASCII DEL" respectively.
+
+   The various regions are given the name C0 (0x00-0x1F), GL
+(0x20-0x7F), C1 (0x80-0x9F), and GR (0xA0-0xFF).  GL and GR stand for
+"graphic left" and "graphic right", respectively, because of the
+standard method of displaying graphic character sets in tables with the
+high byte indexing columns and the low byte indexing rows.  I don't
+find it very intuitive, but these are called "registers".
+
+   An ISO 2022-conformant encoding for a graphic character set must use
+a fixed number of bytes per character, and the values must fit into a
+single register; that is, each byte must range over either 0x20-0x7F, or
+0xA0-0xFF.  It is not allowed to extend the range of the repertoire of a
+character set by using both ranges at the same.  This is why a standard
+character set such as ISO 8859-1 is actually considered by ISO 2022 to
+be an aggregation of two character sets, ASCII and LATIN-1, and why it
+is technically incorrect to refer to ISO 8859-1 as "Latin 1".  Also, a
+single character's bytes must all be drawn from the same register; this
+is why Shift JIS (for Japanese) and Big 5 (for Chinese) are not ISO
+2022-compatible encodings.
+
+   The reason for this restriction becomes clear when you attempt to
+define an efficient, robust encoding for a language like Japanese.
+Like ISO 8859, Japanese encodings are aggregations of several character
+sets.  In practice, the vast majority of characters are drawn from the
+"JIS Roman" character set (a derivative of ASCII; it won't hurt to
+think of it as ASCII) and the JIS X 0208 standard "basic Japanese"
+character set including not only ideographic characters ("kanji") but
+syllabic Japanese characters ("kana"), a wide variety of symbols, and
+many alphabetic characters (Roman, Greek, and Cyrillic) as well.
+Although JIS X 0208 includes the whole Roman alphabet, as a 2-byte code
+it is not suited to programming; thus the inclusion of ASCII in the
+standard Japanese encodings.
+
+   For normal Japanese text such as in newspapers, a broad repertoire of
+approximately 3000 characters is used.  Evidently this won't fit into
+one byte; two must be used.  But much of the text processed by Japanese
+computers is computer source code, nearly all of which is ASCII.  A not
+insignificant portion of ordinary text is English (as such or as
+borrowed Japanese vocabulary) or other languages which can represented
+at least approximately in ASCII, as well.  It seems reasonable then to
+represent ASCII in one byte, and JIS X 0208 in two.  And this is exactly
+what the Extended Unix Code for Japanese (EUC-JP) does.  ASCII is
+invoked to the GL register, and JIS X 0208 is invoked to the GR
+register.  Thus, each byte can be tested for its character set by
+looking at the high bit; if set, it is Japanese, if clear, it is ASCII.
+Furthermore, since control characters like newline can never be part of
+a graphic character, even in the case of corruption in transmission the
+stream will be resynchronized at every line break, on the order of 60-80
+bytes.  This coding system requires no escape sequences or special
+control codes to represent 99.9% of all Japanese text.
+
+   Note carefully the distinction between the character sets (ASCII and
+JIS X 0208), the encoding (EUC-JP), and the coding system (ISO 2022).
+The JIS X 0208 character set is used in three different encodings for
+Japanese, but in ISO-2022-JP it is invoked into GL (so the high bit is
+always clear), in EUC-JP it is invoked into GR (setting the high bit in
+the process), and in Shift JIS the high bit may be set or reset, and the
+significant bits are shifted within the 16-bit character so that the two
+main character sets can coexist with a third (the "halfwidth katakana"
+of JIS X 0201).  As the name implies, the ISO-2022-JP encoding is also a
+version of the ISO-2022 coding system.
+
+   In order to systematically treat subsidiary character sets (like the
+"halfwidth katakana" already mentioned, and the "supplementary kanji" of
+JIS X 0212), four further registers are defined: G0, G1, G2, and G3.
+Unlike GL and GR, they are not logically distinguished by internal
+format.  Instead, the process of "invocation" mentioned earlier is
+broken into two steps: first, a character set is "designated" to one of
+the registers G0-G3 by use of an "escape sequence" of the form:
+
+             ESC [I] I F
+
+   where I is an intermediate character or characters in the range 0x20
+- 0x3F, and F, from the range 0x30-0x7Fm is the final character
+identifying this charset.  (Final characters in the range 0x30-0x3F are
+reserved for private use and will never have a publicly registered
+meaning.)
+
+   Then that register is "invoked" to either GL or GR, either
+automatically (designations to G0 normally involve invocation to GL as
+well), or by use of shifting (affecting only the following character in
+the data stream) or locking (effective until the next designation or
+locking) control sequences.  An encoding conformant to ISO 2022 is
+typically defined by designating the initial contents of the G0-G3
+registers, specifying a 7 or 8 bit environment, and specifying whether
+further designations will be recognized.
+
+   Some examples of character sets and the registered final characters
+F used to designate them:
+
+94-charset
+     ASCII (B), left (J) and right (I) half of JIS X 0201, ...
+
+96-charset
+     Latin-1 (A), Latin-2 (B), Latin-3 (C), ...
+
+94x94-charset
+     GB2312 (A), JIS X 0208 (B), KSC5601 (C), ...
+
+96x96-charset
+     none for the moment
+
+   The meanings of the various characters in these sequences, where not
+specified by the ISO 2022 standard (such as the ESC character), are
+assigned by "ECMA", the European Computer Manufacturers Association.
+
+   The meaning of intermediate characters are:
+
+             $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96).
+             ( [0x28]: designate to G0 a 94-charset whose final byte is F.
+             ) [0x29]: designate to G1 a 94-charset whose final byte is F.
+             * [0x2A]: designate to G2 a 94-charset whose final byte is F.
+             + [0x2B]: designate to G3 a 94-charset whose final byte is F.
+             , [0x2C]: designate to G0 a 96-charset whose final byte is F.
+             - [0x2D]: designate to G1 a 96-charset whose final byte is F.
+             . [0x2E]: designate to G2 a 96-charset whose final byte is F.
+             / [0x2F]: designate to G3 a 96-charset whose final byte is F.
+
+   The comma may be used in files read and written only by MULE, as a
+MULE extension, but this is illegal in ISO 2022.  (The reason is that
+in ISO 2022 G0 must be a 94-member character set, with 0x20 assigned
+the value SPACE, and 0x7F assigned the value DEL.)
+
+   Here are examples of designations:
+
+             ESC ( B :              designate to G0 ASCII
+             ESC - A :              designate to G1 Latin-1
+             ESC $ ( A or ESC $ A : designate to G0 GB2312
+             ESC $ ( B or ESC $ B : designate to G0 JISX0208
+             ESC $ ) C :            designate to G1 KSC5601
+
+   (The short forms used to designate GB2312 and JIS X 0208 are for
+backwards compatibility; the long forms are preferred.)
+
+   To use a charset designated to G2 or G3, and to use a charset
+designated to G1 in a 7-bit environment, you must explicitly invoke G1,
+G2, or G3 into GL.  There are two types of invocation, Locking Shift
+(forever) and Single Shift (one character only).
+
+   Locking Shift is done as follows:
+
+             LS0 or SI (0x0F): invoke G0 into GL
+             LS1 or SO (0x0E): invoke G1 into GL
+             LS2:  invoke G2 into GL
+             LS3:  invoke G3 into GL
+             LS1R: invoke G1 into GR
+             LS2R: invoke G2 into GR
+             LS3R: invoke G3 into GR
+
+   Single Shift is done as follows:
+
+             SS2 or ESC N: invoke G2 into GL
+             SS3 or ESC O: invoke G3 into GL
+
+   The shift functions (such as LS1R and SS3) are represented by control
+characters (from C1) in 8 bit environments and by escape sequences in 7
+bit environments.
+
+   (#### Ben says: I think the above is slightly incorrect.  It appears
+that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N
+and ESC O behave as indicated.  The above definitions will not parse
+EUC-encoded text correctly, and it looks like the code in mule-coding.c
+has similar problems.)
+
+   Evidently there are a lot of ISO-2022-compliant ways of encoding
+multilingual text.  Now, in the world, there exist many coding systems
+such as X11's Compound Text, Japanese JUNET code, and so-called EUC
+(Extended UNIX Code); all of these are variants of ISO 2022.
+
+   In MULE, we characterize a version of ISO 2022 by the following
+attributes:
+
+  1. The character sets initially designated to G0 thru G3.
+
+  2. Whether short form designations are allowed for Japanese and
+     Chinese.
+
+  3. Whether ASCII should be designated to G0 before control characters.

 
 

-   One way to use `catch' and `throw' is to exit from a doubly nested
-loop.  (In most languages, this would be done with a "go to".)  Here we
-compute `(foo I J)' for I and J varying from 0 to 9:
-
-     (defun search-foo ()
-       (catch 'loop
-         (let ((i 0))
-           (while (< i 10)
-             (let ((j 0))
-               (while (< j 10)
-                 (if (foo i j)
-                     (throw 'loop (list i j)))
-                 (setq j (1+ j))))
-             (setq i (1+ i))))))
-
-If `foo' ever returns non-`nil', we stop immediately and return a list
-of I and J.  If `foo' always returns `nil', the `catch' returns
-normally, and the value is `nil', since that is the result of the
-`while'.
-
-   Here are two tricky examples, slightly different, showing two return
-points at once.  First, two return points with the same tag, `hack':
-
-     (defun catch2 (tag)
-       (catch tag
-         (throw 'hack 'yes)))
-     => catch2
+  4. Whether ASCII should be designated to G0 at the end of line.
+
+  5. 7-bit environment or 8-bit environment.
+
+  6. Whether Locking Shifts are used or not.
+
+  7. Whether to use ASCII or the variant JIS X 0201-1976-Roman.
+
+  8. Whether to use JIS X 0208-1983 or the older version JIS X
+     0208-1976.
+
+   (The last two are only for Japanese.)
+
+   By specifying these attributes, you can create any variant of ISO
+2022.
+
+   Here are several examples:
+
+     ISO-2022-JP -- Coding system used in Japanese email (RFC 1463 #### check).
+             1. G0 <- ASCII, G1..3 <- never used
+             2. Yes.
+             3. Yes.
+             4. Yes.
+             5. 7-bit environment
+             6. No.
+             7. Use ASCII
+             8. Use JIS X 0208-1983

      
      

-     (catch 'hack
-       (print (catch2 'hack))
-       'no)
-     -| yes
-     => no
-
-Since both return points have tags that match the `throw', it goes to
-the inner one, the one established in `catch2'.  Therefore, `catch2'
-returns normally with value `yes', and this value is printed.  Finally
-the second body form in the outer `catch', which is `'no', is evaluated
-and returned from the outer `catch'.
-
-   Now let's change the argument given to `catch2':
-
-     (defun catch2 (tag)
-       (catch tag
-         (throw 'hack 'yes)))
-     => catch2
+     ctext -- X11 Compound Text
+             1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used.
+             2. No.
+             3. No.
+             4. Yes.
+             5. 8-bit environment.
+             6. No.
+             7. Use ASCII.
+             8. Use JIS X 0208-1983.

      
      

-     (catch 'hack
-       (print (catch2 'quux))
-       'no)
-     => yes
+     euc-china -- Chinese EUC.  Often called the "GB encoding", but that is
+     technically incorrect.
+             1. G0 <- ASCII, G1 <- GB 2312, G2,3 <- never used.
+             2. No.
+             3. Yes.
+             4. Yes.
+             5. 8-bit environment.
+             6. No.
+             7. Use ASCII.
+             8. Use JIS X 0208-1983.
+     
+     ISO-2022-KR -- Coding system used in Korean email.
+             1. G0 <- ASCII, G1 <- KSC 5601, G2,3 <- never used.
+             2. No.
+             3. Yes.
+             4. Yes.
+             5. 7-bit environment.
+             6. Yes.
+             7. Use ASCII.
+             8. Use JIS X 0208-1983.
+
+   MULE creates all of these coding systems by default.
+
+\1f
+File: lispref.info,  Node: EOL Conversion,  Next: Coding System Properties,  Prev: ISO 2022,  Up: Coding Systems
+
+EOL Conversion
+--------------
+
+`nil'
+     Automatically detect the end-of-line type (LF, CRLF, or CR).  Also
+     generate subsidiary coding systems named `NAME-unix', `NAME-dos',
+     and `NAME-mac', that are identical to this coding system but have
+     an EOL-TYPE value of `lf', `crlf', and `cr', respectively.
+
+`lf'
+     The end of a line is marked externally using ASCII LF.  Since this
+     is also the way that XEmacs represents an end-of-line internally,
+     specifying this option results in no end-of-line conversion.  This
+     is the standard format for Unix text files.
+
+`crlf'
+     The end of a line is marked externally using ASCII CRLF.  This is
+     the standard format for MS-DOS text files.
+
+`cr'
+     The end of a line is marked externally using ASCII CR.  This is the
+     standard format for Macintosh text files.

 
 

-We still have two return points, but this time only the outer one has
-the tag `hack'; the inner one has the tag `quux' instead.  Therefore,
-`throw' makes the outer `catch' return the value `yes'.  The function
-`print' is never called, and the body-form `'no' is never evaluated.
+`t'
+     Automatically detect the end-of-line type but do not generate
+     subsidiary coding systems.  (This value is converted to `nil' when
+     stored internally, and `coding-system-property' will return `nil'.)

 
 \1f
 
 \1f

-File: lispref.info,  Node: Errors,  Next: Cleanups,  Prev: Examples of Catch,  Up: Nonlocal Exits
+File: lispref.info,  Node: Coding System Properties,  Next: Basic Coding System Functions,  Prev: EOL Conversion,  Up: Coding Systems
+
+Coding System Properties
+------------------------
+
+`mnemonic'
+     String to be displayed in the modeline when this coding system is
+     active.
+
+`eol-type'
+     End-of-line conversion to be used.  It should be one of the types
+     listed in *Note EOL Conversion::.
+
+`eol-lf'
+     The coding system which is the same as this one, except that it
+     uses the Unix line-breaking convention.
+
+`eol-crlf'
+     The coding system which is the same as this one, except that it
+     uses the DOS line-breaking convention.
+
+`eol-cr'
+     The coding system which is the same as this one, except that it
+     uses the Macintosh line-breaking convention.
+
+`post-read-conversion'
+     Function called after a file has been read in, to perform the
+     decoding.  Called with two arguments, START and END, denoting a
+     region of the current buffer to be decoded.
+
+`pre-write-conversion'
+     Function called before a file is written out, to perform the
+     encoding.  Called with two arguments, START and END, denoting a
+     region of the current buffer to be encoded.
+
+   The following additional properties are recognized if TYPE is
+`iso2022':
+
+`charset-g0'
+`charset-g1'
+`charset-g2'
+`charset-g3'
+     The character set initially designated to the G0 - G3 registers.
+     The value should be one of
+
+        * A charset object (designate that character set)
+
+        * `nil' (do not ever use this register)
+
+        * `t' (no character set is initially designated to the
+          register, but may be later on; this automatically sets the
+          corresponding `force-g*-on-output' property)
+
+`force-g0-on-output'
+`force-g1-on-output'
+`force-g2-on-output'
+`force-g3-on-output'
+     If non-`nil', send an explicit designation sequence on output
+     before using the specified register.
+
+`short'
+     If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
+     B' on output in place of the full designation sequences `ESC $ (
+     @', `ESC $ ( A', and `ESC $ ( B'.
+
+`no-ascii-eol'
+     If non-`nil', don't designate ASCII to G0 at each end of line on
+     output.  Setting this to non-`nil' also suppresses other
+     state-resetting that normally happens at the end of a line.
+
+`no-ascii-cntl'
+     If non-`nil', don't designate ASCII to G0 before control chars on
+     output.
+
+`seven'
+     If non-`nil', use 7-bit environment on output.  Otherwise, use
+     8-bit environment.
+
+`lock-shift'
+     If non-`nil', use locking-shift (SO/SI) instead of single-shift or
+     designation by escape sequence.
+
+`no-iso6429'
+     If non-`nil', don't use ISO6429's direction specification.
+
+`escape-quoted'
+     If non-`nil', literal control characters that are the same as the
+     beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
+     particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
+     (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
+     that they can be properly distinguished from an escape sequence.
+     (Note that doing this results in a non-portable encoding.) This
+     encoding flag is used for byte-compiled files.  Note that ESC is a
+     good choice for a quoting character because there are no escape
+     sequences whose second byte is a character from the Control-0 or
+     Control-1 character sets; this is explicitly disallowed by the ISO
+     2022 standard.
+
+`input-charset-conversion'
+     A list of conversion specifications, specifying conversion of
+     characters in one charset to another when decoding is performed.
+     Each specification is a list of two elements: the source charset,
+     and the destination charset.
+
+`output-charset-conversion'
+     A list of conversion specifications, specifying conversion of
+     characters in one charset to another when encoding is performed.
+     The form of each specification is the same as for
+     `input-charset-conversion'.
+
+   The following additional properties are recognized (and required) if
+TYPE is `ccl':
+
+`decode'
+     CCL program used for decoding (converting to internal format).
+
+`encode'
+     CCL program used for encoding (converting to external format).
+
+   The following properties are used internally:  EOL-CR, EOL-CRLF,
+EOL-LF, and BASE.

 
 

-Errors
-------
+\1f
+File: lispref.info,  Node: Basic Coding System Functions,  Next: Coding System Property Functions,  Prev: Coding System Properties,  Up: Coding Systems

 
 

-   When XEmacs Lisp attempts to evaluate a form that, for some reason,
-cannot be evaluated, it "signals" an "error".
+Basic Coding System Functions
+-----------------------------

 
 

-   When an error is signaled, XEmacs's default reaction is to print an
-error message and terminate execution of the current command.  This is
-the right thing to do in most cases, such as if you type `C-f' at the
-end of the buffer.
+ - Function: find-coding-system coding-system-or-name
+     This function retrieves the coding system of the given name.

 
 

-   In complicated programs, simple termination may not be what you want.
-For example, the program may have made temporary changes in data
-structures, or created temporary buffers that should be deleted before
-the program is finished.  In such cases, you would use `unwind-protect'
-to establish "cleanup expressions" to be evaluated in case of error.
-(*Note Cleanups::.)  Occasionally, you may wish the program to continue
-execution despite an error in a subroutine.  In these cases, you would
-use `condition-case' to establish "error handlers" to recover control
-in case of error.
+     If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply
+     returned.  Otherwise, CODING-SYSTEM-OR-NAME should be a symbol.
+     If there is no such coding system, `nil' is returned.  Otherwise
+     the associated coding system object is returned.

 
 

-   Resist the temptation to use error handling to transfer control from
-one part of the program to another; use `catch' and `throw' instead.
-*Note Catch and Throw::.
+ - Function: get-coding-system name
+     This function retrieves the coding system of the given name.  Same
+     as `find-coding-system' except an error is signalled if there is no
+     such coding system instead of returning `nil'.

 
 

-* Menu:
+ - Function: coding-system-list
+     This function returns a list of the names of all defined coding
+     systems.
+
+ - Function: coding-system-name coding-system
+     This function returns the name of the given coding system.
+
+ - Function: coding-system-base coding-system
+     Returns the base coding system (undecided EOL convention) coding
+     system.
+
+ - Function: make-coding-system name type &optional doc-string props
+     This function registers symbol NAME as a coding system.
+
+     TYPE describes the conversion method used and should be one of the
+     types listed in *Note Coding System Types::.
+
+     DOC-STRING is a string describing the coding system.
+
+     PROPS is a property list, describing the specific nature of the
+     character set.  Recognized properties are as in *Note Coding
+     System Properties::.

 
 

-* 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.
+ - Function: copy-coding-system old-coding-system new-name
+     This function copies OLD-CODING-SYSTEM to NEW-NAME.  If NEW-NAME
+     does not name an existing coding system, a new one will be created.
+
+ - Function: subsidiary-coding-system coding-system eol-type
+     This function returns the subsidiary coding system of
+     CODING-SYSTEM with eol type EOL-TYPE.

 
 \1f
 
 \1f

-File: lispref.info,  Node: Signaling Errors,  Next: Processing of Errors,  Up: Errors
+File: lispref.info,  Node: Coding System Property Functions,  Next: Encoding and Decoding Text,  Prev: Basic Coding System Functions,  Up: Coding Systems

 
 

-How to Signal an Error
-......................
+Coding System Property Functions
+--------------------------------

 
 

-   Most errors are signaled "automatically" within Lisp primitives
-which you call for other purposes, such as if you try to take the CAR
-of an integer or move forward a character at the end of the buffer; you
-can also signal errors explicitly with the functions `error', `signal',
-and others.
+ - Function: coding-system-doc-string coding-system
+     This function returns the doc string for CODING-SYSTEM.

 
 

-   Quitting, which happens when the user types `C-g', is not considered
-an error, but it is handled almost like an error.  *Note Quitting::.
+ - Function: coding-system-type coding-system
+     This function returns the type of CODING-SYSTEM.

 
 

-   XEmacs has a rich hierarchy of error symbols predefined via
-`deferror'.
+ - Function: coding-system-property coding-system prop
+     This function returns the PROP property of CODING-SYSTEM.

 
 

-     error
-       syntax-error
-         invalid-read-syntax
-         list-formation-error
-           malformed-list
-             malformed-property-list
-           circular-list
-             circular-property-list
-     
-       invalid-argument
-         wrong-type-argument
-         args-out-of-range
-         wrong-number-of-arguments
-         invalid-function
-         no-catch
-     
-       invalid-state
-         void-function
-         cyclic-function-indirection
-         void-variable
-         cyclic-variable-indirection
-     
-       invalid-operation
-         invalid-change
-           setting-constant
-         editing-error
-           beginning-of-buffer
-           end-of-buffer
-           buffer-read-only
-         io-error
-           end-of-file
-         arith-error
-           range-error
-           domain-error
-           singularity-error
-           overflow-error
-           underflow-error
-
-   The five most common errors you will probably use or base your new
-errors off of are `syntax-error', `invalid-argument', `invalid-state',
-`invalid-operation', and `invalid-change'.  Note the semantic
-differences:
-
-   * `syntax-error' is for errors in complex structures: parsed strings,
-     lists, and the like.
-
-   * `invalid-argument' is for errors in a simple value.  Typically, the
-     entire value, not just one part of it, is wrong.
-
-   * `invalid-state' means that some settings have been changed in such
-     a way that their current state is unallowable.  More and more,
-     code is being written more carefully, and catches the error when
-     the settings are being changed, rather than afterwards.  This
-     leads us to the next error:
-
-   * `invalid-change' means that an attempt is being made to change some
-     settings into an invalid state.  `invalid-change' is a type of
-     `invalid-operation'.
-
-   * `invalid-operation' refers to all cases where code is trying to do
-     something that's disallowed.  This includes file errors, buffer
-     errors (e.g. running off the end of a buffer), `invalid-change' as
-     just mentioned, and arithmetic errors.
-
- - Function: error datum &rest args
-     This function signals a non-continuable error.
-
-     DATUM should normally be an error symbol, i.e. a symbol defined
-     using `define-error'.  ARGS will be made into a list, and DATUM
-     and ARGS passed as the two arguments to `signal', the most basic
-     error handling function.
-
-     This error is not continuable: you cannot continue execution after
-     the error using the debugger `r' command.  See also `cerror'.
-
-     The correct semantics of ARGS varies from error to error, but for
-     most errors that need to be generated in Lisp code, the first
-     argument should be a string describing the *context* of the error
-     (i.e. the exact operation being performed and what went wrong),
-     and the remaining arguments or \"frobs\" (most often, there is
-     one) specify the offending object(s) and/or provide additional
-     details such as the exact error when a file error occurred, e.g.:
-
-        * the buffer in which an editing error occurred.
-
-        * an invalid value that was encountered. (In such cases, the
-          string should describe the purpose or \"semantics\" of the
-          value [e.g. if the value is an argument to a function, the
-          name of the argument; if the value is the value corresponding
-          to a keyword, the name of the keyword; if the value is
-          supposed to be a list length, say this and say what the
-          purpose of the list is; etc.] as well as specifying why the
-          value is invalid, if that's not self-evident.)
-
-        * the file in which an error occurred. (In such cases, there
-          should be a second frob, probably a string, specifying the
-          exact error that occurred.  This does not occur in the string
-          that precedes the first frob, because that frob describes the
-          exact operation that was happening.
-
-     For historical compatibility, DATUM can also be a string.  In this
-     case, DATUM and ARGS are passed together as the arguments to
-     `format', and then an error is signalled using the error symbol
-     `error' and formatted string.  Although this usage of `error' is
-     very common, it is deprecated because it totally defeats the
-     purpose of having structured errors.  There is now a rich set of
-     defined errors to use.
-
-     See also `cerror', `signal', and `signal-error'."
-
-     These examples show typical uses of `error':
-
-          (error 'syntax-error
-                 "Dialog descriptor must supply at least one button"
-               descriptor)
-          
-          (error "You have committed an error.
-                  Try something else.")
-               error--> You have committed an error.
-                  Try something else.
-          
-          (error "You have committed %d errors." 10)
-               error--> You have committed 10 errors.
-
-     If you want to use your own string as an error message verbatim,
-     don't just write `(error STRING)'.  If STRING contains `%', it
-     will be interpreted as a format specifier, with undesirable
-     results.  Instead, use `(error "%s" STRING)'.
-
- - Function: cerror datum &rest args
-     This function behaves like `error', except that the error it
-     signals is continuable.  That means that debugger commands `c' and
-     `r' can resume execution.
-
- - Function: signal error-symbol data
-     This function signals a continuable error named by ERROR-SYMBOL.
-     The argument DATA is a list of additional Lisp objects relevant to
-     the circumstances of the error.
-
-     The argument ERROR-SYMBOL must be an "error symbol"--a symbol
-     bearing a property `error-conditions' whose value is a list of
-     condition names.  This is how XEmacs Lisp classifies different
-     sorts of errors.
-
-     The number and significance of the objects in DATA depends on
-     ERROR-SYMBOL.  For example, with a `wrong-type-argument' error,
-     there are two objects in the list: a predicate that describes the
-     type that was expected, and the object that failed to fit that
-     type.  *Note Error Symbols::, for a description of error symbols.
-
-     Both ERROR-SYMBOL and DATA are available to any error handlers
-     that handle the error: `condition-case' binds a local variable to
-     a list of the form `(ERROR-SYMBOL .  DATA)' (*note Handling
-     Errors::).  If the error is not handled, these two values are used
-     in printing the error message.
-
-     The function `signal' can return, if the debugger is invoked and
-     the user invokes the "return from signal" option.  If you want the
-     error not to be continuable, use `signal-error' instead.  Note that
-     in FSF Emacs `signal' never returns.
-
-          (signal 'wrong-number-of-arguments '(x y))
-               error--> Wrong number of arguments: x, y
-          
-          (signal 'no-such-error '("My unknown error condition"))
-               error--> Peculiar error (no-such-error "My unknown error condition")
-
- - Function: signal-error error-symbol data
-     This function behaves like `signal', except that the error it
-     signals is not continuable.
-
- - Macro: check-argument-type predicate argument
-     This macro checks that ARGUMENT satisfies PREDICATE.  If that is
-     not the case, it signals a continuable `wrong-type-argument' error
-     until the returned value satisfies PREDICATE, and assigns the
-     returned value to ARGUMENT.  In other words, execution of the
-     program will not continue until PREDICATE is met.
-
-     ARGUMENT is not evaluated, and should be a symbol.  PREDICATE is
-     evaluated, and should name a function.
-
-     As shown in the following example, `check-argument-type' is useful
-     in low-level code that attempts to ensure the sanity of its data
-     before proceeding.
-
-          (defun cache-object-internal (object wlist)
-            ;; Before doing anything, make sure that WLIST is indeed
-            ;; a weak list, which is what we expect.
-            (check-argument-type 'weak-list-p wlist)
-            ...)
+\1f
+File: lispref.info,  Node: Encoding and Decoding Text,  Next: Detection of Textual Encoding,  Prev: Coding System Property Functions,  Up: Coding Systems
+
+Encoding and Decoding Text
+--------------------------
+
+ - Function: decode-coding-region start end coding-system &optional
+          buffer
+     This function decodes the text between START and END which is
+     encoded in CODING-SYSTEM.  This is useful if you've read in
+     encoded text from a file without decoding it (e.g. you read in a
+     JIS-formatted file but used the `binary' or `no-conversion' coding
+     system, so that it shows up as `^[$B!<!+^[(B').  The length of the
+     encoded text is returned.  BUFFER defaults to the current buffer
+     if unspecified.
+
+ - Function: encode-coding-region start end coding-system &optional
+          buffer
+     This function encodes the text between START and END using
+     CODING-SYSTEM.  This will, for example, convert Japanese
+     characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
+     encoding.  The length of the encoded text is returned.  BUFFER
+     defaults to the current buffer if unspecified.
+
+\1f
+File: lispref.info,  Node: Detection of Textual Encoding,  Next: Big5 and Shift-JIS Functions,  Prev: Encoding and Decoding Text,  Up: Coding Systems
+
+Detection of Textual Encoding
+-----------------------------
+
+ - Function: coding-category-list
+     This function returns a list of all recognized coding categories.
+
+ - Function: set-coding-priority-list list
+     This function changes the priority order of the coding categories.
+     LIST should be a list of coding categories, in descending order of
+     priority.  Unspecified coding categories will be lower in priority
+     than all specified ones, in the same relative order they were in
+     previously.
+
+ - Function: coding-priority-list
+     This function returns a list of coding categories in descending
+     order of priority.
+
+ - Function: set-coding-category-system coding-category coding-system
+     This function changes the coding system associated with a coding
+     category.
+
+ - Function: coding-category-system coding-category
+     This function returns the coding system associated with a coding
+     category.
+
+ - Function: detect-coding-region start end &optional buffer
+     This function detects coding system of the text in the region
+     between START and END.  Returned value is a list of possible coding
+     systems ordered by priority.  If only ASCII characters are found,
+     it returns `autodetect' or one of its subsidiary coding systems
+     according to a detected end-of-line type.  Optional arg BUFFER
+     defaults to the current buffer.
+
+\1f
+File: lispref.info,  Node: Big5 and Shift-JIS Functions,  Next: Predefined Coding Systems,  Prev: Detection of Textual Encoding,  Up: Coding Systems
+
+Big5 and Shift-JIS Functions
+----------------------------
+
+These are special functions for working with the non-standard Shift-JIS
+and Big5 encodings.
+
+ - Function: decode-shift-jis-char code
+     This function decodes a JIS X 0208 character of Shift-JIS
+     coding-system.  CODE is the character code in Shift-JIS as a cons
+     of type bytes.  The corresponding character is returned.
+
+ - Function: encode-shift-jis-char character
+     This function encodes a JIS X 0208 character CHARACTER to
+     SHIFT-JIS coding-system.  The corresponding character code in
+     SHIFT-JIS is returned as a cons of two bytes.
+
+ - Function: decode-big5-char code
+     This function decodes a Big5 character CODE of BIG5 coding-system.
+     CODE is the character code in BIG5.  The corresponding character
+     is returned.
+
+ - Function: encode-big5-char character
+     This function encodes the Big5 character CHARACTER to BIG5
+     coding-system.  The corresponding character code in Big5 is
+     returned.
+
+\1f
+File: lispref.info,  Node: Predefined Coding Systems,  Prev: Big5 and Shift-JIS Functions,  Up: Coding Systems
+
+Coding Systems Implemented
+--------------------------
+
+MULE initializes most of the commonly used coding systems at XEmacs's
+startup.  A few others are initialized only when the relevant language
+environment is selected and support libraries are loaded.  (NB: The
+following list is based on XEmacs 21.2.19, the development branch at the
+time of writing.  The list may be somewhat different for other
+versions.  Recent versions of GNU Emacs 20 implement a few more rare
+coding systems; work is being done to port these to XEmacs.)
+
+   Unfortunately, there is not a consistent naming convention for
+character sets, and for practical purposes coding systems often take
+their name from their principal character sets (ASCII, KOI8-R, Shift
+JIS).  Others take their names from the coding system (ISO-2022-JP,
+EUC-KR), and a few from their non-text usages (internal, binary).  To
+provide for this, and for the fact that many coding systems have
+several common names, an aliasing system is provided.  Finally, some
+effort has been made to use names that are registered as MIME charsets
+(this is why the name 'shift_jis contains that un-Lisp-y underscore).
+
+   There is a systematic naming convention regarding end-of-line (EOL)
+conventions for different systems.  A coding system whose name ends in
+"-unix" forces the assumptions that lines are broken by newlines (0x0A).
+A coding system whose name ends in "-mac" forces the assumptions that
+lines are broken by ASCII CRs (0x0D).  A coding system whose name ends
+in "-dos" forces the assumptions that lines are broken by CRLF sequences
+(0x0D 0x0A).  These subsidiary coding systems are automatically derived
+from a base coding system.  Use of the base coding system implies
+autodetection of the text file convention.  (The fact that the -unix,
+-mac, and -dos are derived from a base system results in them showing up
+as "aliases" in `list-coding-systems'.)  These subsidiaries have a
+consistent modeline indicator as well.  "-dos" coding systems have ":T"
+appended to their modeline indicator, while "-mac" coding systems have
+":t" appended (eg, "ISO8:t" for iso-2022-8-mac).
+
+   In the following table, each coding system is given with its mode
+line indicator in parentheses.  Non-textual coding systems are listed
+first, followed by textual coding systems and their aliases. (The
+coding system subsidiary modeline indicators ":T" and ":t" will be
+omitted from the table of coding systems.)
+
+   ### SJT 1999-08-23 Maybe should order these by language?  Definitely
+need language usage for the ISO-8859 family.
+
+   Note that although true coding system aliases have been implemented
+for XEmacs 21.2, the coding system initialization has not yet been
+converted as of 21.2.19.  So coding systems described as aliases have
+the same properties as the aliased coding system, but will not be equal
+as Lisp objects.
+
+`automatic-conversion'
+`undecided'
+`undecided-dos'
+`undecided-mac'
+`undecided-unix'
+     Modeline indicator: `Auto'.  A type `undecided' coding system.
+     Attempts to determine an appropriate coding system from file
+     contents or the environment.
+
+`raw-text'
+`no-conversion'
+`raw-text-dos'
+`raw-text-mac'
+`raw-text-unix'
+`no-conversion-dos'
+`no-conversion-mac'
+`no-conversion-unix'
+     Modeline indicator: `Raw'.  A type `no-conversion' coding system,
+     which converts only line-break-codes.  An implementation quirk
+     means that this coding system is also used for ISO8859-1.
+
+`binary'
+     Modeline indicator: `Binary'.  A type `no-conversion' coding
+     system which does no character coding or EOL conversions.  An
+     alias for `raw-text-unix'.
+
+`alternativnyj'
+`alternativnyj-dos'
+`alternativnyj-mac'
+`alternativnyj-unix'
+     Modeline indicator: `Cy.Alt'.  A type `ccl' coding system used for
+     Alternativnyj, an encoding of the Cyrillic alphabet.
+
+`big5'
+`big5-dos'
+`big5-mac'
+`big5-unix'
+     Modeline indicator: `Zh/Big5'.  A type `big5' coding system used
+     for BIG5, the most common encoding of traditional Chinese as used
+     in Taiwan.
+
+`cn-gb-2312'
+`cn-gb-2312-dos'
+`cn-gb-2312-mac'
+`cn-gb-2312-unix'
+     Modeline indicator: `Zh-GB/EUC'.  A type `iso2022' coding system
+     used for simplified Chinese (as used in the People's Republic of
+     China), with the `ascii' (G0), `chinese-gb2312' (G1), and `sisheng'
+     (G2) character sets initially designated.  Chinese EUC (Extended
+     Unix Code).
+
+`ctext-hebrew'
+`ctext-hebrew-dos'
+`ctext-hebrew-mac'
+`ctext-hebrew-unix'
+     Modeline indicator: `CText/Hbrw'.  A type `iso2022' coding system
+     with the `ascii' (G0) and `hebrew-iso8859-8' (G1) character sets
+     initially designated for Hebrew.
+
+`ctext'
+`ctext-dos'
+`ctext-mac'
+`ctext-unix'
+     Modeline indicator: `CText'.  A type `iso2022' 8-bit coding system
+     with the `ascii' (G0) and `latin-iso8859-1' (G1) character sets
+     initially designated.  X11 Compound Text Encoding.  Often
+     mistakenly recognized instead of EUC encodings; usual cause is
+     inappropriate setting of `coding-priority-list'.
+
+`escape-quoted'
+     Modeline indicator: `ESC/Quot'.  A type `iso2022' 8-bit coding
+     system with the `ascii' (G0) and `latin-iso8859-1' (G1) character
+     sets initially designated and escape quoting.  Unix EOL conversion
+     (ie, no conversion).  It is used for .ELC files.
+
+`euc-jp'
+`euc-jp-dos'
+`euc-jp-mac'
+`euc-jp-unix'
+     Modeline indicator: `Ja/EUC'.  A type `iso2022' 8-bit coding system
+     with `ascii' (G0), `japanese-jisx0208' (G1), `katakana-jisx0201'
+     (G2), and `japanese-jisx0212' (G3) initially designated.  Japanese
+     EUC (Extended Unix Code).
+
+`euc-kr'
+`euc-kr-dos'
+`euc-kr-mac'
+`euc-kr-unix'
+     Modeline indicator: `ko/EUC'.  A type `iso2022' 8-bit coding system
+     with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
+     Korean EUC (Extended Unix Code).
+
+`hz-gb-2312'
+     Modeline indicator: `Zh-GB/Hz'.  A type `no-conversion' coding
+     system with Unix EOL convention (ie, no conversion) using
+     post-read-decode and pre-write-encode functions to translate the
+     Hz/ZW coding system used for Chinese.
+
+`iso-2022-7bit'
+`iso-2022-7bit-unix'
+`iso-2022-7bit-dos'
+`iso-2022-7bit-mac'
+`iso-2022-7'
+     Modeline indicator: `ISO7'.  A type `iso2022' 7-bit coding system
+     with `ascii' (G0) initially designated.  Other character sets must
+     be explicitly designated to be used.
+
+`iso-2022-7bit-ss2'
+`iso-2022-7bit-ss2-dos'
+`iso-2022-7bit-ss2-mac'
+`iso-2022-7bit-ss2-unix'
+     Modeline indicator: `ISO7/SS'.  A type `iso2022' 7-bit coding
+     system with `ascii' (G0) initially designated.  Other character
+     sets must be explicitly designated to be used.  SS2 is used to
+     invoke a 96-charset, one character at a time.
+
+`iso-2022-8'
+`iso-2022-8-dos'
+`iso-2022-8-mac'
+`iso-2022-8-unix'
+     Modeline indicator: `ISO8'.  A type `iso2022' 8-bit coding system
+     with `ascii' (G0) and `latin-iso8859-1' (G1) initially designated.
+     Other character sets must be explicitly designated to be used.
+     No single-shift or locking-shift.
+
+`iso-2022-8bit-ss2'
+`iso-2022-8bit-ss2-dos'
+`iso-2022-8bit-ss2-mac'
+`iso-2022-8bit-ss2-unix'
+     Modeline indicator: `ISO8/SS'.  A type `iso2022' 8-bit coding
+     system with `ascii' (G0) and `latin-iso8859-1' (G1) initially
+     designated.  Other character sets must be explicitly designated to
+     be used.  SS2 is used to invoke a 96-charset, one character at a
+     time.
+
+`iso-2022-int-1'
+`iso-2022-int-1-dos'
+`iso-2022-int-1-mac'
+`iso-2022-int-1-unix'
+     Modeline indicator: `INT-1'.  A type `iso2022' 7-bit coding system
+     with `ascii' (G0) and `korean-ksc5601' (G1) initially designated.
+     ISO-2022-INT-1.
+
+`iso-2022-jp-1978-irv'
+`iso-2022-jp-1978-irv-dos'
+`iso-2022-jp-1978-irv-mac'
+`iso-2022-jp-1978-irv-unix'
+     Modeline indicator: `Ja-78/7bit'.  A type `iso2022' 7-bit coding
+     system.  For compatibility with old Japanese terminals; if you
+     need to know, look at the source.
+
+`iso-2022-jp'
+`iso-2022-jp-2 (ISO7/SS)'
+`iso-2022-jp-dos'
+`iso-2022-jp-mac'
+`iso-2022-jp-unix'
+`iso-2022-jp-2-dos'
+`iso-2022-jp-2-mac'
+`iso-2022-jp-2-unix'
+     Modeline indicator: `MULE/7bit'.  A type `iso2022' 7-bit coding
+     system with `ascii' (G0) initially designated, and complex
+     specifications to insure backward compatibility with old Japanese
+     systems.  Used for communication with mail and news in Japan.  The
+     "-2" versions also use SS2 to invoke a 96-charset one character at
+     a time.
+
+`iso-2022-kr'
+     Modeline indicator: `Ko/7bit'  A type `iso2022' 7-bit coding
+     system with `ascii' (G0) and `korean-ksc5601' (G1) initially
+     designated.  Used for e-mail in Korea.
+
+`iso-2022-lock'
+`iso-2022-lock-dos'
+`iso-2022-lock-mac'
+`iso-2022-lock-unix'
+     Modeline indicator: `ISO7/Lock'.  A type `iso2022' 7-bit coding
+     system with `ascii' (G0) initially designated, using Locking-Shift
+     to invoke a 96-charset.
+
+`iso-8859-1'
+`iso-8859-1-dos'
+`iso-8859-1-mac'
+`iso-8859-1-unix'
+     Due to implementation, this is not a type `iso2022' coding system,
+     but rather an alias for the `raw-text' coding system.
+
+`iso-8859-2'
+`iso-8859-2-dos'
+`iso-8859-2-mac'
+`iso-8859-2-unix'
+     Modeline indicator: `MIME/Ltn-2'.  A type `iso2022' coding system
+     with `ascii' (G0) and `latin-iso8859-2' (G1) initially invoked.
+
+`iso-8859-3'
+`iso-8859-3-dos'
+`iso-8859-3-mac'
+`iso-8859-3-unix'
+     Modeline indicator: `MIME/Ltn-3'.  A type `iso2022' coding system
+     with `ascii' (G0) and `latin-iso8859-3' (G1) initially invoked.
+
+`iso-8859-4'
+`iso-8859-4-dos'
+`iso-8859-4-mac'
+`iso-8859-4-unix'
+     Modeline indicator: `MIME/Ltn-4'.  A type `iso2022' coding system
+     with `ascii' (G0) and `latin-iso8859-4' (G1) initially invoked.
+
+`iso-8859-5'
+`iso-8859-5-dos'
+`iso-8859-5-mac'
+`iso-8859-5-unix'
+     Modeline indicator: `ISO8/Cyr'.  A type `iso2022' coding system
+     with `ascii' (G0) and `cyrillic-iso8859-5' (G1) initially invoked.
+
+`iso-8859-7'
+`iso-8859-7-dos'
+`iso-8859-7-mac'
+`iso-8859-7-unix'
+     Modeline indicator: `Grk'.  A type `iso2022' coding system with
+     `ascii' (G0) and `greek-iso8859-7' (G1) initially invoked.
+
+`iso-8859-8'
+`iso-8859-8-dos'
+`iso-8859-8-mac'
+`iso-8859-8-unix'
+     Modeline indicator: `MIME/Hbrw'.  A type `iso2022' coding system
+     with `ascii' (G0) and `hebrew-iso8859-8' (G1) initially invoked.
+
+`iso-8859-9'
+`iso-8859-9-dos'
+`iso-8859-9-mac'
+`iso-8859-9-unix'
+     Modeline indicator: `MIME/Ltn-5'.  A type `iso2022' coding system
+     with `ascii' (G0) and `latin-iso8859-9' (G1) initially invoked.
+
+`koi8-r'
+`koi8-r-dos'
+`koi8-r-mac'
+`koi8-r-unix'
+     Modeline indicator: `KOI8'.  A type `ccl' coding-system used for
+     KOI8-R, an encoding of the Cyrillic alphabet.
+
+`shift_jis'
+`shift_jis-dos'
+`shift_jis-mac'
+`shift_jis-unix'
+     Modeline indicator: `Ja/SJIS'.  A type `shift-jis' coding-system
+     implementing the Shift-JIS encoding for Japanese.  The underscore
+     is to conform to the MIME charset implementing this encoding.
+
+`tis-620'
+`tis-620-dos'
+`tis-620-mac'
+`tis-620-unix'
+     Modeline indicator: `TIS620'.  A type `ccl' encoding for Thai.  The
+     external encoding is defined by TIS620, the internal encoding is
+     peculiar to MULE, and called `thai-xtis'.
+
+`viqr'
+     Modeline indicator: `VIQR'.  A type `no-conversion' coding system
+     with Unix EOL convention (ie, no conversion) using
+     post-read-decode and pre-write-encode functions to translate the
+     VIQR coding system for Vietnamese.
+
+`viscii'
+`viscii-dos'
+`viscii-mac'
+`viscii-unix'
+     Modeline indicator: `VISCII'.  A type `ccl' coding-system used for
+     VISCII 1.1 for Vietnamese.  Differs slightly from VSCII; VISCII is
+     given priority by XEmacs.
+
+`vscii'
+`vscii-dos'
+`vscii-mac'
+`vscii-unix'
+     Modeline indicator: `VSCII'.  A type `ccl' coding-system used for
+     VSCII 1.1 for Vietnamese.  Differs slightly from VISCII, which is
+     given priority by XEmacs.  Use `(prefer-coding-system
+     'vietnamese-vscii)' to give priority to VSCII.
+
+
+\1f
+File: lispref.info,  Node: CCL,  Next: Category Tables,  Prev: Coding Systems,  Up: MULE
+
+CCL
+===
+
+CCL (Code Conversion Language) is a simple structured programming
+language designed for character coding conversions.  A CCL program is
+compiled to CCL code (represented by a vector of integers) and executed
+by the CCL interpreter embedded in Emacs.  The CCL interpreter
+implements a virtual machine with 8 registers called `r0', ..., `r7', a
+number of control structures, and some I/O operators.  Take care when
+using registers `r0' (used in implicit "set" statements) and especially
+`r7' (used internally by several statements and operations, especially
+for multiple return values and I/O operations).
+
+   CCL is used for code conversion during process I/O and file I/O for
+non-ISO2022 coding systems.  (It is the only way for a user to specify a
+code conversion function.)  It is also used for calculating the code
+point of an X11 font from a character code.  However, since CCL is
+designed as a powerful programming language, it can be used for more
+generic calculation where efficiency is demanded.  A combination of
+three or more arithmetic operations can be calculated faster by CCL than
+by Emacs Lisp.
+
+   *Warning:*  The code in `src/mule-ccl.c' and
+`$packages/lisp/mule-base/mule-ccl.el' is the definitive description of
+CCL's semantics.  The previous version of this section contained
+several typos and obsolete names left from earlier versions of MULE,
+and many may remain.  (I am not an experienced CCL programmer; the few
+who know CCL well find writing English painful.)
+
+   A CCL program transforms an input data stream into an output data
+stream.  The input stream, held in a buffer of constant bytes, is left
+unchanged.  The buffer may be filled by an external input operation,
+taken from an Emacs buffer, or taken from a Lisp string.  The output
+buffer is a dynamic array of bytes, which can be written by an external
+output operation, inserted into an Emacs buffer, or returned as a Lisp
+string.
+
+   A CCL program is a (Lisp) list containing two or three members.  The
+first member is the "buffer magnification", which indicates the
+required minimum size of the output buffer as a multiple of the input
+buffer.  It is followed by the "main block" which executes while there
+is input remaining, and an optional "EOF block" which is executed when
+the input is exhausted.  Both the main block and the EOF block are CCL
+blocks.
+
+   A "CCL block" is either a CCL statement or list of CCL statements.
+A "CCL statement" is either a "set statement" (either an integer or an
+"assignment", which is a list of a register to receive the assignment,
+an assignment operator, and an expression) or a "control statement" (a
+list starting with a keyword, whose allowable syntax depends on the
+keyword).
+
+* Menu:
+
+* CCL Syntax::          CCL program syntax in BNF notation.
+* CCL Statements::      Semantics of CCL statements.
+* CCL Expressions::     Operators and expressions in CCL.
+* Calling CCL::         Running CCL programs.
+* CCL Examples::        The encoding functions for Big5 and KOI-8.
+
+\1f
+File: lispref.info,  Node: CCL Syntax,  Next: CCL Statements,  Up: CCL
+
+CCL Syntax
+----------
+
+The full syntax of a CCL program in BNF notation:
+
+CCL_PROGRAM :=
+        (BUFFER_MAGNIFICATION
+         CCL_MAIN_BLOCK
+         [ CCL_EOF_BLOCK ])
+
+BUFFER_MAGNIFICATION := integer
+CCL_MAIN_BLOCK := CCL_BLOCK
+CCL_EOF_BLOCK := CCL_BLOCK
+
+CCL_BLOCK :=
+        STATEMENT | (STATEMENT [STATEMENT ...])
+STATEMENT :=
+        SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE
+        | CALL | END
+
+SET :=
+        (REG = EXPRESSION)
+        | (REG ASSIGNMENT_OPERATOR EXPRESSION)
+        | integer
+
+EXPRESSION := ARG | (EXPRESSION OPERATOR 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 | integer | string])
+        | (write-read-repeat REG [integer | ARRAY])
+READ :=
+        (read REG ...)
+        | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK)
+        | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
+WRITE :=
+        (write REG ...)
+        | (write EXPRESSION)
+        | (write integer) | (write string) | (write REG ARRAY)
+        | string
+CALL := (call ccl-program-name)
+END := (end)
+
+REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
+ARG := REG | integer
+OPERATOR :=
+        + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
+        | < | > | == | <= | >= | != | de-sjis | en-sjis
+ASSIGNMENT_OPERATOR :=
+        += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
+ARRAY := '[' integer ... ']'

 
 \1f
 
 \1f

-File: lispref.info,  Node: Processing of Errors,  Next: Handling Errors,  Prev: Signaling Errors,  Up: Errors
-
-How XEmacs Processes Errors
-...........................
-
-   When an error is signaled, `signal' searches for an active "handler"
-for the error.  A handler is a sequence of Lisp expressions designated
-to be executed if an error happens in part of the Lisp program.  If the
-error has an applicable handler, the handler is executed, and control
-resumes following the handler.  The handler executes in the environment
-of the `condition-case' that established it; all functions called
-within that `condition-case' have already been exited, and the handler
-cannot return to them.
-
-   If there is no applicable handler for the error, the current command
-is terminated and control returns to the editor command loop, because
-the command loop has an implicit handler for all kinds of errors.  The
-command loop's handler uses the error symbol and associated data to
-print an error message.
-
-   Errors in command loop are processed using the `command-error'
-function, which takes care of some necessary cleanup, and prints a
-formatted error message to the echo area.  The functions that do the
-formatting are explained below.
-
- - Function: display-error error-object stream
-     This function displays ERROR-OBJECT on STREAM.  ERROR-OBJECT is a
-     cons of error type, a symbol, and error arguments, a list.  If the
-     error type symbol of one of its error condition superclasses has
-     an `display-error' property, that function is invoked for printing
-     the actual error message.  Otherwise, the error is printed as
-     `Error: arg1, arg2, ...'.
-
- - Function: error-message-string error-object
-     This function converts ERROR-OBJECT to an error message string,
-     and returns it.  The message is equivalent to the one that would be
-     printed by `display-error', except that it is conveniently returned
-     in string form.
-
-   An error that has no explicit handler may call the Lisp debugger.
-The debugger is enabled if the variable `debug-on-error' (*note Error
-Debugging::) is non-`nil'.  Unlike error handlers, the debugger runs in
-the environment of the error, so that you can examine values of
-variables precisely as they were at the time of the error.
+File: lispref.info,  Node: CCL Statements,  Next: CCL Expressions,  Prev: CCL Syntax,  Up: CCL
+
+CCL Statements
+--------------
+
+The Emacs Code Conversion Language provides the following statement
+types: "set", "if", "branch", "loop", "repeat", "break", "read",
+"write", "call", and "end".
+
+Set statement:
+==============
+
+The "set" statement has three variants with the syntaxes `(REG =
+EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'.
+The assignment operator variation of the "set" statement works the same
+way as the corresponding C expression statement does.  The assignment
+operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=',
+and `>>=', and they have the same meanings as in C.  A "naked integer"
+INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'.
+
+I/O statements:
+===============
+
+The "read" statement takes one or more registers as arguments.  It
+reads one byte (a C char) from the input into each register in turn.
+
+   The "write" takes several forms.  In the form `(write REG ...)' it
+takes one or more registers as arguments and writes each in turn to the
+output.  The integer in a register (interpreted as an Emchar) is
+encoded to multibyte form (ie, Bufbytes) and written to the current
+output buffer.  If it is less than 256, it is written as is.  The forms
+`(write EXPRESSION)' and `(write INTEGER)' are treated analogously.
+The form `(write STRING)' writes the constant string to the output.  A
+"naked string" `STRING' is equivalent to the statement `(write
+STRING)'.  The form `(write REG ARRAY)' writes the REGth element of the
+ARRAY to the output.
+
+Conditional statements:
+=======================
+
+The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional
+SECOND CCL BLOCK as arguments.  If the EXPRESSION evaluates to
+non-zero, the first CCL BLOCK is executed.  Otherwise, if there is a
+SECOND CCL BLOCK, it is executed.
+
+   The "read-if" variant of the "if" statement takes an EXPRESSION, a
+CCL BLOCK, and an optional SECOND CCL BLOCK as arguments.  The
+EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is
+a register or an integer).  The `read-if' statement first reads from
+the input into the first register operand in the EXPRESSION, then
+conditionally executes a CCL block just as the `if' statement does.
+
+   The "branch" statement takes an EXPRESSION and one or more CCL
+blocks as arguments.  The CCL blocks are treated as a zero-indexed
+array, and the `branch' statement uses the EXPRESSION as the index of
+the CCL block to execute.  Null CCL blocks may be used as no-ops,
+continuing execution with the statement following the `branch'
+statement in the containing CCL block.  Out-of-range values for the
+EXPRESSION are also treated as no-ops.
+
+   The "read-branch" variant of the "branch" statement takes an
+REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments.
+The `read-branch' statement first reads from the input into the
+REGISTER, then conditionally executes a CCL block just as the `branch'
+statement does.
+
+Loop control statements:
+========================
+
+The "loop" statement creates a block with an implied jump from the end
+of the block back to its head.  The loop is exited on a `break'
+statement, and continued without executing the tail by a `repeat'
+statement.
+
+   The "break" statement, written `(break)', terminates the current
+loop and continues with the next statement in the current block.
+
+   The "repeat" statement has three variants, `repeat', `write-repeat',
+and `write-read-repeat'.  Each continues the current loop from its
+head, possibly after performing I/O.  `repeat' takes no arguments and
+does no I/O before jumping.  `write-repeat' takes a single argument (a
+register, an integer, or a string), writes it to the output, then jumps.
+`write-read-repeat' takes one or two arguments.  The first must be a
+register.  The second may be an integer or an array; if absent, it is
+implicitly set to the first (register) argument.  `write-read-repeat'
+writes its second argument to the output, then reads from the input
+into the register, and finally jumps.  See the `write' and `read'
+statements for the semantics of the I/O operations for each type of
+argument.
+
+Other control statements:
+=========================
+
+The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a CCL
+program as a subroutine.  It does not return a value to the caller, but
+can modify the register status.
+
+   The "end" statement, written `(end)', terminates the CCL program
+successfully, and returns to caller (which may be a CCL program).  It
+does not alter the status of the registers.
+
+\1f
+File: lispref.info,  Node: CCL Expressions,  Next: Calling CCL,  Prev: CCL Statements,  Up: CCL
+
+CCL Expressions
+---------------
+
+CCL, unlike Lisp, uses infix expressions.  The simplest CCL expressions
+consist of a single OPERAND, either a register (one of `r0', ..., `r0')
+or an integer.  Complex expressions are lists of the form `( EXPRESSION
+OPERATOR OPERAND )'.  Unlike C, assignments are not expressions.
+
+   In the following table, X is the target resister for a "set".  In
+subexpressions, this is implicitly `r7'.  This means that `>8', `//',
+`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since
+they return parts of their values in `r7'.  Y may be an expression,
+register, or integer, while Z must be a register or an integer.
+
+Name             Operator   Code   C-like Description
+CCL_PLUS         `+'        0x00   X = Y + Z
+CCL_MINUS        `-'        0x01   X = Y - Z
+CCL_MUL          `*'        0x02   X = Y * Z
+CCL_DIV          `/'        0x03   X = Y / Z
+CCL_MOD          `%'        0x04   X = Y % Z
+CCL_AND          `&'        0x05   X = Y & Z
+CCL_OR           `|'        0x06   X = Y | Z
+CCL_XOR          `^'        0x07   X = Y ^ Z
+CCL_LSH          `<<'       0x08   X = Y << Z
+CCL_RSH          `>>'       0x09   X = Y >> Z
+CCL_LSH8         `<8'       0x0A   X = (Y << 8) | Z
+CCL_RSH8         `>8'       0x0B   X = Y >> 8, r[7] = Y & 0xFF
+CCL_DIVMOD       `//'       0x0C   X = Y / Z, r[7] = Y % Z
+CCL_LS           `<'        0x10   X = (X < Y)
+CCL_GT           `>'        0x11   X = (X > Y)
+CCL_EQ           `=='       0x12   X = (X == Y)
+CCL_LE           `<='       0x13   X = (X <= Y)
+CCL_GE           `>='       0x14   X = (X >= Y)
+CCL_NE           `!='       0x15   X = (X != Y)
+CCL_ENCODE_SJIS  `en-sjis'  0x16   X = HIGHER_BYTE (SJIS (Y, Z))
+                                   r[7] = LOWER_BYTE (SJIS (Y, Z)
+CCL_DECODE_SJIS  `de-sjis'  0x17   X = HIGHER_BYTE (DE-SJIS (Y, Z))
+                                   r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
+
+   The CCL operators are as in C, with the addition of CCL_LSH8,
+CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS.  The
+CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes
+as the high and low bytes of a two-byte character code.  (SJIS stands
+for Shift JIS, an encoding of Japanese characters used by Microsoft.
+CCL_ENCODE_SJIS is a complicated transformation of the Japanese
+standard JIS encoding to Shift JIS.  CCL_DECODE_SJIS is its inverse.)
+It is somewhat odd to represent the SJIS operations in infix form.
+
+\1f
+File: lispref.info,  Node: Calling CCL,  Next: CCL Examples,  Prev: CCL Expressions,  Up: CCL
+
+Calling CCL
+-----------
+
+CCL programs are called automatically during Emacs buffer I/O when the
+external representation has a coding system type of `shift-jis',
+`big5', or `ccl'.  The program is specified by the coding system (*note
+Coding Systems::).  You can also call CCL programs from other CCL
+programs, and from Lisp using these functions:
+
+ - Function: ccl-execute ccl-program status
+     Execute CCL-PROGRAM with registers initialized by STATUS.
+     CCL-PROGRAM is a vector of compiled CCL code created by
+     `ccl-compile'.  It is an error for the program to try to execute a
+     CCL I/O command.  STATUS must be a vector of nine values,
+     specifying the initial value for the R0, R1 .. R7 registers and
+     for the instruction counter IC.  A `nil' value for a register
+     initializer causes the register to be set to 0.  A `nil' value for
+     the IC initializer causes execution to start at the beginning of
+     the program.  When the program is done, STATUS is modified (by
+     side-effect) to contain the ending values for the corresponding
+     registers and IC.
+
+ - Function: ccl-execute-on-string ccl-program status string &optional
+          continue
+     Execute CCL-PROGRAM with initial STATUS on STRING.  CCL-PROGRAM is
+     a vector of compiled CCL code created by `ccl-compile'.  STATUS
+     must be a vector of nine values, specifying the initial value for
+     the R0, R1 .. R7 registers and for the instruction counter IC.  A
+     `nil' value for a register initializer causes the register to be
+     set to 0.  A `nil' value for the IC initializer causes execution
+     to start at the beginning of the program.  An optional fourth
+     argument CONTINUE, if non-`nil', causes the IC to remain on the
+     unsatisfied read operation if the program terminates due to
+     exhaustion of the input buffer.  Otherwise the IC is set to the end
+     of the program.  When the program is done, STATUS is modified (by
+     side-effect) to contain the ending values for the corresponding
+     registers and IC.  Returns the resulting string.
+
+   To call a CCL program from another CCL program, it must first be
+registered:
+
+ - Function: register-ccl-program name ccl-program
+     Register NAME for CCL program CCL-PROGRAM in `ccl-program-table'.
+     CCL-PROGRAM should be the compiled form of a CCL program, or
+     `nil'.  Return index number of the registered CCL program.
+
+   Information about the processor time used by the CCL interpreter can
+be obtained using these functions:
+
+ - Function: ccl-elapsed-time
+     Returns the elapsed processor time of the CCL interpreter as cons
+     of user and system time, as floating point numbers measured in
+     seconds.  If only one overall value can be determined, the return
+     value will be a cons of that value and 0.
+
+ - Function: ccl-reset-elapsed-time
+     Resets the CCL interpreter's internal elapsed time registers.
+
+\1f
+File: lispref.info,  Node: CCL Examples,  Prev: Calling CCL,  Up: CCL
+
+CCL Examples
+------------
+
+This section is not yet written.
+
+\1f
+File: lispref.info,  Node: Category Tables,  Prev: CCL,  Up: MULE
+
+Category Tables
+===============
+
+A category table is a type of char table used for keeping track of
+categories.  Categories are used for classifying characters for use in
+regexps--you can refer to a category rather than having to use a
+complicated [] expression (and category lookups are significantly
+faster).
+
+   There are 95 different categories available, one for each printable
+character (including space) in the ASCII charset.  Each category is
+designated by one such character, called a "category designator".  They
+are specified in a regexp using the syntax `\cX', where X is a category
+designator. (This is not yet implemented.)
+
+   A category table specifies, for each character, the categories that
+the character is in.  Note that a character can be in more than one
+category.  More specifically, a category table maps from a character to
+either the value `nil' (meaning the character is in no categories) or a
+95-element bit vector, specifying for each of the 95 categories whether
+the character is in that category.
+
+   Special Lisp functions are provided that abstract this, so you do not
+have to directly manipulate bit vectors.
+
+ - Function: category-table-p object
+     This function returns `t' if OBJECT is a category table.
+
+ - Function: category-table &optional buffer
+     This function returns the current category table.  This is the one
+     specified by the current buffer, or by BUFFER if it is non-`nil'.
+
+ - Function: standard-category-table
+     This function returns the standard category table.  This is the
+     one used for new buffers.
+
+ - Function: copy-category-table &optional category-table
+     This function returns a new category table which is a copy of
+     CATEGORY-TABLE, which defaults to the standard category table.
+
+ - Function: set-category-table category-table &optional buffer
+     This function selects CATEGORY-TABLE as the new category table for
+     BUFFER.  BUFFER defaults to the current buffer if omitted.
+
+ - Function: category-designator-p object
+     This function returns `t' if OBJECT is a category designator (a
+     char in the range `' '' to `'~'').
+
+ - Function: category-table-value-p object
+     This function returns `t' if OBJECT is a category table value.
+     Valid values are `nil' or a bit vector of size 95.
+
+\1f
+File: lispref.info,  Node: Tips,  Next: Building XEmacs and Object Allocation,  Prev: MULE,  Up: Top
+
+Tips and Standards
+******************
+
+This chapter describes no additional features of XEmacs Lisp.  Instead
+it gives advice on making effective use of the features described in
+the previous chapters.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Style Tips,  Next: Compilation Tips,  Up: Tips
+
+Writing Clean Lisp Programs
+===========================
+
+Here are some tips for avoiding common errors in writing Lisp code
+intended for widespread use:
+
+   * Since all global variables share the same name space, and all
+     functions share another name space, you should choose a short word
+     to distinguish your program from other Lisp programs.  Then take
+     care to begin the names of all global variables, constants, and
+     functions with the chosen prefix.  This helps avoid name conflicts.
+
+     This recommendation applies even to names for traditional Lisp
+     primitives that are not primitives in XEmacs Lisp--even to `cadr'.
+     Believe it or not, there is more than one plausible way to define
+     `cadr'.  Play it safe; append your name prefix to produce a name
+     like `foo-cadr' or `mylib-cadr' instead.
+
+     If you write a function that you think ought to be added to Emacs
+     under a certain name, such as `twiddle-files', don't call it by
+     that name in your program.  Call it `mylib-twiddle-files' in your
+     program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu'
+     suggesting we add it to Emacs.  If and when we do, we can change
+     the name easily enough.
+
+     If one prefix is insufficient, your package may use two or three
+     alternative common prefixes, so long as they make sense.
+
+     Separate the prefix from the rest of the symbol name with a hyphen,
+     `-'.  This will be consistent with XEmacs itself and with most
+     Emacs Lisp programs.
+
+   * It is often useful to put a call to `provide' in each separate
+     library program, at least if there is more than one entry point to
+     the program.
+
+   * If a file requires certain other library programs to be loaded
+     beforehand, then the comments at the beginning of the file should
+     say so.  Also, use `require' to make sure they are loaded.
+
+   * If one file FOO uses a macro defined in another file BAR, FOO
+     should contain this expression before the first use of the macro:
+
+          (eval-when-compile (require 'BAR))
+
+     (And BAR should contain `(provide 'BAR)', to make the `require'
+     work.)  This will cause BAR to be loaded when you byte-compile
+     FOO.  Otherwise, you risk compiling FOO without the necessary
+     macro loaded, and that would produce compiled code that won't work
+     right.  *Note Compiling Macros::.
+
+     Using `eval-when-compile' avoids loading BAR when the compiled
+     version of FOO is _used_.
+
+   * If you define a major mode, make sure to run a hook variable using
+     `run-hooks', just as the existing major modes do.  *Note Hooks::.
+
+   * If the purpose of a function is to tell you whether a certain
+     condition is true or false, give the function a name that ends in
+     `p'.  If the name is one word, add just `p'; if the name is
+     multiple words, add `-p'.  Examples are `framep' and
+     `frame-live-p'.
+
+   * If a user option variable records a true-or-false condition, give
+     it a name that ends in `-flag'.
+
+   * Please do not define `C-c LETTER' as a key in your major modes.
+     These sequences are reserved for users; they are the *only*
+     sequences reserved for users, so we cannot do without them.
+
+     Instead, define sequences consisting of `C-c' followed by a
+     non-letter.  These sequences are reserved for major modes.
+
+     Changing all the major modes in Emacs 18 so they would follow this
+     convention was a lot of work.  Abandoning this convention would
+     make that work go to waste, and inconvenience users.
+
+   * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:'
+     or `;' are also reserved for major modes.
+
+   * Sequences consisting of `C-c' followed by any other punctuation
+     character are allocated for minor modes.  Using them in a major
+     mode is not absolutely prohibited, but if you do that, the major
+     mode binding may be shadowed from time to time by minor modes.
+
+   * You should not bind `C-h' following any prefix character (including
+     `C-c').  If you don't bind `C-h', it is automatically available as
+     a help character for listing the subcommands of the prefix
+     character.
+
+   * You should not bind a key sequence ending in <ESC> except following
+     another <ESC>.  (That is, it is ok to bind a sequence ending in
+     `<ESC> <ESC>'.)
+
+     The reason for this rule is that a non-prefix binding for <ESC> in
+     any context prevents recognition of escape sequences as function
+     keys in that context.
+
+   * Applications should not bind mouse events based on button 1 with
+     the shift key held down.  These events include `S-mouse-1',
+     `M-S-mouse-1', `C-S-mouse-1', and so on.  They are reserved for
+     users.
+
+   * Modes should redefine `mouse-2' as a command to follow some sort of
+     reference in the text of a buffer, if users usually would not want
+     to alter the text in that buffer by hand.  Modes such as Dired,
+     Info, Compilation, and Occur redefine it in this way.
+
+   * When a package provides a modification of ordinary Emacs behavior,
+     it is good to include a command to enable and disable the feature,
+     Provide a command named `WHATEVER-mode' which turns the feature on
+     or off, and make it autoload (*note Autoload::).  Design the
+     package so that simply loading it has no visible effect--that
+     should not enable the feature.  Users will request the feature by
+     invoking the command.
+
+   * It is a bad idea to define aliases for the Emacs primitives.  Use
+     the standard names instead.
+
+   * Redefining an Emacs primitive is an even worse idea.  It may do
+     the right thing for a particular program, but there is no telling
+     what other programs might break as a result.
+
+   * If a file does replace any of the functions or library programs of
+     standard XEmacs, prominent comments at the beginning of the file
+     should say which functions are replaced, and how the behavior of
+     the replacements differs from that of the originals.
+
+   * Please keep the names of your XEmacs Lisp source files to 13
+     characters or less.  This way, if the files are compiled, the
+     compiled files' names will be 14 characters or less, which is
+     short enough to fit on all kinds of Unix systems.
+
+   * Don't use `next-line' or `previous-line' in programs; nearly
+     always, `forward-line' is more convenient as well as more
+     predictable and robust.  *Note Text Lines::.
+
+   * Don't call functions that set the mark, unless setting the mark is
+     one of the intended features of your program.  The mark is a
+     user-level feature, so it is incorrect to change the mark except
+     to supply a value for the user's benefit.  *Note The Mark::.
+
+     In particular, don't use these functions:
+
+        * `beginning-of-buffer', `end-of-buffer'
+
+        * `replace-string', `replace-regexp'
+
+     If you just want to move point, or replace a certain string,
+     without any of the other features intended for interactive users,
+     you can replace these functions with one or two lines of simple
+     Lisp code.
+
+   * Use lists rather than vectors, except when there is a particular
+     reason to use a vector.  Lisp has more facilities for manipulating
+     lists than for vectors, and working with lists is usually more
+     convenient.
+
+     Vectors are advantageous for tables that are substantial in size
+     and are accessed in random order (not searched front to back),
+     provided there is no need to insert or delete elements (only lists
+     allow that).
+
+   * The recommended way to print a message in the echo area is with
+     the `message' function, not `princ'.  *Note The Echo Area::.
+
+   * When you encounter an error condition, call the function `error'
+     (or `signal').  The function `error' does not return.  *Note
+     Signaling Errors::.
+
+     Do not use `message', `throw', `sleep-for', or `beep' to report
+     errors.
+
+   * An error message should start with a capital letter but should not
+     end with a period.
+
+   * Try to avoid using recursive edits.  Instead, do what the Rmail `e'
+     command does: use a new local keymap that contains one command
+     defined to switch back to the old local keymap.  Or do what the
+     `edit-options' command does: switch to another buffer and let the
+     user switch back at will.  *Note Recursive Editing::.
+
+   * In some other systems there is a convention of choosing variable
+     names that begin and end with `*'.  We don't use that convention
+     in Emacs Lisp, so please don't use it in your programs.  (Emacs
+     uses such names only for program-generated buffers.)  The users
+     will find Emacs more coherent if all libraries use the same
+     conventions.
+
+   * Use names starting with a space for temporary buffers (*note
+     Buffer Names::), or at least call `buffer-disable-undo' on them.
+     Otherwise they may stay referenced by internal undo variable(s)
+     after getting killed.  If this happens before dumping (*note
+     Building XEmacs::), this may cause fatal error when portable
+     dumper is used.
+
+   * Indent each function with `C-M-q' (`indent-sexp') using the
+     default indentation parameters.
+
+   * Don't make a habit of putting close-parentheses on lines by
+     themselves; Lisp programmers find this disconcerting.  Once in a
+     while, when there is a sequence of many consecutive
+     close-parentheses, it may make sense to split them in one or two
+     significant places.
+
+   * Please put a copyright notice on the file if you give copies to
+     anyone.  Use the same lines that appear at the top of the Lisp
+     files in XEmacs itself.  If you have not signed papers to assign
+     the copyright to the Foundation, then place your name in the
+     copyright notice in place of the Foundation's name.
+
+\1f
+File: lispref.info,  Node: Compilation Tips,  Next: Documentation Tips,  Prev: Style Tips,  Up: Tips
+
+Tips for Making Compiled Code Fast
+==================================
+
+Here are ways of improving the execution speed of byte-compiled Lisp
+programs.
+
+   * Use the `profile' library to profile your program.  See the file
+     `profile.el' for instructions.
+
+   * Use iteration rather than recursion whenever possible.  Function
+     calls are slow in XEmacs Lisp even when a compiled function is
+     calling another compiled function.
+
+   * Using the primitive list-searching functions `memq', `member',
+     `assq', or `assoc' is even faster than explicit iteration.  It may
+     be worth rearranging a data structure so that one of these
+     primitive search functions can be used.
+
+   * Certain built-in functions are handled specially in byte-compiled
+     code, avoiding the need for an ordinary function call.  It is a
+     good idea to use these functions rather than alternatives.  To see
+     whether a function is handled specially by the compiler, examine
+     its `byte-compile' property.  If the property is non-`nil', then
+     the function is handled specially.
+
+     For example, the following input will show you that `aref' is
+     compiled specially (*note Array Functions::) while `elt' is not
+     (*note Sequence Functions::):
+
+          (get 'aref 'byte-compile)
+               => byte-compile-two-args
+          
+          (get 'elt 'byte-compile)
+               => nil
+
+   * If calling a small function accounts for a  substantial part of
+     your program's running time, make the function inline.  This
+     eliminates the function call overhead.  Since making a function
+     inline reduces the flexibility of changing the program, don't do
+     it unless it gives a noticeable speedup in something slow enough
+     that users care about the speed.  *Note Inline Functions::.
+
+\1f
+File: lispref.info,  Node: Documentation Tips,  Next: Comment Tips,  Prev: Compilation Tips,  Up: Tips
+
+Tips for Documentation Strings
+==============================
+
+Here are some tips for the writing of documentation strings.
+
+   * Every command, function, or variable intended for users to know
+     about should have a documentation string.
+
+   * An internal variable or subroutine of a Lisp program might as well
+     have a documentation string.  In earlier Emacs versions, you could
+     save space by using a comment instead of a documentation string,
+     but that is no longer the case.
+
+   * The first line of the documentation string should consist of one
+     or two complete sentences that stand on their own as a summary.
+     `M-x apropos' displays just the first line, and if it doesn't
+     stand on its own, the result looks bad.  In particular, start the
+     first line with a capital letter and end with a period.
+
+     The documentation string can have additional lines that expand on
+     the details of how to use the function or variable.  The
+     additional lines should be made up of complete sentences also, but
+     they may be filled if that looks good.
+
+   * For consistency, phrase the verb in the first sentence of a
+     documentation string as an infinitive with "to" omitted.  For
+     instance, use "Return the cons of A and B." in preference to
+     "Returns the cons of A and B."  Usually it looks good to do
+     likewise for the rest of the first paragraph.  Subsequent
+     paragraphs usually look better if they have proper subjects.
+
+   * Write documentation strings in the active voice, not the passive,
+     and in the present tense, not the future.  For instance, use
+     "Return a list containing A and B." instead of "A list containing
+     A and B will be returned."
+
+   * Avoid using the word "cause" (or its equivalents) unnecessarily.
+     Instead of, "Cause Emacs to display text in boldface," write just
+     "Display text in boldface."
+
+   * Do not start or end a documentation string with whitespace.
+
+   * Format the documentation string so that it fits in an Emacs window
+     on an 80-column screen.  It is a good idea for most lines to be no
+     wider than 60 characters.  The first line can be wider if
+     necessary to fit the information that ought to be there.
+
+     However, rather than simply filling the entire documentation
+     string, you can make it much more readable by choosing line breaks
+     with care.  Use blank lines between topics if the documentation
+     string is long.
+
+   * *Do not* indent subsequent lines of a documentation string so that
+     the text is lined up in the source code with the text of the first
+     line.  This looks nice in the source code, but looks bizarre when
+     users view the documentation.  Remember that the indentation
+     before the starting double-quote is not part of the string!
+
+   * A variable's documentation string should start with `*' if the
+     variable is one that users would often want to set interactively.
+     If the value is a long list, or a function, or if the variable
+     would be set only in init files, then don't start the
+     documentation string with `*'.  *Note Defining Variables::.
+
+   * The documentation string for a variable that is a yes-or-no flag
+     should start with words such as "Non-nil means...", to make it
+     clear that all non-`nil' values are equivalent and indicate
+     explicitly what `nil' and non-`nil' mean.
+
+   * When a function's documentation string mentions the value of an
+     argument of the function, use the argument name in capital letters
+     as if it were a name for that value.  Thus, the documentation
+     string of the function `/' refers to its second argument as
+     `DIVISOR', because the actual argument name is `divisor'.
+
+     Also use all caps for meta-syntactic variables, such as when you
+     show the decomposition of a list or vector into subunits, some of
+     which may vary.
+
+   * When a documentation string refers to a Lisp symbol, write it as it
+     would be printed (which usually means in lower case), with
+     single-quotes around it.  For example: `lambda'.  There are two
+     exceptions: write t and nil without single-quotes.  (In this
+     manual, we normally do use single-quotes for those symbols.)
+
+   * Don't write key sequences directly in documentation strings.
+     Instead, use the `\\[...]' construct to stand for them.  For
+     example, instead of writing `C-f', write `\\[forward-char]'.  When
+     Emacs displays the documentation string, it substitutes whatever
+     key is currently bound to `forward-char'.  (This is normally `C-f',
+     but it may be some other character if the user has moved key
+     bindings.)  *Note Keys in Documentation::.
+
+   * In documentation strings for a major mode, you will want to refer
+     to the key bindings of that mode's local map, rather than global
+     ones.  Therefore, use the construct `\\<...>' once in the
+     documentation string to specify which key map to use.  Do this
+     before the first use of `\\[...]'.  The text inside the `\\<...>'
+     should be the name of the variable containing the local keymap for
+     the major mode.
+
+     It is not practical to use `\\[...]' very many times, because
+     display of the documentation string will become slow.  So use this
+     to describe the most important commands in your major mode, and
+     then use `\\{...}' to display the rest of the mode's keymap.
+
+\1f
+File: lispref.info,  Node: Comment Tips,  Next: Library Headers,  Prev: Documentation Tips,  Up: Tips
+
+Tips on Writing Comments
+========================
+
+We recommend these conventions for where to put comments and how to
+indent them:
+
+`;'
+     Comments that start with a single semicolon, `;', should all be
+     aligned to the same column on the right of the source code.  Such
+     comments usually explain how the code on the same line does its
+     job.  In Lisp mode and related modes, the `M-;'
+     (`indent-for-comment') command automatically inserts such a `;' in
+     the right place, or aligns such a comment if it is already present.
+
+     This and following examples are taken from the Emacs sources.
+
+          (setq base-version-list                 ; there was a base
+                (assoc (substring fn 0 start-vn)  ; version to which
+                       file-version-assoc-list))  ; this looks like
+                                                  ; a subversion
+
+`;;'
+     Comments that start with two semicolons, `;;', should be aligned to
+     the same level of indentation as the code.  Such comments usually
+     describe the purpose of the following lines or the state of the
+     program at that point.  For example:
+
+          (prog1 (setq auto-fill-function
+                       ...
+                       ...
+            ;; update modeline
+            (redraw-modeline)))
+
+     Every function that has no documentation string (because it is
+     used only internally within the package it belongs to), should
+     have instead a two-semicolon comment right before the function,
+     explaining what the function does and how to call it properly.
+     Explain precisely what each argument means and how the function
+     interprets its possible values.
+
+`;;;'
+     Comments that start with three semicolons, `;;;', should start at
+     the left margin.  Such comments are used outside function
+     definitions to make general statements explaining the design
+     principles of the program.  For example:
+
+          ;;; This Lisp code is run in XEmacs
+          ;;; when it is to operate as a server
+          ;;; for other processes.
+
+     Another use for triple-semicolon comments is for commenting out
+     lines within a function.  We use triple-semicolons for this
+     precisely so that they remain at the left margin.
+
+          (defun foo (a)
+          ;;; This is no longer necessary.
+          ;;;  (force-mode-line-update)
+            (message "Finished with %s" a))
+
+`;;;;'
+     Comments that start with four semicolons, `;;;;', should be aligned
+     to the left margin and are used for headings of major sections of a
+     program.  For example:
+
+          ;;;; The kill ring
+
+The indentation commands of the Lisp modes in XEmacs, such as `M-;'
+(`indent-for-comment') and <TAB> (`lisp-indent-line') automatically
+indent comments according to these conventions, depending on the number
+of semicolons.  *Note Manipulating Comments: (xemacs)Comments.
+
+\1f
+File: lispref.info,  Node: Library Headers,  Prev: Comment Tips,  Up: Tips
+
+Conventional Headers for XEmacs Libraries
+=========================================
+
+XEmacs has conventions for using special comments in Lisp libraries to
+divide them into sections and give information such as who wrote them.
+This section explains these conventions.  First, an example:
+
+     ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+     
+     ;; Copyright (C) 1992 Free Software Foundation, Inc.
+     
+     ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
+     ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
+     ;; Created: 14 Jul 1992
+     ;; Version: 1.2
+     ;; Keywords: docs
+     
+     ;; This file is part of XEmacs.
+     COPYING PERMISSIONS...
+
+   The very first line should have this format:
+
+     ;;; FILENAME --- DESCRIPTION
+
+The description should be complete in one line.
+
+   After the copyright notice come several "header comment" lines, each
+beginning with `;; HEADER-NAME:'.  Here is a table of the conventional
+possibilities for HEADER-NAME:
+
+`Author'
+     This line states the name and net address of at least the principal
+     author of the library.
+
+     If there are multiple authors, you can list them on continuation
+     lines led by `;;' and a tab character, like this:
+
+          ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
+          ;;      Dave Sill <de5@ornl.gov>
+          ;;      Dave Brennan <brennan@hal.com>
+          ;;      Eric Raymond <esr@snark.thyrsus.com>
+
+`Maintainer'
+     This line should contain a single name/address as in the Author
+     line, or an address only, or the string `FSF'.  If there is no
+     maintainer line, the person(s) in the Author field are presumed to
+     be the maintainers.  The example above is mildly bogus because the
+     maintainer line is redundant.
+
+     The idea behind the `Author' and `Maintainer' lines is to make
+     possible a Lisp function to "send mail to the maintainer" without
+     having to mine the name out by hand.
+
+     Be sure to surround the network address with `<...>' if you
+     include the person's full name as well as the network address.
+
+`Created'
+     This optional line gives the original creation date of the file.
+     For historical interest only.
+
+`Version'
+     If you wish to record version numbers for the individual Lisp
+     program, put them in this line.
+
+`Adapted-By'
+     In this header line, place the name of the person who adapted the
+     library for installation (to make it fit the style conventions, for
+     example).
+
+`Keywords'
+     This line lists keywords for the `finder-by-keyword' help command.
+     This field is important; it's how people will find your package
+     when they're looking for things by topic area.  To separate the
+     keywords, you can use spaces, commas, or both.
+
+   Just about every Lisp library ought to have the `Author' and
+`Keywords' header comment lines.  Use the others if they are
+appropriate.  You can also put in header lines with other header
+names--they have no standard meanings, so they can't do any harm.
+
+   We use additional stylized comments to subdivide the contents of the
+library file.  Here is a table of them:
+
+`;;; Commentary:'
+     This begins introductory comments that explain how the library
+     works.  It should come right after the copying permissions.
+
+`;;; Change log:'
+     This begins change log information stored in the library file (if
+     you store the change history there).  For most of the Lisp files
+     distributed with XEmacs, the change history is kept in the file
+     `ChangeLog' and not in the source file at all; these files do not
+     have a `;;; Change log:' line.
+
+`;;; Code:'
+     This begins the actual code of the program.
+
+`;;; FILENAME ends here'
+     This is the "footer line"; it appears at the very end of the file.
+     Its purpose is to enable people to detect truncated versions of
+     the file from the lack of a footer line.
+
+\1f
+File: lispref.info,  Node: Building XEmacs and Object Allocation,  Next: Standard Errors,  Prev: Tips,  Up: Top
+
+Building XEmacs; Allocation of Objects
+**************************************
+
+This chapter describes how the runnable XEmacs executable is dumped
+with the preloaded Lisp libraries in it and how storage is allocated.
+
+   There is an entire separate document, the `XEmacs Internals Manual',
+devoted to the internals of XEmacs from the perspective of the C
+programmer.  It contains much more detailed information about the build
+process, the allocation and garbage-collection process, and other
+aspects related to the internals of XEmacs.
+
+* Menu:
+
+* 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.
+
+\1f
+File: lispref.info,  Node: Building XEmacs,  Next: Pure Storage,  Up: Building XEmacs and Object Allocation
+
+Building XEmacs
+===============
+
+This section explains the steps involved in building the XEmacs
+executable.  You don't have to know this material to build and install
+XEmacs, since the makefiles do all these things automatically.  This
+information is pertinent to XEmacs maintenance.
+
+   The `XEmacs Internals Manual' contains more information about this.
+
+   Compilation of the C source files in the `src' directory produces an
+executable file called `temacs', also called a "bare impure XEmacs".
+It contains the XEmacs Lisp interpreter and I/O routines, but not the
+editing commands.
+
+   Before XEmacs is actually usable, a number of Lisp files need to be
+loaded.  These define all the editing commands, plus most of the startup
+code and many very basic Lisp primitives.  This is accomplished by
+loading the file `loadup.el', which in turn loads all of the other
+standardly-loaded Lisp files.
+
+   It takes a substantial time to load the standard Lisp files.
+Luckily, you don't have to do this each time you run XEmacs; `temacs'
+can dump out an executable program called `xemacs' that has these files
+preloaded.  `xemacs' starts more quickly because it does not need to
+load the files.  This is the XEmacs executable that is normally
+installed.
+
+   To create `xemacs', use the command `temacs -batch -l loadup dump'.
+The purpose of `-batch' here is to tell `temacs' to run in
+non-interactive, command-line mode. (`temacs' can _only_ run in this
+fashion.  Part of the code required to initialize frames and faces is
+in Lisp, and must be loaded before XEmacs is able to create any frames.)
+The argument `dump' tells `loadup.el' to dump a new executable named
+`xemacs'.
+
+   The dumping process is highly system-specific, and some operating
+systems don't support dumping.  On those systems, you must start XEmacs
+with the `temacs -batch -l loadup run-temacs' command each time you use
+it.  This takes a substantial time, but since you need to start Emacs
+once a day at most--or once a week if you never log out--the extra time
+is not too severe a problem. (In older versions of Emacs, you started
+Emacs from `temacs' using `temacs -l loadup'.)
+
+   You are free to start XEmacs directly from `temacs' if you want,
+even if there is already a dumped `xemacs'.  Normally you wouldn't want
+to do that; but the Makefiles do this when you rebuild XEmacs using
+`make all-elc', which builds XEmacs and simultaneously compiles any
+out-of-date Lisp files. (You need `xemacs' in order to compile Lisp
+files.  However, you also need the compiled Lisp files in order to dump
+out `xemacs'.  If both of these are missing or corrupted, you are out
+of luck unless you're able to bootstrap `xemacs' from `temacs'.  Note
+that `make all-elc' actually loads the alternative loadup file
+`loadup-el.el', which works like `loadup.el' but disables the
+pure-copying process and forces XEmacs to ignore any compiled Lisp
+files even if they exist.)
+
+   You can specify additional files to preload by writing a library
+named `site-load.el' that loads them.  You may need to increase the
+value of `PURESIZE', in `src/puresize.h', to make room for the
+additional files.  You should _not_ modify this file directly, however;
+instead, use the `--puresize' configuration option. (If you run out of
+pure space while dumping `xemacs', you will be told how much pure space
+you actually will need.) However, the advantage of preloading
+additional files decreases as machines get faster.  On modern machines,
+it is often not advisable, especially if the Lisp code is on a file
+system local to the machine running XEmacs.
+
+   You can specify other Lisp expressions to execute just before dumping
+by putting them in a library named `site-init.el'.  However, if they
+might alter the behavior that users expect from an ordinary unmodified
+XEmacs, it is better to put them in `default.el', so that users can
+override them if they wish.  *Note Start-up Summary::.
+
+   Before `loadup.el' dumps the new executable, it finds the
+documentation strings for primitive and preloaded functions (and
+variables) in the file where they are stored, by calling
+`Snarf-documentation' (*note Accessing Documentation::).  These strings
+were moved out of the `xemacs' executable to make it smaller.  *Note
+Documentation Basics::.
+
+ - Function: dump-emacs to-file from-file
+     This function dumps the current state of XEmacs into an executable
+     file TO-FILE.  It takes symbols from FROM-FILE (this is normally
+     the executable file `temacs').
+
+     If you use this function in an XEmacs that was already dumped, you
+     must set `command-line-processed' to `nil' first for good results.
+     *Note Command Line Arguments::.
+
+ - Function: run-emacs-from-temacs &rest args
+     This is the function that implements the `run-temacs' command-line
+     argument.  It is called from `loadup.el' as appropriate.  You
+     should most emphatically _not_ call this yourself; it will
+     reinitialize your XEmacs process and you'll be sorry.
+
+ - Command: emacs-version &optional arg
+     This function returns a string describing the version of XEmacs
+     that is running.  It is useful to include this string in bug
+     reports.
+
+     When called interactively with a prefix argument, insert string at
+     point.  Don't use this function in programs to choose actions
+     according to the system configuration; look at
+     `system-configuration' instead.
+
+          (emacs-version)
+            => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
+                           of Mon Apr  7 1997 on altair.xemacs.org"
+
+     Called interactively, the function prints the same information in
+     the echo area.
+
+ - Variable: emacs-build-time
+     The value of this variable is the time at which XEmacs was built
+     at the local site.
+
+          emacs-build-time "Mon Apr  7 20:28:52 1997"
+               =>
+
+ - Variable: emacs-version
+     The value of this variable is the version of Emacs being run.  It
+     is a string, e.g. `"20.1 XEmacs Lucid"'.
+
+   The following two variables did not exist before FSF GNU Emacs
+version 19.23 and XEmacs version 19.10, which reduces their usefulness
+at present, but we hope they will be convenient in the future.
+
+ - Variable: emacs-major-version
+     The major version number of Emacs, as an integer.  For XEmacs
+     version 20.1, the value is 20.
+
+ - Variable: emacs-minor-version
+     The minor version number of Emacs, as an integer.  For XEmacs
+     version 20.1, the value is 1.
+
+\1f
+File: lispref.info,  Node: Pure Storage,  Next: Garbage Collection,  Prev: Building XEmacs,  Up: Building XEmacs and Object Allocation
+
+Pure Storage
+============
+
+XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
+"normal storage" and "pure storage".  Normal storage is where all the
+new data created during an XEmacs session is kept; see the following
+section for information on normal storage.  Pure storage is used for
+certain data in the preloaded standard Lisp files--data that should
+never change during actual use of XEmacs.
+
+   Pure storage is allocated only while `temacs' is loading the
+standard preloaded Lisp libraries.  In the file `xemacs', it is marked
+as read-only (on operating systems that permit this), so that the
+memory space can be shared by all the XEmacs jobs running on the machine
+at once.  Pure storage is not expandable; a fixed amount is allocated
+when XEmacs is compiled, and if that is not sufficient for the preloaded
+libraries, `temacs' aborts with an error message.  If that happens, you
+must increase the compilation parameter `PURESIZE' using the
+`--puresize' option to `configure'.  This normally won't happen unless
+you try to preload additional libraries or add features to the standard
+ones.
+
+ - Function: purecopy object
+     This function makes a copy of OBJECT in pure storage and returns
+     it.  It copies strings by simply making a new string with the same
+     characters in pure storage.  It recursively copies the contents of
+     vectors and cons cells.  It does not make copies of other objects
+     such as symbols, but just returns them unchanged.  It signals an
+     error if asked to copy markers.
+
+     This function is a no-op in XEmacs, and its use in new code is
+     deprecated.
+
+ - Variable: pure-bytes-used
+     The value of this variable is the number of bytes of pure storage
+     allocated so far.  Typically, in a dumped XEmacs, this number is
+     very close to the total amount of pure storage available--if it
+     were not, we would preallocate less.
+
+ - Variable: purify-flag
+     This variable determines whether `defun' should make a copy of the
+     function definition in pure storage.  If it is non-`nil', then the
+     function definition is copied into pure storage.
+
+     This flag is `t' while loading all of the basic functions for
+     building XEmacs initially (allowing those functions to be sharable
+     and non-collectible).  Dumping XEmacs as an executable always
+     writes `nil' in this variable, regardless of the value it actually
+     has before and after dumping.
+
+     You should not change this flag in a running XEmacs.
+
+\1f
+File: lispref.info,  Node: Garbage Collection,  Prev: Pure Storage,  Up: Building XEmacs and Object Allocation
+
+Garbage Collection
+==================
+
+When a program creates a list or the user defines a new function (such
+as by loading a library), that data is placed in normal storage.  If
+normal storage runs low, then XEmacs asks the operating system to
+allocate more memory in blocks of 2k bytes.  Each block is used for one
+type of Lisp object, so symbols, cons cells, markers, etc., are
+segregated in distinct blocks in memory.  (Vectors, long strings,
+buffers and certain other editing types, which are fairly large, are
+allocated in individual blocks, one per object, while small strings are
+packed into blocks of 8k bytes. [More correctly, a string is allocated
+in two sections: a fixed size chunk containing the length, list of
+extents, etc.; and a chunk containing the actual characters in the
+string.  It is this latter chunk that is either allocated individually
+or packed into 8k blocks.  The fixed size chunk is packed into 2k
+blocks, as for conses, markers, etc.])
+
+   It is quite common to use some storage for a while, then release it
+by (for example) killing a buffer or deleting the last pointer to an
+object.  XEmacs provides a "garbage collector" to reclaim this
+abandoned storage.  (This name is traditional, but "garbage recycler"
+might be a more intuitive metaphor for this facility.)
+
+   The garbage collector operates by finding and marking all Lisp
+objects that are still accessible to Lisp programs.  To begin with, it
+assumes all the symbols, their values and associated function
+definitions, and any data presently on the stack, are accessible.  Any
+objects that can be reached indirectly through other accessible objects
+are also accessible.
+
+   When marking is finished, all objects still unmarked are garbage.  No
+matter what the Lisp program or the user does, it is impossible to refer
+to them, since there is no longer a way to reach them.  Their space
+might as well be reused, since no one will miss them.  The second
+("sweep") phase of the garbage collector arranges to reuse them.
+
+   The sweep phase puts unused cons cells onto a "free list" for future
+allocation; likewise for symbols, markers, extents, events, floats,
+compiled-function objects, and the fixed-size portion of strings.  It
+compacts the accessible small string-chars chunks so they occupy fewer
+8k blocks; then it frees the other 8k blocks.  Vectors, buffers,
+windows, and other large objects are individually allocated and freed
+using `malloc' and `free'.
+
+     Common Lisp note: unlike other Lisps, XEmacs Lisp does not call
+     the garbage collector when the free list is empty.  Instead, it
+     simply requests the operating system to allocate more storage, and
+     processing continues until `gc-cons-threshold' bytes have been
+     used.
+
+     This means that you can make sure that the garbage collector will
+     not run during a certain portion of a Lisp program by calling the
+     garbage collector explicitly just before it (provided that portion
+     of the program does not use so much space as to force a second
+     garbage collection).
+
+ - Command: garbage-collect
+     This command runs a garbage collection, and returns information on
+     the amount of space in use.  (Garbage collection can also occur
+     spontaneously if you use more than `gc-cons-threshold' bytes of
+     Lisp data since the previous garbage collection.)
+
+     `garbage-collect' returns a list containing the following
+     information:
+
+          ((USED-CONSES . FREE-CONSES)
+           (USED-SYMS . FREE-SYMS)
+           (USED-MARKERS . FREE-MARKERS)
+           USED-STRING-CHARS
+           USED-VECTOR-SLOTS
+           (PLIST))
+          
+          => ((73362 . 8325) (13718 . 164)
+          (5089 . 5098) 949121 118677
+          (conses-used 73362 conses-free 8329 cons-storage 658168
+          symbols-used 13718 symbols-free 164 symbol-storage 335216
+          bit-vectors-used 0 bit-vectors-total-length 0
+          bit-vector-storage 0 vectors-used 7882
+          vectors-total-length 118677 vector-storage 537764
+          compiled-functions-used 1336 compiled-functions-free 37
+          compiled-function-storage 44440 short-strings-used 28829
+          long-strings-used 2 strings-free 7722
+          short-strings-total-length 916657 short-string-storage 1179648
+          long-strings-total-length 32464 string-header-storage 441504
+          floats-used 3 floats-free 43 float-storage 2044 markers-used 5089
+          markers-free 5098 marker-storage 245280 events-used 103
+          events-free 835 event-storage 110656 extents-used 10519
+          extents-free 2718 extent-storage 372736
+          extent-auxiliarys-used 111 extent-auxiliarys-freed 3
+          extent-auxiliary-storage 4440 window-configurations-used 39
+          window-configurations-on-free-list 5
+          window-configurations-freed 10 window-configuration-storage 9492
+          popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62
+          toolbar-button-storage 4960 toolbar-datas-used 12
+          toolbar-data-storage 240 symbol-value-buffer-locals-used 182
+          symbol-value-buffer-local-storage 5824
+          symbol-value-lisp-magics-used 22
+          symbol-value-lisp-magic-storage 1496
+          symbol-value-varaliases-used 43
+          symbol-value-varalias-storage 1032 opaque-lists-used 2
+          opaque-list-storage 48 color-instances-used 12
+          color-instance-storage 288 font-instances-used 5
+          font-instance-storage 180 opaques-used 11 opaque-storage 312
+          range-tables-used 1 range-table-storage 16 faces-used 34
+          face-storage 2584 glyphs-used 124 glyph-storage 4464
+          specifiers-used 775 specifier-storage 43869 weak-lists-used 786
+          weak-list-storage 18864 char-tables-used 40
+          char-table-storage 41920 buffers-used 25 buffer-storage 7000
+          extent-infos-used 457 extent-infos-freed 73
+          extent-info-storage 9140 keymaps-used 275 keymap-storage 12100
+          consoles-used 4 console-storage 384 command-builders-used 2
+          command-builder-storage 120 devices-used 2 device-storage 344
+          frames-used 3 frame-storage 624 image-instances-used 47
+          image-instance-storage 3008 windows-used 27 windows-freed 2
+          window-storage 9180 lcrecord-lists-used 15
+          lcrecord-list-storage 360 hash-tables-used 631
+          hash-table-storage 25240 streams-used 1 streams-on-free-list 3
+          streams-freed 12 stream-storage 91))
+
+     Here is a table explaining each element:
+
+    USED-CONSES
+          The number of cons cells in use.
+
+    FREE-CONSES
+          The number of cons cells for which space has been obtained
+          from the operating system, but that are not currently being
+          used.
+
+    USED-SYMS
+          The number of symbols in use.
+
+    FREE-SYMS
+          The number of symbols for which space has been obtained from
+          the operating system, but that are not currently being used.
+
+    USED-MARKERS
+          The number of markers in use.
+
+    FREE-MARKERS
+          The number of markers for which space has been obtained from
+          the operating system, but that are not currently being used.
+
+    USED-STRING-CHARS
+          The total size of all strings, in characters.
+
+    USED-VECTOR-SLOTS
+          The total number of elements of existing vectors.
+
+    PLIST
+          A list of alternating keyword/value pairs providing more
+          detailed information. (As you can see above, quite a lot of
+          information is provided.)
+
+ - User Option: gc-cons-threshold
+     The value of this variable is the number of bytes of storage that
+     must be allocated for Lisp objects after one garbage collection in
+     order to trigger another garbage collection.  A cons cell counts
+     as eight bytes, a string as one byte per character plus a few
+     bytes of overhead, and so on; space allocated to the contents of
+     buffers does not count.  Note that the subsequent garbage
+     collection does not happen immediately when the threshold is
+     exhausted, but only the next time the Lisp evaluator is called.
+
+     The initial threshold value is 500,000.  If you specify a larger
+     value, garbage collection will happen less often.  This reduces the
+     amount of time spent garbage collecting, but increases total
+     memory use.  You may want to do this when running a program that
+     creates lots of Lisp data.
+
+     You can make collections more frequent by specifying a smaller
+     value, down to 10,000.  A value less than 10,000 will remain in
+     effect only until the subsequent garbage collection, at which time
+     `garbage-collect' will set the threshold back to 10,000. (This does
+     not apply if XEmacs was configured with `--debug'.  Therefore, be
+     careful when setting `gc-cons-threshold' in that case!)
+
+ - Variable: pre-gc-hook
+     This is a normal hook to be run just before each garbage
+     collection.  Interrupts, garbage collection, and errors are
+     inhibited while this hook runs, so be extremely careful in what
+     you add here.  In particular, avoid consing, and do not interact
+     with the user.
+
+ - Variable: post-gc-hook
+     This is a normal hook to be run just after each garbage collection.
+     Interrupts, garbage collection, and errors are inhibited while
+     this hook runs, so be extremely careful in what you add here.  In
+     particular, avoid consing, and do not interact with the user.
+
+ - Variable: gc-message
+     This is a string to print to indicate that a garbage collection is
+     in progress.  This is printed in the echo area.  If the selected
+     frame is on a window system and `gc-pointer-glyph' specifies a
+     value (i.e. a pointer image instance) in the domain of the
+     selected frame, the mouse cursor will change instead of this
+     message being printed.
+
+ - Glyph: gc-pointer-glyph
+     This holds the pointer glyph used to indicate that a garbage
+     collection is in progress.  If the selected window is on a window
+     system and this glyph specifies a value (i.e. a pointer image
+     instance) in the domain of the selected window, the cursor will be
+     changed as specified during garbage collection.  Otherwise, a
+     message will be printed in the echo area, as controlled by
+     `gc-message'.  *Note Glyphs::.
+
+   If XEmacs was configured with `--debug', you can set the following
+two variables to get direct information about all the allocation that
+is happening in a segment of Lisp code.
+
+ - Variable: debug-allocation
+     If non-zero, print out information to stderr about all objects
+     allocated.
+
+ - Variable: debug-allocation-backtrace
+     Length (in stack frames) of short backtrace printed out by
+     `debug-allocation'.
+
+\1f
+File: lispref.info,  Node: Standard Errors,  Next: Standard Buffer-Local Variables,  Prev: Building XEmacs and Object Allocation,  Up: Top
+
+Standard Errors
+***************
+
+Here is the complete list of the error symbols in standard Emacs,
+grouped by concept.  The list includes each symbol's message (on the
+`error-message' property of the symbol) and a cross reference to a
+description of how the error can occur.
+
+   Each error symbol has an `error-conditions' property that is a list
+of symbols.  Normally this list includes the error symbol itself and
+the symbol `error'.  Occasionally it includes additional symbols, which
+are intermediate classifications, narrower than `error' but broader
+than a single error symbol.  For example, all the errors in accessing
+files have the condition `file-error'.
+
+   As a special exception, the error symbol `quit' does not have the
+condition `error', because quitting is not considered an error.
+
+   *Note Errors::, for an explanation of how errors are generated and
+handled.
+
+`SYMBOL'
+     STRING; REFERENCE.
+
+`error'
+     `"error"'
+     *Note Errors::.
+
+`quit'
+     `"Quit"'
+     *Note Quitting::.
+
+`args-out-of-range'
+     `"Args out of range"'
+     *Note Sequences Arrays Vectors::.
+
+`arith-error'
+     `"Arithmetic error"'
+     See `/' and `%' in *Note Numbers::.
+
+`beginning-of-buffer'
+     `"Beginning of buffer"'
+     *Note Motion::.
+
+`buffer-read-only'
+     `"Buffer is read-only"'
+     *Note Read Only Buffers::.
+
+`cyclic-function-indirection'
+     `"Symbol's chain of function indirections contains a loop"'
+     *Note Function Indirection::.
+
+`domain-error'
+     `"Arithmetic domain error"'
+`end-of-buffer'
+     `"End of buffer"'
+     *Note Motion::.
+
+`end-of-file'
+     `"End of file during parsing"'
+     This is not a `file-error'.
+     *Note Input Functions::.
+
+`file-error'
+     This error and its subcategories do not have error-strings,
+     because the error message is constructed from the data items alone
+     when the error condition `file-error' is present.
+     *Note Files::.
+
+`file-locked'
+     This is a `file-error'.
+     *Note File Locks::.
+
+`file-already-exists'
+     This is a `file-error'.
+     *Note Writing to Files::.
+
+`file-supersession'
+     This is a `file-error'.
+     *Note Modification Time::.
+
+`invalid-byte-code'
+     `"Invalid byte code"'
+     *Note Byte Compilation::.
+
+`invalid-function'
+     `"Invalid function"'
+     *Note Classifying Lists::.
+
+`invalid-read-syntax'
+     `"Invalid read syntax"'
+     *Note Input Functions::.
+
+`invalid-regexp'
+     `"Invalid regexp"'
+     *Note Regular Expressions::.
+
+`mark-inactive'
+     `"The mark is not active now"'
+`no-catch'
+     `"No catch for tag"'
+     *Note Catch and Throw::.
+
+`overflow-error'
+     `"Arithmetic overflow error"'
+`protected-field'
+     `"Attempt to modify a protected field"'
+`range-error'
+     `"Arithmetic range error"'
+`search-failed'
+     `"Search failed"'
+     *Note Searching and Matching::.
+
+`setting-constant'
+     `"Attempt to set a constant symbol"'
+     *Note Variables that Never Change: Constant Variables.
+
+`singularity-error'
+     `"Arithmetic singularity error"'
+`tooltalk-error'
+     `"ToolTalk error"'
+     *Note ToolTalk Support::.
+
+`undefined-keystroke-sequence'
+     `"Undefined keystroke sequence"'
+`void-function'
+     `"Symbol's function definition is void"'
+     *Note Function Cells::.
+
+`void-variable'
+     `"Symbol's value as variable is void"'
+     *Note Accessing Variables::.
+
+`wrong-number-of-arguments'
+     `"Wrong number of arguments"'
+     *Note Classifying Lists::.
+
+`wrong-type-argument'
+     `"Wrong type argument"'
+     *Note Type Predicates::.
+
+   These error types, which are all classified as special cases of
+`arith-error', can occur on certain systems for invalid use of
+mathematical functions.
+
+`domain-error'
+     `"Arithmetic domain error"'
+     *Note Math Functions::.
+
+`overflow-error'
+     `"Arithmetic overflow error"'
+     *Note Math Functions::.
+
+`range-error'
+     `"Arithmetic range error"'
+     *Note Math Functions::.
+
+`singularity-error'
+     `"Arithmetic singularity error"'
+     *Note Math Functions::.
+
+`underflow-error'
+     `"Arithmetic underflow error"'
+     *Note Math Functions::.
+
+\1f
+File: lispref.info,  Node: Standard Buffer-Local Variables,  Next: Standard Keymaps,  Prev: Standard Errors,  Up: Top
+
+Buffer-Local Variables
+**********************
+
+The table below lists the general-purpose Emacs variables that are
+automatically local (when set) in each buffer.  Many Lisp packages
+define such variables for their internal use; we don't list them here.
+
+`abbrev-mode'
+     *note Abbrevs::
+
+`auto-fill-function'
+     *note Auto Filling::
+
+`buffer-auto-save-file-name'
+     *note Auto-Saving::
+
+`buffer-backed-up'
+     *note Backup Files::
+
+`buffer-display-table'
+     *note Display Tables::
+
+`buffer-file-format'
+     *note Format Conversion::
+
+`buffer-file-name'
+     *note Buffer File Name::
+
+`buffer-file-number'
+     *note Buffer File Name::
+
+`buffer-file-truename'
+     *note Buffer File Name::
+
+`buffer-file-type'
+     *note Files and MS-DOS::
+
+`buffer-invisibility-spec'
+     *note Invisible Text::
+
+`buffer-offer-save'
+     *note Saving Buffers::
+
+`buffer-read-only'
+     *note Read Only Buffers::
+
+`buffer-saved-size'
+     *note Point::
+
+`buffer-undo-list'
+     *note Undo::
+
+`cache-long-line-scans'
+     *note Text Lines::
+
+`case-fold-search'
+     *note Searching and Case::
+
+`ctl-arrow'
+     *note Usual Display::
+
+`comment-column'
+     *note Comments: (xemacs)Comments.
+
+`default-directory'
+     *note System Environment::
+
+`defun-prompt-regexp'
+     *note List Motion::
+
+`fill-column'
+     *note Auto Filling::
+
+`goal-column'
+     *note Moving Point: (xemacs)Moving Point.
+
+`left-margin'
+     *note Indentation::
+
+`local-abbrev-table'
+     *note Abbrevs::
+
+`local-write-file-hooks'
+     *note Saving Buffers::
+
+`major-mode'
+     *note Mode Help::
+
+`mark-active'
+     *note The Mark::
+
+`mark-ring'
+     *note The Mark::
+
+`minor-modes'
+     *note Minor Modes::
+
+`modeline-format'
+     *note Modeline Data::
+
+`modeline-buffer-identification'
+     *note Modeline Variables::
+
+`modeline-format'
+     *note Modeline Data::
+
+`modeline-modified'
+     *note Modeline Variables::
+
+`modeline-process'
+     *note Modeline Variables::
+
+`mode-name'
+     *note Modeline Variables::
+
+`overwrite-mode'
+     *note Insertion::
+
+`paragraph-separate'
+     *note Standard Regexps::
+
+`paragraph-start'
+     *note Standard Regexps::
+
+`point-before-scroll'
+     Used for communication between mouse commands and scroll-bar
+     commands.
+
+`require-final-newline'
+     *note Insertion::
+
+`selective-display'
+     *note Selective Display::
+
+`selective-display-ellipses'
+     *note Selective Display::
+
+`tab-width'
+     *note Usual Display::
+
+`truncate-lines'
+     *note Truncation::
+
+`vc-mode'
+     *note Modeline Variables::
+
+\1f
+File: lispref.info,  Node: Standard Keymaps,  Next: Standard Hooks,  Prev: Standard Buffer-Local Variables,  Up: Top
+
+Standard Keymaps
+****************
+
+The following symbols are used as the names for various keymaps.  Some
+of these exist when XEmacs is first started, others are loaded only
+when their respective mode is used.  This is not an exhaustive list.
+
+   Almost all of these maps are used as local maps.  Indeed, of the
+modes that presently exist, only Vip mode and Terminal mode ever change
+the global keymap.
+
+`bookmark-map'
+     A keymap containing bindings to bookmark functions.
+
+`Buffer-menu-mode-map'
+     A keymap used by Buffer Menu mode.
+
+`c++-mode-map'
+     A keymap used by C++ mode.
+
+`c-mode-map'
+     A keymap used by C mode.  A sparse keymap used by C mode.
+
+`command-history-map'
+     A keymap used by Command History mode.
+
+`ctl-x-4-map'
+     A keymap for subcommands of the prefix `C-x 4'.
+
+`ctl-x-5-map'
+     A keymap for subcommands of the prefix `C-x 5'.
+
+`ctl-x-map'
+     A keymap for `C-x' commands.
+
+`debugger-mode-map'
+     A keymap used by Debugger mode.
+
+`dired-mode-map'
+     A keymap for `dired-mode' buffers.
+
+`edit-abbrevs-map'
+     A keymap used in `edit-abbrevs'.
+
+`edit-tab-stops-map'
+     A keymap used in `edit-tab-stops'.
+
+`electric-buffer-menu-mode-map'
+     A keymap used by Electric Buffer Menu mode.
+
+`electric-history-map'
+     A keymap used by Electric Command History mode.
+
+`emacs-lisp-mode-map'
+     A keymap used by Emacs Lisp mode.
+
+`help-map'
+     A keymap for characters following the Help key.
+
+`Helper-help-map'
+     A keymap used by the help utility package.
+     It has the same keymap in its value cell and in its function cell.
+
+`Info-edit-map'
+     A keymap used by the `e' command of Info.
+
+`Info-mode-map'
+     A keymap containing Info commands.
+
+`isearch-mode-map'
+     A keymap that defines the characters you can type within
+     incremental search.
+
+`itimer-edit-map'
+     A keymap used when in Itimer Edit mode.
+
+`lisp-interaction-mode-map'
+     A keymap used by Lisp mode.
+
+`lisp-mode-map'
+     A keymap used by Lisp mode.
+
+     A keymap for minibuffer input with completion.
+
+`minibuffer-local-isearch-map'
+     A keymap for editing isearch strings in the minibuffer.
+
+`minibuffer-local-map'
+     Default keymap to use when reading from the minibuffer.
+
+`minibuffer-local-must-match-map'
+     A keymap for minibuffer input with completion, for exact match.
+
+`mode-specific-map'
+     The keymap for characters following `C-c'.  Note, this is in the
+     global map.  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.
+
+`modeline-map'
+     The keymap consulted for mouse-clicks on the modeline of a window.
+
+`objc-mode-map'
+     A keymap used in Objective C mode as a local map.
+
+`occur-mode-map'
+     A local keymap used by Occur mode.
+
+`overriding-local-map'
+     A keymap that overrides all other local keymaps.
+
+`query-replace-map'
+     A local keymap used for responses in `query-replace' and related
+     commands; also for `y-or-n-p' and `map-y-or-n-p'.  The functions
+     that use this map do not support prefix keys; they look up one
+     event at a time.
+
+`read-expression-map'
+     The minibuffer keymap used for reading Lisp expressions.
+
+`read-shell-command-map'
+     The minibuffer keymap used by `shell-command' and related commands.
+
+`shared-lisp-mode-map'
+     A keymap for commands shared by all sorts of Lisp modes.
+
+`text-mode-map'
+     A keymap used by Text mode.
+
+`toolbar-map'
+     The keymap consulted for mouse-clicks over a toolbar.
+
+`view-mode-map'
+     A keymap used by View mode.
+
+\1f
+File: lispref.info,  Node: Standard Hooks,  Next: Index,  Prev: Standard Keymaps,  Up: Top
+
+Standard Hooks
+**************
+
+The following is a list of hook variables that let you provide
+functions to be called from within Emacs on suitable occasions.
+
+   Most of these variables have names ending with `-hook'.  They are
+"normal hooks", run by means of `run-hooks'.  The value of such a hook
+is a list of functions.  The recommended way to put a new function on
+such a hook is to call `add-hook'.  *Note Hooks::, for more information
+about using hooks.
+
+   The variables whose names end in `-function' have single functions
+as their values.  Usually there is a specific reason why the variable is
+not a normal hook, such as the need to pass arguments to the function.
+(In older Emacs versions, some of these variables had names ending in
+`-hook' even though they were not normal hooks.)
+
+   The variables whose names end in `-hooks' or `-functions' have lists
+of functions as their values, but these functions are called in a
+special way (they are passed arguments, or else their values are used).
+
+`activate-menubar-hook'
+
+`activate-popup-menu-hook'
+
+`ad-definition-hooks'
+
+`adaptive-fill-function'
+
+`add-log-current-defun-function'
+
+`after-change-functions'
+
+`after-delete-annotation-hook'
+
+`after-init-hook'
+
+`after-insert-file-functions'
+
+`after-revert-hook'
+
+`after-save-hook'
+
+`after-set-visited-file-name-hooks'
+
+`after-write-file-hooks'
+
+`auto-fill-function'
+
+`auto-save-hook'
+
+`before-change-functions'
+
+`before-delete-annotation-hook'
+
+`before-init-hook'
+
+`before-revert-hook'
+
+`blink-paren-function'
+
+`buffers-menu-switch-to-buffer-function'
+
+`c++-mode-hook'
+
+`c-delete-function'
+
+`c-mode-common-hook'
+
+`c-mode-hook'
+
+`c-special-indent-hook'
+
+`calendar-load-hook'
+
+`change-major-mode-hook'
+
+`command-history-hook'
+
+`comment-indent-function'
+
+`compilation-buffer-name-function'
+
+`compilation-exit-message-function'
+
+`compilation-finish-function'
+
+`compilation-parse-errors-function'
+
+`compilation-mode-hook'
+
+`create-console-hook'
+
+`create-device-hook'
+
+`create-frame-hook'
+
+`dabbrev-friend-buffer-function'
+
+`dabbrev-select-buffers-function'
+
+`delete-console-hook'
+
+`delete-device-hook'
+
+`delete-frame-hook'
+
+`deselect-frame-hook'
+
+`diary-display-hook'
+
+`diary-hook'
+
+`dired-after-readin-hook'
+
+`dired-before-readin-hook'
+
+`dired-load-hook'
+
+`dired-mode-hook'
+
+`disabled-command-hook'
+
+`display-buffer-function'
+
+`ediff-after-setup-control-frame-hook'
+
+`ediff-after-setup-windows-hook'
+
+`ediff-before-setup-control-frame-hook'
+
+`ediff-before-setup-windows-hook'
+
+`ediff-brief-help-message-function'
+
+`ediff-cleanup-hook'
+
+`ediff-control-frame-position-function'
+
+`ediff-display-help-hook'
+
+`ediff-focus-on-regexp-matches-function'
+
+`ediff-forward-word-function'
+
+`ediff-hide-regexp-matches-function'
+
+`ediff-keymap-setup-hook'
+
+`ediff-load-hook'
+
+`ediff-long-help-message-function'
+
+`ediff-make-wide-display-function'
+
+`ediff-merge-split-window-function'
+
+`ediff-meta-action-function'
+
+`ediff-meta-redraw-function'
+
+`ediff-mode-hook'
+
+`ediff-prepare-buffer-hook'
+
+`ediff-quit-hook'
+
+`ediff-registry-setup-hook'
+
+`ediff-select-hook'
+
+`ediff-session-action-function'
+
+`ediff-session-group-setup-hook'
+
+`ediff-setup-diff-regions-function'
+
+`ediff-show-registry-hook'
+
+`ediff-show-session-group-hook'
+
+`ediff-skip-diff-region-function'
+
+`ediff-split-window-function'
+
+`ediff-startup-hook'
+
+`ediff-suspend-hook'
+
+`ediff-toggle-read-only-function'
+
+`ediff-unselect-hook'
+
+`ediff-window-setup-function'
+
+`edit-picture-hook'
+
+`electric-buffer-menu-mode-hook'
+
+`electric-command-history-hook'
+
+`electric-help-mode-hook'
+
+`emacs-lisp-mode-hook'
+
+`fill-paragraph-function'
+
+`find-file-hooks'
+
+`find-file-not-found-hooks'
+
+`first-change-hook'
+
+`font-lock-after-fontify-buffer-hook'
+
+`font-lock-beginning-of-syntax-function'
+
+`font-lock-mode-hook'
+
+`fume-found-function-hook'
+
+`fume-list-mode-hook'
+
+`fume-rescan-buffer-hook'
+
+`fume-sort-function'
+
+`gnus-startup-hook'
+
+`hack-local-variables-hook'
+
+`highlight-headers-follow-url-function'
+
+`hyper-apropos-mode-hook'
+
+`indent-line-function'
+
+`indent-mim-hook'
+
+`indent-region-function'
+
+`initial-calendar-window-hook'
+
+`isearch-mode-end-hook'
+
+`isearch-mode-hook'
+
+`java-mode-hook'
+
+`kill-buffer-hook'
+
+`kill-buffer-query-functions'
+
+`kill-emacs-hook'
+
+`kill-emacs-query-functions'
+
+`kill-hooks'
+
+`LaTeX-mode-hook'
+
+`latex-mode-hook'
+
+`ledit-mode-hook'
+
+`lisp-indent-function'
+
+`lisp-interaction-mode-hook'
+
+`lisp-mode-hook'
+
+`list-diary-entries-hook'
+
+`load-read-function'
+
+`log-message-filter-function'
+
+`m2-mode-hook'
+
+`mail-citation-hook'
+
+`mail-mode-hook'
+
+`mail-setup-hook'
+
+`make-annotation-hook'
+
+`makefile-mode-hook'
+
+`map-frame-hook'
+
+`mark-diary-entries-hook'
+
+`medit-mode-hook'
+
+`menu-no-selection-hook'
+
+`mh-compose-letter-hook'
+
+`mh-folder-mode-hook'
+
+`mh-letter-mode-hook'
+
+`mim-mode-hook'
+
+`minibuffer-exit-hook'
+
+`minibuffer-setup-hook'
+
+`mode-motion-hook'
+
+`mouse-enter-frame-hook'
+
+`mouse-leave-frame-hook'
+
+`mouse-track-cleanup-hook'
+
+`mouse-track-click-hook'
+
+`mouse-track-down-hook'
+
+`mouse-track-drag-hook'
+
+`mouse-track-drag-up-hook'
+
+`mouse-track-up-hook'
+
+`mouse-yank-function'
+
+`news-mode-hook'
+
+`news-reply-mode-hook'
+
+`news-setup-hook'
+
+`nongregorian-diary-listing-hook'
+
+`nongregorian-diary-marking-hook'
+
+`nroff-mode-hook'
+
+`objc-mode-hook'
+
+`outline-mode-hook'
+
+`perl-mode-hook'
+
+`plain-TeX-mode-hook'
+
+`post-command-hook'
+
+`post-gc-hook'
+
+`pre-abbrev-expand-hook'
+
+`pre-command-hook'
+
+`pre-display-buffer-function'
+
+`pre-gc-hook'
+
+`pre-idle-hook'
+
+`print-diary-entries-hook'
+
+`prolog-mode-hook'
+
+`protect-innocence-hook'
+
+`remove-message-hook'
+
+`revert-buffer-function'
+
+`revert-buffer-insert-contents-function'
+
+`rmail-edit-mode-hook'
+
+`rmail-mode-hook'
+
+`rmail-retry-setup-hook'
+
+`rmail-summary-mode-hook'
+
+`scheme-indent-hook'
+
+`scheme-mode-hook'
+
+`scribe-mode-hook'
+
+`select-frame-hook'
+
+`send-mail-function'
+
+`shell-mode-hook'
+
+`shell-set-directory-error-hook'
+
+`special-display-function'
+
+`suspend-hook'
+
+`suspend-resume-hook'
+
+`temp-buffer-show-function'
+
+`term-setup-hook'
+
+`terminal-mode-hook'
+
+`terminal-mode-break-hook'
+
+`TeX-mode-hook'
+
+`tex-mode-hook'
+
+`text-mode-hook'
+
+`today-visible-calendar-hook'
+
+`today-invisible-calendar-hook'
+
+`tooltalk-message-handler-hook'
+
+`tooltalk-pattern-handler-hook'
+
+`tooltalk-unprocessed-message-hook'
+
+`unmap-frame-hook'
+
+`vc-checkin-hook'
+
+`vc-checkout-writable-buffer-hook'
+
+`vc-log-after-operation-hook'
+
+`vc-make-buffer-writable-hook'
+
+`view-hook'
+
+`vm-arrived-message-hook'
+
+`vm-arrived-messages-hook'
+
+`vm-chop-full-name-function'
+
+`vm-display-buffer-hook'
+
+`vm-edit-message-hook'
+
+`vm-forward-message-hook'
+
+`vm-iconify-frame-hook'
+
+`vm-inhibit-write-file-hook'
+
+`vm-key-functions'
+
+`vm-mail-hook'
+
+`vm-mail-mode-hook'
+
+`vm-menu-setup-hook'
+
+`vm-mode-hook'
+
+`vm-quit-hook'
+
+`vm-rename-current-buffer-function'
+
+`vm-reply-hook'
+
+`vm-resend-bounced-message-hook'
+
+`vm-resend-message-hook'
+
+`vm-retrieved-spooled-mail-hook'
+
+`vm-select-message-hook'
+
+`vm-select-new-message-hook'
+
+`vm-select-unread-message-hook'
+
+`vm-send-digest-hook'
+
+`vm-summary-mode-hook'
+
+`vm-summary-pointer-update-hook'
+
+`vm-summary-redo-hook'
+
+`vm-summary-update-hook'
+
+`vm-undisplay-buffer-hook'
+
+`vm-visit-folder-hook'
+
+`window-setup-hook'
+
+`write-contents-hooks'
+
+`write-file-data-hooks'
+
+`write-file-hooks'
+
+`write-region-annotate-functions'
+
+`x-lost-selection-hooks'
+
+`x-sent-selection-hooks'
+
+`zmacs-activate-region-hook'
+
+`zmacs-deactivate-region-hook'
+
+`zmacs-update-region-hook'

 
 

diff --git a/info/lispref.info-9 b/info/lispref.info-9
index 5e15da6..715274f 100644 (file)
--- a/info/lispref.info-9
+++ b/info/lispref.info-9
@@ -1,4 +1,4 @@
-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from

 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,1157 +50,3499 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
 Foundation instead of in the original English.
 
 \1f

-File: lispref.info,  Node: Handling Errors,  Next: Error Symbols,  Prev: Processing of Errors,  Up: Errors
+File: lispref.info,  Node: Index,  Prev: Standard Hooks,  Up: Top

 
 

-Writing Code to Handle Errors
-.............................
-
-   The usual effect of signaling an error is to terminate the command
-that is running and return immediately to the XEmacs editor command
-loop.  You can arrange to trap errors occurring in a part of your
-program by establishing an error handler, with the special form
-`condition-case'.  A simple example looks like this:
-
-     (condition-case nil
-         (delete-file filename)
-       (error nil))
-
-This deletes the file named FILENAME, catching any error and returning
-`nil' if an error occurs.
-
-   The second argument of `condition-case' is called the "protected
-form".  (In the example above, the protected form is a call to
-`delete-file'.)  The error handlers go into effect when this form
-begins execution and are deactivated when this form returns.  They
-remain in effect for all the intervening time.  In particular, they are
-in effect during the execution of functions called by this form, in
-their subroutines, and so on.  This is a good thing, since, strictly
-speaking, errors can be signaled only by Lisp primitives (including
-`signal' and `error') called by the protected form, not by the
-protected form itself.
-
-   The arguments after the protected form are handlers.  Each handler
-lists one or more "condition names" (which are symbols) to specify
-which errors it will handle.  The error symbol specified when an error
-is signaled also defines a list of condition names.  A handler applies
-to an error if they have any condition names in common.  In the example
-above, there is one handler, and it specifies one condition name,
-`error', which covers all errors.
-
-   The search for an applicable handler checks all the established
-handlers starting with the most recently established one.  Thus, if two
-nested `condition-case' forms offer to handle the same error, the inner
-of the two will actually handle it.
-
-   When an error is handled, control returns to the handler.  Before
-this happens, XEmacs unbinds all variable bindings made by binding
-constructs that are being exited and executes the cleanups of all
-`unwind-protect' forms that are exited.  Once control arrives at the
-handler, the body of the handler is executed.
-
-   After execution of the handler body, execution continues by returning
-from the `condition-case' form.  Because the protected form is exited
-completely before execution of the handler, the handler cannot resume
-execution at the point of the error, nor can it examine variable
-bindings that were made within the protected form.  All it can do is
-clean up and proceed.
-
-   `condition-case' is often used to trap errors that are predictable,
-such as failure to open a file in a call to `insert-file-contents'.  It
-is also used to trap errors that are totally unpredictable, such as
-when the program evaluates an expression read from the user.
-
-   Even when an error is handled, the debugger may still be called if
-the variable `debug-on-signal' (*note Error Debugging::) is non-`nil'.
-Note that this may yield unpredictable results with code that traps
-expected errors as normal part of its operation.  Do not set
-`debug-on-signal' unless you know what you are doing.
-
-   Error signaling and handling have some resemblance to `throw' and
-`catch', but they are entirely separate facilities.  An error cannot be
-caught by a `catch', and a `throw' cannot be handled by an error
-handler (though using `throw' when there is no suitable `catch' signals
-an error that can be handled).
-
- - Special Form: condition-case var protected-form handlers...
-     This special form establishes the error handlers HANDLERS around
-     the execution of PROTECTED-FORM.  If PROTECTED-FORM executes
-     without error, the value it returns becomes the value of the
-     `condition-case' form; in this case, the `condition-case' has no
-     effect.  The `condition-case' form makes a difference when an
-     error occurs during PROTECTED-FORM.
-
-     Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
-     Here CONDITIONS is an error condition name to be handled, or a
-     list of condition names; BODY is one or more Lisp expressions to
-     be executed when this handler handles an error.  Here are examples
-     of handlers:
-
-          (error nil)
-          
-          (arith-error (message "Division by zero"))
-          
-          ((arith-error file-error)
-           (message
-            "Either division by zero or failure to open a file"))
-
-     Each error that occurs has an "error symbol" that describes what
-     kind of error it is.  The `error-conditions' property of this
-     symbol is a list of condition names (*note Error Symbols::).  Emacs
-     searches all the active `condition-case' forms for a handler that
-     specifies one or more of these condition names; the innermost
-     matching `condition-case' handles the error.  Within this
-     `condition-case', the first applicable handler handles the error.
-
-     After executing the body of the handler, the `condition-case'
-     returns normally, using the value of the last form in the handler
-     body as the overall value.
-
-     The argument VAR is a variable.  `condition-case' does not bind
-     this variable when executing the PROTECTED-FORM, only when it
-     handles an error.  At that time, it binds VAR locally to a list of
-     the form `(ERROR-SYMBOL . DATA)', giving the particulars of the
-     error.  The handler can refer to this list to decide what to do.
-     For example, if the error is for failure opening a file, the file
-     name is the second element of DATA--the third element of VAR.
-
-     If VAR is `nil', that means no variable is bound.  Then the error
-     symbol and associated data are not available to the handler.
-
-   Here is an example of using `condition-case' to handle the error
-that results from dividing by zero.  The handler prints out a warning
-message and returns a very large number.
-
-     (defun safe-divide (dividend divisor)
-       (condition-case err
-           ;; Protected form.
-           (/ dividend divisor)
-         ;; The handler.
-         (arith-error                        ; Condition.
-          (princ (format "Arithmetic error: %s" err))
-          1000000)))
-     => safe-divide
-     
-     (safe-divide 5 0)
-          -| Arithmetic error: (arith-error)
-     => 1000000
-
-The handler specifies condition name `arith-error' so that it will
-handle only division-by-zero errors.  Other kinds of errors will not be
-handled, at least not by this `condition-case'.  Thus,
-
-     (safe-divide nil 3)
-          error--> Wrong type argument: integer-or-marker-p, nil
-
-   Here is a `condition-case' that catches all kinds of errors,
-including those signaled with `error':
-
-     (setq baz 34)
-          => 34
-     
-     (condition-case err
-         (if (eq baz 35)
-             t
-           ;; This is a call to the function `error'.
-           (error "Rats!  The variable %s was %s, not 35" 'baz baz))
-       ;; This is the handler; it is not a form.
-       (error (princ (format "The error was: %s" err))
-              2))
-     -| The error was: (error "Rats!  The variable baz was 34, not 35")
-     => 2
-
-\1f
-File: lispref.info,  Node: Error Symbols,  Prev: Handling Errors,  Up: Errors
-
-Error Symbols and Condition Names
-.................................
-
-   When you signal an error, you specify an "error symbol" to specify
-the kind of error you have in mind.  Each error has one and only one
-error symbol to categorize it.  This is the finest classification of
-errors defined by the XEmacs Lisp language.
-
-   These narrow classifications are grouped into a hierarchy of wider
-classes called "error conditions", identified by "condition names".
-The narrowest such classes belong to the error symbols themselves: each
-error symbol is also a condition name.  There are also condition names
-for more extensive classes, up to the condition name `error' which
-takes in all kinds of errors.  Thus, each error has one or more
-condition names: `error', the error symbol if that is distinct from
-`error', and perhaps some intermediate classifications.
-
-   In other words, each error condition "inherits" from another error
-condition, with `error' sitting at the top of the inheritance hierarchy.
-
- - Function: define-error error-symbol error-message &optional
-          inherits-from
-     This function defines a new error, denoted by ERROR-SYMBOL.
-     ERROR-MESSAGE is an informative message explaining the error, and
-     will be printed out when an unhandled error occurs.  ERROR-SYMBOL
-     is a sub-error of INHERITS-FROM (which defaults to `error').
-
-     `define-error' internally works by putting on ERROR-SYMBOL an
-     `error-message' property whose value is ERROR-MESSAGE, and an
-     `error-conditions' property that is a list of ERROR-SYMBOL
-     followed by each of its super-errors, up to and including `error'.
-     You will sometimes see code that sets this up directly rather than
-     calling `define-error', but you should _not_ do this yourself,
-     unless you wish to maintain compatibility with FSF Emacs, which
-     does not provide `define-error'.
-
-   Here is how we define a new error symbol, `new-error', that belongs
-to a range of errors called `my-own-errors':
-
-     (define-error 'my-own-errors "A whole range of errors" 'error)
-     (define-error 'new-error "A new error" 'my-own-errors)
-
-`new-error' has three condition names: `new-error', the narrowest
-classification; `my-own-errors', which we imagine is a wider
-classification; and `error', which is the widest of all.
-
-   Note that it is not legal to try to define an error unless its
-super-error is also defined.  For instance, attempting to define
-`new-error' before `my-own-errors' are defined will signal an error.
-
-   The error string should start with a capital letter but it should
-not end with a period.  This is for consistency with the rest of Emacs.
-
-   Naturally, XEmacs will never signal `new-error' on its own; only an
-explicit call to `signal' (*note Signaling Errors::) in your code can
-do this:
-
-     (signal 'new-error '(x y))
-          error--> A new error: x, y
-
-   This error can be handled through any of the three condition names.
-This example handles `new-error' and any other errors in the class
-`my-own-errors':
-
-     (condition-case foo
-         (bar nil t)
-       (my-own-errors nil))
-
-   The significant way that errors are classified is by their condition
-names--the names used to match errors with handlers.  An error symbol
-serves only as a convenient way to specify the intended error message
-and list of condition names.  It would be cumbersome to give `signal' a
-list of condition names rather than one error symbol.
-
-   By contrast, using only error symbols without condition names would
-seriously decrease the power of `condition-case'.  Condition names make
-it possible to categorize errors at various levels of generality when
-you write an error handler.  Using error symbols alone would eliminate
-all but the narrowest level of classification.
-
-   *Note Standard Errors::, for a list of all the standard error symbols
-and their conditions.
-
-\1f
-File: lispref.info,  Node: Cleanups,  Prev: Errors,  Up: Nonlocal Exits
-
-Cleaning Up from Nonlocal Exits
--------------------------------
-
-   The `unwind-protect' construct is essential whenever you temporarily
-put a data structure in an inconsistent state; it permits you to ensure
-the data are consistent in the event of an error or throw.
-
- - Special Form: unwind-protect body cleanup-forms...
-     `unwind-protect' executes the BODY with a guarantee that the
-     CLEANUP-FORMS will be evaluated if control leaves BODY, no matter
-     how that happens.  The BODY may complete normally, or execute a
-     `throw' out of the `unwind-protect', or cause an error; in all
-     cases, the CLEANUP-FORMS will be evaluated.
-
-     If the BODY forms finish normally, `unwind-protect' returns the
-     value of the last BODY form, after it evaluates the CLEANUP-FORMS.
-     If the BODY forms do not finish, `unwind-protect' does not return
-     any value in the normal sense.
-
-     Only the BODY is actually protected by the `unwind-protect'.  If
-     any of the CLEANUP-FORMS themselves exits nonlocally (e.g., via a
-     `throw' or an error), `unwind-protect' is _not_ guaranteed to
-     evaluate the rest of them.  If the failure of one of the
-     CLEANUP-FORMS has the potential to cause trouble, then protect it
-     with another `unwind-protect' around that form.
-
-     The number of currently active `unwind-protect' forms counts,
-     together with the number of local variable bindings, against the
-     limit `max-specpdl-size' (*note Local Variables::).
-
-   For example, here we make an invisible buffer for temporary use, and
-make sure to kill it before finishing:
-
-     (save-excursion
-       (let ((buffer (get-buffer-create " *temp*")))
-         (set-buffer buffer)
-         (unwind-protect
-             BODY
-           (kill-buffer buffer))))
-
-You might think that we could just as well write `(kill-buffer
-(current-buffer))' and dispense with the variable `buffer'.  However,
-the way shown above is safer, if BODY happens to get an error after
-switching to a different buffer!  (Alternatively, you could write
-another `save-excursion' around the body, to ensure that the temporary
-buffer becomes current in time to kill it.)
-
-   Here is an actual example taken from the file `ftp.el'.  It creates
-a process (*note Processes::) to try to establish a connection to a
-remote machine.  As the function `ftp-login' is highly susceptible to
-numerous problems that the writer of the function cannot anticipate, it
-is protected with a form that guarantees deletion of the process in the
-event of failure.  Otherwise, XEmacs might fill up with useless
-subprocesses.
-
-     (let ((win nil))
-       (unwind-protect
-           (progn
-             (setq process (ftp-setup-buffer host file))
-             (if (setq win (ftp-login process host user password))
-                 (message "Logged in")
-               (error "Ftp login failed")))
-         (or win (and process (delete-process process)))))
-
-   This example actually has a small bug: if the user types `C-g' to
-quit, and the quit happens immediately after the function
-`ftp-setup-buffer' returns but before the variable `process' is set,
-the process will not be killed.  There is no easy way to fix this bug,
-but at least it is very unlikely.
-
-   Here is another example which uses `unwind-protect' to make sure to
-kill a temporary buffer.  In this example, the value returned by
-`unwind-protect' is used.
-
-     (defun shell-command-string (cmd)
-       "Return the output of the shell command CMD, as a string."
-       (save-excursion
-         (set-buffer (generate-new-buffer " OS*cmd"))
-         (shell-command cmd t)
-         (unwind-protect
-             (buffer-string)
-           (kill-buffer (current-buffer)))))
-
-\1f
-File: lispref.info,  Node: Variables,  Next: Functions,  Prev: Control Structures,  Up: Top
-
-Variables
-*********
-
-   A "variable" is a name used in a program to stand for a value.
-Nearly all programming languages have variables of some sort.  In the
-text of a Lisp program, variables are written using the syntax for
-symbols.
-
-   In Lisp, unlike most programming languages, programs are represented
-primarily as Lisp objects and only secondarily as text.  The Lisp
-objects used for variables are symbols: the symbol name is the variable
-name, and the variable's value is stored in the value cell of the
-symbol.  The use of a symbol as a variable is independent of its use as
-a function name.  *Note Symbol Components::.
-
-   The Lisp objects that constitute a Lisp program determine the textual
-form of the program--it is simply the read syntax for those Lisp
-objects.  This is why, for example, a variable in a textual Lisp program
-is written using the read syntax for the symbol that represents the
-variable.
+Index
+*****

 
 * Menu:
 
 
 * Menu:
 

-* 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.
-* Variable Aliases::     Making one variable point to another.
-
-\1f
-File: lispref.info,  Node: Global Variables,  Next: Constant Variables,  Up: Variables
-
-Global Variables
-================
-
-   The simplest way to use a variable is "globally".  This means that
-the variable has just one value at a time, and this value is in effect
-(at least for the moment) throughout the Lisp system.  The value remains
-in effect until you specify a new one.  When a new value replaces the
-old one, no trace of the old value remains in the variable.
-
-   You specify a value for a symbol with `setq'.  For example,
-
-     (setq x '(a b))
-
-gives the variable `x' the value `(a b)'.  Note that `setq' does not
-evaluate its first argument, the name of the variable, but it does
-evaluate the second argument, the new value.
-
-   Once the variable has a value, you can refer to it by using the
-symbol by itself as an expression.  Thus,
-
-     x => (a b)
-
-assuming the `setq' form shown above has already been executed.
-
-   If you do another `setq', the new value replaces the old one:
-
-     x
-          => (a b)
-     (setq x 4)
-          => 4
-     x
-          => 4
-
-\1f
-File: lispref.info,  Node: Constant Variables,  Next: Local Variables,  Prev: Global Variables,  Up: Variables
-
-Variables That Never Change
-===========================
-
-   In XEmacs Lisp, some symbols always evaluate to themselves: the two
-special symbols `nil' and `t', as well as "keyword symbols", that is,
-symbols whose name begins with the character ``:''.  These symbols
-cannot be rebound, nor can their value cells be changed.  An attempt to
-change the value of `nil' or `t' signals a `setting-constant' error.
-
-     nil == 'nil
-          => nil
-     (setq nil 500)
-     error--> Attempt to set constant symbol: nil
-
-\1f
-File: lispref.info,  Node: Local Variables,  Next: Void Variables,  Prev: Constant Variables,  Up: Variables
-
-Local Variables
-===============
-
-   Global variables have values that last until explicitly superseded
-with new values.  Sometimes it is useful to create variable values that
-exist temporarily--only while within a certain part of the program.
-These values are called "local", and the variables so used are called
-"local variables".
-
-   For example, when a function is called, its argument variables
-receive new local values that last until the function exits.  The `let'
-special form explicitly establishes new local values for specified
-variables; these last until exit from the `let' form.
-
-   Establishing a local value saves away the previous value (or lack of
-one) of the variable.  When the life span of the local value is over,
-the previous value is restored.  In the mean time, we say that the
-previous value is "shadowed" and "not visible".  Both global and local
-values may be shadowed (*note Scope::).
-
-   If you set a variable (such as with `setq') while it is local, this
-replaces the local value; it does not alter the global value, or
-previous local values that are shadowed.  To model this behavior, we
-speak of a "local binding" of the variable as well as a local value.
-
-   The local binding is a conceptual place that holds a local value.
-Entry to a function, or a special form such as `let', creates the local
-binding; exit from the function or from the `let' removes the local
-binding.  As long as the local binding lasts, the variable's value is
-stored within it.  Use of `setq' or `set' while there is a local
-binding stores a different value into the local binding; it does not
-create a new binding.
-
-   We also speak of the "global binding", which is where (conceptually)
-the global value is kept.
-
-   A variable can have more than one local binding at a time (for
-example, if there are nested `let' forms that bind it).  In such a
-case, the most recently created local binding that still exists is the
-"current binding" of the variable.  (This is called "dynamic scoping";
-see *Note Variable Scoping::.)  If there are no local bindings, the
-variable's global binding is its current binding.  We also call the
-current binding the "most-local existing binding", for emphasis.
-Ordinary evaluation of a symbol always returns the value of its current
-binding.
-
-   The special forms `let' and `let*' exist to create local bindings.
-
- - Special Form: let (bindings...) forms...
-     This special form binds variables according to BINDINGS and then
-     evaluates all of the FORMS in textual order.  The `let'-form
-     returns the value of the last form in FORMS.
-
-     Each of the BINDINGS is either (i) a symbol, in which case that
-     symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL
-     VALUE-FORM)', in which case SYMBOL is bound to the result of
-     evaluating VALUE-FORM.  If VALUE-FORM is omitted, `nil' is used.
-
-     All of the VALUE-FORMs in BINDINGS are evaluated in the order they
-     appear and _before_ any of the symbols are bound.  Here is an
-     example of this: `Z' is bound to the old value of `Y', which is 2,
-     not the new value, 1.
-
-          (setq Y 2)
-               => 2
-          (let ((Y 1)
-                (Z Y))
-            (list Y Z))
-               => (1 2)
-
- - Special Form: let* (bindings...) forms...
-     This special form is like `let', but it binds each variable right
-     after computing its local value, before computing the local value
-     for the next variable.  Therefore, an expression in BINDINGS can
-     reasonably refer to the preceding symbols bound in this `let*'
-     form.  Compare the following example with the example above for
-     `let'.
-
-          (setq Y 2)
-               => 2
-          (let* ((Y 1)
-                 (Z Y))    ; Use the just-established value of `Y'.
-            (list Y Z))
-               => (1 1)
-
-   Here is a complete list of the other facilities that create local
-bindings:
-
-   * Function calls (*note Functions::).
-
-   * Macro calls (*note Macros::).
-
-   * `condition-case' (*note Errors::).
-
-   Variables can also have buffer-local bindings (*note Buffer-Local
-Variables::).  These kinds of bindings work somewhat like ordinary local
-bindings, but they are localized depending on "where" you are in Emacs,
-rather than localized in time.
-
- - Variable: max-specpdl-size
-     This variable defines the limit on the total number of local
-     variable bindings and `unwind-protect' cleanups (*note Nonlocal
-     Exits::) that are allowed before signaling an error (with data
-     `"Variable binding depth exceeds max-specpdl-size"').
-
-     This limit, with the associated error when it is exceeded, is one
-     way that Lisp avoids infinite recursion on an ill-defined function.
-
-     The default value is 3000.
-
-     `max-lisp-eval-depth' provides another limit on depth of nesting.
-     *Note Eval::.
-
-\1f
-File: lispref.info,  Node: Void Variables,  Next: Defining Variables,  Prev: Local Variables,  Up: Variables
-
-When a Variable is "Void"
-=========================
-
-   If you have never given a symbol any value as a global variable, we
-say that that symbol's global value is "void".  In other words, the
-symbol's value cell does not have any Lisp object in it.  If you try to
-evaluate the symbol, you get a `void-variable' error rather than a
-value.
-
-   Note that a value of `nil' is not the same as void.  The symbol
-`nil' is a Lisp object and can be the value of a variable just as any
-other object can be; but it is _a value_.  A void variable does not
-have any value.
-
-   After you have given a variable a value, you can make it void once
-more using `makunbound'.
-
- - Function: makunbound symbol
-     This function makes the current binding of SYMBOL void.
-     Subsequent attempts to use this symbol's value as a variable will
-     signal the error `void-variable', unless or until you set it again.
-
-     `makunbound' returns SYMBOL.
-
-          (makunbound 'x)      ; Make the global value
-                               ;   of `x' void.
-               => x
-          x
-          error--> Symbol's value as variable is void: x
-
-     If SYMBOL is locally bound, `makunbound' affects the most local
-     existing binding.  This is the only way a symbol can have a void
-     local binding, since all the constructs that create local bindings
-     create them with values.  In this case, the voidness lasts at most
-     as long as the binding does; when the binding is removed due to
-     exit from the construct that made it, the previous or global
-     binding is reexposed as usual, and the variable is no longer void
-     unless the newly reexposed binding was void all along.
-
-          (setq x 1)               ; Put a value in the global binding.
-               => 1
-          (let ((x 2))             ; Locally bind it.
-            (makunbound 'x)        ; Void the local binding.
-            x)
-          error--> Symbol's value as variable is void: x
-          x                        ; The global binding is unchanged.
-               => 1
-          
-          (let ((x 2))             ; Locally bind it.
-            (let ((x 3))           ; And again.
-              (makunbound 'x)      ; Void the innermost-local binding.
-              x))                  ; And refer: it's void.
-          error--> Symbol's value as variable is void: x
-          
-          (let ((x 2))
-            (let ((x 3))
-              (makunbound 'x))     ; Void inner binding, then remove it.
-            x)                     ; Now outer `let' binding is visible.
-               => 2
-
-   A variable that has been made void with `makunbound' is
-indistinguishable from one that has never received a value and has
-always been void.
-
-   You can use the function `boundp' to test whether a variable is
-currently void.
-
- - Function: boundp variable
-     `boundp' returns `t' if VARIABLE (a symbol) is not void; more
-     precisely, if its current binding is not void.  It returns `nil'
-     otherwise.
-
-          (boundp 'abracadabra)          ; Starts out void.
-               => nil
-          (let ((abracadabra 5))         ; Locally bind it.
-            (boundp 'abracadabra))
-               => t
-          (boundp 'abracadabra)          ; Still globally void.
-               => nil
-          (setq abracadabra 5)           ; Make it globally nonvoid.
-               => 5
-          (boundp 'abracadabra)
-               => t
-
-\1f
-File: lispref.info,  Node: Defining Variables,  Next: Accessing Variables,  Prev: Void Variables,  Up: Variables
-
-Defining Global Variables
-=========================
-
-   You may announce your intention to use a symbol as a global variable
-with a "variable definition": a special form, either `defconst' or
-`defvar'.
-
-   In XEmacs Lisp, definitions serve three purposes.  First, they inform
-people who read the code that certain symbols are _intended_ to be used
-a certain way (as variables).  Second, they inform the Lisp system of
-these things, supplying a value and documentation.  Third, they provide
-information to utilities such as `etags' and `make-docfile', which
-create data bases of the functions and variables in a program.
-
-   The difference between `defconst' and `defvar' is primarily a matter
-of intent, serving to inform human readers of whether programs will
-change the variable.  XEmacs Lisp does not restrict the ways in which a
-variable can be used based on `defconst' or `defvar' declarations.
-However, it does make a difference for initialization: `defconst'
-unconditionally initializes the variable, while `defvar' initializes it
-only if it is void.
-
-   One would expect user option variables to be defined with
-`defconst', since programs do not change them.  Unfortunately, this has
-bad results if the definition is in a library that is not preloaded:
-`defconst' would override any prior value when the library is loaded.
-Users would like to be able to set user options in their init files,
-and override the default values given in the definitions.  For this
-reason, user options must be defined with `defvar'.
-
- - Special Form: defvar symbol [value [doc-string]]
-     This special form defines SYMBOL as a value and initializes it.
-     The definition informs a person reading your code that SYMBOL is
-     used as a variable that programs are likely to set or change.  It
-     is also used for all user option variables except in the preloaded
-     parts of XEmacs.  Note that SYMBOL is not evaluated; the symbol to
-     be defined must appear explicitly in the `defvar'.
-
-     If SYMBOL already has a value (i.e., it is not void), VALUE is not
-     even evaluated, and SYMBOL's value remains unchanged.  If SYMBOL
-     is void and VALUE is specified, `defvar' evaluates it and sets
-     SYMBOL to the result.  (If VALUE is omitted, the value of SYMBOL
-     is not changed in any case.)
-
-     When you evaluate a top-level `defvar' form with `C-M-x' in Emacs
-     Lisp mode (`eval-defun'), a special feature of `eval-defun'
-     evaluates it as a `defconst'.  The purpose of this is to make sure
-     the variable's value is reinitialized, when you ask for it
-     specifically.
-
-     If SYMBOL has a buffer-local binding in the current buffer,
-     `defvar' sets the default value, not the local value.  *Note
-     Buffer-Local Variables::.
-
-     If the DOC-STRING argument appears, it specifies the documentation
-     for the variable.  (This opportunity to specify documentation is
-     one of the main benefits of defining the variable.)  The
-     documentation is stored in the symbol's `variable-documentation'
-     property.  The XEmacs help functions (*note Documentation::) look
-     for this property.
-
-     If the first character of DOC-STRING is `*', it means that this
-     variable is considered a user option.  This lets users set the
-     variable conveniently using the commands `set-variable' and
-     `edit-options'.
-
-     For example, this form defines `foo' but does not set its value:
-
-          (defvar foo)
-               => foo
-
-     The following example sets the value of `bar' to `23', and gives
-     it a documentation string:
-
-          (defvar bar 23
-            "The normal weight of a bar.")
-               => bar
-
-     The following form changes the documentation string for `bar',
-     making it a user option, but does not change the value, since `bar'
-     already has a value.  (The addition `(1+ 23)' is not even
-     performed.)
-
-          (defvar bar (1+ 23)
-            "*The normal weight of a bar.")
-               => bar
-          bar
-               => 23
-
-     Here is an equivalent expression for the `defvar' special form:
-
-          (defvar SYMBOL VALUE DOC-STRING)
-          ==
-          (progn
-            (if (not (boundp 'SYMBOL))
-                (setq SYMBOL VALUE))
-            (put 'SYMBOL 'variable-documentation 'DOC-STRING)
-            'SYMBOL)
-
-     The `defvar' form returns SYMBOL, but it is normally used at top
-     level in a file where its value does not matter.
-
- - Special Form: defconst symbol [value [doc-string]]
-     This special form defines SYMBOL as a value and initializes it.
-     It informs a person reading your code that SYMBOL has a global
-     value, established here, that will not normally be changed or
-     locally bound by the execution of the program.  The user, however,
-     may be welcome to change it.  Note that SYMBOL is not evaluated;
-     the symbol to be defined must appear explicitly in the `defconst'.
-
-     `defconst' always evaluates VALUE and sets the global value of
-     SYMBOL to the result, provided VALUE is given.  If SYMBOL has a
-     buffer-local binding in the current buffer, `defconst' sets the
-     default value, not the local value.
-
-     *Please note:* Don't use `defconst' for user option variables in
-     libraries that are not standardly preloaded.  The user should be
-     able to specify a value for such a variable in the `.emacs' file,
-     so that it will be in effect if and when the library is loaded
-     later.
-
-     Here, `pi' is a constant that presumably ought not to be changed
-     by anyone (attempts by the Indiana State Legislature
-     notwithstanding).  As the second form illustrates, however, this
-     is only advisory.
-
-          (defconst pi 3.1415 "Pi to five places.")
-               => pi
-          (setq pi 3)
-               => pi
-          pi
-               => 3
-
- - Function: user-variable-p variable
-     This function returns `t' if VARIABLE is a user option--a variable
-     intended to be set by the user for customization--and `nil'
-     otherwise.  (Variables other than user options exist for the
-     internal purposes of Lisp programs, and users need not know about
-     them.)
-
-     User option variables are distinguished from other variables by the
-     first character of the `variable-documentation' property.  If the
-     property exists and is a string, and its first character is `*',
-     then the variable is a user option.
-
-   If a user option variable has a `variable-interactive' property, the
-`set-variable' command uses that value to control reading the new value
-for the variable.  The property's value is used as if it were the
-argument to `interactive'.
-
-   *Warning:* If the `defconst' and `defvar' special forms are used
-while the variable has a local binding, they set the local binding's
-value; the global binding is not changed.  This is not what we really
-want.  To prevent it, use these special forms at top level in a file,
-where normally no local binding is in effect, and make sure to load the
-file before making a local binding for the variable.
-
-\1f
-File: lispref.info,  Node: Accessing Variables,  Next: Setting Variables,  Prev: Defining Variables,  Up: Variables
-
-Accessing Variable Values
-=========================
-
-   The usual way to reference a variable is to write the symbol which
-names it (*note Symbol Forms::).  This requires you to specify the
-variable name when you write the program.  Usually that is exactly what
-you want to do.  Occasionally you need to choose at run time which
-variable to reference; then you can use `symbol-value'.
-
- - Function: symbol-value symbol
-     This function returns the value of SYMBOL.  This is the value in
-     the innermost local binding of the symbol, or its global value if
-     it has no local bindings.
-
-          (setq abracadabra 5)
-               => 5
-          (setq foo 9)
-               => 9
-          
-          ;; Here the symbol `abracadabra'
-          ;;   is the symbol whose value is examined.
-          (let ((abracadabra 'foo))
-            (symbol-value 'abracadabra))
-               => foo
-          
-          ;; Here the value of `abracadabra',
-          ;;   which is `foo',
-          ;;   is the symbol whose value is examined.
-          (let ((abracadabra 'foo))
-            (symbol-value abracadabra))
-               => 9
-          
-          (symbol-value 'abracadabra)
-               => 5
-
-     A `void-variable' error is signaled if SYMBOL has neither a local
-     binding nor a global value.
-
-\1f
-File: lispref.info,  Node: Setting Variables,  Next: Variable Scoping,  Prev: Accessing Variables,  Up: Variables
-
-How to Alter a Variable Value
-=============================
-
-   The usual way to change the value of a variable is with the special
-form `setq'.  When you need to compute the choice of variable at run
-time, use the function `set'.
-
- - Special Form: setq [symbol form]...
-     This special form is the most common method of changing a
-     variable's value.  Each SYMBOL is given a new value, which is the
-     result of evaluating the corresponding FORM.  The most-local
-     existing binding of the symbol is changed.
-
-     `setq' does not evaluate SYMBOL; it sets the symbol that you
-     write.  We say that this argument is "automatically quoted".  The
-     `q' in `setq' stands for "quoted."
-
-     The value of the `setq' form is the value of the last FORM.
-
-          (setq x (1+ 2))
-               => 3
-          x                   ; `x' now has a global value.
-               => 3
-          (let ((x 5))
-            (setq x 6)        ; The local binding of `x' is set.
-            x)
-               => 6
-          x                   ; The global value is unchanged.
-               => 3
-
-     Note that the first FORM is evaluated, then the first SYMBOL is
-     set, then the second FORM is evaluated, then the second SYMBOL is
-     set, and so on:
-
-          (setq x 10          ; Notice that `x' is set before
-                y (1+ x))     ;   the value of `y' is computed.
-               => 11
-
- - Function: set symbol value
-     This function sets SYMBOL's value to VALUE, then returns VALUE.
-     Since `set' is a function, the expression written for SYMBOL is
-     evaluated to obtain the symbol to set.
-
-     The most-local existing binding of the variable is the binding
-     that is set; shadowed bindings are not affected.
-
-          (set one 1)
-          error--> Symbol's value as variable is void: one
-          (set 'one 1)
-               => 1
-          (set 'two 'one)
-               => one
-          (set two 2)         ; `two' evaluates to symbol `one'.
-               => 2
-          one                 ; So it is `one' that was set.
-               => 2
-          (let ((one 1))      ; This binding of `one' is set,
-            (set 'one 3)      ;   not the global value.
-            one)
-               => 3
-          one
-               => 2
-
-     If SYMBOL is not actually a symbol, a `wrong-type-argument' error
-     is signaled.
-
-          (set '(x y) 'z)
-          error--> Wrong type argument: symbolp, (x y)
-
-     Logically speaking, `set' is a more fundamental primitive than
-     `setq'.  Any use of `setq' can be trivially rewritten to use
-     `set'; `setq' could even be defined as a macro, given the
-     availability of `set'.  However, `set' itself is rarely used;
-     beginners hardly need to know about it.  It is useful only for
-     choosing at run time which variable to set.  For example, the
-     command `set-variable', which reads a variable name from the user
-     and then sets the variable, needs to use `set'.
-
-          Common Lisp note: In Common Lisp, `set' always changes the
-          symbol's special value, ignoring any lexical bindings.  In
-          XEmacs Lisp, all variables and all bindings are (in effect)
-          special, so `set' always affects the most local existing
-          binding.
-
-   One other function for setting a variable is designed to add an
-element to a list if it is not already present in the list.
-
- - Function: add-to-list symbol element
-     This function sets the variable SYMBOL by consing ELEMENT onto the
-     old value, if ELEMENT is not already a member of that value.  It
-     returns the resulting list, whether updated or not.  The value of
-     SYMBOL had better be a list already before the call.
-
-     The argument SYMBOL is not implicitly quoted; `add-to-list' is an
-     ordinary function, like `set' and unlike `setq'.  Quote the
-     argument yourself if that is what you want.
-
-     Here's a scenario showing how to use `add-to-list':
-
-          (setq foo '(a b))
-               => (a b)
-          
-          (add-to-list 'foo 'c)     ;; Add `c'.
-               => (c a b)
-          
-          (add-to-list 'foo 'b)     ;; No effect.
-               => (c a b)
-          
-          foo                       ;; `foo' was changed.
-               => (c a b)
-
-   An equivalent expression for `(add-to-list 'VAR VALUE)' is this:
-
-     (or (member VALUE VAR)
-         (setq VAR (cons VALUE VAR)))
-
-\1f
-File: lispref.info,  Node: Variable Scoping,  Next: Buffer-Local Variables,  Prev: Setting Variables,  Up: Variables
-
-Scoping Rules for Variable Bindings
-===================================
-
-   A given symbol `foo' may have several local variable bindings,
-established at different places in the Lisp program, as well as a global
-binding.  The most recently established binding takes precedence over
-the others.
-
-   Local bindings in XEmacs Lisp have "indefinite scope" and "dynamic
-extent".  "Scope" refers to _where_ textually in the source code the
-binding can be accessed.  Indefinite scope means that any part of the
-program can potentially access the variable binding.  "Extent" refers
-to _when_, as the program is executing, the binding exists.  Dynamic
-extent means that the binding lasts as long as the activation of the
-construct that established it.
-
-   The combination of dynamic extent and indefinite scope is called
-"dynamic scoping".  By contrast, most programming languages use
-"lexical scoping", in which references to a local variable must be
-located textually within the function or block that binds the variable.
-
-     Common Lisp note: Variables declared "special" in Common Lisp are
-     dynamically scoped, like variables in XEmacs Lisp.
-
-* Menu:
-
-* 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.
-
-\1f
-File: lispref.info,  Node: Scope,  Next: Extent,  Up: Variable Scoping
-
-Scope
------
-
-   XEmacs Lisp uses "indefinite scope" for local variable bindings.
-This means that any function anywhere in the program text might access a
-given binding of a variable.  Consider the following function
-definitions:
-
-     (defun binder (x)   ; `x' is bound in `binder'.
-        (foo 5))         ; `foo' is some other function.
-     
-     (defun user ()      ; `x' is used in `user'.
-       (list x))
-
-   In a lexically scoped language, the binding of `x' in `binder' would
-never be accessible in `user', because `user' is not textually
-contained within the function `binder'.  However, in dynamically scoped
-XEmacs Lisp, `user' may or may not refer to the binding of `x'
-established in `binder', depending on circumstances:
-
-   * If we call `user' directly without calling `binder' at all, then
-     whatever binding of `x' is found, it cannot come from `binder'.
-
-   * If we define `foo' as follows and call `binder', then the binding
-     made in `binder' will be seen in `user':
-
-          (defun foo (lose)
-            (user))
-
-   * If we define `foo' as follows and call `binder', then the binding
-     made in `binder' _will not_ be seen in `user':
-
-          (defun foo (x)
-            (user))
-
-     Here, when `foo' is called by `binder', it binds `x'.  (The
-     binding in `foo' is said to "shadow" the one made in `binder'.)
-     Therefore, `user' will access the `x' bound by `foo' instead of
-     the one bound by `binder'.
-
-\1f
-File: lispref.info,  Node: Extent,  Next: Impl of Scope,  Prev: Scope,  Up: Variable Scoping
-
-Extent
-------
-
-   "Extent" refers to the time during program execution that a variable
-name is valid.  In XEmacs Lisp, a variable is valid only while the form
-that bound it is executing.  This is called "dynamic extent".  "Local"
-or "automatic" variables in most languages, including C and Pascal,
-have dynamic extent.
-
-   One alternative to dynamic extent is "indefinite extent".  This
-means that a variable binding can live on past the exit from the form
-that made the binding.  Common Lisp and Scheme, for example, support
-this, but XEmacs Lisp does not.
-
-   To illustrate this, the function below, `make-add', returns a
-function that purports to add N to its own argument M.  This would work
-in Common Lisp, but it does not work as intended in XEmacs Lisp,
-because after the call to `make-add' exits, the variable `n' is no
-longer bound to the actual argument 2.
-
-     (defun make-add (n)
-         (function (lambda (m) (+ n m))))  ; Return a function.
-          => make-add
-     (fset 'add2 (make-add 2))  ; Define function `add2'
-                                ;   with `(make-add 2)'.
-          => (lambda (m) (+ n m))
-     (add2 4)                   ; Try to add 2 to 4.
-     error--> Symbol's value as variable is void: n
-
-   Some Lisp dialects have "closures", objects that are like functions
-but record additional variable bindings.  XEmacs Lisp does not have
-closures.
-
-\1f
-File: lispref.info,  Node: Impl of Scope,  Next: Using Scoping,  Prev: Extent,  Up: Variable Scoping
-
-Implementation of Dynamic Scoping
----------------------------------
-
-   A simple sample implementation (which is not how XEmacs Lisp actually
-works) may help you understand dynamic binding.  This technique is
-called "deep binding" and was used in early Lisp systems.
-
-   Suppose there is a stack of bindings: variable-value pairs.  At entry
-to a function or to a `let' form, we can push bindings on the stack for
-the arguments or local variables created there.  We can pop those
-bindings from the stack at exit from the binding construct.
-
-   We can find the value of a variable by searching the stack from top
-to bottom for a binding for that variable; the value from that binding
-is the value of the variable.  To set the variable, we search for the
-current binding, then store the new value into that binding.
-
-   As you can see, a function's bindings remain in effect as long as it
-continues execution, even during its calls to other functions.  That is
-why we say the extent of the binding is dynamic.  And any other function
-can refer to the bindings, if it uses the same variables while the
-bindings are in effect.  That is why we say the scope is indefinite.
-
-   The actual implementation of variable scoping in XEmacs Lisp uses a
-technique called "shallow binding".  Each variable has a standard place
-in which its current value is always found--the value cell of the
-symbol.
-
-   In shallow binding, setting the variable works by storing a value in
-the value cell.  Creating a new binding works by pushing the old value
-(belonging to a previous binding) on a stack, and storing the local
-value in the value cell.  Eliminating a binding works by popping the
-old value off the stack, into the value cell.
-
-   We use shallow binding because it has the same results as deep
-binding, but runs faster, since there is never a need to search for a
-binding.
-
-\1f
-File: lispref.info,  Node: Using Scoping,  Prev: Impl of Scope,  Up: Variable Scoping
-
-Proper Use of Dynamic Scoping
------------------------------
-
-   Binding a variable in one function and using it in another is a
-powerful technique, but if used without restraint, it can make programs
-hard to understand.  There are two clean ways to use this technique:
-
-   * Use or bind the variable only in a few related functions, written
-     close together in one file.  Such a variable is used for
-     communication within one program.
-
-     You should write comments to inform other programmers that they
-     can see all uses of the variable before them, and to advise them
-     not to add uses elsewhere.
-
-   * Give the variable a well-defined, documented meaning, and make all
-     appropriate functions refer to it (but not bind it or set it)
-     wherever that meaning is relevant.  For example, the variable
-     `case-fold-search' is defined as "non-`nil' means ignore case when
-     searching"; various search and replace functions refer to it
-     directly or through their subroutines, but do not bind or set it.
-
-     Then you can bind the variable in other programs, knowing reliably
-     what the effect will be.
-
-   In either case, you should define the variable with `defvar'.  This
-helps other people understand your program by telling them to look for
-inter-function usage.  It also avoids a warning from the byte compiler.
-Choose the variable's name to avoid name conflicts--don't use short
-names like `x'.
-
-\1f
-File: lispref.info,  Node: Buffer-Local Variables,  Next: Variable Aliases,  Prev: Variable Scoping,  Up: Variables
-
-Buffer-Local Variables
-======================
-
-   Global and local variable bindings are found in most programming
-languages in one form or another.  XEmacs also supports another, unusual
-kind of variable binding: "buffer-local" bindings, which apply only to
-one buffer.  XEmacs Lisp is meant for programming editing commands, and
-having different values for a variable in different buffers is an
-important customization method.
-
-* Menu:
+* " in printing:                         Output Functions.
+* " in strings:                          String Type.
+* #$:                                    Docs and Compilation.
+* #@COUNT:                               Docs and Compilation.
+* $ in display:                          Truncation.
+* $ in regexp:                           Syntax of Regexps.
+* %:                                     Arithmetic Operations.
+* % in format:                           Formatting Strings.
+* & in replacement:                      Replacing Match.
+* &define (Edebug):                      Specification List.
+* &not (Edebug):                         Specification List.
+* &optional:                             Argument List.
+* &optional (Edebug):                    Specification List.
+* &or (Edebug):                          Specification List.
+* &rest:                                 Argument List.
+* &rest (Edebug):                        Specification List.
+* ' for quoting:                         Quoting.
+* ( in regexp:                           Syntax of Regexps.
+* (...) in lists:                        Cons Cell Type.
+* ) in regexp:                           Syntax of Regexps.
+* *:                                     Arithmetic Operations.
+* * in interactive:                      Using Interactive.
+* * in regexp:                           Syntax of Regexps.
+* *? in regexp:                          Syntax of Regexps.
+* *PQfn:                                 Unimplemented libpq Functions.
+* *PQoidStatus:                          Unimplemented libpq Functions.
+* *PQsetdb:                              Unimplemented libpq Functions.
+* *PQsetdbLogin:                         Unimplemented libpq Functions.
+* *scratch*:                             Auto Major Mode.
+* +:                                     Arithmetic Operations.
+* + in regexp:                           Syntax of Regexps.
+* +? in regexp:                          Syntax of Regexps.
+* , (with Backquote):                    Backquote.
+* ,@ (with Backquote):                   Backquote.
+* -:                                     Arithmetic Operations.
+* . in lists:                            Dotted Pair Notation.
+* . in regexp:                           Syntax of Regexps.
+* .emacs:                                Init File.
+* .emacs customization:                  Major Mode Conventions.
+* /:                                     Arithmetic Operations.
+* /=:                                    Comparison of Numbers.
+* 1+:                                    Arithmetic Operations.
+* 1-:                                    Arithmetic Operations.
+* ; in comment:                          Comments.
+* <:                                     Comparison of Numbers.
+* <=:                                    Comparison of Numbers.
+* <ESC>:                                 Functions for Key Lookup.
+* =:                                     Comparison of Numbers.
+* >:                                     Comparison of Numbers.
+* >=:                                    Comparison of Numbers.
+* ? in character constant:               Character Type.
+* ? in regexp:                           Syntax of Regexps.
+* ?? in regexp:                          Syntax of Regexps.
+* @ in interactive:                      Using Interactive.
+* [ in regexp:                           Syntax of Regexps.
+* [...] (Edebug):                        Specification List.
+* \ in character constant:               Character Type.
+* \ in display:                          Truncation.
+* \ in printing:                         Output Functions.
+* \ in regexp:                           Syntax of Regexps.
+* \ in replacement:                      Replacing Match.
+* \ in strings:                          String Type.
+* \ in symbols:                          Symbol Type.
+* \' in regexp:                          Syntax of Regexps.
+* \(?: in regexp:                        Syntax of Regexps.
+* \< in regexp:                          Syntax of Regexps.
+* \= in regexp:                          Syntax of Regexps.
+* \> in regexp:                          Syntax of Regexps.
+* \` in regexp:                          Syntax of Regexps.
+* \a:                                    Character Type.
+* \b:                                    Character Type.
+* \B in regexp:                          Syntax of Regexps.
+* \b in regexp:                          Syntax of Regexps.
+* \e:                                    Character Type.
+* \f:                                    Character Type.
+* \n:                                    Character Type.
+* \n in print:                           Output Variables.
+* \N in replacement:                     Replacing Match.
+* \r:                                    Character Type.
+* \S in regexp:                          Syntax of Regexps.
+* \s in regexp:                          Syntax of Regexps.
+* \t:                                    Character Type.
+* \v:                                    Character Type.
+* \W in regexp:                          Syntax of Regexps.
+* \w in regexp:                          Syntax of Regexps.
+* \{n,m\} in regexp:                     Syntax of Regexps.
+* ] in regexp:                           Syntax of Regexps.
+* ^ in regexp:                           Syntax of Regexps.
+* _ in interactive:                      Using Interactive.
+* `:                                     Backquote.
+* ` (Edebug):                            Debugging Backquote.
+* ` (list substitution):                 Backquote.
+* abbrev:                                Abbrevs.
+* abbrev table:                          Abbrevs.
+* abbrev tables in modes:                Major Mode Conventions.
+* abbrev-all-caps:                       Abbrev Expansion.
+* abbrev-expansion:                      Abbrev Expansion.
+* abbrev-file-name:                      Abbrev Files.
+* abbrev-mode:                           Abbrev Mode.
+* abbrev-prefix-mark:                    Abbrev Expansion.
+* abbrev-start-location:                 Abbrev Expansion.
+* abbrev-start-location-buffer:          Abbrev Expansion.
+* abbrev-symbol:                         Abbrev Expansion.
+* abbrev-table-name-list:                Abbrev Tables.
+* abbreviate-file-name:                  Directory Names.
+* abbrevs-changed:                       Abbrev Files.
+* abort-recursive-edit:                  Recursive Editing.
+* aborting:                              Recursive Editing.
+* abs:                                   Arithmetic Operations.
+* absolute file name:                    Relative File Names.
+* accelerate-menu:                       Menu Accelerator Functions.
+* accept-process-output:                 Accepting Output.
+* accessibility of a file:               Testing Accessibility.
+* accessible portion (of a buffer):      Narrowing.
+* accessible-keymaps:                    Scanning Keymaps.
+* acos:                                  Math Functions.
+* acosh:                                 Math Functions.
+* activate-menubar-hook:                 Menubar.
+* activate-popup-menu-hook:              Pop-Up Menus.
+* active display table:                  Active Display Table.
+* active keymap:                         Active Keymaps.
+* active-minibuffer-window:              Minibuffer Misc.
+* add-abbrev:                            Defining Abbrevs.
+* add-hook:                              Hooks.
+* add-menu:                              Modifying Menus.
+* add-menu-button:                       Modifying Menus.
+* add-menu-item:                         Modifying Menus.
+* add-name-to-file:                      Changing File Attributes.
+* add-spec-list-to-specifier:            Adding Specifications.
+* add-spec-to-specifier:                 Adding Specifications.
+* add-submenu:                           Modifying Menus.
+* add-text-properties:                   Changing Properties.
+* add-timeout:                           Timers.
+* add-to-list:                           Setting Variables.
+* add-tooltalk-message-arg:              Elisp Interface for Sending Messages.
+* add-tooltalk-pattern-arg:              Elisp Interface for Receiving Messages.
+* add-tooltalk-pattern-attribute:        Elisp Interface for Receiving Messages.
+* adding a button to a toolbar:          Simple Specifier Usage.
+* address field of register:             Cons Cell Type.
+* after-change-function:                 Change Hooks.
+* after-change-functions:                Change Hooks.
+* after-find-file:                       Subroutines of Visiting.
+* after-init-hook:                       Init File.
+* after-insert-file-functions:           Saving Properties.
+* after-load-alist:                      Hooks for Loading.
+* after-revert-hook:                     Reverting.
+* after-save-hook:                       Saving Buffers.
+* aliases, for variables:                Variable Aliases.
+* alist:                                 Association Lists.
+* alist-to-plist:                        Converting Plists To/From Alists.
+* all-annotations:                       Locating Annotations.
+* all-completions:                       Basic Completion.
+* and:                                   Combining Conditions.
+* annotation:                            Annotations.
+* annotation hooks:                      Annotation Hooks.
+* annotation-action:                     Annotation Properties.
+* annotation-data:                       Annotation Properties.
+* annotation-down-glyph:                 Annotation Properties.
+* annotation-face:                       Annotation Properties.
+* annotation-glyph:                      Annotation Properties.
+* annotation-layout:                     Annotation Properties.
+* annotation-list:                       Locating Annotations.
+* annotation-menu:                       Annotation Properties.
+* annotation-side:                       Annotation Properties.
+* annotation-visible:                    Annotation Properties.
+* annotation-width:                      Annotation Properties.
+* annotationp:                           Annotation Primitives.
+* annotations-at:                        Locating Annotations.
+* annotations-in-region:                 Locating Annotations.
+* anonymous function:                    Anonymous Functions.
+* anonymous lambda expressions (Edebug): Instrumenting.
+* apostrophe for quoting:                Quoting.
+* append:                                Building Lists.
+* append-to-file:                        Writing to Files.
+* apply:                                 Calling Functions.
+* apply, and debugging:                  Internals of Debugger.
+* apropos:                               Help Functions.
+* aref:                                  Array Functions.
+* argument binding:                      Argument List.
+* argument descriptors:                  Using Interactive.
+* argument evaluation form:              Using Interactive.
+* argument prompt:                       Using Interactive.
+* arguments, reading:                    Minibuffers.
+* arith-error example:                   Handling Errors.
+* arith-error in division:               Arithmetic Operations.
+* arithmetic shift:                      Bitwise Operations.
+* array:                                 Arrays.
+* array elements:                        Array Functions.
+* arrayp:                                Array Functions.
+* ASCII character codes:                 Character Type.
+* aset:                                  Array Functions.
+* ash:                                   Bitwise Operations.
+* asin:                                  Math Functions.
+* asinh:                                 Math Functions.
+* ask-user-about-lock:                   File Locks.
+* ask-user-about-supersession-threat:    Modification Time.
+* asking the user questions:             Yes-or-No Queries.
+* assoc:                                 Association Lists.
+* association list:                      Association Lists.
+* assq:                                  Association Lists.
+* asynchronous subprocess:               Asynchronous Processes.
+* atan:                                  Math Functions.
+* atanh:                                 Math Functions.
+* atom <1>:                              List-related Predicates.
+* atom:                                  Cons Cell Type.
+* atomic extent:                         Atomic Extents.
+* atoms:                                 List-related Predicates.
+* attributes of text:                    Text Properties.
+* Auto Fill mode:                        Auto Filling.
+* auto-fill-function:                    Auto Filling.
+* auto-lower-frame:                      Raising and Lowering.
+* auto-mode-alist:                       Auto Major Mode.
+* auto-raise-frame:                      Raising and Lowering.
+* auto-save-default:                     Auto-Saving.
+* auto-save-file-format:                 Format Conversion.
+* auto-save-file-name-p:                 Auto-Saving.
+* auto-save-hook:                        Auto-Saving.
+* auto-save-interval:                    Auto-Saving.
+* auto-save-list-file-name:              Auto-Saving.
+* auto-save-mode:                        Auto-Saving.
+* auto-save-timeout:                     Auto-Saving.
+* auto-save-visited-file-name:           Auto-Saving.
+* auto-saving:                           Auto-Saving.
+* autoload <1>:                          Domain Specification.
+* autoload:                              Autoload.
+* autoload errors:                       Autoload.
+* automatically buffer-local:            Intro to Buffer-Local.
+* available fonts:                       Font Instance Names.
+* back-to-indentation:                   Motion by Indent.
+* background pixmap:                     Merging Faces.
+* backquote (Edebug):                    Debugging Backquote.
+* backquote (list substitution):         Backquote.
+* backslash in character constant:       Character Type.
+* backslash in strings:                  String Type.
+* backslash in symbols:                  Symbol Type.
+* backspace:                             Character Type.
+* backtrace:                             Internals of Debugger.
+* backtrace-debug:                       Internals of Debugger.
+* backtrace-frame:                       Internals of Debugger.
+* backtracking:                          Backtracking.
+* backup file:                           Backup Files.
+* backup files, how to make them:        Rename or Copy.
+* backup-buffer:                         Making Backups.
+* backup-by-copying:                     Rename or Copy.
+* backup-by-copying-when-linked:         Rename or Copy.
+* backup-by-copying-when-mismatch:       Rename or Copy.
+* backup-enable-predicate:               Making Backups.
+* backup-file-name-p:                    Backup Names.
+* backup-inhibited:                      Making Backups.
+* backward-char:                         Character Motion.
+* backward-delete-char-untabify:         Deletion.
+* backward-list:                         List Motion.
+* backward-prefix-chars:                 Motion and Syntax.
+* backward-sexp:                         List Motion.
+* backward-to-indentation:               Motion by Indent.
+* backward-word:                         Word Motion.
+* balancing parentheses:                 Blinking.
+* barf-if-buffer-read-only:              Read Only Buffers.
+* base buffer:                           Indirect Buffers.
+* base64:                                Transformations.
+* base64-decode-region:                  Transformations.
+* base64-decode-string:                  Transformations.
+* base64-encode-region:                  Transformations.
+* base64-encode-string:                  Transformations.
+* batch mode:                            Batch Mode.
+* batch-byte-compile:                    Compilation Functions.
+* batch-byte-recompile-directory:        Compilation Functions.
+* beep:                                  Beeping.
+* beeping:                               Beeping.
+* before point, insertion:               Insertion.
+* before-change-function:                Change Hooks.
+* before-change-functions:               Change Hooks.
+* before-init-hook:                      Init File.
+* before-revert-hook:                    Reverting.
+* beginning of line:                     Text Lines.
+* beginning of line in regexp:           Syntax of Regexps.
+* beginning-of-buffer:                   Buffer End Motion.
+* beginning-of-defun:                    List Motion.
+* beginning-of-line:                     Text Lines.
+* bell:                                  Beeping.
+* bell character:                        Character Type.
+* bell-volume:                           Beeping.
+* binary files and text files:           Files and MS-DOS.
+* binary packages:                       Package Terminology.
+* binary-process-input:                  MS-DOS Subprocesses.
+* binary-process-output:                 MS-DOS Subprocesses.
+* bind-text-domain:                      Level 3 Primitives.
+* binding arguments:                     Argument List.
+* binding local variables:               Local Variables.
+* binding of a key:                      Keymap Terminology.
+* bit vector:                            Bit Vectors.
+* bit vector length:                     Sequence Functions.
+* bit-vector:                            Bit Vector Functions.
+* bit-vector-p:                          Bit Vector Functions.
+* bitp:                                  Bit Vector Functions.
+* bitwise and:                           Bitwise Operations.
+* bitwise exclusive or:                  Bitwise Operations.
+* bitwise not:                           Bitwise Operations.
+* bitwise or:                            Bitwise Operations.
+* blink-matching-open:                   Blinking.
+* blink-matching-paren:                  Blinking.
+* blink-matching-paren-delay:            Blinking.
+* blink-matching-paren-distance:         Blinking.
+* blink-paren-function:                  Blinking.
+* blink-paren-hook:                      Blinking.
+* blinking:                              Blinking.
+* bobp:                                  Near Point.
+* body of function:                      Lambda Components.
+* bold:                                  Font Instance Characteristics.
+* bolp:                                  Near Point.
+* bookmark-map:                          Standard Keymaps.
+* boolean:                               nil and t.
+* boolean-specifier-p:                   Specifier Types.
+* bootstrapping XEmacs from temacs:      Building XEmacs.
+* bottom-gutter:                         Specifying a Gutter.
+* bottom-gutter-height:                  Other Gutter Variables.
+* bottom-gutter-visible-p:               Other Gutter Variables.
+* bottom-toolbar:                        Specifying the Toolbar.
+* bottom-toolbar-height:                 Other Toolbar Variables.
+* bottom-toolbar-visible-p:              Other Toolbar Variables.
+* boundp:                                Void Variables.
+* box diagrams, for lists:               Cons Cell Type.
+* box representation for lists:          Lists as Boxes.
+* break:                                 Debugger.
+* breakpoints:                           Breakpoints.
+* bucket (in obarray):                   Creating Symbols.
+* buffer:                                Buffers.
+* buffer contents:                       Text.
+* buffer file name:                      Buffer File Name.
+* buffer input stream:                   Input Streams.
+* buffer list:                           The Buffer List.
+* buffer modification:                   Buffer Modification.
+* buffer names:                          Buffer Names.
+* buffer output stream:                  Output Streams.
+* buffer text notation:                  Buffer Text Notation.
+* buffer, read-only:                     Read Only Buffers.
+* buffer-auto-save-file-name:            Auto-Saving.
+* buffer-backed-up:                      Making Backups.
+* buffer-base-buffer:                    Indirect Buffers.
+* buffer-disable-undo:                   Maintaining Undo.
+* buffer-enable-undo:                    Maintaining Undo.
+* buffer-end:                            Point.
+* buffer-file-format:                    Format Conversion.
+* buffer-file-name:                      Buffer File Name.
+* buffer-file-number:                    Buffer File Name.
+* buffer-file-truename:                  Buffer File Name.
+* buffer-file-type:                      Files and MS-DOS.
+* buffer-flush-undo:                     Maintaining Undo.
+* buffer-glyph-p:                        Glyph Types.
+* buffer-indirect-children:              Indirect Buffers.
+* buffer-invisibility-spec:              Invisible Text.
+* buffer-list:                           The Buffer List.
+* buffer-live-p:                         Killing Buffers.
+* buffer-local variables:                Buffer-Local Variables.
+* buffer-local variables in modes:       Major Mode Conventions.
+* buffer-local-variables:                Creating Buffer-Local.
+* Buffer-menu-mode-map:                  Standard Keymaps.
+* buffer-modified-p:                     Buffer Modification.
+* buffer-modified-tick:                  Buffer Modification.
+* buffer-name:                           Buffer Names.
+* buffer-offer-save <1>:                 Killing Buffers.
+* buffer-offer-save:                     Saving Buffers.
+* buffer-read-only:                      Read Only Buffers.
+* buffer-saved-size <1>:                 Point.
+* buffer-saved-size:                     Auto-Saving.
+* buffer-size:                           Point.
+* buffer-string:                         Buffer Contents.
+* buffer-substring:                      Buffer Contents.
+* buffer-undo-list:                      Undo.
+* bufferp:                               Buffer Basics.
+* buffers menu:                          Buffers Menu.
+* buffers, controlled in windows:        Buffers and Windows.
+* buffers, creating:                     Creating Buffers.
+* buffers, killing:                      Killing Buffers.
+* buffers-menu-filter:                   Menu Filters.
+* buffers-menu-max-size:                 Buffers Menu.
+* buffers-menu-switch-to-buffer-function: Buffers Menu.
+* building lists:                        Building Lists.
+* building packages:                     Building Packages.
+* building XEmacs:                       Building XEmacs.
+* built-in function:                     What Is a Function.
+* bury-buffer:                           The Buffer List.
+* busy-pointer-glyph:                    Mouse Pointer.
+* button-event-p:                        Event Predicates.
+* button-press-event-p:                  Event Predicates.
+* button-release-event-p:                Event Predicates.
+* bvconcat:                              Bit Vector Functions.
+* byte-code <1>:                         Compilation Functions.
+* byte-code:                             Byte Compilation.
+* byte-code function:                    Compiled-Function Objects.
+* byte-code interpreter:                 Compilation Functions.
+* byte-compile:                          Compilation Functions.
+* byte-compile-call-tree:                Compilation Options.
+* byte-compile-call-tree-sort:           Compilation Options.
+* byte-compile-default-warnings:         Compilation Options.
+* byte-compile-delete-errors:            Compilation Options.
+* byte-compile-dest-file:                Compilation Options.
+* byte-compile-dynamic:                  Dynamic Loading.
+* byte-compile-dynamic-docstrings:       Docs and Compilation.
+* byte-compile-emacs19-compatibility:    Compilation Options.
+* byte-compile-error-on-warn:            Compilation Options.
+* byte-compile-file:                     Compilation Functions.
+* byte-compile-generate-call-tree:       Compilation Options.
+* byte-compile-new-bytecodes:            Compilation Options.
+* byte-compile-overwrite-file:           Compilation Options.
+* byte-compile-print-gensym:             Compilation Options.
+* byte-compile-single-version:           Compilation Options.
+* byte-compile-verbose:                  Compilation Options.
+* byte-compile-warnings:                 Compilation Options.
+* byte-compiler-options:                 Compilation Options.
+* byte-compiling macros:                 Compiling Macros.
+* byte-compiling require:                Named Features.
+* byte-optimize:                         Compilation Options.
+* byte-optimize-log:                     Compilation Options.
+* byte-recompile-directory:              Compilation Functions.
+* byte-recompile-directory-ignore-errors-p: Compilation Functions.
+* byte-recompile-directory-recursively:  Compilation Functions.
+* bytes:                                 Strings and Characters.
+* c++-mode-map:                          Standard Keymaps.
+* C-c:                                   Prefix Keys.
+* C-g:                                   Quitting.
+* C-h:                                   Prefix Keys.
+* C-M-x:                                 Instrumenting.
+* c-mode-abbrev-table:                   Standard Abbrev Tables.
+* c-mode-map:                            Standard Keymaps.
+* c-mode-syntax-table:                   Standard Syntax Tables.
+* C-q:                                   Flow Control.
+* C-s:                                   Flow Control.
+* C-x:                                   Prefix Keys.
+* C-x 4:                                 Prefix Keys.
+* C-x 5:                                 Prefix Keys.
+* C-x a:                                 Prefix Keys.
+* C-x n:                                 Prefix Keys.
+* C-x r:                                 Prefix Keys.
+* caaaar:                                List Elements.
+* caaadr:                                List Elements.
+* caaar:                                 List Elements.
+* caadar:                                List Elements.
+* caaddr:                                List Elements.
+* caadr:                                 List Elements.
+* caar:                                  List Elements.
+* cadaar:                                List Elements.
+* cadadr:                                List Elements.
+* cadar:                                 List Elements.
+* caddar:                                List Elements.
+* cadddr:                                List Elements.
+* caddr:                                 List Elements.
+* cadr:                                  List Elements.
+* call stack:                            Internals of Debugger.
+* call-interactively:                    Interactive Call.
+* call-process:                          Synchronous Processes.
+* call-process-region:                   Synchronous Processes.
+* calling a function:                    Calling Functions.
+* cancel-debug-on-entry:                 Function Debugging.
+* canonicalize-inst-list:                Adding Specifications.
+* canonicalize-inst-pair:                Adding Specifications.
+* canonicalize-lax-plist:                Working With Lax Plists.
+* canonicalize-plist:                    Working With Normal Plists.
+* canonicalize-spec:                     Adding Specifications.
+* canonicalize-spec-list:                Adding Specifications.
+* canonicalize-tag-set:                  Specifier Tag Functions.
+* capitalization:                        Character Case.
+* capitalize:                            Character Case.
+* capitalize-region:                     Case Changes.
+* capitalize-word:                       Case Changes.
+* car:                                   List Elements.
+* car-safe:                              List Elements.
+* case changes:                          Case Changes.
+* case in replacements:                  Replacing Match.
+* case-fold-search:                      Searching and Case.
+* case-replace:                          Searching and Case.
+* case-table-p:                          Case Tables.
+* catch:                                 Catch and Throw.
+* category-designator-p:                 Category Tables.
+* category-table:                        Category Tables.
+* category-table-p:                      Category Tables.
+* category-table-value-p:                Category Tables.
+* CBREAK:                                Flow Control.
+* ccl-elapsed-time:                      Calling CCL.
+* ccl-execute:                           Calling CCL.
+* ccl-execute-on-string:                 Calling CCL.
+* ccl-reset-elapsed-time:                Calling CCL.
+* cdaaar:                                List Elements.
+* cdaadr:                                List Elements.
+* cdaar:                                 List Elements.
+* cdadar:                                List Elements.
+* cdaddr:                                List Elements.
+* cdadr:                                 List Elements.
+* cdar:                                  List Elements.
+* cddaar:                                List Elements.
+* cddadr:                                List Elements.
+* cddar:                                 List Elements.
+* cdddar:                                List Elements.
+* cddddr:                                List Elements.
+* cdddr:                                 List Elements.
+* cddr:                                  List Elements.
+* CDE dt:                                CDE dt.
+* cdr:                                   List Elements.
+* cdr-safe:                              List Elements.
+* ceiling:                               Numeric Conversions.
+* centering point:                       Vertical Scrolling.
+* cerror:                                Signaling Errors.
+* change hooks:                          Change Hooks.
+* change-major-mode-hook:                Major Mode Conventions.
+* changing key bindings:                 Changing Key Bindings.
+* changing to another buffer:            Current Buffer.
+* changing window size:                  Resizing Windows.
+* char table type:                       Char Table Type.
+* char-after:                            Near Point.
+* char-before:                           Near Point.
+* char-charset:                          MULE Characters.
+* char-equal:                            Text Comparison.
+* char-int:                              Character Codes.
+* char-int confoundance disease:         Character Type.
+* char-int-p:                            Character Codes.
+* char-octet:                            MULE Characters.
+* char-or-char-int-p:                    Character Codes.
+* char-or-string-p:                      Predicates for Strings.
+* char-syntax:                           Syntax Table Functions.
+* char-table-p:                          Char Tables.
+* char-table-type:                       Char Table Types.
+* char-table-type-list:                  Char Table Types.
+* char-to-string:                        String Conversion.
+* char=:                                 Text Comparison.
+* character arrays:                      Strings and Characters.
+* character case:                        Character Case.
+* character descriptor:                  Character Descriptors.
+* character insertion:                   Commands for Insertion.
+* character printing:                    Describing Characters.
+* character set (in regexp):             Syntax of Regexps.
+* character to string:                   String Conversion.
+* character-to-event:                    Converting Events.
+* characteristics of font instances:     Font Instance Characteristics.
+* characterp:                            Predicates for Characters.
+* characters:                            Strings and Characters.
+* characters for interactive codes:      Interactive Codes.
+* character quote:                       Syntax Class Table.
+* charset type:                          Charset Type.
+* charset-ccl-program:                   Charset Property Functions.
+* charset-chars:                         Charset Property Functions.
+* charset-description:                   Charset Property Functions.
+* charset-dimension:                     Charset Property Functions.
+* charset-direction:                     Charset Property Functions.
+* charset-from-attributes:               Basic Charset Functions.
+* charset-iso-final-char:                Charset Property Functions.
+* charset-iso-graphic-plane:             Charset Property Functions.
+* charset-list:                          Basic Charset Functions.
+* charset-name:                          Charset Property Functions.
+* charset-property:                      Charset Property Functions.
+* charset-registry:                      Charset Property Functions.
+* charset-reverse-direction-charset:     Basic Charset Functions.
+* charset-width:                         Charset Property Functions.
+* charsetp:                              Charsets.
+* check-argument-type:                   Signaling Errors.
+* check-gutter-button-syntax:            Gutter Descriptor Format.
+* check-toolbar-button-syntax:           Toolbar Descriptor Format.
+* check-valid-char-table-value:          Working With Char Tables.
+* check-valid-inst-list:                 Specifier Validation Functions.
+* check-valid-instantiator:              Specifier Validation Functions.
+* check-valid-plist:                     Property Lists.
+* check-valid-spec-list:                 Specifier Validation Functions.
+* child process:                         Processes.
+* children, of extent:                   Extent Parents.
+* CL note--allocate more storage:        Garbage Collection.
+* CL note--case of letters:              Symbol Type.
+* CL note--default optional arg:         Argument List.
+* CL note--integers vrs eq:              Comparison of Numbers.
+* CL note--lack union, set:              Sets And Lists.
+* CL note--only throw in Emacs:          Catch and Throw.
+* CL note--rplaca vrs setcar:            Modifying Lists.
+* CL note--set local:                    Setting Variables.
+* CL note--special forms compared:       Special Forms.
+* CL note--special variables:            Variable Scoping.
+* CL note--symbol in obarrays:           Creating Symbols.
+* cl-read:                               Reading in Edebug.
+* cl-specs.el:                           Instrumenting.
+* cl.el (Edebug):                        Instrumenting.
+* cleanup forms:                         Cleanups.
+* clear-abbrev-table:                    Abbrev Tables.
+* clear-message:                         The Echo Area.
+* clear-range-table:                     Working With Range Tables.
+* clear-visited-file-modtime:            Modification Time.
+* close parenthesis:                     Blinking.
+* close-database:                        Connecting to a Database.
+* close parenthesis character:           Syntax Class Table.
+* closures not available:                Extent.
+* clrhash:                               Working With Hash Tables.
+* codes, interactive, description of:    Interactive Codes.
+* coding standards:                      Tips.
+* coding system type:                    Coding System Type.
+* coding-category-list:                  Detection of Textual Encoding.
+* coding-category-system:                Detection of Textual Encoding.
+* coding-priority-list:                  Detection of Textual Encoding.
+* coding-system-base:                    Basic Coding System Functions.
+* coding-system-doc-string:              Coding System Property Functions.
+* coding-system-list:                    Basic Coding System Functions.
+* coding-system-name:                    Basic Coding System Functions.
+* coding-system-p:                       Coding Systems.
+* coding-system-property:                Coding System Property Functions.
+* coding-system-type:                    Coding System Property Functions.
+* color instance type:                   Color Instance Type.
+* color instances:                       Color Instances.
+* color-instance-name:                   Color Instance Properties.
+* color-instance-p:                      Color Instances.
+* color-instance-rgb-components:         Color Instance Properties.
+* color-name:                            Color Convenience Functions.
+* color-pixmap-image-instance-p:         Image Instance Types.
+* color-rgb-components:                  Color Convenience Functions.
+* color-specifier-p <1>:                 Color Specifiers.
+* color-specifier-p:                     Specifier Types.
+* colorize-image-instance:               Image Instance Functions.
+* colors:                                Colors.
+* columns:                               Columns.
+* Command:                               Visibility of Frames.
+* command:                               What Is a Function.
+* command descriptions:                  A Sample Function Description.
+* command history:                       Command History.
+* command in keymap:                     Key Lookup.
+* command line arguments:                Command Line Arguments.
+* command line options:                  Command Line Arguments.
+* command loop:                          Command Loop.
+* command loop, recursive:               Recursive Editing.
+* command-debug-status:                  Internals of Debugger.
+* command-execute:                       Interactive Call.
+* command-history:                       Command History.
+* command-history-map:                   Standard Keymaps.
+* command-line:                          Command Line Arguments.
+* command-line-args:                     Command Line Arguments.
+* command-line-functions:                Command Line Arguments.
+* command-line-processed:                Command Line Arguments.
+* command-switch-alist:                  Command Line Arguments.
+* commandp:                              Interactive Call.
+* commandp example:                      High-Level Completion.
+* commands, defining:                    Defining Commands.
+* comment syntax:                        Syntax Class Table.
+* comments:                              Comments.
+* comment ender:                         Syntax Class Table.
+* comment starter:                       Syntax Class Table.
+* Common Lisp:                           Lisp History.
+* Common Lisp (Edebug):                  Instrumenting.
+* compare-buffer-substrings:             Comparing Text.
+* comparing buffer text:                 Comparing Text.
+* comparison of modification time:       Modification Time.
+* compilation:                           Byte Compilation.
+* compilation functions:                 Compilation Functions.
+* compilation options:                   Compilation Options.
+* compile-defun:                         Compilation Functions.
+* compiled function:                     Compiled-Function Objects.
+* compiled-function-arglist:             Compiled-Function Objects.
+* compiled-function-constants:           Compiled-Function Objects.
+* compiled-function-doc-string:          Compiled-Function Objects.
+* compiled-function-domain:              Compiled-Function Objects.
+* compiled-function-instructions:        Compiled-Function Objects.
+* compiled-function-interactive:         Compiled-Function Objects.
+* compiled-function-p:                   What Is a Function.
+* compiled-function-stack-depth:         Compiled-Function Objects.
+* compiling packages:                    Makefile.
+* complete key:                          Keymap Terminology.
+* completing-read:                       Minibuffer Completion.
+* completion:                            Completion.
+* completion, file name:                 File Name Completion.
+* completion, user name:                 User Name Completion.
+* completion-auto-help:                  Completion Commands.
+* completion-ignore-case:                Basic Completion.
+* completion-ignored-extensions:         File Name Completion.
+* complex arguments:                     Minibuffers.
+* complex command:                       Command History.
+* complex-buffers-menu-p:                Buffers Menu.
+* compose-region:                        Composite Characters.
+* composite-char-string:                 Composite Characters.
+* concat:                                Creating Strings.
+* concatenating lists:                   Rearrangement.
+* concatenating strings:                 Creating Strings.
+* cond:                                  Conditionals.
+* condition name:                        Error Symbols.
+* condition-case:                        Handling Errors.
+* conditional evaluation:                Conditionals.
+* cons:                                  Building Lists.
+* cons cell as box:                      Lists as Boxes.
+* cons cells:                            Building Lists.
+* consing:                               Building Lists.
+* console-device-list:                   Basic Console Functions.
+* console-disable-input:                 Console and Device I/O.
+* console-enable-input:                  Console and Device I/O.
+* console-list:                          Basic Console Functions.
+* console-live-p:                        Connecting to a Console or Device.
+* console-type-image-conversion-list:    Image Instantiator Conversion.
+* consolep:                              Consoles and Devices.
+* consoles:                              Consoles and Devices.
+* consp:                                 List-related Predicates.
+* continuation lines:                    Truncation.
+* continuation-glyph:                    Redisplay Glyphs.
+* continue-process:                      Signals to Processes.
+* control character printing:            Describing Characters.
+* control characters:                    Character Type.
+* control characters in display:         Usual Display.
+* control characters, reading:           Quoted Character Input.
+* control structures:                    Control Structures.
+* control-arrow-glyph:                   Redisplay Glyphs.
+* Control-X-prefix:                      Prefix Keys.
+* conventions for writing minor modes:   Minor Mode Conventions.
+* conversion of image instantiators:     Image Instantiator Conversion.
+* conversion of strings:                 String Conversion.
+* copy-alist:                            Association Lists.
+* copy-category-table:                   Category Tables.
+* copy-coding-system:                    Basic Coding System Functions.
+* copy-event:                            Working With Events.
+* copy-extent:                           Detached Extents.
+* copy-face:                             Basic Face Functions.
+* copy-file:                             Changing File Attributes.
+* copy-hash-table:                       Introduction to Hash Tables.
+* copy-keymap:                           Creating Keymaps.
+* copy-marker:                           Creating Markers.
+* copy-range-table:                      Introduction to Range Tables.
+* copy-region-as-kill:                   Kill Functions.
+* copy-sequence:                         Sequence Functions.
+* copy-specifier:                        Other Specification Functions.
+* copy-syntax-table:                     Syntax Table Functions.
+* copying alists:                        Association Lists.
+* copying bit vectors:                   Bit Vector Functions.
+* copying files:                         Changing File Attributes.
+* copying lists:                         Building Lists.
+* copying sequences:                     Sequence Functions.
+* copying strings:                       Creating Strings.
+* copying vectors:                       Vector Functions.
+* cos:                                   Math Functions.
+* cosh:                                  Math Functions.
+* count-lines:                           Text Lines.
+* count-loop:                            A Sample Function Description.
+* counting columns:                      Columns.
+* coverage testing:                      Coverage Testing.
+* create-device-hook:                    Connecting to a Console or Device.
+* create-file-buffer:                    Subroutines of Visiting.
+* create-frame-hook:                     Frame Hooks.
+* create-tooltalk-message:               Elisp Interface for Sending Messages.
+* create-tooltalk-pattern:               Elisp Interface for Receiving Messages.
+* creating buffers:                      Creating Buffers.
+* creating keymaps:                      Creating Keymaps.
+* creating packages:                     Creating Packages.
+* ctl-arrow:                             Usual Display.
+* ctl-x-4-map <1>:                       Standard Keymaps.
+* ctl-x-4-map:                           Prefix Keys.
+* ctl-x-5-map <1>:                       Standard Keymaps.
+* ctl-x-5-map:                           Prefix Keys.
+* ctl-x-map <1>:                         Standard Keymaps.
+* ctl-x-map:                             Prefix Keys.
+* cube-root:                             Math Functions.
+* current binding:                       Local Variables.
+* current buffer:                        Current Buffer.
+* current buffer excursion:              Excursions.
+* current buffer mark:                   The Mark.
+* current buffer point and mark (Edebug): Edebug Display Update.
+* current buffer position:               Point.
+* current command:                       Command Loop Info.
+* current stack frame:                   Using Debugger.
+* current-buffer:                        Current Buffer.
+* current-case-table:                    Case Tables.
+* current-column:                        Columns.
+* current-display-table:                 Active Display Table.
+* current-fill-column:                   Margins.
+* current-frame-configuration:           Frame Configurations.
+* current-global-map:                    Active Keymaps.
+* current-indentation:                   Primitive Indent.
+* current-input-mode:                    Input Modes.
+* current-justification:                 Filling.
+* current-keymaps:                       Active Keymaps.
+* current-kill:                          Low-Level Kill Ring.
+* current-left-margin:                   Margins.
+* current-local-map:                     Active Keymaps.
+* current-menubar:                       Menubar.
+* current-message:                       The Echo Area.
+* current-minor-mode-maps:               Active Keymaps.
+* current-mouse-event:                   Command Loop Info.
+* current-prefix-arg:                    Prefix Command Arguments.
+* current-time:                          Time of Day.
+* current-time-string:                   Time of Day.
+* current-time-zone:                     Time of Day.
+* current-window-configuration:          Window Configurations.
+* cursor (mouse):                        Mouse Pointer.
+* cursor-in-echo-area:                   The Echo Area.
+* cust-print:                            Printing in Edebug.
+* cut buffer:                            X Selections.
+* cyclic ordering of windows:            Cyclic Window Ordering.
+* data type:                             Lisp Data Types.
+* data-directory:                        Accessing Documentation.
+* database:                              Databases.
+* database type:                         Database Type.
+* database-file-name:                    Other Database Functions.
+* database-last-error:                   Other Database Functions.
+* database-live-p:                       Connecting to a Database.
+* database-subtype:                      Other Database Functions.
+* database-type:                         Other Database Functions.
+* databasep:                             Databases.
+* deallocate-event:                      Working With Events.
+* debug:                                 Invoking the Debugger.
+* debug-allocation:                      Garbage Collection.
+* debug-allocation-backtrace:            Garbage Collection.
+* debug-ignored-errors:                  Error Debugging.
+* debug-on-entry:                        Function Debugging.
+* debug-on-error:                        Error Debugging.
+* debug-on-error use:                    Processing of Errors.
+* debug-on-next-call:                    Internals of Debugger.
+* debug-on-quit:                         Infinite Loops.
+* debug-on-signal:                       Error Debugging.
+* debug-on-signal use:                   Handling Errors.
+* debugger <1>:                          Internals of Debugger.
+* debugger:                              Debugger.
+* debugger command list:                 Debugger Commands.
+* debugger-mode-map:                     Standard Keymaps.
+* debugging errors:                      Error Debugging.
+* debugging specific functions:          Function Debugging.
+* decode-big5-char:                      Big5 and Shift-JIS Functions.
+* decode-coding-region:                  Encoding and Decoding Text.
+* decode-shift-jis-char:                 Big5 and Shift-JIS Functions.
+* decode-time:                           Time Conversion.
+* decoding file formats:                 Format Conversion.
+* decompose-region:                      Composite Characters.
+* decrement field of register:           Cons Cell Type.
+* dedicated window:                      Choosing Window.
+* deep binding:                          Impl of Scope.
+* def-edebug-spec:                       Instrumenting Macro Calls.
+* defalias:                              Defining Functions.
+* default argument string:               Interactive Codes.
+* default init file:                     Init File.
+* default value:                         Default Value.
+* default-abbrev-mode:                   Abbrev Mode.
+* default-boundp:                        Default Value.
+* default-buffer-file-type:              Files and MS-DOS.
+* default-case-fold-search:              Searching and Case.
+* default-ctl-arrow:                     Usual Display.
+* default-deselect-frame-hook:           Raising and Lowering.
+* default-directory:                     File Name Expansion.
+* default-file-modes:                    Changing File Attributes.
+* default-fill-column:                   Margins.
+* default-frame-name:                    Frame Name.
+* default-frame-plist:                   Initial Properties.
+* default-gutter:                        Specifying a Gutter.
+* default-gutter-height:                 Other Gutter Variables.
+* default-gutter-position:               Specifying a Gutter.
+* default-gutter-visible-p:              Other Gutter Variables.
+* default-gutter-width:                  Other Gutter Variables.
+* default-justification:                 Filling.
+* default-major-mode:                    Auto Major Mode.
+* default-menubar:                       Menubar.
+* default-minibuffer-frame:              Minibuffers and Frames.
+* default-modeline-format:               Modeline Variables.
+* default-popup-menu:                    Pop-Up Menus.
+* default-select-frame-hook:             Raising and Lowering.
+* default-text-properties:               Examining Properties.
+* default-toolbar:                       Specifying the Toolbar.
+* default-toolbar-height:                Other Toolbar Variables.
+* default-toolbar-position:              Specifying the Toolbar.
+* default-toolbar-visible-p:             Other Toolbar Variables.
+* default-toolbar-width:                 Other Toolbar Variables.
+* default-truncate-lines:                Truncation.
+* default-value:                         Default Value.
+* default-x-device:                      Resources.
+* default.el:                            Start-up Summary.
+* defconst <1>:                          Domain Specification.
+* defconst:                              Defining Variables.
+* defcustom:                             Variable Definitions.
+* defgroup:                              Group Definitions.
+* define-abbrev:                         Defining Abbrevs.
+* define-abbrev-table:                   Abbrev Tables.
+* define-derived-mode:                   Derived Modes.
+* define-error:                          Error Symbols.
+* define-function:                       Defining Functions.
+* define-key:                            Changing Key Bindings.
+* define-obsolete-function-alias:        Obsoleteness.
+* define-obsolete-variable-alias:        Obsoleteness.
+* define-prefix-command:                 Prefix Keys.
+* define-specifier-tag:                  Specifier Tag Functions.
+* defining a function:                   Defining Functions.
+* defining commands:                     Defining Commands.
+* defining-kbd-macro:                    Keyboard Macros.
+* definition of a symbol:                Definitions.
+* defmacro:                              Defining Macros.
+* defsubst:                              Inline Functions.
+* defun:                                 Defining Functions.
+* defun-prompt-regexp:                   List Motion.
+* defvar <1>:                            Domain Specification.
+* defvar:                                Defining Variables.
+* defvaralias:                           Variable Aliases.
+* delete:                                Sets And Lists.
+* delete previous char:                  Deletion.
+* delete-annotation:                     Annotation Primitives.
+* delete-auto-save-file-if-necessary:    Auto-Saving.
+* delete-auto-save-files:                Auto-Saving.
+* delete-backward-char:                  Deletion.
+* delete-blank-lines:                    User-Level Deletion.
+* delete-char:                           Deletion.
+* delete-device:                         Connecting to a Console or Device.
+* delete-device-hook:                    Connecting to a Console or Device.
+* delete-directory:                      Create/Delete Dirs.
+* delete-exited-processes:               Deleting Processes.
+* delete-extent:                         Creating and Modifying Extents.
+* delete-file:                           Changing File Attributes.
+* delete-frame:                          Deleting Frames.
+* delete-frame-hook:                     Frame Hooks.
+* delete-horizontal-space:               User-Level Deletion.
+* delete-indentation:                    User-Level Deletion.
+* delete-menu-item:                      Modifying Menus.
+* delete-old-versions:                   Numbered Backups.
+* delete-other-windows:                  Deleting Windows.
+* delete-process:                        Deleting Processes.
+* delete-region:                         Deletion.
+* delete-to-left-margin:                 Margins.
+* delete-window:                         Deleting Windows.
+* delete-windows-on:                     Deleting Windows.
+* deleting files:                        Changing File Attributes.
+* deleting processes:                    Deleting Processes.
+* deleting whitespace:                   User-Level Deletion.
+* deleting windows:                      Deleting Windows.
+* deletion of elements:                  Sets And Lists.
+* deletion of frames:                    Deleting Frames.
+* deletion vs killing:                   Deletion.
+* delq:                                  Sets And Lists.
+* demibold:                              Font Instance Characteristics.
+* describe-bindings:                     Scanning Keymaps.
+* describe-bindings-internal:            Scanning Keymaps.
+* describe-buffer-case-table:            Case Tables.
+* describe-mode:                         Mode Help.
+* describe-prefix-bindings:              Help Functions.
+* describe-tooltalk-message:             Elisp Interface for Receiving Messages.
+* description for interactive codes:     Interactive Codes.
+* description format:                    Format of Descriptions.
+* deselect-frame-hook:                   Frame Hooks.
+* destroy-tooltalk-message:              Elisp Interface for Sending Messages.
+* destroy-tooltalk-pattern:              Elisp Interface for Receiving Messages.
+* destructive-alist-to-plist:            Converting Plists To/From Alists.
+* destructive-plist-to-alist:            Converting Plists To/From Alists.
+* detach-extent:                         Detached Extents.
+* detached extent:                       Detached Extents.
+* detect-coding-region:                  Detection of Textual Encoding.
+* device-baud-rate <1>:                  Terminal Output.
+* device-baud-rate:                      Console and Device I/O.
+* device-class:                          Console Types and Device Classes.
+* device-frame-list <1>:                 Basic Device Functions.
+* device-frame-list:                     Finding All Frames.
+* device-list:                           Basic Device Functions.
+* device-live-p:                         Connecting to a Console or Device.
+* device-matches-specifier-tag-set-p:    Specifier Tag Functions.
+* device-matching-specifier-tag-list:    Specifier Tag Functions.
+* device-or-frame-p:                     Basic Device Functions.
+* device-or-frame-type:                  Console Types and Device Classes.
+* device-type:                           Console Types and Device Classes.
+* device-x-display:                      Connecting to a Console or Device.
+* devicep:                               Consoles and Devices.
+* devices:                               Consoles and Devices.
+* dgettext:                              Level 3 Primitives.
+* diagrams, boxed, for lists:            Cons Cell Type.
+* dialog box:                            Dialog Boxes.
+* digit-argument:                        Prefix Command Arguments.
+* ding:                                  Beeping.
+* directory name:                        Directory Names.
+* directory name abbreviation:           Directory Names.
+* directory part (of file name):         File Name Components.
+* directory-abbrev-alist:                Directory Names.
+* directory-file-name:                   Directory Names.
+* directory-files:                       Contents of Directories.
+* directory-oriented functions:          Contents of Directories.
+* dired-kept-versions:                   Numbered Backups.
+* dired-mode-map:                        Standard Keymaps.
+* disable undo:                          Maintaining Undo.
+* disable-command:                       Disabling Commands.
+* disable-menu-item:                     Modifying Menus.
+* disable-timeout:                       Timers.
+* disabled:                              Disabling Commands.
+* disabled command:                      Disabling Commands.
+* disabled-command-hook:                 Disabling Commands.
+* disassemble:                           Disassembly.
+* disassembled byte-code:                Disassembly.
+* discard input:                         Peeking and Discarding.
+* discard-input:                         Peeking and Discarding.
+* dispatch-event:                        Dispatching an Event.
+* dispatching an event:                  Dispatching an Event.
+* display columns:                       Size and Position.
+* display lines:                         Size and Position.
+* display order:                         Extent Endpoints.
+* display table:                         Display Tables.
+* display update:                        Refresh Screen.
+* display-buffer:                        Choosing Window.
+* display-buffer-function:               Choosing Window.
+* display-completion-list:               Completion Commands.
+* display-error:                         Processing of Errors.
+* display-message:                       The Echo Area.
+* display-warning:                       Warnings.
+* display-warning-minimum-level:         Warnings.
+* display-warning-suppressed-classes:    Warnings.
+* displaying a buffer:                   Displaying Buffers.
+* do-auto-save:                          Auto-Saving.
+* DOC (documentation) file:              Documentation Basics.
+* doc-directory:                         Accessing Documentation.
+* documentation:                         Accessing Documentation.
+* documentation conventions:             Documentation Basics.
+* documentation for major mode:          Mode Help.
+* documentation notation:                Evaluation Notation.
+* documentation of function:             Function Documentation.
+* documentation strings:                 Documentation.
+* documentation, keys in:                Keys in Documentation.
+* documentation-property:                Accessing Documentation.
+* documenting packages:                  Documenting Packages.
+* domain:                                Level 3 Primitives.
+* domain (in a specifier):               Specifiers In-Depth.
+* domain-of:                             Level 3 Primitives.
+* dotted lists (Edebug):                 Specification List.
+* dotted pair notation:                  Dotted Pair Notation.
+* double-quote in strings:               String Type.
+* down-list:                             List Motion.
+* downcase:                              Character Case.
+* downcase-region:                       Case Changes.
+* downcase-word:                         Case Changes.
+* downcasing in lookup-key:              Key Sequence Input.
+* drag:                                  Drag Interface.
+* drag and drop:                         Drag and Drop.
+* Drag API:                              Drag Interface.
+* dribble file:                          Recording Input.
+* drop:                                  Drop Interface.
+* Drop API:                              Drop Interface.
+* dump-emacs:                            Building XEmacs.
+* duplicable extent:                     Duplicable Extents.
+* dynamic loading of documentation:      Docs and Compilation.
+* dynamic loading of functions:          Dynamic Loading.
+* dynamic scoping:                       Variable Scoping.
+* echo area:                             The Echo Area.
+* echo-keystrokes <1>:                   The Echo Area.
+* echo-keystrokes:                       Command Loop Info.
+* edebug:                                Embedded Breakpoints.
+* Edebug:                                Edebug.
+* Edebug execution modes:                Edebug Execution Modes.
+* Edebug mode:                           Edebug.
+* Edebug specification list:             Specification List.
+* edebug-`:                              Debugging Backquote.
+* edebug-all-defs <1>:                   Edebug Options.
+* edebug-all-defs:                       Instrumenting.
+* edebug-all-forms <1>:                  Edebug Options.
+* edebug-all-forms:                      Instrumenting.
+* edebug-continue-kbd-macro:             Edebug Options.
+* edebug-display-freq-count:             Coverage Testing.
+* edebug-eval-top-level-form:            Instrumenting.
+* edebug-global-break-condition <1>:     Edebug Options.
+* edebug-global-break-condition:         Global Break Condition.
+* edebug-initial-mode:                   Edebug Options.
+* edebug-on-error <1>:                   Edebug Options.
+* edebug-on-error:                       Trapping Errors.
+* edebug-on-quit <1>:                    Edebug Options.
+* edebug-on-quit:                        Trapping Errors.
+* edebug-print-circle <1>:               Edebug Options.
+* edebug-print-circle:                   Printing in Edebug.
+* edebug-print-length <1>:               Edebug Options.
+* edebug-print-length:                   Printing in Edebug.
+* edebug-print-level <1>:                Edebug Options.
+* edebug-print-level:                    Printing in Edebug.
+* edebug-print-trace-after <1>:          Edebug Options.
+* edebug-print-trace-after:              Tracing.
+* edebug-print-trace-before <1>:         Edebug Options.
+* edebug-print-trace-before:             Tracing.
+* edebug-save-displayed-buffer-points <1>: Edebug Options.
+* edebug-save-displayed-buffer-points:   Edebug Display Update.
+* edebug-save-windows <1>:               Edebug Options.
+* edebug-save-windows:                   Edebug Display Update.
+* edebug-set-global-break-condition:     Global Break Condition.
+* edebug-setup-hook:                     Edebug Options.
+* edebug-test-coverage:                  Edebug Options.
+* edebug-trace <1>:                      Edebug Options.
+* edebug-trace:                          Tracing.
+* edebug-tracing:                        Tracing.
+* edebug-unwrap:                         Specification List.
+* edebug-unwrap-results <1>:             Edebug Options.
+* edebug-unwrap-results:                 Debugging Backquote.
+* edit-abbrevs-map:                      Standard Keymaps.
+* edit-and-eval-command:                 Object from Minibuffer.
+* edit-menu-filter:                      Menu Filters.
+* edit-tab-stops-map:                    Standard Keymaps.
+* editing types:                         Editing Types.
+* editor command loop:                   Command Loop.
+* eighth:                                List Elements.
+* electric-buffer-menu-mode-map:         Standard Keymaps.
+* electric-future-map:                   A Sample Variable Description.
+* electric-history-map:                  Standard Keymaps.
+* element (of list):                     Lists.
+* elements of sequences:                 Sequence Functions.
+* elt:                                   Sequence Functions.
+* emacs-build-time:                      Building XEmacs.
+* emacs-lisp-file-regexp:                Compilation Options.
+* emacs-lisp-mode-map:                   Standard Keymaps.
+* emacs-lisp-mode-syntax-table:          Standard Syntax Tables.
+* emacs-major-version:                   Building XEmacs.
+* emacs-minor-version:                   Building XEmacs.
+* emacs-pid:                             System Environment.
+* emacs-version:                         Building XEmacs.
+* EMACSLOADPATH environment variable:    How Programs Do Loading.
+* embedded breakpoints:                  Embedded Breakpoints.
+* empty list:                            Cons Cell Type.
+* enable-command:                        Disabling Commands.
+* enable-flow-control:                   Flow Control.
+* enable-flow-control-on:                Flow Control.
+* enable-local-eval:                     Auto Major Mode.
+* enable-local-variables:                Auto Major Mode.
+* enable-menu-item:                      Modifying Menus.
+* enable-recursive-minibuffers:          Minibuffer Misc.
+* encode-big5-char:                      Big5 and Shift-JIS Functions.
+* encode-coding-region:                  Encoding and Decoding Text.
+* encode-shift-jis-char:                 Big5 and Shift-JIS Functions.
+* encode-time:                           Time Conversion.
+* encoding file formats:                 Format Conversion.
+* end of buffer marker:                  Creating Markers.
+* end-of-buffer:                         Buffer End Motion.
+* end-of-defun:                          List Motion.
+* end-of-file:                           Input Functions.
+* end-of-line:                           Text Lines.
+* enlarge-window:                        Resizing Windows.
+* enlarge-window-horizontally:           Resizing Windows.
+* enlarge-window-pixels:                 Resizing Windows.
+* enqueue-eval-event:                    Reading One Event.
+* environment:                           Intro Eval.
+* environment variable access:           System Environment.
+* environment variables, subprocesses:   Subprocess Creation.
+* eobp:                                  Near Point.
+* eolp:                                  Near Point.
+* eq:                                    Equality Predicates.
+* equal:                                 Equality Predicates.
+* equality:                              Equality Predicates.
+* erase-buffer:                          Deletion.
+* error:                                 Signaling Errors.
+* error cleanup:                         Cleanups.
+* error debugging:                       Error Debugging.
+* error display:                         The Echo Area.
+* error handler:                         Handling Errors.
+* error in debug:                        Invoking the Debugger.
+* error message notation:                Error Messages.
+* error name:                            Error Symbols.
+* error symbol:                          Error Symbols.
+* error-conditions:                      Error Symbols.
+* error-message-string:                  Processing of Errors.
+* errors:                                Errors.
+* esc-map:                               Prefix Keys.
+* ESC-prefix:                            Prefix Keys.
+* escape <1>:                            Syntax Class Table.
+* escape:                                Character Type.
+* escape characters:                     Output Variables.
+* escape characters in printing:         Output Functions.
+* escape sequence:                       Character Type.
+* eval:                                  Eval.
+* eval, and debugging:                   Internals of Debugger.
+* eval-and-compile:                      Eval During Compile.
+* eval-buffer:                           Eval.
+* eval-current-buffer (Edebug):          Instrumenting.
+* eval-defun (Edebug):                   Instrumenting.
+* eval-event-p:                          Event Predicates.
+* eval-expression (Edebug):              Instrumenting.
+* eval-minibuffer:                       Object from Minibuffer.
+* eval-region:                           Eval.
+* eval-region (Edebug):                  Instrumenting.
+* eval-when-compile:                     Eval During Compile.
+* evaluated expression argument:         Interactive Codes.
+* evaluation:                            Evaluation.
+* evaluation error:                      Local Variables.
+* evaluation list (Edebug):              Eval List.
+* evaluation notation:                   Evaluation Notation.
+* evaluation of buffer contents:         Eval.
+* event printing:                        Describing Characters.
+* event-buffer:                          Window-Level Event Position Info.
+* event-button:                          Accessing Other Event Info.
+* event-closest-point:                   Event Text Position Info.
+* event-device:                          Accessing Other Event Info.
+* event-frame:                           Frame-Level Event Position Info.
+* event-function:                        Accessing Other Event Info.
+* event-glyph-extent:                    Event Glyph Position Info.
+* event-glyph-x-pixel:                   Event Glyph Position Info.
+* event-glyph-y-pixel:                   Event Glyph Position Info.
+* event-key:                             Accessing Other Event Info.
+* event-live-p:                          Event Predicates.
+* event-matches-key-specifier-p:         Key Sequences.
+* event-modifier-bits:                   Accessing Other Event Info.
+* event-modifiers:                       Accessing Other Event Info.
+* event-object:                          Accessing Other Event Info.
+* event-over-border-p:                   Other Event Position Info.
+* event-over-glyph-p:                    Event Glyph Position Info.
+* event-over-modeline-p:                 Event Text Position Info.
+* event-over-text-area-p:                Event Text Position Info.
+* event-over-toolbar-p:                  Event Toolbar Position Info.
+* event-point:                           Event Text Position Info.
+* event-process:                         Accessing Other Event Info.
+* event-timestamp:                       Accessing Other Event Info.
+* event-to-character:                    Converting Events.
+* event-toolbar-button:                  Event Toolbar Position Info.
+* event-type:                            Event Contents.
+* event-window:                          Window-Level Event Position Info.
+* event-window-x-pixel:                  Window-Level Event Position Info.
+* event-window-y-pixel:                  Window-Level Event Position Info.
+* event-x:                               Event Text Position Info.
+* event-x-pixel:                         Frame-Level Event Position Info.
+* event-y:                               Event Text Position Info.
+* event-y-pixel:                         Frame-Level Event Position Info.
+* eventp:                                Events.
+* events:                                Events.
+* events-to-keys:                        Converting Events.
+* examining windows:                     Buffers and Windows.
+* examples of using interactive:         Interactive Examples.
+* examples, specifier:                   Simple Specifier Usage.
+* exchange-point-and-mark:               The Mark.
+* excursion:                             Excursions.
+* exec-directory:                        Subprocess Creation.
+* exec-path:                             Subprocess Creation.
+* execute program:                       Subprocess Creation.
+* execute with prefix argument:          Interactive Call.
+* execute-extended-command:              Interactive Call.
+* execute-kbd-macro:                     Keyboard Macros.
+* executing-macro:                       Keyboard Macros.
+* execution speed:                       Compilation Tips.
+* exit:                                  Recursive Editing.
+* exit recursive editing:                Recursive Editing.
+* exit-minibuffer:                       Minibuffer Misc.
+* exit-recursive-edit:                   Recursive Editing.
+* exiting XEmacs:                        Getting Out.
+* exp:                                   Math Functions.
+* expand-abbrev:                         Abbrev Expansion.
+* expand-file-name:                      File Name Expansion.
+* expansion of file names:               File Name Expansion.
+* expansion of macros:                   Expansion.
+* expression:                            Intro Eval.
+* expression prefix:                     Syntax Class Table.
+* expt:                                  Math Functions.
+* extended-command-history:              Minibuffer History.
+* extent <1>:                            Extents.
+* extent:                                Variable Scoping.
+* extent children:                       Extent Parents.
+* extent end position:                   Extent Endpoints.
+* extent endpoint:                       Extent Endpoints.
+* extent order:                          Extent Endpoints.
+* extent parent:                         Extent Parents.
+* extent priority:                       Intro to Extents.
+* extent property:                       Extent Properties.
+* extent replica:                        Duplicable Extents.
+* extent start position:                 Extent Endpoints.
+* extent, duplicable:                    Duplicable Extents.
+* extent, unique:                        Duplicable Extents.
+* extent-at:                             Finding Extents.
+* extent-begin-glyph:                    Extent Properties.
+* extent-begin-glyph-layout:             Extent Properties.
+* extent-children:                       Extent Parents.
+* extent-descendants:                    Extent Parents.
+* extent-detached-p:                     Detached Extents.
+* extent-end-glyph:                      Extent Properties.
+* extent-end-glyph-layout:               Extent Properties.
+* extent-end-position:                   Extent Endpoints.
+* extent-face:                           Extent Properties.
+* extent-in-region-p:                    Mapping Over Extents.
+* extent-keymap:                         Extent Properties.
+* extent-length:                         Extent Endpoints.
+* extent-list:                           Finding Extents.
+* extent-live-p:                         Creating and Modifying Extents.
+* extent-mouse-face:                     Extent Properties.
+* extent-object:                         Creating and Modifying Extents.
+* extent-parent:                         Extent Parents.
+* extent-priority:                       Extent Properties.
+* extent-properties:                     Extent Properties.
+* extent-property:                       Extent Properties.
+* extent-start-position:                 Extent Endpoints.
+* extentp:                               Extents.
+* extents, locating:                     Finding Extents.
+* extents, mapping:                      Mapping Over Extents.
+* face type:                             Face Type.
+* face-background:                       Face Convenience Functions.
+* face-background-instance:              Face Convenience Functions.
+* face-background-pixmap:                Face Convenience Functions.
+* face-background-pixmap-instance:       Face Convenience Functions.
+* face-boolean-specifier-p:              Specifier Types.
+* face-differs-from-default-p:           Other Face Display Functions.
+* face-equal:                            Other Face Display Functions.
+* face-font:                             Face Convenience Functions.
+* face-font-instance:                    Face Convenience Functions.
+* face-font-name:                        Face Convenience Functions.
+* face-foreground:                       Face Convenience Functions.
+* face-foreground-instance:              Face Convenience Functions.
+* face-list:                             Basic Face Functions.
+* face-property:                         Face Properties.
+* face-property-instance:                Face Properties.
+* face-underline-p:                      Face Convenience Functions.
+* facep:                                 Basic Face Functions.
+* faces:                                 Faces and Window-System Objects.
+* fallback (in a specifier):             Specifier Instancing.
+* false:                                 nil and t.
+* fboundp:                               Function Cells.
+* fceiling:                              Rounding Operations.
+* featurep:                              Named Features.
+* features:                              Named Features.
+* fetch-bytecode:                        Dynamic Loading.
+* ffloor:                                Rounding Operations.
+* field width:                           Formatting Strings.
+* fifth:                                 List Elements.
+* file accessibility:                    Testing Accessibility.
+* file age:                              Testing Accessibility.
+* file attributes:                       File Attributes.
+* file format conversion:                Format Conversion.
+* file hard link:                        Changing File Attributes.
+* file locks:                            File Locks.
+* file mode specification error:         Auto Major Mode.
+* file modes and MS-DOS:                 Changing File Attributes.
+* file modification time:                Testing Accessibility.
+* file name completion subroutines:      File Name Completion.
+* file name of buffer:                   Buffer File Name.
+* file name of directory:                Directory Names.
+* file names:                            File Names.
+* file names in directory:               Contents of Directories.
+* file open error:                       Subroutines of Visiting.
+* file symbolic links:                   Kinds of Files.
+* file types on MS-DOS:                  Files and MS-DOS.
+* file with multiple names:              Changing File Attributes.
+* file-accessible-directory-p:           Testing Accessibility.
+* file-already-exists:                   Changing File Attributes.
+* file-attributes:                       File Attributes.
+* file-directory-p:                      Kinds of Files.
+* file-error:                            How Programs Do Loading.
+* file-executable-p:                     Testing Accessibility.
+* file-exists-p:                         Testing Accessibility.
+* file-local-copy:                       Magic File Names.
+* file-locked:                           File Locks.
+* file-locked-p:                         File Locks.
+* file-menu-filter:                      Menu Filters.
+* file-modes:                            File Attributes.
+* file-name-absolute-p:                  Relative File Names.
+* file-name-all-completions:             File Name Completion.
+* file-name-as-directory:                Directory Names.
+* file-name-buffer-file-type-alist:      Files and MS-DOS.
+* file-name-completion:                  File Name Completion.
+* file-name-directory:                   File Name Components.
+* file-name-history:                     Minibuffer History.
+* file-name-nondirectory:                File Name Components.
+* file-name-sans-extension:              File Name Components.
+* file-name-sans-versions:               File Name Components.
+* file-newer-than-file-p:                Testing Accessibility.
+* file-newest-backup:                    Backup Names.
+* file-nlinks:                           File Attributes.
+* file-ownership-preserved-p:            Testing Accessibility.
+* file-precious-flag:                    Saving Buffers.
+* file-readable-p:                       Testing Accessibility.
+* file-regular-p:                        Kinds of Files.
+* file-relative-name:                    File Name Expansion.
+* file-supersession:                     Modification Time.
+* file-symlink-p:                        Kinds of Files.
+* file-truename:                         Truenames.
+* file-writable-p:                       Testing Accessibility.
+* fill-column:                           Margins.
+* fill-individual-paragraphs:            Filling.
+* fill-individual-varying-indent:        Filling.
+* fill-paragraph:                        Filling.
+* fill-paragraph-function:               Filling.
+* fill-prefix:                           Margins.
+* fill-region:                           Filling.
+* fill-region-as-paragraph:              Filling.
+* fillarray:                             Array Functions.
+* filling a paragraph:                   Filling.
+* filling, automatic:                    Auto Filling.
+* filling, explicit:                     Filling.
+* filter function:                       Filter Functions.
+* find-backup-file-name:                 Backup Names.
+* find-buffer-file-type:                 Files and MS-DOS.
+* find-charset:                          Basic Charset Functions.
+* find-charset-region:                   MULE Characters.
+* find-charset-string:                   MULE Characters.
+* find-coding-system:                    Basic Coding System Functions.
+* find-file:                             Visiting Functions.
+* find-file-binary:                      Files and MS-DOS.
+* find-file-hooks:                       Visiting Functions.
+* find-file-name-handler:                Magic File Names.
+* find-file-noselect:                    Visiting Functions.
+* find-file-not-found-hooks:             Visiting Functions.
+* find-file-other-window:                Visiting Functions.
+* find-file-read-only:                   Visiting Functions.
+* find-file-text:                        Files and MS-DOS.
+* find-menu-item:                        Modifying Menus.
+* finding files:                         Visiting Files.
+* finding windows:                       Selecting Windows.
+* first:                                 List Elements.
+* first-change-hook:                     Change Hooks.
+* fixup-whitespace:                      User-Level Deletion.
+* float:                                 Numeric Conversions.
+* float-output-format:                   Output Variables.
+* floating-point numbers, printing:      Output Variables.
+* floatp:                                Predicates on Numbers.
+* floor:                                 Numeric Conversions.
+* flow control characters:               Flow Control.
+* flush input:                           Peeking and Discarding.
+* fmakunbound:                           Function Cells.
+* focus-frame:                           Input Focus.
+* following-char:                        Near Point.
+* font instance characteristics:         Font Instance Characteristics.
+* font instance name:                    Font Instance Names.
+* font instance size:                    Font Instance Size.
+* font instance type:                    Font Instance Type.
+* font-instance-name:                    Font Instance Names.
+* font-instance-p:                       Font Instances.
+* font-instance-properties:              Font Instance Characteristics.
+* font-instance-truename:                Font Instance Names.
+* font-name:                             Font Convenience Functions.
+* font-properties:                       Font Convenience Functions.
+* font-specifier-p <1>:                  Font Specifiers.
+* font-specifier-p:                      Specifier Types.
+* font-truename:                         Font Convenience Functions.
+* fonts <1>:                             Fonts.
+* fonts:                                 Some Terms.
+* fonts available:                       Font Instance Names.
+* foo:                                   A Sample Function Description.
+* for:                                   Argument Evaluation.
+* force-cursor-redisplay:                Refresh Screen.
+* force-highlight-extent:                Extents and Events.
+* forcing redisplay:                     Waiting.
+* format:                                Formatting Strings.
+* format definition:                     Format Conversion.
+* format of keymaps:                     Format of Keymaps.
+* format of menus:                       Menu Format.
+* format of the menubar:                 Menubar Format.
+* format precision:                      Formatting Strings.
+* format specification:                  Formatting Strings.
+* format-alist:                          Format Conversion.
+* format-buffers-menu-line:              Buffers Menu.
+* format-find-file:                      Format Conversion.
+* format-insert-file:                    Format Conversion.
+* format-time-string:                    Time Conversion.
+* format-write-file:                     Format Conversion.
+* formatting strings:                    Formatting Strings.
+* formfeed:                              Character Type.
+* forms:                                 Intro Eval.
+* forward-char:                          Character Motion.
+* forward-comment:                       Parsing Expressions.
+* forward-line:                          Text Lines.
+* forward-list:                          List Motion.
+* forward-sexp:                          List Motion.
+* forward-to-indentation:                Motion by Indent.
+* forward-word:                          Word Motion.
+* fourth:                                List Elements.
+* frame:                                 Frames.
+* frame configuration:                   Frame Configurations.
+* frame hooks:                           Frame Hooks.
+* frame name:                            Frame Name.
+* frame of terminal:                     Basic Windows.
+* frame position:                        Size and Position.
+* frame size:                            Size and Position.
+* frame visibility:                      Visibility of Frames.
+* frame-device:                          Basic Device Functions.
+* frame-height:                          Size and Position.
+* frame-highest-window:                  Frames and Windows.
+* frame-icon-title-format:               Frame Titles.
+* frame-iconified-p:                     Visibility of Frames.
+* frame-leftmost-window:                 Frames and Windows.
+* frame-list:                            Finding All Frames.
+* frame-live-p:                          Deleting Frames.
+* frame-lowest-window:                   Frames and Windows.
+* frame-name:                            Frame Name.
+* frame-pixel-height:                    Size and Position.
+* frame-pixel-width:                     Size and Position.
+* frame-properties:                      Property Access.
+* frame-property:                        Property Access.
+* frame-rightmost-window:                Frames and Windows.
+* frame-root-window:                     Frames and Windows.
+* frame-selected-window:                 Frames and Windows.
+* frame-title-format:                    Frame Titles.
+* frame-totally-visible-p:               Visibility of Frames.
+* frame-visible-p:                       Visibility of Frames.
+* frame-width:                           Size and Position.
+* framep:                                Frames.
+* free list:                             Garbage Collection.
+* frequency counts:                      Coverage Testing.
+* fround:                                Rounding Operations.
+* fset:                                  Function Cells.
+* ftp-login:                             Cleanups.
+* ftruncate:                             Rounding Operations.
+* funcall:                               Calling Functions.
+* funcall, and debugging:                Internals of Debugger.
+* function <1>:                          Anonymous Functions.
+* function:                              What Is a Function.
+* function call:                         Function Forms.
+* function call debugging:               Function Debugging.
+* function cell:                         Symbol Components.
+* function cell in autoload:             Autoload.
+* function definition:                   Function Names.
+* function descriptions:                 A Sample Function Description.
+* function form evaluation:              Function Forms.
+* function input stream:                 Input Streams.
+* function invocation:                   Calling Functions.
+* function name:                         Function Names.
+* function output stream:                Output Streams.
+* function quoting:                      Anonymous Functions.
+* function-interactive:                  Using Interactive.
+* function-key-map:                      Translating Input.
+* function-obsoleteness-doc:             Obsoleteness.
+* functionals:                           Calling Functions.
+* functions in modes:                    Major Mode Conventions.
+* functions, making them interactive:    Defining Commands.
+* Fundamental mode:                      Major Modes.
+* fundamental-mode:                      Auto Major Mode.
+* fundamental-mode-abbrev-table:         Standard Abbrev Tables.
+* garbage collector:                     Garbage Collection.
+* garbage-collect:                       Garbage Collection.
+* gc-cons-threshold:                     Garbage Collection.
+* gc-message:                            Garbage Collection.
+* gc-pointer-glyph <1>:                  Garbage Collection.
+* gc-pointer-glyph:                      Mouse Pointer.
+* generate-new-buffer:                   Creating Buffers.
+* generate-new-buffer-name:              Buffer Names.
+* generic-specifier-p:                   Specifier Types.
+* get:                                   Object Plists.
+* get-buffer:                            Buffer Names.
+* get-buffer-create:                     Creating Buffers.
+* get-buffer-process:                    Process Buffers.
+* get-buffer-window:                     Buffers and Windows.
+* get-char-property:                     Examining Properties.
+* get-char-table:                        Working With Char Tables.
+* get-charset:                           Basic Charset Functions.
+* get-coding-system:                     Basic Coding System Functions.
+* get-database:                          Working With a Database.
+* get-file-buffer:                       Buffer File Name.
+* get-largest-window:                    Selecting Windows.
+* get-lru-window:                        Selecting Windows.
+* get-process:                           Process Information.
+* get-range-char-table:                  Working With Char Tables.
+* get-range-table:                       Working With Range Tables.
+* get-register:                          Registers.
+* get-text-property:                     Examining Properties.
+* get-tooltalk-message-attribute:        Elisp Interface for Sending Messages.
+* getenv:                                System Environment.
+* getf:                                  Other Plists.
+* gethash:                               Working With Hash Tables.
+* gettext:                               Level 3 Primitives.
+* global binding:                        Local Variables.
+* global break condition:                Global Break Condition.
+* global keymap:                         Active Keymaps.
+* global mark ring:                      The Mark.
+* global variable:                       Global Variables.
+* global-abbrev-table:                   Standard Abbrev Tables.
+* global-key-binding:                    Functions for Key Lookup.
+* global-map:                            Active Keymaps.
+* global-mark-ring:                      The Mark.
+* global-mode-string:                    Modeline Variables.
+* global-popup-menu:                     Pop-Up Menus.
+* global-set-key:                        Key Binding Commands.
+* global-unset-key:                      Key Binding Commands.
+* glyph type:                            Glyph Type.
+* glyph-ascent:                          Glyph Dimensions.
+* glyph-baseline:                        Glyph Convenience Functions.
+* glyph-baseline-instance:               Glyph Convenience Functions.
+* glyph-contrib-p:                       Glyph Convenience Functions.
+* glyph-contrib-p-instance:              Glyph Convenience Functions.
+* glyph-descent:                         Glyph Dimensions.
+* glyph-face:                            Glyph Convenience Functions.
+* glyph-height:                          Glyph Dimensions.
+* glyph-image:                           Glyph Convenience Functions.
+* glyph-image-instance:                  Glyph Convenience Functions.
+* glyph-property:                        Glyph Properties.
+* glyph-property-instance:               Glyph Properties.
+* glyph-type:                            Glyph Types.
+* glyph-type-list:                       Glyph Types.
+* glyph-width:                           Glyph Dimensions.
+* glyphp:                                Glyphs.
+* glyphs:                                Glyphs.
+* goto-char:                             Character Motion.
+* goto-line:                             Text Lines.
+* gutter:                                Gutter.
+* gutter-buttons-captioned-p:            Other Gutter Variables.
+* gutter-make-button-list:               Gutter Descriptor Format.
+* gutter-specifier-p:                    Specifying a Gutter.
+* hack-local-variables:                  Auto Major Mode.
+* handling errors:                       Handling Errors.
+* hash notation:                         Printed Representation.
+* hash table:                            Hash Tables.
+* hash table type:                       Hash Table Type.
+* hash table, weak:                      Weak Hash Tables.
+* hash-table-count:                      Introduction to Hash Tables.
+* hash-table-p:                          Hash Tables.
+* hash-table-rehash-size:                Introduction to Hash Tables.
+* hash-table-rehash-threshold:           Introduction to Hash Tables.
+* hash-table-size:                       Introduction to Hash Tables.
+* hash-table-test:                       Introduction to Hash Tables.
+* hash-table-weakness:                   Introduction to Hash Tables.
+* hashing:                               Creating Symbols.
+* header comments:                       Library Headers.
+* help for major mode:                   Mode Help.
+* help-char:                             Help Functions.
+* help-command:                          Help Functions.
+* help-form:                             Help Functions.
+* help-map <1>:                          Standard Keymaps.
+* help-map:                              Help Functions.
+* Helper-describe-bindings:              Help Functions.
+* Helper-help:                           Help Functions.
+* Helper-help-map:                       Standard Keymaps.
+* hide-annotation:                       Annotation Properties.
+* highlight-extent:                      Extents and Events.
+* history list:                          Minibuffer History.
+* history of commands:                   Command History.
+* HOME environment variable:             Subprocess Creation.
+* hooks:                                 Hooks.
+* hooks for loading:                     Hooks for Loading.
+* hooks for text changes:                Change Hooks.
+* horizontal position:                   Columns.
+* horizontal scrolling:                  Horizontal Scrolling.
+* hscroll-glyph:                         Redisplay Glyphs.
+* icon-glyph-p:                          Glyph Types.
+* iconified frame:                       Visibility of Frames.
+* iconify-frame:                         Visibility of Frames.
+* identity:                              Calling Functions.
+* IEEE floating point:                   Float Basics.
+* if:                                    Conditionals.
+* ignore:                                Calling Functions.
+* ignored-local-variables:               Auto Major Mode.
+* image instance type:                   Image Instance Type.
+* image instance types:                  Image Instance Types.
+* image instances:                       Image Instances.
+* image instantiator conversion:         Image Instantiator Conversion.
+* image specifiers:                      Image Specifiers.
+* image-instance-background:             Image Instance Functions.
+* image-instance-depth:                  Image Instance Functions.
+* image-instance-domain:                 Image Instance Functions.
+* image-instance-file-name:              Image Instance Functions.
+* image-instance-foreground:             Image Instance Functions.
+* image-instance-height:                 Image Instance Functions.
+* image-instance-hotspot-x:              Image Instance Functions.
+* image-instance-hotspot-y:              Image Instance Functions.
+* image-instance-mask-file-name:         Image Instance Functions.
+* image-instance-name:                   Image Instance Functions.
+* image-instance-p:                      Image Instances.
+* image-instance-string:                 Image Instance Functions.
+* image-instance-type:                   Image Instance Types.
+* image-instance-type-list:              Image Instance Types.
+* image-instance-width:                  Image Instance Functions.
+* image-instantiator-format-list:        Image Specifiers.
+* image-specifier-p <1>:                 Image Specifiers.
+* image-specifier-p:                     Specifier Types.
+* implicit progn:                        Sequencing.
+* inc:                                   Simple Macro.
+* indent-according-to-mode:              Mode-Specific Indent.
+* indent-code-rigidly:                   Region Indent.
+* indent-for-tab-command:                Mode-Specific Indent.
+* indent-line-function:                  Mode-Specific Indent.
+* indent-region:                         Region Indent.
+* indent-region-function:                Region Indent.
+* indent-relative:                       Relative Indent.
+* indent-relative-maybe:                 Relative Indent.
+* indent-rigidly:                        Region Indent.
+* indent-tabs-mode:                      Primitive Indent.
+* indent-to:                             Primitive Indent.
+* indent-to-left-margin:                 Margins.
+* indentation:                           Indentation.
+* indenting with parentheses:            Parsing Expressions.
+* indirect buffers:                      Indirect Buffers.
+* indirect specifications:               Specification List.
+* indirect variables:                    Variable Aliases.
+* indirect-function:                     Function Indirection.
+* indirect-variable:                     Variable Aliases.
+* indirection:                           Function Indirection.
+* infinite loops:                        Infinite Loops.
+* infinite recursion:                    Local Variables.
+* infinity:                              Float Basics.
+* Info-edit-map:                         Standard Keymaps.
+* Info-minibuffer-history:               Minibuffer History.
+* Info-mode-map:                         Standard Keymaps.
+* inherit:                               Syntax Class Table.
+* inheriting a keymap's bindings:        Inheritance and Keymaps.
+* inhibit-default-init:                  Init File.
+* inhibit-file-name-handlers:            Magic File Names.
+* inhibit-file-name-operation:           Magic File Names.
+* inhibit-quit:                          Quitting.
+* inhibit-read-only:                     Read Only Buffers.
+* inhibit-startup-echo-area-message:     Start-up Summary.
+* inhibit-startup-message:               Start-up Summary.
+* init file:                             Init File.
+* initial-frame-plist:                   Initial Properties.
+* initial-gutter-spec:                   Other Gutter Variables.
+* initial-major-mode:                    Auto Major Mode.
+* initial-toolbar-spec:                  Other Toolbar Variables.
+* initialization:                        Start-up Summary.
+* inline functions:                      Inline Functions.
+* innermost containing parentheses:      Parsing Expressions.
+* input events:                          Events.
+* input focus:                           Input Focus.
+* input modes:                           Input Modes.
+* input stream:                          Input Streams.
+* input-pending-p:                       Peeking and Discarding.
+* insert:                                Insertion.
+* insert-abbrev-table-description:       Abbrev Tables.
+* insert-before-markers:                 Insertion.
+* insert-buffer:                         Commands for Insertion.
+* insert-buffer-substring:               Insertion.
+* insert-char:                           Insertion.
+* insert-default-directory:              Reading File Names.
+* insert-directory:                      Contents of Directories.
+* insert-directory-program:              Contents of Directories.
+* insert-extent:                         Detached Extents.
+* insert-file-contents:                  Reading from Files.
+* insert-register:                       Registers.
+* insert-string:                         Insertion.
+* inserting killed text:                 Yank Commands.
+* insertion before point:                Insertion.
+* insertion of text:                     Insertion.
+* inside comment:                        Parsing Expressions.
+* inside margin:                         Annotation Basics.
+* inside string:                         Parsing Expressions.
+* inst-list (in a specifier):            Specifiers In-Depth.
+* inst-pair (in a specifier):            Specifiers In-Depth.
+* installation-directory:                System Environment.
+* instance (in a specifier):             Specifiers In-Depth.
+* instancing (in a specifier):           Specifiers In-Depth.
+* instantiator (in a specifier):         Specifiers In-Depth.
+* int-char:                              Character Codes.
+* int-to-string:                         String Conversion.
+* integer to decimal:                    String Conversion.
+* integer to hexadecimal:                Formatting Strings.
+* integer to octal:                      Formatting Strings.
+* integer to string:                     String Conversion.
+* integer-char-or-marker-p:              Predicates on Markers.
+* integer-or-char-p:                     Predicates for Characters.
+* integer-or-marker-p:                   Predicates on Markers.
+* integer-specifier-p:                   Specifier Types.
+* integerp:                              Predicates on Numbers.
+* integers:                              Numbers.
+* interactive:                           Using Interactive.
+* interactive call:                      Interactive Call.
+* interactive code description:          Interactive Codes.
+* interactive commands (Edebug):         Instrumenting.
+* interactive completion:                Interactive Codes.
+* interactive function:                  Defining Commands.
+* interactive, examples of using:        Interactive Examples.
+* interactive-p:                         Interactive Call.
+* intern:                                Creating Symbols.
+* intern-soft:                           Creating Symbols.
+* internal-doc-file-name:                Accessing Documentation.
+* interning:                             Creating Symbols.
+* interpreter:                           Evaluation.
+* interpreter-mode-alist:                Auto Major Mode.
+* interprogram-cut-function:             Low-Level Kill Ring.
+* interprogram-paste-function:           Low-Level Kill Ring.
+* interrupt-process:                     Signals to Processes.
+* invalid function:                      Function Indirection.
+* invalid prefix key error:              Changing Key Bindings.
+* invalid-function:                      Function Indirection.
+* invalid-read-syntax:                   Printed Representation.
+* invalid-regexp:                        Syntax of Regexps.
+* invert-face:                           Other Face Display Functions.
+* invisible frame:                       Visibility of Frames.
+* invisible text:                        Invisible Text.
+* invisible-text-glyph:                  Redisplay Glyphs.
+* invocation-directory:                  System Environment.
+* invocation-name:                       System Environment.
+* isearch-mode-map:                      Standard Keymaps.
+* ISO Latin 1:                           Case Tables.
+* ISO Latin-1 characters (input):        Translating Input.
+* iso-syntax:                            Case Tables.
+* iso-transl:                            Translating Input.
+* italic:                                Font Instance Characteristics.
+* iteration:                             Iteration.
+* itimer-edit-map:                       Standard Keymaps.
+* joining lists:                         Rearrangement.
+* just-one-space:                        User-Level Deletion.
+* justify-current-line:                  Filling.
+* kept-new-versions:                     Numbered Backups.
+* kept-old-versions:                     Numbered Backups.
+* key:                                   Keymap Terminology.
+* key binding:                           Keymap Terminology.
+* key lookup:                            Key Lookup.
+* key sequence:                          Key Sequence Input.
+* key sequence error:                    Changing Key Bindings.
+* key sequence input:                    Key Sequence Input.
+* key sequences:                         Key Sequences.
+* key translation function:              Translating Input.
+* key-binding:                           Functions for Key Lookup.
+* key-description:                       Describing Characters.
+* key-press-event-p:                     Event Predicates.
+* key-translation-map:                   Translating Input.
+* keyboard macro execution:              Interactive Call.
+* keyboard macro termination:            Beeping.
+* keyboard macros:                       Keyboard Macros.
+* keyboard macros (Edebug):              Edebug Execution Modes.
+* keyboard menu accelerators:            Menu Accelerators.
+* keyboard-quit:                         Quitting.
+* keymap:                                Keymaps.
+* keymap entry:                          Key Lookup.
+* keymap format:                         Format of Keymaps.
+* keymap in keymap:                      Key Lookup.
+* keymap inheritance:                    Inheritance and Keymaps.
+* keymap parent:                         Inheritance and Keymaps.
+* keymap-default-binding:                Inheritance and Keymaps.
+* keymap-fullness:                       Scanning Keymaps.
+* keymap-name:                           Creating Keymaps.
+* keymap-parents:                        Inheritance and Keymaps.
+* keymap-prompt:                         Other Keymap Functions.
+* keymapp:                               Format of Keymaps.
+* keymaps in modes:                      Major Mode Conventions.
+* keys in documentation strings:         Keys in Documentation.
+* keystroke:                             Keymap Terminology.
+* keystroke command:                     What Is a Function.
+* keywordp:                              Specification List.
+* kill command repetition:               Command Loop Info.
+* kill ring:                             The Kill Ring.
+* kill-all-local-variables:              Creating Buffer-Local.
+* kill-append:                           Low-Level Kill Ring.
+* kill-buffer:                           Killing Buffers.
+* kill-buffer-hook:                      Killing Buffers.
+* kill-buffer-query-functions:           Killing Buffers.
+* kill-emacs:                            Killing XEmacs.
+* kill-emacs-hook:                       Killing XEmacs.
+* kill-emacs-query-functions:            Killing XEmacs.
+* kill-local-variable:                   Creating Buffer-Local.
+* kill-new:                              Low-Level Kill Ring.
+* kill-process:                          Signals to Processes.
+* kill-region:                           Kill Functions.
+* kill-ring:                             Internals of Kill Ring.
+* kill-ring-max:                         Internals of Kill Ring.
+* kill-ring-yank-pointer:                Internals of Kill Ring.
+* killing buffers:                       Killing Buffers.
+* killing XEmacs:                        Killing XEmacs.
+* lambda expression:                     Lambda Expressions.
+* lambda expression in hook:             Hooks.
+* lambda in debug:                       Invoking the Debugger.
+* lambda in keymap:                      Key Lookup.
+* lambda list:                           Lambda Components.
+* lambda-list (Edebug):                  Specification List.
+* lambda-list-keywordp:                  Specification List.
+* last-abbrev:                           Abbrev Expansion.
+* last-abbrev-location:                  Abbrev Expansion.
+* last-abbrev-text:                      Abbrev Expansion.
+* last-command:                          Command Loop Info.
+* last-command-char:                     Command Loop Info.
+* last-command-event:                    Command Loop Info.
+* last-input-char:                       Peeking and Discarding.
+* last-input-event:                      Peeking and Discarding.
+* last-kbd-macro:                        Keyboard Macros.
+* Latin-1 character set (input):         Translating Input.
+* lax-plist-get:                         Working With Lax Plists.
+* lax-plist-member:                      Working With Lax Plists.
+* lax-plist-put:                         Working With Lax Plists.
+* lax-plist-remprop:                     Working With Lax Plists.
+* lax-plists-eq:                         Working With Lax Plists.
+* lax-plists-equal:                      Working With Lax Plists.
+* layout policy:                         Annotation Basics.
+* layout types:                          Annotation Basics.
+* lazy loading:                          Dynamic Loading.
+* LDAP:                                  LDAP Support.
+* ldap-add:                              Low-level Operations on a LDAP Server.
+* ldap-add-entries:                      The High-Level LDAP API.
+* ldap-attribute-syntax-decoders:        LDAP Internationalization Variables.
+* ldap-attribute-syntax-encoders:        LDAP Internationalization Variables.
+* ldap-attribute-syntaxes-alist:         LDAP Internationalization Variables.
+* ldap-close:                            Opening and Closing a LDAP Connection.
+* ldap-coding-system:                    LDAP Internationalization Variables.
+* ldap-decode-address:                   Encoder/Decoder Functions.
+* ldap-decode-attribute:                 LDAP Internationalization.
+* ldap-decode-boolean:                   Encoder/Decoder Functions.
+* ldap-decode-string:                    Encoder/Decoder Functions.
+* ldap-default-attribute-decoder:        LDAP Internationalization Variables.
+* ldap-default-base:                     LDAP Variables.
+* ldap-default-host:                     LDAP Variables.
+* ldap-default-port:                     LDAP Variables.
+* ldap-delete:                           Low-level Operations on a LDAP Server.
+* ldap-delete-entries:                   The High-Level LDAP API.
+* ldap-encode-address:                   Encoder/Decoder Functions.
+* ldap-encode-boolean:                   Encoder/Decoder Functions.
+* ldap-encode-string:                    Encoder/Decoder Functions.
+* ldap-host:                             The LDAP Lisp Object.
+* ldap-host-parameters-alist:            LDAP Variables.
+* ldap-ignore-attribute-codings:         LDAP Internationalization Variables.
+* ldap-live-p:                           The LDAP Lisp Object.
+* ldap-modify:                           Low-level Operations on a LDAP Server.
+* ldap-modify-entries:                   The High-Level LDAP API.
+* ldap-open:                             Opening and Closing a LDAP Connection.
+* ldap-search-basic:                     Low-level Operations on a LDAP Server.
+* ldap-search-entries:                   The High-Level LDAP API.
+* ldap-verbose:                          LDAP Variables.
+* ldapp:                                 The LDAP Lisp Object.
+* left-gutter:                           Specifying a Gutter.
+* left-gutter-visible-p:                 Other Gutter Variables.
+* left-gutter-width:                     Other Gutter Variables.
+* left-margin:                           Margins.
+* left-margin-width:                     Margin Primitives.
+* left-toolbar:                          Specifying the Toolbar.
+* left-toolbar-visible-p:                Other Toolbar Variables.
+* left-toolbar-width:                    Other Toolbar Variables.
+* length:                                Sequence Functions.
+* let:                                   Local Variables.
+* let*:                                  Local Variables.
+* let-specifier:                         Adding Specifications.
+* lexical binding (Edebug):              Edebug Eval.
+* lexical comparison:                    Text Comparison.
+* library <1>:                           Loading.
+* library:                               Package Terminology.
+* library compilation:                   Compilation Functions.
+* library header comments:               Library Headers.
+* line wrapping:                         Truncation.
+* lines:                                 Text Lines.
+* lines in region:                       Text Lines.
+* linking files:                         Changing File Attributes.
+* Lisp debugger:                         Debugger.
+* Lisp expression motion:                List Motion.
+* Lisp history:                          Lisp History.
+* Lisp library:                          Loading.
+* Lisp nesting error:                    Eval.
+* Lisp object:                           Lisp Data Types.
+* Lisp printer:                          Output Functions.
+* Lisp reader:                           Streams Intro.
+* lisp-interaction-mode-map:             Standard Keymaps.
+* lisp-mode-abbrev-table:                Standard Abbrev Tables.
+* lisp-mode-map:                         Standard Keymaps.
+* lisp-mode.el:                          Example Major Modes.
+* list <1>:                              Building Lists.
+* list:                                  Lists.
+* list elements:                         List Elements.
+* list form evaluation:                  Classifying Lists.
+* list in keymap:                        Key Lookup.
+* list length:                           Sequence Functions.
+* list motion:                           List Motion.
+* list structure:                        Cons Cells.
+* list-buffers:                          The Buffer List.
+* list-buffers-directory:                Buffer File Name.
+* list-fonts:                            Font Instance Names.
+* list-processes:                        Process Information.
+* listp:                                 List-related Predicates.
+* lists and cons cells:                  Cons Cells.
+* lists as sets:                         Sets And Lists.
+* lists represented as boxes:            Lists as Boxes.
+* literal evaluation:                    Self-Evaluating Forms.
+* lmessage:                              The Echo Area.
+* ln:                                    Changing File Attributes.
+* load:                                  How Programs Do Loading.
+* load error with require:               Named Features.
+* load errors:                           How Programs Do Loading.
+* load-average:                          System Environment.
+* load-default-sounds:                   Beeping.
+* load-history:                          Unloading.
+* load-ignore-elc-files:                 How Programs Do Loading.
+* load-in-progress:                      How Programs Do Loading.
+* load-path:                             How Programs Do Loading.
+* load-read-function:                    How Programs Do Loading.
+* load-sound-file:                       Beeping.
+* load-warn-when-source-newer:           How Programs Do Loading.
+* load-warn-when-source-only:            How Programs Do Loading.
+* loading:                               Loading.
+* loading hooks:                         Hooks for Loading.
+* loadup.el:                             Building XEmacs.
+* local binding:                         Local Variables.
+* local keymap:                          Active Keymaps.
+* local variables:                       Local Variables.
+* local-abbrev-table:                    Standard Abbrev Tables.
+* local-key-binding:                     Functions for Key Lookup.
+* local-set-key:                         Key Binding Commands.
+* local-unset-key:                       Key Binding Commands.
+* local-variable-p:                      Creating Buffer-Local.
+* local-write-file-hooks:                Saving Buffers.
+* local.rules:                           Local.rules File.
+* locale (in a specifier):               Specifiers In-Depth.
+* locate-file:                           How Programs Do Loading.
+* locate-file-clear-hashing:             How Programs Do Loading.
+* lock-buffer:                           File Locks.
+* log:                                   Math Functions.
+* log-message-ignore-labels:             The Echo Area.
+* log-message-ignore-regexps:            The Echo Area.
+* log-message-max-size:                  The Echo Area.
+* log-warning-minimum-level:             Warnings.
+* log-warning-suppressed-classes:        Warnings.
+* log10:                                 Math Functions.
+* logand:                                Bitwise Operations.
+* logb:                                  Float Basics.
+* logical and:                           Bitwise Operations.
+* logical exclusive or:                  Bitwise Operations.
+* logical inclusive or:                  Bitwise Operations.
+* logical not:                           Bitwise Operations.
+* logical shift:                         Bitwise Operations.
+* logior:                                Bitwise Operations.
+* lognot:                                Bitwise Operations.
+* logxor:                                Bitwise Operations.
+* looking-at:                            Regexp Search.
+* lookup-key:                            Functions for Key Lookup.
+* loops, infinite:                       Infinite Loops.
+* lower case:                            Character Case.
+* lower-frame:                           Raising and Lowering.
+* lowering a frame:                      Raising and Lowering.
+* lsh:                                   Bitwise Operations.
+* lwarn:                                 Warnings.
+* M-x:                                   Interactive Call.
+* Maclisp:                               Lisp History.
+* macro:                                 What Is a Function.
+* macro argument evaluation:             Argument Evaluation.
+* macro call:                            Expansion.
+* macro call evaluation:                 Macro Forms.
+* macro compilation:                     Compilation Functions.
+* macro descriptions:                    A Sample Function Description.
+* macro expansion:                       Expansion.
+* macroexpand:                           Expansion.
+* macros:                                Macros.
+* magic file names:                      Magic File Names.
+* mail-host-address:                     System Environment.
+* major mode:                            Major Modes.
+* major mode hook:                       Major Mode Conventions.
+* major mode keymap:                     Active Keymaps.
+* major-mode:                            Mode Help.
+* make-abbrev-table:                     Abbrev Tables.
+* make-annotation:                       Annotation Primitives.
+* make-auto-save-file-name:              Auto-Saving.
+* make-backup-file-name:                 Backup Names.
+* make-backup-files:                     Making Backups.
+* make-bit-vector:                       Bit Vector Functions.
+* make-boolean-specifier:                Creating Specifiers.
+* make-byte-code:                        Compiled-Function Objects.
+* make-char:                             MULE Characters.
+* make-char-table:                       Working With Char Tables.
+* make-charset:                          Basic Charset Functions.
+* make-coding-system:                    Basic Coding System Functions.
+* make-color-specifier:                  Color Specifiers.
+* make-composite-char:                   Composite Characters.
+* make-device:                           Connecting to a Console or Device.
+* make-directory:                        Create/Delete Dirs.
+* make-display-table:                    Display Table Format.
+* make-display-table-specifier:          Creating Specifiers.
+* make-event:                            Working With Events.
+* make-extent:                           Creating and Modifying Extents.
+* make-face:                             Basic Face Functions.
+* make-face-boolean-specifier:           Color Specifiers.
+* make-file-part:                        Creating a Partial File.
+* make-font-instance:                    Font Instances.
+* make-font-specifier:                   Font Specifiers.
+* make-frame:                            Creating Frames.
+* make-frame-invisible:                  Visibility of Frames.
+* make-frame-visible:                    Visibility of Frames.
+* make-generic-specifier:                Creating Specifiers.
+* make-glyph:                            Creating Glyphs.
+* make-glyph-internal:                   Creating Glyphs.
+* make-gutter-size-specifier:            Creating Gutter.
+* make-gutter-specifier:                 Creating Gutter.
+* make-gutter-visible-specifier:         Creating Gutter.
+* make-hash-table:                       Introduction to Hash Tables.
+* make-icon-glyph:                       Creating Glyphs.
+* make-image-instance:                   Image Instance Functions.
+* make-image-specifier:                  Image Specifiers.
+* make-indirect-buffer:                  Indirect Buffers.
+* make-integer-specifier:                Creating Specifiers.
+* make-keymap:                           Creating Keymaps.
+* make-list:                             Building Lists.
+* make-local-hook:                       Hooks.
+* make-local-variable:                   Creating Buffer-Local.
+* make-marker:                           Creating Markers.
+* make-natnum-specifier:                 Creating Specifiers.
+* make-obsolete:                         Obsoleteness.
+* make-obsolete-variable:                Obsoleteness.
+* make-pointer-glyph:                    Creating Glyphs.
+* make-range-table:                      Introduction to Range Tables.
+* make-reverse-direction-charset:        Basic Charset Functions.
+* make-sparse-keymap:                    Creating Keymaps.
+* make-specifier:                        Creating Specifiers.
+* make-specifier-and-init:               Creating Specifiers.
+* make-string:                           Creating Strings.
+* make-symbol:                           Creating Symbols.
+* make-symbolic-link:                    Changing File Attributes.
+* make-syntax-table:                     Syntax Table Functions.
+* make-temp-name:                        Unique File Names.
+* make-toolbar-specifier:                Creating Toolbar.
+* make-tooltalk-message:                 Elisp Interface for Sending Messages.
+* make-tooltalk-pattern:                 Elisp Interface for Receiving Messages.
+* make-tty-device:                       Connecting to a Console or Device.
+* make-variable-buffer-local:            Creating Buffer-Local.
+* make-vector:                           Vector Functions.
+* make-weak-list:                        Weak Lists.
+* make-x-device:                         Connecting to a Console or Device.
+* Makefile, package:                     Makefile.
+* makunbound:                            Void Variables.
+* Manual-page-minibuffer-history:        Minibuffer History.
+* map-char-table:                        Working With Char Tables.
+* map-database:                          Working With a Database.
+* map-extent-children:                   Mapping Over Extents.
+* map-extents:                           Mapping Over Extents.
+* map-frame-hook:                        Frame Hooks.
+* map-keymap:                            Scanning Keymaps.
+* map-range-table:                       Working With Range Tables.
+* map-specifier:                         Other Specification Functions.
+* map-y-or-n-p:                          Multiple Queries.
+* mapatoms:                              Creating Symbols.
+* mapcar:                                Mapping Functions.
+* mapcar-extents:                        Mapping Over Extents.
+* mapconcat:                             Mapping Functions.
+* maphash:                               Working With Hash Tables.
+* mapping functions:                     Mapping Functions.
+* margin:                                Annotation Basics.
+* margin width:                          Margin Primitives.
+* mark:                                  The Mark.
+* mark excursion:                        Excursions.
+* mark ring:                             The Mark.
+* mark, the:                             The Mark.
+* mark-marker:                           The Mark.
+* mark-ring:                             The Mark.
+* mark-ring-max:                         The Mark.
+* marker argument:                       Interactive Codes.
+* marker garbage collection:             Overview of Markers.
+* marker input stream:                   Input Streams.
+* marker output stream:                  Output Streams.
+* marker relocation:                     Overview of Markers.
+* marker-buffer:                         Information from Markers.
+* marker-position:                       Information from Markers.
+* markerp:                               Predicates on Markers.
+* markers:                               Markers.
+* markers as numbers:                    Overview of Markers.
+* markers vs. extents:                   Overview of Markers.
+* match data:                            Match Data.
+* match-beginning:                       Simple Match Data.
+* match-data:                            Entire Match Data.
+* match-end:                             Simple Match Data.
+* match-string:                          Simple Match Data.
+* mathematical functions:                Math Functions.
+* max:                                   Comparison of Numbers.
+* max-lisp-eval-depth:                   Eval.
+* max-specpdl-size:                      Local Variables.
+* md5:                                   Transformations.
+* MD5 digests:                           Transformations.
+* member:                                Sets And Lists.
+* membership in a list:                  Sets And Lists.
+* memory allocation:                     Garbage Collection.
+* memq:                                  Sets And Lists.
+* menu:                                  Menus.
+* menu accelerators:                     Menu Accelerators.
+* menu filters:                          Menu Filters.
+* menu format:                           Menu Format.
+* menu-accelerator-enabled:              Menu Accelerator Functions.
+* menu-accelerator-map:                  Menu Accelerator Functions.
+* menu-accelerator-modifiers:            Menu Accelerator Functions.
+* menu-accelerator-prefix:               Menu Accelerator Functions.
+* menu-no-selection-hook:                Menubar.
+* menubar:                               Menubar.
+* menubar format:                        Menubar Format.
+* menubar-configuration:                 Menu Format.
+* menubar-pointer-glyph:                 Mouse Pointer.
+* menubar-show-keybindings:              Menubar.
+* message:                               The Echo Area.
+* meta character printing:               Describing Characters.
+* meta-prefix-char:                      Functions for Key Lookup.
+* min:                                   Comparison of Numbers.
+* minibuffer:                            Minibuffers.
+* minibuffer history:                    Minibuffer History.
+* minibuffer input:                      Recursive Editing.
+* minibuffer window:                     Cyclic Window Ordering.
+* minibuffer-complete:                   Completion Commands.
+* minibuffer-complete-and-exit:          Completion Commands.
+* minibuffer-complete-word:              Completion Commands.
+* minibuffer-completion-confirm:         Completion Commands.
+* minibuffer-completion-help:            Completion Commands.
+* minibuffer-completion-predicate:       Completion Commands.
+* minibuffer-completion-table:           Completion Commands.
+* minibuffer-depth:                      Minibuffer Misc.
+* minibuffer-exit-hook:                  Minibuffer Misc.
+* minibuffer-frame-plist:                Initial Properties.
+* minibuffer-help-form:                  Minibuffer Misc.
+* minibuffer-history:                    Minibuffer History.
+* minibuffer-local-completion-map <1>:   Standard Keymaps.
+* minibuffer-local-completion-map:       Completion Commands.
+* minibuffer-local-isearch-map:          Standard Keymaps.
+* minibuffer-local-map <1>:              Standard Keymaps.
+* minibuffer-local-map:                  Text from Minibuffer.
+* minibuffer-local-must-match-map <1>:   Standard Keymaps.
+* minibuffer-local-must-match-map:       Completion Commands.
+* minibuffer-prompt:                     Minibuffer Misc.
+* minibuffer-prompt-width:               Minibuffer Misc.
+* minibuffer-scroll-window:              Minibuffer Misc.
+* minibuffer-setup-hook:                 Minibuffer Misc.
+* minibuffer-window:                     Minibuffer Misc.
+* minibuffer-window-active-p:            Minibuffer Misc.
+* minimum window size:                   Resizing Windows.
+* minor mode:                            Minor Modes.
+* minor mode conventions:                Minor Mode Conventions.
+* minor-mode-alist:                      Modeline Variables.
+* minor-mode-key-binding:                Functions for Key Lookup.
+* minor-mode-map-alist:                  Active Keymaps.
+* misc-user-event-p:                     Event Predicates.
+* mod:                                   Arithmetic Operations.
+* mode:                                  Modes.
+* mode help:                             Mode Help.
+* mode hook:                             Major Mode Conventions.
+* mode loading:                          Major Mode Conventions.
+* mode variable:                         Minor Mode Conventions.
+* mode-class property:                   Major Mode Conventions.
+* mode-name:                             Modeline Variables.
+* mode-popup-menu:                       Pop-Up Menus.
+* mode-specific-map <1>:                 Standard Keymaps.
+* mode-specific-map:                     Prefix Keys.
+* modeline:                              Modeline Format.
+* modeline construct:                    Modeline Data.
+* modeline-buffer-identification:        Modeline Variables.
+* modeline-format:                       Modeline Data.
+* modeline-map <1>:                      Standard Keymaps.
+* modeline-map:                          Active Keymaps.
+* modeline-modified:                     Modeline Variables.
+* modeline-pointer-glyph:                Mouse Pointer.
+* modeline-process:                      Modeline Variables.
+* modification flag (of buffer):         Buffer Modification.
+* modification of lists:                 Rearrangement.
+* modification time, comparison of:      Modification Time.
+* modify-syntax-entry:                   Syntax Table Functions.
+* modulus:                               Arithmetic Operations.
+* momentary-string-display:              Temporary Displays.
+* mono-pixmap-image-instance-p:          Image Instance Types.
+* motion-event-p:                        Event Predicates.
+* mouse cursor:                          Mouse Pointer.
+* mouse pointer:                         Mouse Pointer.
+* mouse-event-p:                         Event Predicates.
+* mouse-grabbed-buffer:                  Active Keymaps.
+* mouse-highlight-priority:              Extents and Events.
+* move-marker:                           Changing Markers.
+* move-to-column:                        Columns.
+* move-to-left-margin:                   Margins.
+* move-to-window-line:                   Screen Lines.
+* MS-DOS and file modes:                 Changing File Attributes.
+* MS-DOS file types:                     Files and MS-DOS.
+* MSWindows OLE:                         MSWindows OLE.
+* multilingual string formatting:        Formatting Strings.
+* multiple windows:                      Basic Windows.
+* named function:                        Function Names.
+* NaN:                                   Float Basics.
+* narrow-to-page:                        Narrowing.
+* narrow-to-region:                      Narrowing.
+* narrowing:                             Narrowing.
+* natnum-specifier-p:                    Specifier Types.
+* natnump:                               Predicates on Numbers.
+* natural numbers:                       Predicates on Numbers.
+* nconc:                                 Rearrangement.
+* negative infinity:                     Float Basics.
+* negative-argument:                     Prefix Command Arguments.
+* network connection:                    Network.
+* new file message:                      Subroutines of Visiting.
+* newline <1>:                           Commands for Insertion.
+* newline:                               Character Type.
+* newline and Auto Fill mode:            Commands for Insertion.
+* newline in print:                      Output Functions.
+* newline in strings:                    String Type.
+* newline-and-indent:                    Mode-Specific Indent.
+* next input:                            Peeking and Discarding.
+* next-command-event:                    Reading One Event.
+* next-event:                            Reading One Event.
+* next-extent:                           Finding Extents.
+* next-frame:                            Finding All Frames.
+* next-history-element:                  Minibuffer Misc.
+* next-matching-history-element:         Minibuffer Misc.
+* next-property-change:                  Property Search.
+* next-screen-context-lines:             Vertical Scrolling.
+* next-single-property-change:           Property Search.
+* next-window:                           Cyclic Window Ordering.
+* nil:                                   Constant Variables.
+* nil and lists:                         Cons Cells.
+* nil in keymap:                         Key Lookup.
+* nil in lists:                          Cons Cell Type.
+* nil input stream:                      Input Streams.
+* nil output stream:                     Output Streams.
+* nil, uses of:                          nil and t.
+* ninth:                                 List Elements.
+* nlistp:                                List-related Predicates.
+* no-catch:                              Catch and Throw.
+* no-redraw-on-reenter:                  Refresh Screen.
+* nondirectory part (of file name):      File Name Components.
+* noninteractive:                        Batch Mode.
+* noninteractive use:                    Batch Mode.
+* nonlocal exits:                        Nonlocal Exits.
+* nonprinting characters, reading:       Quoted Character Input.
+* nontext-pointer-glyph:                 Mouse Pointer.
+* normal-mode:                           Auto Major Mode.
+* not:                                   Combining Conditions.
+* not-modified:                          Buffer Modification.
+* nothing-image-instance-p:              Image Instance Types.
+* nreverse:                              Rearrangement.
+* nth:                                   List Elements.
+* nthcdr:                                List Elements.
+* null:                                  List-related Predicates.
+* number equality:                       Comparison of Numbers.
+* number-char-or-marker-p:               Predicates on Markers.
+* number-or-marker-p:                    Predicates on Markers.
+* number-to-string:                      String Conversion.
+* numberp:                               Predicates on Numbers.
+* numbers:                               Numbers.
+* numeric prefix:                        Formatting Strings.
+* numeric prefix argument:               Prefix Command Arguments.
+* numeric prefix argument usage:         Interactive Codes.
+* obarray:                               Creating Symbols.
+* obarray in completion:                 Basic Completion.
+* objc-mode-map:                         Standard Keymaps.
+* object:                                Lisp Data Types.
+* object to string:                      Output Functions.
+* object-plist:                          Object Plists.
+* oblique:                               Font Instance Characteristics.
+* obsolete buffer:                       Modification Time.
+* occur-mode-map:                        Standard Keymaps.
+* octal character code:                  Character Type.
+* octal character input:                 Quoted Character Input.
+* octal-escape-glyph:                    Redisplay Glyphs.
+* OffiX DND:                             OffiX DND.
+* old-eq:                                Equality Predicates.
+* one-window-p:                          Splitting Windows.
+* only-global-abbrevs:                   Defining Abbrevs.
+* open-database:                         Connecting to a Database.
+* open-dribble-file:                     Recording Input.
+* open-network-stream:                   Network.
+* open-termscript:                       Terminal Output.
+* open parenthesis character:            Syntax Class Table.
+* operating system environment:          System Environment.
+* option descriptions:                   A Sample Variable Description.
+* optional arguments:                    Argument List.
+* options on command line:               Command Line Arguments.
+* or:                                    Combining Conditions.
+* order of extents:                      Extent Endpoints.
+* ordering of windows, cyclic:           Cyclic Window Ordering.
+* other-buffer:                          The Buffer List.
+* other-window:                          Cyclic Window Ordering.
+* other-window-scroll-buffer:            Vertical Scrolling.
+* Outline mode:                          Substitution.
+* output from processes:                 Output from Processes.
+* output stream:                         Output Streams.
+* outside margin:                        Annotation Basics.
+* overflow:                              Integer Basics.
+* overlay arrow:                         Overlay Arrow.
+* overlay-arrow-position:                Overlay Arrow.
+* overlay-arrow-string:                  Overlay Arrow.
+* overriding-local-map <1>:              Standard Keymaps.
+* overriding-local-map:                  Active Keymaps.
+* overriding-terminal-local-map:         Active Keymaps.
+* overwrite-mode:                        Commands for Insertion.
+* package <1>:                           Package Terminology.
+* package:                               Packaging.
+* package building:                      Building Packages.
+* package distributions:                 Package Terminology.
+* package Makefile:                      Makefile.
+* package makefile targets:              Makefile Targets.
+* package-compile.el:                    Makefile.
+* package-info:                          package-info.in.
+* package-info.in:                       package-info.in.
+* packaging:                             Packaging.
+* padding:                               Formatting Strings.
+* page-delimiter:                        Standard Regexps.
+* paired delimiter:                      Syntax Class Table.
+* paragraph-separate:                    Standard Regexps.
+* paragraph-start:                       Standard Regexps.
+* parent of a keymap:                    Inheritance and Keymaps.
+* parent process:                        Processes.
+* parent, of extent:                     Extent Parents.
+* parenthesis:                           Cons Cell Type.
+* parenthesis depth:                     Parsing Expressions.
+* parenthesis matching:                  Blinking.
+* parenthesis syntax:                    Syntax Class Table.
+* parse state:                           Parsing Expressions.
+* parse-partial-sexp:                    Parsing Expressions.
+* parse-sexp-ignore-comments:            Parsing Expressions.
+* parsing:                               Syntax Tables.
+* partial files:                         Partial Files.
+* passwd-echo:                           Reading a Password.
+* passwd-invert-frame-when-keyboard-grabbed: Reading a Password.
+* passwords, reading:                    Reading a Password.
+* PATH environment variable:             Subprocess Creation.
+* path-separator:                        System Environment.
+* pausing:                               Waiting.
+* peeking at input:                      Peeking and Discarding.
+* percent symbol in modeline:            Modeline Data.
+* perform-replace:                       Search and Replace.
+* performance analysis:                  Coverage Testing.
+* permanent local variable:              Creating Buffer-Local.
+* permission:                            File Attributes.
+* pg-coding-system:                      libpq Lisp Variables.
+* pg:authtype:                           libpq Lisp Variables.
+* pg:client-encoding:                    libpq Lisp Variables.
+* pg:cost-heap:                          libpq Lisp Variables.
+* pg:cost-index:                         libpq Lisp Variables.
+* pg:database:                           libpq Lisp Variables.
+* pg:date-style:                         libpq Lisp Variables.
+* pg:geqo:                               libpq Lisp Variables.
+* pg:host:                               libpq Lisp Variables.
+* pg:options:                            libpq Lisp Variables.
+* pg:port:                               libpq Lisp Variables.
+* pg:realm:                              libpq Lisp Variables.
+* pg:tty:                                libpq Lisp Variables.
+* pg:tz:                                 libpq Lisp Variables.
+* pg:user:                               libpq Lisp Variables.
+* pgres::polling-active:                 libpq Lisp Symbols and DataTypes.
+* pgres::polling-failed:                 libpq Lisp Symbols and DataTypes.
+* pgres::polling-ok:                     libpq Lisp Symbols and DataTypes.
+* pgres::polling-reading:                libpq Lisp Symbols and DataTypes.
+* pgres::polling-writing:                libpq Lisp Symbols and DataTypes.
+* pipes:                                 Asynchronous Processes.
+* play-sound:                            Beeping.
+* play-sound-file:                       Beeping.
+* plist:                                 Property Lists.
+* plist, symbol:                         Symbol Properties.
+* plist-get:                             Working With Normal Plists.
+* plist-member:                          Working With Normal Plists.
+* plist-put:                             Working With Normal Plists.
+* plist-remprop:                         Working With Normal Plists.
+* plist-to-alist:                        Converting Plists To/From Alists.
+* plists-eq <1>:                         Other Plists.
+* plists-eq:                             Working With Normal Plists.
+* plists-equal <1>:                      Other Plists.
+* plists-equal:                          Working With Normal Plists.
+* point:                                 Point.
+* point excursion:                       Excursions.
+* point in window:                       Window Point.
+* point with narrowing:                  Point.
+* point-marker:                          Creating Markers.
+* point-max:                             Point.
+* point-max-marker:                      Creating Markers.
+* point-min:                             Point.
+* point-min-marker:                      Creating Markers.
+* pointer (mouse):                       Mouse Pointer.
+* pointer-glyph-p:                       Glyph Types.
+* pointer-image-instance-p:              Image Instance Types.
+* pop-global-mark:                       The Mark.
+* pop-mark:                              The Mark.
+* pop-to-buffer:                         Displaying Buffers.
+* pop-up menu:                           Pop-Up Menus.
+* pop-up-frame-function:                 Choosing Window.
+* pop-up-frame-plist:                    Choosing Window.
+* pop-up-frames:                         Choosing Window.
+* pop-up-windows:                        Choosing Window.
+* popup-buffer-menu:                     Pop-Up Menus.
+* popup-dialog-box:                      Dialog Box Functions.
+* popup-menu:                            Pop-Up Menus.
+* popup-menu-titles:                     Pop-Up Menus.
+* popup-menu-up-p:                       Pop-Up Menus.
+* popup-menubar-menu:                    Pop-Up Menus.
+* popup-mode-menu:                       Pop-Up Menus.
+* pos-visible-in-window-p:               Window Start.
+* position (in buffer):                  Positions.
+* position argument:                     Interactive Codes.
+* position in window:                    Window Point.
+* position of frame:                     Size and Position.
+* position of window:                    Position of Window.
+* positive infinity:                     Float Basics.
+* posix-looking-at:                      POSIX Regexps.
+* posix-search-backward:                 POSIX Regexps.
+* posix-search-forward:                  POSIX Regexps.
+* posix-string-match:                    POSIX Regexps.
+* post-command-hook:                     Command Overview.
+* post-gc-hook:                          Garbage Collection.
+* PostgreSQL:                            PostgreSQL Support.
+* pq-binary-tuples:                      libpq Lisp Symbols and DataTypes.
+* pq-clear:                              Other libpq Functions.
+* pq-client-encoding:                    Other libpq Functions.
+* pq-cmd-status:                         libpq Lisp Symbols and DataTypes.
+* pq-cmd-tuples:                         libpq Lisp Symbols and DataTypes.
+* pq-conn-defaults:                      Other libpq Functions.
+* pq-connect-poll:                       Asynchronous Interface Functions.
+* pq-connect-start:                      Asynchronous Interface Functions.
+* pq-connectdb:                          Synchronous Interface Functions.
+* pq-consume-input:                      Asynchronous Interface Functions.
+* pq-env-2-encoding:                     Other libpq Functions.
+* pq-exec:                               Synchronous Interface Functions.
+* pq-finish:                             Other libpq Functions.
+* pq-flush:                              Asynchronous Interface Functions.
+* pq-fmod:                               libpq Lisp Symbols and DataTypes.
+* pq-fname:                              libpq Lisp Symbols and DataTypes.
+* pq-fnumber:                            libpq Lisp Symbols and DataTypes.
+* pq-fsize:                              libpq Lisp Symbols and DataTypes.
+* pq-ftype:                              libpq Lisp Symbols and DataTypes.
+* pq-get-is-null:                        libpq Lisp Symbols and DataTypes.
+* pq-get-length:                         libpq Lisp Symbols and DataTypes.
+* pq-get-result:                         Asynchronous Interface Functions.
+* pq-get-value:                          libpq Lisp Symbols and DataTypes.
+* pq-is-busy:                            Asynchronous Interface Functions.
+* pq-is-nonblocking:                     Asynchronous Interface Functions.
+* pq-lo-close:                           Unimplemented libpq Functions.
+* pq-lo-creat:                           Unimplemented libpq Functions.
+* pq-lo-export:                          Large Object Support.
+* pq-lo-import:                          Large Object Support.
+* pq-lo-lseek:                           Unimplemented libpq Functions.
+* pq-lo-open:                            Unimplemented libpq Functions.
+* pq-lo-read:                            Unimplemented libpq Functions.
+* pq-lo-tell:                            Unimplemented libpq Functions.
+* pq-lo-unlink:                          Unimplemented libpq Functions.
+* pq-lo-write:                           Unimplemented libpq Functions.
+* pq-make-empty-pgresult:                libpq Lisp Symbols and DataTypes.
+* pq-nfields:                            libpq Lisp Symbols and DataTypes.
+* pq-notifies:                           Synchronous Interface Functions.
+* pq-ntuples:                            libpq Lisp Symbols and DataTypes.
+* pq-oid-value:                          libpq Lisp Symbols and DataTypes.
+* pq-pgconn:                             libpq Lisp Symbols and DataTypes.
+* pq-res-status:                         libpq Lisp Symbols and DataTypes.
+* pq-reset:                              Synchronous Interface Functions.
+* pq-reset-cancel:                       Asynchronous Interface Functions.
+* pq-reset-poll:                         Asynchronous Interface Functions.
+* pq-reset-start:                        Asynchronous Interface Functions.
+* pq-result-error-message:               libpq Lisp Symbols and DataTypes.
+* pq-result-status:                      libpq Lisp Symbols and DataTypes.
+* pq-send-query:                         Asynchronous Interface Functions.
+* pq-set-client-encoding:                Other libpq Functions.
+* pq-set-nonblocking:                    Asynchronous Interface Functions.
+* PQdisplayTuples:                       Unimplemented libpq Functions.
+* PQmblen:                               Unimplemented libpq Functions.
+* PQprint:                               Unimplemented libpq Functions.
+* PQprintTuples:                         Unimplemented libpq Functions.
+* PQsetenv:                              Synchronous Interface Functions.
+* PQsetenvAbort:                         Asynchronous Interface Functions.
+* PQsetenvPoll:                          Asynchronous Interface Functions.
+* PQsetenvStart:                         Asynchronous Interface Functions.
+* PQsocket:                              Unimplemented libpq Functions.
+* PQtrace:                               Unimplemented libpq Functions.
+* PQuntrace:                             Unimplemented libpq Functions.
+* pre-abbrev-expand-hook:                Abbrev Expansion.
+* pre-command-hook:                      Command Overview.
+* pre-gc-hook:                           Garbage Collection.
+* preceding-char:                        Near Point.
+* precision of formatted numbers:        Formatting Strings.
+* predicates:                            Type Predicates.
+* prefix argument:                       Prefix Command Arguments.
+* prefix argument unreading:             Peeking and Discarding.
+* prefix command:                        Prefix Keys.
+* prefix key:                            Prefix Keys.
+* prefix-arg:                            Prefix Command Arguments.
+* prefix-help-command:                   Help Functions.
+* prefix-numeric-value:                  Prefix Command Arguments.
+* preventing backtracking:               Specification List.
+* preventing prefix key:                 Key Lookup.
+* previous complete subexpression:       Parsing Expressions.
+* previous-extent:                       Finding Extents.
+* previous-frame:                        Finding All Frames.
+* previous-history-element:              Minibuffer Misc.
+* previous-matching-history-element:     Minibuffer Misc.
+* previous-property-change:              Property Search.
+* previous-single-property-change:       Property Search.
+* previous-window:                       Cyclic Window Ordering.
+* primitive:                             What Is a Function.
+* primitive type:                        Lisp Data Types.
+* primitive types:                       Primitive Types.
+* primitive-undo:                        Undo.
+* prin1:                                 Output Functions.
+* prin1-to-string:                       Output Functions.
+* princ:                                 Output Functions.
+* print:                                 Output Functions.
+* print example:                         Output Streams.
+* print name cell:                       Symbol Components.
+* print-escape-newlines:                 Output Variables.
+* print-gensym:                          Output Variables.
+* print-help-return-message:             Help Functions.
+* print-length:                          Output Variables.
+* print-level:                           Output Variables.
+* print-readably <1>:                    Output Variables.
+* print-readably:                        Printing in Edebug.
+* print-string-length:                   Output Variables.
+* printed representation:                Printed Representation.
+* printed representation for characters: Character Type.
+* printing:                              Streams Intro.
+* printing (Edebug):                     Printing in Edebug.
+* printing circular structures:          Printing in Edebug.
+* printing floating-point numbers:       Output Variables.
+* printing limits:                       Output Variables.
+* printing notation:                     Printing Notation.
+* printing readably:                     Output Variables.
+* printing uninterned symbols:           Output Variables.
+* priority of an extent:                 Intro to Extents.
+* process:                               Processes.
+* process filter:                        Filter Functions.
+* process input:                         Input to Processes.
+* process output:                        Output from Processes.
+* process sentinel:                      Sentinels.
+* process signals:                       Signals to Processes.
+* process window size:                   Process Window Size.
+* process-buffer:                        Process Buffers.
+* process-command:                       Process Information.
+* process-connection-type:               Asynchronous Processes.
+* process-environment:                   System Environment.
+* process-event-p:                       Event Predicates.
+* process-exit-status:                   Process Information.
+* process-filter:                        Filter Functions.
+* process-id:                            Process Information.
+* process-kill-without-query:            Deleting Processes.
+* process-kill-without-query-p:          Process Information.
+* process-list:                          Process Information.
+* process-mark:                          Process Buffers.
+* process-name:                          Process Information.
+* process-send-eof:                      Input to Processes.
+* process-send-region:                   Input to Processes.
+* process-send-signal:                   Signals to Processes.
+* process-send-string:                   Input to Processes.
+* process-sentinel:                      Sentinels.
+* process-status:                        Process Information.
+* process-tty-name:                      Process Information.
+* processp:                              Processes.
+* profile.el:                            Compilation Tips.
+* profiling:                             Compilation Tips.
+* prog1:                                 Sequencing.
+* prog2:                                 Sequencing.
+* progn:                                 Sequencing.
+* program arguments:                     Subprocess Creation.
+* program directories:                   Subprocess Creation.
+* programmed completion:                 Programmed Completion.
+* programming types:                     Programming Types.
+* properties of strings:                 String Properties.
+* properties of text:                    Text Properties.
+* property list:                         Property Lists.
+* property list cell (symbol):           Symbol Components.
+* property list, symbol:                 Symbol Properties.
+* property lists vs association lists:   Plists and Alists.
+* property of an extent:                 Extent Properties.
+* protected forms:                       Cleanups.
+* provide:                               Named Features.
+* providing features:                    Named Features.
+* PTYs:                                  Asynchronous Processes.
+* punctuation character:                 Syntax Class Table.
+* pure storage:                          Pure Storage.
+* pure-bytes-used:                       Pure Storage.
+* purecopy:                              Pure Storage.
+* purify-flag:                           Pure Storage.
+* push-mark:                             The Mark.
+* put:                                   Object Plists.
+* put-char-table:                        Working With Char Tables.
+* put-database:                          Working With a Database.
+* put-range-table:                       Working With Range Tables.
+* put-text-property:                     Changing Properties.
+* putf:                                  Other Plists.
+* puthash:                               Working With Hash Tables.
+* query-replace-history:                 Minibuffer History.
+* query-replace-map <1>:                 Standard Keymaps.
+* query-replace-map:                     Search and Replace.
+* querying the user:                     Yes-or-No Queries.
+* question mark in character constant:   Character Type.
+* quietly-read-abbrev-file:              Abbrev Files.
+* quit-flag:                             Quitting.
+* quit-process:                          Signals to Processes.
+* quitting:                              Quitting.
+* quitting from infinite loop:           Infinite Loops.
+* quote:                                 Quoting.
+* quote character:                       Parsing Expressions.
+* quoted character input:                Quoted Character Input.
+* quoted-insert suppression:             Changing Key Bindings.
+* quoting:                               Quoting.
+* quoting characters in printing:        Output Functions.
+* quoting using apostrophe:              Quoting.
+* raise-frame:                           Raising and Lowering.
+* raising a frame:                       Raising and Lowering.
+* random:                                Random Numbers.
+* random numbers:                        Random Numbers.
+* range table type:                      Range Table Type.
+* Range Tables:                          Range Tables.
+* range-table-p:                         Range Tables.
+* rassoc:                                Association Lists.
+* rassq:                                 Association Lists.
+* raw prefix argument:                   Prefix Command Arguments.
+* raw prefix argument usage:             Interactive Codes.
+* re-search-backward:                    Regexp Search.
+* re-search-forward:                     Regexp Search.
+* read:                                  Input Functions.
+* read command name:                     Interactive Call.
+* read syntax:                           Printed Representation.
+* read syntax for characters:            Character Type.
+* read-buffer:                           High-Level Completion.
+* read-char:                             Reading One Event.
+* read-command:                          High-Level Completion.
+* read-expression:                       Object from Minibuffer.
+* read-expression-history:               Minibuffer History.
+* read-expression-map:                   Standard Keymaps.
+* read-file-name:                        Reading File Names.
+* read-from-minibuffer:                  Text from Minibuffer.
+* read-from-string:                      Input Functions.
+* read-key-sequence:                     Key Sequence Input.
+* read-minibuffer:                       Object from Minibuffer.
+* read-only buffer:                      Read Only Buffers.
+* read-only buffers in interactive:      Using Interactive.
+* read-passwd:                           Reading a Password.
+* read-quoted-char:                      Quoted Character Input.
+* read-quoted-char quitting:             Quitting.
+* read-shell-command-map:                Standard Keymaps.
+* read-string:                           Text from Minibuffer.
+* read-variable:                         High-Level Completion.
+* reading:                               Streams Intro.
+* reading (Edebug):                      Reading in Edebug.
+* reading interactive arguments:         Interactive Codes.
+* reading symbols:                       Creating Symbols.
+* rearrangement of lists:                Rearrangement.
+* rebinding:                             Changing Key Bindings.
+* receiving ToolTalk messages:           Receiving Messages.
+* recent-auto-save-p:                    Auto-Saving.
+* recent-keys:                           Recording Input.
+* recent-keys-ring-size:                 Recording Input.
+* recenter:                              Vertical Scrolling.
+* record command history:                Interactive Call.
+* recursion:                             Iteration.
+* recursion-depth:                       Recursive Editing.
+* recursive command loop:                Recursive Editing.
+* recursive editing level:               Recursive Editing.
+* recursive evaluation:                  Intro Eval.
+* recursive-edit:                        Recursive Editing.
+* redo:                                  Undo.
+* redraw-display:                        Refresh Screen.
+* redraw-frame:                          Refresh Screen.
+* redraw-modeline:                       Modeline Format.
+* refresh display:                       Refresh Screen.
+* regexp:                                Regular Expressions.
+* regexp alternative:                    Syntax of Regexps.
+* regexp grouping:                       Syntax of Regexps.
+* regexp searching:                      Regexp Search.
+* regexp-history:                        Minibuffer History.
+* regexp-quote:                          Syntax of Regexps.
+* regexps used standardly in editing:    Standard Regexps.
+* region argument:                       Interactive Codes.
+* region, the:                           The Region.
+* region-active-p:                       The Region.
+* region-beginning:                      The Region.
+* region-end:                            The Region.
+* region-exists-p:                       The Region.
+* register-alist:                        Registers.
+* register-ccl-program:                  Calling CCL.
+* register-tooltalk-pattern:             Elisp Interface for Receiving Messages.
+* registers:                             Registers.
+* regular expression:                    Regular Expressions.
+* regular expression searching:          Regexp Search.
+* regular package:                       Package Terminology.
+* reindent-then-newline-and-indent:      Mode-Specific Indent.
+* relabel-menu-item:                     Modifying Menus.
+* relative file name:                    Relative File Names.
+* remainder:                             Arithmetic Operations.
+* remassoc:                              Association Lists.
+* remassq:                               Association Lists.
+* remhash:                               Working With Hash Tables.
+* remove-database:                       Working With a Database.
+* remove-face-property:                  Face Properties.
+* remove-glyph-property:                 Glyph Properties.
+* remove-hook:                           Hooks.
+* remove-range-table:                    Working With Range Tables.
+* remove-specifier:                      Other Specification Functions.
+* remove-text-properties:                Changing Properties.
+* remprop:                               Object Plists.
+* remrassoc:                             Association Lists.
+* remrassq:                              Association Lists.
+* rename-auto-save-file:                 Auto-Saving.
+* rename-buffer:                         Buffer Names.
+* rename-file:                           Changing File Attributes.
+* renaming files:                        Changing File Attributes.
+* repeated loading:                      Repeated Loading.
+* replace bindings:                      Changing Key Bindings.
+* replace characters:                    Substitution.
+* replace-buffer-in-windows:             Displaying Buffers.
+* replace-match:                         Replacing Match.
+* replacement:                           Search and Replace.
+* repositioning format arguments:        Formatting Strings.
+* require:                               Named Features.
+* require-final-newline:                 Saving Buffers.
+* requiring features:                    Named Features.
+* reset-char-table:                      Working With Char Tables.
+* resize redisplay:                      Size and Position.
+* rest arguments:                        Argument List.
+* restriction (in a buffer):             Narrowing.
+* resume (cf. no-redraw-on-reenter):     Refresh Screen.
+* return:                                Character Type.
+* return-tooltalk-message:               Elisp Interface for Sending Messages.
+* reveal-annotation:                     Annotation Properties.
+* reverse:                               Building Lists.
+* reversing a list:                      Rearrangement.
+* revert-buffer:                         Reverting.
+* revert-buffer-function:                Reverting.
+* revert-buffer-insert-file-contents-function: Reverting.
+* right-gutter:                          Specifying a Gutter.
+* right-gutter-visible-p:                Other Gutter Variables.
+* right-gutter-width:                    Other Gutter Variables.
+* right-margin-width:                    Margin Primitives.
+* right-toolbar:                         Specifying the Toolbar.
+* right-toolbar-visible-p:               Other Toolbar Variables.
+* right-toolbar-width:                   Other Toolbar Variables.
+* rm:                                    Changing File Attributes.
+* round:                                 Numeric Conversions.
+* rounding in conversions:               Numeric Conversions.
+* rounding without conversion:           Rounding Operations.
+* rplaca:                                Modifying Lists.
+* rplacd:                                Modifying Lists.
+* run time stack:                        Internals of Debugger.
+* run-emacs-from-temacs:                 Building XEmacs.
+* run-hooks:                             Hooks.
+* runnable temacs:                       Building XEmacs.
+* same-window-buffer-names:              Choosing Window.
+* same-window-regexps:                   Choosing Window.
+* save-abbrevs:                          Abbrev Files.
+* save-buffer:                           Saving Buffers.
+* save-current-buffer:                   Excursions.
+* save-excursion:                        Excursions.
+* save-excursion (Edebug):               Edebug Display Update.
+* save-match-data:                       Saving Match Data.
+* save-restriction:                      Narrowing.
+* save-selected-frame:                   Input Focus.
+* save-selected-window <1>:              Excursions.
+* save-selected-window:                  Selecting Windows.
+* save-some-buffers:                     Saving Buffers.
+* save-window-excursion:                 Window Configurations.
+* saving text properties:                Saving Properties.
+* saving window information:             Window Configurations.
+* scan-lists:                            Parsing Expressions.
+* scan-sexps:                            Parsing Expressions.
+* scope:                                 Variable Scoping.
+* screen layout:                         Window Configuration Type.
+* scroll-conservatively:                 Vertical Scrolling.
+* scroll-down:                           Vertical Scrolling.
+* scroll-left:                           Horizontal Scrolling.
+* scroll-other-window:                   Vertical Scrolling.
+* scroll-right:                          Horizontal Scrolling.
+* scroll-step:                           Vertical Scrolling.
+* scroll-up:                             Vertical Scrolling.
+* scrollbar-pointer-glyph:               Mouse Pointer.
+* scrollbars:                            Scrollbars.
+* scrolling vertically:                  Vertical Scrolling.
+* search-backward:                       String Search.
+* search-failed:                         String Search.
+* search-forward:                        String Search.
+* searching:                             Searching and Matching.
+* searching and case:                    Searching and Case.
+* searching for regexp:                  Regexp Search.
+* second:                                List Elements.
+* select-console:                        The Selected Console and Device.
+* select-device:                         The Selected Console and Device.
+* select-frame:                          Input Focus.
+* select-frame-hook:                     Frame Hooks.
+* select-window:                         Selecting Windows.
+* selected frame:                        Input Focus.
+* selected window:                       Basic Windows.
+* selected-console:                      The Selected Console and Device.
+* selected-device:                       The Selected Console and Device.
+* selected-frame:                        Input Focus.
+* selected-window:                       Selecting Windows.
+* selecting a buffer:                    Current Buffer.
+* selecting windows:                     Selecting Windows.
+* selection (for X windows):             X Selections.
+* selection-pointer-glyph:               Mouse Pointer.
+* selective display:                     Selective Display.
+* selective-display:                     Selective Display.
+* selective-display-ellipses:            Selective Display.
+* self-evaluating form:                  Self-Evaluating Forms.
+* self-insert-and-exit:                  Minibuffer Misc.
+* self-insert-command:                   Commands for Insertion.
+* self-insert-command override:          Changing Key Bindings.
+* self-insert-command, minor modes:      Keymaps and Minor Modes.
+* self-insertion:                        Commands for Insertion.
+* send-string-to-terminal:               Terminal Output.
+* send-tooltalk-message:                 Elisp Interface for Sending Messages.
+* sending signals:                       Signals to Processes.
+* sending ToolTalk messages:             Sending Messages.
+* sentence-end:                          Standard Regexps.
+* sentinel:                              Sentinels.
+* sequence:                              Sequences Arrays Vectors.
+* sequence length:                       Sequence Functions.
+* sequencep:                             Sequence Functions.
+* set:                                   Setting Variables.
+* set-annotation-action:                 Annotation Properties.
+* set-annotation-data:                   Annotation Properties.
+* set-annotation-down-glyph:             Annotation Properties.
+* set-annotation-face:                   Annotation Properties.
+* set-annotation-glyph:                  Annotation Properties.
+* set-annotation-layout:                 Annotation Properties.
+* set-annotation-menu:                   Annotation Properties.
+* set-auto-mode:                         Auto Major Mode.
+* set-buffer:                            Current Buffer.
+* set-buffer-auto-saved:                 Auto-Saving.
+* set-buffer-major-mode:                 Auto Major Mode.
+* set-buffer-menubar:                    Menubar.
+* set-buffer-modified-p:                 Buffer Modification.
+* set-case-syntax:                       Case Tables.
+* set-case-syntax-delims:                Case Tables.
+* set-case-syntax-pair:                  Case Tables.
+* set-case-table:                        Case Tables.
+* set-category-table:                    Category Tables.
+* set-charset-ccl-program:               Charset Property Functions.
+* set-charset-registry:                  Charset Property Functions.
+* set-coding-category-system:            Detection of Textual Encoding.
+* set-coding-priority-list:              Detection of Textual Encoding.
+* set-console-type-image-conversion-list: Image Instantiator Conversion.
+* set-default:                           Default Value.
+* set-default-file-modes:                Changing File Attributes.
+* set-default-gutter-position:           Specifying a Gutter.
+* set-default-toolbar-position:          Specifying the Toolbar.
+* set-device-baud-rate <1>:              Terminal Output.
+* set-device-baud-rate:                  Console and Device I/O.
+* set-extent-begin-glyph:                Extent Properties.
+* set-extent-begin-glyph-layout:         Extent Properties.
+* set-extent-end-glyph:                  Extent Properties.
+* set-extent-end-glyph-layout:           Extent Properties.
+* set-extent-endpoints:                  Extent Endpoints.
+* set-extent-face:                       Extent Properties.
+* set-extent-initial-redisplay-function: Extent Properties.
+* set-extent-keymap:                     Extent Properties.
+* set-extent-mouse-face:                 Extent Properties.
+* set-extent-parent:                     Extent Parents.
+* set-extent-priority:                   Extent Properties.
+* set-extent-properties:                 Extent Properties.
+* set-extent-property:                   Extent Properties.
+* set-face-background:                   Face Convenience Functions.
+* set-face-background-pixmap:            Face Convenience Functions.
+* set-face-font:                         Face Convenience Functions.
+* set-face-foreground:                   Face Convenience Functions.
+* set-face-property:                     Face Properties.
+* set-face-underline-p:                  Face Convenience Functions.
+* set-file-modes:                        Changing File Attributes.
+* set-frame-configuration:               Frame Configurations.
+* set-frame-pointer:                     Mouse Pointer.
+* set-frame-position:                    Size and Position.
+* set-frame-properties:                  Property Access.
+* set-frame-property:                    Property Access.
+* set-frame-size:                        Size and Position.
+* set-glyph-baseline:                    Glyph Convenience Functions.
+* set-glyph-contrib-p:                   Glyph Convenience Functions.
+* set-glyph-face:                        Glyph Convenience Functions.
+* set-glyph-image:                       Glyph Convenience Functions.
+* set-glyph-property:                    Glyph Properties.
+* set-input-mode:                        Input Modes.
+* set-keymap-default-binding:            Inheritance and Keymaps.
+* set-keymap-name:                       Creating Keymaps.
+* set-keymap-parents:                    Inheritance and Keymaps.
+* set-keymap-prompt:                     Other Keymap Functions.
+* set-left-margin:                       Margins.
+* set-mark:                              The Mark.
+* set-marker:                            Changing Markers.
+* set-match-data:                        Entire Match Data.
+* set-menubar:                           Menubar.
+* set-menubar-dirty-flag:                Menubar.
+* set-process-buffer:                    Process Buffers.
+* set-process-filter:                    Filter Functions.
+* set-process-sentinel:                  Sentinels.
+* set-process-window-size:               Process Window Size.
+* set-recent-keys-ring-size:             Recording Input.
+* set-register:                          Registers.
+* set-right-margin:                      Margins.
+* set-specifier:                         Adding Specifications.
+* set-standard-case-table:               Case Tables.
+* set-syntax-table:                      Syntax Table Functions.
+* set-text-properties:                   Changing Properties.
+* set-tooltalk-message-attribute:        Elisp Interface for Sending Messages.
+* set-visited-file-modtime:              Modification Time.
+* set-visited-file-name:                 Buffer File Name.
+* set-weak-list-list:                    Weak Lists.
+* set-window-buffer:                     Buffers and Windows.
+* set-window-buffer-dedicated:           Choosing Window.
+* set-window-configuration:              Window Configurations.
+* set-window-dedicated-p:                Choosing Window.
+* set-window-hscroll:                    Horizontal Scrolling.
+* set-window-point:                      Window Point.
+* set-window-start:                      Window Start.
+* setcar:                                Setcar.
+* setcdr:                                Setcdr.
+* setenv:                                System Environment.
+* setplist:                              Object Plists.
+* setq:                                  Setting Variables.
+* setq-default:                          Default Value.
+* sets:                                  Sets And Lists.
+* setting modes of files:                Changing File Attributes.
+* setting-constant:                      Constant Variables.
+* seventh:                               List Elements.
+* sexp motion:                           List Motion.
+* shadowing of variables:                Local Variables.
+* shallow binding:                       Impl of Scope.
+* shared-lisp-mode-map:                  Standard Keymaps.
+* Shell mode modeline-format:            Modeline Data.
+* shell-command-history:                 Minibuffer History.
+* shrink-window:                         Resizing Windows.
+* shrink-window-horizontally:            Resizing Windows.
+* shrink-window-pixels:                  Resizing Windows.
+* side effect:                           Intro Eval.
+* signal:                                Signaling Errors.
+* signal-error:                          Signaling Errors.
+* signal-process:                        Signals to Processes.
+* signaling errors:                      Signaling Errors.
+* signals:                               Signals to Processes.
+* sin:                                   Math Functions.
+* single-file package:                   Package Terminology.
+* single-key-description:                Describing Characters.
+* sinh:                                  Math Functions.
+* sit-for:                               Waiting.
+* site-init.el:                          Building XEmacs.
+* site-load.el:                          Building XEmacs.
+* site-run-file:                         Init File.
+* site-start.el:                         Start-up Summary.
+* sixth:                                 List Elements.
+* size of frame:                         Size and Position.
+* size of window:                        Size of Window.
+* skip-chars-backward:                   Skipping Characters.
+* skip-chars-forward:                    Skipping Characters.
+* skip-syntax-backward:                  Motion and Syntax.
+* skip-syntax-forward:                   Motion and Syntax.
+* skipping characters:                   Skipping Characters.
+* skipping comments:                     Parsing Expressions.
+* sleep-for:                             Waiting.
+* Snarf-documentation:                   Accessing Documentation.
+* sort:                                  Rearrangement.
+* sort-columns:                          Sorting.
+* sort-fields:                           Sorting.
+* sort-lines:                            Sorting.
+* sort-numeric-fields:                   Sorting.
+* sort-pages:                            Sorting.
+* sort-paragraphs:                       Sorting.
+* sort-regexp-fields:                    Sorting.
+* sort-subr:                             Sorting.
+* sorting lists:                         Rearrangement.
+* sorting text:                          Sorting.
+* sound:                                 Beeping.
+* sound-alist:                           Beeping.
+* source packages:                       Package Terminology.
+* special:                               Major Mode Conventions.
+* special form descriptions:             A Sample Function Description.
+* special form evaluation:               Special Forms.
+* special forms:                         Primitive Function Type.
+* special forms (Edebug):                Instrumenting.
+* special forms for control structures:  Control Structures.
+* special-display-buffer-names:          Choosing Window.
+* special-display-frame-plist:           Choosing Window.
+* special-display-function:              Choosing Window.
+* special-display-popup-frame:           Choosing Window.
+* special-display-regexps:               Choosing Window.
+* specification (in a specifier):        Specifiers In-Depth.
+* specifier:                             Specifiers.
+* specifier examples:                    Simple Specifier Usage.
+* specifier type:                        Specifier Type.
+* specifier, domain:                     Specifiers In-Depth.
+* specifier, fallback:                   Specifier Instancing.
+* specifier, inst-list:                  Specifiers In-Depth.
+* specifier, inst-pair:                  Specifiers In-Depth.
+* specifier, instance:                   Specifiers In-Depth.
+* specifier, instancing:                 Specifiers In-Depth.
+* specifier, instantiator:               Specifiers In-Depth.
+* specifier, locale:                     Specifiers In-Depth.
+* specifier, specification:              Specifiers In-Depth.
+* specifier, tag:                        Specifiers In-Depth.
+* specifier, tag set:                    Specifiers In-Depth.
+* specifier-fallback:                    Retrieving Specifications.
+* specifier-instance:                    Specifier Instancing Functions.
+* specifier-instance-from-inst-list:     Specifier Instancing Functions.
+* specifier-locale-type-from-locale:     Other Specification Functions.
+* specifier-matching-instance:           Specifier Instancing Functions.
+* specifier-spec-list:                   Retrieving Specifications.
+* specifier-specs:                       Retrieving Specifications.
+* specifier-tag-list:                    Specifier Tag Functions.
+* specifier-tag-predicate:               Specifier Tag Functions.
+* specifier-type:                        Specifier Types.
+* specifierp:                            Specifiers.
+* speedups:                              Compilation Tips.
+* splicing (with backquote):             Backquote.
+* split-height-threshold:                Choosing Window.
+* split-line:                            Commands for Insertion.
+* split-path:                            Regexp Search.
+* split-string:                          Regexp Search.
+* split-window:                          Splitting Windows.
+* split-window-horizontally:             Splitting Windows.
+* split-window-vertically:               Splitting Windows.
+* splitting windows:                     Splitting Windows.
+* sqrt:                                  Math Functions.
+* stable sort:                           Rearrangement.
+* standard regexps used in editing:      Standard Regexps.
+* standard-case-table:                   Case Tables.
+* standard-category-table:               Category Tables.
+* standard-input:                        Input Functions.
+* standard-output:                       Output Variables.
+* standard-syntax-table:                 Standard Syntax Tables.
+* standards of coding style:             Tips.
+* start up of XEmacs:                    Start-up Summary.
+* start-process:                         Asynchronous Processes.
+* start-process-shell-command:           Asynchronous Processes.
+* startup.el:                            Start-up Summary.
+* stop points:                           Using Edebug.
+* stop-process:                          Signals to Processes.
+* stopping an infinite loop:             Infinite Loops.
+* stopping on events:                    Global Break Condition.
+* store-match-data:                      Entire Match Data.
+* stream (for printing):                 Output Streams.
+* stream (for reading):                  Input Streams.
+* string:                                Creating Strings.
+* string equality:                       Text Comparison.
+* string in keymap:                      Key Lookup.
+* string input stream:                   Input Streams.
+* string length:                         Sequence Functions.
+* string length, maximum when printing:  Output Variables.
+* string properties:                     String Properties.
+* string search:                         String Search.
+* string to character:                   String Conversion.
+* string to number:                      String Conversion.
+* string to object:                      Input Functions.
+* string, writing a doc string:          Documentation Basics.
+* string-equal:                          Text Comparison.
+* string-lessp:                          Text Comparison.
+* string-match:                          Regexp Search.
+* string-modified-tick:                  Modifying Strings.
+* string-to-char:                        String Conversion.
+* string-to-int:                         String Conversion.
+* string-to-number:                      String Conversion.
+* string<:                               Text Comparison.
+* string=:                               Text Comparison.
+* stringp:                               Predicates for Strings.
+* strings:                               Strings and Characters.
+* strings, formatting them:              Formatting Strings.
+* strings, modifying:                    Modifying Strings.
+* string quote:                          Syntax Class Table.
+* subprocess:                            Processes.
+* subr:                                  What Is a Function.
+* subrp:                                 What Is a Function.
+* subsidiary-coding-system:              Basic Coding System Functions.
+* subst-char-in-region:                  Substitution.
+* substitute-command-keys:               Keys in Documentation.
+* substitute-in-file-name:               File Name Expansion.
+* substitute-key-definition:             Changing Key Bindings.
+* substituting keys in documentation:    Keys in Documentation.
+* substring:                             Creating Strings.
+* subwindow type:                        Subwindow Type.
+* subwindow-image-instance-p:            Image Instance Types.
+* subwindowp:                            Subwindows.
+* suppress-keymap:                       Changing Key Bindings.
+* suspend (cf. no-redraw-on-reenter):    Refresh Screen.
+* suspend evaluation:                    Recursive Editing.
+* suspend-emacs:                         Suspending XEmacs.
+* suspend-hook:                          Suspending XEmacs.
+* suspend-resume-hook:                   Suspending XEmacs.
+* suspending XEmacs:                     Suspending XEmacs.
+* switch-to-buffer:                      Displaying Buffers.
+* switch-to-buffer-other-window:         Displaying Buffers.
+* switches on command line:              Command Line Arguments.
+* switching to a buffer:                 Displaying Buffers.
+* symbol:                                Symbols.
+* symbol components:                     Symbol Components.
+* symbol equality:                       Creating Symbols.
+* symbol evaluation:                     Symbol Forms.
+* symbol function indirection:           Function Indirection.
+* symbol in keymap:                      Key Lookup.
+* symbol name hashing:                   Creating Symbols.
+* symbol-function:                       Function Cells.
+* symbol-name:                           Creating Symbols.
+* symbol-plist:                          Object Plists.
+* symbol-value:                          Accessing Variables.
+* symbolp:                               Symbols.
+* symbol constituent:                    Syntax Class Table.
+* synchronous subprocess:                Synchronous Processes.
+* syntax classes:                        Syntax Descriptors.
+* syntax descriptor:                     Syntax Descriptors.
+* syntax error (Edebug):                 Backtracking.
+* syntax flags:                          Syntax Flags.
+* syntax for characters:                 Character Type.
+* syntax table:                          Syntax Tables.
+* syntax table example:                  Example Major Modes.
+* syntax table internals:                Syntax Table Internals.
+* syntax tables in modes:                Major Mode Conventions.
+* syntax-table:                          Syntax Table Functions.
+* syntax-table-p:                        Syntax Basics.
+* system-configuration:                  System Environment.
+* system-name:                           System Environment.
+* system-type:                           System Environment.
+* t:                                     Constant Variables.
+* t and truth:                           nil and t.
+* t input stream:                        Input Streams.
+* t output stream:                       Output Streams.
+* tab:                                   Character Type.
+* tab deletion:                          Deletion.
+* tab-stop-list:                         Indent Tabs.
+* tab-to-tab-stop:                       Indent Tabs.
+* tab-width:                             Usual Display.
+* tabs stops for indentation:            Indent Tabs.
+* tag (in a specifier):                  Specifiers In-Depth.
+* tag on run time stack:                 Catch and Throw.
+* tag set (in a specifier):              Specifiers In-Depth.
+* tan:                                   Math Functions.
+* tanh:                                  Math Functions.
+* TCP:                                   Network.
+* temacs:                                Building XEmacs.
+* temp-buffer-show-function:             Temporary Displays.
+* temp-directory:                        Unique File Names.
+* tenth:                                 List Elements.
+* TERM environment variable:             Terminal-Specific.
+* term-file-prefix:                      Terminal-Specific.
+* term-setup-hook:                       Terminal-Specific.
+* Termcap:                               Terminal-Specific.
+* terminal frame <1>:                    Frames.
+* terminal frame:                        Basic Windows.
+* terminal input:                        Terminal Input.
+* terminal input modes:                  Input Modes.
+* terminal output:                       Terminal Output.
+* terminal-device:                       Console Types and Device Classes.
+* terminal-specific initialization:      Terminal-Specific.
+* terminate keyboard macro:              Peeking and Discarding.
+* termscript file:                       Terminal Output.
+* terpri:                                Output Functions.
+* testing types:                         Type Predicates.
+* text:                                  Text.
+* text files and binary files:           Files and MS-DOS.
+* text insertion:                        Insertion.
+* text parsing:                          Syntax Tables.
+* text properties:                       Text Properties.
+* text properties in files:              Saving Properties.
+* text-char-description:                 Describing Characters.
+* text-image-instance-p:                 Image Instance Types.
+* text-mode-abbrev-table:                Standard Abbrev Tables.
+* text-mode-map:                         Standard Keymaps.
+* text-mode-syntax-table:                Standard Syntax Tables.
+* text-pointer-glyph:                    Mouse Pointer.
+* text-properties-at:                    Examining Properties.
+* text-property-any:                     Property Search.
+* text-property-not-all:                 Property Search.
+* third:                                 List Elements.
+* this-command:                          Command Loop Info.
+* this-command-keys:                     Command Loop Info.
+* throw:                                 Catch and Throw.
+* throw example:                         Recursive Editing.
+* tiled windows:                         Basic Windows.
+* timeout-event-p:                       Event Predicates.
+* timing programs:                       Compilation Tips.
+* tips:                                  Tips.
+* toggle-read-only:                      Read Only Buffers.
+* toolbar:                               Toolbar.
+* toolbar button type:                   Toolbar Button Type.
+* toolbar button, adding:                Simple Specifier Usage.
+* toolbar-buttons-captioned-p:           Other Toolbar Variables.
+* toolbar-make-button-list:              Toolbar Descriptor Format.
+* toolbar-map <1>:                       Standard Keymaps.
+* toolbar-map:                           Active Keymaps.
+* toolbar-pointer-glyph:                 Mouse Pointer.
+* toolbar-specifier-p <1>:               Specifier Types.
+* toolbar-specifier-p:                   Specifying the Toolbar.
+* ToolTalk:                              ToolTalk Support.
+* ToolTalk message:                      Sending Messages.
+* ToolTalk pattern:                      Receiving Messages.
+* top-gutter:                            Specifying a Gutter.
+* top-gutter-height:                     Other Gutter Variables.
+* top-gutter-visible-p:                  Other Gutter Variables.
+* top-level:                             Recursive Editing.
+* top-level form:                        Loading.
+* top-toolbar:                           Specifying the Toolbar.
+* top-toolbar-height:                    Other Toolbar Variables.
+* top-toolbar-visible-p:                 Other Toolbar Variables.
+* tq-close:                              Transaction Queues.
+* tq-create:                             Transaction Queues.
+* tq-enqueue:                            Transaction Queues.
+* tracing:                               Tracing.
+* transaction queue:                     Transaction Queues.
+* transcendental functions:              Math Functions.
+* translate-region:                      Substitution.
+* translating input events:              Translating Input.
+* transpose-regions:                     Transposition.
+* true:                                  nil and t.
+* truename (of file):                    Truenames.
+* truncate:                              Numeric Conversions.
+* truncate-lines:                        Truncation.
+* truncate-partial-width-windows:        Truncation.
+* truncation-glyph:                      Redisplay Glyphs.
+* truth value:                           nil and t.
+* try-completion:                        Basic Completion.
+* two's complement:                      Integer Basics.
+* type:                                  Lisp Data Types.
+* type checking:                         Type Predicates.
+* type predicates:                       Type Predicates.
+* type-of:                               Type Predicates.
+* unbinding keys:                        Key Binding Commands.
+* undefined:                             Functions for Key Lookup.
+* undefined in keymap:                   Key Lookup.
+* undefined key:                         Keymap Terminology.
+* undo avoidance:                        Substitution.
+* undo-boundary:                         Undo.
+* undo-limit:                            Maintaining Undo.
+* undo-strong-limit:                     Maintaining Undo.
+* unexec:                                Building XEmacs.
+* unhandled-file-name-directory:         Magic File Names.
+* unintern:                              Creating Symbols.
+* uninterned symbol:                     Creating Symbols.
+* uninterned symbols, printing:          Output Variables.
+* unique extents:                        Duplicable Extents.
+* universal-argument:                    Prefix Command Arguments.
+* unload-feature:                        Unloading.
+* unloading:                             Unloading.
+* unlock-buffer:                         File Locks.
+* unmap-frame-hook:                      Frame Hooks.
+* unread-command-event:                  Peeking and Discarding.
+* unread-command-events:                 Peeking and Discarding.
+* unreading:                             Input Streams.
+* unregister-tooltalk-pattern:           Elisp Interface for Receiving Messages.
+* unwind-protect:                        Cleanups.
+* unwinding:                             Cleanups.
+* up-list:                               List Motion.
+* upcase:                                Character Case.
+* upcase-region:                         Case Changes.
+* upcase-word:                           Case Changes.
+* update display:                        Refresh Screen.
+* update-directory-autoloads:            Autoload.
+* update-file-autoloads:                 Autoload.
+* upper case:                            Character Case.
+* upper case key sequence:               Key Sequence Input.
+* use-global-map:                        Active Keymaps.
+* use-hard-newlines:                     Filling.
+* use-left-overflow:                     Margin Primitives.
+* use-local-map:                         Active Keymaps.
+* use-right-overflow:                    Margin Primitives.
+* user name completion subroutines:      User Name Completion.
+* user option:                           Defining Variables.
+* user-defined error:                    Error Symbols.
+* user-full-name:                        User Identification.
+* user-home-directory:                   User Identification.
+* user-login-name:                       User Identification.
+* user-mail-address:                     User Identification.
+* user-name-all-completions:             User Name Completion.
+* user-name-completion:                  User Name Completion.
+* user-name-completion-1:                User Name Completion.
+* user-real-login-name:                  User Identification.
+* user-real-uid:                         User Identification.
+* user-uid:                              User Identification.
+* user-variable-p:                       Defining Variables.
+* user-variable-p example:               High-Level Completion.
+* valid-char-table-type-p:               Char Table Types.
+* valid-char-table-value-p:              Working With Char Tables.
+* valid-device-class-p:                  Console Types and Device Classes.
+* valid-device-type-p:                   Console Types and Device Classes.
+* valid-glyph-type-p:                    Glyph Types.
+* valid-image-instance-type-p:           Image Instance Types.
+* valid-image-instantiator-format-p:     Image Specifiers.
+* valid-inst-list-p:                     Specifier Validation Functions.
+* valid-instantiator-p:                  Specifier Validation Functions.
+* valid-plist-p:                         Property Lists.
+* valid-spec-list-p:                     Specifier Validation Functions.
+* valid-specifier-domain-p:              Specifier Validation Functions.
+* valid-specifier-locale-p:              Specifier Validation Functions.
+* valid-specifier-locale-type-p:         Specifier Validation Functions.
+* valid-specifier-tag-p <1>:             Specifier Validation Functions.
+* valid-specifier-tag-p:                 Specifier Tag Functions.
+* valid-specifier-tag-set-p:             Specifier Tag Functions.
+* valid-specifier-type-p:                Specifier Validation Functions.
+* value cell:                            Symbol Components.
+* value of expression:                   Evaluation.
+* values:                                Eval.
+* variable:                              Variables.
+* variable aliases:                      Variable Aliases.
+* variable definition:                   Defining Variables.
+* variable descriptions:                 A Sample Variable Description.
+* variable limit error:                  Local Variables.
+* variable-alias:                        Variable Aliases.
+* variable-documentation:                Documentation Basics.
+* variable-obsoleteness-doc:             Obsoleteness.
+* variables, buffer-local:               Buffer-Local Variables.
+* variables, indirect:                   Variable Aliases.
+* vc-mode:                               Modeline Variables.
+* vconcat:                               Vector Functions.
+* vector <1>:                            Vector Functions.
+* vector:                                Vectors.
+* vector evaluation:                     Self-Evaluating Forms.
+* vector length:                         Sequence Functions.
+* vectorp:                               Vector Functions.
+* verify-visited-file-modtime:           Modification Time.
+* version number (in file name):         File Name Components.
+* version-control:                       Numbered Backups.
+* vertical scrolling:                    Vertical Scrolling.
+* vertical tab:                          Character Type.
+* vertical-motion:                       Screen Lines.
+* vertical-motion-pixels:                Screen Lines.
+* view-file:                             Visiting Functions.
+* view-mode-map:                         Standard Keymaps.
+* view-register:                         Registers.
+* visible frame:                         Visibility of Frames.
+* visible-bell:                          Beeping.
+* visible-frame-list:                    Finding All Frames.
+* visited file:                          Buffer File Name.
+* visited file mode:                     Auto Major Mode.
+* visited-file-modtime:                  Modification Time.
+* visiting files:                        Visiting Files.
+* void function:                         Function Indirection.
+* void function cell:                    Function Cells.
+* void variable:                         Void Variables.
+* void-function:                         Function Cells.
+* void-variable:                         Void Variables.
+* waiting:                               Waiting.
+* waiting for command key input:         Peeking and Discarding.
+* waiting-for-user-input-p:              Sentinels.
+* wakeup:                                Subprocess Creation.
+* walk-windows:                          Cyclic Window Ordering.
+* weak hash table:                       Weak Hash Tables.
+* weak list:                             Weak Lists.
+* weak list type:                        Weak List Type.
+* weak-list-list:                        Weak Lists.
+* weak-list-p:                           Weak Lists.
+* weak-list-type:                        Weak Lists.
+* where-is-internal:                     Scanning Keymaps.
+* while:                                 Iteration.
+* whitespace:                            Character Type.
+* whitespace character:                  Syntax Class Table.
+* widen:                                 Narrowing.
+* widening:                              Narrowing.
+* widget-image-instance-p:               Image Instance Types.
+* window:                                Basic Windows.
+* window configuration (Edebug):         Edebug Display Update.
+* window configurations:                 Window Configurations.
+* window excursions:                     Excursions.
+* window ordering, cyclic:               Cyclic Window Ordering.
+* window point:                          Window Point.
+* window position <1>:                   Position of Window.
+* window position:                       Window Point.
+* window resizing:                       Resizing Windows.
+* window size:                           Size of Window.
+* window size, changing:                 Resizing Windows.
+* window splitting:                      Splitting Windows.
+* window system types:                   Window-System Types.
+* window top line:                       Window Start.
+* window-buffer:                         Buffers and Windows.
+* window-configuration-p:                Window Configurations.
+* window-dedicated-p:                    Choosing Window.
+* window-displayed-text-pixel-height:    Size of Window.
+* window-end:                            Window Start.
+* window-frame:                          Frames and Windows.
+* window-height:                         Size of Window.
+* window-highest-p:                      Position of Window.
+* window-hscroll:                        Horizontal Scrolling.
+* window-left-margin-pixel-width:        Margin Primitives.
+* window-live-p:                         Deleting Windows.
+* window-lowest-p:                       Position of Window.
+* window-min-height:                     Resizing Windows.
+* window-min-width:                      Resizing Windows.
+* window-minibuffer-p:                   Minibuffer Misc.
+* window-pixel-edges:                    Position of Window.
+* window-pixel-height:                   Size of Window.
+* window-pixel-width:                    Size of Window.
+* window-point:                          Window Point.
+* window-right-margin-pixel-width:       Margin Primitives.
+* window-setup-hook:                     Terminal-Specific.
+* window-size-change-functions:          Resizing Windows.
+* window-start:                          Window Start.
+* window-system objects:                 Faces and Window-System Objects.
+* window-text-area-pixel-edges:          Position of Window.
+* window-text-area-pixel-height:         Size of Window.
+* window-text-area-pixel-width:          Size of Window.
+* window-width:                          Size of Window.
+* windowp:                               Basic Windows.
+* windows, controlling precisely:        Buffers and Windows.
+* with-current-buffer:                   Excursions.
+* with-output-to-temp-buffer:            Temporary Displays.
+* with-selected-frame:                   Input Focus.
+* with-temp-file:                        Excursions.
+* word search:                           String Search.
+* word-search-backward:                  String Search.
+* word-search-forward:                   String Search.
+* words-include-escapes:                 Word Motion.
+* word constituent:                      Syntax Class Table.
+* write-abbrev-file:                     Abbrev Files.
+* write-char:                            Output Functions.
+* write-contents-hooks:                  Saving Buffers.
+* write-file:                            Saving Buffers.
+* write-file-hooks:                      Saving Buffers.
+* write-region:                          Writing to Files.
+* write-region-annotate-functions:       Saving Properties.
+* writing a documentation string:        Documentation Basics.
+* wrong-number-of-arguments:             Argument List.
+* wrong-type-argument:                   Type Predicates.
+* X:                                     X-Windows.
+* X resource type:                       X Resource Type.
+* X window frame:                        Frames.
+* x-allow-sendevents:                    X Miscellaneous.
+* x-bitmap-file-path <1>:                X Miscellaneous.
+* x-bitmap-file-path:                    Image Specifiers.
+* x-debug-events:                        X Miscellaneous.
+* x-debug-mode:                          X Miscellaneous.
+* x-disown-selection:                    X Selections.
+* x-display-visual-class:                Server Data.
+* x-emacs-application-class:             Resources.
+* x-find-larger-font:                    Font Instance Size.
+* x-find-smaller-font:                   Font Instance Size.
+* x-font-size:                           Font Instance Size.
+* x-get-cutbuffer:                       X Selections.
+* x-get-resource:                        Resources.
+* x-get-selection:                       X Selections.
+* x-grab-keyboard:                       Grabs.
+* x-grab-pointer:                        Grabs.
+* x-library-search-path:                 X Miscellaneous.
+* x-make-font-bold:                      Font Instance Characteristics.
+* x-make-font-bold-italic:               Font Instance Characteristics.
+* x-make-font-italic:                    Font Instance Characteristics.
+* x-make-font-unbold:                    Font Instance Characteristics.
+* x-make-font-unitalic:                  Font Instance Characteristics.
+* x-own-selection:                       X Selections.
+* x-put-resource:                        Resources.
+* x-server-vendor:                       Server Data.
+* x-server-version:                      Server Data.
+* x-set-frame-icon-pixmap:               Frame Titles.
+* x-store-cutbuffer:                     X Selections.
+* x-ungrab-keyboard:                     Grabs.
+* x-ungrab-pointer:                      Grabs.
+* x-valid-keysym-name-p:                 X Miscellaneous.
+* x-window-id:                           X Miscellaneous.
+* X-Windows:                             X-Windows.
+* XEmacs event standard notation:        Describing Characters.
+* xpm-color-symbols:                     Image Specifiers.
+* y-or-n-p:                              Yes-or-No Queries.
+* y-or-n-p-maybe-dialog-box:             Yes-or-No Queries.
+* yank:                                  Yank Commands.
+* yank suppression:                      Changing Key Bindings.
+* yank-pop:                              Yank Commands.
+* yes-or-no questions:                   Yes-or-No Queries.
+* yes-or-no-p:                           Yes-or-No Queries.
+* yes-or-no-p-dialog-box:                Yes-or-No Queries.
+* yes-or-no-p-maybe-dialog-box:          Yes-or-No Queries.
+* zero-length extent:                    Extent Endpoints.
+* zerop:                                 Predicates on Numbers.
+* zmacs-activate-region:                 The Region.
+* zmacs-activate-region-hook:            The Region.
+* zmacs-deactivate-region:               The Region.
+* zmacs-deactivate-region-hook:          The Region.
+* zmacs-region-stays:                    The Region.
+* zmacs-regions:                         The Region.
+* zmacs-update-region:                   The Region.
+* zmacs-update-region-hook:              The Region.
+* | in regexp:                           Syntax of Regexps.

 
 

-* 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.

 
 

diff --git a/info/new-users-guide.info b/info/new-users-guide.info
index c013101..dbebb64 100644 (file)
--- a/info/new-users-guide.info
+++ b/info/new-users-guide.info
@@ -1,4 +1,4 @@
-This is ../info/new-users-guide.info, produced by makeinfo version 4.0
+This is ../info/new-users-guide.info, produced by makeinfo version 4.6

 from new-users-guide/new-users-guide.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 from new-users-guide/new-users-guide.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -17,60 +17,2787 @@ manual provided the copyright notice and this permission notice are
 preserved on all copies.
 
 \1f
 preserved on all copies.
 
 \1f

-Indirect:
-new-users-guide.info-1: 635
-new-users-guide.info-2: 50520
-new-users-guide.info-3: 100114
+File: new-users-guide.info,  Node: Top,  Next: Intro,  Prev: (dir),  Up: (dir)
+
+The Emacs Editor
+****************
+
+Emacs is the extensible, customizable, self-documenting real-time
+display editor.  This Info file will help you get started on using
+XEmacs.  It corresponds to XEmacs version 19.13.
+
+* Menu:
+
+* Intro::                       Introduction to XEmacs editor
+
+Indices, nodes containing large menus
+* Key Index::                   An item for each standard Emacs key sequence.
+* Command Index::               An item for each command and function name
+* Variable Index::              An item for each variable in User-Guide
+* Concept Index::               An item for the concepts introduced
+
+Entering, Exiting and Editing Emacs
+* Entering::                    Starting Emacs from the shell and Exiting
+* Windows and Menus::           Description of Pull-down menus
+* Edit::                        Basic Editing commands
+
+Other Features of XEmacs
+* Customization Basics::        Customize Emacs menus and keybindings
+* Help::                        Help menu and other help commands
+* Modes::                       Major and Minor modes in XEmacs
+* Files::                       Visiting, Saving and Listing Files
+* Other Customizations::        Customizing Variables, Modes, etc
+* Select and Move::             Selecting text and moving text
+* Search and Replace::          Searching and Replacing text
+
+
+
+ --- The Detailed Node Listing ---
+
+Entering and Exiting Emacs
+
+* Enter::                       Entering Emacs from the shell
+* Frame::                       Basic information about the XEmacs Frame
+* Exiting::                     Exiting Emacs
+* Mode Line::                   Interpreting the mode line.
+* Echo Area::                   Bottom of the frame where you interact
+                                with Emacs.
+
+XEmacs Windows and Menus
+
+* XEmacs Window::               Manipulating XEmacs Windows
+* Pull-down Menus::             Description of XEmacs Pull-down Menus
+
+Pull-down menus
+
+* File menu::                   Items on the File Menu
+* Edit menu::                   Items on the Edit Menu
+* Options Menu::                Items on the Options Menu
+* Buffers Menu::                Items on the Buffers Menu
+* Help menu::                   The Help Menu at the extreme right on
+                                the frame
+
+Basic Editing Commands
+
+* Insert::                      Insert text in Emacs by simply typing at
+                                the cursor position.
+* Cursor Position::             Moving Around the cursor in the buffer,
+* Erase::                       Different commands for erasing text
+* Numeric Argument::            Giving Numeric Arguments to commands
+* Undo::                        Undoing Changes made by mistake
+
+Customize key bindings and menus
+
+* Customizing key Bindings::    Changing Key Bindings
+* Customizing Menus::           Adding, Deleting, Enabling and Disabling Menus
+
+Help
+
+* The Help Menu::               Items on the Help Menu
+
+Major and Minor Modes
+
+* Major Modes::                 Choosing Major Modes
+* Minor Modes::                 Auto-Fill, Abbrev and other minor modes
+
+Emacs Files
+
+* File Names::                  How to type and edit file name arguments.
+* Visiting::                    Visiting a file prepares Emacs to edit the file.
+* Saving Files::                How to save Emacs files.
+
+Other Customizations
+
+* Setting Variables::           Customizing Emacs variables
+* Init File::                   Some examples of Lisp expressions in
+                                init.el file
+
+Selecting and Moving Text
+
+* Selecting Text::              Select a region of text by setting the Mark
+* Mouse::                       Selecting Text with Mouse
+* Region Operation::            Various ways to operate on a selected text
+* Moving Text::                 Moving Text
+* Accumulating text::           Accumulating Text from several buffers
+
+No sub menu for the node search and replace
+
+\1f
+File: new-users-guide.info,  Node: Intro,  Next: Key Index,  Prev: Top,  Up: Top
+
+Introduction
+************
+
+You are reading about XEmacs which is a self-documenting, customizable,
+extensible real-time display editor.
+
+   XEmacs is a "display" editor because normally the text being edited
+is visible on the screen and is updated automatically as you type.
+*Note Display: (xemacs)Frame.
+
+   It is a "real-time" editor because the display is updated very
+frequently, usually after each character or pair of characters you type.
+This minimizes the amount of information you must keep in your head as
+you edit.  *Note Real-time: (xemacs)Basic.
+
+   It is advanced because it provides facilities that go beyond simple
+insertion and deletion: filling of text; automatic indentation of
+programs; viewing two or more files at once; and dealing in terms of
+characters, words, lines, sentences, paragraphs, and pages, as well as
+expressions and comments in several different programming languages.
+It is much easier to type one command meaning "go to the end of the
+paragraph" than to find that spot with simple cursor keys.
+
+   "Self-documenting" means that at any time you can type a special
+character, `Control-h', to find out what your options are.  You can
+also use `C-h' to find out what a command does, or to find all the
+commands relevant to a topic.  *Note Help: (xemacs)Help.
+
+   "Customizable" means you can change the definitions of Emacs
+commands.  For example, if you use a programming language in which
+comments start with `<**' and end with `**>', you can tell the Emacs
+comment manipulation commands to use those strings (*note Comments:
+(xemacs)Comments.).  Another sort of customization is rearrangement of
+the command set.  For example, you can set up the four basic cursor
+motion commands (up, down, left and right) on keys in a diamond pattern
+on the keyboard if you prefer.  *Note Customization:
+(xemacs)Customization.
+
+   "Extensible" means you can go beyond simple customization and write
+entirely new commands, programs in the Lisp language to be run by
+Emacs's own Lisp interpreter.  Emacs is an "on-line extensible" system:
+it is divided into many functions that call each other.  You can
+redefine any function in the middle of an editing session and replace
+any part of Emacs without making a separate copy of all of Emacs.  Most
+of the editing commands of Emacs are written in Lisp; the few
+exceptions could have been written in Lisp but are written in C for
+efficiency.  Only a programmer can write an extension to Emacs, but
+anybody can use it afterward.
+
+\1f
+File: new-users-guide.info,  Node: Entering,  Next: Windows and Menus,  Prev: Concept Index,  Up: Top
+
+Entering and Exiting Emacs
+**************************
+
+While using Emacs you should be familiar with the following three terms:
+
+Buffer
+     A buffer is a region of memory holding characters. It is the basic
+     editing unit; one buffer corresponds to one piece of text being
+     edited. You can have multiple buffers but you can edit only one
+     buffer at any one time. For more information, *Note Buffers:
+     (xemacs)Buffers.
+
+File
+     A file is a region of disk space holding characters. Emacs edits a
+     file by reading it into a buffer, editing that buffer and writing
+     out the buffer back to the file. To save your work permanently you
+     have to write it to a file.  So after you load and work with a
+     file, you have to save it back.
+
+Windows
+     A window is a rectangular region in which a buffer is displayed.
+     You can open multiple windows with multiple buffers and edit them
+     by selecting the corresponding buffer. Initially, when you start
+     emacs, it will automatically open up a window for you.
+
+* Menu:
+
+* Enter::                       Entering Emacs from the shell
+* Frame::                      Basic information about the XEmacs Frame
+* Exiting::                     Exiting Emacs
+* Mode Line::                   Interpreting the mode line.
+* Echo Area::                   Bottom of the frame where you interact
+                                with Emacs.
+
+\1f
+File: new-users-guide.info,  Node: Enter,  Next: Frame,  Prev: Entering,  Up: Entering
+
+Entering Emacs
+==============
+
+To enter Emacs type `xemacs' and press the Return key at the shell i.e.
+`xemacs <RET>'.  This will bring up an emacs window with `*scratch*' as
+the default buffer because Emacs must always have a buffer to work on.
+Then choose the Open... option from the File menu on the menubar at the
+top of the frame. It will prompt you to enter a filename. After you
+enter the filename, Emacs will read that file into the current buffer.
+You can also type :
+     xemacs <filename> <RET>
+   directly which will bring up an Emacs frame with the "filename" as
+the buffer.
+
+\1f
+File: new-users-guide.info,  Node: Frame,  Next: Exiting,  Prev: Enter,  Up: Entering
+
+Emacs Frame
+===========
+
+When you run XEmacs under X, a menu bar on top of the Emacs frame
+provides access to pull-down menus of file, edit, and help-related
+commands. The menus only provide convenient shortcuts, the options that
+they provide are available via key commands. You can invoke those
+commands from the keyboard also. For many of the options, their
+corresponding key commands are displayed right besides them. The five
+default menus on the menubar that you will see on the frame are File,
+Edit, Options, Buffers and Help. *Note XEmacs Pull-down Menus:
+(xemacs)XEmacs Pull-down Menus, for detailed information on the
+functions provided by the pull-down menus.
+
+   The Emacs frame has a rectangle shaped box at the extreme right and
+you can drag it up or down to scroll the window accordingly. Clicking
+on the arrows also serves the same purpose.
+
+   The last line in your window is `the Mode line' which will give you
+a description of what's going on in that particular window. *Note Mode
+Line::, for more information. Below the mode line is the `Echo area'.
+Emacs uses this area to interact with the user. *Note Echo Area::.
+
+   If you wish to open another file in a new window after you enter
+XEmacs, select Open in New Frame... from the File menu, which will
+prompt you for a filename and open a new window with that filename as
+the current buffer. If you want to open a new file in the same window,
+select Open.. from the File menu. You need to enter XEmacs only once,
+you can edit multiple files by opening several other frames or by
+switching between buffers.
+
+\1f
+File: new-users-guide.info,  Node: Exiting,  Next: Mode Line,  Prev: Frame,  Up: Entering
+
+Exiting Emacs
+=============
+
+There are two commands for exiting Emacs, one for "suspending" Emacs
+and the other for "killing" Emacs. "Suspending" means stopping Emacs
+temporarily and returning control to the shell, allowing you to resume
+editing later in the same Emacs job, with the same files, same kill
+ring, same undo history, and so on.  This is the usual way to exit.
+"Killing" Emacs means destroying the Emacs job.  You can run Emacs
+again later, but you will get a fresh Emacs; there is no way to resume
+the same editing session after it has been killed.
+
+`C-z'
+     Suspend Emacs (`suspend-emacs').  If used under the X window
+     system, this command will shrink the X window containing the Emacs
+     frame to an icon. Clicking on the icon will resume that Emacs
+     process again. *Note Exiting Emacs: (xemacs)Exiting Emacs.
+
+`C-x C-c'
+     Kill Emacs (`save-buffers-kill-emacs'). You can also select Exit
+     Emacs option from the File menu to kill that Emacs process. If you
+     haven't saved the file, Emacs will ask you if you wish to save the
+     file before killing that process.
+
+\1f
+File: new-users-guide.info,  Node: Mode Line,  Next: Echo Area,  Prev: Exiting,  Up: Entering
+
+The Mode Line
+=============
+
+When you enter XEmacs, each text window's last line is a "mode line"
+which describes what is going on in that window. Normally, the mode
+line looks like :
+
+     --CH-XEmacs: BUF     (MAJOR MINOR)----POS------
+
+This gives information about the buffer being displayed in the window:
+the buffer's name, what major and minor modes are in use, whether the
+buffer's text has been changed, and how far down the buffer you are
+currently looking.
+
+   The CH contains :
+`**'
+     if the text in the buffer has been edited
+
+`--'
+     if the text in the buffer has not been edited
+
+`%%'
+     if the buffer is a read-only-buffer i.e. it cannot be edited
+
+   BUF is the name of the window's chosen "buffer". If you are editing
+a file (which is the selected buffer), the file name appears in BUF.
+*Note Buffers: (xemacs)Buffers.
+
+   POS contains :
+`All'
+     if your entire file is visible on the screen.
+
+`Top'
+     if you are looking at the beginning of the file.
+
+`Bot'
+     if you are looking at the end of the file.
+
+`NN%'
+     NN will be a number corresponding to the percentage of the file
+     above the top of the screen, for example `52', which means that 52%
+     of the file is above the top of the screen.
+
+   MAJOR is the name of the "major mode" in effect in the buffer.  At
+any time, each buffer is in one and only one major mode.  The available
+major modes include Fundamental mode (the least specialized), Text
+mode, Lisp mode, and C mode.  *Note Major Modes: (xemacs)Major Modes,
+for details on how the modes differ and how you select one.
+
+   MINOR is a list of some of the "minor modes" that are turned on in
+the window's chosen buffer.  For example, `Fill' means that Auto Fill
+mode is on which means that lines are broken automatically when they
+become too wide. *Note Minor Modes: (xemacs)Minor Modes, for more
+information on various minor modes and how to enable them.
+
+   You can also display time in the mode line. *Note The Mode Line:
+(xemacs)The Mode Line, for more information regarding the mode line.
+
+\1f
+File: new-users-guide.info,  Node: Echo Area,  Prev: Mode Line,  Up: Entering
+
+The Echo Area
+=============
+
+The line at the bottom of the frame (below the mode line) is the "echo
+area".  Emacs uses this area to communicate with you:
+
+   *   The "echo area" will print out the characters that you type. For
+     example, if you choose the Open... option from the File menu you
+     might get the following in the echo area:
+
+          Find file: /usr/lib/x11/
+
+     Now you need to give a file name to open, for example if the file
+     name is `myfile', you will type `myfile' after `/usr/lib/x11/' and
+     press the <Return> key. If you pause for more than a second while
+     typing, you will see the characters that you type in the "echo
+     area".
+
+   *   The "echo area" also prints error messages. For example, if you
+     misspell `usr' and type `/urs/lib/x11/myfile' <RETURN> in the
+     above example you might get an error message. Since Emacs will not
+     be able to find the `/urs' directory, the "echo area" will say:
+
+          error--> Opening directory: no such file or directory, /urs/lib/x11/myfile
+
+     This error message will be accompanied by a beep. Some XEmacs
+     commands will print informative messages in the "echo area". *Note
+     The Echo Area: (xemacs)The Echo Area, for more information on the
+     "echo area".
+
+\1f
+File: new-users-guide.info,  Node: Windows and Menus,  Next: Edit,  Prev: Entering,  Up: Top
+
+XEmacs Windows and Menus
+************************
+
+The first section of this chapter will show you how you can manipulate
+XEmacs Windows and the other section will explain the Pull-down Menus of
+an XEmacs window.
+
+* Menu:
+
+* XEmacs Window::               Manipulating XEmacs Windows
+* Pull-down Menus::             Description of XEmacs Pull-down Menus
+
+\1f
+File: new-users-guide.info,  Node: XEmacs Window,  Next: Pull-down Menus,  Prev: Windows and Menus,  Up: Windows and Menus
+
+XEmacs Windows
+==============
+
+When you use XEmacs under X, you can open multiple windows and each
+window can display one buffer or multiple parts of one buffer. Each
+window will have its own "mode line" and "echo area". At any one time
+there is only one "selected window" and the buffer it displays is the
+"selected buffer". There are some commands for manipulating windows:
+
+`M-C-v'
+     This command will scroll the window which is not "selected"
+     (`scroll-other-window').
+
+`C-x 0'
+     This command will get rid of the selected window (`delete-window').
+     That is a zero. If there is more than one Emacs frame, deleting the
+     sole remaining window on that frame deletes the frame as well. If
+     the current frame is the only frame, it is not deleted.
+
+`C-x 1'
+     This command will get rid of all the windows except the selected
+     one.  (`delete-other-windows'). For example, if you use the
+     Describe variable option from the Help menu, the window will split
+     vertically and the bottom window will contain documentation for
+     that variable. After you are done looking at that variable's
+     documentation you might want to come back to your original single
+     window. Just type `C-x 1' after your cursor is in the top window
+     (the window which you want to keep) and hit <RET>.
+
+`C-x 2'
+     This command will split the selected window into two windows, one
+     above the other (`split-window-vertically'). Both the windows will
+     start out by displaying the same buffer. The window in which you
+     have your cursor will be your "selected window".
+
+`C-x 3'
+     This will split the selected window into two windows positioned
+     side by side (`split-window-horizontally'). A line of vertical
+     bars will separate the window.
+
+You can select a buffer in another window by using some other commands.
+These commands all have a prefix key `C-x 4'
+`C-x 4 b BUFNAME <RET>'
+     This command will select a buffer BUFNAME in another window.  This
+     runs `switch-to-buffer-other-window'. It will prompt you for a
+     buffername.
+
+`C-x 4 f FILENAME <RET>'
+     Visit file FILENAME and select its buffer in another window.  This
+     runs `find-file-other-window'.  *Note Visiting: (xemacs)Visiting.
+     It will prompt you for a filename.
+
+`C-x 4 d DIRECTORY <RET>'
+     Select a Dired buffer for directory DIRECTORY in another window.
+     This runs `dired-other-window'.  *Note Dired: (xemacs)Dired.
+
+`C-x 4 m'
+     Start composing a mail message in another window.  This runs
+     `mail-other-window', and its same-window version is `C-x m'.
+     *Note Sending Mail: (xemacs)Sending Mail, for information on how
+     to Send Mail using XEmacs. *Note Reading Mail With Rmail:
+     (xemacs)Reading Mail With Rmail, for information on reading mail
+     using Rmail.
+
+   If you click the right button on the mouse on a mode line, you will
+get a menu with following options:
+Delete Window
+     Choosing this menu will remove the window above this modeline from
+     the frame.
+
+Delete Other Windows
+     Delete all windows on the frame except for the one above this
+     modeline.
+
+Split Window
+     Split the window above the mode line in half, creating another
+     window.
+
+Split Window Horizontally
+     Split the window above the mode line in half horizontally, so that
+     there will be two windows side-by-side.
+
+Balance Windows
+     Readjust the sizes of all windows on the frame until all windows
+     have roughly the same number of lines.
+
+\1f
+File: new-users-guide.info,  Node: Pull-down Menus,  Prev: XEmacs Window,  Up: Windows and Menus
+
+XEmacs Pull-down Menus
+======================
+
+When you run XEmacs under X, each Emacs frame has a menu-bar at the top
+which provides commands for editing, help and other options. All these
+options are also available via key commands, the menus just provide
+convenient short-cuts. The key commands are displayed right besides
+some of the options. The following is a brief description of the four
+default menus on the menu bar:
+
+* Menu:
+
+* File menu::                   Items on the File menu
+* Edit menu::                   Items on the Edit menu
+* Options Menu::                Items on the Options Menu
+* Buffers Menu::                Items on the Buffers Menu
+* Help menu::                   The Help Menu at the extreme right on
+                                the frame
+
+\1f
+File: new-users-guide.info,  Node: File menu,  Next: Edit menu,  Prev: Pull-down Menus,  Up: Pull-down Menus
+
+The File Menu
+-------------
+
+The File menu bar contains the following items. To choose a particular
+option, press the left mouse button and drag it to the item you wish to
+select. Then release the button.
+
+Open...
+     This option will prompt you for a file name. You will get a
+     message in the echo area:
+
+          Find File:
+
+     After Find File, there might be a directory path also. After you
+     type the file name and press <RET> the file will be loaded into a
+     new buffer.
+
+Open in New Frame...
+     It prompts you for a file name and loads that file in a new buffer
+     in a new frame. You can open many frames for the same Emacs
+     session. You can delete the frame by selecting Delete Frame.
+
+Insert File...
+     Prompts you for a filename and inserts the contents of this
+     filename in your current buffer. Position your cursor at the place
+     you wish to insert the file and select this option. You will get
+     the following message in the echo area:
+
+          Insert file:
+
+     Insert the file name and press <RET>.
+
+Save <Buffername>
+     It saves the changes you have made to the buffer. If you have made
+     changes which are not saved yet, the option will appear dark,
+     otherwise it will be light and unselectable. If you do not wish to
+     save the changes, select Revert Buffer.
+
+Save As...
+     Prompts you for a filename and saves the current buffer in that
+     file. It loads the new file if the filename you specify is
+     different from the one you were working with.
+
+Print Buffer <buffername>
+     Prints a hardcopy of the current or "selected" buffer.
+
+New Frame
+     Opens a new frame with *scratch* as the default buffer. It doesn't
+     prompt you for a filename. To open a file you need to go to that
+     frame and select Open...
+
+Split Frame
+     Splits the current window into two equal-sized windows with the
+     same buffer. To get back a single frame, select Un-Split (Keep
+     This). *Note XEmacs Window::, for more information about windows.
+
+Un-Split (Keep This)
+     If the frame contains multiple windows, it will remove all windows
+     except the selected one.
+
+Un-Split (Keep Others)
+     If the frame contains multiple windows, it will remove the selected
+     window and keep the other one.
+
+Revert Buffer <buffername>
+     If you do not wish to save the changes you made to the file since
+     you opened it, select this option. It will restore the last saved
+     version of the file to the current buffer.
+
+Kill Buffer <buffername>
+     It will kill the current buffer. If will prompt you if there are
+     unsaved changes.
+
+Exit Emacs
+     It will kill the Emacs "process" as opposed to simply killing the
+     "buffer". Before it kills the process, it will prompt you as to
+     which unsaved buffers you wish to save by going through the list
+     of the buffers.
+
+
+* Menu:
+
+* Edit menu::                   Items on the Edit Menu
+* Options Menu::                Items on the Options Menu
+* Buffers Menu::                Items on the Buffers Menu
+* Help menu::                   The Help Menu at the extreme right on
+                                the frame
+
+\1f
+File: new-users-guide.info,  Node: Edit menu,  Next: Options Menu,  Prev: File menu,  Up: Pull-down Menus
+
+The Edit Menu
+-------------
+
+Most of the commands in this menu work on a block of text or a selected
+region. The text will be highlighted as you select it.
+Undo
+     Undoes the previous command.  If you type something by mistake you
+     can use this command. For example, if you select Insert File...
+     from the File menu and insert a wrong file by mistake, you can
+     select this item and it will remove the inserted file. It undoes a
+     batch of text which is worth an emacs command.
+
+Cut
+     Removes the selected text block from the current buffer, makes it
+     the X clipboard selection, and places it in the kill ring (*note
+     Moving Text::). Before executing this command, you have to select
+     a region using Emacs region selection commands or with the mouse.
+     *Note Selecting Text::.
+
+Copy
+     Makes a selected text block the X clipboard selection, and places
+     it in the kill ring.  You can select text using one of the Emacs
+     region selection commands or by selecting a text region with the
+     mouse. *Note Selecting Text::, for more information.
+
+Paste
+     Inserts the current value of the X clipboard selection in the
+     current buffer.  Note that this is not necessarily the same as the
+     Emacs `yank' command, because the Emacs kill ring and the X
+     clipboard selection are not the same thing.  You can paste in text
+     you have placed in the clipboard using Copy or Cut.  You can also
+     use Paste to insert text that was pasted into the clipboard from
+     other applications. *Note X Clipboard Selection: (xemacs)X
+     Clipboard Selection, for information on using Clipboard Selection.
+
+Clear
+     Removes the selected text block from the current buffer but does
+     not place it in the kill ring or the X clipboard selection. You
+     will not be able to get this text back.
+
+Start Macro Recording
+     After selecting this, Emacs will remember every keystroke you type
+     until End Macro Recording is selected.
+
+End Macro Recording
+     Selecting this tells emacs to stop remembering your keystrokes.
+
+Execute Last Macro
+     Selecting this item will cause emacs to re-interpret all of the
+     keystrokes which were saved between selections of the Start Macro
+     Recording and End Macro Recording menu items.  You can now execute
+     the most recent keyboard macro. *Note Keyboard Macros:
+     (xemacs)Keyboard Macros, for further information.
+
+\1f
+File: new-users-guide.info,  Node: Options Menu,  Next: Buffers Menu,  Prev: Edit menu,  Up: Pull-down Menus
+
+The Options Menu
+----------------
+
+There are sub-menus for some of the menus which you will need to
+select. If sub-menus exist for an item, they will be displayed
+automatically when you drag the mouse on that item. The items in this
+menu provide some fancy editing operations.
+
+Read Only
+     Selecting this item will cause the buffer to visit the file in a
+     read-only mode. Changes to the file will not be allowed.
+
+Case Sensitive Search
+     Selecting this item will cause searches to be case-sensitive. If
+     its not selected then searches will ignore case. This option is
+     local to the buffer. For example, if this item is selected and you
+     are searching for `Smile', then an occurrence of `smile' will not
+     be recognized because of the smaller case of `s'.
+
+Overstrike
+     After selecting this item, when you type letters they will replace
+     existing text on a one-to-one basis, rather than pushing it to the
+     right. At the end of a line, such characters extend the line.
+     Before a tab, such characters insert until the tab is filled in.
+
+Auto Delete Selection
+     Selecting this item will cause automatic deletion of the selected
+     region. After you select a region and hit the <RET> key, the
+     selected text will be deleted. The typed text will replace the
+     selection if the selection is active (i.e. if its highlighted). If
+     the option is not selected then the typed text is just inserted at
+     the cursor.
+
+Teach Extended Commands
+     After you  select this item, any time you execute a command with
+     `M-x' which has a shorter keybinding, you will be shown the
+     alternate binding before the command executes. For example if you
+     type `M-x find-file-other-window' which performs the same function
+     as the Open in Other Window... in File menu you will see the
+     following message:
+
+          M-x find-file-other-window (bound to keys: C-x 4 f, C-x 4 C-f)
+
+Syntax Highlighting
+     You can customize your `init.el' file to include the font-lock mode
+     so that when you select this item, the comments will be displayed
+     in one face, strings in another, reserved words in another, and so
+     on. *Note Customization: (xemacs)Customization, for more
+     information on customizing `init.el' file.  After selecting this
+     item, you will find your code a lot easier to read. When Fonts is
+     selected, different parts of the program will appear in different
+     Fonts. When Colors is selected, then the program will be displayed
+     in different colors. Selecting None causes the program to appear in
+     just one Font and Color. Selecting Less resets the Fonts and Colors
+     to a fast, minimal set of decorations. Selecting More resets the
+     Fonts and Colors to a larger set of decorations. For example, if
+     Less is selected (which is the default setting) then you might have
+     all comments in green color. It does not matter what the comments
+     contain. Whereas, if More is selected then a function name in the
+     comments themselves might appear in a different Color or Font. Even
+     though the comments themselves might appear in green color, a
+     function name "within" the comments might appear in red color.
+
+Paren Highlighting
+     After selecting Blink from this item, if you place the cursor on a
+     parenthesis, the matching parenthesis will blink. If you select
+     Highlight and place the cursor on a parenthesis, the whole
+     expression of the parenthesis under the cursor will be highlighted.
+     Selecting None will turn off the options (regarding Paren
+     Highlighting) which you had selected earlier.
+
+Font
+     You can select any Font for your program by choosing from one of
+     the available Fonts. The whole buffer will be converted to the
+     Font you select.
+
+Size
+     You can select any size for the text in your buffer (ranging from
+     2 to 24) by selecting the appropriate option.
+
+Weight
+     You can choose either Bold or Medium for the weight of the text of
+     your buffer.
+
+Buffers Menu Length...
+     Prompts you for the number of buffers to display. Then it will
+     display that number of most recently selected buffers.
+
+Buffers Sub-Menus
+     After selection of this item the Buffers menu will contain several
+     commands, as submenus of each buffer line. If this item is
+     unselected, then there are no submenus for each buffer line, the
+     only command available will be selecting that buffer.
+
+Save Options
+     Selecting this item will save the current settings of your Options
+     menu to your `init.el' file so that the next time you start XEmacs,
+     you won't need to select the options again.
+
+\1f
+File: new-users-guide.info,  Node: Buffers Menu,  Next: Help menu,  Prev: Options Menu,  Up: Pull-down Menus
+
+The Buffers Menu
+----------------
+
+The Buffers menu provides a selection of up to ten buffers and the item
+List All Buffers, which provides a Buffer List. If you select Buffers
+Sub-menus from the Options menu, you will get some sub-menus for each
+of the buffer listing.
+
+\1f
+File: new-users-guide.info,  Node: Help menu,  Prev: Buffers Menu,  Up: Pull-down Menus
+
+The Help Menu
+-------------
+
+The Help Menu gives you access to Emacs Info and provides a menu
+equivalent for some of the choices you have when using `C-h'.  *Note
+Help::, for more information.
+
+   The Describe variable and Describe function will provide
+documentation for the corresponding variable or function. The Help menu
+also gives access to UNIX online manual pages via the UNIX Manual...
+option.
+
+\1f
+File: new-users-guide.info,  Node: Edit,  Next: Customization Basics,  Prev: Windows and Menus,  Up: Top
+
+Basic Editing Commands
+**********************
+
+This chapter will introduce you to some basic editing commands. You can
+also learn the basic editing commands by typing `Control-h t'
+(`help-with-tutorial' OR by selecting Emacs Tutorial from the Help menu
+on the menu bar. Most of the Emacs commands will use the <CONTROL> key
+or the <META> key. The following abbreviations will be used for the
+<CONTROL> and <META> key in this manual:
+
+`C-<chr>'
+     This means that you should hold down the <CONTROL> key while typing
+     `<chr>'. For example, if the command is `C-g', you should hold the
+     <CONTROL> key and type <g>.
+
+`M-<chr>'
+     This means that you should hold down the `META' key while typing
+     `<chr>'. If there is no `META' key on your keyboard, use the `ESC'
+     key instead. For example, if the command is `M-x', then type
+     `ESC', release it and type `x'.
+
+   The following abbreviations will be used for some other keys:
+
+<SPC>
+     Space bar.
+
+<RET>
+     Return key.
+
+<LFD>
+     Linefeed key.
+
+<TAB>
+     Tab.
+
+<ESC>
+     Escape.
+
+<SFT>
+     Shift.
+
+* Menu:
+
+* Insert::                      Insert text in Emacs by simply typing at
+                                the cursor position.
+* Cursor Position::             Moving Around the cursor in the buffer,
+* Erase::                       Different commands for erasing text
+* Numeric Argument::            Giving Numeric Arguments to commands
+* Undo::                        Undoing Changes made by mistake
+
+\1f
+File: new-users-guide.info,  Node: Insert,  Next: Cursor Position,  Prev: Edit,  Up: Edit
+
+Inserting Text
+==============
+
+To insert printing characters into the text you are editing, just type
+them. Emacs will automatically insert the characters that you type into
+the buffer at the cursor. The cursor moves forward, but if you prefer
+to have text characters replace (overwrite) existing text characters,
+you can enable the Overstrike option from the Options menu in the menu
+bar.
+
+   To "delete" text you have just inserted, use <DEL>.  <DEL> deletes
+the character BEFORE the cursor (not the one that the cursor is on top
+of or under; that is the character AFTER the cursor).  The cursor and
+all characters after it move backwards.  Therefore, if you type a
+printing character and then type <DEL>, they cancel out.
+
+   To end a line and start typing a new one, type <RET>.  This inserts
+a newline character in the buffer.  If point is in the middle of a
+line, <RET> splits the line.  Typing <DEL> when the cursor is at the
+beginning of a line rubs out the newline before the line, thus joining
+the line with the preceding line.
+
+   Emacs automatically splits lines when they become too long, if you
+turn on a special mode called "Auto Fill" mode.  *Note Filling:
+(xemacs)Filling, for information on using Auto Fill mode.
+
+\1f
+File: new-users-guide.info,  Node: Cursor Position,  Next: Erase,  Prev: Insert,  Up: Edit
+
+Moving Around
+=============
+
+The following commands will allow you to move the cursor around the
+screen. The actual function names corresponding to these commands are
+given in parenthesis. You can also invoke these commands by typing `M-x
+<function name>'. You can do this for any command in XEmacs.
+
+`C-b'
+     Move the cursor backward one character (`backward-char').
+
+`C-f'
+     Move the cursor forward one character (`forward-char').
+
+`C-p'
+     Move the cursor up one line vertically (`previous-line').
+
+`C-n'
+     Move the cursor down one line vertically (`next-line').
+
+`C-a'
+     Move the cursor to the beginning of the line (`beginning-of-line').
+
+`C-e'
+     Move the cursor to the end of the line (`end-of-line').
+
+`M-f'
+     Move the cursor forward one word (`forward-word').
+
+`M-b'
+     Move the cursor backward one word (`backward-word').
+
+`M-<'
+     Move the cursor to the top of the buffer (`beginning-of-buffer').
+
+`M->'
+     Move the cursor to the end of the buffer (`end-of-buffer').
+
+`M-x goto-char RET <number> RET'
+     To enable this command type `M-x goto-char', and hit <RETURN> key.
+     In the "echo area" you will see:
+
+          Goto char:
+
+     You should then type in a number right after the colon and hit the
+     `RETURN' key again. After reading a number N this command will
+     move the cursor to character number N.  Position 1 is the
+     beginning of the buffer. For example, if you type `M-x goto-char
+     RET 200 RET', then the cursor will move to the 200th character
+     starting from the beginning of the buffer.
+
+`M-x goto-line RET <number> RET'
+     To enable this command type `M-x goto-line', and hit the <RETURN>
+     key. After you see `Goto line:' in the "echo area", type in a
+     number N and hit <RETURN> key again. This command will position
+     the cursor on the nth line starting from the beginning of the
+     buffer.
+
+`M-x what-line RET'
+     This command will display the current line number in the echo area.
+
+
+\1f
+File: new-users-guide.info,  Node: Erase,  Next: Numeric Argument,  Prev: Cursor Position,  Up: Edit
+
+Erasing Text
+============
+
+`<DEL>'
+     If you press <DEL> i.e. the "delete" key, it will delete the
+     character before the cursor (`delete-backward-char').
+
+`C-d'
+     This will delete the character after the cursor (`delete-char').
+
+`C-k'
+     Kill to the end of the line (`kill-line'). If you kill the line by
+     mistake you can "yank" or `paste' it back by typing `C-y'. *Note
+     Moving Text::, for more information on yanking.
+
+`M-d'
+     Kill forward to the end of the next word (`kill-word').
+
+`M-<DEL>'
+     Kill back to the beginning of the previous word
+     (`backward-kill-word').
+
+`M-k'
+     Kill to the end of current sentence (`kill-sentence').
+
+`M-z CHAR'
+     Kill up to next occurrence of CHAR (`zap-to-char'). To use this
+     command type `M-z'. You will see the following statement in the
+     echo area :
+
+          Zap to char:
+
+     Type any char and press the <RET> key. For example, if you type
+     `p' then the entire text starting from the position of the cursor
+     until the first occurrence of `p' is killed.
+
+\1f
+File: new-users-guide.info,  Node: Numeric Argument,  Next: Undo,  Prev: Erase,  Up: Edit
+
+Giving Numeric Arguments
+========================
+
+Any Emacs command can be given a "numeric argument".  Some commands
+interpret the argument as a repetition count.  For example, if you want
+to move forward ten characters, you could type `C-f' ten times.
+However, a more efficient way to do this would be to give an argument
+of ten to the key `C-f' (the command `forward-char', move forward one
+character). Negative arguments are also allowed. Often they tell a
+command to move or act backwards. For example, if you want to move down
+ten lines, type the following:
+     C-u 10 C-n RET
+
+After you press <RET> key, the cursor will move ten lines downward. You
+can also type:
+     M-10 C-n RET
+
+Both `C-u' and `M-' allow you to give numeric arguments. If you want to
+move ten lines backward, you can also give negative arguments, like:
+     C-u -10 C-n RET
+
+OR you could also type:
+     M--10 C-n RET
+
+You can obviously use `C-b' to move backward rather than giving
+negative arguments to `C-n'. *Note Numeric Arguments: (xemacs)Numeric
+Arguments, for more information on numeric arguments.
+
+\1f
+File: new-users-guide.info,  Node: Undo,  Prev: Numeric Argument,  Up: Edit
+
+Undoing Changes
+===============
+
+When you are editing a buffer, you might type something by mistake.
+Emacs allows you to undo all changes you make to a buffer (but not more
+than 8000 characters). Each buffer in Emacs keeps a record of the
+changes made to it individually, so the undo command applies to the
+current buffer. There are two undo commands:
+
+`C-x u'
+     Undo one batch of changes (usually, one command's worth).
+     (`undo').
+
+`C-_'
+     The same as above, but this command might not be obvious to type
+     on some keyboards so it might be better to use the above command.
+
+   *Note Undoing Changes: (xemacs)Undoing Changes, for more information
+on undoing changes.
+
+\1f
+File: new-users-guide.info,  Node: Customization Basics,  Next: Help,  Prev: Edit,  Up: Top
+
+Customize key bindings and menus
+********************************
+
+When you start Emacs, it reads the file `~/.xemacs/init.el' in the
+`.xemacs/' subdirectory of your home directory. You can use this file
+to initialize and customize Emacs to your liking. This file should
+contain lisp-code. You can customize your `init.el' file to create new
+menus, disable menus, change key bindings, enable a minor mode, etc.
+Any kind of customization affects only a particular Emacs job that you
+do them in. If you want to save your customizations `permanently' i.e.
+for future use also, you have to put it in your `init.el' file. After
+you make changes to your `init.el' file and save it, the changes will
+be effective only after you start Emacs again i.e. for a new Emacs
+process. To try out some of the examples in this section, highlight
+that region and evaluate the region by giving the command `M-x
+eval-region'. You will be able to see the results of your
+customizations in that Emacs session only (*note Lisp Eval:
+(xemacs)Lisp Eval.).
+
+* Menu:
+
+* Customizing key Bindings::    Changing Key Bindings
+* Customizing Menus::           Adding, Deleting, Enabling and Disabling Menus
+
+\1f
+File: new-users-guide.info,  Node: Customizing key Bindings,  Next: Customizing Menus,  Prev: Customization Basics,  Up: Customization Basics
+
+Customize key bindings
+======================
+
+Most of Emacs commands use key sequences. *Note Keystrokes:
+(xemacs)Keystrokes, for more information about Keys and Commands. In
+Emacs, the keys themselves carry no meaning unless they are bound to a
+function. For example, `C-n' moves the cursor to the next line because
+its bound to the function next-line. Similarly, `C-p' moves to the
+previous line because its bound to the function previous-line. The
+functions themselves define a particular behavior. You can customize
+the key `C-n' to move to the previous line by binding it to
+previous-line and `C-p' to move to the next line by binding it to
+next-line. To bind keys to globally run commands you need to use the
+following syntax in your init.el file:
+
+     `(global-set-key KEYS CMD)'
+
+Here, `global-set-key' is a function which will bind the "keys" to the
+specified "cmd". For example, if you type the following in your init.el
+file:
+
+     (global-set-key "\C-p" 'next-line)
+     (global-set-key "\C-n" 'previous-line)
+
+then `C-p' will move to the next line and `C-n' to the previous line.
+
+   You can also disable a key binding, by using `nil' as the CMD in the
+syntax stated above. Here, `nil' stands for `false' which means disable
+a command or turn off a feature. If you want to enable a command or
+turn on a particular feature use `t' which stands for `true'.  For
+example, if you do not wish `C-x C-c' to `Exit Emacs' you can type the
+following expression in your `init.el' file:
+
+     (global-set-key "\C-x\C-c" nil)
+
+You might want to have this statement in your `init.el' file because
+its easy to hit this command by mistake and it could be annoying to exit
+Emacs unintentionally. There is an Exit Emacs option in the File menu
+which you might want to use instead. To make a particular key undefined
+you can also use:
+
+     (global-unset-key "\C-x\C-c")
+
+Now if you use the command `C-x C-c', you will get an error saying that
+the command is undefined.
+
+   Some other customizations you could try are:
+   *      (global-set-key 'button3 'beginning-of-buffer)
+
+     Now when you press the third button of your mouse, the cursor will
+     be placed at the `beginning-of-buffer'.
+
+   *      (global-set-key 'f1 'goto-line)
+
+     If you press the <F1> key, you will be prompted for a line number.
+     After you type the line number and hit <RET>, the cursor will be
+     placed on that line number.
+
+   *      (global-set-key 'f2 'undo)
+
+     Pressing <F2> will undo the last command. If you have a <undo> key
+     on your keyboard, try binding that key to the undo command.
+
+   Another syntax for customizing key bindings is: `(define-key KEYMAP
+KEYS DEF)' It defines KEYS to run DEF in the keymap KEYMAP.
+
+   KEYMAP is a keymap object which records the bindings of keys to the
+commands that they run.
+
+   KEYS is the sequence of keystrokes to bind.
+
+   DEF is anything that can be a key's definition:
+
+   Look at the following two examples:
+
+     (define-key global-map "\C-xl" 'make-symbolic-link)
+     (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+
+Both the examples bind the key `C-xl' to run the function
+`make-symbolic-link' (*note Misc File Ops: (xemacs)Misc File Ops.).
+However, the second example will bind the key only for C mode. *Note
+Major Modes: (xemacs)Major Modes, for more information on Major Modes
+in XEmacs.
+
+\1f
+File: new-users-guide.info,  Node: Customizing Menus,  Prev: Customizing key Bindings,  Up: Customization Basics
+
+Customizing Menus
+=================
+
+You can customize any of the  XEmacs Pull-down-Menus. You can create
+your own menu, delete an existing one, enable a menu or disable a menu.
+For more information on the default menus available to you, *Note
+Pull-down Menus::.
+
+   Some of the functions which are available to you for customization
+are:
+  1. add-menu-item: (MENU-NAME ITEM-NAME FUNCTION ENABLED-P &optional
+     BEFORE)
+
+     This function will add a menu item to a menu, creating the menu
+     first if necessary. If the named item already exists, the menu
+     will remain unchanged. For example, if you add the following
+     example to your `init.el' file or evaluate it (*note Customization
+     Basics::),
+
+          (add-menu-item '("Edit") "Replace String" replace-string t "Clear")
+
+     a sub-menu Replace String will be created under Edit menu before
+     the sub-menu Clear. The Edit menu will now look like:
+
+          Undo                    C-x u
+          Cut                     cut
+          Copy                    copy
+          Paste                   paste
+          Replace String
+          Clear
+          Start Macro Recording   C-x(
+          End Macro Recording     C-x)
+          Execute Last Macro      C-xe
+
+     Replace String will now execute the function `replace-string'.
+     Select this menu item. Emacs will prompt you for a string name to
+     be replaced. Type a string and hit <RET>. Now type a new string to
+     replace the old string and hit <RET>. All occurrences of the old
+     string will be replaced by the new string. In this example,
+
+     `Edit' is the MENU-NAME which identifies the menu into which the
+     new menu item should be inserted.
+
+     `Replace String' is the ITEM-NAME which names the menu item to be
+     added.
+
+     `replace-string' is the FUNCTION i.e. the command to be invoked
+     when the menu item "Replace String" is selected.
+
+     `t' is the ENABLED-P parameter which controls whether the menu
+     item is selectable or not. This parameter can be either `t'
+     (selectable), `nil' (not selectable), or a form to evaluate. This
+     form is evaluated just before the menu is displayed, and the menu
+     item will be selectable if the form returns non-`nil'.
+
+     `Clear' is the &OPTIONAL BEFORE parameter which is the name of the
+     menu before which the new menu or sub-menu should be added. The
+     &OPTIONAL string means that this parameter is optional. You do not
+     need to specify this parameter. If you do not specify this
+     parameter in the example above, the Replace String menu item will
+     be added at the end of the list of sub-menus in the Edit menu i.e.
+     after Execute Last Macro.
+
+     If you wish to add a new menu to the menubar, try:
+
+          (add-menu-item nil "Bot" 'end-of-buffer t)
+
+     This will create a new menu Bot on the menu bar. Selecting this
+     menu will take you to the end of the buffer. Using `nil' for the
+     parameter MENU-NAME will create a new menu. Your menu-bar will now
+     look like:
+
+          File Edit Options Buffers Bot                         Help
+
+     The following example will illustrate how you can add sub-menus to
+     the submenus themselves:
+
+          (add-menu-item '("File" "Management") "Copy File" 'copy-file t)
+          (add-menu-item '("File" "Management") "Delete File" 'delete-file t)
+          (add-menu-item '("File" "Management") "Rename File" 'rename-file t)
+
+     This will create a sub-menu Management under the File menu. When
+     you select the submenu Management, it will contain three submenus:
+     Copy File, Delete File and Rename File.
+
+  2. delete-menu-item: (MENU-PATH) This function will remove the menu
+     item defined by MENU-NAME from the menu hierarchy. Look at the
+     following examples and the comments just above them which specify
+     what the examples do.
+
+          ;; deletes the "Replace String" menu item created earlier
+          (delete-menu-item '("Edit" "Replace String"))
+          
+          ;; deletes the "Bot" menu created earlier
+          (delete-menu-item '("Bot"))
+          
+          ;; deletes the sub-menu "Copy File" created earlier
+          (delete-menu-item '("File" "File Management" "Copy File"))
+          
+          ;; deletes the sub-menu "Delete File" created earlier
+          (delete-menu-item '("File" "Management" "Delete File"))
+          
+          ;; deletes the sub-menu "Rename File" created earlier
+          (delete-menu-item '("File" "Management" "Rename File"))
+
+  3. disable-menu-item: (MENU-NAME) Disables the specified menu item.
+     The following example
+
+          (disable-menu-item '("File" "Management" "Copy File"))
+
+     will make the Copy File item unselectable. This menu-item would
+     still be there but it will appear faded which would mean that it
+     cannot be selected.
+
+  4. enable-menu-item: (MENU-NAME) Enables the specified previously
+     disabled menu item.
+
+          (enable-menu-item '("File" "Management" "Copy File"))
+
+     This will enable the sub-menu Copy File, which was disabled by the
+     earlier command.
+
+  5. relabel-menu-item: (MENU-NAME NEW-NAME) Change the string of the
+     menu item specified by MENU-NAME to NEW-NAME.
+
+          (relabel-menu-item '("File" "Open...") "Open File")
+
+     This example will rename the Open... menu item from the File menu
+     to Open File.
+
+
+\1f
+File: new-users-guide.info,  Node: Help,  Next: Modes,  Prev: Customization Basics,  Up: Top
+
+Help
+****
+
+XEmacs provides a comprehensive Help facility. On the extreme right of
+the menu-bar there is a Help menu. There are several help commands
+provided by this menu. You can also use `C-h' for invoking the Help
+facility. Type "?" for a list of keys you can type after typing `C-h'.
+If you want more information on what your options are and what kind of
+help you can get type "?" again. You will get a listing of all the keys
+you can type and what they will do. Initially if you want help, type
+`C-h' three times.
+
+* Menu:
+
+* The Help Menu::                   Items on the Help menu
+
+\1f
+File: new-users-guide.info,  Node: The Help Menu,  Prev: Help,  Up: Help
+
+Help menu
+=========
+
+When you click on the Help menu with any of the mouse buttons you will
+get the following menu items:
+
+Info
+     Selecting this item will take you to the Info page which is the
+     online documentation browsing system. You can simply click on the
+     highlighted items and "Info" will take you to the document
+     providing information about that topic.
+
+Describe Mode
+     After you select this item, you will get a documentation on the
+     major and minor modes which are enabled in the buffer you are
+     working with. *Note Modes::, for information on Modes.
+
+Hyper Apropos...
+     After you select this item, you will see the following message in
+     the echo area:
+
+          List symbols matching regexp:
+
+     If you type "mode" and hit <RET>, you will get a list of all the
+     symbols (like functions and commands). You can now get
+     documentation on any of the given symbols by "clicking" on any of
+     the symbols (i.e. drag your mouse on the appropriate symbol and
+     release the button). For example, if you "click" on the
+     'auto-fill-mode' you will get the following message in the window
+     at the bottom:
+
+          auto-fill-mode
+          
+          Function, Command:
+          
+            Toggle auto-fill mode.
+            With arg, turn auto-fill mode on if and only if arg is positive.
+            In auto-fill mode, inserting a space at a column beyond `fill-column'
+            automatically breaks the line at a previous space.
+          
+          Variable:
+          
+            value = nil
+          
+            variable not documented
+
+Command Apropos...
+     Selecting this item will prompt you for a string just like when you
+     select Hyper Apropos.... After you give a string name, you will get
+     a listing of all the functions and commands containing that string
+     name with a very short description about what that command does.
+
+Full Apropos...
+     After you select this item, you will be prompted for a string name
+     in the echo area:
+
+          Apropos (regexp):
+
+     Now you can give any string name, for example "mode" and hit
+     <RET>. You will get a listing of all the variables and commands
+     containing that string i.e "mode" with a short description of its
+     function.
+
+List Keybindings
+     Select this item and you will get a listing of all the keys and the
+     commands that they execute. Depending on which Major mode your
+     buffer is in, you will get a listing of the special keybindings
+     for that particular buffer also. For example, if you are in
+     "Texinfo" mode, part of your list will contain:
+
+          C-c C-c n       texinfo-insert-@node
+          C-c C-c o       texinfo-insert-@noindent
+          C-c C-c s       texinfo-insert-@samp
+          C-c C-c t       texinfo-insert-@table
+          C-c C-c v       texinfo-insert-@var
+          C-c C-c x       texinfo-insert-@example
+          C-c C-c {      texinfo-insert-braces
+
+     These keybindings apply only to "Texinfo" mode. *Note Modes::, for
+     more information on various modes.
+
+Describe Key...
+     After you select this item, you will be see the following message
+     in the echo area:
+
+          Describe Key:
+     After you type a command key sequence, full documentation of that
+     command will be displayed. For example if you type `C-g', you will
+     see the following documentation for `C-g':
+
+          keyboard-quit:
+          Signal a `quit' condition.
+     This means that `C-g' will quit whatever command you gave earlier.
+
+Describe Function...
+     This menu item provides documentation for a function. After you
+     select this item, it will prompt you for a function name in the
+     echo area:
+
+          Describe function (default <some function name>):
+
+     If you hit <RET> without giving a function name, you will get
+     documentation for that default function name, otherwise if you
+     type a function name and hit <RET>, you will get documentation for
+     the given function.
+
+Describe Variable...
+     You can get documentation on any variable by selecting this menu
+     item. It is similar to Describe Function and will prompt you for a
+     variable name.
+
+Unix Manual...
+     After you select this item you will be prompted for a Unix command
+     for which you wish to see the man page. You will see the following
+     message in the echo area:
+
+          Manual entry: (default <some name>)
+
+     Now you can type any command, for example type `who' and press
+     <RET>. You will get the man page for the Unix command `who' which
+     lists who is on the system.
+
+Emacs Tutorial
+     Select this item and you will get a tutorial on Emacs. It is good
+     for new users.
+
+Emacs News
+     Select this item and you will get a lot of historical and current
+     news on Emacs !
+
+
+   For more information on the Help facility, *Note Help: (xemacs)Help.
+
+\1f
+File: new-users-guide.info,  Node: Modes,  Next: Files,  Prev: Help,  Up: Top
+
+Major and Minor Modes
+*********************
+
+XEmacs is "language sensitive". It has several "major" and "minor"
+modes.  The major modes customize Emacs to edit text of a particular
+sort. There are major modes for C, Lisp, Emacs Lisp, LaTeX, English
+etc. Within each major mode, certain functions and keys are redefined
+to "suit" that particular sort of text. The minor modes provide certain
+features which can be turned off or on at any time. Emacs can only be
+in one major mode at any time, but it can turn on several minor modes
+at the same time. After you have selected any major or minor mode, you
+can select Describe Mode from the Help menu and you will get
+documentation about those modes.
+
+* Menu:
+
+* Major Modes::                 Choosing Major Modes
+* Minor Modes::                 Auto-Fill, Abbrev and other minor modes
+
+\1f
+File: new-users-guide.info,  Node: Major Modes,  Next: Minor Modes,  Prev: Modes,  Up: Modes
+
+Major Modes
+===========
+
+Emacs has several major modes which customize Emacs to edit text of
+various sorts. You can have only one major mode at any time. Within each
+major mode, Emacs redefines certain functions (like cursor movement,
+indentation and text killing) to suit the needs of the text being
+edited. When you are editing a specific type of text you should switch
+to the appropriate mode. If you are working with C code, you should
+switch to C mode; if you are working with Lisp code, then switch to lisp
+mode and if you are working with English text switch to Text mode.
+
+   When you open a file to work on, Emacs usually selects the
+appropriate mode. For example, if you open a file called `guide.c' then
+Emacs will select the C mode because of the ".c" extension of the file.
+To explicitly select a mode type the following command:
+
+     ;;; selects lisp mode
+     M-x lisp-mode
+     
+     ;;; selects C mode
+     M-x c-mode
+
+To select any other mode, just add the major mode name before the
+'-mode'. The current mode in which you are in will be displayed in
+parenthesis in the mode-line at the bottom of the frame. All major
+modes have some special keybindings and you can get a listing of those
+keybindings by selecting List Keybindings from the Help menu on the
+menu bar.
+
+   Some of the available modes in XEmacs are :
+
+fundamental-mode
+     When you start XEmacs, usually you start with the default
+     "Fundamental" mode. This mode has no special definitions or
+     settings.
+
+nroff-mode
+     Use this mode when you have to format a text with nroff before it
+     can be available in readable form. It redefines some indentation
+     commands. *Note Nroff Mode: (xemacs)Nroff Mode, for information on
+     this mode.
+
+tex-mode
+     Use this mode if you are using the LaTeX text-formatter. It
+     provides commands for insertion of quotes, braces and other
+     characters. It also allows you to format the buffer for printing.
+     *Note TeX Mode: (xemacs)TeX Mode, for information on this mode.
+
+texinfo-mode
+     Texinfo is a documentation system that uses a single source file to
+     produce both printed output and on-line documentation. When you
+     use this mode, there will be some special keybindings for
+     inserting some characters and executing some commands.
+
+     This info file which you are reading right now is produced by
+     'Texinfo'
+
+outline-mode
+     Use this mode for editing outlines. When you enable this mode, you
+     can make part of the text temporarily invisible so that you can
+     see the overall structure of the outline. *Note Outline Mode:
+     (xemacs)Outline Mode, for information on this mode.
+
+c-mode
+     Use this mode for C programs. It will redefine some indentation
+     commands. *Note C Indent: (xemacs)C Indent.
+
+lisp-mode
+     Use this mode for Lisp programs. Look at the XEmacs User's Manual
+     for more information.
+
+fortran-mode
+     Use this mode for Fortran programs. This mode provides special
+     commands to move around and some other indentation commands.  For
+     more information on this mode, *Note Fortran: (xemacs)Fortran.
+
+edit-picture
+     This is the picture mode which you can use to create a picture out
+     of text characters. *Note Picture: (xemacs)Picture, for more
+     information.
+
+asm-mode
+     Use asm-mode for editing files of assembler code. Look at the file
+     ` /usr/local/lib/xemacs-VERSION/lisp/modes/asm.el' for more
+     information.
+
+
+   There are some other modes and commands for working with other kinds
+of text or programs. Emacs also provides commands for reading and
+sending Mail. For more information on these features look at the XEmacs
+Manual. Emacs also provides the functions of a desk calendar, with a
+diary of past or planned events. For more information on the calendar
+mode look at the manual for Calendar Mode and Diary.
+
+\1f
+File: new-users-guide.info,  Node: Minor Modes,  Prev: Major Modes,  Up: Modes
+
+Minor Modes
+===========
+
+The minor modes in Emacs provide some optional features which you can
+turn on or off. Any number of minor modes can be active at the same time
+with any major mode. You can enable a minor mode in one buffer and
+disable it in other mode. To enable a minor mode, for example the
+font-lock mode type the following command:
+
+     M-x font-lock-mode
+
+To enable the other minor modes, replace the "font-lock" with the name
+of the minor mode. To disable the mode type the command again. A
+positive argument will always turn the mode on. Whenever you type this
+command, it will turn the mode on if it was off, OR it will turn it off
+if it was on i.e. it toggles. Look at the mode-line at the bottom of the
+frame. If it says FLock in parentheses, then it means that this mode is
+on, otherwise it is off.
+
+   The following are some of the minor modes available in XEmacs. To
+enable any one of them type "M-x" in front of them.
+
+font-lock-mode
+     You can also choose this mode by selecting the Syntax Highlighting
+     menu item from the Options menu on the menu-bar at the top. If you
+     wish to have this mode enabled permanently, choose Save Options
+     from the Options menu. *Note Options Menu::, for more information
+     on the Options menu.  You can also add statements in your
+     `init.el' file. For each major mode in which you wish to enable
+     this minor mode, you need a statement in your `init.el' file. The
+     following example shows how to enable the font-lock mode when the
+     major mode is c-mode.
+
+          (add-hook 'c-mode-hook          'turn-on-font-lock)
+
+     *Note Other Customizations::.
+
+     When you enable this mode, the text will be displayed in different
+     colors and fonts depending on the type of the text. This makes the
+     text very easy to read and understand. For example, comments might
+     be displayed in red, variables in black, functions in blue and
+     other keywords in different colors and fonts. When you select More
+     from the Syntax Highlighting option, you get very detailed display
+     of colors and fonts; function names within comments themselves
+     might appear in a different font and color.
+
+auto-fill-mode
+     Enabling this mode will provide automatic word-wrapping. The <SPC>
+     key will break lines i.e. insert newlines as you type to prevent
+     lines from becoming too long.
+
+overwrite-mode
+     When you enable this mode, the text that you type will replace the
+     existing text rather than moving it to the right (the default
+     case). You can enable this mode by selecting Overstrike menu-item
+     from the Options menu from the menu-bar.
+
+abbrev-mode
+     After you enable this mode, you can define words which will expand
+     into some different text i.e. you can define abbreviations. For
+     example, you might define "expand" to "expand will eventually
+     expand to this text". After this definition you will be able to
+     get "expand will eventually expand to this text" simply by typing
+
+          expand <SPC>
+
+     *Note Abbrevs: (xemacs)Abbrevs, for more information on this mode
+     and on defining abbreviations.
+
+auto-save-mode
+     After you enable this mode in a buffer, the contents of that
+     buffer will be saved periodically. This will reduce the amount you
+     might lose in case of a system crash.
+
+line-number-mode
+     After you enable this mode, the line number at which your cursor is
+     present will be displayed continuously in the mode line.
+
+blink-paren
+     To enable this command, just type
+          M-x blink-paren
+
+     Do not add the "-mode" to it.  You can also select the Paren
+     Highlighting option from the Options menu. After you enable this
+     command, put your cursor on one of the left parenthesis. The other
+     matching parenthesis will start blinking. *Note Options Menu::,
+     for more information on the Paren Highlighting option.
+
+   For information on some other modes, look at the XEmacs User's Manual
+and the associated files.
+
+\1f
+File: new-users-guide.info,  Node: Files,  Next: Other Customizations,  Prev: Modes,  Up: Top
+
+Files
+*****
+
+The basic unit of stored data in Unix is the "file".  To edit a file,
+you must tell Emacs to read the file into a buffer. This is called
+"visiting" the file. You can now edit the buffer and to save the
+changes you must write the buffer back to the file.
+
+   In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, and operate on file directories.
+
+* Menu:
+
+* File Names::                  How to type and edit file name arguments.
+* Visiting::                    Visiting a file prepares Emacs to edit the file.
+* Saving Files::                How to save Emacs files.
+
+\1f
+File: new-users-guide.info,  Node: File Names,  Next: Visiting,  Prev: Files,  Up: Files
+
+File Names
+==========
+
+Most of the Emacs commands that operate on a file require you to
+specify a file name. For example, you might specify the file name
+initially when you enter Emacs :
+
+     xemacs myfile RET
+
+After you hit <RET>, you will enter XEmacs with "myfile" read into the
+current buffer. If you do not specify the filename when entering Emacs,
+you can use the Open... option from the File menu. You will be prompted
+for a filename in the echo area:
+
+     Find file: /usr/workspace/
+
+Type in a file name which you want to open after the "/" and hit <RET>.
+The specified file will be read into the current buffer. The
+"/usr/workspace" might be the "default directory". When Emacs prompts
+you for a file, it uses the default-directory unless you specify a
+directory. You can see what the default directory of the current buffer
+is by using the Describe Variable option from the Help menu. When Emacs
+prompts you for the variable name to describe, type
+`default-directory'. If you wish to open a file in some other
+directory, use <DEL> or the <BackSpace> key to go back and type the
+path name of the new directory.
+
+   You can create a new directory by typing `M-x make-directory'. This
+command will prompt you for a directory name:
+
+     Create directory: /usr/workspace/
+
+After you type a directory name and press <RET>, a new directory with
+the specified name will be created. If you do not wish to create a new
+directory, then simply press `C-g' to quit the command. Similarly, you
+can also remove a directory by using the command `remove-directory'.
+The command `M-x pwd' will print the current buffer's default
+directory. For more information on file names, *Note File Names:
+(xemacs)File Names.
+
+\1f
+File: new-users-guide.info,  Node: Visiting,  Next: Saving Files,  Prev: File Names,  Up: Files
+
+Visiting Files
+==============
+
+To edit a file in Emacs you need to "visit" it. "Visiting" a file means
+copying its contents (or reading them) into the current buffer. Emacs
+will create a new buffer for each file that you visit. The buffer will
+be named after the file that you open. If you open a file
+`/usr/workspace/myfile.texinfo', the buffer will be called
+"myfile.texinfo". If a buffer with this name already exists, a unique
+name will be constructed by appending `<2>', `<3>', etc. If this is the
+second buffer with the same name, a "<2>" will be appended, "<3>" for a
+third buffer and so on. The name of the buffer which is being displayed
+in the window will be shown both at the top and bottom of the frame.
+Once you are in XEmacs, you can use the following commands:
+
+`C-x C-f'
+     This command will visit a file (`find-file'). It will prompt you
+     for a file name to visit. The Open... option from the File menu
+     does the same thing:
+
+          Find file: /usr/workspace/
+
+     Type in a filename and press <RET>. You will see a new buffer on
+     the screen with its name in the mode-line. If the filename you
+     specify already exists in Emacs, the buffer containing that file
+     will be selected. You will get an error message if the filename
+     does not exist. If you still press <RET>, a new buffer with the
+     given filename will be displayed on the screen.
+
+`C-x C-v'
+     This command (`find-alternate-file'), will visit a different file
+     instead of the one visited last. It is similar to `C-c C-f' except
+     that it kills the current buffer (after offering to save it).
+
+`C-x 5 C-f'
+     This command will visit a file in another frame
+     (`find-file-other-frame') without changing the current window or
+     frame. The Open in New Frame... from the File menu will do the
+     same thing. It will prompt you for a file name in the echo area.
+     After you type the file name and press <RET>, the specified file
+     will be read into a new buffer and displayed on a new frame.
+
+\1f
+File: new-users-guide.info,  Node: Saving Files,  Prev: Visiting,  Up: Files
+
+Saving Files
+============
+
+The changes that you make after visiting a file will not be saved
+unless you save the buffer. When you save the buffer, Emacs writes the
+current contents of the buffer into the visited file. Some commands to
+save buffers are:
+
+`C-x C-s'
+     This command will permanently save the current buffer in its
+     visited file (`save-buffer'). You will see the following message
+     in the echo area if you save a file called "myfile.texinfo" :
+
+          Wrote /usr/workspace/myfile.texinfo
+
+     Try using this command twice. You will get the above message the
+     first time you use this command, the second time you will get the
+     following message:
+
+          (No changes need to be saved)
+
+     This message indicates that you haven't made any changes since the
+     last time you saved the file.
+
+`C-x s'
+     This command will save all the buffers in their visited files
+     (`save-some-buffers'). It will prompt you for typing yes or no:
+
+          Save file /usr/workspace/myfile.texinfo? (y or n)
+
+     You will get the above message for all the buffers. Type "y" if
+     you want to save the buffer.
+
+`C-x C-w'
+     This command will prompt you for a file name and save the current
+     buffer in that file. (`write-file'). You will see the following
+     message in the echo area:
+
+          Write file: /usr/workspace/
+
+     After you type in a file name, press <RET>. The buffer will be
+     saved in a new file. You can make copies of a particular file
+     using this command.
+
+   You can also undo all the changes made since the file was visited or
+saved by reading the text from the file again (called "reverting"). For
+more information on this option, *Note Reverting: (xemacs)Reverting.
+
+   When you save a file in Emacs, it destroys its old contents. However,
+if you set the variable `make-backup-files' to non-`nil' i.e. `t',
+Emacs will create a "backup" file. Select the Describe variable option
+from the Help menu and look at the documentation for this variable. Its
+default value should be `t'. However, if its not then use `M-x
+set-variable' to set it to `t' (*note Setting Variables::). The backup
+file will contain the contents from the last time you visited the file.
+Emacs also provides options for creating numbered backups. For more
+information on backups, *Note Backup: (xemacs)Backup.
+
+   Emacs also saves all the files from time to time so that in case of a
+system crash you don't lose lot of your work. You will see the message
+`Auto-saving...' displayed in the echo area when the buffer is being
+saved automatically. The auto saved files are named by putting the
+character `#' in front and back. For example a file called
+"myfile.texinfo" would be named as `#myfile.texinfo#'. For information
+on controlling auto-saving and recovering data from auto-saving, *Note
+Auto Save Files: (xemacs)Auto Save Files.
+
+   Emacs provides protection from simultaneous editing which occurs if
+two users are visiting the same file and trying to save their changes.
+It will put a lock on a file which is being visited and modified. If
+any other user tries to modify that file, it will inform the user about
+the lock and provide some options. For more information on protection
+against simultaneous editing, *Note Interlocking: (xemacs)Interlocking.
+
+\1f
+File: new-users-guide.info,  Node: Other Customizations,  Next: Select and Move,  Prev: Files,  Up: Top
+
+Other Customizations
+********************
+
+You can modify the behavior of Emacs in minor ways permanently by
+putting your changes in your `init.el' file. This file contains Lisp
+function call expressions. Each of these expressions will consist of a
+function name followed by arguments, all surrounded by parentheses. For
+example, to turn on the auto-fill-mode (i.e. break lines automatically
+when they become too long) , put the following  line in your `init.el'
+file:
+
+     (add-hook 'text-mode-hook
+             '(lambda() (auto-fill-mode 1)))
+
+Emacs has a function named "turn-on-auto-fill" which is defined as
+"(lambda() (auto-fill-mode 1))". Therefore you can also write the above
+as:
+
+     (add-hook 'text-mode-hook 'turn-on-auto-fill)
+
+Emacs provides a number of hooks for the sake of customization. The hook
+variables contain list of functions to be called with no arguments. To
+turn on the auto-fill-mode, add the appropriate hook as shown in the
+example above.
+
+   Similarly, to enable the "font-lock mode" which displays your
+program in different fonts and colors(*note Modes::), put the following
+in your `init.el' file. The comments above the statement explain what
+the statements do.
+
+     ;;; enables the font-lock-mode in Lisp Mode
+     (add-hook 'lisp-mode-hook    'turn-on-font-lock)
+     
+     ;;; enables the font-lock-mode in Texinfo Mode
+     (add-hook 'texinfo-mode-hook    'turn-on-font-lock)
+     
+     ;;; enables the font-lock mode in C Mode
+     (add-hook 'c-mode-hook          'turn-on-font-lock)
+
+   To turn on the font-lock mode in other Major Modes like emacs-lisp,
+just put the name of the mode with "-hook" appended to it as the middle
+parameter in the above examples. You can also select the color that the
+functions, comments or other keywords  should be displayed in :
+
+     ;;; the function names will now be displayed in blue color
+     (set-face-foreground 'font-lock-function-name-face "blue")
+     
+     ;;; the comments will be displayed in forest green
+      (set-face-foreground 'font-lock-comment-face "forest green")
+
+For other customizations regarding the font-lock face, look at the file
+`/usr/local/lib/xemacs-VERSION/etc/sample.init.el'.
+
+* Menu:
+
+* Setting Variables::           Customizing Emacs variables
+* Init File::                   Some examples of Lisp expressions in
+                                init.el file
+
+\1f
+File: new-users-guide.info,  Node: Setting Variables,  Next: Init File,  Prev: Other Customizations,  Up: Other Customizations
+
+Other Customizations
+====================
+
+In XEmacs, "variables" are used for internal record-keeping and
+customizations. There are some variables called "options" which you can
+use for customizations. To examine a variable use:
+
+     ;;; print the value and documentation of the variable, use either of the
+     ;;; following commands
+     C-h v
+     M-x describe variable
+
+   After you type any of the above commands, you will be prompted for a
+variable name in the "echo area". Type in the name of the variable, for
+example, type  `case-fold-search' <RET> Your window will split into two
+and you will see the following message in that window:
+
+     case-fold-search's value is t
+     This value is specific to the current buffer.
+     
+     Documentation:
+     *Non-nil if searches should ignore case.
+     Automatically becomes buffer-local when set in any fashion.
+
+Since this variable's value is 't' searches will ignore case. If you
+want case-sensitive-search (i.e. if you are searching for "Foo" and you
+do not want "foo" to be included in the search, you need to set this
+variable to "nil". In order to do that, use:
+
+     M-x set-variable
+
+Emacs will prompt you for the variable which you wish to set. Type in
+"case-fold-search" and hit <RET>. You will see the following message:
+
+     Set case-fold-search to value:
+
+Type "nil" and hit <RET>.  Now if you again use `M-x describe variable'
+, you will see that the new value of case-fold-search will be "nil" and
+your searches will be case-sensitive. This will be effective only for
+that Emacs session. If you want to change the value of a variable
+permanently put the following statement in your `init.el' file :
+
+     (setq case-fold-search nil)
+
+This statement will make searches case-sensitive only in the current
+buffer which is the `init.el' file. This will not be very useful. To
+make searches case-sensitive globally in all buffers, use:
+
+     (setq-default case-fold-search nil)
+
+   If you want to change the value of any other variable, use :
+
+     (setq <variable-name> <new value>)
+
+"setq" will assign the "new value" to the "variable-name" .
+
+   If you want a list of the "options" i.e. the variables available for
+customization type:
+
+
+     ;;; displays a buffer listing names, values and documentation of options
+     M-x list-options
+     
+     ;;; displays options and allows you to edit those list of options
+     M-x edit-options
+
+Try these options. If you are using edit-options to edit a variable,
+just point at the variable you wish to edit and use one of the following
+commands:
+
+1
+     Set the value of the variable to t (non-nil).
+
+0
+     Set the value of the variable to nil.
+
+n
+     Move to the next variable.
+
+p
+     Move to the previous variable.
+
+   There are some other options available to make the value of a
+variable local to a buffer and then to switch to its global value. You
+can also have a "local variables list" in a file which specifies the
+values to use for certain Emacs variables when you edit that file.
+*Note Variables: (xemacs)Variables, for information on these options.
+
+\1f
+File: new-users-guide.info,  Node: Init File,  Prev: Setting Variables,  Up: Other Customizations
+
+Init File Examples
+==================
+
+For customizing Emacs, you need to put Lisp expressions in your
+`init.el' file. The following are some useful Lisp expressions. If you
+find any of them useful, just type them in your `init.el' file:
+
+   * The following expression will make <TAB> in C mode insert a real
+     tab character if the cursor or point is in the middle of the line.
+     Now hitting the <TAB> key will indent a line only if the cursor is
+     at the left margin or in the line's indentation:
+
+          (setq c-tab-always-indent nil)
+
+     The value of the variable `c-tab-always-indent' is usually `t' for
+     `true'. When this variable is true, then hitting the <TAB> key
+     always indents the current line.
+
+   * This expression will turn on the AUTO-FILL-MODE when you are in
+     text mode:
+
+          (setq text-mode-hook 'turn-on-auto-fill)
+
+     This mode will automatically break lines when you type a space so
+     that the lines don't become too long. The length of the lines is
+     controlled by the variable `fill-column'. You can set this
+     variable to a value you wish. Look at the documentation for this
+     variable to see its default value. To change the value to 75 for
+     example, use:
+
+          (setq-default fill-column 75)
+
+     This will change the value of this variable globally.
+
+   * The following expression will enable the use of EVAL-EXPRESSION
+     without confirmation:
+
+          (put 'eval-expression 'disabled nil)
+
+     Now when you use EVAL-EXPRESSION, it will print the value of the
+     expression you specify in the "echo area" without confirming with
+     you.
+
+   * This expression will remove the binding of `C-x C-c', because its
+     easy to hit this key by mistake and you will exit Emacs
+     unintentionally. You can use the Exit Emacs option from the File
+     menu to exit Emacs.
+
+          (global-set-key "\C-x\C-c" nil)
+
+     Now if you type `C-x C-c', you won't exit Emacs.
+
+   * The following expression will make the <BACKSPACE> and the <DEL>
+     key work in the same manner:
+
+          (global-set-key 'backspace [delete])
+
+   * This expression will make searches case sensitive:
+
+          (setq-default case-fold-search nil)
+
+     If we use "setq" instead of "setq-default" then searches will be
+     case-sensitive only in the current buffer's local value. In this
+     case the buffer would be the `init.el' file. Since this would not
+     be too helpful and we want to have case-sensitive searches in all
+     buffers, we have to use "setq-default".
+
+   * This expression will enable the font-lock mode when you are using
+     texinfo mode:
+
+          (add-hook 'texinfo-mode-hook 'turn-on-font-lock)
+
+     *Note Minor Modes::, for information on font-lock mode.
+
+   * Rebinds the key `C-x l' to run the function `make-symbolic-link':
+
+          (global-set-key "\C-xl" 'make-symbolic-link)
+
+     We use the single quote before "make-symbolic-link" because its a
+     function name. You can also use the following expression which
+     does the same thing:
+
+          (define-key global-map "C-xl" 'make-symbolic-link)
+
+   * The following expression will bind `C-x l' to run the function
+     `make-symbolic-link' in C mode only:
+
+          (define-key c-mode-map "C-xl" 'make-symbolic-link)
+
+     Instead of binding `C-xl' to run `make-symbolic-link', you can
+     bind the <F1> key to run this function:
+
+          (define-key c-mode-map 'f1 'make-symbolic-link)
+
+     Here, you have to use lower case for naming function keys like
+     <F1>.
+
+   * You can bind the function `undo' i.e. `C-x u' to any key, for
+     example to <F2>:
+
+          (global-set-key 'f2 'undo)
+
+   * The following statement will display the current time in the
+     modeline of the buffer:
+
+          (display-time)
+
+   * This displays the current line number on which the cursor is
+     present in the modeline:
+
+          (setq line-number-mode t)
+
+   * If you don't want the text to be highlighted when you use commands
+     for marking regions so as to use the "kill" and "yank" commands
+     later, you can use the following expression in your `init.el' file:
+
+          (setq zmacs-regions nil)
+
+     Now if you use a command like `C-x C-p' (`mark-page'), the text
+     will not be highlighted.
+
+   * To control the number of buffers listed when you select the Buffers
+     menu, you need to set the variable `buffers-menu-max-size' to
+     whatever value you wish. For example, if you want 20 buffers to be
+     listed when you select Buffers use:
+
+          (setq buffers-menu-max-size 20)
+
+   * If you want the window title area to display the full
+     directory/name of the current buffer's file, and not just the
+     name, use:
+
+          (setq frame-title-format "%S: %f")
+
+   * To get rid of the menu, use :
+
+          (set-menubar nil)
+
+   * If you want an extensive menu-bar use the following expression in
+     your `init.el' file.
+
+          (load "big-menubar")
+
+     If you want to write your own menus, you can look at some of the
+     examples in
+     `/usr/local/lib/xemacs/xemacs-packages/lisp/edit-utils/big-menubar.el'
+     file.
+
+
+   For more information on initializing your `init.el' file, *Note Init
+File: (xemacs)Init File. You should also look at
+`/usr/local/lib/xemacs-VERSION/etc/sample.init.el', which is a sample
+`init.el' file. It contains some of the commonly desired customizations
+in Emacs.
+
+\1f
+File: new-users-guide.info,  Node: Select and Move,  Next: Search and Replace,  Prev: Other Customizations,  Up: Top
+
+Selecting and Moving Text
+*************************
+
+Many Emacs commands operate on an arbitrary contiguous part of the
+current buffer. You can select some part of the buffer and edit only
+that part of the buffer. This selected buffer is called a "region". You
+can select text in two ways:
+
+   * You use special keys to select text by defining a region between
+     the cursor and "the mark" (which you set).
+
+   * If you are running XEmacs under X, you can also select text with
+     the mouse.
+
+* Menu:
+
+* Selecting Text::              Select a region of text by setting the Mark
+* Mouse::                       Selecting Text with Mouse
+* Region Operation::            Various ways to operate on a selected text
+* Moving Text::                 Moving Text
+* Accumulating text::           Accumulating Text from several buffers
+
+\1f
+File: new-users-guide.info,  Node: Selecting Text,  Next: Mouse,  Prev: Select and Move,  Up: Select and Move
+
+Setting the Mark
+================
+
+To define a region you need to set "the mark" at one end of it and move
+the cursor to the other end. Once you set the mark, it remains there
+until you set it again to some other place. Each buffer has its own
+"mark ring" (a place where Emacs remembers 16 previous locations of the
+mark). To set "the mark", you can use the following commands:
+
+`C-<SPC>'
+     This command will set "the mark" at the position of your cursor
+     (`set-mark-command').  You can move your cursor around and "the
+     mark" will stay there.
+
+`C-x C-x'
+     Interchange mark and point (`exchange-point-and-mark'). Since Emacs
+     will have only one cursor, after you move the cursor it will be
+     unable to show you where you set the "the mark". In order to see
+     "the mark" you can type the command `C-x C-x' which will put your
+     cursor on the position of your mark and your mark on the position
+     of your cursor. Use the command again to reset the positions of
+     your cursor and mark.
+
+`C-<'
+     This command will push the mark at the beginning of the buffer
+     without changing the position of your cursor.
+
+`C->'
+     This command will push the mark at the end of the buffer without
+     changing the position of your cursor.
+
+You can also give arguments to `C-<' or `C->'. *Note The Mark and the
+Region: (xemacs)The Mark and the Region, for more information.
+
+\1f
+File: new-users-guide.info,  Node: Mouse,  Next: Region Operation,  Prev: Selecting Text,  Up: Select and Move
+
+Selecting Text with Mouse
+=========================
+
+If you are using XEmacs under X, you can use the mouse to select text.
+The selected text will always be highlighted, so just by looking at the
+text you know what you have selected so far. To select a word just
+double-click with the left-mouse-button on the word. To select a whole
+line triple-click anywhere on the line with the left-mouse-button. You
+can also use the Copy item from the Edit menu on the menu-bar to select
+text. This kind of selection is called Clipboard selection, *Note X
+Clipboard Selection: (xemacs)X Clipboard Selection, for more
+information. To select an arbitrary region, follow these steps:
+
+  1. Move the mouse cursor over the character at the beginning of the
+     region of text you want to select.
+
+  2. Press and hold the left mouse button.
+
+  3. While holding the left mouse button down, drag the cursor to the
+     character at the end of the region of text you want to select.
+
+  4. Release the left mouse button.
+        The selected region of text is highlighted.
+
+   *Note Selecting Text with the Mouse: (xemacs)Selecting Text with the
+Mouse, for more information regarding the Mouse and additional mouse
+operations.
+
+\1f
+File: new-users-guide.info,  Node: Region Operation,  Next: Moving Text,  Prev: Mouse,  Up: Select and Move
+
+Operating on the Region
+=======================
+
+Once you have selected a region you can do a lot of things to the text
+in the region:
+   * Kill the text with `C-w'. For example if you want to kill a
+     paragraph, position the cursor to the beginning of the paragraph
+     and type `C-SPC'. Then go to the end of the paragraph and type
+     `C-w'. The entire paragraph will be deleted. You can also select
+     the text with a mouse and type `C-w' to kill the entire region.
+     *Note Killing: (xemacs)Killing, for more information.
+
+   * Save the text in a buffer or a file (*note Accumulating Text:
+     (xemacs)Accumulating Text.).
+
+   * You can convert the case of the text with `C-x C-l' or `C-x C-u'
+     If you type `C-x C-u' the selected text will become all
+     upper-case. If you type `C-x C-l' the selected text will become all
+     lower-case.
+
+   * Print hardcopy with `M-x print-region'. *Note Hardcopy:
+     (xemacs)Hardcopy, for more information. This command will print a
+     hardcopy of only the selected text.
+
+   * Indent it with `C-x <TAB>' or `C-M-\' *Note Indentation:
+     (xemacs)Indentation, for more information.
+
+\1f
+File: new-users-guide.info,  Node: Moving Text,  Next: Accumulating text,  Prev: Region Operation,  Up: Select and Move
+
+Moving Text
+===========
+
+The most common way to move or copy text in Emacs is through "killing"
+or `cutting' it and then "yanking" or `pasting' it. You can also use
+the Cut or Copy option from the Edit menu for killing and copying
+respectively. *Note Edit menu::, for reviewing the commands for killing
+text. All the killed text in Emacs is recorded in the "kill ring".
+Since there is only one kill ring in Emacs, you can kill text in one
+buffer and yank it in another buffer. To `paste' or `yank' the killed
+text you can use the following commands:
+`C-y'
+     This command will yank or paste the last killed text (`yank').
+
+`M-w'
+     Save region as last killed text without actually killing it
+     (`copy-region-as-kill'). You can use this command to copy a
+     selected region and then yank (or paste) it without actually
+     removing it from the buffer.
+
+`C-M-w'
+     Append next kill to last batch of killed text
+     (`append-next-kill'). This command will append whatever you killed
+     last to what you kill now. Then later you will be able to yank the
+     entire appended text from the "kill ring".
+
+\1f
+File: new-users-guide.info,  Node: Accumulating text,  Prev: Moving Text,  Up: Select and Move
+
+Accumulating Text
+=================
+
+The following commands can be used for accumulating text from different
+buffers into one place or for copying one region of text into many
+buffers:
+
+`M-x append-to-buffer'
+     Append region to contents of specified buffer
+     (`append-to-buffer'). After you type in this command and press
+     <RET>, Emacs will prompt you for a buffer name. You will see a
+     message in the echo area:
+          Append to buffer: (default <buffer name>)
+
+     After you type in a buffer name, a copy of the region will be
+     inserted at the location of the cursor into that buffer. If there
+     is no buffer with the name given by you, Emacs will create a new
+     buffer with that name. By default the cursor's position in the
+     <buffer name> is at the end.
+
+`M-x prepend-to-buffer'
+     Prepend region to contents of specified buffer. This command is
+     similar to the above command except that the cursor in the buffer
+     (by default) is at the beginning rather than at the end.
+
+`M-x copy-to-buffer'
+     Copy region into specified buffer, deleting that buffer's old
+     contents. This command will also prompt you for a buffer name.
+
+`M-x insert-buffer'
+     Insert contents of specified buffer into current buffer at point.
+     This command will prompt you for a buffer name which you want to
+     be copied into the current buffer at the location of the cursor.
+
+`M-x append-to-file'
+     This command will prompt you for a filename and append the region
+     to the end of the contents of the specified file.
+
+*Note Accumulating Text: (xemacs)Accumulating Text, for more
+information regarding this topic.
+
+   You can also use "rectangle commands" for operating on rectangular
+areas of text. *Note Rectangles: (xemacs)Rectangles, for more
+information regarding rectangle commands.
+
+   Emacs also provides "registers" which serve as temporary storage for
+text or positions. Each register has a one character name and they can
+store "regions", a "rectangle", or a "mark" i.e. a cursor position.
+Whatever you store in register stays there until you store something
+else in that register. To find out about commands which manipulate
+registers *Note Registers: (xemacs)Registers.
+
+\1f
+File: new-users-guide.info,  Node: Search and Replace,  Prev: Select and Move,  Up: Top
+
+Searching and Replacing
+***********************
+
+Emacs provides commands for searching for occurrences of a particular
+string. The search is incremental i.e. it begins even before you
+complete typing the whole string. All searches in Emacs ignore the case
+of the text they are searching, i.e. if you are searching for "String",
+then "string" will also be one of the selections. If you want a case
+sensitive search select the Case Sensitive Search from the Option menu.
+You can also set the variable `case-fold-search' to `nil' for making
+searches case-sensitive. For information on setting variables, *Note
+Setting Variables::. The two commands for searching for strings in
+XEmacs are:
+
+`C-s'
+     This command will prompt you for a string to search :
+
+          I-search:
+
+     If you type "myname" as the string to be searched, then Emacs will
+     start searching for "m", "my", "myn", etc as you go on typing the
+     whole string in the forward direction. The cursor will be on the
+     matching string which has been found so far. If you find the
+     correct match just hit <RET> or type `C-f' or `C-b' to set the
+     cursor's position. If you find a matching string "myname" but you
+     were looking for a different occurrence of it, use `C-s' again. If
+     the search is unable to find the string, it will give you an error
+     message.
+
+`C-r'
+     This command will perform an incremental search in the backward
+     direction. It will prompt you for a string name:
+
+          I-search backward:
+
+     After you start typing the string name, it will search for the
+     string in the same fashion as it does for `C-s' except that it
+     will search in the backward direction. If it cannot find the
+     string name, it will give you an error message.
+
+   If you make a mistake while typing the string names when you use the
+above commands, you can use the <DEL> key to erase characters. Each
+<DEL> will erase the last character. At any time if you want to quit
+the search, just type `C-g'.
+
+   To do a non-incremental search i.e. to start the search only after
+you have typed the whole string you can use the following commands:
+
+`C-s RET "string" RET'
+     This command will search for the specified string in the forward
+     direction and will give an error message if the string is not
+     found.
+
+`C-r RET "string" RET'
+     This command will search for the specified string in the backward
+     direction.
+
+   For information on how Emacs searches for words and regular
+expressions, *Note Search: (xemacs)Search.
+
+   To replace all occurrences of a string in Emacs, you can use the
+following command:
+     M-x replace-string
+
+After you type `M-x replace-string', you will be prompted for a string
+name to replace:
+
+     Replace string:
+
+After you type in a string name, for example "FOO" and press <RET>, you
+will see another prompt:
+
+     Replace string FOO with:
+
+Now type the string which you want to replace "FOO" with and press
+<RET>. After all the occurrences are replaced you will see the message
+"Done" in the echo area.  If you want only some occurrences of the
+string to be replaced, use `M-x query-replace RET <string> RET
+<newstring> RET'. For more information, *Note Query Replace:
+(xemacs)Query Replace.
+
+   XEmacs also provides a utility for checking spellings. Use `M-x
+ispell-buffer' to check for spellings in the whole buffer. You can also
+check the spelling of a word or a region. You can use menus to check
+for spellings:
+
+Evaluate the expression `(load "big-menubar")'. To evaluate this
+expression you need to hit the <META> or the <ESC> key twice and type
+in the expression in the echo area before hitting <RET>. You will get
+an extensive menubar. Select the Spell Check menu item from the
+Utilities menu for checking spellings.
+
+\1f
+File: new-users-guide.info,  Node: Key Index,  Next: Command Index,  Prev: Intro,  Up: Top
+
+Key (Character) Index
+*********************
+
+* Menu:
+
+* C-<:                                   Selecting Text.
+* C->:                                   Selecting Text.
+* C-a:                                   Cursor Position.
+* C-b:                                   Cursor Position.
+* C-d:                                   Erase.
+* C-e:                                   Cursor Position.
+* C-fx:                                  Cursor Position.
+* C-g:                                   The Help Menu.
+* C-h d:                                 The Help Menu.
+* C-h k:                                 The Help Menu.
+* C-h t:                                 Edit.
+* C-k:                                   Erase.
+* C-M-\:                                 Region Operation.
+* C-n:                                   Cursor Position.
+* C-p:                                   Cursor Position.
+* C-r:                                   Search and Replace.
+* C-s:                                   Search and Replace.
+* C-SPC <1>:                             Region Operation.
+* C-SPC:                                 Selecting Text.
+* C-t:                                   Cursor Position.
+* C-u:                                   Numeric Argument.
+* C-v:                                   Cursor Position.
+* C-w:                                   Region Operation.
+* C-x 0:                                 XEmacs Window.
+* C-x 1:                                 XEmacs Window.
+* C-x 2:                                 XEmacs Window.
+* C-x 3:                                 XEmacs Window.
+* C-x 4:                                 XEmacs Window.
+* C-x 4 b:                               XEmacs Window.
+* C-x 4 d:                               XEmacs Window.
+* C-x 4 f:                               XEmacs Window.
+* C-x 4 m:                               XEmacs Window.
+* C-x 5 C-f:                             Visiting.
+* C-x C-c:                               Exiting.
+* C-x C-f:                               Visiting.
+* C-x C-l:                               Region Operation.
+* C-x C-s:                               Saving Files.
+* C-x C-u:                               Region Operation.
+* C-x C-v:                               Visiting.
+* C-x C-w:                               Saving Files.
+* C-x C-x:                               Selecting Text.
+* C-x s:                                 Saving Files.
+* C-x TAB:                               Region Operation.
+* C-x u:                                 Undo.
+* C-y:                                   Moving Text.
+* C-z:                                   Exiting.
+* DEL:                                   Insert.
+* M--:                                   Numeric Argument.
+* M-<:                                   Cursor Position.
+* M->:                                   Cursor Position.
+* M-C-v:                                 XEmacs Window.
+* M-d:                                   Erase.
+* M-DEL:                                 Erase.
+* M-k:                                   Erase.
+* M-v:                                   Cursor Position.
+* M-z:                                   Erase.
+* RET:                                   Insert.
+
+\1f
+File: new-users-guide.info,  Node: Command Index,  Next: Variable Index,  Prev: Key Index,  Up: Top
+
+Command and Function Index
+**************************
+
+* Menu:
+
+* add-menu-item:                         Customizing Menus.
+* append-to-buffer:                      Accumulating text.
+* append-to-file:                        Accumulating text.
+* auto-fill-mode <1>:                    Minor Modes.
+* auto-fill-mode:                        Insert.
+* backward-char:                         Cursor Position.
+* backward-kill-word:                    Erase.
+* backward-word:                         Cursor Position.
+* beginning-of-buffer:                   Cursor Position.
+* beginning-of-line:                     Cursor Position.
+* copy-to-buffer:                        Accumulating text.
+* delete-backward-char:                  Erase.
+* delete-char:                           Erase.
+* delete-menu-item:                      Customizing Menus.
+* delete-other-windows <1>:              XEmacs Window.
+* delete-other-windows:                  Windows and Menus.
+* delete-window <1>:                     XEmacs Window.
+* delete-window:                         Windows and Menus.
+* describe-variable:                     Setting Variables.
+* dired-other-window:                    XEmacs Window.
+* disable-menu-item:                     Customizing Menus.
+* edit-options:                          Setting Variables.
+* enable-menu-item:                      Customizing Menus.
+* end-of-buffer:                         Cursor Position.
+* end-of-line:                           Cursor Position.
+* eval-expression:                       Init File.
+* eval-region:                           Customization Basics.
+* exchange-point-and-mark:               Selecting Text.
+* find-alternate-file:                   Visiting.
+* find-file:                             Visiting.
+* find-file-other-frame:                 Visiting.
+* find-file-other-window:                XEmacs Window.
+* forward-char:                          Cursor Position.
+* forward-word:                          Cursor Position.
+* goto-char:                             Cursor Position.
+* goto-line:                             Cursor Position.
+* help-with-tutorial:                    Edit.
+* isearch-backward:                      Search and Replace.
+* isearch-forward:                       Search and Replace.
+* kill-line:                             Erase.
+* kill-sentence:                         Erase.
+* kill-word:                             Erase.
+* list-options:                          Setting Variables.
+* mail-other-window:                     XEmacs Window.
+* make-directory:                        File Names.
+* make-symbolic-link:                    Customizing key Bindings.
+* mark-beginning-of-buffer:              Selecting Text.
+* mark-end-of-buffer:                    Selecting Text.
+* next-line:                             Cursor Position.
+* prepend-to-buffer:                     Accumulating text.
+* previous-line:                         Cursor Position.
+* print-region:                          Region Operation.
+* relabel-menu-items:                    Customizing Menus.
+* remove-directory:                      File Names.
+* replace-string:                        Search and Replace.
+* save-buffer:                           Saving Files.
+* save-buffers-kill-emacs:               Exiting.
+* save-some-buffers:                     Saving Files.
+* scroll-other-window <1>:               XEmacs Window.
+* scroll-other-window:                   Windows and Menus.
+* set-mark-command:                      Selecting Text.
+* set-variable:                          Setting Variables.
+* split-window-horizontally:             XEmacs Window.
+* split-window-vertically:               XEmacs Window.
+* suspend-emacs:                         Exiting.
+* switch-to-buffer-other-window:         XEmacs Window.
+* transpose-chars:                       Cursor Position.
+* write file:                            Saving Files.
+* yank:                                  Moving Text.
+* zap-to-char:                           Erase.
+
+\1f
+File: new-users-guide.info,  Node: Variable Index,  Next: Concept Index,  Prev: Command Index,  Up: Top
+
+Variable Index
+**************
+
+* Menu:
+
+* buffers-menu-max-size:                 Init File.
+* case-fold-search:                      Search and Replace.
+* default-directory:                     File Names.
+* display-time:                          Init File.
+* fill-column:                           Init File.
+* frame-title-format:                    Init File.
+* make-backup-files:                     Saving Files.
+* zmacs-regions:                         Init File.
+
+\1f
+File: new-users-guide.info,  Node: Concept Index,  Next: Entering,  Prev: Variable Index,  Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* abbrev-mode:                           Minor Modes.
+* accumulating text:                     Accumulating text.
+* add menus:                             Customizing Menus.
+* asm-mode:                              Major Modes.
+* Auto Delete Selection menu item:       Options Menu.
+* auto saving:                           Saving Files.
+* auto-save-mode:                        Minor Modes.
+* binding keys:                          Customizing key Bindings.
+* blink-paren:                           Minor Modes.
+* buffer:                                Entering.
+* Buffers menu:                          Buffers Menu.
+* Buffers Menu Length... menu item:      Options Menu.
+* Buffers Sub-Menus menu item:           Options Menu.
+* c-mode:                                Major Modes.
+* Case Sensitive Search menu item:       Options Menu.
+* Clear menu item:                       Edit menu.
+* clipboard selection:                   Mouse.
+* Copy menu item:                        Edit menu.
+* copying text:                          Accumulating text.
+* creating-directories:                  File Names.
+* cursor control:                        Cursor Position.
+* cursor position:                       Cursor Position.
+* cursor shapes:                         Mouse.
+* customize <1>:                         Other Customizations.
+* customize:                             Customization Basics.
+* customize menus:                       Customizing Menus.
+* Cut menu item:                         Edit menu.
+* Delete Frame menu item:                File menu.
+* delete menus:                          Customizing Menus.
+* deleting:                              Erase.
+* deleting menu items:                   Customizing Menus.
+* deletion:                              Insert.
+* digit argument:                        Numeric Argument.
+* disable menus:                         Customizing Menus.
+* disabling menu items:                  Customizing Menus.
+* displaying time:                       Init File.
+* echo area:                             Echo Area.
+* edit-picture:                          Major Modes.
+* enabling menu items:                   Customizing Menus.
+* End Macro Recording menu item:         Edit menu.
+* entering Emacs:                        Enter.
+* entering XEmacs:                       Enter.
+* erasing:                               Erase.
+* Execute Last Macro menu item:          Edit menu.
+* Exit Emacs menu item:                  File menu.
+* exiting:                               Exiting.
+* file:                                  Entering.
+* File menu:                             File menu.
+* file names:                            File Names.
+* files:                                 Files.
+* Font menu item:                        Options Menu.
+* font-lock-mode <1>:                    Other Customizations.
+* font-lock-mode:                        Minor Modes.
+* fortran-mode:                          Major Modes.
+* fundamental-mode:                      Major Modes.
+* goto-line:                             Cursor Position.
+* help <1>:                              The Help Menu.
+* help:                                  Help.
+* Help menu:                             Help menu.
+* hook:                                  Other Customizations.
+* init file examples:                    Init File.
+* init.el:                               Customization Basics.
+* Insert File... menu item:              File menu.
+* insertion:                             Insert.
+* key bindings:                          Customizing key Bindings.
+* keystrokes:                            Customizing key Bindings.
+* Kill Buffer menu item:                 File menu.
+* kill ring:                             Moving Text.
+* killing:                               Moving Text.
+* killing Emacs:                         Exiting.
+* line-number-mode:                      Minor Modes.
+* lisp-mode:                             Major Modes.
+* major modes:                           Major Modes.
+* mark:                                  Select and Move.
+* menus:                                 XEmacs Window.
+* minor modes:                           Minor Modes.
+* mistakes, correcting:                  Undo.
+* mode line:                             Mode Line.
+* modes:                                 Modes.
+* mouse selection:                       Mouse.
+* moving text:                           Moving Text.
+* negative argument:                     Numeric Argument.
+* New Frame menu item:                   File menu.
+* newline:                               Insert.
+* nroff-mode:                            Major Modes.
+* numeric argument:                      Numeric Argument.
+* Open ... menu item:                    File menu.
+* open another file:                     Frame.
+* Open in New Frame... menu item:        File menu.
+* Options menu:                          Options Menu.
+* outline-mode:                          Major Modes.
+* overstrike:                            Insert.
+* Overstrike menu item:                  Options Menu.
+* overwrite-mode:                        Minor Modes.
+* Paren Highlighting menu item:          Options Menu.
+* Paste menu item:                       Edit menu.
+* pasting:                               Moving Text.
+* primary selection:                     Mouse.
+* Print Buffer menu item:                File menu.
+* pull-down-menus:                       XEmacs Window.
+* Read Only menu item:                   Options Menu.
+* rectangle commands:                    Accumulating text.
+* region:                                Select and Move.
+* registers:                             Accumulating text.
+* relabelling menu items:                Customizing Menus.
+* removing-directories:                  File Names.
+* replace:                               Search and Replace.
+* Revert Buffer menu item:               File menu.
+* Save Buffer As ... menu item:          File menu.
+* Save Buffer menu item:                 File menu.
+* Save Options:                          Options Menu.
+* saving files:                          Saving Files.
+* searching:                             Search and Replace.
+* selected window:                       Windows and Menus.
+* setting variables:                     Setting Variables.
+* shrinking XEmacs frame:                Exiting.
+* simultaneous editing:                  Saving Files.
+* Size menu item:                        Options Menu.
+* Split Frame:                           File menu.
+* Start Macro Recording menu item:       Edit menu.
+* suspending:                            Exiting.
+* Syntax Highlighting menu item:         Options Menu.
+* Teach Extended Commands menu item:     Options Menu.
+* temporary storage:                     Accumulating text.
+* tex-mode:                              Major Modes.
+* texinfo-mode:                          Major Modes.
+* top level:                             Mode Line.
+* Un-split (Keep Others):                File menu.
+* Un-split (Keep This):                  File menu.
+* undo:                                  Undo.
+* Undo menu item:                        Edit menu.
+* visiting files:                        Visiting.
+* Weight menu item:                      Options Menu.
+* windows <1>:                           XEmacs Window.
+* windows <2>:                           Windows and Menus.
+* windows:                               Entering.
+* yanking:                               Moving Text.
+
+

 \1f
 Tag Table:
 \1f
 Tag Table:

-(Indirect)

 Node: Top\7f635
 Node: Top\7f635

-Node: Intro\7f4613
-Node: Entering\7f7196
-Node: Enter\7f8710
-Node: Frame\7f9392
-Node: Exiting\7f11061
-Node: Mode Line\7f12261
-Node: Echo Area\7f14408
-Node: Windows and Menus\7f15763
-Node: XEmacs Window\7f16216
-Node: Pull-down Menus\7f19837
-Node: File menu\7f20716
-Node: Edit menu\7f23975
-Node: Options Menu\7f26501
-Node: Buffers Menu\7f31286
-Node: Help menu\7f31672
-Node: Edit\7f32170
-Node: Insert\7f33764
-Node: Cursor Position\7f35092
-Node: Erase\7f37163
-Node: Numeric Argument\7f38317
-Node: Undo\7f39501
-Node: Customization Basics\7f40264
-Node: Customizing key Bindings\7f41536
-Node: Customizing Menus\7f45030
-Node: Help\7f50520
-Node: The Help Menu\7f51208
-Node: Modes\7f56174
-Node: Major Modes\7f57090
-Node: Minor Modes\7f61041
-Node: Files\7f65138
-Node: File Names\7f65860
-Node: Visiting\7f67663
-Node: Saving Files\7f69787
-Node: Other Customizations\7f73166
-Node: Setting Variables\7f75650
-Node: Init File\7f78861
-Node: Select and Move\7f84346
-Node: Selecting Text\7f85300
-Node: Mouse\7f86813
-Node: Region Operation\7f88138
-Node: Moving Text\7f89398
-Node: Accumulating text\7f90638
-Node: Search and Replace\7f92959
-Node: Key Index\7f96825
-Node: Command Index\7f100114
-Node: Variable Index\7f104216
-Node: Concept Index\7f104793
+Node: Intro\7f4610
+Node: Entering\7f7190
+Node: Enter\7f8701
+Node: Frame\7f9380
+Node: Exiting\7f11046
+Node: Mode Line\7f12243
+Node: Echo Area\7f14387
+Node: Windows and Menus\7f15739
+Node: XEmacs Window\7f16189
+Node: Pull-down Menus\7f19807
+Node: File menu\7f20683
+Node: Edit menu\7f23940
+Node: Options Menu\7f26463
+Node: Buffers Menu\7f31245
+Node: Help menu\7f31628
+Node: Edit\7f32123
+Node: Insert\7f33714
+Node: Cursor Position\7f35039
+Node: Erase\7f37108
+Node: Numeric Argument\7f38262
+Node: Undo\7f39443
+Node: Customization Basics\7f40203
+Node: Customizing key Bindings\7f41472
+Node: Customizing Menus\7f44964
+Node: Help\7f50451
+Node: The Help Menu\7f51136
+Node: Modes\7f56100
+Node: Major Modes\7f57013
+Node: Minor Modes\7f60962
+Node: Files\7f65056
+Node: File Names\7f65775
+Node: Visiting\7f67577
+Node: Saving Files\7f69698
+Node: Other Customizations\7f73076
+Node: Setting Variables\7f75557
+Node: Init File\7f78767
+Node: Select and Move\7f84270
+Node: Selecting Text\7f85221
+Node: Mouse\7f86731
+Node: Region Operation\7f88053
+Node: Moving Text\7f89310
+Node: Accumulating text\7f90547
+Node: Search and Replace\7f92865
+Node: Key Index\7f96730
+Node: Command Index\7f100019
+Node: Variable Index\7f104121
+Node: Concept Index\7f104698

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

diff --git a/info/standards.info b/info/standards.info
index d7b69eb..8574d8f 100644 (file)
--- a/info/standards.info
+++ b/info/standards.info
@@ -1,4 +1,4 @@
-This is ../info/standards.info, produced by makeinfo version 4.0 from
+This is ../info/standards.info, produced by makeinfo version 4.6 from

 standards.texi.
 
 START-INFO-DIR-ENTRY
 standards.texi.
 
 START-INFO-DIR-ENTRY

@@ -23,73 +23,4403 @@ versions, except that this permission notice may be stated in a
 translation approved by the Free Software Foundation.
 
 \1f
 translation approved by the Free Software Foundation.
 
 \1f

-Indirect:
-standards.info-1: 980
-standards.info-2: 50916
-standards.info-3: 100599
-standards.info-4: 150168
+File: standards.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
+
+Version
+*******
+
+Last updated February 21, 2001.
+
+* Menu:
+
+* Preface::                 About the GNU Coding Standards
+* Legal Issues::            Keeping Free Software Free
+* Design Advice::           General Program Design
+* Program Behavior::        Program Behavior for All Programs
+* Writing C::               Making The Best Use of C
+* Documentation::           Documenting Programs
+* Managing Releases::       The Release Process
+* References::              References to Non-Free Software or Documentation
+* Index::
+
+\1f
+File: standards.info,  Node: Preface,  Next: Legal Issues,  Prev: Top,  Up: Top
+
+About the GNU Coding Standards
+******************************
+
+The GNU Coding Standards were written by Richard Stallman and other GNU
+Project volunteers.  Their purpose is to make the GNU system clean,
+consistent, and easy to install.  This document can also be read as a
+guide to writing portable, robust and reliable programs.  It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language.  The rules often
+state reasons for writing in a certain way.
+
+   Corrections or suggestions for this document should be sent to
+<bug-standards@gnu.org>.  If you make a suggestion, please include a
+suggested new wording for it; our time is limited.  We prefer a context
+diff to the `standards.texi' or `make-stds.texi' files, but if you
+don't have those files, please mail your suggestion anyway.
+
+   This release of the GNU Coding Standards was last updated February
+21, 2001.
+
+   If you did not obtain this file directly from the GNU project and
+recently, please check for a newer version.  You can ftp the GNU Coding
+Standards from any GNU FTP host in the directory `/pub/gnu/standards/'.
+The GNU Coding Standards are available there in several different
+formats: `standards.text', `standards.texi', `standards.info', and
+`standards.dvi'.  The GNU Coding Standards are also available on the
+GNU World Wide Web server: `http://www.gnu.org/prep/standards_toc.html'.
+
+\1f
+File: standards.info,  Node: Legal Issues,  Next: Design Advice,  Prev: Preface,  Up: Top
+
+Keeping Free Software Free
+**************************
+
+This node discusses how you can make sure that GNU software avoids
+legal difficulties, and other related issues.
+
+* Menu:
+
+* Reading Non-Free Code::       Referring to Proprietary Programs
+* Contributions::               Accepting Contributions
+* Trademarks::                  How We Deal with Trademark Issues
+
+\1f
+File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Up: Legal Issues
+
+Referring to Proprietary Programs
+=================================
+
+Don't in any circumstances refer to Unix source code for or during your
+work on GNU!  (Or to any other proprietary programs.)
+
+   If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+   For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different.  You could keep the entire input file in core and scan it
+there instead of using stdio.  Use a smarter algorithm discovered more
+recently than the Unix program.  Eliminate use of temporary files.  Do
+it in one pass instead of two (we did this in the assembler).
+
+   Or, on the contrary, emphasize simplicity instead of speed.  For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+   Or go for generality.  For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead.  Make sure your program handles NULs and
+other funny characters in the input files.  Add a programming language
+for extensibility and write part of the program in that language.
+
+   Or turn some parts of the program into independently usable
+libraries.  Or use a simple garbage collector instead of tracking
+precisely when to free memory, or use a new GNU facility such as
+obstacks.
+
+\1f
+File: standards.info,  Node: Contributions,  Next: Trademarks,  Prev: Reading Non-Free Code,  Up: Legal Issues
+
+Accepting Contributions
+=======================
+
+If the program you are working on is copyrighted by the Free Software
+Foundation, then when someone else sends you a piece of code to add to
+the program, we need legal papers to use it--just as we asked you to
+sign papers initially.  _Each_ person who makes a nontrivial
+contribution to a program must sign some sort of legal papers in order
+for us to have clear title to the program; the main author alone is not
+enough.
+
+   So, before adding in any contributions from other people, please tell
+us, so we can arrange to get the papers.  Then wait until we tell you
+that we have received the signed papers, before you actually use the
+contribution.
+
+   This applies both before you release the program and afterward.  If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for that change.
+
+   This also applies to comments and documentation files.  For copyright
+law, comments and code are just text.  Copyright applies to all kinds of
+text, so we need legal papers for all kinds.
+
+   We know it is frustrating to ask for legal papers; it's frustrating
+for us as well.  But if you don't wait, you are going out on a limb--for
+example, what if the contributor's employer won't sign a disclaimer?
+You might have to take that code out again!
+
+   You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes.  Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use.  For example, if someone send you one implementation, but
+you write a different implementation of the same idea, you don't need to
+get papers.
+
+   The very worst thing is if you forget to tell us about the other
+contributor.  We could be very embarrassed in court some day as a
+result.
+
+   We have more detailed advice for maintainers of programs; if you have
+reached the stage of actually maintaining a program for GNU (whether
+released or not), please ask us for a copy.
+
+\1f
+File: standards.info,  Node: Trademarks,  Prev: Contributions,  Up: Legal Issues
+
+Trademarks
+==========
+
+Please do not include any trademark acknowledgements in GNU software
+packages or documentation.
+
+   Trademark acknowledgements are the statements that such-and-such is a
+trademark of so-and-so.  The GNU Project has no objection to the basic
+idea of trademarks, but these acknowledgements feel like kowtowing, so
+we don't use them.  There is no legal requirement for them.
+
+   What is legally required, as regards other people's trademarks, is to
+avoid using them in ways which a reader might read as naming or labeling
+our own programs or activities.  For example, since "Objective C" is
+(or at least was) a trademark, we made sure to say that we provide a
+"compiler for the Objective C language" rather than an "Objective C
+compiler".  The latter is meant to be short for the former, but it does
+not explicitly state the relationship, so it could be misinterpreted as
+using "Objective C" as a label for the compiler rather than for the
+language.
+
+\1f
+File: standards.info,  Node: Design Advice,  Next: Program Behavior,  Prev: Legal Issues,  Up: Top
+
+General Program Design
+**********************
+
+This node discusses some of the issues you should take into account
+when designing your program.
+
+* Menu:
+
+* Source Language::             Which languges to use.
+* Compatibility::               Compatibility with other implementations
+* Using Extensions::            Using non-standard features
+* Standard C::                  Using Standard C features
+
+\1f
+File: standards.info,  Node: Source Language,  Next: Compatibility,  Up: Design Advice
+
+Which Languages to Use
+======================
+
+When you want to use a language that gets compiled and runs at high
+speed, the best language to use is C.  Using another language is like
+using a non-standard feature: it will cause trouble for users.  Even if
+GCC supports the other language, users may find it inconvenient to have
+to install the compiler for that other language in order to build your
+program.  For example, if you write your program in C++, people will
+have to install the GNU C++ compiler in order to compile your program.
+
+   C has one other advantage over C++ and other compiled languages: more
+people know C, so more people will find it easy to read and modify the
+program if it is written in C.
+
+   So in general it is much better to use C, rather than the comparable
+alternatives.
+
+   But there are two exceptions to that conclusion:
+
+   * It is no problem to use another language to write a tool
+     specifically intended for use with that language.  That is because
+     the only people who want to build the tool will be those who have
+     installed the other language anyway.
+
+   * If an application is of interest only to a narrow part of the
+     community, then the question of which language it is written in
+     has less effect on other people, so you may as well please
+     yourself.
+
+   Many programs are designed to be extensible: they include an
+interpreter for a language that is higher level than C.  Often much of
+the program is written in that language, too.  The Emacs editor
+pioneered this technique.
+
+   The standard extensibility interpreter for GNU software is GUILE,
+which implements the language Scheme (an especially clean and simple
+dialect of Lisp).  `http://www.gnu.org/software/guile/'.  We don't
+reject programs written in other "scripting languages" such as Perl and
+Python, but using GUILE is very important for the overall consistency of
+the GNU system.
+
+\1f
+File: standards.info,  Node: Compatibility,  Next: Using Extensions,  Prev: Source Language,  Up: Design Advice
+
+Compatibility with Other Implementations
+========================================
+
+With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with Standard C if Standard C specifies their behavior, and
+upward compatible with POSIX if POSIX specifies their behavior.
+
+   When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+   Standard C and POSIX prohibit many kinds of extensions.  Feel free
+to make the extensions anyway, and include a `--ansi', `--posix', or
+`--compatible' option to turn them off.  However, if the extension has
+a significant chance of breaking any real programs or scripts, then it
+is not really upward compatible.  So you should try to redesign its
+interface to make it upward compatible.
+
+   Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable `POSIXLY_CORRECT' is defined (even if it is
+defined with a null value).  Please make your program recognize this
+variable if appropriate.
+
+   When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better.  (For example,
+`vi' is replaced with Emacs.)  But it is nice to offer a compatible
+feature as well.  (There is a free `vi' clone, so we offer it.)
+
+   Additional useful features are welcome regardless of whether there
+is any precedent for them.
+
+\1f
+File: standards.info,  Node: Using Extensions,  Next: Standard C,  Prev: Compatibility,  Up: Design Advice
+
+Using Non-standard Features
+===========================
+
+Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities.  Whether to use these
+extensions in implementing your program is a difficult question.
+
+   On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program unless
+the other GNU tools are available.  This might cause the program to
+work on fewer kinds of machines.
+
+   With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a "keyword" `INLINE' and
+define that as a macro to expand into either `inline' or nothing,
+depending on the compiler.
+
+   In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+   An exception to this rule are the large, established programs (such
+as Emacs) which run on a great variety of systems.  Using GNU
+extensions in such programs would make many users unhappy, so we don't
+do that.
+
+   Another exception is for programs that are used as part of
+compilation: anything that must be compiled with other compilers in
+order to bootstrap the GNU compilation facilities.  If these require
+the GNU compiler, then no one can compile them without having them
+installed already.  That would be extremely troublesome in certain
+cases.
+
+\1f
+File: standards.info,  Node: Standard C,  Prev: Using Extensions,  Up: Design Advice
+
+Standard C and Pre-Standard C
+=============================
+
+1989 Standard C is widespread enough now that it is ok to use its
+features in new programs.  There is one exception: do not ever use the
+"trigraph" feature of Standard C.
+
+   1999 Standard C is not widespread yet, so please do not require its
+features in programs.  It is ok to use its features if they are present.
+
+   However, it is easy to support pre-standard compilers in most
+programs, so if you know how to do that, feel free.  If a program you
+are maintaining has such support, you should try to keep it working.
+
+   To support pre-standard C, instead of writing function definitions in
+standard prototype form,
+
+     int
+     foo (int x, int y)
+     ...
+
+write the definition in pre-standard style like this,
+
+     int
+     foo (x, y)
+          int x, y;
+     ...
+
+and use a separate declaration to specify the argument prototype:
+
+     int foo (int, int);
+
+   You need such a declaration anyway, in a header file, to get the
+benefit of prototypes in all the files where the function is called.
+And once you have the declaration, you normally lose nothing by writing
+the function definition in the pre-standard style.
+
+   This technique does not work for integer types narrower than `int'.
+If you think of an argument as being of a type narrower than `int',
+declare it as `int' instead.
+
+   There are a few special cases where this technique is hard to use.
+For example, if a function argument needs to hold the system type
+`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
+some machines; but you cannot use `int' instead, because `dev_t' is
+wider than `int' on some machines.  There is no type you can safely use
+on all machines in a non-standard definition.  The only way to support
+non-standard C and pass such an argument is to check the width of
+`dev_t' using Autoconf and choose the argument type accordingly.  This
+may not be worth the trouble.
+
+   In order to support pre-standard compilers that do not recognize
+prototypes, you may want to use a preprocessor macro like this:
+
+     /* Declare the prototype for a general external function.  */
+     #if defined (__STDC__) || defined (WINDOWSNT)
+     #define P_(proto) proto
+     #else
+     #define P_(proto) ()
+     #endif
+
+\1f
+File: standards.info,  Node: Program Behavior,  Next: Writing C,  Prev: Design Advice,  Up: Top
+
+Program Behavior for All Programs
+*********************************
+
+This node describes conventions for writing robust software.  It also
+describes general standards for error messages, the command line
+interface, and how libraries should behave.
+
+* Menu:
+
+* Semantics::                   Writing robust programs
+* Libraries::                   Library behavior
+* Errors::                      Formatting error messages
+* User Interfaces::             Standards about interfaces generally
+* Graphical Interfaces::        Standards for graphical interfaces
+* Command-Line Interfaces::     Standards for command line interfaces
+* Option Table::                Table of long options
+* Memory Usage::                When and how to care about memory needs
+* File Usage::                  Which files to use, and where
+
+\1f
+File: standards.info,  Node: Semantics,  Next: Libraries,  Up: Program Behavior
+
+Writing Robust Programs
+=======================
+
+Avoid arbitrary limits on the length or number of _any_ data structure,
+including file names, lines, files, and symbols, by allocating all data
+structures dynamically.  In most Unix utilities, "long lines are
+silently truncated".  This is not acceptable in a GNU utility.
+
+   Utilities reading files should not drop NUL characters, or any other
+nonprinting characters _including those with codes above 0177_.  The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of terminals or printers that can't handle
+those characters.  Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters,
+using encodings such as UTF-8 and others.
+
+   Check every system call for an error return, unless you know you
+wish to ignore errors.  Include the system error text (from `perror' or
+equivalent) in _every_ error message resulting from a failing system
+call, as well as the name of the file if any and the name of the
+utility.  Just "cannot open foo.c" or "stat failed" is not sufficient.
+
+   Check every call to `malloc' or `realloc' to see if it returned
+zero.  Check `realloc' even if you are making the block smaller; in a
+system that rounds block sizes to a power of 2, `realloc' may get a
+different block if you ask for less space.
+
+   In Unix, `realloc' can destroy the storage block if it returns zero.
+GNU `realloc' does not have this bug: if it fails, the original block
+is unchanged.  Feel free to assume the bug is fixed.  If you wish to
+run your program on Unix, and wish to avoid lossage in this case, you
+can use the GNU `malloc'.
+
+   You must expect `free' to alter the contents of the block that was
+freed.  Anything you want to fetch from the block, you must fetch before
+calling `free'.
+
+   If `malloc' fails in a noninteractive program, make that a fatal
+error.  In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop.  This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+   Use `getopt_long' to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+   When static storage is to be written in during program execution, use
+explicit C code to initialize it.  Reserve C initialized declarations
+for data that will not be changed.
+
+   Try to avoid low-level interfaces to obscure Unix data structures
+(such as file directories, utmp, or the layout of kernel memory), since
+these are less likely to work compatibly.  If you need to find all the
+files in a directory, use `readdir' or some other high-level interface.
+These are supported compatibly by GNU.
+
+   The preferred signal handling facilities are the BSD variant of
+`signal', and the POSIX `sigaction' function; the alternative USG
+`signal' interface is an inferior design.
+
+   Nowadays, using the POSIX signal functions may be the easiest way to
+make a program portable.  If you use `signal', then on GNU/Linux
+systems running GNU libc version 1, you should include `bsd/signal.h'
+instead of `signal.h', so as to get BSD behavior.  It is up to you
+whether to support systems where `signal' has only the USG behavior, or
+give up on them.
+
+   In error checks that detect "impossible" conditions, just abort.
+There is usually no point in printing any message.  These checks
+indicate the existence of bugs.  Whoever wants to fix the bugs will have
+to read the source code and run a debugger.  So explain the problem with
+comments in the source.  The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+   Do not use a count of errors as the exit status for a program.
+_That does not work_, because exit status values are limited to 8 bits
+(0 through 255).  A single run of the program might have 256 errors; if
+you try to return 256 as the exit status, the parent process will see 0
+as the status, and it will appear that the program succeeded.
+
+   If you make temporary files, check the `TMPDIR' environment
+variable; if that variable is defined, use the specified directory
+instead of `/tmp'.
+
+   In addition, be aware that there is a possible security problem when
+creating temporary files in world-writable directories.  In C, you can
+avoid this problem by creating temporary files in this manner:
+
+     fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+
+or by using the `mkstemps' function from libiberty.
+
+   In bash, use `set -C' to avoid this problem.
+
+\1f
+File: standards.info,  Node: Libraries,  Next: Errors,  Prev: Semantics,  Up: Program Behavior
+
+Library Behavior
+================
+
+Try to make library functions reentrant.  If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of `malloc' itself.
+
+   Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+   Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this prefix.
+In addition, there should only be one of these in any given library
+member.  This usually means putting each one in a separate source file.
+
+   An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+   External symbols that are not documented entry points for the user
+should have names beginning with `_'.  The `_' should be followed by
+the chosen name prefix for the library, to prevent collisions with
+other libraries.  These can go in the same files with user entry points
+if you like.
+
+   Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+\1f
+File: standards.info,  Node: Errors,  Next: User Interfaces,  Prev: Libraries,  Up: Program Behavior
+
+Formatting Error Messages
+=========================
+
+Error messages from compilers should look like this:
+
+     SOURCE-FILE-NAME:LINENO: MESSAGE
+
+If you want to mention the column number, use this format:
+
+     SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+Line numbers should start from 1 at the beginning of the file, and
+column numbers should start from 1 at the beginning of the line.  (Both
+of these conventions are chosen for compatibility.)  Calculate column
+numbers assuming that space and all ASCII printing characters have
+equal width, and assuming tab stops every 8 columns.
+
+   Error messages from other noninteractive programs should look like
+this:
+
+     PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
+
+when there is an appropriate source file, or like this:
+
+     PROGRAM: MESSAGE
+
+when there is no relevant source file.
+
+   If you want to mention the column number, use this format:
+
+     PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
+
+   In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message.  The place to indicate which program is running is in the
+prompt or with the screen layout.  (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+   The string MESSAGE should not begin with a capital letter when it
+follows a program name and/or file name.  Also, it should not end with
+a period.
+
+   Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter.  But they should not
+end with a period.
+
+\1f
+File: standards.info,  Node: User Interfaces,  Next: Graphical Interfaces,  Prev: Errors,  Up: Program Behavior
+
+Standards for Interfaces Generally
+==================================
+
+Please don't make the behavior of a utility depend on the name used to
+invoke it.  It is useful sometimes to make a link to a utility with a
+different name, and that should not change what it does.
+
+   Instead, use a run time option or a compilation switch or both to
+select among the alternate behaviors.
+
+   Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with.  Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then.  (Variation in error
+message syntax when using a terminal is ok, because that is a side issue
+that people do not depend on.)
+
+   If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+   Compatibility requires certain programs to depend on the type of
+output device.  It would be disastrous if `ls' or `sh' did not do so in
+the way all users expect.  In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type.  For example, we provide a `dir' program much like
+`ls' except that its default output format is always multi-column
+format.
+
+\1f
+File: standards.info,  Node: Graphical Interfaces,  Next: Command-Line Interfaces,  Prev: User Interfaces,  Up: Program Behavior
+
+Standards for Graphical Interfaces
+==================================
+
+When you write a program that provides a graphical user interface,
+please make it work with X Windows and the GTK toolkit unless the
+functionality specifically requires some alternative (for example,
+"displaying jpeg images while in console mode").
+
+   In addition, please provide a command-line interface to control the
+functionality.  (In many cases, the graphical user interface can be a
+separate program which invokes the command-line program.)  This is so
+that the same jobs can be done from scripts.
+
+   Please also consider providing a CORBA interface (for use from
+GNOME), a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console mode).
+Once you are doing the work to provide the functionality and the
+graphical interface, these won't be much extra work.
+
+\1f
+File: standards.info,  Node: Command-Line Interfaces,  Next: Option Table,  Prev: Graphical Interfaces,  Up: Program Behavior
+
+Standards for Command Line Interfaces
+=====================================
+
+It is a good idea to follow the POSIX guidelines for the command-line
+options of a program.  The easiest way to do this is to use `getopt' to
+parse them.  Note that the GNU version of `getopt' will normally permit
+options anywhere among the arguments unless the special argument `--'
+is used.  This is not what POSIX specifies; it is a GNU extension.
+
+   Please define long-named options that are equivalent to the
+single-letter Unix-style options.  We hope to make GNU more user
+friendly this way.  This is easy to do with the GNU function
+`getopt_long'.
+
+   One of the advantages of long-named options is that they can be
+consistent from program to program.  For example, users should be able
+to expect the "verbose" option of any GNU program which has one, to be
+spelled precisely `--verbose'.  To achieve this uniformity, look at the
+table of common long-option names when you choose the option names for
+your program (*note Option Table::).
+
+   It is usually a good idea for file names given as ordinary arguments
+to be input files only; any output files would be specified using
+options (preferably `-o' or `--output').  Even if you allow an output
+file name as an ordinary argument for compatibility, try to provide an
+option as another way to specify it.  This will lead to more consistency
+among GNU utilities, and fewer idiosyncracies for users to remember.
+
+   All programs should support two standard options: `--version' and
+`--help'.
+
+`--version'
+     This option should direct the program to print information about
+     its name, version, origin and legal status, all on standard
+     output, and then exit successfully.  Other options and arguments
+     should be ignored once this is seen, and the program should not
+     perform its normal function.
+
+     The first line is meant to be easy for a program to parse; the
+     version number proper starts after the last space.  In addition,
+     it contains the canonical name for this program, in this format:
+
+          GNU Emacs 19.30
+
+     The program's name should be a constant string; _don't_ compute it
+     from `argv[0]'.  The idea is to state the standard or canonical
+     name for the program, not its file name.  There are other ways to
+     find out the precise file name where a command is found in `PATH'.
+
+     If the program is a subsidiary part of a larger package, mention
+     the package name in parentheses, like this:
+
+          emacsserver (GNU Emacs) 19.30
+
+     If the package has a version number which is different from this
+     program's version number, you can mention the package version
+     number just before the close-parenthesis.
+
+     If you *need* to mention the version numbers of libraries which
+     are distributed separately from the package which contains this
+     program, you can do so by printing an additional line of version
+     info for each library you want to mention.  Use the same format
+     for these lines as for the first line.
+
+     Please do not mention all of the libraries that the program uses
+     "just for completeness"--that would produce a lot of unhelpful
+     clutter.  Please mention library version numbers only if you find
+     in practice that they are very important to you in debugging.
+
+     The following line, after the version number line or lines, should
+     be a copyright notice.  If more than one copyright notice is
+     called for, put each on a separate line.
+
+     Next should follow a brief statement that the program is free
+     software, and that users are free to copy and change it on certain
+     conditions.  If the program is covered by the GNU GPL, say so
+     here.  Also mention that there is no warranty, to the extent
+     permitted by law.
+
+     It is ok to finish the output with a list of the major authors of
+     the program, as a way of giving credit.
+
+     Here's an example of output that follows these rules:
+
+          GNU Emacs 19.34.5
+          Copyright (C) 1996 Free Software Foundation, Inc.
+          GNU Emacs comes with NO WARRANTY,
+          to the extent permitted by law.
+          You may redistribute copies of GNU Emacs
+          under the terms of the GNU General Public License.
+          For more information about these matters,
+          see the files named COPYING.
+
+     You should adapt this to your program, of course, filling in the
+     proper year, copyright holder, name of program, and the references
+     to distribution terms, and changing the rest of the wording as
+     necessary.
+
+     This copyright notice only needs to mention the most recent year in
+     which changes were made--there's no need to list the years for
+     previous versions' changes.  You don't have to mention the name of
+     the program in these notices, if that is inconvenient, since it
+     appeared in the first line.
+
+`--help'
+     This option should output brief documentation for how to invoke the
+     program, on standard output, then exit successfully.  Other
+     options and arguments should be ignored once this is seen, and the
+     program should not perform its normal function.
+
+     Near the end of the `--help' option's output there should be a line
+     that says where to mail bug reports.  It should have this format:
+
+          Report bugs to MAILING-ADDRESS.
+
+\1f
+File: standards.info,  Node: Option Table,  Next: Memory Usage,  Prev: Command-Line Interfaces,  Up: Program Behavior
+
+Table of Long Options
+=====================
+
+Here is a table of long options used by GNU programs.  It is surely
+incomplete, but we aim to list all the options that a new program might
+want to be compatible with.  If you use names not already in the table,
+please send <bug-standards@gnu.org> a list of them, with their
+meanings, so we can update the table.
+
+`after-date'
+     `-N' in `tar'.
+
+`all'
+     `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
+
+`all-text'
+     `-a' in `diff'.
+
+`almost-all'
+     `-A' in `ls'.
+
+`append'
+     `-a' in `etags', `tee', `time'; `-r' in `tar'.
+
+`archive'
+     `-a' in `cp'.
+
+`archive-name'
+     `-n' in `shar'.
+
+`arglength'
+     `-l' in `m4'.
+
+`ascii'
+     `-a' in `diff'.
+
+`assign'
+     `-v' in `gawk'.
+
+`assume-new'
+     `-W' in Make.
+
+`assume-old'
+     `-o' in Make.
+
+`auto-check'
+     `-a' in `recode'.
+
+`auto-pager'
+     `-a' in `wdiff'.
+
+`auto-reference'
+     `-A' in `ptx'.
+
+`avoid-wraps'
+     `-n' in `wdiff'.
+
+`background'
+     For server programs, run in the background.
+
+`backward-search'
+     `-B' in `ctags'.
+
+`basename'
+     `-f' in `shar'.
+
+`batch'
+     Used in GDB.
+
+`baud'
+     Used in GDB.
+
+`before'
+     `-b' in `tac'.
+
+`binary'
+     `-b' in `cpio' and `diff'.
+
+`bits-per-code'
+     `-b' in `shar'.
+
+`block-size'
+     Used in `cpio' and `tar'.
+
+`blocks'
+     `-b' in `head' and `tail'.
+
+`break-file'
+     `-b' in `ptx'.
+
+`brief'
+     Used in various programs to make output shorter.
+
+`bytes'
+     `-c' in `head', `split', and `tail'.
+
+`c++'
+     `-C' in `etags'.
+
+`catenate'
+     `-A' in `tar'.
+
+`cd'
+     Used in various programs to specify the directory to use.
+
+`changes'
+     `-c' in `chgrp' and `chown'.
+
+`classify'
+     `-F' in `ls'.
+
+`colons'
+     `-c' in `recode'.
+
+`command'
+     `-c' in `su'; `-x' in GDB.
+
+`compare'
+     `-d' in `tar'.
+
+`compat'
+     Used in `gawk'.
+
+`compress'
+     `-Z' in `tar' and `shar'.
+
+`concatenate'
+     `-A' in `tar'.
+
+`confirmation'
+     `-w' in `tar'.
+
+`context'
+     Used in `diff'.
+
+`copyleft'
+     `-W copyleft' in `gawk'.
+
+`copyright'
+     `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
+
+`core'
+     Used in GDB.
+
+`count'
+     `-q' in `who'.
+
+`count-links'
+     `-l' in `du'.
+
+`create'
+     Used in `tar' and `cpio'.
+
+`cut-mark'
+     `-c' in `shar'.
+
+`cxref'
+     `-x' in `ctags'.
+
+`date'
+     `-d' in `touch'.
+
+`debug'
+     `-d' in Make and `m4'; `-t' in Bison.
+
+`define'
+     `-D' in `m4'.
+
+`defines'
+     `-d' in Bison and `ctags'.
+
+`delete'
+     `-D' in `tar'.
+
+`dereference'
+     `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
+
+`dereference-args'
+     `-D' in `du'.
+
+`device'
+     Specify an I/O device (special file name).
+
+`diacritics'
+     `-d' in `recode'.
+
+`dictionary-order'
+     `-d' in `look'.
+
+`diff'
+     `-d' in `tar'.
+
+`digits'
+     `-n' in `csplit'.
+
+`directory'
+     Specify the directory to use, in various programs.  In `ls', it
+     means to show directories themselves rather than their contents.
+     In `rm' and `ln', it means to not treat links to directories
+     specially.
+
+`discard-all'
+     `-x' in `strip'.
+
+`discard-locals'
+     `-X' in `strip'.
+
+`dry-run'
+     `-n' in Make.
+
+`ed'
+     `-e' in `diff'.
+
+`elide-empty-files'
+     `-z' in `csplit'.
+
+`end-delete'
+     `-x' in `wdiff'.
+
+`end-insert'
+     `-z' in `wdiff'.
+
+`entire-new-file'
+     `-N' in `diff'.
+
+`environment-overrides'
+     `-e' in Make.
+
+`eof'
+     `-e' in `xargs'.
+
+`epoch'
+     Used in GDB.
+
+`error-limit'
+     Used in `makeinfo'.
+
+`error-output'
+     `-o' in `m4'.
+
+`escape'
+     `-b' in `ls'.
+
+`exclude-from'
+     `-X' in `tar'.
+
+`exec'
+     Used in GDB.
+
+`exit'
+     `-x' in `xargs'.
+
+`exit-0'
+     `-e' in `unshar'.
+
+`expand-tabs'
+     `-t' in `diff'.
+
+`expression'
+     `-e' in `sed'.
+
+`extern-only'
+     `-g' in `nm'.
+
+`extract'
+     `-i' in `cpio'; `-x' in `tar'.
+
+`faces'
+     `-f' in `finger'.
+
+`fast'
+     `-f' in `su'.
+
+`fatal-warnings'
+     `-E' in `m4'.
+
+`file'
+     `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
+     in `touch'.
+
+`field-separator'
+     `-F' in `gawk'.
+
+`file-prefix'
+     `-b' in Bison.
+
+`file-type'
+     `-F' in `ls'.
+
+`files-from'
+     `-T' in `tar'.
+
+`fill-column'
+     Used in `makeinfo'.
+
+`flag-truncation'
+     `-F' in `ptx'.
+
+`fixed-output-files'
+     `-y' in Bison.
+
+`follow'
+     `-f' in `tail'.
+
+`footnote-style'
+     Used in `makeinfo'.
+
+`force'
+     `-f' in `cp', `ln', `mv', and `rm'.
+
+`force-prefix'
+     `-F' in `shar'.
+
+`foreground'
+     For server programs, run in the foreground; in other words, don't
+     do anything special to run the server in the background.
+
+`format'
+     Used in `ls', `time', and `ptx'.
+
+`freeze-state'
+     `-F' in `m4'.
+
+`fullname'
+     Used in GDB.
+
+`gap-size'
+     `-g' in `ptx'.
+
+`get'
+     `-x' in `tar'.
+
+`graphic'
+     `-i' in `ul'.
+
+`graphics'
+     `-g' in `recode'.
+
+`group'
+     `-g' in `install'.
+
+`gzip'
+     `-z' in `tar' and `shar'.
+
+`hashsize'
+     `-H' in `m4'.
+
+`header'
+     `-h' in `objdump' and `recode'
+
+`heading'
+     `-H' in `who'.
+
+`help'
+     Used to ask for brief usage information.
+
+`here-delimiter'
+     `-d' in `shar'.
+
+`hide-control-chars'
+     `-q' in `ls'.
+
+`html'
+     In `makeinfo', output HTML.
+
+`idle'
+     `-u' in `who'.
+
+`ifdef'
+     `-D' in `diff'.
+
+`ignore'
+     `-I' in `ls'; `-x' in `recode'.
+
+`ignore-all-space'
+     `-w' in `diff'.
+
+`ignore-backups'
+     `-B' in `ls'.
+
+`ignore-blank-lines'
+     `-B' in `diff'.
+
+`ignore-case'
+     `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
+
+`ignore-errors'
+     `-i' in Make.
+
+`ignore-file'
+     `-i' in `ptx'.
+
+`ignore-indentation'
+     `-I' in `etags'.
+
+`ignore-init-file'
+     `-f' in Oleo.
+
+`ignore-interrupts'
+     `-i' in `tee'.
+
+`ignore-matching-lines'
+     `-I' in `diff'.
+
+`ignore-space-change'
+     `-b' in `diff'.
+
+`ignore-zeros'
+     `-i' in `tar'.
+
+`include'
+     `-i' in `etags'; `-I' in `m4'.
+
+`include-dir'
+     `-I' in Make.
+
+`incremental'
+     `-G' in `tar'.
+
+`info'
+     `-i', `-l', and `-m' in Finger.
+
+`init-file'
+     In some programs, specify the name of the file to read as the
+     user's init file.
+
+`initial'
+     `-i' in `expand'.
+
+`initial-tab'
+     `-T' in `diff'.
+
+`inode'
+     `-i' in `ls'.
+
+`interactive'
+     `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
+     `-w' in `tar'.
+
+`intermix-type'
+     `-p' in `shar'.
+
+`iso-8601'
+     Used in `date'
+
+`jobs'
+     `-j' in Make.
+
+`just-print'
+     `-n' in Make.
+
+`keep-going'
+     `-k' in Make.
+
+`keep-files'
+     `-k' in `csplit'.
+
+`kilobytes'
+     `-k' in `du' and `ls'.
+
+`language'
+     `-l' in `etags'.
+
+`less-mode'
+     `-l' in `wdiff'.
+
+`level-for-gzip'
+     `-g' in `shar'.
+
+`line-bytes'
+     `-C' in `split'.
+
+`lines'
+     Used in `split', `head', and `tail'.
+
+`link'
+     `-l' in `cpio'.
+
+`lint'
+`lint-old'
+     Used in `gawk'.
+
+`list'
+     `-t' in `cpio'; `-l' in `recode'.
+
+`list'
+     `-t' in `tar'.
+
+`literal'
+     `-N' in `ls'.
+
+`load-average'
+     `-l' in Make.
+
+`login'
+     Used in `su'.
+
+`machine'
+     No listing of which programs already use this; someone should
+     check to see if any actually do, and tell <gnu@gnu.org>.
+
+`macro-name'
+     `-M' in `ptx'.
+
+`mail'
+     `-m' in `hello' and `uname'.
+
+`make-directories'
+     `-d' in `cpio'.
+
+`makefile'
+     `-f' in Make.
+
+`mapped'
+     Used in GDB.
+
+`max-args'
+     `-n' in `xargs'.
+
+`max-chars'
+     `-n' in `xargs'.
+
+`max-lines'
+     `-l' in `xargs'.
+
+`max-load'
+     `-l' in Make.
+
+`max-procs'
+     `-P' in `xargs'.
+
+`mesg'
+     `-T' in `who'.
+
+`message'
+     `-T' in `who'.
+
+`minimal'
+     `-d' in `diff'.
+
+`mixed-uuencode'
+     `-M' in `shar'.
+
+`mode'
+     `-m' in `install', `mkdir', and `mkfifo'.
+
+`modification-time'
+     `-m' in `tar'.
+
+`multi-volume'
+     `-M' in `tar'.
+
+`name-prefix'
+     `-a' in Bison.
+
+`nesting-limit'
+     `-L' in `m4'.
+
+`net-headers'
+     `-a' in `shar'.
+
+`new-file'
+     `-W' in Make.
+
+`no-builtin-rules'
+     `-r' in Make.
+
+`no-character-count'
+     `-w' in `shar'.
+
+`no-check-existing'
+     `-x' in `shar'.
+
+`no-common'
+     `-3' in `wdiff'.
+
+`no-create'
+     `-c' in `touch'.
+
+`no-defines'
+     `-D' in `etags'.
+
+`no-deleted'
+     `-1' in `wdiff'.
+
+`no-dereference'
+     `-d' in `cp'.
+
+`no-inserted'
+     `-2' in `wdiff'.
+
+`no-keep-going'
+     `-S' in Make.
+
+`no-lines'
+     `-l' in Bison.
+
+`no-piping'
+     `-P' in `shar'.
+
+`no-prof'
+     `-e' in `gprof'.
+
+`no-regex'
+     `-R' in `etags'.
+
+`no-sort'
+     `-p' in `nm'.
+
+`no-split'
+     Used in `makeinfo'.
+
+`no-static'
+     `-a' in `gprof'.
+
+`no-time'
+     `-E' in `gprof'.
+
+`no-timestamp'
+     `-m' in `shar'.
+
+`no-validate'
+     Used in `makeinfo'.
+
+`no-wait'
+     Used in `emacsclient'.
+
+`no-warn'
+     Used in various programs to inhibit warnings.
+
+`node'
+     `-n' in `info'.
+
+`nodename'
+     `-n' in `uname'.
+
+`nonmatching'
+     `-f' in `cpio'.
+
+`nstuff'
+     `-n' in `objdump'.
+
+`null'
+     `-0' in `xargs'.
+
+`number'
+     `-n' in `cat'.
+
+`number-nonblank'
+     `-b' in `cat'.
+
+`numeric-sort'
+     `-n' in `nm'.
+
+`numeric-uid-gid'
+     `-n' in `cpio' and `ls'.
+
+`nx'
+     Used in GDB.
+
+`old-archive'
+     `-o' in `tar'.
+
+`old-file'
+     `-o' in Make.
+
+`one-file-system'
+     `-l' in `tar', `cp', and `du'.
+
+`only-file'
+     `-o' in `ptx'.
+
+`only-prof'
+     `-f' in `gprof'.
+
+`only-time'
+     `-F' in `gprof'.
+
+`options'
+     `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
+
+`output'
+     In various programs, specify the output file name.
+
+`output-prefix'
+     `-o' in `shar'.
+
+`override'
+     `-o' in `rm'.
+
+`overwrite'
+     `-c' in `unshar'.
+
+`owner'
+     `-o' in `install'.
+
+`paginate'
+     `-l' in `diff'.
+
+`paragraph-indent'
+     Used in `makeinfo'.
+
+`parents'
+     `-p' in `mkdir' and `rmdir'.
+
+`pass-all'
+     `-p' in `ul'.
+
+`pass-through'
+     `-p' in `cpio'.
+
+`port'
+     `-P' in `finger'.
+
+`portability'
+     `-c' in `cpio' and `tar'.
+
+`posix'
+     Used in `gawk'.
+
+`prefix-builtins'
+     `-P' in `m4'.
+
+`prefix'
+     `-f' in `csplit'.
+
+`preserve'
+     Used in `tar' and `cp'.
+
+`preserve-environment'
+     `-p' in `su'.
+
+`preserve-modification-time'
+     `-m' in `cpio'.
+
+`preserve-order'
+     `-s' in `tar'.
+
+`preserve-permissions'
+     `-p' in `tar'.
+
+`print'
+     `-l' in `diff'.
+
+`print-chars'
+     `-L' in `cmp'.
+
+`print-data-base'
+     `-p' in Make.
+
+`print-directory'
+     `-w' in Make.
+
+`print-file-name'
+     `-o' in `nm'.
+
+`print-symdefs'
+     `-s' in `nm'.
+
+`printer'
+     `-p' in `wdiff'.
+
+`prompt'
+     `-p' in `ed'.
+
+`proxy'
+     Specify an HTTP proxy.
+
+`query-user'
+     `-X' in `shar'.
+
+`question'
+     `-q' in Make.
+
+`quiet'
+     Used in many programs to inhibit the usual output.  *Note:* every
+     program accepting `--quiet' should accept `--silent' as a synonym.
+
+`quiet-unshar'
+     `-Q' in `shar'
+
+`quote-name'
+     `-Q' in `ls'.
+
+`rcs'
+     `-n' in `diff'.
+
+`re-interval'
+     Used in `gawk'.
+
+`read-full-blocks'
+     `-B' in `tar'.
+
+`readnow'
+     Used in GDB.
+
+`recon'
+     `-n' in Make.
+
+`record-number'
+     `-R' in `tar'.
+
+`recursive'
+     Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
+
+`reference-limit'
+     Used in `makeinfo'.
+
+`references'
+     `-r' in `ptx'.
+
+`regex'
+     `-r' in `tac' and `etags'.
+
+`release'
+     `-r' in `uname'.
+
+`reload-state'
+     `-R' in `m4'.
+
+`relocation'
+     `-r' in `objdump'.
+
+`rename'
+     `-r' in `cpio'.
+
+`replace'
+     `-i' in `xargs'.
+
+`report-identical-files'
+     `-s' in `diff'.
+
+`reset-access-time'
+     `-a' in `cpio'.
+
+`reverse'
+     `-r' in `ls' and `nm'.
+
+`reversed-ed'
+     `-f' in `diff'.
+
+`right-side-defs'
+     `-R' in `ptx'.
+
+`same-order'
+     `-s' in `tar'.
+
+`same-permissions'
+     `-p' in `tar'.
+
+`save'
+     `-g' in `stty'.
+
+`se'
+     Used in GDB.
+
+`sentence-regexp'
+     `-S' in `ptx'.
+
+`separate-dirs'
+     `-S' in `du'.
+
+`separator'
+     `-s' in `tac'.
+
+`sequence'
+     Used by `recode' to chose files or pipes for sequencing passes.
+
+`shell'
+     `-s' in `su'.
+
+`show-all'
+     `-A' in `cat'.
+
+`show-c-function'
+     `-p' in `diff'.
+
+`show-ends'
+     `-E' in `cat'.
+
+`show-function-line'
+     `-F' in `diff'.
+
+`show-tabs'
+     `-T' in `cat'.
+
+`silent'
+     Used in many programs to inhibit the usual output.  *Note:* every
+     program accepting `--silent' should accept `--quiet' as a synonym.
+
+`size'
+     `-s' in `ls'.
+
+`socket'
+     Specify a file descriptor for a network server to use for its
+     socket, instead of opening and binding a new socket.  This
+     provides a way to run, in a nonpriveledged process, a server that
+     normally needs a reserved port number.
+
+`sort'
+     Used in `ls'.
+
+`source'
+     `-W source' in `gawk'.
+
+`sparse'
+     `-S' in `tar'.
+
+`speed-large-files'
+     `-H' in `diff'.
+
+`split-at'
+     `-E' in `unshar'.
+
+`split-size-limit'
+     `-L' in `shar'.
+
+`squeeze-blank'
+     `-s' in `cat'.
+
+`start-delete'
+     `-w' in `wdiff'.
+
+`start-insert'
+     `-y' in `wdiff'.
+
+`starting-file'
+     Used in `tar' and `diff' to specify which file within a directory
+     to start processing with.
+
+`statistics'
+     `-s' in `wdiff'.
+
+`stdin-file-list'
+     `-S' in `shar'.
+
+`stop'
+     `-S' in Make.
+
+`strict'
+     `-s' in `recode'.
+
+`strip'
+     `-s' in `install'.
+
+`strip-all'
+     `-s' in `strip'.
+
+`strip-debug'
+     `-S' in `strip'.
+
+`submitter'
+     `-s' in `shar'.
+
+`suffix'
+     `-S' in `cp', `ln', `mv'.
+
+`suffix-format'
+     `-b' in `csplit'.
+
+`sum'
+     `-s' in `gprof'.
+
+`summarize'
+     `-s' in `du'.
+
+`symbolic'
+     `-s' in `ln'.
+
+`symbols'
+     Used in GDB and `objdump'.
+
+`synclines'
+     `-s' in `m4'.
+
+`sysname'
+     `-s' in `uname'.
+
+`tabs'
+     `-t' in `expand' and `unexpand'.
+
+`tabsize'
+     `-T' in `ls'.
+
+`terminal'
+     `-T' in `tput' and `ul'.  `-t' in `wdiff'.
+
+`text'
+     `-a' in `diff'.
+
+`text-files'
+     `-T' in `shar'.
+
+`time'
+     Used in `ls' and `touch'.
+
+`timeout'
+     Specify how long to wait before giving up on some operation.
+
+`to-stdout'
+     `-O' in `tar'.
+
+`total'
+     `-c' in `du'.
+
+`touch'
+     `-t' in Make, `ranlib', and `recode'.
+
+`trace'
+     `-t' in `m4'.
+
+`traditional'
+     `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
+     and `ptx'.
+
+`tty'
+     Used in GDB.
+
+`typedefs'
+     `-t' in `ctags'.
+
+`typedefs-and-c++'
+     `-T' in `ctags'.
+
+`typeset-mode'
+     `-t' in `ptx'.
+
+`uncompress'
+     `-z' in `tar'.
+
+`unconditional'
+     `-u' in `cpio'.
+
+`undefine'
+     `-U' in `m4'.
+
+`undefined-only'
+     `-u' in `nm'.
+
+`update'
+     `-u' in `cp', `ctags', `mv', `tar'.
+
+`usage'
+     Used in `gawk'; same as `--help'.
+
+`uuencode'
+     `-B' in `shar'.
+
+`vanilla-operation'
+     `-V' in `shar'.
+
+`verbose'
+     Print more information about progress.  Many programs support this.
+
+`verify'
+     `-W' in `tar'.
+
+`version'
+     Print the version number.
+
+`version-control'
+     `-V' in `cp', `ln', `mv'.
+
+`vgrind'
+     `-v' in `ctags'.
+
+`volume'
+     `-V' in `tar'.
+
+`what-if'
+     `-W' in Make.
+
+`whole-size-limit'
+     `-l' in `shar'.
+
+`width'
+     `-w' in `ls' and `ptx'.
+
+`word-regexp'
+     `-W' in `ptx'.
+
+`writable'
+     `-T' in `who'.
+
+`zeros'
+     `-z' in `gprof'.
+
+\1f
+File: standards.info,  Node: Memory Usage,  Next: File Usage,  Prev: Option Table,  Up: Program Behavior
+
+Memory Usage
+============
+
+If a program typically uses just a few meg of memory, don't bother
+making any effort to reduce memory usage.  For example, if it is
+impractical for other reasons to operate on files more than a few meg
+long, it is reasonable to read entire input files into core to operate
+on them.
+
+   However, for programs such as `cat' or `tail', that can usefully
+operate on very large files, it is important to avoid using a technique
+that would artificially limit the size of files it can handle.  If a
+program works by lines and could be applied to arbitrary user-supplied
+input files, it should keep only a line in memory, because this is not
+very hard and users will want to be able to operate on input files that
+are bigger than will fit in core all at once.
+
+   If your program creates complicated data structures, just make them
+in core and give a fatal error if `malloc' returns zero.
+
+\1f
+File: standards.info,  Node: File Usage,  Prev: Memory Usage,  Up: Program Behavior
+
+File Usage
+==========
+
+Programs should be prepared to operate when `/usr' and `/etc' are
+read-only file systems.  Thus, if the program manages log files, lock
+files, backup files, score files, or any other files which are modified
+for internal purposes, these files should not be stored in `/usr' or
+`/etc'.
+
+   There are two exceptions.  `/etc' is used to store system
+configuration information; it is reasonable for a program to modify
+files in `/etc' when its job is to update the system configuration.
+Also, if the user explicitly asks to modify one file in a directory, it
+is reasonable for the program to store other files in the same
+directory.
+
+\1f
+File: standards.info,  Node: Writing C,  Next: Documentation,  Prev: Program Behavior,  Up: Top
+
+Making The Best Use of C
+************************
+
+This node provides advice on how best to use the C language when
+writing GNU software.
+
+* Menu:
+
+* Formatting::                  Formatting Your Source Code
+* Comments::                    Commenting Your Work
+* Syntactic Conventions::       Clean Use of C Constructs
+* Names::                       Naming Variables and Functions
+* System Portability::          Portability between different operating systems
+* CPU Portability::             Supporting the range of CPU types
+* System Functions::            Portability and ``standard'' library functions
+* Internationalization::        Techniques for internationalization
+* Mmap::                        How you can safely use `mmap'.
+
+\1f
+File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C
+
+Formatting Your Source Code
+===========================
+
+It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero.  Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+   It is also important for function definitions to start the name of
+the function in column zero.  This helps people to search for function
+definitions, and may also help certain tools recognize them.  Thus, the
+proper format is this:
+
+     static char *
+     concat (s1, s2)        /* Name starts in column zero here */
+          char *s1, *s2;
+     {                     /* Open brace in column zero here */
+       ...
+     }
+
+or, if you want to use Standard C syntax, format the definition like
+this:
+
+     static char *
+     concat (char *s1, char *s2)
+     {
+       ...
+     }
+
+   In Standard C, if the arguments don't fit nicely on one line, split
+it like this:
+
+     int
+     lots_of_args (int an_integer, long a_long, short a_short,
+                   double a_double, float a_float)
+     ...
+
+   The rest of this section gives our recommendations for other aspects
+of C formatting style, which is also the default style of the `indent'
+program in version 1.2 and newer.  It corresponds to the options
+
+     -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
+     -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
+
+   We don't think of these recommendations as requirements, because it
+causes no problems for users if two different programs have different
+formatting styles.
+
+   But whatever style you use, please use it consistently, since a
+mixture of styles within one program tends to look ugly.  If you are
+contributing changes to an existing program, please follow the style of
+that program.
+
+   For the body of the function, our recommended style looks like this:
+
+     if (x < foo (y, z))
+       haha = bar[4] + 5;
+     else
+       {
+         while (z)
+           {
+             haha += foo (z, z);
+             z--;
+           }
+         return ++x + bar ();
+       }
+
+   We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas.  Especially after the commas.
+
+   When you split an expression into multiple lines, split it before an
+operator, not after one.  Here is the right way:
+
+     if (foo_this_is_long && bar > win (x, y, z)
+         && remaining_condition)
+
+   Try to avoid having two operators of different precedence at the same
+level of indentation.  For example, don't write this:
+
+     mode = (inmode[j] == VOIDmode
+             || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+             ? outmode[j] : inmode[j]);
+
+   Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+     mode = ((inmode[j] == VOIDmode
+              || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+             ? outmode[j] : inmode[j]);
+
+   Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+
+     v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+         + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+
+but Emacs would alter it.  Adding a set of parentheses produces
+something that looks equally nice, and which Emacs will preserve:
+
+     v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+          + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+
+   Format do-while statements like this:
+
+     do
+       {
+         a = foo (a);
+       }
+     while (a > 0);
+
+   Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function).  It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page.  The formfeeds should appear alone on lines by themselves.
+
+\1f
+File: standards.info,  Node: Comments,  Next: Syntactic Conventions,  Prev: Formatting,  Up: Writing C
+
+Commenting Your Work
+====================
+
+Every program should start with a comment saying briefly what it is for.
+Example: `fmt - filter for simple filling of text'.
+
+   Please write the comments in a GNU program in English, because
+English is the one language that nearly all programmers in all
+countries can read.  If you do not write English well, please write
+comments in English as well as you can, then ask other people to help
+rewrite them.  If you can't write comments in English, please find
+someone to work with you and translate your comments into English.
+
+   Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for.  It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion.  If there is anything nonstandard about
+its use (such as an argument of type `char *' which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+   Also explain the significance of the return value, if there is one.
+
+   Please put two spaces after the end of a sentence in your comments,
+so that the Emacs sentence commands will work.  Also, please write
+complete sentences and capitalize the first word.  If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier.  If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., "The identifier lower-case is ...").
+
+   The comment on a function is much clearer if you use the argument
+names to speak about the argument values.  The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself.  Thus, "the inode
+number NODE_NUM" rather than "an inode".
+
+   There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the
+function itself would be off the bottom of the screen.
+
+   There should be a comment on each static variable as well, like this:
+
+     /* Nonzero means truncate lines in the display;
+        zero means continue them.  */
+     int truncate_lines;
+
+   Every `#endif' should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested.  The comment should
+state the condition of the conditional that is ending, _including its
+sense_.  `#else' should have a comment describing the condition _and
+sense_ of the code that follows.  For example:
+
+     #ifdef foo
+       ...
+     #else /* not foo */
+       ...
+     #endif /* not foo */
+     #ifdef foo
+       ...
+     #endif /* foo */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+     #ifndef foo
+       ...
+     #else /* foo */
+       ...
+     #endif /* foo */
+     #ifndef foo
+       ...
+     #endif /* not foo */
+
+\1f
+File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Writing C
+
+Clean Use of C Constructs
+=========================
+
+Please explicitly declare the types of all objects.  For example, you
+should explicitly declare all arguments to functions, and you should
+declare functions to return `int' rather than omitting the `int'.
+
+   Some programmers like to use the GCC `-Wall' option, and change the
+code whenever it issues a warning.  If you want to do this, then do.
+Other programmers prefer not to use `-Wall', because it gives warnings
+for valid and legitimate code which they do not want to change.  If you
+want to do this, then do.  The compiler should be your servant, not
+your master.
+
+   Declarations of external functions and functions to appear later in
+the source file should all go in one place near the beginning of the
+file (somewhere before the first function definition in the file), or
+else should go in a header file.  Don't put `extern' declarations inside
+functions.
+
+   It used to be common practice to use the same local variables (with
+names like `tem') over and over for different values within one
+function.  Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful.  This not only makes programs easier to understand, it also
+facilitates optimization by good compilers.  You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses.  This makes the program even cleaner.
+
+   Don't use local variables or parameters that shadow global
+identifiers.
+
+   Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead.  For example, instead of
+this:
+
+     int    foo,
+            bar;
+
+write either this:
+
+     int foo, bar;
+
+or this:
+
+     int foo;
+     int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+   When you have an `if'-`else' statement nested in another `if'
+statement, always put braces around the `if'-`else'.  Thus, never write
+like this:
+
+     if (foo)
+       if (bar)
+         win ();
+       else
+         lose ();
+
+always like this:
+
+     if (foo)
+       {
+         if (bar)
+           win ();
+         else
+           lose ();
+       }
+
+   If you have an `if' statement nested inside of an `else' statement,
+either write `else if' on one line, like this,
+
+     if (foo)
+       ...
+     else if (bar)
+       ...
+
+with its `then'-part indented like the preceding `then'-part, or write
+the nested `if' within braces like this:
+
+     if (foo)
+       ...
+     else
+       {
+         if (bar)
+           ...
+       }
+
+   Don't declare both a structure tag and variables or typedefs in the
+same declaration.  Instead, declare the structure tag separately and
+then use it to declare the variables or typedefs.
+
+   Try to avoid assignments inside `if'-conditions.  For example, don't
+write this:
+
+     if ((foo = (char *) malloc (sizeof *foo)) == 0)
+       fatal ("virtual memory exhausted");
+
+instead, write this:
+
+     foo = (char *) malloc (sizeof *foo);
+     if (foo == 0)
+       fatal ("virtual memory exhausted");
+
+   Don't make the program ugly to placate `lint'.  Please don't insert
+any casts to `void'.  Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+\1f
+File: standards.info,  Node: Names,  Next: System Portability,  Prev: Syntactic Conventions,  Up: Writing C
+
+Naming Variables and Functions
+==============================
+
+The names of global variables and functions in a program serve as
+comments of a sort.  So don't choose terse names--instead, look for
+names that give useful information about the meaning of the variable or
+function.  In a GNU program, names should be English, like other
+comments.
+
+   Local variable names can be shorter, because they are used only
+within one context, where (presumably) comments explain their purpose.
+
+   Try to limit your use of abbreviations in symbol names.  It is ok to
+make a few abbreviations, explain what they mean, and then use them
+frequently, but don't use lots of obscure abbreviations.
+
+   Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them.  Stick to lower case; reserve
+upper case for macros and `enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+   For example, you should use names like `ignore_space_change_flag';
+don't use names like `iCantReadThis'.
+
+   Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter.  A comment should state both the exact meaning of
+the option and its letter.  For example,
+
+     /* Ignore changes in horizontal whitespace (-b).  */
+     int ignore_space_change_flag;
+
+   When you want to define names with constant integer values, use
+`enum' rather than `#define'.  GDB knows about enumeration constants.
+
+   You might want to make sure that none of the file names would
+conflict the files were loaded onto an MS-DOS file system which
+shortens the names.  You can use the program `doschk' to test for this.
+
+   Some GNU programs were designed to limit themselves to file names of
+14 characters or less, to avoid file name conflicts if they are read
+into older System V systems.  Please preserve this feature in the
+existing GNU programs that have it, but there is no need to do this in
+new GNU programs.  `doschk' also reports file names longer than 14
+characters.
+
+\1f
+File: standards.info,  Node: System Portability,  Next: CPU Portability,  Prev: Names,  Up: Writing C
+
+Portability between System Types
+================================
+
+In the Unix world, "portability" refers to porting to different Unix
+versions.  For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+   The primary purpose of GNU software is to run on top of the GNU
+kernel, compiled with the GNU C compiler, on various types of CPU.  So
+the kinds of portability that are absolutely necessary are quite
+limited.  But it is important to support Linux-based GNU systems, since
+they are the form of GNU that is popular.
+
+   Beyond that, it is good to support the other free operating systems
+(*BSD), and it is nice to support other Unix-like systems if you want
+to.  Supporting a variety of Unix-like systems is desirable, although
+not paramount.  It is usually not too hard, so you may as well do it.
+But you don't have to consider it an obligation, if it does turn out to
+be hard.
+
+   The easiest way to achieve portability to most Unix-like systems is
+to use Autoconf.  It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+   Avoid using the format of semi-internal data bases (e.g.,
+directories) when there is a higher-level alternative (`readdir').
+
+   As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is often a lot of work.  When
+that is the case, it is better to spend your time adding features that
+will be useful on GNU and GNU/Linux, rather than on supporting other
+incompatible systems.
+
+   It is a good idea to define the "feature test macro" `_GNU_SOURCE'
+when compiling your C files.  When you compile on GNU or GNU/Linux,
+this will enable the declarations of GNU library extension functions,
+and that will usually give you a compiler error message if you define
+the same function names in some other way in your program.  (You don't
+have to actually _use_ these functions, if you prefer to make the
+program more portable to other systems.)
+
+   But whether or not you use these GNU extensions, you should avoid
+using their names for any other meanings.  Doing so would make it hard
+to move your code into other GNU programs.
+
+\1f
+File: standards.info,  Node: CPU Portability,  Next: System Functions,  Prev: System Portability,  Up: Writing C
+
+Portability between CPUs
+========================
+
+Even GNU systems will differ because of differences among CPU
+types--for example, difference in byte ordering and alignment
+requirements.  It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+`int' will be less than 32 bits.  We don't support 16-bit machines in
+GNU.
+
+   Similarly, don't make any effort to cater to the possibility that
+`long' will be smaller than predefined types like `size_t'.  For
+example, the following code is ok:
+
+     printf ("size = %lu\n", (unsigned long) sizeof array);
+     printf ("diff = %ld\n", (long) (pointer2 - pointer1));
+
+   1989 Standard C requires this to work, and we know of only one
+counterexample: 64-bit programs on Microsoft Windows IA-64.  We will
+leave it to those who want to port GNU programs to that environment to
+figure out how to do it.
+
+   Predefined file-size types like `off_t' are an exception: they are
+longer than `long' on many platforms, so code like the above won't work
+with them.  One way to print an `off_t' value portably is to print its
+digits yourself, one by one.
+
+   Don't assume that the address of an `int' object is also the address
+of its least-significant byte.  This is false on big-endian machines.
+Thus, don't make the following mistake:
+
+     int c;
+     ...
+     while ((c = getchar()) != EOF)
+       write(file_descriptor, &c, 1);
+
+   When calling functions, you need not worry about the difference
+between pointers of various types, or between pointers and integers.
+On most machines, there's no difference anyway.  As for the few
+machines where there is a difference, all of them support Standard C
+prototypes, so you can use prototypes (perhaps conditionalized to be
+active only in Standard C) to make the code work on those systems.
+
+   In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system.  For example, many GNU programs have error-reporting functions
+that pass their arguments along to `printf' and friends:
+
+     error (s, a1, a2, a3)
+          char *s;
+          char *a1, *a2, *a3;
+     {
+       fprintf (stderr, "error: ");
+       fprintf (stderr, s, a1, a2, a3);
+     }
+
+In practice, this works on all machines, since a pointer is generally
+the widest possible kind of argument; it is much simpler than any
+"correct" alternative.  Be sure _not_ to use a prototype for such
+functions.
+
+   If you have decided to use Standard C, then you can instead define
+`error' using `stdarg.h', and pass the arguments along to `vfprintf'.
+
+   Avoid casting pointers to integers if you can.  Such casts greatly
+reduce portability, and in most programs they are easy to avoid.  In the
+cases where casting pointers to integers is essential--such as, a Lisp
+interpreter which stores type information as well as an address in one
+word--you'll have to make explicit provisions to handle different word
+sizes.  You will also need to make provision for systems in which the
+normal range of addresses you can get from `malloc' starts far away
+from zero.
+
+\1f
+File: standards.info,  Node: System Functions,  Next: Internationalization,  Prev: CPU Portability,  Up: Writing C
+
+Calling System Functions
+========================
+
+C implementations differ substantially.  Standard C reduces but does
+not eliminate the incompatibilities; meanwhile, many GNU packages still
+support pre-standard compilers because this is not hard to do.  This
+chapter gives recommendations for how to use the more-or-less standard C
+library functions to avoid unnecessary loss of portability.
+
+   * Don't use the return value of `sprintf'.  It returns the number of
+     characters written on some systems, but not on all systems.
+
+   * Be aware that `vfprintf' is not always available.
+
+   * `main' should be declared to return type `int'.  It should
+     terminate either by calling `exit' or by returning the integer
+     status code; make sure it cannot ever return an undefined value.
+
+   * Don't declare system functions explicitly.
+
+     Almost any declaration for a system function is wrong on some
+     system.  To minimize conflicts, leave it to the system header
+     files to declare system functions.  If the headers don't declare a
+     function, let it remain undeclared.
+
+     While it may seem unclean to use a function without declaring it,
+     in practice this works fine for most system library functions on
+     the systems where this really happens; thus, the disadvantage is
+     only theoretical.  By contrast, actual declarations have
+     frequently caused actual conflicts.
+
+   * If you must declare a system function, don't specify the argument
+     types.  Use an old-style declaration, not a Standard C prototype.
+     The more you specify about the function, the more likely a
+     conflict.
+
+   * In particular, don't unconditionally declare `malloc' or `realloc'.
+
+     Most GNU programs use those functions just once, in functions
+     conventionally named `xmalloc' and `xrealloc'.  These functions
+     call `malloc' and `realloc', respectively, and check the results.
+
+     Because `xmalloc' and `xrealloc' are defined in your program, you
+     can declare them in other files without any risk of type conflict.
+
+     On most systems, `int' is the same length as a pointer; thus, the
+     calls to `malloc' and `realloc' work fine.  For the few
+     exceptional systems (mostly 64-bit machines), you can use
+     *conditionalized* declarations of `malloc' and `realloc'--or put
+     these declarations in configuration files specific to those
+     systems.
+
+   * The string functions require special treatment.  Some Unix systems
+     have a header file `string.h'; others have `strings.h'.  Neither
+     file name is portable.  There are two things you can do: use
+     Autoconf to figure out which file to include, or don't include
+     either file.
+
+   * If you don't include either strings file, you can't get
+     declarations for the string functions from the header file in the
+     usual way.
+
+     That causes less of a problem than you might think.  The newer
+     standard string functions should be avoided anyway because many
+     systems still don't support them.  The string functions you can
+     use are these:
+
+          strcpy   strncpy   strcat   strncat
+          strlen   strcmp    strncmp
+          strchr   strrchr
+
+     The copy and concatenate functions work fine without a declaration
+     as long as you don't use their values.  Using their values without
+     a declaration fails on systems where the width of a pointer
+     differs from the width of `int', and perhaps in other cases.  It
+     is trivial to avoid using their values, so do that.
+
+     The compare functions and `strlen' work fine without a declaration
+     on most systems, possibly all the ones that GNU software runs on.
+     You may find it necessary to declare them *conditionally* on a few
+     systems.
+
+     The search functions must be declared to return `char *'.  Luckily,
+     there is no variation in the data type they return.  But there is
+     variation in their names.  Some systems give these functions the
+     names `index' and `rindex'; other systems use the names `strchr'
+     and `strrchr'.  Some systems support both pairs of names, but
+     neither pair works on all systems.
+
+     You should pick a single pair of names and use it throughout your
+     program.  (Nowadays, it is better to choose `strchr' and `strrchr'
+     for new programs, since those are the standard names.)  Declare
+     both of those names as functions returning `char *'.  On systems
+     which don't support those names, define them as macros in terms of
+     the other pair.  For example, here is what to put at the beginning
+     of your file (or in a header) if you want to use the names
+     `strchr' and `strrchr' throughout:
+
+          #ifndef HAVE_STRCHR
+          #define strchr index
+          #endif
+          #ifndef HAVE_STRRCHR
+          #define strrchr rindex
+          #endif
+          
+          char *strchr ();
+          char *strrchr ();
+
+   Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
+defined in systems where the corresponding functions exist.  One way to
+get them properly defined is to use Autoconf.
+
+\1f
+File: standards.info,  Node: Internationalization,  Next: Mmap,  Prev: System Functions,  Up: Writing C
+
+Internationalization
+====================
+
+GNU has a library called GNU gettext that makes it easy to translate the
+messages in a program into various languages.  You should use this
+library in every program.  Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+   Using GNU gettext involves putting a call to the `gettext' macro
+around each string that might need translation--like this:
+
+     printf (gettext ("Processing file `%s'..."));
+
+This permits GNU gettext to replace the string `"Processing file
+`%s'..."' with a translated version.
+
+   Once a program uses gettext, please make a point of writing calls to
+`gettext' when you add new strings that call for translation.
+
+   Using GNU gettext in a package involves specifying a "text domain
+name" for the package.  The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package--for example, `fileutils' for the GNU file utilities.
+
+   To enable gettext to work well, avoid writing code that makes
+assumptions about the structure of words or sentences.  When you want
+the precise text of a sentence to vary depending on the data, use two or
+more alternative string constants each containing a complete sentences,
+rather than inserting conditionalized words or phrases into a single
+sentence framework.
+
+   Here is an example of what not to do:
+
+     printf ("%d file%s processed", nfiles,
+             nfiles != 1 ? "s" : "");
+
+The problem with that example is that it assumes that plurals are made
+by adding `s'.  If you apply gettext to the format string, like this,
+
+     printf (gettext ("%d file%s processed"), nfiles,
+             nfiles != 1 ? "s" : "");
+
+the message can use different words, but it will still be forced to use
+`s' for the plural.  Here is a better way:
+
+     printf ((nfiles != 1 ? "%d files processed"
+              : "%d file processed"),
+             nfiles);
+
+This way, you can apply gettext to each of the two strings
+independently:
+
+     printf ((nfiles != 1 ? gettext ("%d files processed")
+              : gettext ("%d file processed")),
+             nfiles);
+
+This can be any method of forming the plural of the word for "file", and
+also handles languages that require agreement in the word for
+"processed".
+
+   A similar problem appears at the level of sentence structure with
+this code:
+
+     printf ("#  Implicit rule search has%s been done.\n",
+             f->tried_implicit ? "" : " not");
+
+Adding `gettext' calls to this code cannot give correct results for all
+languages, because negation in some languages requires adding words at
+more than one place in the sentence.  By contrast, adding `gettext'
+calls does the job straightfowardly if the code starts out like this:
+
+     printf (f->tried_implicit
+             ? "#  Implicit rule search has been done.\n",
+             : "#  Implicit rule search has not been done.\n");
+
+\1f
+File: standards.info,  Node: Mmap,  Prev: Internationalization,  Up: Writing C
+
+Mmap
+====
+
+Don't assume that `mmap' either works on all files or fails for all
+files.  It may work on some files and fail on others.
+
+   The proper way to use `mmap' is to try it on the specific file for
+which you want to use it--and if `mmap' doesn't work, fall back on
+doing the job in another way using `read' and `write'.
+
+   The reason this precaution is needed is that the GNU kernel (the
+HURD) provides a user-extensible file system, in which there can be many
+different kinds of "ordinary files."  Many of them support `mmap', but
+some do not.  It is important to make programs handle all these kinds
+of files.
+
+\1f
+File: standards.info,  Node: Documentation,  Next: Managing Releases,  Prev: Writing C,  Up: Top
+
+Documenting Programs
+********************
+
+A GNU program should ideally come with full free documentation, adequate
+for both reference and tutorial purposes.  If the package can be
+programmed or extended, the documentation should cover programming or
+extending it, as well as just using it.
+
+* Menu:
+
+* GNU Manuals::                 Writing proper manuals.
+* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
+* Manual Structure Details::    Specific structure conventions.
+* License for Manuals::         Writing the distribution terms for a manual.
+* Manual Credits::              Giving credit to documentation contributors.
+* Printed Manuals::             Mentioning the printed manual.
+* NEWS File::                   NEWS files supplement manuals.
+* Change Logs::                 Recording Changes
+* Man Pages::                   Man pages are secondary.
+* Reading other Manuals::       How far you can go in learning
+                                from other manuals.
+
+\1f
+File: standards.info,  Node: GNU Manuals,  Next: Doc Strings and Manuals,  Up: Documentation
+
+GNU Manuals
+===========
+
+The preferred document format for the GNU system is the Texinfo
+formatting language.  Every GNU package should (ideally) have
+documentation in Texinfo both for reference and for learners.  Texinfo
+makes it possible to produce a good quality formatted book, using TeX,
+and to generate an Info file.  It is also possible to generate HTML
+output from Texinfo source.  See the Texinfo manual, either the
+hardcopy, or the on-line version available through `info' or the Emacs
+Info subsystem (`C-h i').
+
+   Nowadays some other formats such as Docbook and Sgmltexi can be
+converted automatically into Texinfo.  It is ok to produce the Texinfo
+documentation by conversion this way, as long as it gives good results.
+
+   Programmers often find it most natural to structure the documentation
+following the structure of the implementation, which they know.  But
+this structure is not necessarily good for explaining how to use the
+program; it may be irrelevant and confusing for a user.
+
+   At every level, from the sentences in a paragraph to the grouping of
+topics into separate manuals, the right way to structure documentation
+is according to the concepts and questions that a user will have in mind
+when reading it.  Sometimes this structure of ideas matches the
+structure of the implementation of the software being documented--but
+often they are different.  Often the most important part of learning to
+write good documentation is learning to notice when you are structuring
+the documentation like the implementation, and think about better
+alternatives.
+
+   For example, each program in the GNU system probably ought to be
+documented in one manual; but this does not mean each program should
+have its own manual.  That would be following the structure of the
+implementation, rather than the structure that helps the user
+understand.
+
+   Instead, each manual should cover a coherent _topic_.  For example,
+instead of a manual for `diff' and a manual for `diff3', we have one
+manual for "comparison of files" which covers both of those programs,
+as well as `cmp'.  By documenting these programs together, we can make
+the whole subject clearer.
+
+   The manual which discusses a program should certainly document all of
+the program's command-line options and all of its commands.  It should
+give examples of their use.  But don't organize the manual as a list of
+features.  Instead, organize it logically, by subtopics.  Address the
+questions that a user will ask when thinking about the job that the
+program does.
+
+   In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside).  A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.  The
+Bison manual is a good example of this--please take a look at it to see
+what we mean.
+
+   That is not as hard as it first sounds.  Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense.  Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs.  The watchword is, _at each point, address the
+most fundamental and important issue raised by the preceding text._
+
+   If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject.  These provide
+the framework for a beginner to understand the rest of the manual.  The
+Bison manual provides a good example of how to do this.
+
+   To serve as a reference, a manual should have an Index that list all
+the functions, variables, options, and important concepts that are part
+of the program.  One combined Index should do for a short manual, but
+sometimes for a complex package it is better to use multiple indices.
+The Texinfo manual includes advice on preparing good index entries, see
+*Note Making Index Entries: (texinfo)Index Entries, and see *Note
+Defining the Entries of an Index: (texinfo)Indexing Commands.
+
+   Don't use Unix man pages as a model for how to write GNU
+documentation; most of them are terse, badly structured, and give
+inadequate explanation of the underlying concepts.  (There are, of
+course, some exceptions.)  Also, Unix man pages use a particular format
+which is different from what we use in GNU manuals.
+
+   Please include an email address in the manual for where to report
+bugs _in the manual_.
+
+   Please do not use the term "pathname" that is used in Unix
+documentation; use "file name" (two words) instead.  We use the term
+"path" only for search paths, which are lists of directory names.
+
+   Please do not use the term "illegal" to refer to erroneous input to a
+computer program.  Please use "invalid" for this, and reserve the term
+"illegal" for activities punishable by law.
+
+\1f
+File: standards.info,  Node: Doc Strings and Manuals,  Next: Manual Structure Details,  Prev: GNU Manuals,  Up: Documentation
+
+Doc Strings and Manuals
+=======================
+
+Some programming systems, such as Emacs, provide a documentation string
+for each function, command or variable.  You may be tempted to write a
+reference manual by compiling the documentation strings and writing a
+little additional text to go around them--but you must not do it.  That
+approach is a fundamental mistake.  The text of well-written
+documentation strings will be entirely wrong for a manual.
+
+   A documentation string needs to stand alone--when it appears on the
+screen, there will be no other text to introduce or explain it.
+Meanwhile, it can be rather informal in style.
+
+   The text describing a function or variable in a manual must not stand
+alone; it appears in the context of a section or subsection.  Other text
+at the beginning of the section should explain some of the concepts, and
+should often make some general points that apply to several functions or
+variables.  The previous descriptions of functions and variables in the
+section will also have given information about the topic.  A description
+written to stand alone would repeat some of that information; this
+redundance looks bad.  Meanwhile, the informality that is acceptable in
+a documentation string is totally unacceptable in a manual.
+
+   The only good way to use documentation strings in writing a good
+manual is to use them as a source of information for writing good text.
+
+\1f
+File: standards.info,  Node: Manual Structure Details,  Next: License for Manuals,  Prev: Doc Strings and Manuals,  Up: Documentation
+
+Manual Structure Details
+========================
+
+The title page of the manual should state the version of the programs or
+packages documented in the manual.  The Top node of the manual should
+also contain this information.  If the manual is changing more
+frequently than or independent of the program, also state a version
+number for the manual in both of these places.
+
+   Each program documented in the manual should have a node named
+`PROGRAM Invocation' or `Invoking PROGRAM'.  This node (together with
+its subnodes, if any) should describe the program's command line
+arguments and how to run it (the sort of information people would look
+in a man page for).  Start with an `@example' containing a template for
+all the options and arguments that the program uses.
+
+   Alternatively, put a menu item in some menu whose item name fits one
+of the above patterns.  This identifies the node which that item points
+to as the node for this purpose, regardless of the node's actual name.
+
+   The `--usage' feature of the Info reader looks for such a node or
+menu item in order to find the relevant text, so it is essential for
+every Texinfo file to have one.
+
+   If one manual describes several programs, it should have such a node
+for each program described in the manual.
+
+\1f
+File: standards.info,  Node: License for Manuals,  Next: Manual Credits,  Prev: Manual Structure Details,  Up: Documentation
+
+License for Manuals
+===================
+
+Please use the GNU Free Documentation License for all GNU manuals that
+are more than a few pages long.  Likewise for a collection of short
+documents--you only need one copy of the GNU FDL for the whole
+collection.  For a single short document, you can use a very permissive
+non-copyleft license, to avoid taking up space with a long license.
+
+   See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
+of how to employ the GFDL.
+
+   Note that it is not obligatory to include a copy of the GNU GPL or
+GNU LGPL in a manual whose license is neither the GPL nor the LGPL.  It
+can be a good idea to include the program's license in a large manual;
+in a short manual, whose size would be increased considerably by
+including the program's license, it is probably better not to include
+it.
+
+\1f
+File: standards.info,  Node: Manual Credits,  Next: Printed Manuals,  Prev: License for Manuals,  Up: Documentation
+
+Manual Credits
+==============
+
+Please credit the principal human writers of the manual as the authors,
+on the title page of the manual.  If a company sponsored the work, thank
+the company in a suitable place in the manual, but do not cite the
+company as an author.
+
+\1f
+File: standards.info,  Node: Printed Manuals,  Next: NEWS File,  Prev: Manual Credits,  Up: Documentation
+
+Printed Manuals
+===============
+
+The FSF publishes some GNU manuals in printed form.  To encourage sales
+of these manuals, the on-line versions of the manual should mention at
+the very start that the printed manual is available and should point at
+information for getting it--for instance, with a link to the page
+<http://www.gnu.org/order/order.html>.  This should not be included in
+the printed manual, though, because there it is redundant.
+
+   It is also useful to explain in the on-line forms of the manual how
+the user can print out the manual from the sources.
+
+\1f
+File: standards.info,  Node: NEWS File,  Next: Change Logs,  Prev: Printed Manuals,  Up: Documentation
+
+The NEWS File
+=============
+
+In addition to its manual, the package should have a file named `NEWS'
+which contains a list of user-visible changes worth mentioning.  In
+each new release, add items to the front of the file and identify the
+version they pertain to.  Don't discard old items; leave them in the
+file after the newer items.  This way, a user upgrading from any
+previous version can see what is new.
+
+   If the `NEWS' file gets very long, move some of the older items into
+a file named `ONEWS' and put a note at the end referring the user to
+that file.
+
+\1f
+File: standards.info,  Node: Change Logs,  Next: Man Pages,  Prev: NEWS File,  Up: Documentation
+
+Change Logs
+===========
+
+Keep a change log to describe all the changes made to program source
+files.  The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help you eliminate conceptual
+inconsistencies between different parts of a program, by giving you a
+history of how the conflicting concepts arose and who they came from.
+
+* Menu:
+
+* Change Log Concepts::
+* Style of Change Logs::
+* Simple Changes::
+* Conditional Changes::
+* Indicating the Part Changed::
+
+\1f
+File: standards.info,  Node: Change Log Concepts,  Next: Style of Change Logs,  Up: Change Logs
+
+Change Log Concepts
+-------------------
+
+You can think of the change log as a conceptual "undo list" which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log to
+tell them what is in it.  What they want from a change log is a clear
+explanation of how the earlier version differed.
+
+   The change log file is normally called `ChangeLog' and covers an
+entire directory.  Each directory can have its own change log, or a
+directory can use the change log of its parent directory-it's up to you.
+
+   Another alternative is to record change log information with a
+version control system such as RCS or CVS.  This can be converted
+automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
+command `C-x v a' (`vc-update-change-log') does the job.
+
+   There's no need to describe the full purpose of the changes or how
+they work together.  If you think that a change calls for explanation,
+you're probably right.  Please do explain it--but please put the
+explanation in comments in the code, where people will see it whenever
+they see the code.  For example, "New function" is enough for the
+change log when you add a function, because there should be a comment
+before the function definition to explain what it does.
+
+   However, sometimes it is useful to write one line to describe the
+overall purpose of a batch of changes.
+
+   The easiest way to add an entry to `ChangeLog' is with the Emacs
+command `M-x add-change-log-entry'.  An entry should have an asterisk,
+the name of the changed file, and then in parentheses the name of the
+changed functions, variables or whatever, followed by a colon.  Then
+describe the changes you made to that function or variable.
+
+\1f
+File: standards.info,  Node: Style of Change Logs,  Next: Simple Changes,  Prev: Change Log Concepts,  Up: Change Logs
+
+Style of Change Logs
+--------------------
+
+Here are some simple examples of change log entries, starting with the
+header line that says who made the change and when, followed by
+descriptions of specific changes.  (These examples are drawn from Emacs
+and GCC.)
+
+     1998-08-17  Richard Stallman  <rms@gnu.org>
+     
+     * register.el (insert-register): Return nil.
+     (jump-to-register): Likewise.
+     
+     * sort.el (sort-subr): Return nil.
+     
+     * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+     Restart the tex shell if process is gone or stopped.
+     (tex-shell-running): New function.
+     
+     * expr.c (store_one_arg): Round size up for move_block_to_reg.
+     (expand_call): Round up when emitting USE insns.
+     * stmt.c (assign_parms): Round size up for move_block_from_reg.
+
+   It's important to name the changed function or variable in full.
+Don't abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find all
+the change log entries that pertain to it; if you abbreviate the name,
+they won't find it when they search.
+
+   For example, some people are tempted to abbreviate groups of function
+names by writing `* register.el ({insert,jump-to}-register)'; this is
+not a good idea, since searching for `jump-to-register' or
+`insert-register' would not find that entry.
+
+   Separate unrelated change log entries with blank lines.  When two
+entries represent parts of the same change, so that they work together,
+then don't put blank lines between them.  Then you can omit the file
+name and the asterisk when successive entries are in the same file.
+
+   Break long lists of function names by closing continued lines with
+`)', rather than `,', and opening the continuation with `(' as in this
+example:
+
+     * keyboard.c (menu_bar_items, tool_bar_items)
+     (Fexecute_extended_command): Deal with `keymap' property.
+
+\1f
+File: standards.info,  Node: Simple Changes,  Next: Conditional Changes,  Prev: Style of Change Logs,  Up: Change Logs
+
+Simple Changes
+--------------
+
+Certain simple kinds of changes don't need much detail in the change
+log.
+
+   When you change the calling sequence of a function in a simple
+fashion, and you change all the callers of the function to use the new
+calling sequence, there is no need to make individual entries for all
+the callers that you changed.  Just write in the entry for the function
+being called, "All callers changed"--like this:
+
+     * keyboard.c (Fcommand_execute): New arg SPECIAL.
+     All callers changed.
+
+   When you change just comments or doc strings, it is enough to write
+an entry for the file, without mentioning the functions.  Just "Doc
+fixes" is enough for the change log.
+
+   There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix.  Documentation does not consist of parts that must interact in a
+precisely engineered fashion.  To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare what the
+documentation says with the way the program actually works.
+
+\1f
+File: standards.info,  Node: Conditional Changes,  Next: Indicating the Part Changed,  Prev: Simple Changes,  Up: Change Logs
+
+Conditional Changes
+-------------------
+
+C programs often contain compile-time `#if' conditionals.  Many changes
+are conditional; sometimes you add a new definition which is entirely
+contained in a conditional.  It is very useful to indicate in the
+change log the conditions for which the change applies.
+
+   Our convention for indicating conditional changes is to use square
+brackets around the name of the condition.
+
+   Here is a simple example, describing a change which is conditional
+but does not have a function or entity name associated with it:
+
+     * xterm.c [SOLARIS2]: Include string.h.
+
+   Here is an entry describing a new definition which is entirely
+conditional.  This new definition for the macro `FRAME_WINDOW_P' is
+used only when `HAVE_X_WINDOWS' is defined:
+
+     * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
+
+   Here is an entry for a change within the function `init_display',
+whose definition as a whole is unconditional, but the changes themselves
+are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
+
+     * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
+
+   Here is an entry for a change that takes affect only when a certain
+macro is _not_ defined:
+
+     (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+
+\1f
+File: standards.info,  Node: Indicating the Part Changed,  Prev: Conditional Changes,  Up: Change Logs
+
+Indicating the Part Changed
+---------------------------
+
+Indicate the part of a function which changed by using angle brackets
+enclosing an indication of what the changed part does.  Here is an entry
+for a change in the part of the function `sh-while-getopts' that deals
+with `sh' commands:
+
+     * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
+     user-specified option string is empty.
+
+\1f
+File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation
+
+Man Pages
+=========
+
+In the GNU project, man pages are secondary.  It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+   When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed.  The time
+you spend on the man page is time taken away from more useful work.
+
+   For a simple program which changes little, updating the man page may
+be a small job.  Then there is little reason not to include a man page,
+if you have one.
+
+   For a large program that changes a great deal, updating a man page
+may be a substantial burden.  If a user offers to donate a man page,
+you may find this gift costly to accept.  It may be better to refuse
+the man page unless the same person agrees to take full responsibility
+for maintaining it--so that you can wash your hands of it entirely.  If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+   When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating.  If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative.  The note should say how to access the Texinfo
+documentation.
+
+\1f
+File: standards.info,  Node: Reading other Manuals,  Prev: Man Pages,  Up: Documentation
+
+Reading other Manuals
+=====================
+
+There may be non-free books or documentation files that describe the
+program you are documenting.
+
+   It is ok to use these documents for reference, just as the author of
+a new algebra textbook can read other books on algebra.  A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject.  But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation.  Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+\1f
+File: standards.info,  Node: Managing Releases,  Next: References,  Prev: Documentation,  Up: Top
+
+The Release Process
+*******************
+
+Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP.  You should set up your software so
+that it can be configured to run on a variety of systems.  Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below.  Doing so
+makes it easy to include your package into the larger framework of all
+GNU software.
+
+* Menu:
+
+* Configuration::               How Configuration Should Work
+* Makefile Conventions::       Makefile Conventions
+* Releases::                    Making Releases
+
+\1f
+File: standards.info,  Node: Configuration,  Next: Makefile Conventions,  Up: Managing Releases
+
+How Configuration Should Work
+=============================
+
+Each GNU distribution should come with a shell script named
+`configure'.  This script is given arguments which describe the kind of
+machine and system you want to compile the program for.
+
+   The `configure' script must record the configuration options so that
+they affect compilation.
+
+   One way to do this is to make a link from a standard name such as
+`config.h' to the proper configuration file for the chosen system.  If
+you use this technique, the distribution should _not_ contain a file
+named `config.h'.  This is so that people won't be able to build the
+program without configuring it first.
+
+   Another thing that `configure' can do is to edit the Makefile.  If
+you do this, the distribution should _not_ contain a file named
+`Makefile'.  Instead, it should include a file `Makefile.in' which
+contains the input used for editing.  Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+   If `configure' does write the `Makefile', then `Makefile' should
+have a target named `Makefile' which causes `configure' to be rerun,
+setting up the same configuration that was set up last time.  The files
+that `configure' reads should be listed as dependencies of `Makefile'.
+
+   All the files which are output from the `configure' script should
+have comments at the beginning explaining that they were generated
+automatically using `configure'.  This is so that users won't think of
+trying to edit them by hand.
+
+   The `configure' script should write a file named `config.status'
+which describes which configuration options were specified when the
+program was last configured.  This file should be a shell script which,
+if run, will recreate the same configuration.
+
+   The `configure' script should accept an option of the form
+`--srcdir=DIRNAME' to specify the directory where sources are found (if
+it is not the current directory).  This makes it possible to build the
+program in a separate directory, so that the actual source directory is
+not modified.
+
+   If the user does not specify `--srcdir', then `configure' should
+check both `.' and `..' to see if it can find the sources.  If it finds
+the sources in one of these places, it should use them from there.
+Otherwise, it should report that it cannot find the sources, and should
+exit with nonzero status.
+
+   Usually the easy way to support `--srcdir' is by editing a
+definition of `VPATH' into the Makefile.  Some rules may need to refer
+explicitly to the specified source directory.  To make this possible,
+`configure' can add to the Makefile a variable named `srcdir' whose
+value is precisely the specified directory.
+
+   The `configure' script should also take an argument which specifies
+the type of system to build the program for.  This argument should look
+like this:
+
+     CPU-COMPANY-SYSTEM
+
+   For example, a Sun 3 might be `m68k-sun-sunos4.1'.
+
+   The `configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine.  Thus, `sun3-sunos4.1'
+would be a valid alias.  For many programs, `vax-dec-ultrix' would be
+an alias for `vax-dec-bsd', simply because the differences between
+Ultrix and BSD are rarely noticeable, but a few programs might need to
+distinguish them.
+
+   There is a shell script called `config.sub' that you can use as a
+subroutine to validate system types and canonicalize aliases.
+
+   Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+`--enable-FEATURE[=PARAMETER]'
+     Configure the package to build and install an optional user-level
+     facility called FEATURE.  This allows users to choose which
+     optional features to include.  Giving an optional PARAMETER of
+     `no' should omit FEATURE, if it is built by default.
+
+     No `--enable' option should *ever* cause one feature to replace
+     another.  No `--enable' option should ever substitute one useful
+     behavior for another useful behavior.  The only proper use for
+     `--enable' is for questions of whether to build part of the program
+     or exclude it.
+
+`--with-PACKAGE'
+     The package PACKAGE will be installed, so configure this package
+     to work with PACKAGE.
+
+     Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
+     `gnu-libc', `gdb', `x', and `x-toolkit'.
+
+     Do not use a `--with' option to specify the file name to use to
+     find certain files.  That is outside the scope of what `--with'
+     options are for.
+
+   All `configure' scripts should accept all of these "detail" options,
+whether or not they make any difference to the particular package at
+hand.  In particular, they should accept any option that starts with
+`--with-' or `--enable-'.  This is so users will be able to configure
+an entire GNU source tree at once with a single set of options.
+
+   You will note that the categories `--with-' and `--enable-' are
+narrow: they *do not* provide a place for any sort of option you might
+think of.  That is deliberate.  We want to limit the possible
+configuration options in GNU software.  We do not want GNU programs to
+have idiosyncratic configuration options.
+
+   Packages that perform part of the compilation process may support
+cross-compilation.  In such a case, the host and target machines for the
+program may be different.
+
+   The `configure' script should normally treat the specified type of
+system as both the host and the target, thus producing a program which
+works for the same type of machine that it runs on.
+
+   To configure a cross-compiler, cross-assembler, or what have you, you
+should specify a target different from the host, using the configure
+option `--target=TARGETTYPE'.  The syntax for TARGETTYPE is the same as
+for the host type.  So the command would look like this:
+
+     ./configure HOSTTYPE --target=TARGETTYPE
+
+   Programs for which cross-operation is not meaningful need not accept
+the `--target' option, because configuring an entire operating system
+for cross-operation is not a meaningful operation.
+
+   Bootstrapping a cross-compiler requires compiling it on a machine
+other than the host it will run on.  Compilation packages accept a
+configuration option `--build=BUILDTYPE' for specifying the
+configuration on which you will compile them, but the configure script
+should normally guess the build machine type (using `config.guess'), so
+this option is probably not necessary.  The host and target types
+normally default from the build type, so in bootstrapping a
+cross-compiler you must specify them both explicitly.
+
+   Some programs have ways of configuring themselves automatically.  If
+your program is set up to do this, your `configure' script can simply
+ignore most of its arguments.
+
+\1f
+File: standards.info,  Node: Makefile Conventions,  Next: Releases,  Prev: Configuration,  Up: Managing Releases
+
+Makefile Conventions
+====================
+
+This node describes conventions for writing the Makefiles for GNU
+programs.  Using Automake will help you write a Makefile that follows
+these conventions.
+
+* Menu:
+
+* Makefile Basics::            General Conventions for Makefiles
+* Utilities in Makefiles::     Utilities in Makefiles
+* Command Variables::          Variables for Specifying Commands
+* Directory Variables::                Variables for Installation Directories
+* Standard Targets::           Standard Targets for Users
+* Install Command Categories::  Three categories of commands in the `install'
+                                  rule: normal, pre-install and post-install.
+
+\1f
+File: standards.info,  Node: Makefile Basics,  Next: Utilities in Makefiles,  Up: Makefile Conventions
+
+General Conventions for Makefiles
+---------------------------------
+
+Every Makefile should contain this line:
+
+     SHELL = /bin/sh
+
+to avoid trouble on systems where the `SHELL' variable might be
+inherited from the environment.  (This is never a problem with GNU
+`make'.)
+
+   Different `make' programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior.  So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+     .SUFFIXES:
+     .SUFFIXES: .c .o
+
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+   Don't assume that `.' is in the path for command execution.  When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses `./' if the program is built as
+part of the make or `$(srcdir)/' if the file is an unchanging part of
+the source code.  Without one of these prefixes, the current search
+path is used.
+
+   The distinction between `./' (the "build directory") and
+`$(srcdir)/' (the "source directory") is important because users can
+build in a separate directory using the `--srcdir' option to
+`configure'.  A rule of the form:
+
+     foo.1 : foo.man sedscript
+             sed -e sedscript foo.man > foo.1
+
+will fail when the build directory is not the source directory, because
+`foo.man' and `sedscript' are in the source directory.
+
+   When using GNU `make', relying on `VPATH' to find the source file
+will work in the case where there is a single dependency file, since
+the `make' automatic variable `$<' will represent the source file
+wherever it is.  (Many versions of `make' set `$<' only in implicit
+rules.)  A Makefile target like
+
+     foo.o : bar.c
+             $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+     foo.o : bar.c
+             $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow `VPATH' to work correctly.  When the target has
+multiple dependencies, using an explicit `$(srcdir)' is the easiest way
+to make the rule work well.  For example, the target above for `foo.1'
+is best written as:
+
+     foo.1 : foo.man sedscript
+             sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+   GNU distributions usually contain some files which are not source
+files--for example, Info files, and the output from Autoconf, Automake,
+Bison or Flex.  Since these files normally appear in the source
+directory, they should always appear in the source directory, not in the
+build directory.  So Makefile rules to update them should put the
+updated files in the source directory.
+
+   However, if a file does not appear in the distribution, then the
+Makefile should not put it in the source directory, because building a
+program in ordinary circumstances should not modify the source directory
+in any way.
+
+   Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel `make'.
+
+\1f
+File: standards.info,  Node: Utilities in Makefiles,  Next: Command Variables,  Prev: Makefile Basics,  Up: Makefile Conventions
+
+Utilities in Makefiles
+----------------------
+
+Write the Makefile commands (and any shell scripts, such as
+`configure') to run in `sh', not in `csh'.  Don't use any special
+features of `ksh' or `bash'.
+
+   The `configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+     cat cmp cp diff echo egrep expr false grep install-info
+     ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+
+   The compression program `gzip' can be used in the `dist' rule.
+
+   Stick to the generally supported options for these programs.  For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+   It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+   The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via `make' variables
+so that the user can substitute alternatives.  Here are some of the
+programs we mean:
+
+     ar bison cc flex install ld ldconfig lex
+     make makeinfo ranlib texi2dvi yacc
+
+   Use the following `make' variables to run those programs:
+
+     $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
+     $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+   When you use `ranlib' or `ldconfig', you should make sure nothing
+bad happens if the system does not have the program in question.
+Arrange to ignore an error from that command, and print a message before
+the command to tell the user that failure of this command does not mean
+a problem.  (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
+
+   If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+   Additional utilities that can be used via Make variables are:
+
+     chgrp chmod chown mknod
+
+   It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+\1f
+File: standards.info,  Node: Command Variables,  Next: Directory Variables,  Prev: Utilities in Makefiles,  Up: Makefile Conventions
+
+Variables for Specifying Commands
+---------------------------------
+
+Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+   In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named `BISON' whose default
+value is set with `BISON = bison', and refer to it with `$(BISON)'
+whenever you need to use Bison.
+
+   File management utilities such as `ln', `rm', `mv', and so on, need
+not be referred to through variables in this way, since users don't
+need to replace them with other programs.
+
+   Each program-name variable should come with an options variable that
+is used to supply options to the program.  Append `FLAGS' to the
+program-name variable name to get the options variable name--for
+example, `BISONFLAGS'.  (The names `CFLAGS' for the C compiler,
+`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
+but we keep them because they are standard.)  Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+   If there are C compiler options that _must_ be used for proper
+compilation of certain files, do not include them in `CFLAGS'.  Users
+expect to be able to specify `CFLAGS' freely themselves.  Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+     CFLAGS = -g
+     ALL_CFLAGS = -I. $(CFLAGS)
+     .c.o:
+             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+   Do include the `-g' option in `CFLAGS', because that is not
+_required_ for proper compilation.  You can consider it a default that
+is only recommended.  If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+   Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+   `CFLAGS' should be used in every invocation of the C compiler, both
+those which do compilation and those which do linking.
+
+   Every Makefile should define the variable `INSTALL', which is the
+basic command for installing a file into the system.
+
+   Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'.  (The default for `INSTALL_PROGRAM' should be
+`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
+644'.)  Then it should use those variables as the commands for actual
+installation, for executables and nonexecutables respectively.  Use
+these variables as follows:
+
+     $(INSTALL_PROGRAM) foo $(bindir)/foo
+     $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+   Optionally, you may prepend the value of `DESTDIR' to the target
+filename.  Doing this allows the installer to create a snapshot of the
+installation to be copied onto the real target filesystem later.  Do not
+set the value of `DESTDIR' in your Makefile, and do not include it in
+any installed files.  With support for `DESTDIR', the above examples
+become:
+
+     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
+     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands.  Use a separate command for each file to be
+installed.
+
+\1f
+File: standards.info,  Node: Directory Variables,  Next: Standard Targets,  Prev: Command Variables,  Up: Makefile Conventions
+
+Variables for Installation Directories
+--------------------------------------
+
+Installation directories should always be named by variables, so it is
+easy to install in a nonstandard place.  The standard names for these
+variables are described below.  They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
+and other modern operating systems.
+
+   These two variables set the root for the installation.  All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+`prefix'
+     A prefix used in constructing the default values of the variables
+     listed below.  The default value of `prefix' should be
+     `/usr/local'.  When building the complete GNU system, the prefix
+     will be empty and `/usr' will be a symbolic link to `/'.  (If you
+     are using Autoconf, write it as `@prefix@'.)
+
+     Running `make install' with a different value of `prefix' from the
+     one used to build the program should _not_ recompile the program.
+
+`exec_prefix'
+     A prefix used in constructing the default values of some of the
+     variables listed below.  The default value of `exec_prefix' should
+     be `$(prefix)'.  (If you are using Autoconf, write it as
+     `@exec_prefix@'.)
+
+     Generally, `$(exec_prefix)' is used for directories that contain
+     machine-specific files (such as executables and subroutine
+     libraries), while `$(prefix)' is used directly for other
+     directories.
+
+     Running `make install' with a different value of `exec_prefix'
+     from the one used to build the program should _not_ recompile the
+     program.
+
+   Executable programs are installed in one of the following
+directories.
+
+`bindir'
+     The directory for installing executable programs that users can
+     run.  This should normally be `/usr/local/bin', but write it as
+     `$(exec_prefix)/bin'.  (If you are using Autoconf, write it as
+     `@bindir@'.)
+
+`sbindir'
+     The directory for installing executable programs that can be run
+     from the shell, but are only generally useful to system
+     administrators.  This should normally be `/usr/local/sbin', but
+     write it as `$(exec_prefix)/sbin'.  (If you are using Autoconf,
+     write it as `@sbindir@'.)
+
+`libexecdir'
+     The directory for installing executable programs to be run by other
+     programs rather than by users.  This directory should normally be
+     `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+     (If you are using Autoconf, write it as `@libexecdir@'.)
+
+   Data files used by the program during its execution are divided into
+categories in two ways.
+
+   * Some files are normally modified by programs; others are never
+     normally modified (though users may edit some of these).
+
+   * Some files are architecture-independent and can be shared by all
+     machines at a site; some are architecture-dependent and can be
+     shared only by machines of the same kind and operating system;
+     others may never be shared between two machines.
+
+   This makes for six different possibilities.  However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries.  It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+   Therefore, here are the variables Makefiles should use to specify
+directories:
+
+`datadir'
+     The directory for installing read-only architecture independent
+     data files.  This should normally be `/usr/local/share', but write
+     it as `$(prefix)/share'.  (If you are using Autoconf, write it as
+     `@datadir@'.)  As a special exception, see `$(infodir)' and
+     `$(includedir)' below.
+
+`sysconfdir'
+     The directory for installing read-only data files that pertain to a
+     single machine-that is to say, files for configuring a host.
+     Mailer and network configuration files, `/etc/passwd', and so
+     forth belong here.  All the files in this directory should be
+     ordinary ASCII text files.  This directory should normally be
+     `/usr/local/etc', but write it as `$(prefix)/etc'.  (If you are
+     using Autoconf, write it as `@sysconfdir@'.)
+
+     Do not install executables here in this directory (they probably
+     belong in `$(libexecdir)' or `$(sbindir)').  Also do not install
+     files that are modified in the normal course of their use (programs
+     whose purpose is to change the configuration of the system
+     excluded).  Those probably belong in `$(localstatedir)'.
+
+`sharedstatedir'
+     The directory for installing architecture-independent data files
+     which the programs modify while they run.  This should normally be
+     `/usr/local/com', but write it as `$(prefix)/com'.  (If you are
+     using Autoconf, write it as `@sharedstatedir@'.)
+
+`localstatedir'
+     The directory for installing data files which the programs modify
+     while they run, and that pertain to one specific machine.  Users
+     should never need to modify files in this directory to configure
+     the package's operation; put such configuration information in
+     separate files that go in `$(datadir)' or `$(sysconfdir)'.
+     `$(localstatedir)' should normally be `/usr/local/var', but write
+     it as `$(prefix)/var'.  (If you are using Autoconf, write it as
+     `@localstatedir@'.)
+
+`libdir'
+     The directory for object files and libraries of object code.  Do
+     not install executables here, they probably ought to go in
+     `$(libexecdir)' instead.  The value of `libdir' should normally be
+     `/usr/local/lib', but write it as `$(exec_prefix)/lib'.  (If you
+     are using Autoconf, write it as `@libdir@'.)
+
+`infodir'
+     The directory for installing the Info files for this package.  By
+     default, it should be `/usr/local/info', but it should be written
+     as `$(prefix)/info'.  (If you are using Autoconf, write it as
+     `@infodir@'.)
+
+`lispdir'
+     The directory for installing any Emacs Lisp files in this package.
+     By default, it should be `/usr/local/share/emacs/site-lisp', but
+     it should be written as `$(prefix)/share/emacs/site-lisp'.
+
+     If you are using Autoconf, write the default as `@lispdir@'.  In
+     order to make `@lispdir@' work, you need the following lines in
+     your `configure.in' file:
+
+          lispdir='${datadir}/emacs/site-lisp'
+          AC_SUBST(lispdir)
+
+`includedir'
+     The directory for installing header files to be included by user
+     programs with the C `#include' preprocessor directive.  This
+     should normally be `/usr/local/include', but write it as
+     `$(prefix)/include'.  (If you are using Autoconf, write it as
+     `@includedir@'.)
+
+     Most compilers other than GCC do not look for header files in
+     directory `/usr/local/include'.  So installing the header files
+     this way is only useful with GCC.  Sometimes this is not a problem
+     because some libraries are only really intended to work with GCC.
+     But some libraries are intended to work with other compilers.
+     They should install their header files in two places, one
+     specified by `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+     The directory for installing `#include' header files for use with
+     compilers other than GCC.  This should normally be `/usr/include'.
+     (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+     The Makefile commands should check whether the value of
+     `oldincludedir' is empty.  If it is, they should not try to use
+     it; they should cancel the second installation of the header files.
+
+     A package should not replace an existing header in this directory
+     unless the header came from the same package.  Thus, if your Foo
+     package provides a header file `foo.h', then it should install the
+     header file in the `oldincludedir' directory if either (1) there
+     is no `foo.h' there or (2) the `foo.h' that exists came from the
+     Foo package.
+
+     To tell whether `foo.h' came from the Foo package, put a magic
+     string in the file--part of a comment--and `grep' for that string.
+
+   Unix-style man pages are installed in one of the following:
+
+`mandir'
+     The top-level directory for installing the man pages (if any) for
+     this package.  It will normally be `/usr/local/man', but you should
+     write it as `$(prefix)/man'.  (If you are using Autoconf, write it
+     as `@mandir@'.)
+
+`man1dir'
+     The directory for installing section 1 man pages.  Write it as
+     `$(mandir)/man1'.
+
+`man2dir'
+     The directory for installing section 2 man pages.  Write it as
+     `$(mandir)/man2'
+
+`...'
+     *Don't make the primary documentation for any GNU software be a
+     man page.  Write a manual in Texinfo instead.  Man pages are just
+     for the sake of people running GNU software on Unix, which is a
+     secondary application only.*
+
+`manext'
+     The file name extension for the installed man page.  This should
+     contain a period followed by the appropriate digit; it should
+     normally be `.1'.
+
+`man1ext'
+     The file name extension for installed section 1 man pages.
+
+`man2ext'
+     The file name extension for installed section 2 man pages.
+
+`...'
+     Use these names instead of `manext' if the package needs to
+     install man pages in more than one section of the manual.
+
+   And finally, you should set the following variable:
+
+`srcdir'
+     The directory for the sources being compiled.  The value of this
+     variable is normally inserted by the `configure' shell script.
+     (If you are using Autconf, use `srcdir = @srcdir@'.)
+
+   For example:
+
+     # Common prefix for installation directories.
+     # NOTE: This directory must exist when you start the install.
+     prefix = /usr/local
+     exec_prefix = $(prefix)
+     # Where to put the executable for the command `gcc'.
+     bindir = $(exec_prefix)/bin
+     # Where to put the directories used by the compiler.
+     libexecdir = $(exec_prefix)/libexec
+     # Where to put the Info files.
+     infodir = $(prefix)/info
+
+   If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the `install' rule to create these subdirectories.
+
+   Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above.  The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
+\1f
+File: standards.info,  Node: Standard Targets,  Next: Install Command Categories,  Prev: Directory Variables,  Up: Makefile Conventions
+
+Standard Targets for Users
+--------------------------
+
+All GNU programs should have the following targets in their Makefiles:
+
+`all'
+     Compile the entire program.  This should be the default target.
+     This target need not rebuild any documentation files; Info files
+     should normally be included in the distribution, and DVI files
+     should be made only when explicitly asked for.
+
+     By default, the Make rules should compile and link with `-g', so
+     that executable programs have debugging symbols.  Users who don't
+     mind being helpless can strip the executables later if they wish.
+
+`install'
+     Compile the program and copy the executables, libraries, and so on
+     to the file names where they should reside for actual use.  If
+     there is a simple test to verify that a program is properly
+     installed, this target should run that test.
+
+     Do not strip executables when installing them.  Devil-may-care
+     users can use the `install-strip' target to do that.
+
+     If possible, write the `install' target rule so that it does not
+     modify anything in the directory where the program was built,
+     provided `make all' has just been done.  This is convenient for
+     building the program under one user name and installing it under
+     another.
+
+     The commands should create all the directories in which files are
+     to be installed, if they don't already exist.  This includes the
+     directories specified as the values of the variables `prefix' and
+     `exec_prefix', as well as all subdirectories that are needed.  One
+     way to do this is by means of an `installdirs' target as described
+     below.
+
+     Use `-' before any command for installing a man page, so that
+     `make' will ignore any errors.  This is in case there are systems
+     that don't have the Unix man page documentation system installed.
+
+     The way to install Info files is to copy them into `$(infodir)'
+     with `$(INSTALL_DATA)' (*note Command Variables::), and then run
+     the `install-info' program if it is present.  `install-info' is a
+     program that edits the Info `dir' file to add or update the menu
+     entry for the given Info file; it is part of the Texinfo package.
+     Here is a sample rule to install an Info file:
+
+          $(DESTDIR)$(infodir)/foo.info: foo.info
+                  $(POST_INSTALL)
+          # There may be a newer info file in . than in srcdir.
+                  -if test -f foo.info; then d=.; \
+                   else d=$(srcdir); fi; \
+                  $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
+          # Run install-info only if it exists.
+          # Use `if' instead of just prepending `-' to the
+          # line so we notice real errors from install-info.
+          # We use `$(SHELL) -c' because some shells do not
+          # fail gracefully when there is an unknown command.
+                  if $(SHELL) -c 'install-info --version' \
+                     >/dev/null 2>&1; then \
+                    install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+                                 $(DESTDIR)$(infodir)/foo.info; \
+                  else true; fi
+
+     When writing the `install' target, you must classify all the
+     commands into three categories: normal ones, "pre-installation"
+     commands and "post-installation" commands.  *Note Install Command
+     Categories::.
+
+`uninstall'
+     Delete all the installed files--the copies that the `install'
+     target creates.
+
+     This rule should not modify the directories where compilation is
+     done, only the directories where files are installed.
+
+     The uninstallation commands are divided into three categories,
+     just like the installation commands.  *Note Install Command
+     Categories::.
+
+`install-strip'
+     Like `install', but strip the executable files while installing
+     them.  In simple cases, this target can use the `install' target in
+     a simple way:
+
+          install-strip:
+                  $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+                          install
+
+     But if the package installs scripts as well as real executables,
+     the `install-strip' target can't just refer to the `install'
+     target; it has to strip the executables but not the scripts.
+
+     `install-strip' should not strip the executables in the build
+     directory which are being copied for installation.  It should only
+     strip the copies that are installed.
+
+     Normally we do not recommend stripping an executable unless you
+     are sure the program has no bugs.  However, it can be reasonable
+     to install a stripped executable for actual execution while saving
+     the unstripped executable elsewhere in case there is a bug.
+
+`clean'
+     Delete all files from the current directory that are normally
+     created by building the program.  Don't delete the files that
+     record the configuration.  Also preserve files that could be made
+     by building, but normally aren't because the distribution comes
+     with them.
+
+     Delete `.dvi' files here if they are not part of the distribution.
+
+`distclean'
+     Delete all files from the current directory that are created by
+     configuring or building the program.  If you have unpacked the
+     source and built the program without creating any other files,
+     `make distclean' should leave only the files that were in the
+     distribution.
+
+`mostlyclean'
+     Like `clean', but may refrain from deleting a few files that people
+     normally don't want to recompile.  For example, the `mostlyclean'
+     target for GCC does not delete `libgcc.a', because recompiling it
+     is rarely necessary and takes a lot of time.
+
+`maintainer-clean'
+     Delete almost everything from the current directory that can be
+     reconstructed with this Makefile.  This typically includes
+     everything deleted by `distclean', plus more: C source files
+     produced by Bison, tags tables, Info files, and so on.
+
+     The reason we say "almost everything" is that running the command
+     `make maintainer-clean' should not delete `configure' even if
+     `configure' can be remade using a rule in the Makefile.  More
+     generally, `make maintainer-clean' should not delete anything that
+     needs to exist in order to run `configure' and then begin to build
+     the program.  This is the only exception; `maintainer-clean' should
+     delete everything else that can be rebuilt.
+
+     The `maintainer-clean' target is intended to be used by a
+     maintainer of the package, not by ordinary users.  You may need
+     special tools to reconstruct some of the files that `make
+     maintainer-clean' deletes.  Since these files are normally
+     included in the distribution, we don't take care to make them easy
+     to reconstruct.  If you find you need to unpack the full
+     distribution again, don't blame us.
+
+     To help make users aware of this, the commands for the special
+     `maintainer-clean' target should start with these two:
+
+          @echo 'This command is intended for maintainers to use; it'
+          @echo 'deletes files that may need special tools to rebuild.'
+
+`TAGS'
+     Update a tags table for this program.
+
+`info'
+     Generate any Info files needed.  The best way to write the rules
+     is as follows:
+
+          info: foo.info
+          
+          foo.info: foo.texi chap1.texi chap2.texi
+                  $(MAKEINFO) $(srcdir)/foo.texi
+
+     You must define the variable `MAKEINFO' in the Makefile.  It should
+     run the `makeinfo' program, which is part of the Texinfo
+     distribution.
+
+     Normally a GNU distribution comes with Info files, and that means
+     the Info files are present in the source directory.  Therefore,
+     the Make rule for an info file should update it in the source
+     directory.  When users build the package, ordinarily Make will not
+     update the Info files because they will already be up to date.
+
+`dvi'
+     Generate DVI files for all Texinfo documentation.  For example:
+
+          dvi: foo.dvi
+          
+          foo.dvi: foo.texi chap1.texi chap2.texi
+                  $(TEXI2DVI) $(srcdir)/foo.texi
+
+     You must define the variable `TEXI2DVI' in the Makefile.  It should
+     run the program `texi2dvi', which is part of the Texinfo
+     distribution.(1)  Alternatively, write just the dependencies, and
+     allow GNU `make' to provide the command.
+
+`dist'
+     Create a distribution tar file for this program.  The tar file
+     should be set up so that the file names in the tar file start with
+     a subdirectory name which is the name of the package it is a
+     distribution for.  This name can include the version number.
+
+     For example, the distribution tar file of GCC version 1.40 unpacks
+     into a subdirectory named `gcc-1.40'.
+
+     The easiest way to do this is to create a subdirectory
+     appropriately named, use `ln' or `cp' to install the proper files
+     in it, and then `tar' that subdirectory.
+
+     Compress the tar file with `gzip'.  For example, the actual
+     distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
+
+     The `dist' target should explicitly depend on all non-source files
+     that are in the distribution, to make sure they are up to date in
+     the distribution.  *Note Making Releases: Releases.
+
+`check'
+     Perform self-tests (if any).  The user must build the program
+     before running the tests, but need not install the program; you
+     should write the self-tests so that they work when the program is
+     built but not installed.
+
+   The following targets are suggested as conventional names, for
+programs in which they are useful.
+
+`installcheck'
+     Perform installation tests (if any).  The user must build and
+     install the program before running the tests.  You should not
+     assume that `$(bindir)' is in the search path.
+
+`installdirs'
+     It's useful to add a target named `installdirs' to create the
+     directories where files are installed, and their parent
+     directories.  There is a script called `mkinstalldirs' which is
+     convenient for this; you can find it in the Texinfo package.  You
+     can use a rule like this:
+
+          # Make sure all installation directories (e.g. $(bindir))
+          # actually exist by making them if necessary.
+          installdirs: mkinstalldirs
+                  $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+                                          $(libdir) $(infodir) \
+                                          $(mandir)
+
+     or, if you wish to support `DESTDIR',
+
+          # Make sure all installation directories (e.g. $(bindir))
+          # actually exist by making them if necessary.
+          installdirs: mkinstalldirs
+                  $(srcdir)/mkinstalldirs \
+                      $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
+                      $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
+                      $(DESTDIR)$(mandir)
+
+     This rule should not modify the directories where compilation is
+     done.  It should do nothing but create installation directories.
+
+   ---------- Footnotes ----------
+
+   (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
+not distributed with Texinfo.
+
+\1f
+File: standards.info,  Node: Install Command Categories,  Prev: Standard Targets,  Up: Makefile Conventions
+
+Install Command Categories
+--------------------------
+
+When writing the `install' target, you must classify all the commands
+into three categories: normal ones, "pre-installation" commands and
+"post-installation" commands.
+
+   Normal commands move files into their proper places, and set their
+modes.  They may not alter any files except the ones that come entirely
+from the package they belong to.
+
+   Pre-installation and post-installation commands may alter other
+files; in particular, they can edit global configuration files or data
+bases.
+
+   Pre-installation commands are typically executed before the normal
+commands, and post-installation commands are typically run after the
+normal commands.
+
+   The most common use for a post-installation command is to run
+`install-info'.  This cannot be done with a normal command, since it
+alters a file (the Info directory) which does not come entirely and
+solely from the package being installed.  It is a post-installation
+command because it needs to be done after the normal command which
+installs the package's Info files.
+
+   Most programs don't need any pre-installation commands, but we have
+the feature just in case it is needed.
+
+   To classify the commands in the `install' rule into these three
+categories, insert "category lines" among them.  A category line
+specifies the category for the commands that follow.
+
+   A category line consists of a tab and a reference to a special Make
+variable, plus an optional comment at the end.  There are three
+variables you can use, one for each category; the variable name
+specifies the category.  Category lines are no-ops in ordinary execution
+because these three Make variables are normally undefined (and you
+_should not_ define them in the makefile).
+
+   Here are the three possible category lines, each with a comment that
+explains what it means:
+
+             $(PRE_INSTALL)     # Pre-install commands follow.
+             $(POST_INSTALL)    # Post-install commands follow.
+             $(NORMAL_INSTALL)  # Normal commands follow.
+
+   If you don't use a category line at the beginning of the `install'
+rule, all the commands are classified as normal until the first category
+line.  If you don't use any category lines, all the commands are
+classified as normal.
+
+   These are the category lines for `uninstall':
+
+             $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
+             $(POST_UNINSTALL)    # Post-uninstall commands follow.
+             $(NORMAL_UNINSTALL)  # Normal commands follow.
+
+   Typically, a pre-uninstall command would be used for deleting entries
+from the Info directory.
+
+   If the `install' or `uninstall' target has any dependencies which
+act as subroutines of installation, then you should start _each_
+dependency's commands with a category line, and start the main target's
+commands with a category line also.  This way, you can ensure that each
+command is placed in the right category regardless of which of the
+dependencies actually run.
+
+   Pre-installation and post-installation commands should not run any
+programs except for these:
+
+     [ basename bash cat chgrp chmod chown cmp cp dd diff echo
+     egrep expand expr false fgrep find getopt grep gunzip gzip
+     hostname install install-info kill ldconfig ln ls md5sum
+     mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
+     test touch true uname xargs yes
+
+   The reason for distinguishing the commands in this way is for the
+sake of making binary packages.  Typically a binary package contains
+all the executables and other files that need to be installed, and has
+its own method of installing them--so it does not need to run the normal
+installation commands.  But installing the binary package does need to
+execute the pre-installation and post-installation commands.
+
+   Programs to build binary packages work by extracting the
+pre-installation and post-installation commands.  Here is one way of
+extracting the pre-installation commands:
+
+     make -n install -o all \
+           PRE_INSTALL=pre-install \
+           POST_INSTALL=post-install \
+           NORMAL_INSTALL=normal-install \
+       | gawk -f pre-install.awk
+
+where the file `pre-install.awk' could contain this:
+
+     $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
+     on {print $0}
+     $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
+
+   The resulting file of pre-installation commands is executed as a
+shell script as part of installing the binary package.
+
+\1f
+File: standards.info,  Node: Releases,  Prev: Makefile Conventions,  Up: Managing Releases
+
+Making Releases
+===============
+
+Package the distribution of `Foo version 69.96' up in a gzipped tar
+file with the name `foo-69.96.tar.gz'.  It should unpack into a
+subdirectory named `foo-69.96'.
+
+   Building and installing the program should never modify any of the
+files contained in the distribution.  This means that all the files
+that form part of the program in any way must be classified into "source
+files" and "non-source files".  Source files are written by humans and
+never changed automatically; non-source files are produced from source
+files by programs under the control of the Makefile.
+
+   The distribution should contain a file named `README' which gives
+the name of the package, and a general description of what it does.  It
+is also good to explain the purpose of each of the first-level
+subdirectories in the package, if there are any.  The `README' file
+should either state the version number of the package, or refer to where
+in the package it can be found.
+
+   The `README' file should refer to the file `INSTALL', which should
+contain an explanation of the installation procedure.
+
+   The `README' file should also refer to the file which contains the
+copying conditions.  The GNU GPL, if used, should be in a file called
+`COPYING'.  If the GNU LGPL is used, it should be in a file called
+`COPYING.LIB'.
+
+   Naturally, all the source files must be in the distribution.  It is
+okay to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them.  We commonly include non-source files
+produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+   Non-source files that might actually be modified by building and
+installing the program should *never* be included in the distribution.
+So if you do distribute non-source files, always make sure they are up
+to date when you make a new distribution.
+
+   Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of `tar' which preserve the ownership and
+permissions of the files from the tar archive will be able to extract
+all the files even if the user is unprivileged.
+
+   Make sure that all the files in the distribution are world-readable.
+
+   Make sure that no file name in the distribution is more than 14
+characters long.  Likewise, no file created by building the program
+should have a name longer than 14 characters.  The reason for this is
+that some systems adhere to a foolish interpretation of the POSIX
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+   Don't include any symbolic links in the distribution itself.  If the
+tar file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links.  Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the distribution.
+
+   Try to make sure that all the file names will be unique on MS-DOS.  A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters.  MS-DOS will truncate extra
+characters both before and after the period.  Thus, `foobarhacker.c'
+and `foobarhacker.o' are not ambiguous; they are truncated to
+`foobarha.c' and `foobarha.o', which are distinct.
+
+   Include in your distribution a copy of the `texinfo.tex' you used to
+test print any `*.texinfo' or `*.texi' files.
+
+   Likewise, if your program uses small GNU software packages like
+regex, getopt, obstack, or termcap, include them in the distribution
+file.  Leaving them out would make the distribution file a little
+smaller at the expense of possible inconvenience to a user who doesn't
+know what other files to get.
+
+\1f
+File: standards.info,  Node: References,  Next: Index,  Prev: Managing Releases,  Up: Top
+
+References to Non-Free Software and Documentation
+*************************************************
+
+A GNU program should not recommend use of any non-free program.  We
+can't stop some people from writing proprietary programs, or stop other
+people from using them.  But we can and should avoid helping to
+advertise them to new customers.
+
+   Sometimes it is important to mention how to build your package on
+top of some non-free operating system or other non-free base package.
+In such cases, please mention the name of the non-free package or
+system in the briefest possible way.  Don't include any references for
+where to find more information about the proprietary program.  The goal
+should be that people already using the proprietary program will get
+the advice they need about how to use your free program, while people
+who don't already use the proprietary program will not see anything to
+encourage them to take an interest in it.
+
+   Likewise, a GNU package should not refer the user to any non-free
+documentation for free software.  The need for free documentation to go
+with free software is now a major focus of the GNU project; to show that
+we are serious about the need for free documentation, we must not
+undermine our position by recommending use of documentation that isn't
+free.
+
+\1f
+File: standards.info,  Node: Index,  Prev: References,  Up: Top
+
+Index
+*****
+
+* Menu:
+
+* #endif, commenting:                    Comments.
+* --help option:                         Command-Line Interfaces.
+* --version option:                      Command-Line Interfaces.
+* -Wall compiler option:                 Syntactic Conventions.
+* accepting contributions:               Contributions.
+* address for bug reports:               Command-Line Interfaces.
+* ANSI C standard:                       Standard C.
+* arbitrary limits on data:              Semantics.
+* autoconf:                              System Portability.
+* avoiding proprietary code:             Reading Non-Free Code.
+* behavior, dependent on program's name: User Interfaces.
+* binary packages:                       Install Command Categories.
+* bindir:                                Directory Variables.
+* braces, in C source:                   Formatting.
+* bug reports:                           Command-Line Interfaces.
+* canonical name of a program:           Command-Line Interfaces.
+* casting pointers to integers:          CPU Portability.
+* change logs:                           Change Logs.
+* change logs, conditional changes:      Conditional Changes.
+* change logs, style:                    Style of Change Logs.
+* command-line arguments, decoding:      Semantics.
+* command-line interface:                Command-Line Interfaces.
+* commenting:                            Comments.
+* compatibility with C and POSIX standards: Compatibility.
+* compiler warnings:                     Syntactic Conventions.
+* conditional changes, and change logs:  Conditional Changes.
+* conditionals, comments for:            Comments.
+* configure:                             Configuration.
+* control-L:                             Formatting.
+* conventions for makefiles:             Makefile Conventions.
+* corba:                                 Graphical Interfaces.
+* credits for manuals:                   Manual Credits.
+* data types, and portability:           CPU Portability.
+* declaration for system functions:      System Functions.
+* documentation:                         Documentation.
+* doschk:                                Names.
+* downloading this manual:               Preface.
+* error messages:                        Semantics.
+* error messages, formatting:            Errors.
+* exec_prefix:                           Directory Variables.
+* expressions, splitting:                Formatting.
+* file usage:                            File Usage.
+* file-name limitations:                 Names.
+* formatting error messages:             Errors.
+* formatting source code:                Formatting.
+* formfeed:                              Formatting.
+* function argument, declaring:          Syntactic Conventions.
+* function prototypes:                   Standard C.
+* getopt:                                Command-Line Interfaces.
+* gettext:                               Internationalization.
+* gnome:                                 Graphical Interfaces.
+* graphical user interface:              Graphical Interfaces.
+* gtk:                                   Graphical Interfaces.
+* GUILE:                                 Source Language.
+* implicit int:                          Syntactic Conventions.
+* impossible conditions:                 Semantics.
+* internationalization:                  Internationalization.
+* legal aspects:                         Legal Issues.
+* legal papers:                          Contributions.
+* libexecdir:                            Directory Variables.
+* libraries:                             Libraries.
+* library functions, and portability:    System Functions.
+* license for manuals:                   License for Manuals.
+* lint:                                  Syntactic Conventions.
+* long option names:                     Option Table.
+* long-named options:                    Command-Line Interfaces.
+* makefile, conventions for:             Makefile Conventions.
+* malloc return value:                   Semantics.
+* man pages:                             Man Pages.
+* manual structure:                      Manual Structure Details.
+* memory allocation failure:             Semantics.
+* memory usage:                          Memory Usage.
+* message text, and internationalization: Internationalization.
+* mmap:                                  Mmap.
+* multiple variables in a line:          Syntactic Conventions.
+* names of variables and functions:      Names.
+* NEWS file:                             NEWS File.
+* non-POSIX systems, and portability:    System Portability.
+* non-standard extensions:               Using Extensions.
+* NUL characters:                        Semantics.
+* open brace:                            Formatting.
+* optional features, configure-time:     Configuration.
+* options for compatibility:             Compatibility.
+* output device and program's behavior:  User Interfaces.
+* packaging:                             Releases.
+* portability, and data types:           CPU Portability.
+* portability, and library functions:    System Functions.
+* portability, between system types:     System Portability.
+* POSIX compatibility:                   Compatibility.
+* POSIXLY_CORRECT, environment variable: Compatibility.
+* post-installation commands:            Install Command Categories.
+* pre-installation commands:             Install Command Categories.
+* prefix:                                Directory Variables.
+* program configuration:                 Configuration.
+* program design:                        Design Advice.
+* program name and its behavior:         User Interfaces.
+* program's canonical name:              Command-Line Interfaces.
+* programming languges:                  Source Language.
+* proprietary programs:                  Reading Non-Free Code.
+* README file:                           Releases.
+* references to non-free material:       References.
+* releasing:                             Managing Releases.
+* sbindir:                               Directory Variables.
+* signal handling:                       Semantics.
+* spaces before open-paren:              Formatting.
+* standard command-line options:         Command-Line Interfaces.
+* standards for makefiles:               Makefile Conventions.
+* string library functions:              System Functions.
+* syntactic conventions:                 Syntactic Conventions.
+* table of long options:                 Option Table.
+* temporary files:                       Semantics.
+* temporary variables:                   Syntactic Conventions.
+* texinfo.tex, in a distribution:        Releases.
+* TMPDIR environment variable:           Semantics.
+* trademarks:                            Trademarks.
+* where to obtain standards.texi:        Preface.
+
+

 \1f
 Tag Table:
 \1f
 Tag Table:

-(Indirect)

 Node: Top\7f980
 Node: Top\7f980

-Node: Preface\7f1585
-Node: Legal Issues\7f3105
-Node: Reading Non-Free Code\7f3568
-Node: Contributions\7f5291
-Node: Trademarks\7f7440
-Node: Design Advice\7f8498
-Node: Source Language\7f9004
-Node: Compatibility\7f11011
-Node: Using Extensions\7f12634
-Node: Standard C\7f14205
-Node: Program Behavior\7f16571
-Node: Semantics\7f17489
-Node: Libraries\7f22177
-Node: Errors\7f23417
-Node: User Interfaces\7f25193
-Node: Graphical Interfaces\7f26793
-Node: Command-Line Interfaces\7f27823
-Node: Option Table\7f33308
-Node: Memory Usage\7f48312
-Node: File Usage\7f49332
-Node: Writing C\7f50075
-Node: Formatting\7f50916
-Node: Comments\7f54974
-Node: Syntactic Conventions\7f58272
-Node: Names\7f61679
-Node: System Portability\7f63867
-Node: CPU Portability\7f66247
-Node: System Functions\7f69498
-Node: Internationalization\7f74700
-Node: Mmap\7f77848
-Node: Documentation\7f78553
-Node: GNU Manuals\7f79657
-Node: Doc Strings and Manuals\7f84709
-Node: Manual Structure Details\7f86257
-Node: License for Manuals\7f87670
-Node: Manual Credits\7f88639
-Node: Printed Manuals\7f89027
-Node: NEWS File\7f89708
-Node: Change Logs\7f90380
-Node: Change Log Concepts\7f91129
-Node: Style of Change Logs\7f92984
-Node: Simple Changes\7f95030
-Node: Conditional Changes\7f96265
-Node: Indicating the Part Changed\7f97678
-Node: Man Pages\7f98196
-Node: Reading other Manuals\7f99815
-Node: Managing Releases\7f100599
-Node: Configuration\7f101354
-Node: Makefile Conventions\7f108254
-Node: Makefile Basics\7f109013
-Node: Utilities in Makefiles\7f112178
-Node: Command Variables\7f114314
-Node: Directory Variables\7f117882
-Node: Standard Targets\7f128767
-Ref: Standard Targets-Footnote-1\7f140018
-Node: Install Command Categories\7f140118
-Node: Releases\7f144691
-Node: References\7f148774
-Node: Index\7f150168
+Node: Preface\7f1582
+Node: Legal Issues\7f3099
+Node: Reading Non-Free Code\7f3559
+Node: Contributions\7f5279
+Node: Trademarks\7f7425
+Node: Design Advice\7f8480
+Node: Source Language\7f8983
+Node: Compatibility\7f10987
+Node: Using Extensions\7f12607
+Node: Standard C\7f14175
+Node: Program Behavior\7f16538
+Node: Semantics\7f17453
+Node: Libraries\7f22138
+Node: Errors\7f23375
+Node: User Interfaces\7f25148
+Node: Graphical Interfaces\7f26745
+Node: Command-Line Interfaces\7f27772
+Node: Option Table\7f33254
+Node: Memory Usage\7f48255
+Node: File Usage\7f49272
+Node: Writing C\7f50012
+Node: Formatting\7f50850
+Node: Comments\7f54905
+Node: Syntactic Conventions\7f58199
+Node: Names\7f61603
+Node: System Portability\7f63788
+Node: CPU Portability\7f66165
+Node: System Functions\7f69413
+Node: Internationalization\7f74612
+Node: Mmap\7f77757
+Node: Documentation\7f78459
+Node: GNU Manuals\7f79560
+Node: Doc Strings and Manuals\7f84609
+Node: Manual Structure Details\7f86154
+Node: License for Manuals\7f87564
+Node: Manual Credits\7f88530
+Node: Printed Manuals\7f88915
+Node: NEWS File\7f89593
+Node: Change Logs\7f90263
+Node: Change Log Concepts\7f91009
+Node: Style of Change Logs\7f92861
+Node: Simple Changes\7f94904
+Node: Conditional Changes\7f96136
+Node: Indicating the Part Changed\7f97546
+Node: Man Pages\7f98061
+Node: Reading other Manuals\7f99677
+Node: Managing Releases\7f100458
+Node: Configuration\7f101210
+Node: Makefile Conventions\7f108107
+Node: Makefile Basics\7f108863
+Node: Utilities in Makefiles\7f112025
+Node: Command Variables\7f114158
+Node: Directory Variables\7f117723
+Node: Standard Targets\7f128605
+Ref: Standard Targets-Footnote-1\7f139853
+Node: Install Command Categories\7f139953
+Node: Releases\7f144523
+Node: References\7f148603
+Node: Index\7f149994

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

diff --git a/info/term.info b/info/term.info
index 1f84f9e..326ec06 100644 (file)
--- a/info/term.info
+++ b/info/term.info
@@ -1,4 +1,4 @@
-This is ../info/term.info, produced by makeinfo version 4.0 from
+This is ../info/term.info, produced by makeinfo version 4.6 from

 term.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 term.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -50,7 +50,7 @@ File: term.info,  Node: Overview,  Next: Connecting to remote computers,  Up: te
 Overview
 ========
 
 Overview
 ========
 

-   The `term' mode is used to control a program (an "inferior process").
+The `term' mode is used to control a program (an "inferior process").

 It sends most keyboard input characters to the program, and displays
 output from the program in the buffer.  This is similar to the
 traditional comint mode, and modes derived from it (such as shell and
 It sends most keyboard input characters to the program, and displays
 output from the program in the buffer.  This is similar to the
 traditional comint mode, and modes derived from it (such as shell and

@@ -72,12 +72,12 @@ File: term.info,  Node: Output from the inferior,  Next: subbuffer,  Up: Overvie
 Output from the inferior
 ------------------------
 
 Output from the inferior
 ------------------------
 

-   In typical usage, output from the inferior is added to the end of
-the buffer.  If needed, the window will be scrolled, just like a
-regular terminal.  (Only one line at a time will be scrolled, just like
-regular terminals, and in contrast to the old shell mode.)  Thus the
-buffer becomes a log of your interaction with the inferior, just like
-the old shell mode.
+In typical usage, output from the inferior is added to the end of the
+buffer.  If needed, the window will be scrolled, just like a regular
+terminal.  (Only one line at a time will be scrolled, just like regular
+terminals, and in contrast to the old shell mode.)  Thus the buffer
+becomes a log of your interaction with the inferior, just like the old
+shell mode.

 
    Like a real terminal, term maintains a "cursor position."  This is
 the `process-mark' of the inferior process.  If the process-mark is not
 
    Like a real terminal, term maintains a "cursor position."  This is
 the `process-mark' of the inferior process.  If the process-mark is not

@@ -104,9 +104,9 @@ File: term.info,  Node: subbuffer,  Next: altsubbuffer,  Prev: Output from the i
 The sub-buffer
 --------------
 
 The sub-buffer
 --------------
 

-   A program that talks to terminal expects the terminal to have a
-fixed size.  If the program is talking a terminal emulator program such
-as `xterm', that size can be changed (if the xterm window is re-sized),
+A program that talks to terminal expects the terminal to have a fixed
+size.  If the program is talking a terminal emulator program such as
+`xterm', that size can be changed (if the xterm window is re-sized),

 but programs still assume a logical terminal that has a fixed size
 independent of the amount of output transmitted by the programs.
 
 but programs still assume a logical terminal that has a fixed size
 independent of the amount of output transmitted by the programs.
 

@@ -137,10 +137,10 @@ File: term.info,  Node: altsubbuffer,  Next: Input to the inferior,  Prev: subbu
 The alternate sub-buffer
 ------------------------
 
 The alternate sub-buffer
 ------------------------
 

-   When a "graphical" program finishes, it is nice to restore the
-screen state to what it was before the program started.  Many people
-are used to this behavior from `xterm', and its also offered by the
-`term' emulator.
+When a "graphical" program finishes, it is nice to restore the screen
+state to what it was before the program started.  Many people are used
+to this behavior from `xterm', and its also offered by the `term'
+emulator.

 
  - Function: term-switch-to-alternate-sub-buffer set
      If SET is true, and we're not already using the alternate
 
  - Function: term-switch-to-alternate-sub-buffer set
      If SET is true, and we're not already using the alternate

@@ -161,7 +161,7 @@ File: term.info,  Node: Input to the inferior,  Prev: altsubbuffer,  Up: Overvie
 Input to the inferior
 ---------------------
 
 Input to the inferior
 ---------------------
 

-   Characters typed by the user are sent to the inferior.  How this is
+Characters typed by the user are sent to the inferior.  How this is

 done depends on whether the `term' buffer is in "character" mode or
 "line" mode.  (A `term' buffer can also be in "pager" mode.  This is
 discussed <later>.)  Which of these is currently active is specified in
 done depends on whether the `term' buffer is in "character" mode or
 "line" mode.  (A `term' buffer can also be in "pager" mode.  This is
 discussed <later>.)  Which of these is currently active is specified in

@@ -180,8 +180,8 @@ typed, the entire current line of the buffer (except possibly the
 prompt) is sent to the inferior process.  Line mode is basically the
 original shell mode from earlier Emacs versions.
 
 prompt) is sent to the inferior process.  Line mode is basically the
 original shell mode from earlier Emacs versions.
 

-   To switch from line mode to character mode type `C-c c'.  To switch
-from character mode to line mode type `C-c l'.
+   To switch from line mode to character mode type `C-c C-k'.  To
+switch from character mode to line mode type `C-c C-j'.

 
    In either mode, "echoing" of user input is handled by the inferior.
 Therefor, in line mode after an input line at the end of the buffer is
 
    In either mode, "echoing" of user input is handled by the inferior.
 Therefor, in line mode after an input line at the end of the buffer is

@@ -194,8 +194,8 @@ File: term.info,  Node: Connecting to remote computers,  Next: Paging,  Prev: Ov
 Connecting to remote computers
 ==============================
 
 Connecting to remote computers
 ==============================
 

-   If you want to login to a remove computer, you can do that just as
-you would expect, using whatever commands you would normally use.
+If you want to login to a remove computer, you can do that just as you
+would expect, using whatever commands you would normally use.

 
    (This is worth emphasizing, because earlier versions of `shell' mode
 would not work properly if you tried to log in to some other computer,
 
    (This is worth emphasizing, because earlier versions of `shell' mode
 would not work properly if you tried to log in to some other computer,

@@ -233,8 +233,8 @@ File: term.info,  Node: Paging,  Next: Terminal escapes,  Prev: Connecting to re
 Paging
 ======
 
 Paging
 ======
 

-   When the pager is enabled, Emacs will "pause" after each screenful
-of output (since the last input sent to the inferior).  It will enter
+When the pager is enabled, Emacs will "pause" after each screenful of
+output (since the last input sent to the inferior).  It will enter

 "pager" mode, which feels a lot like the "more" program:  Typing a
 space requests another screenful of output.  Other commands request
 more or less output, or scroll backwards in the `term' buffer.  In
 "pager" mode, which feels a lot like the "more" program:  Typing a
 space requests another screenful of output.  Other commands request
 more or less output, or scroll backwards in the `term' buffer.  In

@@ -250,8 +250,8 @@ File: term.info,  Node: Terminal escapes,  Prev: Paging,  Up: term mode
 Terminal Escape sequences
 =========================
 
 Terminal Escape sequences
 =========================
 

-   A program that does "graphics" on a terminal controls the terminal
-by sending strings called "terminal escape sequences" that the terminal
+A program that does "graphics" on a terminal controls the terminal by
+sending strings called "terminal escape sequences" that the terminal

 (or terminal emulator) interprets as special commands.  The `term' mode
 includes a terminal emulator that understands standard ANSI escape
 sequences, originally popularized by VT100 terminals, and now used by
 (or terminal emulator) interprets as special commands.  The `term' mode
 includes a terminal emulator that understands standard ANSI escape
 sequences, originally popularized by VT100 terminals, and now used by

@@ -306,10 +306,10 @@ File: term.info,  Node: Erasing,  Next: Inserting and deleting,  Prev: Cursor mo
 Escape commands for erasing text
 --------------------------------
 
 Escape commands for erasing text
 --------------------------------
 

-   These commands "erase" part of the sub-buffer.  Erasing means
-replacing by white space; it is not the same as deleting.  The relative
-screen positions of things that are not erased remain unchanged with
-each other, as does the relative cursor position.
+These commands "erase" part of the sub-buffer.  Erasing means replacing
+by white space; it is not the same as deleting.  The relative screen
+positions of things that are not erased remain unchanged with each
+other, as does the relative cursor position.

 
 `E [ J'
      Erase from cursor to end of screen.
 
 `E [ J'
      Erase from cursor to end of screen.

@@ -375,9 +375,9 @@ File: term.info,  Node: Command hook,  Next: Miscellaneous escapes,  Prev: Scrol
 Command hook
 ------------
 
 Command hook
 ------------
 

-   If `C-z' is seen, any text up to a following <LF> is scanned.  The
-text in between (not counting the initial C-z or the final LF) is
-passed to the function that is the value of `term-command-hook'.
+If `C-z' is seen, any text up to a following <LF> is scanned.  The text
+in between (not counting the initial C-z or the final LF) is passed to
+the function that is the value of `term-command-hook'.

 
    The default value of the `term-command-hook' variable is the
 function `term-command-hook', which handles the following:
 
    The default value of the `term-command-hook' variable is the
 function `term-command-hook', which handles the following:

@@ -424,18 +424,18 @@ Tag Table:
 Node: Top\7f201
 Node: term mode\7f367
 Node: Overview\7f1190
 Node: Top\7f201
 Node: term mode\7f367
 Node: Overview\7f1190

-Node: Output from the inferior\7f1940
-Node: subbuffer\7f3520
-Node: altsubbuffer\7f4843
-Node: Input to the inferior\7f5868
-Node: Connecting to remote computers\7f7388
-Node: Paging\7f9293
-Node: Terminal escapes\7f9962
-Node: Cursor motion\7f10830
-Node: Erasing\7f11490
-Node: Inserting and deleting\7f12285
-Node: Scrolling\7f12675
-Node: Command hook\7f13121
-Node: Miscellaneous escapes\7f14157
+Node: Output from the inferior\7f1937
+Node: subbuffer\7f3514
+Node: altsubbuffer\7f4834
+Node: Input to the inferior\7f5856
+Node: Connecting to remote computers\7f7377
+Node: Paging\7f9279
+Node: Terminal escapes\7f9945
+Node: Cursor motion\7f10810
+Node: Erasing\7f11470
+Node: Inserting and deleting\7f12262
+Node: Scrolling\7f12652
+Node: Command hook\7f13098
+Node: Miscellaneous escapes\7f14131

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

diff --git a/info/termcap.info b/info/termcap.info
index 5bbede1..8f5ec22 100644 (file)
--- a/info/termcap.info
+++ b/info/termcap.info
@@ -1,4 +1,4 @@
-This is ../info/termcap.info, produced by makeinfo version 4.0 from
+This is ../info/termcap.info, produced by makeinfo version 4.6 from

 termcap.texi.
 
 START-INFO-DIR-ENTRY
 termcap.texi.
 
 START-INFO-DIR-ENTRY

@@ -24,58 +24,3560 @@ versions, except that this permission notice may be stated in a
 translation approved by the Foundation.
 
 \1f
 translation approved by the Foundation.
 
 \1f

-Indirect:
-termcap.info-1: 959
-termcap.info-2: 49216
-termcap.info-3: 92525
+File: termcap.info,  Node: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)
+
+* Menu:
+
+* Introduction::What is termcap?  Why this manual?
+* Library::     The termcap library functions.
+* Data Base::   What terminal descriptions in `/etc/termcap' look like.
+* Capabilities::Definitions of the individual terminal capabilities:
+                 how to write them in descriptions, and how to use
+                 their values to do display updating.
+* Summary::    Brief table of capability names and their meanings.
+* Var Index::   Index of C functions and variables.
+* Cap Index::   Index of termcap capabilities.
+* Index::       Concept index.
+
+\1f
+File: termcap.info,  Node: Introduction,  Next: Library,  Prev: Top,  Up: Top
+
+Introduction
+************
+
+"Termcap" is a library and data base that enables programs to use
+display terminals in a terminal-independent manner.  It originated in
+Berkeley Unix.
+
+   The termcap data base describes the capabilities of hundreds of
+different display terminals in great detail.  Some examples of the
+information recorded for a terminal could include how many columns wide
+it is, what string to send to move the cursor to an arbitrary position
+(including how to encode the row and column numbers), how to scroll the
+screen up one or several lines, and how much padding is needed for such
+a scrolling operation.
+
+   The termcap library is provided for easy access this data base in
+programs that want to do terminal-independent character-based display
+output.
+
+   This manual describes the GNU version of the termcap library, which
+has some extensions over the Unix version.  All the extensions are
+identified as such, so this manual also tells you how to use the Unix
+termcap.
+
+   The GNU version of the termcap library is available free as source
+code, for use in free programs, and runs on Unix and VMS systems (at
+least).  You can find it in the GNU Emacs distribution in the files
+`termcap.c' and `tparam.c'.
+
+   This manual was written for the GNU project, whose goal is to
+develop a complete free operating system upward-compatible with Unix
+for user programs.  The project is approximately two thirds complete.
+For more information on the GNU project, including the GNU Emacs editor
+and the mostly-portable optimizing C compiler, send one dollar to
+
+     Free Software Foundation
+     675 Mass Ave
+     Cambridge, MA 02139
+
+\1f
+File: termcap.info,  Node: Library,  Next: Data Base,  Prev: Introduction,  Up: Top
+
+The Termcap Library
+*******************
+
+The termcap library is the application programmer's interface to the
+termcap data base.  It contains functions for the following purposes:
+
+   * Finding the description of the user's terminal type (`tgetent').
+
+   * Interrogating the description for information on various topics
+     (`tgetnum', `tgetflag', `tgetstr').
+
+   * Computing and performing padding (`tputs').
+
+   * Encoding numeric parameters such as cursor positions into the
+     terminal-specific form required for display commands (`tparam',
+     `tgoto').
+
+* Menu:
+
+* Preparation:: Preparing to use the termcap library.
+* Find::        Finding the description of the terminal being used.
+* Interrogate:: Interrogating the description for particular capabilities.
+* Initialize::  Initialization for output using termcap.
+* Padding::     Outputting padding.
+* Parameters::  Encoding parameters such as cursor positions.
+
+\1f
+File: termcap.info,  Node: Preparation,  Next: Find,  Prev: Library,  Up: Library
+
+Preparing to Use the Termcap Library
+====================================
+
+To use the termcap library in a program, you need two kinds of
+preparation:
+
+   * The compiler needs declarations of the functions and variables in
+     the library.
+
+     On GNU systems, it suffices to include the header file `termcap.h'
+     in each source file that uses these functions and variables.
+
+     On Unix systems, there is often no such header file.  Then you must
+     explictly declare the variables as external.  You can do likewise
+     for the functions, or let them be implicitly declared and cast
+     their values from type `int' to the appropriate type.
+
+     We illustrate the declarations of the individual termcap library
+     functions with ANSI C prototypes because they show how to pass the
+     arguments.  If you are not using the GNU C compiler, you probably
+     cannot use function prototypes, so omit the argument types and
+     names from your declarations.
+
+   * The linker needs to search the library.  Usually either
+     `-ltermcap' or `-ltermlib' as an argument when linking will do
+     this.
+
+\1f
+File: termcap.info,  Node: Find,  Next: Interrogate,  Prev: Preparation,  Up: Library
+
+Finding a Terminal Description: `tgetent'
+=========================================
+
+An application program that is going to use termcap must first look up
+the description of the terminal type in use.  This is done by calling
+`tgetent', whose declaration in ANSI Standard C looks like:
+
+     int tgetent (char *BUFFER, char *TERMTYPE);
+
+This function finds the description and remembers it internally so that
+you can interrogate it about specific terminal capabilities (*note
+Interrogate::).
+
+   The argument TERMTYPE is a string which is the name for the type of
+terminal to look up.  Usually you would obtain this from the environment
+variable `TERM' using `getenv ("TERM")'.
+
+   If you are using the GNU version of termcap, you can alternatively
+ask `tgetent' to allocate enough space.  Pass a null pointer for
+BUFFER, and `tgetent' itself allocates the storage using `malloc'.  In
+this case the returned value on success is the address of the storage,
+cast to `int'.  But normally there is no need for you to look at the
+address.  Do not free the storage yourself.
+
+   With the Unix version of termcap, you must allocate space for the
+description yourself and pass the address of the space as the argument
+BUFFER.  There is no way you can tell how much space is needed, so the
+convention is to allocate a buffer 2048 characters long and assume that
+is enough.  (Formerly the convention was to allocate 1024 characters and
+assume that was enough.  But one day, for one kind of terminal, that was
+not enough.)
+
+   No matter how the space to store the description has been obtained,
+termcap records its address internally for use when you later
+interrogate the description with `tgetnum', `tgetstr' or `tgetflag'.  If
+the buffer was allocated by termcap, it will be freed by termcap too if
+you call `tgetent' again.  If the buffer was provided by you, you must
+make sure that its contents remain unchanged for as long as you still
+plan to interrogate the description.
+
+   The return value of `tgetent' is -1 if there is some difficulty
+accessing the data base of terminal types, 0 if the data base is
+accessible but the specified type is not defined in it, and some other
+value otherwise.
+
+   Here is how you might use the function `tgetent':
+
+     #ifdef unix
+     static char term_buffer[2048];
+     #else
+     #define term_buffer 0
+     #endif
+     
+     init_terminal_data ()
+     {
+       char *termtype = getenv ("TERM");
+       int success;
+     
+       if (termtype == 0)
+         fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
+     
+       success = tgetent (term_buffer, termtype);
+       if (success < 0)
+         fatal ("Could not access the termcap data base.\n");
+       if (success == 0)
+         fatal ("Terminal type `%s' is not defined.\n", termtype);
+     }
+
+Here we assume the function `fatal' prints an error message and exits.
+
+   If the environment variable `TERMCAP' is defined, its value is used
+to override the terminal type data base.  The function `tgetent' checks
+the value of `TERMCAP' automatically.  If the value starts with `/'
+then it is taken as a file name to use as the data base file, instead
+of `/etc/termcap' which is the standard data base.  If the value does
+not start with `/' then it is itself used as the terminal description,
+provided that the terminal type TERMTYPE is among the types it claims
+to apply to.  *Note Data Base::, for information on the format of a
+terminal description.
+
+\1f
+File: termcap.info,  Node: Interrogate,  Next: Initialize,  Prev: Find,  Up: Library
+
+Interrogating the Terminal Description
+======================================
+
+Each piece of information recorded in a terminal description is called a
+"capability".  Each defined terminal capability has a two-letter code
+name and a specific meaning.  For example, the number of columns is
+named `co'.  *Note Capabilities::, for definitions of all the standard
+capability names.
+
+   Once you have found the proper terminal description with `tgetent'
+(*note Find::), your application program must "interrogate" it for
+various terminal capabilities.  You must specify the two-letter code of
+the capability whose value you seek.
+
+   Capability values can be numeric, boolean (capability is either
+present or absent) or strings.  Any particular capability always has
+the same value type; for example, `co' always has a numeric value,
+while `am' (automatic wrap at margin) is always a flag, and `cm'
+(cursor motion command) always has a string value.  The documentation
+of each capability says which type of value it has.
+
+   There are three functions to use to get the value of a capability,
+depending on the type of value the capability has.  Here are their
+declarations in ANSI C:
+
+     int tgetnum (char *NAME);
+     int tgetflag (char *NAME);
+     char *tgetstr (char *NAME, char **AREA);
+
+`tgetnum'
+     Use `tgetnum' to get a capability value that is numeric.  The
+     argument NAME is the two-letter code name of the capability.  If
+     the capability is present, `tgetnum' returns the numeric value
+     (which is nonnegative).  If the capability is not mentioned in the
+     terminal description, `tgetnum' returns -1.
+
+`tgetflag'
+     Use `tgetflag' to get a boolean value.  If the capability NAME is
+     present in the terminal description, `tgetflag' returns 1;
+     otherwise, it returns 0.
+
+`tgetstr'
+     Use `tgetstr' to get a string value.  It returns a pointer to a
+     string which is the capability value, or a null pointer if the
+     capability is not present in the terminal description.
+
+     There are two ways `tgetstr' can find space to store the string
+     value:
+
+        * You can ask `tgetstr' to allocate the space.  Pass a null
+          pointer for the argument AREA, and `tgetstr' will use
+          `malloc' to allocate storage big enough for the value.
+          Termcap will never free this storage or refer to it again; you
+          should free it when you are finished with it.
+
+          This method is more robust, since there is no need to guess
+          how much space is needed.  But it is supported only by the GNU
+          termcap library.
+
+        * You can provide the space.  Provide for the argument AREA the
+          address of a pointer variable of type `char *'.  Before
+          calling `tgetstr', initialize the variable to point at
+          available space.  Then `tgetstr' will store the string value
+          in that space and will increment the pointer variable to
+          point after the space that has been used.  You can use the
+          same pointer variable for many calls to `tgetstr'.
+
+          There is no way to determine how much space is needed for a
+          single string, and no way for you to prevent or handle
+          overflow of the area you have provided.  However, you can be
+          sure that the total size of all the string values you will
+          obtain from the terminal description is no greater than the
+          size of the description (unless you get the same capability
+          twice).  You can determine that size with `strlen' on the
+          buffer you provided to `tgetent'.  See below for an example.
+
+          Providing the space yourself is the only method supported by
+          the Unix version of termcap.
+
+   Note that you do not have to specify a terminal type or terminal
+description for the interrogation functions.  They automatically use the
+description found by the most recent call to `tgetent'.
+
+   Here is an example of interrogating a terminal description for
+various capabilities, with conditionals to select between the Unix and
+GNU methods of providing buffer space.
+
+     char *tgetstr ();
+     
+     char *cl_string, *cm_string;
+     int height;
+     int width;
+     int auto_wrap;
+     
+     char PC;   /* For tputs.  */
+     char *BC;  /* For tgoto.  */
+     char *UP;
+     
+     interrogate_terminal ()
+     {
+     #ifdef UNIX
+       /* Here we assume that an explicit term_buffer
+          was provided to tgetent.  */
+       char *buffer
+         = (char *) malloc (strlen (term_buffer));
+     #define BUFFADDR &buffer
+     #else
+     #define BUFFADDR 0
+     #endif
+     
+       char *temp;
+     
+       /* Extract information we will use.  */
+       cl_string = tgetstr ("cl", BUFFADDR);
+       cm_string = tgetstr ("cm", BUFFADDR);
+       auto_wrap = tgetflag ("am");
+       height = tgetnum ("li");
+       width = tgetnum ("co");
+     
+       /* Extract information that termcap functions use.  */
+       temp = tgetstr ("pc", BUFFADDR);
+       PC = temp ? *temp : 0;
+       BC = tgetstr ("le", BUFFADDR);
+       UP = tgetstr ("up", BUFFADDR);
+     }
+
+*Note Padding::, for information on the variable `PC'.  *Note Using
+Parameters::, for information on `UP' and `BC'.
+
+\1f
+File: termcap.info,  Node: Initialize,  Next: Padding,  Prev: Interrogate,  Up: Library
+
+Initialization for Use of Termcap
+=================================
+
+Before starting to output commands to a terminal using termcap, an
+application program should do two things:
+
+   * Initialize various global variables which termcap library output
+     functions refer to.  These include `PC' and `ospeed' for padding
+     (*note Output Padding::) and `UP' and `BC' for cursor motion
+     (*note tgoto::).
+
+   * Tell the kernel to turn off alteration and padding of
+     horizontal-tab characters sent to the terminal.
+
+   To turn off output processing in Berkeley Unix you would use `ioctl'
+with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits
+`ANYDELAY' using `TIOCSETN'.  In POSIX or System V, you must clear the
+bit named `OPOST'.  Refer to the system documentation for details.
+
+   If you do not set the terminal flags properly, some older terminals
+will not work.  This is because their commands may contain the
+characters that normally signify newline, carriage return and
+horizontal tab--characters which the kernel thinks it ought to modify
+before output.
+
+   When you change the kernel's terminal flags, you must arrange to
+restore them to their normal state when your program exits.  This
+implies that the program must catch fatal signals such as `SIGQUIT' and
+`SIGINT' and restore the old terminal flags before actually terminating.
+
+   Modern terminals' commands do not use these special characters, so
+if you do not care about problems with old terminals, you can leave the
+kernel's terminal flags unaltered.
+
+\1f
+File: termcap.info,  Node: Padding,  Next: Parameters,  Prev: Initialize,  Up: Library
+
+Padding
+=======
+
+"Padding" means outputting null characters following a terminal display
+command that takes a long time to execute.  The terminal description
+says which commands require padding and how much; the function `tputs',
+described below, outputs a terminal command while extracting from it the
+padding information, and then outputs the padding that is necessary.
+
+* Menu:
+
+* Why Pad::          Explanation of padding.
+* Describe Padding:: The data base says how much padding a terminal needs.
+* Output Padding::   Using `tputs' to output the needed padding.
+
+\1f
+File: termcap.info,  Node: Why Pad,  Next: Describe Padding,  Prev: Padding,  Up: Padding
+
+Why Pad, and How
+----------------
+
+Most types of terminal have commands that take longer to execute than
+they do to send over a high-speed line.  For example, clearing the
+screen may take 20msec once the entire command is received.  During
+that time, on a 9600 bps line, the terminal could receive about 20
+additional output characters while still busy clearing the screen.
+Every terminal has a certain amount of buffering capacity to remember
+output characters that cannot be processed yet, but too many slow
+commands in a row can cause the buffer to fill up.  Then any additional
+output that cannot be processed immediately will be lost.
+
+   To avoid this problem, we normally follow each display command with
+enough useless charaters (usually null characters) to fill up the time
+that the display command needs to execute.  This does the job if the
+terminal throws away null characters without using up space in the
+buffer (which most terminals do).  If enough padding is used, no output
+can ever be lost.  The right amount of padding avoids loss of output
+without slowing down operation, since the time used to transmit padding
+is time that nothing else could be done.
+
+   The number of padding characters needed for an operation depends on
+the line speed.  In fact, it is proportional to the line speed.  A 9600
+baud line transmits about one character per msec, so the clear screen
+command in the example above would need about 20 characters of padding.
+At 1200 baud, however, only about 3 characters of padding are needed
+to fill up 20msec.
+
+\1f
+File: termcap.info,  Node: Describe Padding,  Next: Output Padding,  Prev: Why Pad,  Up: Padding
+
+Specifying Padding in a Terminal Description
+--------------------------------------------
+
+In the terminal description, the amount of padding required by each
+display command is recorded as a sequence of digits at the front of the
+command.  These digits specify the padding time in msec.  They can be
+followed optionally by a decimal point and one more digit, which is a
+number of tenths of msec.
+
+   Sometimes the padding needed by a command depends on the cursor
+position.  For example, the time taken by an "insert line" command is
+usually proportional to the number of lines that need to be moved down
+or cleared.  An asterisk (`*') following the padding time says that the
+time should be multiplied by the number of screen lines affected by the
+command.
+
+     :al=1.3*\E[L:
+
+is used to describe the "insert line" command for a certain terminal.
+The padding required is 1.3 msec per line affected.  The command itself
+is `<ESC> [ L'.
+
+   The padding time specified in this way tells `tputs' how many pad
+characters to output.  *Note Output Padding::.
+
+   Two special capability values affect padding for all commands.
+These are the `pc' and `pb'.  The variable `pc' specifies the character
+to pad with, and `pb' the speed below which no padding is needed.  The
+defaults for these variables, a null character and 0, are correct for
+most terminals.  *Note Pad Specs::.
+
+\1f
+File: termcap.info,  Node: Output Padding,  Prev: Describe Padding,  Up: Padding
+
+Performing Padding with `tputs'
+-------------------------------
+
+Use the termcap function `tputs' to output a string containing an
+optional padding spec of the form described above (*note Describe
+Padding::).  The function `tputs' strips off and decodes the padding
+spec, outputs the rest of the string, and then outputs the appropriate
+padding.  Here is its declaration in ANSI C:
+
+     char PC;
+     short ospeed;
+     
+     int tputs (char *STRING, int NLINES, int (*OUTFUN) ());
+
+   Here STRING is the string (including padding spec) to be output;
+NLINES is the number of lines affected by the operation, which is used
+to multiply the amount of padding if the padding spec ends with a `*'.
+Finally, OUTFUN is a function (such as `fputchar') that is called to
+output each character.  When actually called, OUTFUN should expect one
+argument, a character.
+
+   The operation of `tputs' is controlled by two global variables,
+`ospeed' and `PC'.  The value of `ospeed' is supposed to be the
+terminal output speed, encoded as in the `ioctl' system call which gets
+the speed information.  This is needed to compute the number of padding
+characters.  The value of `PC' is the character used for padding.
+
+   You are responsible for storing suitable values into these variables
+before using `tputs'.  The value stored into the `PC' variable should be
+taken from the `pc' capability in the terminal description (*note Pad
+Specs::).  Store zero in `PC' if there is no `pc' capability.
+
+   The argument NLINES requires some thought.  Normally, it should be
+the number of lines whose contents will be cleared or moved by the
+command.  For cursor motion commands, or commands that do editing
+within one line, use the value 1.  For most commands that affect
+multiple lines, such as `al' (insert a line) and `cd' (clear from the
+cursor to the end of the screen), NLINES should be the screen height
+minus the current vertical position (origin 0).  For multiple insert
+and scroll commands such as `AL' (insert multiple lines), that same
+value for NLINES is correct; the number of lines being inserted is not
+correct.
+
+   If a "scroll window" feature is used to reduce the number of lines
+affected by a command, the value of NLINES should take this into
+account.  This is because the delay time required depends on how much
+work the terminal has to do, and the scroll window feature reduces the
+work.  *Note Scrolling::.
+
+   Commands such as `ic' and `dc' (insert or delete characters) are
+problematical because the padding needed by these commands is
+proportional to the number of characters affected, which is the number
+of columns from the cursor to the end of the line.  It would be nice to
+have a way to specify such a dependence, and there is no need for
+dependence on vertical position in these commands, so it is an obvious
+idea to say that for these commands NLINES should really be the number
+of columns affected.  However, the definition of termcap clearly says
+that NLINES is always the number of lines affected, even in this case,
+where it is always 1.  It is not easy to change this rule now, because
+too many programs and terminal descriptions have been written to follow
+it.
+
+   Because NLINES is always 1 for the `ic' and `dc' strings, there is
+no reason for them to use `*', but some of them do.  These should be
+corrected by deleting the `*'.  If, some day, such entries have
+disappeared, it may be possible to change to a more useful convention
+for the NLINES argument for these operations without breaking any
+programs.
+
+\1f
+File: termcap.info,  Node: Parameters,  Prev: Padding,  Up: Library
+
+Filling In Parameters
+=====================
+
+Some terminal control strings require numeric "parameters".  For
+example, when you move the cursor, you need to say what horizontal and
+vertical positions to move it to.  The value of the terminal's `cm'
+capability, which says how to move the cursor, cannot simply be a
+string of characters; it must say how to express the cursor position
+numbers and where to put them within the command.
+
+   The specifications of termcap include conventions as to which
+string-valued capabilities require parameters, how many parameters, and
+what the parameters mean; for example, it defines the `cm' string to
+take two parameters, the vertical and horizontal positions, with 0,0
+being the upper left corner.  These conventions are described where the
+individual commands are documented.
+
+   Termcap also defines a language used within the capability
+definition for specifying how and where to encode the parameters for
+output.  This language uses character sequences starting with `%'.
+(This is the same idea as `printf', but the details are different.)
+The language for parameter encoding is described in this section.
+
+   A program that is doing display output calls the functions `tparam'
+or `tgoto' to encode parameters according to the specifications.  These
+functions produce a string containing the actual commands to be output
+(as well a padding spec which must be processed with `tputs'; *note
+Padding::).
+
+* Menu:
+
+* Encode Parameters:: The language for encoding parameters.
+* Using Parameters::  Outputting a string command with parameters.
+
+\1f
+File: termcap.info,  Node: Encode Parameters,  Next: Using Parameters,  Prev: Parameters,  Up: Parameters
+
+Describing the Encoding
+-----------------------
+
+A terminal command string that requires parameters contains special
+character sequences starting with `%' to say how to encode the
+parameters.  These sequences control the actions of `tparam' and
+`tgoto'.
+
+   The parameters values passed to `tparam' or `tgoto' are considered
+to form a vector.  A pointer into this vector determines the next
+parameter to be processed.  Some of the `%'-sequences encode one
+parameter and advance the pointer to the next parameter.  Other
+`%'-sequences alter the pointer or alter the parameter values without
+generating output.
+
+   For example, the `cm' string for a standard ANSI terminal is written
+as `\E[%i%d;%dH'.  (`\E' stands for <ESC>.)  `cm' by convention always
+requires two parameters, the vertical and horizontal goal positions, so
+this string specifies the encoding of two parameters.  Here `%i'
+increments the two values supplied, and each `%d' encodes one of the
+values in decimal.  If the cursor position values 20,58 are encoded
+with this string, the result is `\E[21;59H'.
+
+   First, here are the `%'-sequences that generate output.  Except for
+`%%', each of them encodes one parameter and advances the pointer to
+the following parameter.
+
+`%%'
+     Output a single `%'.  This is the only way to represent a literal
+     `%' in a terminal command with parameters.  `%%' does not use up a
+     parameter.
+
+`%d'
+     As in `printf', output the next parameter in decimal.
+
+`%2'
+     Like `%02d' in `printf': output the next parameter in decimal, and
+     always use at least two digits.
+
+`%3'
+     Like `%03d' in `printf': output the next parameter in decimal, and
+     always use at least three digits.  Note that `%4' and so on are
+     _not_ defined.
+
+`%.'
+     Output the next parameter as a single character whose ASCII code is
+     the parameter value.  Like `%c' in `printf'.
+
+`%+CHAR'
+     Add the next parameter to the character CHAR, and output the
+     resulting character.  For example, `%+ ' represents 0 as a space,
+     1 as `!', etc.
+
+   The following `%'-sequences specify alteration of the parameters
+(their values, or their order) rather than encoding a parameter for
+output.  They generate no output; they are used only for their side
+effects on the parameters.  Also, they do not advance the "next
+parameter" pointer except as explicitly stated.  Only `%i', `%r' and
+`%>' are defined in standard Unix termcap.  The others are GNU
+extensions.
+
+`%i'
+     Increment the next two parameters.  This is used for terminals that
+     expect cursor positions in origin 1.  For example, `%i%d,%d' would
+     output two parameters with `1' for 0, `2' for 1, etc.
+
+`%r'
+     Interchange the next two parameters.  This is used for terminals
+     whose cursor positioning command expects the horizontal position
+     first.
+
+`%s'
+     Skip the next parameter.  Do not output anything.
+
+`%b'
+     Back up one parameter.  The last parameter used will become once
+     again the next parameter to be output, and the next output command
+     will use it.  Using `%b' more than once, you can back up any
+     number of parameters, and you can refer to each parameter any
+     number of times.
+
+`%>C1C2'
+     Conditionally increment the next parameter.  Here C1 and C2 are
+     characters which stand for their ASCII codes as numbers.  If the
+     next parameter is greater than the ASCII code of C1, the ASCII
+     code of C2 is added to it.
+
+`%a OP TYPE POS'
+     Perform arithmetic on the next parameter, do not use it up, and do
+     not output anything.  Here OP specifies the arithmetic operation,
+     while TYPE and POS together specify the other operand.
+
+     Spaces are used above to separate the operands for clarity; the
+     spaces don't appear in the data base, where this sequence is
+     exactly five characters long.
+
+     The character OP says what kind of arithmetic operation to
+     perform.  It can be any of these characters:
+
+    `='
+          assign a value to the next parameter, ignoring its old value.
+          The new value comes from the other operand.
+
+    `+'
+          add the other operand to the next parameter.
+
+    `-'
+          subtract the other operand from the next parameter.
+
+    `*'
+          multiply the next parameter by the other operand.
+
+    `/'
+          divide the next parameter by the other operand.
+
+     The "other operand" may be another parameter's value or a constant;
+     the character TYPE says which.  It can be:
+
+    `p'
+          Use another parameter.  The character POS says which
+          parameter to use.  Subtract 64 from its ASCII code to get the
+          position of the desired parameter relative to this one.  Thus,
+          the character `A' as POS means the parameter after the next
+          one; the character `?' means the parameter before the next
+          one.
+
+    `c'
+          Use a constant value.  The character POS specifies the value
+          of the constant.  The 0200 bit is cleared out, so that 0200
+          can be used to represent zero.
+
+   The following `%'-sequences are special purpose hacks to compensate
+for the weird designs of obscure terminals.  They modify the next
+parameter or the next two parameters but do not generate output and do
+not use up any parameters.  `%m' is a GNU extension; the others are
+defined in standard Unix termcap.
+
+`%n'
+     Exclusive-or the next parameter with 0140, and likewise the
+     parameter after next.
+
+`%m'
+     Complement all the bits of the next parameter and the parameter
+     after next.
+
+`%B'
+     Encode the next parameter in BCD.  It alters the value of the
+     parameter by adding six times the quotient of the parameter by ten.
+     Here is a C statement that shows how the new value is computed:
+
+          PARM = (PARM / 10) * 16 + PARM % 10;
+
+`%D'
+     Transform the next parameter as needed by Delta Data terminals.
+     This involves subtracting twice the remainder of the parameter by
+     16.
+
+          PARM -= 2 * (PARM % 16);
+
+\1f
+File: termcap.info,  Node: Using Parameters,  Prev: Encode Parameters,  Up: Parameters
+
+Sending Display Commands with Parameters
+----------------------------------------
+
+The termcap library functions `tparam' and `tgoto' serve as the analog
+of `printf' for terminal string parameters.  The newer function
+`tparam' is a GNU extension, more general but missing from Unix
+termcap.  The original parameter-encoding function is `tgoto', which is
+preferable for cursor motion.
+
+* Menu:
+
+* tparam::   The general case, for GNU termcap only.
+* tgoto::    The special case of cursor motion.
+
+\1f
+File: termcap.info,  Node: tparam,  Next: tgoto,  Prev: Using Parameters,  Up: Using Parameters
+
+`tparam'
+........
+
+The function `tparam' can encode display commands with any number of
+parameters and allows you to specify the buffer space.  It is the
+preferred function for encoding parameters for all but the `cm'
+capability.  Its ANSI C declaration is as follows:
+
+     char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
+
+   The arguments are a control string CTLSTRING (the value of a terminal
+capability, presumably), an output buffer BUFFER and SIZE, and any
+number of integer parameters to be encoded.  The effect of `tparam' is
+to copy the control string into the buffer, encoding parameters
+according to the `%' sequences in the control string.
+
+   You describe the output buffer by its address, BUFFER, and its size
+in bytes, SIZE.  If the buffer is not big enough for the data to be
+stored in it, `tparam' calls `malloc' to get a larger buffer.  In
+either case, `tparam' returns the address of the buffer it ultimately
+uses.  If the value equals BUFFER, your original buffer was used.
+Otherwise, a new buffer was allocated, and you must free it after you
+are done with printing the results.  If you pass zero for SIZE and
+BUFFER, `tparam' always allocates the space with `malloc'.
+
+   All capabilities that require parameters also have the ability to
+specify padding, so you should use `tputs' to output the string
+produced by `tparam'.  *Note Padding::.  Here is an example.
+
+     {
+       char *buf;
+       char buffer[40];
+     
+       buf = tparam (command, buffer, 40, parm);
+       tputs (buf, 1, fputchar);
+       if (buf != buffer)
+         free (buf);
+     }
+
+   If a parameter whose value is zero is encoded with `%.'-style
+encoding, the result is a null character, which will confuse `tputs'.
+This would be a serious problem, but luckily `%.' encoding is used only
+by a few old models of terminal, and only for the `cm' capability.  To
+solve the problem, use `tgoto' rather than `tparam' to encode the `cm'
+capability.
+
+\1f
+File: termcap.info,  Node: tgoto,  Prev: tparam,  Up: Using Parameters
+
+`tgoto'
+.......
+
+The special case of cursor motion is handled by `tgoto'.  There are two
+reasons why you might choose to use `tgoto':
+
+   * For Unix compatibility, because Unix termcap does not have
+     `tparam'.
+
+   * For the `cm' capability, since `tgoto' has a special feature to
+     avoid problems with null characters, tabs and newlines on certain
+     old terminal types that use `%.' encoding for that capability.
+
+   Here is how `tgoto' might be declared in ANSI C:
+
+     char *tgoto (char *CSTRING, int HPOS, int VPOS)
+
+   There are three arguments, the terminal description's `cm' string and
+the two cursor position numbers; `tgoto' computes the parametrized
+string in an internal static buffer and returns the address of that
+buffer.  The next time you use `tgoto' the same buffer will be reused.
+
+   Parameters encoded with `%.' encoding can generate null characters,
+tabs or newlines.  These might cause trouble: the null character because
+`tputs' would think that was the end of the string, the tab because the
+kernel or other software might expand it into spaces, and the newline
+becaue the kernel might add a carriage-return, or padding characters
+normally used for a newline.  To prevent such problems, `tgoto' is
+careful to avoid these characters.  Here is how this works: if the
+target cursor position value is such as to cause a problem (that is to
+say, zero, nine or ten), `tgoto' increments it by one, then compensates
+by appending a string to move the cursor back or up one position.
+
+   The compensation strings to use for moving back or up are found in
+global variables named `BC' and `UP'.  These are actual external C
+variables with upper case names; they are declared `char *'.  It is up
+to you to store suitable values in them, normally obtained from the
+`le' and `up' terminal capabilities in the terminal description with
+`tgetstr'.  Alternatively, if these two variables are both zero, the
+feature of avoiding nulls, tabs and newlines is turned off.
+
+   It is safe to use `tgoto' for commands other than `cm' only if you
+have stored zero in `BC' and `UP'.
+
+   Note that `tgoto' reverses the order of its operands: the horizontal
+position comes before the vertical position in the arguments to
+`tgoto', even though the vertical position comes before the horizontal
+in the parameters of the `cm' string.  If you use `tgoto' with a
+command such as `AL' that takes one parameter, you must pass the
+parameter to `tgoto' as the "vertical position".
+
+\1f
+File: termcap.info,  Node: Data Base,  Next: Capabilities,  Prev: Library,  Up: Top
+
+The Format of the Data Base
+***************************
+
+The termcap data base of terminal descriptions is stored in the file
+`/etc/termcap'.  It contains terminal descriptions, blank lines, and
+comments.
+
+   A terminal description starts with one or more names for the
+terminal type.  The information in the description is a series of
+"capability names" and values.  The capability names have standard
+meanings (*note Capabilities::) and their values describe the terminal.
+
+* Menu:
+
+* Format::            Overall format of a terminal description.
+* Capability Format:: Format of capabilities within a description.
+* Naming::            Naming conventions for terminal types.
+* Inheriting::        Inheriting part of a description from
+                        a related terminal type.
+
+\1f
+File: termcap.info,  Node: Format,  Next: Capability Format,  Prev: Data Base,  Up: Data Base
+
+Terminal Description Format
+===========================
+
+Aside from comments (lines starting with `#', which are ignored), each
+nonblank line in the termcap data base is a terminal description.  A
+terminal description is nominally a single line, but it can be split
+into multiple lines by inserting the two characters `\ newline'.  This
+sequence is ignored wherever it appears in a description.
+
+   The preferred way to split the description is between capabilities:
+insert the four characters `: \ newline tab' immediately before any
+colon.  This allows each sub-line to start with some indentation.  This
+works because, after the `\ newline' are ignored, the result is `: tab
+:'; the first colon ends the preceding capability and the second colon
+starts the next capability.  If you split with `\ newline' alone, you
+may not add any indentation after them.
+
+   Here is a real example of a terminal description:
+
+     dw|vt52|DEC vt52:\
+             :cr=^M:do=^J:nl=^J:bl=^G:\
+             :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
+             :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
+             :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
+
+   Each terminal description begins with several names for the terminal
+type.  The names are separated by `|' characters, and a colon ends the
+last name.  The first name should be two characters long; it exists
+only for the sake of very old Unix systems and is never used in modern
+systems.  The last name should be a fully verbose name such as "DEC
+vt52" or "Ann Arbor Ambassador with 48 lines".  The other names should
+include whatever the user ought to be able to specify to get this
+terminal type, such as `vt52' or `aaa-48'.  *Note Naming::, for
+information on how to choose terminal type names.
+
+   After the terminal type names come the terminal capabilities,
+separated by colons and with a colon after the last one.  Each
+capability has a two-letter name, such as `cm' for "cursor motion
+string" or `li' for "number of display lines".
+
+\1f
+File: termcap.info,  Node: Capability Format,  Next: Naming,  Prev: Format,  Up: Data Base
+
+Writing the Capabilities
+========================
+
+There are three kinds of capabilities: flags, numbers, and strings.
+Each kind has its own way of being written in the description.  Each
+defined capability has by convention a particular kind of value; for
+example, `li' always has a numeric value and `cm' always a string value.
+
+   A flag capability is thought of as having a boolean value: the value
+is true if the capability is present, false if not.  When the
+capability is present, just write its name between two colons.
+
+   A numeric capability has a value which is a nonnegative number.
+Write the capability name, a `#', and the number, between two colons.
+For example, `...:li#48:...' is how you specify the `li' capability for
+48 lines.
+
+   A string-valued capability has a value which is a sequence of
+characters.  Usually these are the characters used to perform some
+display operation.  Write the capability name, a `=', and the
+characters of the value, between two colons.  For example,
+`...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a
+standard ANSI terminal would be specified.
+
+   Special characters in the string value can be expressed using
+`\'-escape sequences as in C; in addition, `\E' stands for <ESC>.  `^'
+is also a kind of escape character; `^' followed by CHAR stands for the
+control-equivalent of CHAR.  Thus, `^a' stands for the character
+control-a, just like `\001'.  `\' and `^' themselves can be represented
+as `\\' and `\^'.
+
+   To include a colon in the string, you must write `\072'.  You might
+ask, "Why can't `\:' be used to represent a colon?"  The reason is that
+the interrogation functions do not count slashes while looking for a
+capability.  Even if `:ce=ab\:cd:' were interpreted as giving the `ce'
+capability the value `ab:cd', it would also appear to define `cd' as a
+flag.
+
+   The string value will often contain digits at the front to specify
+padding (*note Padding::) and/or `%'-sequences within to specify how to
+encode parameters (*note Parameters::).  Although these things are not
+to be output literally to the terminal, they are considered part of the
+value of the capability.  They are special only when the string value
+is processed by `tputs', `tparam' or `tgoto'.  By contrast, `\' and `^'
+are considered part of the syntax for specifying the characters in the
+string.
+
+   Let's look at the VT52 example again:
+
+     dw|vt52|DEC vt52:\
+             :cr=^M:do=^J:nl=^J:bl=^G:\
+             :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
+             :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
+             :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
+
+   Here we see the numeric-valued capabilities `co' and `li', the flags
+`bs' and `pt', and many string-valued capabilities.  Most of the
+strings start with <ESC> represented as `\E'.  The rest contain control
+characters represented using `^'.  The meanings of the individual
+capabilities are defined elsewhere (*note Capabilities::).
+
+\1f
+File: termcap.info,  Node: Naming,  Next: Inheriting,  Prev: Capability Format,  Up: Data Base
+
+Terminal Type Name Conventions
+==============================
+
+There are conventions for choosing names of terminal types.  For one
+thing, all letters should be in lower case.  The terminal type for a
+terminal in its most usual or most fundamental mode of operation should
+not have a hyphen in it.
+
+   If the same terminal has other modes of operation which require
+different terminal descriptions, these variant descriptions are given
+names made by adding suffixes with hyphens.  Such alternate descriptions
+are used for two reasons:
+
+   * When the terminal has a switch that changes its behavior.  Since
+     the computer cannot tell how the switch is set, the user must tell
+     the computer by choosing the appropriate terminal type name.
+
+     For example, the VT-100 has a setup flag that controls whether the
+     cursor wraps at the right margin.  If this flag is set to "wrap",
+     you must use the terminal type `vt100-am'.  Otherwise you must use
+     `vt100-nam'.  Plain `vt100' is defined as a synonym for either
+     `vt100-am' or `vt100-nam' depending on the preferences of the
+     local site.
+
+     The standard suffix `-am' stands for "automatic margins".
+
+   * To give the user a choice in how to use the terminal.  This is done
+     when the terminal has a switch that the computer normally controls.
+
+     For example, the Ann Arbor Ambassador can be configured with many
+     screen sizes ranging from 20 to 60 lines.  Fewer lines make bigger
+     characters but more lines let you see more of what you are editing.
+     As a result, users have different preferences.  Therefore, termcap
+     provides terminal types for many screen sizes.  If you choose type
+     `aaa-30', the terminal will be configured to use 30 lines; if you
+     choose `aaa-48', 48 lines will be used, and so on.
+
+   Here is a list of standard suffixes and their conventional meanings:
+
+`-w'
+     Short for "wide".  This is a mode that gives the terminal more
+     columns than usual.  This is normally a user option.
+
+`-am'
+     "Automatic margins".  This is an alternate description for use when
+     the terminal's margin-wrap switch is on; it contains the `am'
+     flag.  The implication is that normally the switch is off and the
+     usual description for the terminal says that the switch is off.
+
+`-nam'
+     "No automatic margins".  The opposite of `-am', this names an
+     alternative description which lacks the `am' flag.  This implies
+     that the terminal is normally operated with the margin-wrap switch
+     turned on, and the normal description of the terminal says so.
+
+`-na'
+     "No arrows".  This terminal description initializes the terminal to
+     keep its arrow keys in local mode.  This is a user option.
+
+`-rv'
+     "Reverse video".  This terminal description causes text output for
+     normal video to appear as reverse, and text output for reverse
+     video to come out as normal.  Often this description differs from
+     the usual one by interchanging the two strings which turn reverse
+     video on and off.
+
+     This is a user option; you can choose either the "reverse video"
+     variant terminal type or the normal terminal type, and termcap will
+     obey.
+
+`-s'
+     "Status".  Says to enable use of a status line which ordinary
+     output does not touch (*note Status Line::).
+
+     Some terminals have a special line that is used only as a status
+     line.  For these terminals, there is no need for a `-s' variant;
+     the status line commands should be defined by default.  On other
+     terminals, enabling a status line means removing one screen line
+     from ordinary use and reducing the effective screen height.  For
+     these terminals, the user can choose the `-s' variant type to
+     request use of a status line.
+
+`-NLINES'
+     Says to operate with NLINES lines on the screen, for terminals
+     such as the Ambassador which provide this as an option.  Normally
+     this is a user option; by choosing the terminal type, you control
+     how many lines termcap will use.
+
+`-NPAGESp'
+     Says that the terminal has NPAGES pages worth of screen memory,
+     for terminals where this is a hardware option.
+
+`-unk'
+     Says that description is not for direct use, but only for
+     reference in `tc' capabilities.  Such a description is a kind of
+     subroutine, because it describes the common characteristics of
+     several variant descriptions that would use other suffixes in
+     place of `-unk'.
+
+\1f
+File: termcap.info,  Node: Inheriting,  Prev: Naming,  Up: Data Base
+
+Inheriting from Related Descriptions
+====================================
+
+When two terminal descriptions are similar, their identical parts do not
+need to be given twice.  Instead, one of the two can be defined in
+terms of the other, using the `tc' capability.  We say that one
+description "refers to" the other, or "inherits from" the other.
+
+   The `tc' capability must be the last one in the terminal description,
+and its value is a string which is the name of another terminal type
+which is referred to.  For example,
+
+     N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
+             :ti=\E[2J\E[30;0;0;30p:\
+             :te=\E[60;0;0;30p\E[30;1H\E[J:\
+             :li#30:tc=aaa-unk:
+
+defines the terminal type `aaa-30' (also known as plain `aaa') in terms
+of `aaa-unk', which defines everything about the Ambassador that is
+independent of screen height.  The types `aaa-36', `aaa-48' and so on
+for other screen heights are likewise defined to inherit from `aaa-unk'.
+
+   The capabilities overridden by `aaa-30' include `li', which says how
+many lines there are, and `ti' and `te', which configure the terminal
+to use that many lines.
+
+   The effective terminal description for type `aaa' consists of the
+text shown above followed by the text of the description of `aaa-unk'.
+The `tc' capability is handled automatically by `tgetent', which finds
+the description thus referenced and combines the two descriptions
+(*note Find::).  Therefore, only the implementor of the terminal
+descriptions needs to think about using `tc'.  Users and application
+programmers do not need to be concerned with it.
+
+   Since the reference terminal description is used last, capabilities
+specified in the referring description override any specifications of
+the same capabilities in the reference description.
+
+   The referring description can cancel out a capability without
+specifying any new value for it by means of a special trick.  Write the
+capability in the referring description, with the character `@' after
+the capability name, as follows:
+
+     NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
+             :am@:tc=aaa-30:
+
+\1f
+File: termcap.info,  Node: Capabilities,  Next: Summary,  Prev: Data Base,  Up: Top
+
+Definitions of the Terminal Capabilities
+****************************************
+
+This section is divided into many subsections, each for one aspect of
+use of display terminals.  For writing a display program, you usually
+need only check the subsections for the operations you want to use.
+For writing a terminal description, you must read each subsection and
+fill in the capabilities described there.
+
+   String capabilities that are display commands may require numeric
+parameters (*note Parameters::).  Most such capabilities do not use
+parameters.  When a capability requires parameters, this is explicitly
+stated at the beginning of its definition.  In simple cases, the first
+or second sentence of the definition mentions all the parameters, in
+the order they should be given, using a name in upper case for each
+one.  For example, the `rp' capability is a command that requires two
+parameters; its definition begins as follows:
+
+     String of commands to output a graphic character C, repeated N
+     times.
+
+   In complex cases or when there are many parameters, they are
+described explicitly.
+
+   When a capability is described as obsolete, this means that programs
+should not be written to look for it, but terminal descriptions should
+still be written to provide it.
+
+   When a capability is described as very obsolete, this means that it
+should be omitted from terminal descriptions as well.
+
+* Menu:
+
+* Basic::             Basic characteristics.
+* Screen Size::       Screen size, and what happens when it changes.
+* Cursor Motion::     Various ways to move the cursor.
+* Scrolling::         Pushing text up and down on the screen.
+* Wrapping::          What happens if you write a character in the last column.
+* Windows::           Limiting the part of the window that output affects.
+* Clearing::          Erasing one or many lines.
+* Insdel Line::       Making new blank lines in mid-screen; deleting lines.
+* Insdel Char::       Inserting and deleting characters within a line.
+* Standout::          Highlighting some of the text.
+* Underlining::       Underlining some of the text.
+* Cursor Visibility:: Making the cursor more or less easy to spot.
+* Bell::              Attracts user's attention; not localized on the screen.
+* Keypad::            Recognizing when function keys or arrows are typed.
+* Meta Key::          <META> acts like an extra shift key.
+* Initialization::    Commands used to initialize or reset the terminal.
+* Pad Specs::         Info for the kernel on how much padding is needed.
+* Status Line::       A status line displays ``background'' information.
+* Half-Line::         Moving by half-lines, for superscripts and subscripts.
+* Printer::           Controlling auxiliary printers of display terminals.
+
+\1f
+File: termcap.info,  Node: Basic,  Next: Screen Size,  Prev: Capabilities,  Up: Capabilities
+
+Basic Characteristics
+=====================
+
+This section documents the capabilities that describe the basic and
+nature of the terminal, and also those that are relevant to the output
+of graphic characters.
+
+`os'
+     Flag whose presence means that the terminal can overstrike.  This
+     means that outputting a graphic character does not erase whatever
+     was present in the same character position before.  The terminals
+     that can overstrike include printing terminals, storage tubes (all
+     obsolete nowadays), and many bit-map displays.
+
+`eo'
+     Flag whose presence means that outputting a space can erase an
+     overstrike.  If this is not present and overstriking is supported,
+     output of a space has no effect except to move the cursor.
+
+`gn'
+     Flag whose presence means that this terminal type is a generic type
+     which does not really describe any particular terminal.  Generic
+     types are intended for use as the default type assigned when the
+     user connects to the system, with the intention that the user
+     should specify what type he really has.  One example of a generic
+     type is the type `network'.
+
+     Since the generic type cannot say how to do anything interesting
+     with the terminal, termcap-using programs will always find that the
+     terminal is too weak to be supported if the user has failed to
+     specify a real terminal type in place of the generic one.  The
+     `gn' flag directs these programs to use a different error message:
+     "You have not specified your real terminal type", rather than
+     "Your terminal is not powerful enough to be used".
+
+`hc'
+     Flag whose presence means this is a hardcopy terminal.
+
+`rp'
+     String of commands to output a graphic character C, repeated N
+     times.  The first parameter value is the ASCII code for the desired
+     character, and the second parameter is the number of times to
+     repeat the character.  Often this command requires padding
+     proportional to the number of times the character is repeated.
+     This effect can be had by using parameter arithmetic with
+     `%'-sequences to compute the amount of padding, then generating
+     the result as a number at the front of the string so that `tputs'
+     will treat it as padding.
+
+`hz'
+     Flag whose presence means that the ASCII character `~' cannot be
+     output on this terminal because it is used for display commands.
+
+     Programs handle this flag by checking all text to be output and
+     replacing each `~' with some other character(s).  If this is not
+     done, the screen will be thoroughly garbled.
+
+     The old Hazeltine terminals that required such treatment are
+     probably very rare today, so you might as well not bother to
+     support this flag.
+
+`CC'
+     String whose presence means the terminal has a settable command
+     character.  The value of the string is the default command
+     character (which is usually <ESC>).
+
+     All the strings of commands in the terminal description should be
+     written to use the default command character.  If you are writing
+     an application program that changes the command character, use the
+     `CC' capability to figure out how to translate all the display
+     commands to work with the new command character.
+
+     Most programs have no reason to look at the `CC' capability.
+
+`xb'
+     Flag whose presence identifies Superbee terminals which are unable
+     to transmit the characters <ESC> and `Control-C'.  Programs which
+     support this flag are supposed to check the input for the code
+     sequences sent by the <F1> and <F2> keys, and pretend that <ESC>
+     or `Control-C' (respectively) had been read.  But this flag is
+     obsolete, and not worth supporting.
+
+\1f
+File: termcap.info,  Node: Screen Size,  Next: Cursor Motion,  Prev: Basic,  Up: Capabilities
+
+Screen Size
+===========
+
+A terminal description has two capabilities, `co' and `li', that
+describe the screen size in columns and lines.  But there is more to
+the question of screen size than this.
+
+   On some operating systems the "screen" is really a window and the
+effective width can vary.  On some of these systems, `tgetnum' uses the
+actual width of the window to decide what value to return for the `co'
+capability, overriding what is actually written in the terminal
+description.  On other systems, it is up to the application program to
+check the actual window width using a system call.  For example, on BSD
+4.3 systems, the system call `ioctl' with code `TIOCGWINSZ' will tell
+you the current screen size.
+
+   On all window systems, termcap is powerless to advise the application
+program if the user resizes the window.  Application programs must deal
+with this possibility in a system-dependent fashion.  On some systems
+the C shell handles part of the problem by detecting changes in window
+size and setting the `TERMCAP' environment variable appropriately.
+This takes care of application programs that are started subsequently.
+It does not help application programs already running.
+
+   On some systems, including BSD 4.3, all programs using a terminal get
+a signal named `SIGWINCH' whenever the screen size changes.  Programs
+that use termcap should handle this signal by using `ioctl TIOCGWINSZ'
+to learn the new screen size.
+
+`co'
+     Numeric value, the width of the screen in character positions.
+     Even hardcopy terminals normally have a `co' capability.
+
+`li'
+     Numeric value, the height of the screen in lines.
+
+\1f
+File: termcap.info,  Node: Cursor Motion,  Next: Wrapping,  Prev: Screen Size,  Up: Capabilities
+
+Cursor Motion
+=============
+
+Termcap assumes that the terminal has a "cursor", a spot on the screen
+where a visible mark is displayed, and that most display commands take
+effect at the position of the cursor.  It follows that moving the cursor
+to a specified location is very important.
+
+   There are many terminal capabilities for different cursor motion
+operations.  A terminal description should define as many as possible,
+but most programs do not need to use most of them.  One capability,
+`cm', moves the cursor to an arbitrary place on the screen; this by
+itself is sufficient for any application as long as there is no need to
+support hardcopy terminals or certain old, weak displays that have only
+relative motion commands.  Use of other cursor motion capabilities is an
+optimization, enabling the program to output fewer characters in some
+common cases.
+
+   If you plan to use the relative cursor motion commands in an
+application program, you must know what the starting cursor position
+is.  To do this, you must keep track of the cursor position and update
+the records each time anything is output to the terminal, including
+graphic characters.  In addition, it is necessary to know whether the
+terminal wraps after writing in the rightmost column.  *Note Wrapping::.
+
+   One other motion capability needs special mention: `nw' moves the
+cursor to the beginning of the following line, perhaps clearing all the
+starting line after the cursor, or perhaps not clearing at all.  This
+capability is a least common denominator that is probably supported
+even by terminals that cannot do most other things such as `cm' or `do'.
+Even hardcopy terminals can support `nw'.
+
+`cm'
+     String of commands to position the cursor at line L, column C.
+     Both parameters are origin-zero, and are defined relative to the
+     screen, not relative to display memory.
+
+     All display terminals except a few very obsolete ones support `cm',
+     so it is acceptable for an application program to refuse to
+     operate on terminals lacking `cm'.
+
+`ho'
+     String of commands to move the cursor to the upper left corner of
+     the screen (this position is called the "home position").  In
+     terminals where the upper left corner of the screen is not the
+     same as the beginning of display memory, this command must go to
+     the upper left corner of the screen, not the beginning of display
+     memory.
+
+     Every display terminal supports this capability, and many
+     application programs refuse to operate if the `ho' capability is
+     missing.
+
+`ll'
+     String of commands to move the cursor to the lower left corner of
+     the screen.  On some terminals, moving up from home position does
+     this, but programs should never assume that will work.  Just
+     output the `ll' string (if it is provided); if moving to home
+     position and then moving up is the best way to get there, the `ll'
+     command will do that.
+
+`cr'
+     String of commands to move the cursor to the beginning of the line
+     it is on.  If this capability is not specified, many programs
+     assume they can use the ASCII carriage return character for this.
+
+`le'
+     String of commands to move the cursor left one column.  Unless the
+     `bw' flag capability is specified, the effect is undefined if the
+     cursor is at the left margin; do not use this command there.  If
+     `bw' is present, this command may be used at the left margin, and
+     it wraps the cursor to the last column of the preceding line.
+
+`nd'
+     String of commands to move the cursor right one column.  The
+     effect is undefined if the cursor is at the right margin; do not
+     use this command there, not even if `am' is present.
+
+`up'
+     String of commands to move the cursor vertically up one line.  The
+     effect of sending this string when on the top line is undefined;
+     programs should never use it that way.
+
+`do'
+     String of commands to move the cursor vertically down one line.
+     The effect of sending this string when on the bottom line is
+     undefined; programs should never use it that way.
+
+     The original idea was that this string would not contain a newline
+     character and therefore could be used without disabling the
+     kernel's usual habit of converting of newline into a
+     carriage-return newline sequence.  But many terminal descriptions
+     do use newline in the `do' string, so this is not possible; a
+     program which sends the `do' string must disable output conversion
+     in the kernel (*note Initialize::).
+
+`bw'
+     Flag whose presence says that `le' may be used in column zero to
+     move to the last column of the preceding line.  If this flag is
+     not present, `le' should not be used in column zero.
+
+`nw'
+     String of commands to move the cursor to start of next line,
+     possibly clearing rest of line (following the cursor) before
+     moving.
+
+`DO', `UP', `LE', `RI'
+     Strings of commands to move the cursor N lines down vertically, up
+     vertically, or N columns left or right.  Do not attempt to move
+     past any edge of the screen with these commands; the effect of
+     trying that is undefined.  Only a few terminal descriptions provide
+     these commands, and most programs do not use them.
+
+`CM'
+     String of commands to position the cursor at line L, column C,
+     relative to display memory.  Both parameters are origin-zero.
+     This capability is present only in terminals where there is a
+     difference between screen-relative and memory-relative addressing,
+     and not even in all such terminals.
+
+`ch'
+     String of commands to position the cursor at column C in the same
+     line it is on.  This is a special case of `cm' in which the
+     vertical position is not changed.  The `ch' capability is provided
+     only when it is faster to output than `cm' would be in this
+     special case.  Programs should not assume most display terminals
+     have `ch'.
+
+`cv'
+     String of commands to position the cursor at line L in the same
+     column.  This is a special case of `cm' in which the horizontal
+     position is not changed.  The `cv' capability is provided only
+     when it is faster to output than `cm' would be in this special
+     case.  Programs should not assume most display terminals have `cv'.
+
+`sc'
+     String of commands to make the terminal save the current cursor
+     position.  Only the last saved position can be used.  If this
+     capability is present, `rc' should be provided also.  Most
+     terminals have neither.
+
+`rc'
+     String of commands to make the terminal restore the last saved
+     cursor position.  If this capability is present, `sc' should be
+     provided also.  Most terminals have neither.
+
+`ff'
+     String of commands to advance to the next page, for a hardcopy
+     terminal.
+
+`ta'
+     String of commands to move the cursor right to the next hardware
+     tab stop column.  Missing if the terminal does not have any kind of
+     hardware tabs.  Do not send this command if the kernel's terminal
+     modes say that the kernel is expanding tabs into spaces.
+
+`bt'
+     String of commands to move the cursor left to the previous hardware
+     tab stop column.  Missing if the terminal has no such ability; many
+     terminals do not.  Do not send this command if the kernel's
+     terminal modes say that the kernel is expanding tabs into spaces.
+
+   The following obsolete capabilities should be included in terminal
+descriptions when appropriate, but should not be looked at by new
+programs.
+
+`nc'
+     Flag whose presence means the terminal does not support the ASCII
+     carriage return character as `cr'.  This flag is needed because
+     old programs assume, when the `cr' capability is missing, that
+     ASCII carriage return can be used for the purpose.  We use `nc' to
+     tell the old programs that carriage return may not be used.
+
+     New programs should not assume any default for `cr', so they need
+     not look at `nc'.  However, descriptions should contain `nc'
+     whenever they do not contain `cr'.
+
+`xt'
+     Flag whose presence means that the ASCII tab character may not be
+     used for cursor motion.  This flag exists because old programs
+     assume, when the `ta' capability is missing, that ASCII tab can be
+     used for the purpose.  We use `xt' to tell the old programs not to
+     use tab.
+
+     New programs should not assume any default for `ta', so they need
+     not look at `xt' in connection with cursor motion.  Note that `xt'
+     also has implications for standout mode (*note Standout::).  It is
+     obsolete in regard to cursor motion but not in regard to standout.
+
+     In fact, `xt' means that the terminal is a Teleray 1061.
+
+`bc'
+     Very obsolete alternative name for the `le' capability.
+
+`bs'
+     Flag whose presence means that the ASCII character backspace may be
+     used to move the cursor left.  Obsolete; look at `le' instead.
+
+`nl'
+     Obsolete capability which is a string that can either be used to
+     move the cursor down or to scroll.  The same string must scroll
+     when used on the bottom line and move the cursor when used on any
+     other line.  New programs should use `do' or `sf', and ignore `nl'.
+
+     If there is no `nl' capability, some old programs assume they can
+     use the newline character for this purpose.  These programs follow
+     a bad practice, but because they exist, it is still desirable to
+     define the `nl' capability in a terminal description if the best
+     way to move down is _not_ a newline.
+
+\1f
+File: termcap.info,  Node: Wrapping,  Next: Scrolling,  Prev: Cursor Motion,  Up: Capabilities
+
+Wrapping
+========
+
+"Wrapping" means moving the cursor from the right margin to the left
+margin of the following line.  Some terminals wrap automatically when a
+graphic character is output in the last column, while others do not.
+Most application programs that use termcap need to know whether the
+terminal wraps.  There are two special flag capabilities to describe
+what the terminal does when a graphic character is output in the last
+column.
+
+`am'
+     Flag whose presence means that writing a character in the last
+     column causes the cursor to wrap to the beginning of the next line.
+
+     If `am' is not present, writing in the last column leaves the
+     cursor at the place where the character was written.
+
+     Writing in the last column of the last line should be avoided on
+     terminals with `am', as it may or may not cause scrolling to occur
+     (*note Scrolling::).  Scrolling is surely not what you would
+     intend.
+
+     If your program needs to check the `am' flag, then it also needs
+     to check the `xn' flag which indicates that wrapping happens in a
+     strange way.  Many common terminals have the `xn' flag.
+
+`xn'
+     Flag whose presence means that the cursor wraps in a strange way.
+     At least two distinct kinds of strange behavior are known; the
+     termcap data base does not contain anything to distinguish the two.
+
+     On Concept-100 terminals, output in the last column wraps the
+     cursor almost like an ordinary `am' terminal.  But if the next
+     thing output is a newline, it is ignored.
+
+     DEC VT-100 terminals (when the wrap switch is on) do a different
+     strange thing: the cursor wraps only if the next thing output is
+     another graphic character.  In fact, the wrap occurs when the
+     following graphic character is received by the terminal, before the
+     character is placed on the screen.
+
+     On both of these terminals, after writing in the last column a
+     following graphic character will be displayed in the first column
+     of the following line.  But the effect of relative cursor motion
+     characters such as newline or backspace at such a time depends on
+     the terminal.  The effect of erase or scrolling commands also
+     depends on the terminal.  You can't assume anything about what
+     they will do on a terminal that has `xn'.  So, to be safe, you
+     should never do these things at such a time on such a terminal.
+
+     To be sure of reliable results on a terminal which has the `xn'
+     flag, output a `cm' absolute positioning command after writing in
+     the last column.  Another safe thing to do is to output
+     carriage-return newline, which will leave the cursor at the
+     beginning of the following line.
+
+\1f
+File: termcap.info,  Node: Scrolling,  Next: Windows,  Prev: Wrapping,  Up: Capabilities
+
+Scrolling
+=========
+
+"Scrolling" means moving the contents of the screen up or down one or
+more lines.  Moving the contents up is "forward scrolling"; moving them
+down is "reverse scrolling".
+
+   Scrolling happens after each line of output during ordinary output
+on most display terminals.  But in an application program that uses
+termcap for random-access output, scrolling happens only when
+explicitly requested with the commands in this section.
+
+   Some terminals have a "scroll region" feature.  This lets you limit
+the effect of scrolling to a specified range of lines.  Lines outside
+the range are unaffected when scrolling happens.  The scroll region
+feature is available if either `cs' or `cS' is present.
+
+`sf'
+     String of commands to scroll the screen one line up, assuming it is
+     output with the cursor at the beginning of the bottom line.
+
+`sr'
+     String of commands to scroll the screen one line down, assuming it
+     is output with the cursor at the beginning of the top line.
+
+`SF'
+     String of commands to scroll the screen N lines up, assuming it is
+     output with the cursor at the beginning of the bottom line.
+
+`SR'
+     String of commands to scroll the screen N line down, assuming it
+     is output with the cursor at the beginning of the top line.
+
+`cs'
+     String of commands to set the scroll region.  This command takes
+     two parameters, START and END, which are the line numbers
+     (origin-zero) of the first line to include in the scroll region
+     and of the last line to include in it.  When a scroll region is
+     set, scrolling is limited to the specified range of lines; lines
+     outside the range are not affected by scroll commands.
+
+     Do not try to move the cursor outside the scroll region.  The
+     region remains set until explicitly removed.  To remove the scroll
+     region, use another `cs' command specifying the full height of the
+     screen.
+
+     The cursor position is undefined after the `cs' command is set, so
+     position the cursor with `cm' immediately afterward.
+
+`cS'
+     String of commands to set the scroll region using parameters in
+     different form.  The effect is the same as if `cs' were used.
+     Four parameters are required:
+
+       1. Total number of lines on the screen.
+
+       2. Number of lines above desired scroll region.
+
+       3. Number of lines below (outside of) desired scroll region.
+
+       4. Total number of lines on the screen, the same as the first
+          parameter.
+
+     This capability is a GNU extension that was invented to allow the
+     Ann Arbor Ambassador's scroll-region command to be described; it
+     could also be done by putting non-Unix `%'-sequences into a `cs'
+     string, but that would have confused Unix programs that used the
+     `cs' capability with the Unix termcap.  Currently only GNU Emacs
+     uses the `cS' capability.
+
+`ns'
+     Flag which means that the terminal does not normally scroll for
+     ordinary sequential output.  For modern terminals, this means that
+     outputting a newline in ordinary sequential output with the cursor
+     on the bottom line wraps to the top line.  For some obsolete
+     terminals, other things may happen.
+
+     The terminal may be able to scroll even if it does not normally do
+     so.  If the `sf' capability is provided, it can be used for
+     scrolling regardless of `ns'.
+
+`da'
+     Flag whose presence means that lines scrolled up off the top of the
+     screen may come back if scrolling down is done subsequently.
+
+     The `da' and `db' flags do not, strictly speaking, affect how to
+     scroll.  But programs that scroll usually need to clear the lines
+     scrolled onto the screen, if these flags are present.
+
+`db'
+     Flag whose presence means that lines scrolled down off the bottom
+     of the screen may come back if scrolling up is done subsequently.
+
+`lm'
+     Numeric value, the number of lines of display memory that the
+     terminal has.  A value of zero means that the terminal has more
+     display memory than can fit on the screen, but no fixed number of
+     lines.  (The number of lines may depend on the amount of text in
+     each line.)
+
+   Any terminal description that defines `SF' should also define `sf';
+likewise for `SR' and `sr'.  However, many terminals can only scroll by
+one line at a time, so it is common to find `sf' and not `SF', or `sr'
+without `SR'.
+
+   Therefore, all programs that use the scrolling facilities should be
+prepared to work with `sf' in the case that `SF' is absent, and
+likewise with `sr'.  On the other hand, an application program that
+uses only `sf' and not `SF' is acceptable, though slow on some
+terminals.
+
+   When outputting a scroll command with `tputs', the NLINES argument
+should be the total number of lines in the portion of the screen being
+scrolled.  Very often these commands require padding proportional to
+this number of lines.  *Note Padding::.
+
+\1f
+File: termcap.info,  Node: Windows,  Next: Clearing,  Prev: Scrolling,  Up: Capabilities
+
+Windows
+=======
+
+A "window", in termcap, is a rectangular portion of the screen to which
+all display operations are restricted.  Wrapping, clearing, scrolling,
+insertion and deletion all operate as if the specified window were all
+the screen there was.
+
+`wi'
+     String of commands to set the terminal output screen window.  This
+     string requires four parameters, all origin-zero:
+       1. The first line to include in the window.
+
+       2. The last line to include in the window.
+
+       3. The first column to include in the window.
+
+       4. The last column to include in the window.
+
+   Most terminals do not support windows.
+
+\1f
+File: termcap.info,  Node: Clearing,  Next: Insdel Line,  Prev: Windows,  Up: Capabilities
+
+Clearing Parts of the Screen
+============================
+
+There are several terminal capabilities for clearing parts of the screen
+to blank.  All display terminals support the `cl' string, and most
+display terminals support all of these capabilities.
+
+`cl'
+     String of commands to clear the entire screen and position the
+     cursor at the upper left corner.
+
+`cd'
+     String of commands to clear the line the cursor is on, and all the
+     lines below it, down to the bottom of the screen.  This command
+     string should be used only with the cursor in column zero; their
+     effect is undefined if the cursor is elsewhere.
+
+`ce'
+     String of commands to clear from the cursor to the end of the
+     current line.
+
+`ec'
+     String of commands to clear N characters, starting with the
+     character that the cursor is on.  This command string is expected
+     to leave the cursor position unchanged.  The parameter N should
+     never be large enough to reach past the right margin; the effect
+     of such a large parameter would be undefined.
+
+   Clear to end of line (`ce') is extremely important in programs that
+maintain an updating display.  Nearly all display terminals support this
+operation, so it is acceptable for an application program to refuse to
+work if `ce' is not present.  However, if you do not want this
+limitation, you can accomplish clearing to end of line by outputting
+spaces until you reach the right margin.  In order to do this, you must
+know the current horizontal position.  Also, this technique assumes
+that writing a space will erase.  But this happens to be true on all
+the display terminals that fail to support `ce'.
+
+\1f
+File: termcap.info,  Node: Insdel Line,  Next: Insdel Char,  Prev: Clearing,  Up: Capabilities
+
+Insert/Delete Line
+==================
+
+"Inserting a line" means creating a blank line in the middle of the
+screen, and pushing the existing lines of text apart.  In fact, the
+lines above the insertion point do not change, while the lines below
+move down, and one is normally lost at the bottom of the screen.
+
+   "Deleting a line" means causing the line to disappear from the
+screen, closing up the gap by moving the lines below it upward.  A new
+line appears at the bottom of the screen.  Usually this line is blank,
+but on terminals with the `db' flag it may be a line previously moved
+off the screen bottom by scrolling or line insertion.
+
+   Insertion and deletion of lines is useful in programs that maintain
+an updating display some parts of which may get longer or shorter.
+They are also useful in editors for scrolling parts of the screen, and
+for redisplaying after lines of text are killed or inserted.
+
+   Many terminals provide commands to insert or delete a single line at
+the cursor position.  Some provide the ability to insert or delete
+several lines with one command, using the number of lines to insert or
+delete as a parameter.  Always move the cursor to column zero before
+using any of these commands.
+
+`al'
+     String of commands to insert a blank line before the line the
+     cursor is on.  The existing line, and all lines below it, are
+     moved down.  The last line in the screen (or in the scroll region,
+     if one is set) disappears and in most circumstances is discarded.
+     It may not be discarded if the `db' is present (*note Scrolling::).
+
+     The cursor must be at the left margin before this command is used.
+     This command does not move the cursor.
+
+`dl'
+     String of commands to delete the line the cursor is on.  The
+     following lines move up, and a blank line appears at the bottom of
+     the screen (or bottom of the scroll region).  If the terminal has
+     the `db' flag, a nonblank line previously pushed off the screen
+     bottom may reappear at the bottom.
+
+     The cursor must be at the left margin before this command is used.
+     This command does not move the cursor.
+
+`AL'
+     String of commands to insert N blank lines before the line that
+     the cursor is on.  It is like `al' repeated N times, except that
+     it is as fast as one `al'.
+
+`DL'
+     String of commands to delete N lines starting with the line that
+     the cursor is on.  It is like `dl' repeated N times, except that
+     it is as fast as one `dl'.
+
+   Any terminal description that defines `AL' should also define `al';
+likewise for `DL' and `dl'.  However, many terminals can only insert or
+delete one line at a time, so it is common to find `al' and not `AL',
+or `dl' without `DL'.
+
+   Therefore, all programs that use the insert and delete facilities
+should be prepared to work with `al' in the case that `AL' is absent,
+and likewise with `dl'.  On the other hand, it is acceptable to write
+an application that uses only `al' and `dl' and does not look for `AL'
+or `DL' at all.
+
+   If a terminal does not support line insertion and deletion directly,
+but does support a scroll region, the effect of insertion and deletion
+can be obtained with scrolling.  However, it is up to the individual
+user program to check for this possibility and use the scrolling
+commands to get the desired result.  It is fairly important to implement
+this alternate strategy, since it is the only way to get the effect of
+line insertion and deletion on the popular VT100 terminal.
+
+   Insertion and deletion of lines is affected by the scroll region on
+terminals that have a settable scroll region.  This is useful when it is
+desirable to move any few consecutive lines up or down by a few lines.
+*Note Scrolling::.
+
+   The line pushed off the bottom of the screen is not lost if the
+terminal has the `db' flag capability; instead, it is pushed into
+display memory that does not appear on the screen.  This is the same
+thing that happens when scrolling pushes a line off the bottom of the
+screen.  Either reverse scrolling or deletion of a line can bring the
+apparently lost line back onto the bottom of the screen.  If the
+terminal has the scroll region feature as well as `db', the pushed-out
+line really is lost if a scroll region is in effect.
+
+   When outputting an insert or delete command with `tputs', the NLINES
+argument should be the total number of lines from the cursor to the
+bottom of the screen (or scroll region).  Very often these commands
+require padding proportional to this number of lines.  *Note Padding::.
+
+   For `AL' and `DL' the NLINES argument should _not_ depend on the
+number of lines inserted or deleted; only the total number of lines
+affected.  This is because it is just as fast to insert two or N lines
+with `AL' as to insert one line with `al'.
+
+\1f
+File: termcap.info,  Node: Insdel Char,  Next: Standout,  Prev: Insdel Line,  Up: Capabilities
+
+Insert/Delete Character
+=======================
+
+"Inserting a character" means creating a blank space in the middle of a
+line, and pushing the rest of the line rightward.  The character in the
+rightmost column is lost.
+
+   "Deleting a character" means causing the character to disappear from
+the screen, closing up the gap by moving the rest of the line leftward.
+A blank space appears in the rightmost column.
+
+   Insertion and deletion of characters is useful in programs that
+maintain an updating display some parts of which may get longer or
+shorter.  It is also useful in editors for redisplaying the results of
+editing within a line.
+
+   Many terminals provide commands to insert or delete a single
+character at the cursor position.  Some provide the ability to insert
+or delete several characters with one command, using the number of
+characters to insert or delete as a parameter.
+
+   Many terminals provide an insert mode in which outputting a graphic
+character has the added effect of inserting a position for that
+character.  A special command string is used to enter insert mode and
+another is used to exit it.  The reason for designing a terminal with
+an insert mode rather than an insert command is that inserting
+character positions is usually followed by writing characters into
+them.  With insert mode, this is as fast as simply writing the
+characters, except for the fixed overhead of entering and leaving
+insert mode.  However, when the line speed is great enough, padding may
+be required for the graphic characters output in insert mode.
+
+   Some terminals require you to enter insert mode and then output a
+special command for each position to be inserted.  Or they may require
+special commands to be output before or after each graphic character to
+be inserted.
+
+   Deletion of characters is usually accomplished by a straightforward
+command to delete one or several positions; but on some terminals, it
+is necessary to enter a special delete mode before using the delete
+command, and leave delete mode afterward.  Sometimes delete mode and
+insert mode are the same mode.
+
+   Some terminals make a distinction between character positions in
+which a space character has been output and positions which have been
+cleared.  On these terminals, the effect of insert or delete character
+runs to the first cleared position rather than to the end of the line.
+In fact, the effect may run to more than one line if there is no
+cleared position to stop the shift on the first line.  These terminals
+are identified by the `in' flag capability.
+
+   On terminals with the `in' flag, the technique of skipping over
+characters that you know were cleared, and then outputting text later
+on in the same line, causes later insert and delete character
+operations on that line to do nonstandard things.  A program that has
+any chance of doing this must check for the `in' flag and must be
+careful to write explicit space characters into the intermediate
+columns when `in' is present.
+
+   A plethora of terminal capabilities are needed to describe all of
+this complexity.  Here is a list of them all.  Following the list, we
+present an algorithm for programs to use to take proper account of all
+of these capabilities.
+
+`im'
+     String of commands to enter insert mode.
+
+     If the terminal has no special insert mode, but it can insert
+     characters with a special command, `im' should be defined with a
+     null value, because the `vi' editor assumes that insertion of a
+     character is impossible if `im' is not provided.
+
+     New programs should not act like `vi'.  They should pay attention
+     to `im' only if it is defined.
+
+`ei'
+     String of commands to leave insert mode.  This capability must be
+     present if `im' is.
+
+     On a few old terminals the same string is used to enter and exit
+     insert mode.  This string turns insert mode on if it was off, and
+     off if it was on.  You can tell these terminals because the `ei'
+     string equals the `im' string.  If you want to support these
+     terminals, you must always remember accurately whether insert mode
+     is in effect.  However, these terminals are obsolete, and it is
+     reasonable to refuse to support them.  On all modern terminals, you
+     can safely output `ei' at any time to ensure that insert mode is
+     turned off.
+
+`ic'
+     String of commands to insert one character position at the cursor.
+     The cursor does not move.
+
+     If outputting a graphic character while in insert mode is
+     sufficient to insert the character, then the `ic' capability
+     should be defined with a null value.
+
+     If your terminal offers a choice of ways to insert--either use
+     insert mode or use a special command--then define `im' and do not
+     define `ic', since this gives the most efficient operation when
+     several characters are to be inserted.  _Do not_ define both
+     strings, for that means that _both_ must be used each time
+     insertion is done.
+
+`ip'
+     String of commands to output following an inserted graphic
+     character in insert mode.  Often it is used just for a padding
+     spec, when padding is needed after an inserted character (*note
+     Padding::).
+
+`IC'
+     String of commands to insert N character positions at and after
+     the cursor.  It has the same effect as repeating the `ic' string
+     and a space, N times.
+
+     If `IC' is provided, application programs may use it without first
+     entering insert mode.
+
+`mi'
+     Flag whose presence means it is safe to move the cursor while in
+     insert mode and assume the terminal remains in insert mode.
+
+`in'
+     Flag whose presence means that the terminal distinguishes between
+     character positions in which space characters have been output and
+     positions which have been cleared.
+
+   An application program can assume that the terminal can do character
+insertion if _any one of_ the capabilities `IC', `im', `ic' or `ip' is
+provided.
+
+   To insert N blank character positions, move the cursor to the place
+to insert them and follow this algorithm:
+
+  1. If an `IC' string is provided, output it with parameter N and you
+     are finished.  Otherwise (or if you don't want to bother to look
+     for an `IC' string) follow the remaining steps.
+
+  2. Output the `im' string, if there is one, unless the terminal is
+     already in insert mode.
+
+  3. Repeat steps 4 through 6, N times.
+
+  4. Output the `ic' string if any.
+
+  5. Output a space.
+
+  6. Output the `ip' string if any.
+
+  7. Output the `ei' string, eventually, to exit insert mode.  There is
+     no need to do this right away.  If the `mi' flag is present, you
+     can move the cursor and the cursor will remain in insert mode;
+     then you can do more insertion elsewhere without reentering insert
+     mode.
+
+   To insert N graphic characters, position the cursor and follow this
+algorithm:
+
+  1. If an `IC' string is provided, output it with parameter N, then
+     output the graphic characters, and you are finished.  Otherwise
+     (or if you don't want to bother to look for an `IC' string) follow
+     the remaining steps.
+
+  2. Output the `im' string, if there is one, unless the terminal is
+     already in insert mode.
+
+  3. For each character to be output, repeat steps 4 through 6.
+
+  4. Output the `ic' string if any.
+
+  5. Output the next graphic character.
+
+  6. Output the `ip' string if any.
+
+  7. Output the `ei' string, eventually, to exit insert mode.  There is
+     no need to do this right away.  If the `mi' flag is present, you
+     can move the cursor and the cursor will remain in insert mode;
+     then you can do more insertion elsewhere without reentering insert
+     mode.
+
+   Note that this is not the same as the original Unix termcap
+specifications in one respect: it assumes that the `IC' string can be
+used without entering insert mode.  This is true as far as I know, and
+it allows you be able to avoid entering and leaving insert mode, and
+also to be able to avoid the inserted-character padding after the
+characters that go into the inserted positions.
+
+   Deletion of characters is less complicated; deleting one column is
+done by outputting the `dc' string.  However, there may be a delete
+mode that must be entered with `dm' in order to make `dc' work.
+
+`dc'
+     String of commands to delete one character position at the cursor.
+     If `dc' is not present, the terminal cannot delete characters.
+
+`DC'
+     String of commands to delete N characters starting at the cursor.
+     It has the same effect as repeating the `dc' string N times.  Any
+     terminal description that has `DC' also has `dc'.
+
+`dm'
+     String of commands to enter delete mode.  If not present, there is
+     no delete mode, and `dc' can be used at any time (assuming there is
+     a `dc').
+
+`ed'
+     String of commands to exit delete mode.  This must be present if
+     `dm' is.
+
+   To delete N character positions, position the cursor and follow these
+steps:
+
+  1. If the `DC' string is present, output it with parameter N and you
+     are finished.  Otherwise, follow the remaining steps.
+
+  2. Output the `dm' string, unless you know the terminal is already in
+     delete mode.
+
+  3. Output the `dc' string N times.
+
+  4. Output the `ed' string eventually.  If the flag capability `mi' is
+     present, you can move the cursor and do more deletion without
+     leaving and reentering delete mode.
+
+   As with the `IC' string, we have departed from the original termcap
+specifications by assuming that `DC' works without entering delete mode
+even though `dc' would not.
+
+   If the `dm' and `im' capabilities are both present and have the same
+value, it means that the terminal has one mode for both insertion and
+deletion.  It is useful for a program to know this, because then it can
+do insertions after deletions, or vice versa, without leaving
+insert/delete mode and reentering it.
+
+\1f
+File: termcap.info,  Node: Standout,  Next: Underlining,  Prev: Insdel Char,  Up: Capabilities
+
+Standout and Appearance Modes
+=============================
+
+"Appearance modes" are modifications to the ways characters are
+displayed.  Typical appearance modes include reverse video, dim, bright,
+blinking, underlined, invisible, and alternate character set.  Each
+kind of terminal supports various among these, or perhaps none.
+
+   For each type of terminal, one appearance mode or combination of
+them that looks good for highlighted text is chosen as the "standout
+mode".  The capabilities `so' and `se' say how to enter and leave
+standout mode.  Programs that use appearance modes only to highlight
+some text generally use the standout mode so that they can work on as
+many terminals as possible.  Use of specific appearance modes other
+than "underlined" and "alternate character set" is rare.
+
+   Terminals that implement appearance modes fall into two general
+classes as to how they do it.
+
+   In some terminals, the presence or absence of any appearance mode is
+recorded separately for each character position.  In these terminals,
+each graphic character written is given the appearance modes current at
+the time it is written, and keeps those modes until it is erased or
+overwritten.  There are special commands to turn the appearance modes
+on or off for characters to be written in the future.
+
+   In other terminals, the change of appearance modes is represented by
+a marker that belongs to a certain screen position but affects all
+following screen positions until the next marker.  These markers are
+traditionally called "magic cookies".
+
+   The same capabilities (`so', `se', `mb' and so on) for turning
+appearance modes on and off are used for both magic-cookie terminals
+and per-character terminals.  On magic cookie terminals, these give the
+commands to write the magic cookies.  On per-character terminals, they
+change the current modes that affect future output and erasure.  Some
+simple applications can use these commands without knowing whether or
+not they work by means of cookies.
+
+   However, a program that maintains and updates a display needs to know
+whether the terminal uses magic cookies, and exactly what their effect
+is.  This information comes from the `sg' capability.
+
+   The `sg' capability is a numeric capability whose presence indicates
+that the terminal uses magic cookies for appearance modes.  Its value is
+the number of character positions that a magic cookie occupies.  Usually
+the cookie occupies one or more character positions on the screen, and
+these character positions are displayed as blank, but in some terminals
+the cookie has zero width.
+
+   The `sg' capability describes both the magic cookie to turn standout
+on and the cookie to turn it off.  This makes the assumption that both
+kinds of cookie have the same width on the screen.  If that is not true,
+the narrower cookie must be "widened" with spaces until it has the same
+width as the other.
+
+   On some magic cookie terminals, each line always starts with normal
+display; in other words, the scope of a magic cookie never extends over
+more than one line.  But on other terminals, one magic cookie affects
+all the lines below it unless explicitly canceled.  Termcap does not
+define any way to distinguish these two ways magic cookies can work.
+To be safe, it is best to put a cookie at the beginning of each line.
+
+   On some per-character terminals, standout mode or other appearance
+modes may be canceled by moving the cursor.  On others, moving the
+cursor has no effect on the state of the appearance modes.  The latter
+class of terminals are given the flag capability `ms' ("can move in
+standout").  All programs that might have occasion to move the cursor
+while appearance modes are turned on must check for this flag; if it is
+not present, they should reset appearance modes to normal before doing
+cursor motion.
+
+   A program that has turned on only standout mode should use `se' to
+reset the standout mode to normal.  A program that has turned on only
+alternate character set mode should use `ae' to return it to normal.
+If it is possible that any other appearance modes are turned on, use the
+`me' capability to return them to normal.
+
+   Note that the commands to turn on one appearance mode, including `so'
+and `mb' ... `mr', if used while some other appearance modes are turned
+on, may combine the two modes on some terminals but may turn off the
+mode previously enabled on other terminals.  This is because some
+terminals do not have a command to set or clear one appearance mode
+without changing the others.  Programs should not attempt to use
+appearance modes in combination except with `sa', and when switching
+from one single mode to another should always turn off the previously
+enabled mode and then turn on the new desired mode.
+
+   On some old terminals, the `so' and `se' commands may be the same
+command, which has the effect of turning standout on if it is off, or
+off it is on.  It is therefore risky for a program to output extra `se'
+commands for good measure.  Fortunately, all these terminals are
+obsolete.
+
+   Programs that update displays in which standout-text may be replaced
+with non-standout text must check for the `xs' flag.  In a per-character
+terminal, this flag says that the only way to remove standout once
+written is to clear that portion of the line with the `ce' string or
+something even more powerful (*note Clearing::); just writing new
+characters at those screen positions will not change the modes in
+effect there.  In a magic cookie terminal, `xs' says that the only way
+to remove a cookie is to clear a portion of the line that includes the
+cookie; writing a different cookie at the same position does not work.
+
+   Such programs must also check for the `xt' flag, which means that the
+terminal is a Teleray 1061.  On this terminal it is impossible to
+position the cursor at the front of a magic cookie, so the only two
+ways to remove a cookie are (1) to delete the line it is on or (2) to
+position the cursor at least one character before it (possibly on a
+previous line) and output the `se' string, which on these terminals
+finds and removes the next `so' magic cookie on the screen.  (It may
+also be possible to remove a cookie which is not at the beginning of a
+line by clearing that line.)  The `xt' capability also has implications
+for the use of tab characters, but in that regard it is obsolete (*note
+Cursor Motion::).
+
+`so'
+     String of commands to enter standout mode.
+
+`se'
+     String of commands to leave standout mode.
+
+`sg'
+     Numeric capability, the width on the screen of the magic cookie.
+     This capability is absent in terminals that record appearance modes
+     character by character.
+
+`ms'
+     Flag whose presence means that it is safe to move the cursor while
+     the appearance modes are not in the normal state.  If this flag is
+     absent, programs should always reset the appearance modes to
+     normal before moving the cursor.
+
+`xs'
+     Flag whose presence means that the only way to reset appearance
+     modes already on the screen is to clear to end of line.  On a
+     per-character terminal, you must clear the area where the modes
+     are set.  On a magic cookie terminal, you must clear an area
+     containing the cookie.  See the discussion above.
+
+`xt'
+     Flag whose presence means that the cursor cannot be positioned
+     right in front of a magic cookie, and that `se' is a command to
+     delete the next magic cookie following the cursor.  See discussion
+     above.
+
+`mb'
+     String of commands to enter blinking mode.
+
+`md'
+     String of commands to enter double-bright mode.
+
+`mh'
+     String of commands to enter half-bright mode.
+
+`mk'
+     String of commands to enter invisible mode.
+
+`mp'
+     String of commands to enter protected mode.
+
+`mr'
+     String of commands to enter reverse-video mode.
+
+`me'
+     String of commands to turn off all appearance modes, including
+     standout mode and underline mode.  On some terminals it also turns
+     off alternate character set mode; on others, it may not.  This
+     capability must be present if any of `mb' ... `mr' is present.
+
+`as'
+     String of commands to turn on alternate character set mode.  This
+     mode assigns some or all graphic characters an alternate picture
+     on the screen.  There is no standard as to what the alternate
+     pictures look like.
+
+`ae'
+     String of commands to turn off alternate character set mode.
+
+`sa'
+     String of commands to turn on an arbitrary combination of
+     appearance modes.  It accepts 9 parameters, each of which controls
+     a particular kind of appearance mode.  A parameter should be 1 to
+     turn its appearance mode on, or zero to turn that mode off.  Most
+     terminals do not support the `sa' capability, even among those
+     that do have various appearance modes.
+
+     The nine parameters are, in order, STANDOUT, UNDERLINE, REVERSE,
+     BLINK, HALF-BRIGHT, DOUBLE-BRIGHT, BLANK, PROTECT, ALT CHAR SET.
+
+\1f
+File: termcap.info,  Node: Underlining,  Next: Cursor Visibility,  Prev: Standout,  Up: Capabilities
+
+Underlining
+===========
+
+Underlining on most terminals is a kind of appearance mode, much like
+standout mode.  Therefore, it may be implemented using magic cookies or
+as a flag in the terminal whose current state affects each character
+that is output.  *Note Standout::, for a full explanation.
+
+   The `ug' capability is a numeric capability whose presence indicates
+that the terminal uses magic cookies for underlining.  Its value is the
+number of character positions that a magic cookie for underlining
+occupies; it is used for underlining just as `sg' is used for standout.
+Aside from the simplest applications, it is impossible to use
+underlining correctly without paying attention to the value of `ug'.
+
+`us'
+     String of commands to turn on underline mode or to output a magic
+     cookie to start underlining.
+
+`ue'
+     String of commands to turn off underline mode or to output a magic
+     cookie to stop underlining.
+
+`ug'
+     Width of magic cookie that represents a change of underline mode;
+     or missing, if the terminal does not use a magic cookie for this.
+
+`ms'
+     Flag whose presence means that it is safe to move the cursor while
+     the appearance modes are not in the normal state.  Underlining is
+     an appearance mode.  If this flag is absent, programs should
+     always turn off underlining before moving the cursor.
+
+   There are two other, older ways of doing underlining: there can be a
+command to underline a single character, or the output of `_', the
+ASCII underscore character, as an overstrike could cause a character to
+be underlined.  New programs need not bother to handle these
+capabilities unless the author cares strongly about the obscure
+terminals which support them.  However, terminal descriptions should
+provide these capabilities when appropriate.
+
+`uc'
+     String of commands to underline the character under the cursor, and
+     move the cursor right.
+
+`ul'
+     Flag whose presence means that the terminal can underline by
+     overstriking an underscore character (`_'); some terminals can do
+     this even though they do not support overstriking in general.  An
+     implication of this flag is that when outputting new text to
+     overwrite old text, underscore characters must be treated
+     specially lest they underline the old text instead.
+
+\1f
+File: termcap.info,  Node: Cursor Visibility,  Next: Bell,  Prev: Underlining,  Up: Capabilities
+
+Cursor Visibility
+=================
+
+Some terminals have the ability to make the cursor invisible, or to
+enhance it.  Enhancing the cursor is often done by programs that plan
+to use the cursor to indicate to the user a position of interest that
+may be anywhere on the screen--for example, the Emacs editor enhances
+the cursor on entry.  Such programs should always restore the cursor to
+normal on exit.
+
+`vs'
+     String of commands to enhance the cursor.
+
+`vi'
+     String of commands to make the cursor invisible.
+
+`ve'
+     String of commands to return the cursor to normal.
+
+   If you define either `vs' or `vi', you must also define `ve'.
+
+\1f
+File: termcap.info,  Node: Bell,  Next: Keypad,  Prev: Cursor Visibility,  Up: Capabilities
+
+Bell
+====
+
+Here we describe commands to make the terminal ask for the user to pay
+attention to it.
+
+`bl'
+     String of commands to cause the terminal to make an audible sound.
+     If this capability is absent, the terminal has no way to make a
+     suitable sound.
+
+`vb'
+     String of commands to cause the screen to flash to attract
+     attention ("visible bell").  If this capability is absent, the
+     terminal has no way to do such a thing.
+
+\1f
+File: termcap.info,  Node: Keypad,  Next: Meta Key,  Prev: Bell,  Up: Capabilities
+
+Keypad and Function Keys
+========================
+
+Many terminals have arrow and function keys that transmit specific
+character sequences to the computer.  Since the precise sequences used
+depend on the terminal, termcap defines capabilities used to say what
+the sequences are.  Unlike most termcap string-valued capabilities,
+these are not strings of commands to be sent to the terminal, rather
+strings that are received from the terminal.
+
+   Programs that expect to use keypad keys should check, initially, for
+a `ks' capability and send it, to make the keypad actually transmit.
+Such programs should also send the `ke' string when exiting.
+
+`ks'
+     String of commands to make the function keys transmit.  If this
+     capability is not provided, but the others in this section are,
+     programs may assume that the function keys always transmit.
+
+`ke'
+     String of commands to make the function keys work locally.  This
+     capability is provided only if `ks' is.
+
+`kl'
+     String of input characters sent by typing the left-arrow key.  If
+     this capability is missing, you cannot expect the terminal to have
+     a left-arrow key that transmits anything to the computer.
+
+`kr'
+     String of input characters sent by typing the right-arrow key.
+
+`ku'
+     String of input characters sent by typing the up-arrow key.
+
+`kd'
+     String of input characters sent by typing the down-arrow key.
+
+`kh'
+     String of input characters sent by typing the "home-position" key.
+
+`K1' ... `K5'
+     Strings of input characters sent by the five other keys in a 3-by-3
+     array that includes the arrow keys, if the keyboard has such a
+     3-by-3 array.  Note that one of these keys may be the
+     "home-position" key, in which case one of these capabilities will
+     have the same value as the `kh' key.
+
+`k0'
+     String of input characters sent by function key 10 (or 0, if the
+     terminal has one labeled 0).
+
+`k1' ... `k9'
+     Strings of input characters sent by function keys 1 through 9,
+     provided for those function keys that exist.
+
+`kn'
+     Number: the number of numbered function keys, if there are more
+     than 10.
+
+`l0' ... `l9'
+     Strings which are the labels appearing on the keyboard on the keys
+     described by the capabilities `k0' ... `l9'.  These capabilities
+     should be left undefined if the labels are `f0' or `f10' and `f1'
+     ... `f9'.
+
+`kH'
+     String of input characters sent by the "home down" key, if there is
+     one.
+
+`kb'
+     String of input characters sent by the "backspace" key, if there is
+     one.
+
+`ka'
+     String of input characters sent by the "clear all tabs" key, if
+     there is one.
+
+`kt'
+     String of input characters sent by the "clear tab stop this column"
+     key, if there is one.
+
+`kC'
+     String of input characters sent by the "clear screen" key, if
+     there is one.
+
+`kD'
+     String of input characters sent by the "delete character" key, if
+     there is one.
+
+`kL'
+     String of input characters sent by the "delete line" key, if there
+     is one.
+
+`kM'
+     String of input characters sent by the "exit insert mode" key, if
+     there is one.
+
+`kE'
+     String of input characters sent by the "clear to end of line" key,
+     if there is one.
+
+`kS'
+     String of input characters sent by the "clear to end of screen"
+     key, if there is one.
+
+`kI'
+     String of input characters sent by the "insert character" or "enter
+     insert mode" key, if there is one.
+
+`kA'
+     String of input characters sent by the "insert line" key, if there
+     is one.
+
+`kN'
+     String of input characters sent by the "next page" key, if there is
+     one.
+
+`kP'
+     String of input characters sent by the "previous page" key, if
+     there is one.
+
+`kF'
+     String of input characters sent by the "scroll forward" key, if
+     there is one.
+
+`kR'
+     String of input characters sent by the "scroll reverse" key, if
+     there is one.
+
+`kT'
+     String of input characters sent by the "set tab stop in this
+     column" key, if there is one.
+
+`ko'
+     String listing the other function keys the terminal has.  This is a
+     very obsolete way of describing the same information found in the
+     `kH' ... `kT' keys.  The string contains a list of two-character
+     termcap capability names, separated by commas.  The meaning is
+     that for each capability name listed, the terminal has a key which
+     sends the string which is the value of that capability.  For
+     example, the value `:ko=cl,ll,sf,sr:' says that the terminal has
+     four function keys which mean "clear screen", "home down", "scroll
+     forward" and "scroll reverse".
+
+\1f
+File: termcap.info,  Node: Meta Key,  Next: Initialization,  Prev: Keypad,  Up: Capabilities
+
+Meta Key
+========
+
+A Meta key is a key on the keyboard that modifies each character you
+type by controlling the 0200 bit.  This bit is on if and only if the
+Meta key is held down when the character is typed.  Characters typed
+using the Meta key are called Meta characters.  Emacs uses Meta
+characters as editing commands.
+
+`km'
+     Flag whose presence means that the terminal has a Meta key.
+
+`mm'
+     String of commands to enable the functioning of the Meta key.
+
+`mo'
+     String of commands to disable the functioning of the Meta key.
+
+   If the terminal has `km' but does not have `mm' and `mo', it means
+that the Meta key always functions.  If it has `mm' and `mo', it means
+that the Meta key can be turned on or off.  Send the `mm' string to
+turn it on, and the `mo' string to turn it off.  I do not know why one
+would ever not want it to be on.
+
+\1f
+File: termcap.info,  Node: Initialization,  Next: Pad Specs,  Prev: Meta Key,  Up: Capabilities
+
+Initialization
+==============
+
+`ti'
+     String of commands to put the terminal into whatever special modes
+     are needed or appropriate for programs that move the cursor
+     nonsequentially around the screen.  Programs that use termcap to do
+     full-screen display should output this string when they start up.
+
+`te'
+     String of commands to undo what is done by the `ti' string.
+     Programs that output the `ti' string on entry should output this
+     string when they exit.
+
+`is'
+     String of commands to initialize the terminal for each login
+     session.
+
+`if'
+     String which is the name of a file containing the string of
+     commands to initialize the terminal for each session of use.
+     Normally `is' and `if' are not both used.
+
+`i1'
+`i3'
+     Two more strings of commands to initialize the terminal for each
+     login session.  The `i1' string (if defined) is output before `is'
+     or `if', and the `i3' string (if defined) is output after.
+
+     The reason for having three separate initialization strings is to
+     make it easier to define a group of related terminal types with
+     slightly different initializations.  Define two or three of the
+     strings in the basic type; then the other types can override one
+     or two of the strings.
+
+`rs'
+     String of commands to reset the terminal from any strange mode it
+     may be in.  Normally this includes the `is' string (or other
+     commands with the same effects) and more.  What would go in the
+     `rs' string but not in the `is' string are annoying or slow
+     commands to bring the terminal back from strange modes that nobody
+     would normally use.
+
+`it'
+     Numeric value, the initial spacing between hardware tab stop
+     columns when the terminal is powered up.  Programs to initialize
+     the terminal can use this to decide whether there is a need to set
+     the tab stops.  If the initial width is 8, well and good; if it is
+     not 8, then the tab stops should be set; if they cannot be set,
+     the kernel is told to convert tabs to spaces, and other programs
+     will observe this and do likewise.
+
+`ct'
+     String of commands to clear all tab stops.
+
+`st'
+     String of commands to set tab stop at current cursor column on all
+     lines.
+
+\1f
+File: termcap.info,  Node: Pad Specs,  Next: Status Line,  Prev: Initialization,  Up: Capabilities
+
+Padding Capabilities
+====================
+
+There are two terminal capabilities that exist just to explain the
+proper way to obey the padding specifications in all the command string
+capabilities.  One, `pc', must be obeyed by all termcap-using programs.
+
+`pb'
+     Numeric value, the lowest baud rate at which padding is actually
+     needed.  Programs may check this and refrain from doing any
+     padding at lower speeds.
+
+`pc'
+     String of commands for padding.  The first character of this
+     string is to be used as the pad character, instead of using null
+     characters for padding.  If `pc' is not provided, use null
+     characters.  Every program that uses termcap must look up this
+     capability and use it to set the variable `PC' that is used by
+     `tputs'.  *Note Padding::.
+
+   Some termcap capabilities exist just to specify the amount of
+padding that the kernel should give to cursor motion commands used in
+ordinary sequential output.
+
+`dC'
+     Numeric value, the number of msec of padding needed for the
+     carriage-return character.
+
+`dN'
+     Numeric value, the number of msec of padding needed for the newline
+     (linefeed) character.
+
+`dB'
+     Numeric value, the number of msec of padding needed for the
+     backspace character.
+
+`dF'
+     Numeric value, the number of msec of padding needed for the
+     formfeed character.
+
+`dT'
+     Numeric value, the number of msec of padding needed for the tab
+     character.
+
+   In some systems, the kernel uses the above capabilities; in other
+systems, the kernel uses the paddings specified in the string
+capabilities `cr', `sf', `le', `ff' and `ta'.  Descriptions of
+terminals which require such padding should contain the `dC' ...  `dT'
+capabilities and also specify the appropriate padding in the
+corresponding string capabilities.  Since no modern terminals require
+padding for ordinary sequential output, you probably won't need to do
+either of these things.
+
+\1f
+File: termcap.info,  Node: Status Line,  Next: Half-Line,  Prev: Pad Specs,  Up: Capabilities
+
+Status Line
+===========
+
+A "status line" is a line on the terminal that is not used for ordinary
+display output but instead used for a special message.  The intended
+use is for a continuously updated description of what the user's
+program is doing, and that is where the name "status line" comes from,
+but in fact it could be used for anything.  The distinguishing
+characteristic of a status line is that ordinary output to the terminal
+does not affect it; it changes only if the special status line commands
+of this section are used.
+
+`hs'
+     Flag whose presence means that the terminal has a status line.  If
+     a terminal description specifies that there is a status line, it
+     must provide the `ts' and `fs' capabilities.
+
+`ts'
+     String of commands to move the terminal cursor into the status
+     line.  Usually these commands must specifically record the old
+     cursor position for the sake of the `fs' string.
+
+`fs'
+     String of commands to move the cursor back from the status line to
+     its previous position (outside the status line).
+
+`es'
+     Flag whose presence means that other display commands work while
+     writing the status line.  In other words, one can clear parts of
+     it, insert or delete characters, move the cursor within it using
+     `ch' if there is a `ch' capability, enter and leave standout mode,
+     and so on.
+
+`ds'
+     String of commands to disable the display of the status line.  This
+     may be absent, if there is no way to disable the status line
+     display.
+
+`ws'
+     Numeric value, the width of the status line.  If this capability is
+     absent in a terminal that has a status line, it means the status
+     line is the same width as the other lines.
+
+     Note that the value of `ws' is sometimes as small as 8.
+
+\1f
+File: termcap.info,  Node: Half-Line,  Next: Printer,  Prev: Status Line,  Up: Capabilities
+
+Half-Line Motion
+================
+
+Some terminals have commands for moving the cursor vertically by
+half-lines, useful for outputting subscripts and superscripts.  Mostly
+it is hardcopy terminals that have such features.
+
+`hu'
+     String of commands to move the cursor up half a line.  If the
+     terminal is a display, it is your responsibility to avoid moving
+     up past the top line; however, most likely the terminal that
+     supports this is a hardcopy terminal and there is nothing to be
+     concerned about.
+
+`hd'
+     String of commands to move the cursor down half a line.  If the
+     terminal is a display, it is your responsibility to avoid moving
+     down past the bottom line, etc.
+
+\1f
+File: termcap.info,  Node: Printer,  Prev: Half-Line,  Up: Capabilities
+
+Controlling Printers Attached to Terminals
+==========================================
+
+Some terminals have attached hardcopy printer ports.  They may be able
+to copy the screen contents to the printer; they may also be able to
+redirect output to the printer.  Termcap does not have anything to tell
+the program whether the redirected output appears also on the screen;
+it does on some terminals but not all.
+
+`ps'
+     String of commands to cause the contents of the screen to be
+     printed.  If it is absent, the screen contents cannot be printed.
+
+`po'
+     String of commands to redirect further output to the printer.
+
+`pf'
+     String of commands to terminate redirection of output to the
+     printer.  This capability must be present in the description if
+     `po' is.
+
+`pO'
+     String of commands to redirect output to the printer for next N
+     characters of output, regardless of what they are.  Redirection
+     will end automatically after N characters of further output.  Until
+     then, nothing that is output can end redirection, not even the
+     `pf' string if there is one.  The number N should not be more than
+     255.
+
+     One use of this capability is to send non-text byte sequences
+     (such as bit-maps) to the printer.
+
+   Most terminals with printers do not support all of `ps', `po' and
+`pO'; any one or two of them may be supported.  To make a program that
+can send output to all kinds of printers, it is necessary to check for
+all three of these capabilities, choose the most convenient of the ones
+that are provided, and use it in its own appropriate fashion.
+
+\1f
+File: termcap.info,  Node: Summary,  Next: Var Index,  Prev: Capabilities,  Up: Top
+
+Summary of Capability Names
+***************************
+
+Here are all the terminal capability names in alphabetical order with a
+brief description of each.  For cross references to their definitions,
+see the index of capability names (*note Cap Index::).
+
+`ae'
+     String to turn off alternate character set mode.
+
+`al'
+     String to insert a blank line before the cursor.
+
+`AL'
+     String to insert N blank lines before the cursor.
+
+`am'
+     Flag: output to last column wraps cursor to next line.
+
+`as'
+     String to turn on alternate character set mode.like.
+
+`bc'
+     Very obsolete alternative name for the `le' capability.
+
+`bl'
+     String to sound the bell.
+
+`bs'
+     Obsolete flag: ASCII backspace may be used for leftward motion.
+
+`bt'
+     String to move the cursor left to the previous hardware tab stop
+     column.
+
+`bw'
+     Flag: `le' at left margin wraps to end of previous line.
+
+`CC'
+     String to change terminal's command character.
+
+`cd'
+     String to clear the line the cursor is on, and following lines.
+
+`ce'
+     String to clear from the cursor to the end of the line.
+
+`ch'
+     String to position the cursor at column C in the same line.
+
+`cl'
+     String to clear the entire screen and put cursor at upper left
+     corner.
+
+`cm'
+     String to position the cursor at line L, column C.
+
+`CM'
+     String to position the cursor at line L, column C, relative to
+     display memory.
+
+`co'
+     Number: width of the screen.
+
+`cr'
+     String to move cursor sideways to left margin.
+
+`cs'
+     String to set the scroll region.
+
+`cS'
+     Alternate form of string to set the scroll region.
+
+`ct'
+     String to clear all tab stops.
+
+`cv'
+     String to position the cursor at line L in the same column.
+
+`da'
+     Flag: data scrolled off top of screen may be scrolled back.
+
+`db'
+     Flag: data scrolled off bottom of screen may be scrolled back.
+
+`dB'
+     Obsolete number: msec of padding needed for the backspace
+     character.
+
+`dc'
+     String to delete one character position at the cursor.
+
+`dC'
+     Obsolete number: msec of padding needed for the carriage-return
+     character.
+
+`DC'
+     String to delete N characters starting at the cursor.
+
+`dF'
+     Obsolete number: msec of padding needed for the formfeed character.
+
+`dl'
+     String to delete the line the cursor is on.
+
+`DL'
+     String to delete N lines starting with the cursor's line.
+
+`dm'
+     String to enter delete mode.
+
+`dN'
+     Obsolete number: msec of padding needed for the newline character.
+
+`do'
+     String to move the cursor vertically down one line.
+
+`DO'
+     String to move cursor vertically down N lines.
+
+`ds'
+     String to disable the display of the status line.
+
+`dT'
+     Obsolete number: msec of padding needed for the tab character.
+
+`ec'
+     String of commands to clear N characters at cursor.
+
+`ed'
+     String to exit delete mode.
+
+`ei'
+     String to leave insert mode.
+
+`eo'
+     Flag: output of a space can erase an overstrike.
+
+`es'
+     Flag: other display commands work while writing the status line.
+
+`ff'
+     String to advance to the next page, for a hardcopy terminal.
+
+`fs'
+     String to move the cursor back from the status line to its
+     previous position (outside the status line).
+
+`gn'
+     Flag: this terminal type is generic, not real.
+
+`hc'
+     Flag: hardcopy terminal.
+
+`hd'
+     String to move the cursor down half a line.
+
+`ho'
+     String to position cursor at upper left corner.
+
+`hs'
+     Flag: the terminal has a status line.
+
+`hu'
+     String to move the cursor up half a line.
+
+`hz'
+     Flag: terminal cannot accept `~' as output.
+
+`i1'
+     String to initialize the terminal for each login session.
+
+`i3'
+     String to initialize the terminal for each login session.
+
+`ic'
+     String to insert one character position at the cursor.
+
+`IC'
+     String to insert N character positions at the cursor.
+
+`if'
+     String naming a file of commands to initialize the terminal.
+
+`im'
+     String to enter insert mode.
+
+`in'
+     Flag: outputting a space is different from moving over empty
+     positions.
+
+`ip'
+     String to output following an inserted character in insert mode.
+
+`is'
+     String to initialize the terminal for each login session.
+
+`it'
+     Number: initial spacing between hardware tab stop columns.
+
+`k0'
+     String of input sent by function key 0 or 10.
+
+`k1 ... k9'
+     Strings of input sent by function keys 1 through 9.
+
+`K1 ... K5'
+     Strings sent by the five other keys in 3-by-3 array with arrows.
+
+`ka'
+     String of input sent by the "clear all tabs" key.
+
+`kA'
+     String of input sent by the "insert line" key.
+
+`kb'
+     String of input sent by the "backspace" key.
+
+`kC'
+     String of input sent by the "clear screen" key.
+
+`kd'
+     String of input sent by typing the down-arrow key.
+
+`kD'
+     String of input sent by the "delete character" key.
+
+`ke'
+     String to make the function keys work locally.
+
+`kE'
+     String of input sent by the "clear to end of line" key.
+
+`kF'
+     String of input sent by the "scroll forward" key.
+
+`kh'
+     String of input sent by typing the "home-position" key.
+
+`kH'
+     String of input sent by the "home down" key.
+
+`kI'
+     String of input sent by the "insert character" or "enter insert
+     mode" key.
+
+`kl'
+     String of input sent by typing the left-arrow key.
+
+`kL'
+     String of input sent by the "delete line" key.
+
+`km'
+     Flag: the terminal has a Meta key.
+
+`kM'
+     String of input sent by the "exit insert mode" key.
+
+`kn'
+     Numeric value, the number of numbered function keys.
+
+`kN'
+     String of input sent by the "next page" key.
+
+`ko'
+     Very obsolete string listing the terminal's named function keys.
+
+`kP'
+     String of input sent by the "previous page" key.
+
+`kr'
+     String of input sent by typing the right-arrow key.
+
+`kR'
+     String of input sent by the "scroll reverse" key.
+
+`ks'
+     String to make the function keys transmit.
+
+`kS'
+     String of input sent by the "clear to end of screen" key.
+
+`kt'
+     String of input sent by the "clear tab stop this column" key.
+
+`kT'
+     String of input sent by the "set tab stop in this column" key.
+
+`ku'
+     String of input sent by typing the up-arrow key.
+
+`l0'
+     String on keyboard labelling function key 0 or 10.
+
+`l1 ... l9'
+     Strings on keyboard labelling function keys 1 through 9.
+
+`le'
+     String to move the cursor left one column.
+
+`LE'
+     String to move cursor left N columns.
+
+`li'
+     Number: height of the screen.
+
+`ll'
+     String to position cursor at lower left corner.
+
+`lm'
+     Number: lines of display memory.
+
+`mb'
+     String to enter blinking mode.
+
+`md'
+     String to enter double-bright mode.
+
+`me'
+     String to turn off all appearance modes
+
+`mh'
+     String to enter half-bright mode.
+
+`mi'
+     Flag: cursor motion in insert mode is safe.
+
+`mk'
+     String to enter invisible mode.
+
+`mm'
+     String to enable the functioning of the Meta key.
+
+`mo'
+     String to disable the functioning of the Meta key.
+
+`mp'
+     String to enter protected mode.
+
+`mr'
+     String to enter reverse-video mode.
+
+`ms'
+     Flag: cursor motion in standout mode is safe.
+
+`nc'
+     Obsolete flag: do not use ASCII carriage-return on this terminal.
+
+`nd'
+     String to move the cursor right one column.
+
+`nl'
+     Obsolete alternative name for the `do' and `sf' capabilities.
+
+`ns'
+     Flag: the terminal does not normally scroll for sequential output.
+
+`nw'
+     String to move to start of next line, possibly clearing rest of
+     old line.
+
+`os'
+     Flag: terminal can overstrike.
+
+`pb'
+     Number: the lowest baud rate at which padding is actually needed.
+
+`pc'
+     String containing character for padding.
+
+`pf'
+     String to terminate redirection of output to the printer.
+
+`po'
+     String to redirect further output to the printer.
+
+`pO'
+     String to redirect N characters ofoutput to the printer.
+
+`ps'
+     String to print the screen on the attached printer.
+
+`rc'
+     String to move to last saved cursor position.
+
+`RI'
+     String to move cursor right N columns.
+
+`rp'
+     String to output character C repeated N times.
+
+`rs'
+     String to reset the terminal from any strange modes.
+
+`sa'
+     String to turn on an arbitrary combination of appearance modes.
+
+`sc'
+     String to save the current cursor position.
+
+`se'
+     String to leave standout mode.
+
+`sf'
+     String to scroll the screen one line up.
+
+`SF'
+     String to scroll the screen N lines up.
+
+`sg'
+     Number: width of magic standout cookie.  Absent if magic cookies
+     are not used.
+
+`so'
+     String to enter standout mode.
+
+`sr'
+     String to scroll the screen one line down.
+
+`SR'
+     String to scroll the screen N line down.
+
+`st'
+     String to set tab stop at current cursor column on all lines.
+     programs.
+
+`ta'
+     String to move the cursor right to the next hardware tab stop
+     column.
+
+`te'
+     String to return terminal to settings for sequential output.
+
+`ti'
+     String to initialize terminal for random cursor motion.
+
+`ts'
+     String to move the terminal cursor into the status line.
+
+`uc'
+     String to underline one character and move cursor right.
+
+`ue'
+     String to turn off underline mode
+
+`ug'
+     Number: width of underlining magic cookie.  Absent if underlining
+     doesn't use magic cookies.
+
+`ul'
+     Flag: underline by overstriking with an underscore.
+
+`up'
+     String to move the cursor vertically up one line.
+
+`UP'
+     String to move cursor vertically up N lines.
+
+`us'
+     String to turn on underline mode
+
+`vb'
+     String to make the screen flash.
+
+`ve'
+     String to return the cursor to normal.
+
+`vi'
+     String to make the cursor invisible.
+
+`vs'
+     String to enhance the cursor.
+
+`wi'
+     String to set the terminal output screen window.
+
+`ws'
+     Number: the width of the status line.
+
+`xb'
+     Flag: superbee terminal.
+
+`xn'
+     Flag: cursor wraps in a strange way.
+
+`xs'
+     Flag: clearing a line is the only way to clear the appearance
+     modes of positions in that line (or, only way to remove magic
+     cookies on that line).
+
+`xt'
+     Flag: Teleray 1061; several strange characteristics.
+
+\1f
+File: termcap.info,  Node: Var Index,  Next: Cap Index,  Prev: Summary,  Up: Top
+
+Variable and Function Index
+***************************
+
+* Menu:
+
+* BC:                                    tgoto.
+* ospeed:                                Output Padding.
+* PC:                                    Output Padding.
+* tgetent:                               Find.
+* tgetflag:                              Interrogate.
+* tgetnum:                               Interrogate.
+* tgetstr:                               Interrogate.
+* tgoto:                                 tgoto.
+* tparam:                                tparam.
+* tputs:                                 Output Padding.
+* UP:                                    tgoto.
+
+\1f
+File: termcap.info,  Node: Cap Index,  Next: Index,  Prev: Var Index,  Up: Top
+
+Capability Index
+****************
+
+* Menu:
+
+* ae:                                    Standout.
+* AL:                                    Insdel Line.
+* al:                                    Insdel Line.
+* am:                                    Wrapping.
+* as:                                    Standout.
+* bc:                                    Cursor Motion.
+* bl:                                    Bell.
+* bs:                                    Cursor Motion.
+* bt:                                    Cursor Motion.
+* bw:                                    Cursor Motion.
+* CC:                                    Basic.
+* cd:                                    Clearing.
+* ce:                                    Clearing.
+* ch:                                    Cursor Motion.
+* cl:                                    Clearing.
+* CM:                                    Cursor Motion.
+* cm:                                    Cursor Motion.
+* co:                                    Screen Size.
+* cr:                                    Cursor Motion.
+* cS:                                    Scrolling.
+* cs:                                    Scrolling.
+* ct:                                    Initialization.
+* cv:                                    Cursor Motion.
+* da:                                    Scrolling.
+* dB:                                    Pad Specs.
+* db:                                    Scrolling.
+* dC:                                    Pad Specs.
+* DC:                                    Insdel Char.
+* dc:                                    Insdel Char.
+* dF:                                    Pad Specs.
+* DL:                                    Insdel Line.
+* dl:                                    Insdel Line.
+* dm:                                    Insdel Char.
+* dN:                                    Pad Specs.
+* DO:                                    Cursor Motion.
+* do:                                    Cursor Motion.
+* ds:                                    Status Line.
+* dT:                                    Pad Specs.
+* ec:                                    Clearing.
+* ed:                                    Insdel Char.
+* ei:                                    Insdel Char.
+* eo:                                    Basic.
+* es:                                    Status Line.
+* ff:                                    Cursor Motion.
+* fs:                                    Status Line.
+* gn:                                    Basic.
+* hc:                                    Basic.
+* hd:                                    Half-Line.
+* ho:                                    Cursor Motion.
+* hs:                                    Status Line.
+* hu:                                    Half-Line.
+* hz:                                    Basic.
+* i1:                                    Initialization.
+* i3:                                    Initialization.
+* IC:                                    Insdel Char.
+* ic:                                    Insdel Char.
+* if:                                    Initialization.
+* im:                                    Insdel Char.
+* in:                                    Insdel Char.
+* ip:                                    Insdel Char.
+* is:                                    Initialization.
+* it:                                    Initialization.
+* K1...K5:                               Keypad.
+* k1...k9:                               Keypad.
+* kA...kT:                               Keypad.
+* ka...ku:                               Keypad.
+* km:                                    Meta Key.
+* l0...l9:                               Keypad.
+* LE:                                    Cursor Motion.
+* le:                                    Cursor Motion.
+* li:                                    Screen Size.
+* ll:                                    Cursor Motion.
+* lm:                                    Scrolling.
+* mb:                                    Standout.
+* md:                                    Standout.
+* me:                                    Standout.
+* mh:                                    Standout.
+* mi:                                    Insdel Char.
+* mk:                                    Standout.
+* mm:                                    Meta Key.
+* mo:                                    Meta Key.
+* mp:                                    Standout.
+* mr:                                    Standout.
+* ms <1>:                                Underlining.
+* ms:                                    Standout.
+* nc:                                    Cursor Motion.
+* nd:                                    Cursor Motion.
+* nl:                                    Cursor Motion.
+* ns:                                    Scrolling.
+* nw:                                    Cursor Motion.
+* os:                                    Basic.
+* pb:                                    Pad Specs.
+* pc:                                    Pad Specs.
+* pf:                                    Printer.
+* pO:                                    Printer.
+* po:                                    Printer.
+* ps:                                    Printer.
+* rc:                                    Cursor Motion.
+* RI:                                    Cursor Motion.
+* rp:                                    Basic.
+* rs:                                    Initialization.
+* sa:                                    Standout.
+* sc:                                    Cursor Motion.
+* se:                                    Standout.
+* SF:                                    Scrolling.
+* sf:                                    Scrolling.
+* sg:                                    Standout.
+* so:                                    Standout.
+* SR:                                    Scrolling.
+* sr:                                    Scrolling.
+* st:                                    Initialization.
+* ta:                                    Cursor Motion.
+* te:                                    Initialization.
+* ti:                                    Initialization.
+* ts:                                    Status Line.
+* uc:                                    Underlining.
+* ue:                                    Underlining.
+* ug:                                    Underlining.
+* ul:                                    Underlining.
+* UP:                                    Cursor Motion.
+* up:                                    Cursor Motion.
+* us:                                    Underlining.
+* vb:                                    Bell.
+* ve:                                    Cursor Visibility.
+* vi:                                    Cursor Visibility.
+* vs:                                    Cursor Visibility.
+* wi:                                    Windows.
+* ws:                                    Status Line.
+* xb:                                    Basic.
+* xn:                                    Wrapping.
+* xs:                                    Standout.
+* xt <1>:                                Standout.
+* xt:                                    Cursor Motion.
+
+\1f
+File: termcap.info,  Node: Index,  Prev: Cap Index,  Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* %:                                     Encode Parameters.
+* appearance modes:                      Standout.
+* bell:                                  Bell.
+* clearing the screen:                   Clearing.
+* command character:                     Basic.
+* cursor motion:                         Cursor Motion.
+* delete character:                      Insdel Char.
+* delete line:                           Insdel Line.
+* delete mode:                           Insdel Char.
+* description format:                    Format.
+* erasing:                               Clearing.
+* generic terminal type:                 Basic.
+* home position:                         Cursor Motion.
+* inheritance:                           Inheriting.
+* initialization:                        Initialization.
+* insert character:                      Insdel Char.
+* insert line:                           Insdel Line.
+* insert mode:                           Insdel Char.
+* line speed:                            Output Padding.
+* magic cookie:                          Standout.
+* meta key:                              Meta Key.
+* names of terminal types:               Naming.
+* overstrike:                            Basic.
+* padding <1>:                           Pad Specs.
+* padding:                               Padding.
+* parameters:                            Parameters.
+* printer:                               Printer.
+* repeat output:                         Basic.
+* reset:                                 Initialization.
+* screen size <1>:                       Screen Size.
+* screen size:                           Naming.
+* scrolling:                             Scrolling.
+* standout:                              Standout.
+* status line:                           Status Line.
+* Superbee:                              Basic.
+* tab stops:                             Initialization.
+* termcap:                               Introduction.
+* terminal flags (kernel):               Initialize.
+* underlining:                           Underlining.
+* visibility:                            Cursor Visibility.
+* visible bell:                          Bell.
+* window:                                Windows.
+* wrapping <1>:                          Wrapping.
+* wrapping:                              Naming.
+
+

 \1f
 Tag Table:
 \1f
 Tag Table:

-(Indirect)

 Node: Top\7f959
 Node: Introduction\7f1604
 Node: Top\7f959
 Node: Introduction\7f1604

-Node: Library\7f3331
-Node: Preparation\7f4348
-Node: Find\7f5547
-Node: Interrogate\7f9094
-Node: Initialize\7f14401
-Node: Padding\7f16039
-Node: Why Pad\7f16700
-Node: Describe Padding\7f18344
-Node: Output Padding\7f19819
-Node: Parameters\7f23432
-Node: Encode Parameters\7f25090
-Node: Using Parameters\7f31195
-Node: tparam\7f31784
-Node: tgoto\7f33849
-Node: Data Base\7f36404
-Node: Format\7f37281
-Node: Capability Format\7f39372
-Node: Naming\7f42422
-Node: Inheriting\7f46990
-Node: Capabilities\7f49216
-Node: Basic\7f52059
-Node: Screen Size\7f55903
-Node: Cursor Motion\7f57643
-Node: Wrapping\7f67293
-Node: Scrolling\7f70117
-Node: Windows\7f75137
-Node: Clearing\7f75871
-Node: Insdel Line\7f77635
-Node: Insdel Char\7f82541
-Node: Standout\7f92525
-Node: Underlining\7f101582
-Node: Cursor Visibility\7f104001
-Node: Bell\7f104749
-Node: Keypad\7f105298
-Node: Meta Key\7f110019
-Node: Initialization\7f110973
-Node: Pad Specs\7f113337
-Node: Status Line\7f115390
-Node: Half-Line\7f117274
-Node: Printer\7f118076
-Node: Summary\7f119755
-Node: Var Index\7f129960
-Node: Cap Index\7f130684
-Node: Index\7f137875
+Node: Library\7f3328
+Node: Preparation\7f4342
+Node: Find\7f5538
+Node: Interrogate\7f9082
+Node: Initialize\7f14386
+Node: Padding\7f16021
+Node: Why Pad\7f16679
+Node: Describe Padding\7f18320
+Node: Output Padding\7f19792
+Node: Parameters\7f23402
+Node: Encode Parameters\7f25057
+Node: Using Parameters\7f31159
+Node: tparam\7f31745
+Node: tgoto\7f33807
+Node: Data Base\7f36359
+Node: Format\7f37233
+Node: Capability Format\7f39322
+Node: Naming\7f42369
+Node: Inheriting\7f46933
+Node: Capabilities\7f49156
+Node: Basic\7f51996
+Node: Screen Size\7f55837
+Node: Cursor Motion\7f57574
+Node: Wrapping\7f67221
+Node: Scrolling\7f70042
+Node: Windows\7f75059
+Node: Clearing\7f75790
+Node: Insdel Line\7f77549
+Node: Insdel Char\7f82452
+Node: Standout\7f92433
+Node: Underlining\7f101487
+Node: Cursor Visibility\7f103903
+Node: Bell\7f104648
+Node: Keypad\7f105194
+Node: Meta Key\7f109912
+Node: Initialization\7f110863
+Node: Pad Specs\7f113227
+Node: Status Line\7f115277
+Node: Half-Line\7f117158
+Node: Printer\7f117957
+Node: Summary\7f119633
+Node: Var Index\7f129835
+Node: Cap Index\7f130559
+Node: Index\7f137750

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

diff --git a/info/texinfo.info b/info/texinfo.info
index 1f73e7f..d17adb9 100644 (file)
--- a/info/texinfo.info
+++ b/info/texinfo.info
@@ -1,4 +1,4 @@
-This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+This is ../info/texinfo.info, produced by makeinfo version 4.6 from

 texinfo.texi.
 
 INFO-DIR-SECTION Texinfo documentation system
 texinfo.texi.
 
 INFO-DIR-SECTION Texinfo documentation system

@@ -35,316 +35,306 @@ translation approved by the Free Software Foundation.
 \1f
 Indirect:
 texinfo.info-1: 1484
 \1f
 Indirect:
 texinfo.info-1: 1484

-texinfo.info-2: 48707
-texinfo.info-3: 96681
-texinfo.info-4: 146073
-texinfo.info-5: 196055
-texinfo.info-6: 245147
-texinfo.info-7: 293746
-texinfo.info-8: 343561
-texinfo.info-9: 392874
-texinfo.info-10: 435252
-texinfo.info-11: 481368
-texinfo.info-12: 519528
+texinfo.info-2: 300413

 \1f
 Tag Table:
 (Indirect)
 Node: Top\7f1484
 \1f
 Tag Table:
 (Indirect)
 Node: Top\7f1484

-Node: Copying\7f23799
-Node: Overview\7f25804
-Node: Overview-Footnotes\7f27233
-Ref: Overview-Footnote-1\7f27297
-Node: Using Texinfo\7f27769
-Node: Info Files\7f30256
-Node: Info Files-Footnotes\7f34292
-Ref: Info Files-Footnote-1\7f34360
-Node: Printed Books\7f34539
-Node: Printed Books-Footnotes\7f37211
-Ref: Printed Books-Footnote-1\7f37285
-Node: Formatting Commands\7f37495
-Node: Formatting Commands-Footnotes\7f40322
-Ref: Formatting Commands-Footnote-1\7f40408
-Node: Conventions\7f41024
-Node: Comments\7f43586
-Node: Minimum\7f45009
-Node: Six Parts\7f47195
-Node: Short Sample\7f48707
-Node: Acknowledgements\7f52843
-Node: Texinfo Mode\7f53678
-Node: Texinfo Mode Overview\7f55050
-Node: Emacs Editing\7f55826
-Node: Inserting\7f57956
-Node: Showing the Structure\7f62237
-Node: Updating Nodes and Menus\7f64764
-Node: Updating Commands\7f65837
-Node: Updating Requirements\7f71898
-Node: Other Updating Commands\7f74195
-Node: Info Formatting\7f77463
-Node: Printing\7f78721
-Node: Texinfo Mode Summary\7f81066
-Node: Beginning a File\7f85820
-Node: Four Parts\7f86711
-Node: Sample Beginning\7f88181
-Node: Header\7f89801
-Node: First Line\7f91153
-Node: Start of Header\7f92142
-Node: setfilename\7f92855
-Node: settitle\7f94791
-Node: setchapternewpage\7f96681
-Node: paragraphindent\7f99442
-Node: End of Header\7f100924
-Node: Info Summary and Permissions\7f101763
-Node: Titlepage & Copyright Page\7f102782
-Node: titlepage\7f104388
-Node: titlepage-Footnotes\7f106670
-Ref: titlepage-Footnote-1\7f106736
-Node: titlefont center sp\7f107010
-Node: title subtitle author\7f108236
-Node: Copyright & Permissions\7f110508
-Node: end titlepage\7f112509
-Node: headings on off\7f114215
-Node: The Top Node\7f116260
-Node: Title of Top Node\7f117415
-Node: Master Menu Parts\7f118668
-Node: Software Copying Permissions\7f120905
-Node: Ending a File\7f122073
-Node: Printing Indices & Menus\7f122921
-Node: Contents\7f125230
-Node: File End\7f127570
-Node: Structuring\7f128243
-Node: Tree Structuring\7f129900
-Node: Structuring Command Types\7f131343
-Node: makeinfo top\7f133670
-Node: chapter\7f134203
-Node: unnumbered & appendix\7f135227
-Node: majorheading & chapheading\7f136066
-Node: section\7f136887
-Node: unnumberedsec appendixsec heading\7f137651
-Node: subsection\7f138640
-Node: unnumberedsubsec appendixsubsec subheading\7f139212
-Node: subsubsection\7f140165
-Node: Raise/lower sections\7f141715
-Node: Nodes\7f143850
-Node: Two Paths\7f144787
-Node: Node Menu Illustration\7f146073
-Node: node\7f149768
-Node: Node Names\7f152464
-Node: Writing a Node\7f153540
-Node: Node Line Tips\7f155558
-Node: Node Line Requirements\7f156352
-Node: First Node\7f157953
-Node: makeinfo top command\7f159392
-Node: Top Node Summary\7f160571
-Node: makeinfo Pointer Creation\7f162021
-Node: Menus\7f163268
-Node: Menus-Footnotes\7f164207
-Ref: Menus-Footnote-1\7f164265
-Node: Menu Location\7f164558
-Node: Writing a Menu\7f166235
-Node: Menu Parts\7f167201
-Node: Less Cluttered Menu Entry\7f168359
-Node: Menu Example\7f168984
-Node: Other Info Files\7f170505
-Node: Cross References\7f172373
-Node: References\7f173330
-Node: Cross Reference Commands\7f175077
-Node: Cross Reference Parts\7f176136
-Node: xref\7f178972
-Node: Reference Syntax\7f179771
-Node: One Argument\7f181425
-Node: Two Arguments\7f182437
-Node: Three Arguments\7f183552
-Node: Four and Five Arguments\7f185943
-Node: Top Node Naming\7f188355
-Node: ref\7f189365
-Node: pxref\7f190757
-Node: inforef\7f193139
-Node: uref\7f194432
-Node: Marking Text\7f195431
-Node: Indicating\7f196055
-Node: Useful Highlighting\7f197960
-Node: code\7f199349
-Node: kbd\7f202387
-Node: key\7f204257
-Node: samp\7f205590
-Node: var\7f207177
-Node: file\7f208970
-Node: dfn\7f209577
-Node: cite\7f210487
-Node: url\7f210941
-Node: email\7f211505
-Node: Emphasis\7f212317
-Node: emph & strong\7f213217
-Node: Smallcaps\7f214203
-Node: Fonts\7f215530
-Node: Customized Highlighting\7f216618
-Node: Customized Highlighting-Footnotes\7f219433
-Ref: Customized Highlighting-Footnote-1\7f219527
-Node: Quotations and Examples\7f219653
-Node: Block Enclosing Commands\7f221275
-Node: quotation\7f223300
-Node: example\7f224390
-Node: noindent\7f226445
-Node: Lisp Example\7f227909
-Node: Lisp Example-Footnotes\7f228611
-Ref: Lisp Example-Footnote-1\7f228683
-Node: smallexample & smalllisp\7f228801
-Node: display\7f230826
-Node: format\7f231458
-Node: exdent\7f231919
-Node: flushleft & flushright\7f232999
-Node: cartouche\7f234265
-Node: Lists and Tables\7f235032
-Node: Introducing Lists\7f235708
-Node: itemize\7f237373
-Node: enumerate\7f239520
-Node: Two-column Tables\7f242025
-Node: table\7f242714
-Node: ftable vtable\7f245147
-Node: itemx\7f246248
-Node: Multi-column Tables\7f247259
-Node: Multitable Column Widths\7f247930
-Node: Multitable Rows\7f249384
-Node: Indices\7f251165
-Node: Index Entries\7f252315
-Node: Predefined Indices\7f253448
-Node: Indexing Commands\7f254445
-Node: Combining Indices\7f258985
-Node: syncodeindex\7f260348
-Node: synindex\7f262010
-Node: New Indices\7f262535
-Node: Insertions\7f264360
-Node: Braces Atsigns\7f265544
-Node: Inserting An Atsign\7f266096
-Node: Inserting Braces\7f266370
-Node: Inserting Space\7f266733
-Node: Not Ending a Sentence\7f267237
-Node: Ending a Sentence\7f268591
-Node: Multiple Spaces\7f269720
-Node: dmn\7f270939
-Node: Inserting Accents\7f272146
-Node: Dots Bullets\7f273903
-Node: dots\7f274725
-Node: bullet\7f275249
-Node: TeX and copyright\7f275646
-Node: tex\7f276213
-Node: copyright symbol\7f276629
-Node: pounds\7f276889
-Node: minus\7f277253
-Node: math\7f278175
-Node: Glyphs\7f278903
-Node: Glyphs Summary\7f280016
-Node: result\7f280644
-Node: expansion\7f281129
-Node: Print Glyph\7f282085
-Node: Error Glyph\7f282962
-Node: Equivalence\7f283795
-Node: Point Glyph\7f284483
-Node: Images\7f286040
-Node: Breaks\7f287707
-Node: Break Commands\7f289138
-Node: Line Breaks\7f289979
-Node: - and hyphenation\7f290997
-Node: w\7f292247
-Node: sp\7f292960
-Node: page\7f293369
-Node: group\7f293746
-Node: need\7f295489
-Node: Definition Commands\7f296219
-Node: Def Cmd Template\7f297790
-Node: Optional Arguments\7f300787
-Node: deffnx\7f302375
-Node: Def Cmds in Detail\7f303330
-Node: Functions Commands\7f304440
-Node: Variables Commands\7f307445
-Node: Typed Functions\7f309531
-Node: Typed Variables\7f313073
-Node: Abstract Objects\7f315056
-Node: Data Types\7f320281
-Node: Def Cmd Conventions\7f321536
-Node: Sample Function Definition\7f322099
-Node: Footnotes\7f324983
-Node: Footnotes-Footnotes\7f325371
-Ref: Footnotes-Footnote-1\7f325437
-Node: Footnote Commands\7f325717
-Node: Footnote Commands-Footnotes\7f327214
-Ref: Footnote Commands-Footnote-1\7f327296
-Node: Footnote Styles\7f327332
-Node: Conditionals\7f329918
-Node: Conditional Commands\7f330729
-Node: Conditional Not Commands\7f332222
-Node: Raw Formatter Commands\7f332967
-Node: set clear value\7f334797
-Node: ifset ifclear\7f335598
-Node: value\7f338777
-Node: value Example\7f340189
-Node: Macros\7f341767
-Node: Defining Macros\7f342472
-Node: Invoking Macros\7f343561
-Node: Format/Print Hardcopy\7f344667
-Node: Use TeX\7f346504
-Node: Format with tex/texindex\7f347132
-Node: Format with texi2dvi\7f350773
-Node: Print with lpr\7f351364
-Node: Within Emacs\7f352218
-Node: Texinfo Mode Printing\7f353137
-Node: Compile-Command\7f356547
-Node: Requirements Summary\7f357435
-Node: Preparing for TeX\7f358748
-Node: Overfull hboxes\7f361535
-Node: smallbook\7f363094
-Node: A4 Paper\7f364612
-Node: Cropmarks and Magnification\7f365837
-Node: Create an Info File\7f367778
-Node: makeinfo advantages\7f369081
-Node: Invoking makeinfo\7f369997
-Node: makeinfo options\7f370685
-Node: Pointer Validation\7f376169
-Node: makeinfo in Emacs\7f377513
-Node: texinfo-format commands\7f380071
-Node: Batch Formatting\7f381342
-Node: Tag and Split Files\7f382558
-Node: Install an Info File\7f385912
-Node: Directory file\7f386730
-Node: New Info File\7f388598
-Node: Other Info Directories\7f389659
-Node: Installing Dir Entries\7f392874
-Node: Invoking install-info\7f394867
-Node: Command List\7f397282
-Node: Tips\7f435252
-Node: Sample Texinfo File\7f446662
-Node: Sample Permissions\7f448781
-Node: Inserting Permissions\7f449824
-Node: ifinfo Permissions\7f452130
-Node: Titlepage Permissions\7f453751
-Node: Include Files\7f455013
-Node: Using Include Files\7f456100
-Node: texinfo-multiple-files-update\7f458055
-Node: Include File Requirements\7f460416
-Node: Sample Include File\7f461661
-Node: Include Files Evolution\7f463180
-Node: Headings\7f465151
-Node: Headings Introduced\7f465788
-Node: Heading Format\7f467676
-Node: Heading Choice\7f470128
-Node: Custom Headings\7f471500
-Node: Catching Mistakes\7f475828
-Node: makeinfo Preferred\7f477117
-Node: Debugging with Info\7f478022
-Node: Debugging with TeX\7f481368
-Node: Using texinfo-show-structure\7f485648
-Node: Using occur\7f488747
-Node: Running Info-Validate\7f490284
-Node: Using Info-validate\7f491345
-Node: Unsplit\7f493187
-Node: Tagifying\7f494233
-Node: Splitting\7f495085
-Node: Refilling Paragraphs\7f496701
-Node: Refilling Paragraphs-Footnotes\7f498355
-Ref: Refilling Paragraphs-Footnote-1\7f498443
-Node: Command Syntax\7f498606
-Node: Obtaining TeX\7f501563
-Node: Command and Variable Index\7f503676
-Node: Concept Index\7f519528
+Node: Copying\7f23797
+Node: Overview\7f25800
+Node: Overview-Footnotes\7f27227
+Ref: Overview-Footnote-1\7f27291
+Node: Using Texinfo\7f27763
+Node: Info Files\7f30250
+Node: Info Files-Footnotes\7f34284
+Ref: Info Files-Footnote-1\7f34352
+Node: Printed Books\7f34531
+Node: Printed Books-Footnotes\7f37200
+Ref: Printed Books-Footnote-1\7f37274
+Node: Formatting Commands\7f37484
+Node: Formatting Commands-Footnotes\7f40309
+Ref: Formatting Commands-Footnote-1\7f40395
+Node: Conventions\7f41011
+Node: Comments\7f43571
+Node: Minimum\7f44991
+Node: Six Parts\7f47175
+Node: Short Sample\7f48685
+Node: Acknowledgements\7f52817
+Node: Texinfo Mode\7f53650
+Node: Texinfo Mode Overview\7f55021
+Node: Emacs Editing\7f55797
+Node: Inserting\7f57925
+Node: Showing the Structure\7f62204
+Node: Updating Nodes and Menus\7f64729
+Node: Updating Commands\7f65800
+Node: Updating Requirements\7f71861
+Node: Other Updating Commands\7f74156
+Node: Info Formatting\7f77422
+Node: Printing\7f78678
+Node: Texinfo Mode Summary\7f81021
+Node: Beginning a File\7f85757
+Node: Four Parts\7f86646
+Node: Sample Beginning\7f88116
+Node: Header\7f89734
+Node: First Line\7f91084
+Node: Start of Header\7f92071
+Node: setfilename\7f92782
+Node: settitle\7f94716
+Node: setchapternewpage\7f96604
+Node: paragraphindent\7f99363
+Node: End of Header\7f100843
+Node: Info Summary and Permissions\7f101680
+Node: Titlepage & Copyright Page\7f102697
+Node: titlepage\7f104301
+Node: titlepage-Footnotes\7f106581
+Ref: titlepage-Footnote-1\7f106647
+Node: titlefont center sp\7f106921
+Node: title subtitle author\7f108145
+Node: Copyright & Permissions\7f110415
+Node: end titlepage\7f112414
+Node: headings on off\7f114118
+Node: The Top Node\7f116161
+Node: Title of Top Node\7f117314
+Node: Master Menu Parts\7f118567
+Node: Software Copying Permissions\7f120802
+Node: Ending a File\7f121968
+Node: Printing Indices & Menus\7f122814
+Node: Contents\7f125120
+Node: File End\7f127458
+Node: Structuring\7f128129
+Node: Tree Structuring\7f129784
+Node: Structuring Command Types\7f131225
+Node: makeinfo top\7f133550
+Node: chapter\7f134081
+Node: unnumbered & appendix\7f135103
+Node: majorheading & chapheading\7f135940
+Node: section\7f136759
+Node: unnumberedsec appendixsec heading\7f137521
+Node: subsection\7f138508
+Node: unnumberedsubsec appendixsubsec subheading\7f139078
+Node: subsubsection\7f140029
+Node: Raise/lower sections\7f141577
+Node: Nodes\7f143710
+Node: Two Paths\7f144645
+Node: Node Menu Illustration\7f145931
+Node: node\7f149624
+Node: Node Names\7f152318
+Node: Writing a Node\7f153394
+Node: Node Line Tips\7f155410
+Node: Node Line Requirements\7f156202
+Node: First Node\7f157801
+Node: makeinfo top command\7f159238
+Node: Top Node Summary\7f160415
+Node: makeinfo Pointer Creation\7f161863
+Node: Menus\7f163108
+Node: Menus-Footnotes\7f164045
+Ref: Menus-Footnote-1\7f164103
+Node: Menu Location\7f164396
+Node: Writing a Menu\7f166073
+Node: Menu Parts\7f167037
+Node: Less Cluttered Menu Entry\7f168193
+Node: Menu Example\7f168816
+Node: Other Info Files\7f170335
+Node: Cross References\7f172201
+Node: References\7f173156
+Node: Cross Reference Commands\7f174903
+Node: Cross Reference Parts\7f175960
+Node: xref\7f178794
+Node: Reference Syntax\7f179591
+Node: One Argument\7f181245
+Node: Two Arguments\7f182255
+Node: Three Arguments\7f183368
+Node: Four and Five Arguments\7f185757
+Node: Top Node Naming\7f188167
+Node: ref\7f189175
+Node: pxref\7f190565
+Node: inforef\7f192945
+Node: uref\7f194236
+Node: Marking Text\7f195233
+Node: Indicating\7f195855
+Node: Useful Highlighting\7f197758
+Node: code\7f199148
+Node: kbd\7f202184
+Node: key\7f204052
+Node: samp\7f205383
+Node: var\7f206968
+Node: file\7f208759
+Node: dfn\7f209364
+Node: cite\7f210272
+Node: url\7f210724
+Node: email\7f211286
+Node: Emphasis\7f212096
+Node: emph & strong\7f212994
+Node: Smallcaps\7f213978
+Node: Fonts\7f215301
+Node: Customized Highlighting\7f216387
+Node: Customized Highlighting-Footnotes\7f219200
+Ref: Customized Highlighting-Footnote-1\7f219294
+Node: Quotations and Examples\7f219420
+Node: Block Enclosing Commands\7f221040
+Node: quotation\7f223063
+Node: example\7f224151
+Node: noindent\7f226204
+Node: Lisp Example\7f227666
+Node: Lisp Example-Footnotes\7f228366
+Ref: Lisp Example-Footnote-1\7f228438
+Node: smallexample & smalllisp\7f228556
+Node: display\7f230579
+Node: format\7f231209
+Node: exdent\7f231668
+Node: flushleft & flushright\7f232746
+Node: cartouche\7f234010
+Node: Lists and Tables\7f234775
+Node: Introducing Lists\7f235449
+Node: itemize\7f237114
+Node: enumerate\7f239258
+Node: Two-column Tables\7f241757
+Node: table\7f242444
+Node: ftable vtable\7f244875
+Node: itemx\7f245974
+Node: Multi-column Tables\7f246983
+Node: Multitable Column Widths\7f247652
+Node: Multitable Rows\7f249104
+Node: Indices\7f250883
+Node: Index Entries\7f252031
+Node: Predefined Indices\7f253162
+Node: Indexing Commands\7f254157
+Node: Combining Indices\7f258695
+Node: syncodeindex\7f260056
+Node: synindex\7f261716
+Node: New Indices\7f262239
+Node: Insertions\7f264062
+Node: Braces Atsigns\7f265244
+Node: Inserting An Atsign\7f265794
+Node: Inserting Braces\7f266066
+Node: Inserting Space\7f266427
+Node: Not Ending a Sentence\7f266929
+Node: Ending a Sentence\7f268281
+Node: Multiple Spaces\7f269407
+Node: dmn\7f270624
+Node: Inserting Accents\7f271829
+Node: Dots Bullets\7f273584
+Node: dots\7f274404
+Node: bullet\7f274926
+Node: TeX and copyright\7f275321
+Node: tex\7f275886
+Node: copyright symbol\7f276301
+Node: pounds\7f276559
+Node: minus\7f276920
+Node: math\7f277840
+Node: Glyphs\7f278565
+Node: Glyphs Summary\7f279676
+Node: result\7f280302
+Node: expansion\7f280785
+Node: Print Glyph\7f281739
+Node: Error Glyph\7f282614
+Node: Equivalence\7f283445
+Node: Point Glyph\7f284131
+Node: Images\7f285686
+Node: Breaks\7f287351
+Node: Break Commands\7f288780
+Node: Line Breaks\7f289621
+Node: - and hyphenation\7f290637
+Node: w\7f291885
+Node: sp\7f292596
+Node: page\7f293003
+Node: group\7f293378
+Node: need\7f295120
+Node: Definition Commands\7f295848
+Node: Def Cmd Template\7f297417
+Node: Optional Arguments\7f300413
+Node: deffnx\7f301999
+Node: Def Cmds in Detail\7f302952
+Node: Functions Commands\7f304060
+Node: Variables Commands\7f307063
+Node: Typed Functions\7f309147
+Node: Typed Variables\7f312688
+Node: Abstract Objects\7f314669
+Node: Data Types\7f319893
+Node: Def Cmd Conventions\7f321146
+Node: Sample Function Definition\7f321707
+Node: Footnotes\7f324590
+Node: Footnotes-Footnotes\7f324976
+Ref: Footnotes-Footnote-1\7f325042
+Node: Footnote Commands\7f325322
+Node: Footnote Commands-Footnotes\7f326817
+Ref: Footnote Commands-Footnote-1\7f326899
+Node: Footnote Styles\7f326935
+Node: Conditionals\7f329519
+Node: Conditional Commands\7f330328
+Node: Conditional Not Commands\7f331821
+Node: Raw Formatter Commands\7f332564
+Node: set clear value\7f334392
+Node: ifset ifclear\7f335191
+Node: value\7f338369
+Node: value Example\7f339779
+Node: Macros\7f341355
+Node: Defining Macros\7f342058
+Node: Invoking Macros\7f343145
+Node: Format/Print Hardcopy\7f344249
+Node: Use TeX\7f346084
+Node: Format with tex/texindex\7f346712
+Node: Format with texi2dvi\7f350351
+Node: Print with lpr\7f350940
+Node: Within Emacs\7f351792
+Node: Texinfo Mode Printing\7f352709
+Node: Compile-Command\7f356117
+Node: Requirements Summary\7f357003
+Node: Preparing for TeX\7f358314
+Node: Overfull hboxes\7f361101
+Node: smallbook\7f362658
+Node: A4 Paper\7f364174
+Node: Cropmarks and Magnification\7f365397
+Node: Create an Info File\7f367336
+Node: makeinfo advantages\7f368637
+Node: Invoking makeinfo\7f369553
+Node: makeinfo options\7f370239
+Node: Pointer Validation\7f375722
+Node: makeinfo in Emacs\7f377064
+Node: texinfo-format commands\7f379620
+Node: Batch Formatting\7f380891
+Node: Tag and Split Files\7f382105
+Node: Install an Info File\7f385457
+Node: Directory file\7f386273
+Node: New Info File\7f388141
+Node: Other Info Directories\7f389200
+Node: Installing Dir Entries\7f392413
+Node: Invoking install-info\7f394405
+Node: Command List\7f396819
+Node: Tips\7f434787
+Node: Sample Texinfo File\7f446174
+Node: Sample Permissions\7f448291
+Node: Inserting Permissions\7f449332
+Node: ifinfo Permissions\7f451638
+Node: Titlepage Permissions\7f453257
+Node: Include Files\7f454517
+Node: Using Include Files\7f455602
+Node: texinfo-multiple-files-update\7f457555
+Node: Include File Requirements\7f459914
+Node: Sample Include File\7f461157
+Node: Include Files Evolution\7f462674
+Node: Headings\7f464643
+Node: Headings Introduced\7f465278
+Node: Heading Format\7f467166
+Node: Heading Choice\7f469616
+Node: Custom Headings\7f470986
+Node: Catching Mistakes\7f475312
+Node: makeinfo Preferred\7f476599
+Node: Debugging with Info\7f477504
+Node: Debugging with TeX\7f480848
+Node: Using texinfo-show-structure\7f485126
+Node: Using occur\7f488223
+Node: Running Info-Validate\7f489758
+Node: Using Info-validate\7f490817
+Node: Unsplit\7f492657
+Node: Tagifying\7f493701
+Node: Splitting\7f494551
+Node: Refilling Paragraphs\7f496165
+Node: Refilling Paragraphs-Footnotes\7f497817
+Ref: Refilling Paragraphs-Footnote-1\7f497905
+Node: Command Syntax\7f498068
+Node: Obtaining TeX\7f501023
+Node: Command and Variable Index\7f503134
+Node: Concept Index\7f518984

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

diff --git a/info/texinfo.info-1 b/info/texinfo.info-1
index ffb02ba..c45b639 100644 (file)
--- a/info/texinfo.info-1
+++ b/info/texinfo.info-1
@@ -1,4 +1,4 @@
-This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+This is ../info/texinfo.info, produced by makeinfo version 4.6 from

 texinfo.texi.
 
 INFO-DIR-SECTION Texinfo documentation system
 texinfo.texi.
 
 INFO-DIR-SECTION Texinfo documentation system

@@ -38,7 +38,7 @@ File: texinfo.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
 Texinfo
 *******
 
 Texinfo
 *******
 

-  Texinfo is a documentation system that uses a single source file to
+Texinfo is a documentation system that uses a single source file to

 produce both on-line information and printed output.
 
   The first part of this master menu lists the major nodes in this Info
 produce both on-line information and printed output.
 
   The first part of this master menu lists the major nodes in this Info

@@ -516,8 +516,8 @@ File: texinfo.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top
 Texinfo Copying Conditions
 **************************
 
 Texinfo Copying Conditions
 **************************
 

-  The programs currently being distributed that relate to Texinfo
-include portions of GNU Emacs, plus other separate programs (including
+The programs currently being distributed that relate to Texinfo include
+portions of GNU Emacs, plus other separate programs (including

 `makeinfo', `info', `texindex', and `texinfo.tex').  These programs are
 "free"; this means that everyone is free to use them and free to
 redistribute them on a free basis.  The Texinfo-related programs are
 `makeinfo', `info', `texindex', and `texinfo.tex').  These programs are
 "free"; this means that everyone is free to use them and free to
 redistribute them on a free basis.  The Texinfo-related programs are

@@ -556,7 +556,7 @@ File: texinfo.info,  Node: Overview,  Next: Texinfo Mode,  Prev: Copying,  Up: T
 Overview of Texinfo
 *******************
 
 Overview of Texinfo
 *******************
 

-  "Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system
+"Texinfo"(1) (*note Overview-Footnote-1::) is a documentation system

 that uses a single source file to produce both on-line information and
 printed output.  This means that instead of writing two different
 documents, one for the on-line help or other on-line information and
 that uses a single source file to produce both on-line information and
 printed output.  This means that instead of writing two different
 documents, one for the on-line help or other on-line information and

@@ -648,8 +648,8 @@ File: texinfo.info,  Node: Info Files,  Next: Printed Books,  Prev: Using Texinf
 Info files
 ==========
 
 Info files
 ==========
 

-  An Info file is a Texinfo file formatted so that the Info
-documentation reading program can operate on it.  (`makeinfo' and
+An Info file is a Texinfo file formatted so that the Info documentation
+reading program can operate on it.  (`makeinfo' and

 `texinfo-format-buffer' are two commands that convert a Texinfo file
 into an Info file.)
 
 `texinfo-format-buffer' are two commands that convert a Texinfo file
 into an Info file.)
 

@@ -733,9 +733,9 @@ File: texinfo.info,  Node: Printed Books,  Next: Formatting Commands,  Prev: Inf
 Printed Books
 =============
 
 Printed Books
 =============
 

-  A Texinfo file can be formatted and typeset as a printed book or
-manual.  To do this, you need TeX, a powerful, sophisticated typesetting
-program written by Donald Knuth.(1) (*note Printed Books-Footnote-1::)
+A Texinfo file can be formatted and typeset as a printed book or manual.
+To do this, you need TeX, a powerful, sophisticated typesetting program
+written by Donald Knuth.(1) (*note Printed Books-Footnote-1::)

 
   A Texinfo-based book is similar to any other typeset, printed work: it
 can have a title page, copyright page, table of contents, and preface,
 
   A Texinfo-based book is similar to any other typeset, printed work: it
 can have a title page, copyright page, table of contents, and preface,

@@ -795,7 +795,7 @@ File: texinfo.info,  Node: Formatting Commands,  Next: Conventions,  Prev: Print
 @-commands
 ==========
 
 @-commands
 ==========
 

-  In a Texinfo file, the commands that tell TeX how to typeset the
+In a Texinfo file, the commands that tell TeX how to typeset the

 printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
 create an Info file are preceded by `@'; they are called "@-commands".
 For example, `@node' is the command to indicate a node and `@chapter'
 printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
 create an Info file are preceded by `@'; they are called "@-commands".
 For example, `@node' is the command to indicate a node and `@chapter'

@@ -868,8 +868,8 @@ File: texinfo.info,  Node: Conventions,  Next: Comments,  Prev: Formatting Comma
 General Syntactic Conventions
 =============================
 
 General Syntactic Conventions
 =============================
 

-  All printable ASCII characters except `@', `{' and `}' can appear in
-a Texinfo file and stand for themselves.  `@' is the escape character
+All printable ASCII characters except `@', `{' and `}' can appear in a
+Texinfo file and stand for themselves.  `@' is the escape character

 which introduces commands.  `{' and `}' should be used only to surround
 arguments to certain commands.  To put one of these special characters
 into the document, put an `@' character in front of it, like this:
 which introduces commands.  `{' and `}' should be used only to surround
 arguments to certain commands.  To put one of these special characters
 into the document, put an `@' character in front of it, like this:

@@ -921,17 +921,17 @@ File: texinfo.info,  Node: Comments,  Next: Minimum,  Prev: Conventions,  Up: Ov
 Comments
 ========
 
 Comments
 ========
 

-  You can write comments in a Texinfo file that will not appear in
-either the Info file or the printed manual by using the `@comment'
-command (which may be abbreviated to `@c').  Such comments are for the
-person who reads the Texinfo file.  All the text on a line that follows
-either `@comment' or `@c' is a comment; the rest of the line does not
-appear in either the Info file or the printed manual. (Often, you can
-write the `@comment' or `@c' in the middle of a line, and only the text
-that follows after the `@comment' or `@c' command does not appear; but
-some commands, such as `@settitle' and `@setfilename', work on a whole
-line.  You cannot use `@comment' or `@c' in a line beginning with such
-a command.)
+You can write comments in a Texinfo file that will not appear in either
+the Info file or the printed manual by using the `@comment' command
+(which may be abbreviated to `@c').  Such comments are for the person
+who reads the Texinfo file.  All the text on a line that follows either
+`@comment' or `@c' is a comment; the rest of the line does not appear
+in either the Info file or the printed manual. (Often, you can write
+the `@comment' or `@c' in the middle of a line, and only the text that
+follows after the `@comment' or `@c' command does not appear; but some
+commands, such as `@settitle' and `@setfilename', work on a whole line.
+You cannot use `@comment' or `@c' in a line beginning with such a
+command.)

 
   You can write long stretches of text that will not appear in either
 the Info file or the printed manual by using the `@ignore' and `@end
 
   You can write long stretches of text that will not appear in either
 the Info file or the printed manual by using the `@ignore' and `@end

@@ -949,7 +949,7 @@ File: texinfo.info,  Node: Minimum,  Next: Six Parts,  Prev: Comments,  Up: Over
 What a Texinfo File Must Have
 =============================
 
 What a Texinfo File Must Have
 =============================
 

-  By convention, the names of Texinfo files end with one of the
+By convention, the names of Texinfo files end with one of the

 extensions `.texinfo', `.texi', or `.tex'.  The longer extension is
 preferred since it describes more clearly to a human reader the nature
 of the file.  The shorter extensions are for operating systems that
 extensions `.texinfo', `.texi', or `.tex'.  The longer extension is
 preferred since it describes more clearly to a human reader the nature
 of the file.  The shorter extensions are for operating systems that

@@ -1006,8 +1006,8 @@ File: texinfo.info,  Node: Six Parts,  Next: Short Sample,  Prev: Minimum,  Up:
 Six Parts of a Texinfo File
 ===========================
 
 Six Parts of a Texinfo File
 ===========================
 

-  Generally, a Texinfo file contains more than the minimal beginning
-and end--it usually contains six parts:
+Generally, a Texinfo file contains more than the minimal beginning and
+end--it usually contains six parts:

 
 1. Header
      The "Header" names the file, tells TeX which definitions' file to
 
 1. Header
      The "Header" names the file, tells TeX which definitions' file to

@@ -1040,3 +1040,6875 @@ and end--it usually contains six parts:
      The "End" contains commands for printing indices and generating
      the table of contents, and the `@bye' command on a line of its own.
 
      The "End" contains commands for printing indices and generating
      the table of contents, and the `@bye' command on a line of its own.
 

+\1f
+File: texinfo.info,  Node: Short Sample,  Next: Acknowledgements,  Prev: Six Parts,  Up: Overview
+
+A Short Sample Texinfo File
+===========================
+
+Here is a complete but very short Texinfo file, in six parts.  The first
+three parts of the file, from `\input texinfo' through to `@end
+titlepage', look more intimidating than they are.  Most of the material
+is standard boilerplate; when you write a manual, simply insert the
+names for your own manual in this segment. (*Note Beginning a File::.)
+
+In the following, the sample text is _indented_; comments on it are
+not.  The complete file, without any comments, is shown in *Note Sample
+Texinfo File::.
+
+Part 1: Header
+--------------
+
+The header does not appear in either the Info file or the printed
+output.  It sets various parameters, including the name of the Info
+file and the title used in the header.
+
+     \input texinfo   @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename sample.info
+     @settitle Sample Document
+     @c %**end of header
+     
+     @setchapternewpage odd
+
+Part 2: Summary Description and Copyright
+-----------------------------------------
+
+The summary description and copyright segment does not appear in the
+printed document.
+
+     @ifinfo
+     This is a short example of a complete Texinfo file.
+     
+     Copyright @copyright{} 1990 Free Software Foundation, Inc.
+     @end ifinfo
+
+Part 3: Titlepage and Copyright
+-------------------------------
+
+The titlepage segment does not appear in the Info file.
+
+     @titlepage
+     @sp 10
+     @comment The title is printed in a large font.
+     @center @titlefont{Sample Title}
+     
+     @c The following two commands start the copyright page.
+     @page
+     @vskip 0pt plus 1filll
+     Copyright @copyright{} 1990 Free Software Foundation, Inc.
+     @end titlepage
+
+Part 4: `Top' Node and Master Menu
+----------------------------------
+
+The `Top' node contains the master menu for the Info file.  Since a
+printed manual uses a table of contents rather than a menu, the master
+menu appears only in the Info file.
+
+     @node    Top,       First Chapter, ,         (dir)
+     @comment node-name, next,          previous, up
+
+     @menu
+     * First Chapter::    The first chapter is the
+                          only chapter in this sample.
+     * Concept Index::    This index has two entries.
+     @end menu
+
+Part 5:  The Body of the Document
+---------------------------------
+
+The body segment contains all the text of the document, but not the
+indices or table of contents.  This example illustrates a node and a
+chapter containing an enumerated list.
+
+     @node    First Chapter, Concept Index, Top,      Top
+     @comment node-name,     next,          previous, up
+     @chapter First Chapter
+     @cindex Sample index entry
+     
+     This is the contents of the first chapter.
+     @cindex Another sample index entry
+     
+     Here is a numbered list.
+     
+     @enumerate
+     @item
+     This is the first item.
+     
+     @item
+     This is the second item.
+     @end enumerate
+     
+     The @code{makeinfo} and @code{texinfo-format-buffer}
+     commands transform a Texinfo file such as this into
+     an Info file; and @TeX{} typesets it for a printed
+     manual.
+
+Part 6: The End of the Document
+-------------------------------
+
+The end segment contains commands both for generating an index in a node
+and unnumbered chapter of its own and for generating the table of
+contents; and it contains the `@bye' command that marks the end of the
+document.
+
+     @node    Concept Index,    ,  First Chapter, Top
+     @comment node-name,    next,  previous,      up
+     @unnumbered Concept Index
+     
+     @printindex cp
+     
+     @contents
+     @bye
+
+The Results
+-----------
+
+Here is what the contents of the first chapter of the sample look like:
+
+
+     This is the contents of the first chapter.
+
+     Here is a numbered list.
+
+       1. This is the first item.
+
+       2. This is the second item.
+
+     The `makeinfo' and `texinfo-format-buffer' commands transform a
+     Texinfo file such as this into an Info file; and TeX typesets it
+     for a printed manual.
+
+\1f
+File: texinfo.info,  Node: Acknowledgements,  Prev: Short Sample,  Up: Overview
+
+Acknowledgements
+================
+
+Richard M. Stallman wrote Edition 1.0 of this manual.
+Robert J. Chassell revised and extended it, starting with Edition 1.1.
+Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
+starting with Edition 2.22.
+
+  Our thanks go out to all who helped improve this work, particularly to
+Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
+reported mistakes and obscurities; our special thanks go to Melissa
+Weisshaus for her frequent and often tedious reviews of nearly similar
+editions.  Our mistakes are our own.
+
+  Please send suggestions and corrections to:
+
+     Internet address:
+         bug-texinfo@gnu.org
+
+Please include the manual's edition number and update date in your
+messages.
+
+\1f
+File: texinfo.info,  Node: Texinfo Mode,  Next: Beginning a File,  Prev: Overview,  Up: Top
+
+Using Texinfo Mode
+******************
+
+You may edit a Texinfo file with any text editor you choose.  A Texinfo
+file is no different from any other ASCII file.  However, GNU Emacs
+comes with a special mode, called Texinfo mode, that provides  Emacs
+commands and tools to help ease your work.
+
+  This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language.  If you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
+* Menu:
+
+* Texinfo Mode Overview::       How Texinfo mode can help you.
+* Emacs Editing::               Texinfo mode adds to GNU Emacs' general
+                                  purpose editing features.
+* Inserting::                   How to insert frequently used @-commands.
+* Showing the Structure::       How to show the structure of a file.
+* Updating Nodes and Menus::    How to update or create new nodes and menus.
+* Info Formatting::             How to format for Info.
+* Printing::                    How to format and print part or all of a file.
+* Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
+
+\1f
+File: texinfo.info,  Node: Texinfo Mode Overview,  Next: Emacs Editing,  Prev: Texinfo Mode,  Up: Texinfo Mode
+
+Texinfo Mode Overview
+=====================
+
+  Texinfo mode provides special features for working with Texinfo files:
+
+   * Insert frequently used @-commands.
+
+   * Automatically create `@node' lines.
+
+   * Show the structure of a Texinfo source file.
+
+   * Automatically create or update the `Next', `Previous', and `Up'
+     pointers of a node.
+
+   * Automatically create or update menus.
+
+   * Automatically create a master menu.
+
+   * Format a part or all of a file for Info.
+
+   * Typeset and print part or all of a file.
+
+  Perhaps the two most helpful features are those for inserting
+frequently used @-commands and for creating node pointers and menus.
+
+\1f
+File: texinfo.info,  Node: Emacs Editing,  Next: Inserting,  Prev: Texinfo Mode Overview,  Up: Texinfo Mode
+
+The Usual GNU Emacs Editing Commands
+====================================
+
+In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode.  Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features.  The major
+difference concerns filling.  In Texinfo mode, the paragraph separation
+variable and syntax table are redefined so that Texinfo commands that
+should be on lines of their own are not inadvertently included in
+paragraphs.  Thus, the `M-q' (`fill-paragraph') command will refill a
+paragraph but not mix an indexing command on a line adjacent to it into
+the paragraph.
+
+  In addition, Texinfo mode sets the `page-delimiter' variable to the
+value of `texinfo-chapter-level-regexp'; by default, this is a regular
+expression matching the commands for chapters and their equivalents,
+such as appendices.  With this value for the page delimiter, you can
+jump from chapter title to chapter title with the `C-x ]'
+(`forward-page') and `C-x [' (`backward-page') commands and narrow to a
+chapter with the `C-x p' (`narrow-to-page') command.  (*Note Pages:
+(xemacs)Pages, for details about the page commands.)
+
+  You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the three extensions `.texinfo',
+`.texi', or `.tex'.  A longer extension is preferred, since it is
+explicit, but a shorter extension may be necessary for operating
+systems that limit the length of file names.  GNU Emacs automatically
+enters Texinfo mode when you visit a file with a `.texinfo' or  `.texi'
+extension.  Also, Emacs switches to Texinfo mode when you visit a file
+that has `-*-texinfo-*-' in its first line.  If ever you are in another
+mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
+
+  Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish.  In particular, the keybindings are very easy to
+change.  The keybindings described here are the default or standard
+ones.
+
+\1f
+File: texinfo.info,  Node: Inserting,  Next: Showing the Structure,  Prev: Emacs Editing,  Up: Texinfo Mode
+
+Inserting Frequently Used Commands
+==================================
+
+Texinfo mode provides commands to insert various frequently used
+@-commands into the buffer.  You can use these commands to save
+keystrokes.
+
+  The insert commands are invoked by typing `C-c' twice and then the
+first letter of the @-command:
+
+`C-c C-c c'
+`M-x texinfo-insert-@code'
+     Insert `@code{}' and put the cursor between the braces.
+
+`C-c C-c d'
+`M-x texinfo-insert-@dfn'
+     Insert `@dfn{}' and put the cursor between the braces.
+
+`C-c C-c e'
+`M-x texinfo-insert-@end'
+     Insert `@end' and attempt to insert the correct following word,
+     such as `example' or `table'.  (This command does not handle
+     nested lists correctly, but inserts the word appropriate to the
+     immediately preceding list.)
+
+`C-c C-c i'
+`M-x texinfo-insert-@item'
+     Insert `@item' and put the cursor at the beginning of the next
+     line.
+
+`C-c C-c k'
+`M-x texinfo-insert-@kbd'
+     Insert `@kbd{}' and put the cursor between the braces.
+
+`C-c C-c n'
+`M-x texinfo-insert-@node'
+     Insert `@node' and a comment line listing the sequence for the
+     `Next', `Previous', and `Up' nodes.  Leave point after the `@node'.
+
+`C-c C-c o'
+`M-x texinfo-insert-@noindent'
+     Insert `@noindent' and put the cursor at the beginning of the next
+     line.
+
+`C-c C-c s'
+`M-x texinfo-insert-@samp'
+     Insert `@samp{}' and put the cursor between the braces.
+
+`C-c C-c t'
+`M-x texinfo-insert-@table'
+     Insert `@table' followed by a <SPC> and leave the cursor after the
+     <SPC>.
+
+`C-c C-c v'
+`M-x texinfo-insert-@var'
+     Insert `@var{}' and put the cursor between the braces.
+
+`C-c C-c x'
+`M-x texinfo-insert-@example'
+     Insert `@example' and put the cursor at the beginning of the next
+     line.
+
+`C-c C-c {'
+`M-x texinfo-insert-braces'
+     Insert `{}' and put the cursor between the braces.
+
+`C-c C-c }'
+`C-c C-c ]'
+`M-x up-list'
+     Move from between a pair of braces forward past the closing brace.
+     Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
+     however, more mnemonic; hence the two keybindings.  (Also, you can
+     move out from between braces by typing `C-f'.)
+
+  To put a command such as `@code{...}' around an _existing_ word,
+position the cursor in front of the word and type `C-u 1 C-c C-c c'.
+This makes it easy to edit existing plain text.  The value of the
+prefix argument tells Emacs how many words following point to include
+between braces--`1' for one word, `2' for two words, and so on.  Use a
+negative argument to enclose the previous word or words.  If you do not
+specify a prefix argument, Emacs inserts the @-command string and
+positions the cursor between the braces.  This feature works only for
+those @-commands that operate on a word or words within one line, such
+as `@kbd' and `@var'.
+
+  This set of insert commands was created after analyzing the frequency
+with which different @-commands are used in the `GNU Emacs Manual' and
+the `GDB Manual'.  If you wish to add your own insert commands, you can
+bind a keyboard macro to a key, use abbreviations, or extend the code
+in `texinfo.el'.
+
+  `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
+that works differently from the other insert commands.  It inserts a
+node's section or chapter title in the space for the description in a
+menu entry line.  (A menu entry has three parts, the entry name, the
+node name, and the description.  Only the node name is required, but a
+description helps explain what the node is about.  *Note The Parts of a
+Menu: Menu Parts.)
+
+  To use `texinfo-start-menu-description', position point in a menu
+entry line and type `C-c C-c C-d'.  The command looks for and copies
+the title that goes with the node name, and inserts the title as a
+description; it positions point at beginning of the inserted text so you
+can edit it.  The function does not insert the title if the menu entry
+line already contains a description.
+
+  This command is only an aid to writing descriptions; it does not do
+the whole job.  You must edit the inserted text since a title tends to
+use the same words as a node name but a useful description uses
+different words.
+
+\1f
+File: texinfo.info,  Node: Showing the Structure,  Next: Updating Nodes and Menus,  Prev: Inserting,  Up: Texinfo Mode
+
+Showing the Section Structure of a File
+=======================================
+
+You can show the section structure of a Texinfo file by using the `C-c
+C-s' command (`texinfo-show-structure').  This command shows the
+section structure of a Texinfo file by listing the lines that begin
+with the @-commands for `@chapter', `@section', and the like.  It
+constructs what amounts to a table of contents.  These lines are
+displayed in another buffer called the `*Occur*' buffer.  In that
+buffer, you can position the cursor over one of the lines and use the
+`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
+corresponding spot in the Texinfo file.
+
+`C-c C-s'
+`M-x texinfo-show-structure'
+     Show the `@chapter', `@section', and such lines of a Texinfo file.
+
+`C-c C-c'
+`M-x occur-mode-goto-occurrence'
+     Go to the line in the Texinfo file corresponding to the line under
+     the cursor in the `*Occur*' buffer.
+
+  If you call `texinfo-show-structure' with a prefix argument by typing
+`C-u C-c C-s', it will list not only those lines with the @-commands
+for `@chapter', `@section', and the like, but also the `@node' lines.
+(This is how the `texinfo-show-structure' command worked without an
+argument in the first version of Texinfo.  It was changed because
+`@node' lines clutter up the `*Occur*' buffer and are usually not
+needed.)  You can use `texinfo-show-structure' with a prefix argument
+to check whether the `Next', `Previous', and `Up' pointers of an
+`@node' line are correct.
+
+  Often, when you are working on a manual, you will be interested only
+in the structure of the current chapter.  In this case, you can mark
+off the region of the buffer that you are interested in by using the
+`C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
+will work on only that region.  To see the whole buffer again, use
+`C-x n w' (`widen').  (*Note Narrowing: (xemacs)Narrowing, for more
+information about the narrowing commands.)
+
+  In addition to providing the `texinfo-show-structure' command,
+Texinfo mode sets the value of the page delimiter variable to match the
+chapter-level @-commands.  This enables you to use the `C-x ]'
+(`forward-page') and `C-x [' (`backward-page') commands to move forward
+and backward by chapter, and to use the `C-x p' (`narrow-to-page')
+command to narrow to a chapter.  *Note Pages: (xemacs)Pages, for more
+information about the page commands.
+
+\1f
+File: texinfo.info,  Node: Updating Nodes and Menus,  Next: Info Formatting,  Prev: Showing the Structure,  Up: Texinfo Mode
+
+Updating Nodes and Menus
+========================
+
+Texinfo mode provides commands for automatically creating or updating
+menus and node pointers.  The commands are called "update" commands
+because their most frequent use is for updating a Texinfo file after
+you have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an `@node' line that has none and to
+create menus in a file that has none.
+
+  If you do not use the updating commands, you need to write menus and
+node pointers by hand, which is a tedious task.
+
+* Menu:
+
+* Updating Commands::           Five major updating commands.
+* Updating Requirements::       How to structure a Texinfo file for
+                                  using the updating command.
+* Other Updating Commands::     How to indent descriptions, insert
+                                  missing nodes lines, and update
+                                  nodes in sequence.
+
+\1f
+File: texinfo.info,  Node: Updating Commands,  Next: Updating Requirements,  Prev: Updating Nodes and Menus,  Up: Updating Nodes and Menus
+
+The Updating Commands
+---------------------
+
+  You can use the updating commands
+
+   * to insert or update the `Next', `Previous', and `Up' pointers of a
+     node,
+
+   * to insert or update the menu for a section, and
+
+   * to create a master menu for a Texinfo source file.
+
+  You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo file.
+
+  The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books.  In such files, a structuring
+command line must follow closely after each `@node' line, except for
+the `Top' `@node' line.  (A "structuring command line" is a line
+beginning with `@chapter', `@section', or other similar command.)
+
+  You can write the structuring command line on the line that follows
+immediately after an `@node' line or else on the line that follows
+after a single `@comment' line or a single `@ifinfo' line.  You cannot
+interpose more than one line between the `@node' line and the
+structuring command line; and you may interpose only an `@comment' line
+or an `@ifinfo' line.
+
+  Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an `@chapter' or equivalent-level command.
+Note that the menu updating commands will not create a main or master
+menu for a Texinfo file that has only `@chapter'-level nodes!  The menu
+updating commands only create menus _within_ nodes for lower level
+nodes.  To create a menu of chapters, you must provide a `Top' node.
+
+  The menu updating commands remove menu entries that refer to other
+Info files since they do not refer to nodes within the current buffer.
+This is a deficiency.  Rather than use menu entries, you can use cross
+references to refer to other Info files.  None of the updating commands
+affect cross references.
+
+  Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the `texinfo-master-menu' command, is for creating a master
+menu for a complete file, and optionally, for updating every node and
+menu in the whole Texinfo file.
+
+  The `texinfo-master-menu' command is the primary command:
+
+`C-c C-u m'
+`M-x texinfo-master-menu'
+     Create or update a master menu that includes all the other menus
+     (incorporating the descriptions from pre-existing menus, if any).
+
+     With an argument (prefix argument, `C-u,' if interactive), first
+     create or update all the nodes and all the regular menus in the
+     buffer before constructing the master menu.  (*Note The Top Node
+     and Master Menu: The Top Node, for more about a master menu.)
+
+     For `texinfo-master-menu' to work, the Texinfo file must have a
+     `Top' node and at least one subsequent node.
+
+     After extensively editing a Texinfo file, you can type the
+     following:
+
+          C-u M-x texinfo-master-menu
+     or
+          C-u C-c C-u m
+
+     This updates all the nodes and menus completely and all at once.
+
+  The other major updating commands do smaller jobs and are designed for
+the person  who updates nodes and menus as he or she writes a Texinfo
+file.
+
+  The commands are:
+
+`C-c C-u C-n'
+`M-x texinfo-update-node'
+     Insert the `Next', `Previous', and `Up' pointers for the node that
+     point is within (i.e., for the `@node' line preceding point).  If
+     the `@node' line has pre-existing `Next', `Previous', or `Up'
+     pointers in it, the old pointers are removed and new ones inserted.
+     With an argument (prefix argument, `C-u', if interactive), this
+     command updates all `@node' lines in the region (which is the text
+     between point and mark).
+
+`C-c C-u C-m'
+`M-x texinfo-make-menu'
+     Create or update the menu in the node that point is within.  With
+     an argument (`C-u' as prefix argument, if interactive), the
+     command makes or updates menus for the nodes which are either
+     within or a part of the region.
+
+     Whenever `texinfo-make-menu' updates an existing menu, the
+     descriptions from that menu are incorporated into the new menu.
+     This is done by copying descriptions from the existing menu to the
+     entries in the new menu that have the same node names.  If the
+     node names are different, the descriptions are not copied to the
+     new menu.
+
+`C-c C-u C-e'
+`M-x texinfo-every-node-update'
+     Insert or update the `Next', `Previous', and `Up' pointers for
+     every node in the buffer.
+
+`C-c C-u C-a'
+`M-x texinfo-all-menus-update'
+     Create or update all the menus in the buffer.  With an argument
+     (`C-u' as prefix argument, if interactive), first insert or update
+     all the node pointers before working on the menus.
+
+     If a master menu exists, the `texinfo-all-menus-update' command
+     updates it; but the command does not create a new master menu if
+     none already exists.  (Use the `texinfo-master-menu' command for
+     that.)
+
+     When working on a document that does not merit a master menu, you
+     can type the following:
+
+          C-u C-c C-u C-a
+     or
+          C-u M-x texinfo-all-menus-update
+
+     This updates all the nodes and menus.
+
+  The `texinfo-column-for-description' variable specifies the column to
+which menu descriptions are indented.  By default, the value is 32
+although it is often useful to reduce it to as low as 24.  You can set
+the variable with the `M-x edit-options' command (*note Editing
+Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
+command (*note Examining and Setting Variables: (xemacs)Examining.).
+
+  Also, the `texinfo-indent-menu-description' command may be used to
+indent existing menu descriptions to a specified column.  Finally, if
+you wish, you can use the `texinfo-insert-node-lines' command to insert
+missing `@node' lines into a file.  (*Note Other Updating Commands::,
+for more information.)
+
+\1f
+File: texinfo.info,  Node: Updating Requirements,  Next: Other Updating Commands,  Prev: Updating Commands,  Up: Updating Nodes and Menus
+
+Updating Requirements
+---------------------
+
+To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down' more
+than one level at a time: you can follow the `Top' node with a chapter,
+but not with a section; you can follow a chapter with a section, but
+not with a subsection.  However, you may `jump up' any number of levels
+at one time--for example, from a subsection to a chapter.
+
+  Each `@node' line, with the exception of the line for the `Top' node,
+must be followed by a line with a structuring command such as
+`@chapter', `@section', or `@unnumberedsubsec'.
+
+  Each `@node' line/structuring-command line combination must look
+either like this:
+
+     @node     Comments,  Minimum, Conventions, Overview
+     @comment  node-name, next,    previous,    up
+     @section Comments
+
+  or like this (without the `@comment' line):
+
+     @node Comments, Minimum, Conventions, Overview
+     @section Comments
+
+In this example, `Comments' is the name of both the node and the
+section.  The next node is called `Minimum' and the previous node is
+called `Conventions'.  The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer.  (Instead of an
+`@comment' line, you can write an `@ifinfo' line.)
+
+  If a file has a `Top' node, it must be called `top' or `Top' and be
+the first node in the file.
+
+  The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on.  This means that you
+must have a `Top' node if you want a menu of chapters.
+
+  Incidentally, the `makeinfo' command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers.  Thus, if you can be sure that your Texinfo file will be
+formatted with `makeinfo', you have no need for the `update node'
+commands.  (*Note Creating an Info File: Create an Info File, for more
+information about `makeinfo'.)  However, both `makeinfo' and the
+`texinfo-format-...' commands require that you insert menus in the file.
+
+\1f
+File: texinfo.info,  Node: Other Updating Commands,  Prev: Updating Requirements,  Up: Updating Nodes and Menus
+
+Other Updating Commands
+-----------------------
+
+In addition to the five major updating commands, Texinfo mode possesses
+several less frequently used updating commands:
+
+`M-x texinfo-insert-node-lines'
+     Insert `@node' lines before the `@chapter', `@section', and other
+     sectioning commands wherever they are missing throughout a region
+     in a Texinfo file.
+
+     With an argument (`C-u' as prefix argument, if interactive), the
+     `texinfo-insert-node-lines' command not only inserts `@node' lines
+     but also inserts the chapter or section titles as the names of the
+     corresponding nodes.  In addition, it inserts the titles as node
+     names in pre-existing `@node' lines that lack names.  Since node
+     names should be more concise than section or chapter titles, you
+     must manually edit node names so inserted.
+
+     For example, the following marks a whole buffer as a region and
+     inserts `@node' lines and titles throughout:
+
+          C-x h C-u M-x texinfo-insert-node-lines
+
+     (Note that this command inserts titles as node names in `@node'
+     lines; the `texinfo-start-menu-description' command (*note
+     Inserting Frequently Used Commands: Inserting.) inserts titles as
+     descriptions in menu entries, a different action.  However, in both
+     cases, you need to edit the inserted text.)
+
+`M-x texinfo-multiple-files-update'
+     Update nodes and menus in a document built from several separate
+     files.  With `C-u' as a prefix argument, create and insert a
+     master menu in the outer file.  With a numeric prefix argument,
+     such as `C-u 2', first update all the menus and all the `Next',
+     `Previous', and `Up' pointers of all the included files before
+     creating and inserting a master menu in the outer file.  The
+     `texinfo-multiple-files-update' command is described in the
+     appendix on `@include' files.  *Note
+     texinfo-multiple-files-update::.
+
+`M-x texinfo-indent-menu-description'
+     Indent every description in the menu following point to the
+     specified column.  You can use this command to give yourself more
+     space for descriptions.  With an argument (`C-u' as prefix
+     argument, if interactive), the `texinfo-indent-menu-description'
+     command indents every description in every menu in the region.
+     However, this command does not indent the second and subsequent
+     lines of a multi-line description.
+
+`M-x texinfo-sequential-node-update'
+     Insert the names of the nodes immediately following and preceding
+     the current node as the `Next' or `Previous' pointers regardless
+     of those nodes' hierarchical level.  This means that the `Next'
+     node of a subsection may well be the next chapter.  Sequentially
+     ordered nodes are useful for novels and other documents that you
+     read through sequentially.  (However, in Info, the `g *' command
+     lets you look through the file sequentially, so sequentially
+     ordered nodes are not strictly necessary.)  With an argument
+     (prefix argument, if interactive), the
+     `texinfo-sequential-node-update' command sequentially updates all
+     the nodes in the region.
+
+\1f
+File: texinfo.info,  Node: Info Formatting,  Next: Printing,  Prev: Updating Nodes and Menus,  Up: Texinfo Mode
+
+Formatting for Info
+===================
+
+Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info.  Often, when you are writing a document, you
+want to format only part of a file--that is, a region.
+
+  You can use either the `texinfo-format-region' or the
+`makeinfo-region' command to format a region:
+
+`C-c C-e C-r'
+`M-x texinfo-format-region'
+`C-c C-m C-r'
+`M-x makeinfo-region'
+     Format the current region for Info.
+
+  You can use either the `texinfo-format-buffer' or the
+`makeinfo-buffer' command to format a whole buffer:
+
+`C-c C-e C-b'
+`M-x texinfo-format-buffer'
+`C-c C-m C-b'
+`M-x makeinfo-buffer'
+     Format the current buffer for Info.
+
+  For example, after writing a Texinfo file, you can type the following:
+
+     C-u C-c C-u m
+or
+     C-u M-x texinfo-master-menu
+
+This updates all the nodes and menus.  Then type the following to create
+an Info file:
+
+     C-c C-m C-b
+or
+     M-x makeinfo-buffer
+
+  For TeX or the Info formatting commands to work, the file _must_
+include a line that has `@setfilename' in its header.
+
+  *Note Create an Info File::, for details about Info formatting.
+
+\1f
+File: texinfo.info,  Node: Printing,  Next: Texinfo Mode Summary,  Prev: Info Formatting,  Up: Texinfo Mode
+
+Formatting and Printing
+=======================
+
+Typesetting and printing a Texinfo file is a multi-step process in which
+you first create a file for printing (called a DVI file), and then
+print the file.  Optionally, you may also create indices.  To do this,
+you must run the `texindex' command after first running the `tex'
+typesetting command; and then you must run the `tex' command again.  Or
+else run the `texi2dvi' command which automatically creates indices as
+needed (*note Format with texi2dvi::).
+
+  Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like.  You can use the
+`texinfo-tex-region' and related commands for this purpose.  Use the
+`texinfo-tex-buffer' command to format all of a buffer.
+
+`C-c C-t C-b'
+`M-x texinfo-tex-buffer'
+     Run `texi2dvi' on the buffer.  In addition to running TeX on the
+     buffer, this command automatically creates or updates indices as
+     needed.
+
+`C-c C-t C-r'
+`M-x texinfo-tex-region'
+     Run TeX on the region.
+
+`C-c C-t C-i'
+`M-x texinfo-texindex'
+     Run `texindex' to sort the indices of a Texinfo file formatted with
+     `texinfo-tex-region'.  The `texinfo-tex-region' command does not
+     run `texindex' automatically; it only runs the `tex' typesetting
+     command.  You must run the `texinfo-tex-region' command a second
+     time after sorting the raw index files with the `texindex'
+     command.  (Usually, you do not format an index when you format a
+     region, only when you format a buffer.  Now that the `texi2dvi'
+     command exists, there is little or no need for this command.)
+
+`C-c C-t C-p'
+`M-x texinfo-tex-print'
+     Print the file (or the part of the file) previously formatted with
+     `texinfo-tex-buffer' or `texinfo-tex-region'.
+
+  For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
+_must_ start with a `\input texinfo' line and must include an
+`@settitle' line.  The file must end with `@bye' on a line by itself.
+(When you use `texinfo-tex-region', you must surround the `@settitle'
+line with start-of-header and end-of-header lines.)
+
+  *Note Format/Print Hardcopy::, for a description of the other TeX
+related commands, such as `tex-show-print-queue'.
+
+\1f
+File: texinfo.info,  Node: Texinfo Mode Summary,  Prev: Printing,  Up: Texinfo Mode
+
+Texinfo Mode Summary
+====================
+
+In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys.  All the commands that are custom-created for
+Texinfo mode begin with `C-c'.  The keys are somewhat mnemonic.
+
+Insert Commands
+---------------
+
+The insert commands are invoked by typing `C-c' twice and then the
+first letter of the @-command to be inserted.  (It might make more
+sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
+is quick to type.)
+
+     C-c C-c c       Insert `@code'.
+     C-c C-c d       Insert `@dfn'.
+     C-c C-c e       Insert `@end'.
+     C-c C-c i       Insert `@item'.
+     C-c C-c n       Insert `@node'.
+     C-c C-c s       Insert `@samp'.
+     C-c C-c v       Insert `@var'.
+     C-c C-c {       Insert braces.
+     C-c C-c ]
+     C-c C-c }       Move out of enclosing braces.
+     
+     C-c C-c C-d     Insert a node's section title
+                     in the space for the description
+                     in a menu entry line.
+
+Show Structure
+--------------
+
+The `texinfo-show-structure' command is often used within a narrowed
+region.
+
+     C-c C-s         List all the headings.
+
+The Master Update Command
+-------------------------
+
+The `texinfo-master-menu' command creates a master menu; and can be
+used to update every node and menu in a file as well.
+
+     C-c C-u m
+     M-x texinfo-master-menu
+                     Create or update a master menu.
+     
+     C-u C-c C-u m   With `C-u' as a prefix argument, first
+                     create or update all nodes and regular
+                     menus, and then create a master menu.
+
+Update Pointers
+---------------
+
+The update pointer commands are invoked by typing `C-c C-u' and then
+either `C-n' for `texinfo-update-node' or `C-e' for
+`texinfo-every-node-update'.
+
+     C-c C-u C-n     Update a node.
+     C-c C-u C-e     Update every node in the buffer.
+
+Update Menus
+------------
+
+Invoke the  update menu commands by typing `C-c C-u' and then either
+`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
+To update both nodes and menus at the same time, precede `C-c C-u C-a'
+with `C-u'.
+
+     C-c C-u C-m     Make or update a menu.
+     
+     C-c C-u C-a     Make or update all
+                     menus in a buffer.
+     
+     C-u C-c C-u C-a With `C-u' as a prefix argument,
+                     first create or update all nodes and
+                     then create or update all menus.
+
+Format for Info
+---------------
+
+The Info formatting commands that are written in Emacs Lisp are invoked
+by typing `C-c C-e' and then either `C-r' for a region or `C-b' for the
+whole buffer.
+
+  The Info formatting commands that are written in C and based on the
+`makeinfo' program are invoked by typing `C-c C-m' and then either
+`C-r' for a region or `C-b' for the whole buffer.
+
+Use the `texinfo-format...' commands:
+
+     C-c C-e C-r     Format the region.
+     C-c C-e C-b     Format the buffer.
+
+Use `makeinfo':
+
+     C-c C-m C-r     Format the region.
+     C-c C-m C-b     Format the buffer.
+     C-c C-m C-l     Recenter the `makeinfo' output buffer.
+     C-c C-m C-k     Kill the `makeinfo' formatting job.
+
+Typeset and Print
+-----------------
+
+The TeX typesetting and printing commands are invoked by typing `C-c
+C-t' and then another control command: `C-r' for `texinfo-tex-region',
+`C-b' for `texinfo-tex-buffer', and so on.
+
+     C-c C-t C-r     Run TeX on the region.
+     C-c C-t C-b     Run `texi2dvi' on the buffer.
+     C-c C-t C-i     Run `texindex'.
+     C-c C-t C-p     Print the DVI file.
+     C-c C-t C-q     Show the print queue.
+     C-c C-t C-d     Delete a job from the print queue.
+     C-c C-t C-k     Kill the current TeX formatting job.
+     C-c C-t C-x     Quit a currently stopped TeX formatting job.
+     C-c C-t C-l     Recenter the output buffer.
+
+Other Updating Commands
+-----------------------
+
+The `other updating commands' do not have standard keybindings because
+they are rarely used.
+
+     M-x texinfo-insert-node-lines
+                     Insert missing `@node' lines in region.
+                     With `C-u' as a prefix argument,
+                     use section titles as node names.
+     
+     M-x texinfo-multiple-files-update
+                     Update a multi-file document.
+                     With `C-u 2' as a prefix argument,
+                     create or update all nodes and menus
+                     in all included files first.
+     
+     M-x texinfo-indent-menu-description
+                     Indent descriptions.
+     
+     M-x texinfo-sequential-node-update
+                     Insert node pointers in strict sequence.
+
+\1f
+File: texinfo.info,  Node: Beginning a File,  Next: Ending a File,  Prev: Texinfo Mode,  Up: Top
+
+Beginning a Texinfo File
+************************
+
+Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name of the file and the title of the
+document.
+
+* Menu:
+
+* Four Parts::                  Four parts begin a Texinfo file.
+* Sample Beginning::            Here is a sample beginning for a Texinfo file.
+* Header::                      The very beginning of a Texinfo file.
+* Info Summary and Permissions::  Summary and copying permissions for Info.
+* Titlepage & Copyright Page::  Creating the title and copyright pages.
+* The Top Node::                Creating the `Top' node and master menu.
+* Software Copying Permissions::  Ensure that you and others continue to
+                                  have the right to use and share software.
+
+\1f
+File: texinfo.info,  Node: Four Parts,  Next: Sample Beginning,  Prev: Beginning a File,  Up: Beginning a File
+
+Four Parts Begin a File
+=======================
+
+  Generally, the beginning of a Texinfo file has four parts:
+
+  1. The header, delimited by special comment lines, that includes the
+     commands for naming the Texinfo file and telling TeX what
+     definitions file to use when processing the Texinfo file.
+
+  2. A short statement of what the file is about, with a copyright
+     notice and copying permissions.  This is enclosed in `@ifinfo' and
+     `@end ifinfo' commands so that the formatters place it only in the
+     Info file.
+
+  3. A title page and copyright page, with a copyright notice and
+     copying permissions.  This is enclosed between `@titlepage' and
+     `@end titlepage' commands.  The title and copyright page appear
+     only in the printed manual.
+
+  4. The `Top' node that contains a menu for the whole Info file.  The
+     contents of this node appear only in the Info file.
+
+  Also, optionally, you may include the copying conditions for a program
+and a warranty disclaimer.  The copying section will be followed by an
+introduction or else by the first chapter of the manual.
+
+  Since the copyright notice and copying permissions for the Texinfo
+document (in contrast to the copying permissions for a program) are in
+parts that appear only in the Info file or only in the printed manual,
+this information must be given twice.
+
+\1f
+File: texinfo.info,  Node: Sample Beginning,  Next: Header,  Prev: Four Parts,  Up: Beginning a File
+
+Sample Texinfo File Beginning
+=============================
+
+The following sample shows what is needed.
+
+     \input texinfo   @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename NAME-OF-INFO-FILE
+     @settitle NAME-OF-MANUAL
+     @setchapternewpage odd
+     @c %**end of header
+     
+     @ifinfo
+     This file documents ...
+     
+     Copyright YEAR COPYRIGHT-OWNER
+     
+     Permission is granted to ...
+     @end ifinfo
+     
+     @c  This title page illustrates only one of the
+     @c  two methods of forming a title page.
+     
+     @titlepage
+     @title NAME-OF-MANUAL-WHEN-PRINTED
+     @subtitle SUBTITLE-IF-ANY
+     @subtitle SECOND-SUBTITLE
+     @author AUTHOR
+     
+     @c  The following two commands
+     @c  start the copyright page.
+     @page
+     @vskip 0pt plus 1filll
+     Copyright @copyright{} YEAR COPYRIGHT-OWNER
+     
+     Published by ...
+     
+     Permission is granted to ...
+     @end titlepage
+     
+     @node Top, Overview, , (dir)
+     
+     @ifinfo
+     This document describes ...
+     
+     This document applies to version ...
+     of the program named ...
+     @end ifinfo
+     
+     @menu
+     * Copying::          Your rights and freedoms.
+     * First Chapter::    Getting started ...
+     * Second Chapter::              ...
+       ...
+       ...
+     @end menu
+     
+     @node    First Chapter, Second Chapter, top,      top
+     @comment node-name,     next,           previous, up
+     @chapter First Chapter
+     @cindex Index entry for First Chapter
+
+\1f
+File: texinfo.info,  Node: Header,  Next: Info Summary and Permissions,  Prev: Sample Beginning,  Up: Beginning a File
+
+The Texinfo File Header
+=======================
+
+Texinfo files start with at least three lines that provide Info and TeX
+with necessary information.  These are the `\input texinfo' line, the
+`@settitle' line, and the `@setfilename' line.  If you want to run TeX
+on just a part of the Texinfo File, you must write the `@settitle' and
+`@setfilename' lines between start-of-header and end-of-header lines.
+
+  Thus, the beginning of a Texinfo file looks like this:
+
+     \input texinfo   @c -*-texinfo-*-
+     @setfilename sample.info
+     @settitle Sample Document
+
+or else like this:
+
+     \input texinfo   @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename sample.info
+     @settitle Sample Document
+     @c %**end of header
+
+* Menu:
+
+* First Line::                  The first line of a Texinfo file.
+* Start of Header::             Formatting a region requires this.
+* setfilename::                 Tell Info the name of the Info file.
+* settitle::                    Create a title for the printed work.
+* setchapternewpage::           Start chapters on right-hand pages.
+* paragraphindent::             An option to specify paragraph indentation.
+* End of Header::               Formatting a region requires this.
+
+\1f
+File: texinfo.info,  Node: First Line,  Next: Start of Header,  Prev: Header,  Up: Header
+
+The First Line of a Texinfo File
+--------------------------------
+
+Every Texinfo file that is to be the top-level input to TeX must begin
+with a line that looks like this:
+
+     \input texinfo   @c -*-texinfo-*-
+
+This line serves two functions:
+
+  1. When the file is processed by TeX, the `\input texinfo' command
+     tells TeX to load the macros needed for processing a Texinfo file.
+     These are in a file called `texinfo.tex', which is usually located
+     in the `/usr/lib/tex/macros' directory.  TeX uses the backslash,
+     `\', to mark the beginning of a command, just as Texinfo uses `@'.
+     The `texinfo.tex' file causes the switch from `\' to `@'; before
+     the switch occurs, TeX requires `\', which is why it appears at
+     the beginning of the file.
+
+  2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
+     specification tells Emacs to use Texinfo mode.
+
+\1f
+File: texinfo.info,  Node: Start of Header,  Next: setfilename,  Prev: First Line,  Up: Header
+
+Start of Header
+---------------
+
+Write a start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with `@setfilename' and `@settitle'
+lines and, optionally, with other command lines, such as `@smallbook'
+or `@footnotestyle'; and then by an end-of-header line (*note End of
+Header::).
+
+  With these lines, you can format part of a Texinfo file for Info or
+typeset part for printing.
+
+  A start-of-header line looks like this:
+
+     @c %**start of header
+
+  The odd string of characters, `%**', is to ensure that no other
+comment is accidentally taken for a start-of-header line.
+
+\1f
+File: texinfo.info,  Node: setfilename,  Next: settitle,  Prev: Start of Header,  Up: Header
+
+`@setfilename'
+--------------
+
+In order to serve as the primary input file for either `makeinfo' or
+TeX, a Texinfo file must contain a line that looks like this:
+
+     @setfilename INFO-FILE-NAME
+
+  Write the `@setfilename' command at the beginning of a line and
+follow it on the same line by the Info file name.  Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a comment.
+
+  The `@setfilename' line specifies the name of the Info file to be
+generated.  This name should be different from the name of the Texinfo
+file.  There are two conventions for choosing the name: you can either
+remove the `.texi' extension from the input file name, or replace it
+with the `.info' extension.
+
+  Some operating systems cannot handle long file names.  You can run
+into a problem even when the file name you specify is itself short
+enough.  This occurs because the Info formatters split a long Info file
+into short indirect subfiles, and name them by appending `-1', `-2',
+..., `-10', `-11', and so on, to the original file name.  (*Note Tag
+Files and Split Files: Tag and Split Files.)  The subfile name
+`texinfo.info-10', for example, is too long for some systems; so the
+Info file name for this document is `texinfo' rather than
+`texinfo.info'.
+
+  The Info formatting commands ignore everything written before the
+`@setfilename' line, which is why the very first line of the file (the
+`\input' line) does not show up in the output.
+
+  The `@setfilename' line produces no output when you typeset a manual
+with TeX, but it nevertheless is essential: it opens the index,
+cross-reference, and other auxiliary files used by Texinfo, and also
+reads `texinfo.cnf' if that file is present on your system (*note
+Preparing to Use TeX: Preparing for TeX.).
+
+\1f
+File: texinfo.info,  Node: settitle,  Next: setchapternewpage,  Prev: setfilename,  Up: Header
+
+`@settitle'
+-----------
+
+In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
+     @settitle TITLE
+
+  Write the `@settitle' command at the beginning of a line and follow
+it on the same line by the title.  This tells TeX the title to use in a
+header or footer.  Do not write anything else on the line; anything on
+the line after the command is considered part of the title, including a
+comment.
+
+  Conventionally, when TeX formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings.  (TeX learns the title of each chapter
+from each `@chapter' command.)  Page footers are not printed.
+
+  Even if you are printing in a single-sided style, TeX looks for an
+`@settitle' command line, in case you include the manual title in the
+heading.
+
+  The `@settitle' command should precede everything that generates
+actual output in TeX.
+
+  Although the title in the `@settitle' command is usually the same as
+the title on the title page, it does not affect the title as it appears
+on the title page.  Thus, the two do not need not match exactly;  and
+the title in the `@settitle' command can be a shortened or expanded
+version of the title as it appears on the title page. (*Note
+`@titlepage': titlepage.)
+
+  TeX prints page headings only for that text that comes after the
+`@end titlepage' command in the Texinfo file, or that comes after an
+`@headings' command that turns on headings.  (*Note The `@headings'
+Command: headings on off, for more information.)
+
+  You may, if you wish, create your own, customized headings and
+footings.  *Note Page Headings: Headings, for a detailed discussion of
+this process.
+
+\1f
+File: texinfo.info,  Node: setchapternewpage,  Next: paragraphindent,  Prev: settitle,  Up: Header
+
+`@setchapternewpage'
+--------------------
+
+In a book or a manual, text is usually printed on both sides of the
+paper, chapters start on right-hand pages, and right-hand pages have
+odd numbers.  But in short reports, text often is printed only on one
+side of the paper.  Also in short reports, chapters sometimes do not
+start on new pages, but are printed on the same page as the end of the
+preceding chapter, after a small amount of vertical whitespace.
+
+  You can use the `@setchapternewpage' command with various arguments
+to specify how TeX should start chapters and whether it should typeset
+pages for printing on one or both sides of the paper (single-sided or
+double-sided printing).
+
+  Write the `@setchapternewpage' command at the beginning of a line
+followed by its argument.
+
+  For example, you would write the following to cause each chapter to
+start on a fresh odd-numbered page:
+
+     @setchapternewpage odd
+
+  You can specify one of three alternatives with the
+`@setchapternewpage' command:
+
+`@setchapternewpage off'
+     Cause TeX to typeset a new chapter on the same page as the last
+     chapter, after skipping some vertical whitespace.  Also, cause TeX
+     to format page headers for single-sided printing. (You can
+     override the headers format with the `@headings double' command;
+     see *Note The `@headings' Command: headings on off.)
+
+`@setchapternewpage on'
+     Cause TeX to start new chapters on new pages and to typeset page
+     headers for single-sided printing.  This is the form most often
+     used for short reports.
+
+     This alternative is the default.
+
+`@setchapternewpage odd'
+     Cause TeX to start new chapters on new, odd-numbered pages
+     (right-handed pages) and to typeset for double-sided printing.
+     This is the form most often used for books and manuals.
+
+Texinfo does not have an `@setchapternewpage even' command.
+
+(You can countermand or modify an `@setchapternewpage' command with an
+`@headings' command.  *Note The `@headings' Command: headings on off.)
+
+  At the beginning of a manual or book, pages are not numbered--for
+example, the title and copyright pages of a book are not numbered.  By
+convention, table of contents pages are numbered with roman numerals
+and not in sequence with the rest of the document.
+
+  Since an Info file does not have pages, the `@setchapternewpage'
+command has no effect on it.
+
+  Usually, you do not write an `@setchapternewpage' command for
+single-sided printing, but accept the default which is to typeset for
+single-sided printing and to start new chapters on new pages.  Usually,
+you write an `@setchapternewpage odd' command for double-sided printing.
+
+\1f
+File: texinfo.info,  Node: paragraphindent,  Next: End of Header,  Prev: setchapternewpage,  Up: Header
+
+Paragraph Indenting
+-------------------
+
+The Info formatting commands may insert spaces at the beginning of the
+first line of each paragraph, thereby indenting that paragraph.  You
+can use the `@paragraphindent' command to specify the indentation.
+Write an `@paragraphindent' command at the beginning of a line followed
+by either `asis' or a number.  The template is:
+
+     @paragraphindent INDENT
+
+  The Info formatting commands indent according to the value of INDENT:
+
+   * If the value of INDENT is `asis', the Info formatting commands do
+     not change the existing indentation.
+
+   * If the value of INDENT is zero, the Info formatting commands delete
+     existing indentation.
+
+   * If the value of INDENT is greater than zero, the Info formatting
+     commands indent the paragraph by that number of spaces.
+
+  The default value of INDENT is `asis'.
+
+  Write the `@paragraphindent' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file.  (If you write
+the command between the start-of-header and end-of-header lines, the
+region formatting commands indent paragraphs as specified.)
+
+  A peculiarity of the `texinfo-format-buffer' and
+`texinfo-format-region' commands is that they do not indent (nor fill)
+paragraphs that contain `@w' or `@*' commands.  *Note Refilling
+Paragraphs::, for a detailed description of what goes on.
+
+\1f
+File: texinfo.info,  Node: End of Header,  Prev: paragraphindent,  Up: Header
+
+End of Header
+-------------
+
+Follow the header lines with an end-of-header line.  An end-of-header
+line looks like this:
+
+     @c %**end of header
+
+  If you include the `@setchapternewpage' command between the
+start-of-header and end-of-header lines, TeX will typeset a region as
+that command specifies.  Similarly, if you include an `@smallbook'
+command between the start-of-header and end-of-header lines, TeX will
+typeset a region in the "small" book format.
+
+  The reason for the odd string of characters (`%**') is so that the
+`texinfo-tex-region' command does not accidentally find something that
+it should not when it is looking for the header.
+
+  The start-of-header line and the end-of-header line are Texinfo mode
+variables that you can change.
+
+\1f
+File: texinfo.info,  Node: Info Summary and Permissions,  Next: Titlepage & Copyright Page,  Prev: Header,  Up: Beginning a File
+
+Summary and Copying Permissions for Info
+========================================
+
+The title page and the copyright page appear only in the printed copy of
+the manual; therefore, the same information must be inserted in a
+section that appears only in the Info file.  This section usually
+contains a brief description of the contents of the Info file, a
+copyright notice, and copying permissions.
+
+  The copyright notice should read:
+
+     Copyright YEAR COPYRIGHT-OWNER
+
+and be put on a line by itself.
+
+  Standard text for the copyright permissions is contained in an
+appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
+Permissions, for the complete text.
+
+  The permissions text appears in an Info file _before_ the first node.
+This mean that a reader does _not_ see this text when reading the file
+using Info, except when using the advanced Info command `g *'.
+
+\1f
+File: texinfo.info,  Node: Titlepage & Copyright Page,  Next: The Top Node,  Prev: Info Summary and Permissions,  Up: Beginning a File
+
+The Title and Copyright Pages
+=============================
+
+A manual's name and author are usually printed on a title page.
+Sometimes copyright information is printed on the title page as well;
+more often, copyright information is printed on the back of the title
+page.
+
+  The title and copyright pages appear in the printed manual, but not
+in the Info file.  Because of this, it is possible to use several
+slightly obscure TeX typesetting commands that cannot be used in an
+Info file.  In addition, this part of the beginning of a Texinfo file
+contains the text of the copying permissions that will appear in the
+printed manual.
+
+  *Note Titlepage Copying Permissions: Titlepage Permissions, for the
+standard text for the copyright permissions.
+
+* Menu:
+
+* titlepage::                   Create a title for the printed document.
+* titlefont center sp::         The `@titlefont', `@center',
+                                  and `@sp' commands.
+* title subtitle author::       The `@title', `@subtitle',
+                                  and `@author' commands.
+* Copyright & Permissions::     How to write the copyright notice and
+                                  include copying permissions.
+* end titlepage::               Turn on page headings after the title and
+                                  copyright pages.
+* headings on off::             An option for turning headings on and off
+                                  and double or single sided printing.
+
+\1f
+File: texinfo.info,  Node: titlepage,  Next: titlefont center sp,  Prev: Titlepage & Copyright Page,  Up: Titlepage & Copyright Page
+
+`@titlepage'
+------------
+
+Start the material for the title page and following copyright page with
+`@titlepage' on a line by itself and end it with `@end titlepage' on a
+line by itself.
+
+  The `@end titlepage' command starts a new page and turns on page
+numbering.  (*Note Page Headings: Headings, for details about how to
+generate page headings.)  All the material that you want to appear on
+unnumbered pages should be put between the `@titlepage' and `@end
+titlepage' commands.  By using the `@page' command you can force a page
+break within the region delineated by the `@titlepage' and `@end
+titlepage' commands and thereby create more than one unnumbered page.
+This is how the copyright page is produced.  (The `@titlepage' command
+might perhaps have been better named the `@titleandadditionalpages'
+command, but that would have been rather long!)
+
+  When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is
+independent of it, you should also include an edition number(1) (*note
+titlepage-Footnote-1::) for the manual.  This helps readers keep track
+of which manual is for which version of the program.  (The `Top' node
+should also contain this information; see *Note `@top': makeinfo top.)
+
+  Texinfo provides two main methods for creating a title page.  One
+method uses the `@titlefont', `@sp', and `@center' commands to generate
+a title page in which the words on the page are centered.
+
+  The second method uses the `@title', `@subtitle', and `@author'
+commands to create a title page with black rules under the title and
+author lines and the subtitle text set flush to the right hand side of
+the page.  With this method, you do not specify any of the actual
+formatting of the title page.  You specify the text you want, and
+Texinfo does the formatting.  You may use either method.
+
+  For extremely simple applications, Texinfo also provides a command
+`@shorttitlepage' which takes a single argument as the title.  The
+argument is typeset on a page by itself and followed by a blank page.
+
+\1f
+File: texinfo.info,  Node: titlepage-Footnotes,  Up: titlepage
+
+  (1) We have found that it is helpful to refer to versions of manuals
+as `editions' and versions of programs as `versions'; otherwise, we
+find we are liable to confuse each other in conversation by referring
+to both the documentation and the software with the same words.
+
+\1f
+File: texinfo.info,  Node: titlefont center sp,  Next: title subtitle author,  Prev: titlepage,  Up: Titlepage & Copyright Page
+
+`@titlefont', `@center', and `@sp'
+----------------------------------
+
+You can use the `@titlefont', `@sp', and `@center' commands to create a
+title page for a printed document.  (This is the first of the two
+methods for creating a title page in Texinfo.)
+
+  Use the `@titlefont' command to select a large font suitable for the
+title itself.
+
+  For example:
+
+     @titlefont{Texinfo}
+
+  Use the `@center' command at the beginning of a line to center the
+remaining text on that line.  Thus,
+
+     @center @titlefont{Texinfo}
+
+centers the title, which in this example is "Texinfo" printed in the
+title font.
+
+  Use the `@sp' command to insert vertical space.  For example:
+
+     @sp 2
+
+This inserts two blank lines on the printed page.  (*Note `@sp': sp,
+for more information about the `@sp' command.)
+
+  A template for this method looks like this:
+
+     @titlepage
+     @sp 10
+     @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
+     @sp 2
+     @center SUBTITLE-IF-ANY
+     @sp 2
+     @center AUTHOR
+     ...
+     @end titlepage
+
+  The spacing of the example fits an 8 1/2 by 11 inch manual.
+
+\1f
+File: texinfo.info,  Node: title subtitle author,  Next: Copyright & Permissions,  Prev: titlefont center sp,  Up: Titlepage & Copyright Page
+
+`@title', `@subtitle', and `@author'
+------------------------------------
+
+You can use the `@title', `@subtitle', and `@author' commands to create
+a title page in which the vertical and horizontal spacing is done for
+you automatically.  This contrasts with the method described in the
+previous section, in which the `@sp' command is needed to adjust
+vertical spacing.
+
+  Write the `@title', `@subtitle', or `@author' commands at the
+beginning of a line followed by the title, subtitle, or author.
+
+  The `@title' command produces a line in which the title is set flush
+to the left-hand side of the page in a larger than normal font.  The
+title is underlined with a black rule.
+
+  The `@subtitle' command sets subtitles in a normal-sized font flush
+to the right-hand side of the page.
+
+  The `@author' command sets the names of the author or authors in a
+middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page.  The names are underlined with a
+black rule that is thinner than the rule that underlines the title.
+(The black rule only occurs if the `@author' command line is followed
+by an `@page' command line.)
+
+  There are two ways to use the `@author' command: you can write the
+name or names on the remaining part of the line that starts with an
+`@author' command:
+
+     @author by Jane Smith and John Doe
+
+or you can write the names one above each other by using two (or more)
+`@author' commands:
+
+     @author Jane Smith
+     @author John Doe
+
+(Only the bottom name is underlined with a black rule.)
+
+  A template for this method looks like this:
+
+     @titlepage
+     @title NAME-OF-MANUAL-WHEN-PRINTED
+     @subtitle SUBTITLE-IF-ANY
+     @subtitle SECOND-SUBTITLE
+     @author AUTHOR
+     @page
+     ...
+     @end titlepage
+
+Contrast this form with the form of a title page written using the
+`@sp', `@center', and `@titlefont' commands:
+
+     @titlepage
+     @sp 10
+     @center @titlefont{Name of Manual When Printed}
+     @sp 2
+     @center Subtitle, If Any
+     @sp 1
+     @center Second subtitle
+     @sp 2
+     @center Author
+     @page
+     ...
+     @end titlepage
+
+\1f
+File: texinfo.info,  Node: Copyright & Permissions,  Next: end titlepage,  Prev: title subtitle author,  Up: Titlepage & Copyright Page
+
+Copyright Page and Permissions
+------------------------------
+
+By international treaty, the copyright notice for a book should be
+either on the title page or on the back of the title page.  The
+copyright notice should include the year followed by the name of the
+organization or person who owns the copyright.
+
+  When the copyright notice is on the back of the title page, that page
+is customarily not numbered.  Therefore, in Texinfo, the information on
+the copyright page should be within `@titlepage' and `@end titlepage'
+commands.
+
+  Use the `@page' command to cause a page break.  To push the copyright
+notice and the other text on the copyright page towards the bottom of
+the page, you can write a somewhat mysterious line after the `@page'
+command that reads like this:
+
+     @vskip 0pt plus 1filll
+
+This is a TeX command that is not supported by the Info formatting
+commands.  The `@vskip' command inserts whitespace.  The `0pt plus
+1filll' means to put in zero points of mandatory whitespace, and as
+much optional whitespace as needed to push the following text to the
+bottom of the page.  Note the use of three `l's in the word `filll';
+this is the correct usage in TeX.
+
+  In a printed manual, the `@copyright{}' command generates a `c'
+inside a circle.  (In Info, it generates `(C)'.)  The copyright notice
+itself has the following legally defined sequence:
+
+     Copyright (C) YEAR COPYRIGHT-OWNER
+
+  It is customary to put information on how to get a manual after the
+copyright notice, followed by the copying permissions for the manual.
+
+  Note that permissions must be given here as well as in the summary
+segment within `@ifinfo' and `@end ifinfo' that immediately follows the
+header since this text appears only in the printed manual and the
+`ifinfo' text appears only in the Info file.
+
+  *Note Sample Permissions::, for the standard text.
+
+\1f
+File: texinfo.info,  Node: end titlepage,  Next: headings on off,  Prev: Copyright & Permissions,  Up: Titlepage & Copyright Page
+
+Heading Generation
+------------------
+
+An `@end titlepage' command on a line by itself not only marks the end
+of the title and copyright pages, but also causes TeX to start
+generating page headings and page numbers.
+
+  To repeat what is said elsewhere,  Texinfo has two standard page
+heading formats, one for documents which are printed on one side of
+each sheet of paper (single-sided printing), and the other for
+documents which are printed on both sides of each sheet (double-sided
+printing).  (*Note `@setchapternewpage': setchapternewpage.)  You can
+specify these formats in different ways:
+
+   * The conventional way is to write an `@setchapternewpage' command
+     before the title page commands, and then have the `@end titlepage'
+     command start generating page headings in the manner desired.
+     (*Note `@setchapternewpage': setchapternewpage.)
+
+   * Alternatively, you can use the `@headings' command to prevent page
+     headings from being generated or to start them for either single or
+     double-sided printing.  (Write an `@headings' command immediately
+     after the `@end titlepage' command.  *Note The `@headings'
+     Command: headings on off, for more information.)
+
+   * Or, you may specify your own page heading and footing format.
+     *Note Page Headings: Headings, for detailed information about page
+     headings and footings.
+
+  Most documents are formatted with the standard single-sided or
+double-sided format, using `@setchapternewpage odd' for double-sided
+printing and no `@setchapternewpage' command for single-sided printing.
+
+\1f
+File: texinfo.info,  Node: headings on off,  Prev: end titlepage,  Up: Titlepage & Copyright Page
+
+The `@headings' Command
+-----------------------
+
+The `@headings' command is rarely used.  It specifies what kind of page
+headings and footings to print on each page.  Usually, this is
+controlled by the `@setchapternewpage' command.  You need the
+`@headings' command only if the `@setchapternewpage' command does not
+do what you want, or if you want to turn off pre-defined page headings
+prior to defining your own.  Write an `@headings' command immediately
+after the `@end titlepage' command.
+
+  You can use `@headings' as follows:
+
+`@headings off'
+     Turn off printing of page headings.
+
+`@headings single'
+     Turn on page headings appropriate for single-sided printing.
+
+`@headings double'
+     Turn on page headings appropriate for double-sided printing.  The
+     two commands, `@headings on' and `@headings double', are
+     synonymous.
+
+`@headings singleafter'
+`@headings doubleafter'
+     Turn on `single' or `double' headings, respectively, after the
+     current page is output.
+
+`@headings on'
+     Turn on page headings: `single' if `@setchapternewpage on',
+     `double' otherwise.
+
+  For example, suppose you write `@setchapternewpage off' before the
+`@titlepage' command to tell TeX to start a new chapter on the same
+page as the end of the last chapter.  This command also causes TeX to
+typeset page headers for single-sided printing.  To cause TeX to
+typeset for double sided printing, write `@headings double' after the
+`@end titlepage' command.
+
+  You can stop TeX from generating any page headings at all by writing
+`@headings off' on a line of its own immediately after the line
+containing the `@end titlepage' command, like this:
+
+     @end titlepage
+     @headings off
+
+The `@headings off' command overrides the `@end titlepage' command,
+which would otherwise cause TeX to print page headings.
+
+  You can also specify your own style of page heading and footing.
+*Note Page Headings: Headings, for more information.
+
+\1f
+File: texinfo.info,  Node: The Top Node,  Next: Software Copying Permissions,  Prev: Titlepage & Copyright Page,  Up: Beginning a File
+
+The `Top' Node and Master Menu
+==============================
+
+The `Top' node is the node from which you enter an Info file.
+
+  A `Top' node should contain a brief description of the Info file and
+an extensive, master menu for the whole Info file.  This helps the
+reader understand what the Info file is about.  Also, you should write
+the version number of the program to which the Info file applies; or,
+at least, the edition number.
+
+  The contents of the `Top' node should appear only in the Info file;
+none of it should appear in printed output, so enclose it between
+`@ifinfo' and `@end ifinfo' commands.  (TeX does not print either an
+`@node' line or a menu; they appear only in Info; strictly speaking,
+you are not required to enclose these parts between `@ifinfo' and `@end
+ifinfo', but it is simplest to do so.  *Note Conditionally Visible
+Text: Conditionals.)
+
+* Menu:
+
+* Title of Top Node::           Sketch what the file is about.
+* Master Menu Parts::           A master menu has three or more parts.
+
+\1f
+File: texinfo.info,  Node: Title of Top Node,  Next: Master Menu Parts,  Prev: The Top Node,  Up: The Top Node
+
+`Top' Node Title
+----------------
+
+  Sometimes, you will want to place an `@top' sectioning command line
+containing the title of the document immediately after the `@node Top'
+line (*note The `@top' Sectioning Command: makeinfo top command., for
+more information).
+
+  For example, the beginning of the Top node of this manual contains an
+`@top' sectioning command, a short description, and edition and version
+information.  It looks like this:
+
+     ...
+     @end titlepage
+     
+     @ifinfo
+     @node Top, Copying, , (dir)
+     @top Texinfo
+     
+     Texinfo is a documentation system...
+     
+     This is edition...
+     ...
+     @end ifinfo
+     
+     @menu
+     * Copying::                 Texinfo is freely
+                                   redistributable.
+     * Overview::                What is Texinfo?
+     ...
+     @end menu
+
+  In a `Top' node, the `Previous', and `Up' nodes usually refer to the
+top level directory of the whole Info system, which is called `(dir)'.
+The `Next' node refers to the first node that follows the main or master
+menu, which is usually the copying permissions, introduction, or first
+chapter.
+
+\1f
+File: texinfo.info,  Node: Master Menu Parts,  Prev: Title of Top Node,  Up: The Top Node
+
+Parts of a Master Menu
+----------------------
+
+A "master menu" is a detailed main menu listing all the nodes in a file.
+
+  A master menu is enclosed in `@menu' and `@end menu' commands and
+does not appear in the printed document.
+
+  Generally, a master menu is divided into parts.
+
+   * The first part contains the major nodes in the Texinfo file: the
+     nodes for the chapters, chapter-like sections, and the appendices.
+
+   * The second part contains nodes for the indices.
+
+   * The third and subsequent parts contain a listing of the other,
+     lower level nodes, often ordered by chapter.  This way, rather
+     than go through an intermediary menu, an inquirer can go directly
+     to a particular node when searching for specific information.
+     These menu items are not required; add them if you think they are a
+     convenience.  If you do use them, put `@detailmenu' before the
+     first one, and `@end detailmenu' after the last; otherwise,
+     `makeinfo' will get confused.
+
+  Each section in the menu can be introduced by a descriptive line.  So
+long as the line does not begin with an asterisk, it will not be
+treated as a menu entry.  (*Note Writing a Menu::, for more
+information.)
+
+  For example, the master menu for this manual looks like the following
+(but has many more entries):
+
+     @menu
+     * Copying::             Texinfo is freely
+                               redistributable.
+     * Overview::            What is Texinfo?
+     * Texinfo Mode::        Special features in GNU Emacs.
+     ...
+     ...
+     * Command and Variable Index::
+                             An entry for each @-command.
+     * Concept Index::       An entry for each concept.
+     
+     @detailmenu
+      --- The Detailed Node Listing ---
+     
+     Overview of Texinfo
+     
+     * Info Files::          What is an Info file?
+     * Printed Manuals::     Characteristics of
+                               a printed manual.
+     ...
+     ...
+     
+     Using Texinfo Mode
+     
+     * Info on a Region::    Formatting part of a file
+                               for Info.
+     ...
+     ...
+     @end detailmenu
+     @end menu
+
+\1f
+File: texinfo.info,  Node: Software Copying Permissions,  Prev: The Top Node,  Up: Beginning a File
+
+Software Copying Permissions
+============================
+
+If the Texinfo file has a section containing the "General Public
+License" and the distribution information and a warranty disclaimer for
+the software that is documented, this section usually follows the `Top'
+node.  The General Public License is very important to Project GNU
+software.  It ensures that you and others will continue to have a right
+to use and share the software.
+
+  The copying and distribution information and the disclaimer are
+followed by an introduction or else by the first chapter of the manual.
+
+  Although an introduction is not a required part of a Texinfo file, it
+is very helpful.  Ideally, it should state clearly and concisely what
+the file is about and who would be interested in reading it.  In
+general, an introduction would follow the licensing and distribution
+information, although sometimes people put it earlier in the document.
+Usually, an introduction is put in an `@unnumbered' section.  (*Note
+The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
+
+\1f
+File: texinfo.info,  Node: Ending a File,  Next: Structuring,  Prev: Beginning a File,  Up: Top
+
+Ending a Texinfo File
+*********************
+
+The end of a Texinfo file should include the commands that create
+indices and generate detailed and summary tables of contents.  And it
+must include the `@bye' command that marks the last line processed by
+TeX.
+
+  For example:
+
+     @node    Concept Index,     , Variables Index, Top
+     @c        node-name,    next, previous,        up
+     @unnumbered Concept Index
+     
+     @printindex cp
+     
+     @contents
+     @bye
+
+* Menu:
+
+* Printing Indices & Menus::    How to print an index in hardcopy and
+                                  generate index menus in Info.
+* Contents::                    How to create a table of contents.
+* File End::                    How to mark the end of a file.
+
+\1f
+File: texinfo.info,  Node: Printing Indices & Menus,  Next: Contents,  Prev: Ending a File,  Up: Ending a File
+
+Index Menus and Printing an Index
+=================================
+
+To print an index means to include it as part of a manual or Info file.
+This does not happen automatically just because you use `@cindex' or
+other index-entry generating commands in the Texinfo file; those just
+cause the raw data for the index to be accumulated.  To generate an
+index, you must include the `@printindex' command at the place in the
+document where you want the index to appear.  Also, as part of the
+process of creating a printed manual, you must run a program called
+`texindex' (*note Format/Print Hardcopy::) to sort the raw data to
+produce a sorted index file.  The sorted index file is what is actually
+used to print the index.
+
+  Texinfo offers six different types of predefined index: the concept
+index, the function index, the variables index, the keystroke index, the
+program index, and the data type index (*note Predefined Indices::).
+Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
+and `tp'.  You may merge indices, or put them into separate sections
+(*note Combining Indices::); or you may define your own indices (*note
+Defining New Indices: New Indices.).
+
+  The `@printindex' command takes a two-letter index name, reads the
+corresponding sorted index file and formats it appropriately into an
+index.
+
+  The `@printindex' command does not generate a chapter heading for the
+index.  Consequently, you should precede the `@printindex' command with
+a suitable section or chapter command (usually `@unnumbered') to supply
+the chapter heading and put the index into the table of contents.
+Precede the `@unnumbered' command with an `@node' line.
+
+  For example:
+
+     @node Variable Index, Concept Index, Function Index, Top
+     @comment    node-name,         next,       previous, up
+     @unnumbered Variable Index
+     
+     @printindex vr
+     
+     @node     Concept Index,     , Variable Index, Top
+     @comment      node-name, next,       previous, up
+     @unnumbered Concept Index
+     
+     @printindex cp
+     
+     @summarycontents
+     @contents
+     @bye
+
+(Readers often prefer that the concept index come last in a book, since
+that makes it easiest to find.)
+
+\1f
+File: texinfo.info,  Node: Contents,  Next: File End,  Prev: Printing Indices & Menus,  Up: Ending a File
+
+Generating a Table of Contents
+==============================
+
+The `@chapter', `@section', and other structuring commands supply the
+information to make up a table of contents, but they do not cause an
+actual table to appear in the manual.  To do this, you must use the
+`@contents' and `@summarycontents' commands:
+
+`@contents'
+     Generate a table of contents in a printed manual, including all
+     chapters, sections, subsections, etc., as well as appendices and
+     unnumbered chapters.  (Headings generated by the `@heading' series
+     of commands do not appear in the table of contents.)  The
+     `@contents' command should be written on a line by itself.
+
+`@shortcontents'
+`@summarycontents'
+     (`@summarycontents' is a synonym for `@shortcontents'; the two
+     commands are exactly the same.)
+
+     Generate a short or summary table of contents that lists only the
+     chapters (and appendices and unnumbered chapters).  Omit sections,
+     subsections and subsubsections.  Only a long manual needs a short
+     table of contents in addition to the full table of contents.
+
+     Write the `@shortcontents' command on a line by itself right
+     _before_ the `@contents' command.
+
+  The table of contents commands automatically generate a chapter-like
+heading at the top of the first table of contents page.  Write the table
+of contents commands at the very end of a Texinfo file, just before the
+`@bye' command, following any index sections--anything in the Texinfo
+file after the table of contents commands will be omitted from the
+table of contents.
+
+  When you print a manual with a table of contents, the table of
+contents are printed last and numbered with roman numerals.  You need
+to place those pages in their proper place, after the title page,
+yourself.  (This is the only collating you need to do for a printed
+manual.  The table of contents is printed last because it is generated
+after the rest of the manual is typeset.)
+
+  Here is an example of where to write table of contents commands:
+
+     INDICES...
+     @shortcontents
+     @contents
+     @bye
+
+  Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the `@contents' and `@shortcontents'
+commands.
+
+\1f
+File: texinfo.info,  Node: File End,  Prev: Contents,  Up: Ending a File
+
+`@bye' File Ending
+==================
+
+An `@bye' command terminates TeX or Info formatting.  None of the
+formatting commands see any of the file following `@bye'.  The `@bye'
+command should be on a line by itself.
+
+  If you wish, you may follow the `@bye' line with notes. These notes
+will not be formatted and will not appear in either Info or a printed
+manual; it is as if text after `@bye' were within `@ignore' ... `@end
+ignore'.  Also, you may follow the `@bye' line with a local variables
+list.  *Note Using Local Variables and the Compile Command:
+Compile-Command, for more information.
+
+\1f
+File: texinfo.info,  Node: Structuring,  Next: Nodes,  Prev: Ending a File,  Up: Top
+
+Chapter Structuring
+*******************
+
+The "chapter structuring" commands divide a document into a hierarchy of
+chapters, sections, subsections, and subsubsections.  These commands
+generate large headings; they also provide information for the table of
+contents of a printed manual (*note Generating a Table of Contents:
+Contents.).
+
+  The chapter structuring commands do not create an Info node structure,
+so normally you should put an `@node' command immediately before each
+chapter structuring command (*note Nodes::).  The only time you are
+likely to use the chapter structuring commands without using the node
+structuring commands is if you are writing a document that contains no
+cross references and will never be transformed into Info format.
+
+  It is unlikely that you will ever write a Texinfo file that is
+intended only as an Info file and not as a printable document.  If you
+do, you might still use chapter structuring commands to create a
+heading at the top of each node--but you don't need to.
+
+* Menu:
+
+* Tree Structuring::            A manual is like an upside down tree ...
+* Structuring Command Types::   How to divide a manual into parts.
+* makeinfo top::                The `@top' command, part of the `Top' node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection::               Commands for the lowest level sections.
+* Raise/lower sections::        How to change commands' hierarchical level.
+
+\1f
+File: texinfo.info,  Node: Tree Structuring,  Next: Structuring Command Types,  Prev: Structuring,  Up: Structuring
+
+Tree Structure of Sections
+==========================
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like.  This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
+subsubsections.
+
+  Here is a diagram that shows a Texinfo file with three chapters, each
+of which has two sections.
+
+                               Top
+                                |
+              -------------------------------------
+             |                  |                  |
+          Chapter 1          Chapter 2          Chapter 3
+             |                  |                  |
+          --------           --------           --------
+         |        |         |        |         |        |
+      Section  Section   Section  Section   Section  Section
+        1.1      1.2       2.1      2.2       3.1      3.2
+
+  In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:
+
+     @node    Chapter 2,  Chapter 3, Chapter 1, top
+     @chapter Chapter 2
+
+  The chapter structuring commands are described in the sections that
+follow; the `@node' and `@menu' commands are described in following
+chapters. (*Note Nodes::, and see *Note Menus::.)
+
+\1f
+File: texinfo.info,  Node: Structuring Command Types,  Next: makeinfo top,  Prev: Tree Structuring,  Up: Structuring
+
+Types of Structuring Commands
+=============================
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
+subsubsections.
+
+  The four groups are the `@chapter' series, the `@unnumbered' series,
+the `@appendix' series, and the `@heading' series.
+
+  Each command produces titles that have a different appearance on the
+printed page or Info file; only some of the commands produce titles
+that are listed in the table of contents of a printed book or manual.
+
+   * The `@chapter' and `@appendix' series of commands produce numbered
+     or lettered entries both in the body of a printed work and in its
+     table of contents.
+
+   * The `@unnumbered' series of commands produce unnumbered entries
+     both in the body of a printed work and in its table of contents.
+     The `@top' command, which has a special use, is a member of this
+     series (*note `@top': makeinfo top.).
+
+   * The `@heading' series of commands produce unnumbered headings that
+     do not appear in a table of contents.  The heading commands never
+     start a new page.
+
+   * The `@majorheading' command produces results similar to using the
+     `@chapheading' command but generates a larger vertical whitespace
+     before the heading.
+
+   * When an `@setchapternewpage' command says to do so, the
+     `@chapter', `@unnumbered', and `@appendix' commands start new
+     pages in the printed manual; the `@heading' commands do not.
+
+  Here are the four groups of chapter structuring commands:
+
+
+                                                            No new pages
+     Numbered       Unnumbered       Lettered and numbered  Unnumbered
+     In contents    In contents          In contents        Not in contents
+     
+                    @top                                    @majorheading
+     @chapter       @unnumbered          @appendix          @chapheading
+     @section       @unnumberedsec       @appendixsec       @heading
+     @subsection    @unnumberedsubsec    @appendixsubsec    @subheading
+     @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
+
+\1f
+File: texinfo.info,  Node: makeinfo top,  Next: chapter,  Prev: Structuring Command Types,  Up: Structuring
+
+`@top'
+======
+
+The `@top' command is a special sectioning command that you use only
+after an `@node Top' line at the beginning of a Texinfo file.  The
+`@top' command tells the `makeinfo' formatter which node is the `Top'
+node.  It has the same typesetting effect as `@unnumbered' (*note
+`@unnumbered': (`@appendix')unnumbered & appendix.).  For detailed
+information, see *Note The `@top' Command: makeinfo top command.
+
+\1f
+File: texinfo.info,  Node: chapter,  Next: unnumbered & appendix,  Prev: makeinfo top,  Up: Structuring
+
+`@chapter'
+==========
+
+`@chapter' identifies a chapter in the document.  Write the command at
+the beginning of a line and follow it on the same line by the title of
+the chapter.
+
+  For example, this chapter in this manual is entitled "Chapter
+Structuring"; the `@chapter' line looks like this:
+
+     @chapter Chapter Structuring
+
+  In TeX, the `@chapter' command creates a chapter in the document,
+specifying the chapter title.  The chapter is numbered automatically.
+
+  In Info, the `@chapter' command causes the title to appear on a line
+by itself, with a line of asterisks inserted underneath.  Thus, in
+Info, the above example produces the following output:
+
+     Chapter Structuring
+     *******************
+
+  Texinfo also provides a command `@centerchap', which is analogous to
+`@unnumbered', but centers its argument in the printed output.  This
+kind of stylistic choice is not usually offered by Texinfo.
+
+\1f
+File: texinfo.info,  Node: unnumbered & appendix,  Next: majorheading & chapheading,  Prev: chapter,  Up: Structuring
+
+`@unnumbered', `@appendix'
+==========================
+
+Use the `@unnumbered' command to create a chapter that appears in a
+printed manual without chapter numbers of any kind.  Use the
+`@appendix' command to create an appendix in a printed manual that is
+labelled by letter instead of by number.
+
+  For Info file output, the `@unnumbered' and `@appendix' commands are
+equivalent to `@chapter': the title is printed on a line by itself with
+a line of asterisks underneath.  (*Note `@chapter': chapter.)
+
+  To create an appendix or an unnumbered chapter, write an `@appendix'
+or `@unnumbered' command at the beginning of a line and follow it on
+the same line by the title, as you would if you were creating a chapter.
+
+\1f
+File: texinfo.info,  Node: majorheading & chapheading,  Next: section,  Prev: unnumbered & appendix,  Up: Structuring
+
+`@majorheading', `@chapheading'
+===============================
+
+The `@majorheading' and `@chapheading' commands put chapter-like
+headings in the body of a document.
+
+  However, neither command causes TeX to produce a numbered heading or
+an entry in the table of contents; and neither command causes TeX to
+start a new page in a printed manual.
+
+  In TeX, an `@majorheading' command generates a larger vertical
+whitespace before the heading than an `@chapheading' command but is
+otherwise the same.
+
+  In Info, the `@majorheading' and `@chapheading' commands are
+equivalent to `@chapter': the title is printed on a line by itself with
+a line of asterisks underneath.  (*Note `@chapter': chapter.)
+
+\1f
+File: texinfo.info,  Node: section,  Next: unnumberedsec appendixsec heading,  Prev: majorheading & chapheading,  Up: Structuring
+
+`@section'
+==========
+
+In a printed manual, an `@section' command identifies a numbered
+section within a chapter.  The section title appears in the table of
+contents.  In Info, an `@section' command provides a title for a
+segment of text, underlined with `='.
+
+  This section is headed with an `@section' command and looks like this
+in the Texinfo file:
+
+     @section @code{@@section}
+
+  To create a section, write the `@section' command at the beginning of
+a line and follow it on the same line by the section title.
+
+  Thus,
+
+     @section This is a section
+
+produces
+
+     This is a section
+     =================
+
+in Info.
+
+\1f
+File: texinfo.info,  Node: unnumberedsec appendixsec heading,  Next: subsection,  Prev: section,  Up: Structuring
+
+`@unnumberedsec', `@appendixsec', `@heading'
+============================================
+
+The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
+respectively, the unnumbered, appendix-like, and heading-like
+equivalents of the `@section' command.  (*Note `@section': section.)
+
+`@unnumberedsec'
+     The `@unnumberedsec' command may be used within an unnumbered
+     chapter or within a regular chapter or appendix to provide an
+     unnumbered section.
+
+`@appendixsec'
+`@appendixsection'
+     `@appendixsection' is a longer spelling of the `@appendixsec'
+     command; the two are synonymous.
+
+     Conventionally, the `@appendixsec' or `@appendixsection' command
+     is used only within appendices.
+
+`@heading'
+     You may use the `@heading' command anywhere you wish for a
+     section-style heading that will not appear in the table of
+     contents.
+
+\1f
+File: texinfo.info,  Node: subsection,  Next: unnumberedsubsec appendixsubsec subheading,  Prev: unnumberedsec appendixsec heading,  Up: Structuring
+
+The `@subsection' Command
+=========================
+
+Subsections are to sections as sections are to chapters.  (*Note
+`@section': section.)  In Info, subsection titles are underlined with
+`-'.  For example,
+
+     @subsection This is a subsection
+
+produces
+
+     This is a subsection
+     --------------------
+
+  In a printed manual, subsections are listed in the table of contents
+and are numbered three levels deep.
+
+\1f
+File: texinfo.info,  Node: unnumberedsubsec appendixsubsec subheading,  Next: subsubsection,  Prev: subsection,  Up: Structuring
+
+The `@subsection'-like Commands
+===============================
+
+The `@unnumberedsubsec', `@appendixsubsec', and `@subheading' commands
+are, respectively, the unnumbered, appendix-like, and heading-like
+equivalents of the `@subsection' command.  (*Note `@subsection':
+subsection.)
+
+  In Info, the `@subsection'-like commands generate a title underlined
+with hyphens.  In a printed manual, an `@subheading' command produces a
+heading like that of a subsection except that it is not numbered and
+does not appear in the table of contents.  Similarly, an
+`@unnumberedsubsec' command produces an unnumbered heading like that of
+a subsection and an `@appendixsubsec' command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of contents.
+
+\1f
+File: texinfo.info,  Node: subsubsection,  Next: Raise/lower sections,  Prev: unnumberedsubsec appendixsubsec subheading,  Up: Structuring
+
+The `subsub' Commands
+=====================
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands.  They are:
+
+`@subsubsection'
+     Subsubsections are to subsections as subsections are to sections.
+     (*Note `@subsection': subsection.)  In a printed manual,
+     subsubsection titles appear in the table of contents and are
+     numbered four levels deep.
+
+`@unnumberedsubsubsec'
+     Unnumbered subsubsection titles appear in the table of contents of
+     a printed manual, but lack numbers.  Otherwise, unnumbered
+     subsubsections are the same as subsubsections.  In Info, unnumbered
+     subsubsections look exactly like ordinary subsubsections.
+
+`@appendixsubsubsec'
+     Conventionally, appendix commands are used only for appendices and
+     are lettered and numbered appropriately in a printed manual.  They
+     also appear in the table of contents.  In Info, appendix
+     subsubsections look exactly like ordinary subsubsections.
+
+`@subsubheading'
+     The `@subsubheading' command may be used anywhere that you need a
+     small heading that will not appear in the table of contents.  In
+     Info, subsubheadings look exactly like ordinary subsubsection
+     headings.
+
+  In Info,  `subsub' titles are underlined with periods.  For example,
+
+     @subsubsection This is a subsubsection
+
+produces
+
+     This is a subsubsection
+     .......................
+
+\1f
+File: texinfo.info,  Node: Raise/lower sections,  Prev: subsubsection,  Up: Structuring
+
+`@raisesections' and `@lowersections'
+=====================================
+
+The `@raisesections' and `@lowersections' commands raise and lower the
+hierarchical level of chapters, sections, subsections and the like.
+The `@raisesections' command changes sections to chapters, subsections
+to sections, and so on.  The `@lowersections' command changes chapters
+to sections, sections to subsections, and so on.
+
+  An `@lowersections' command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file.  If you write the command at
+the beginning of the file, all your `@chapter' commands are formatted
+as if they were `@section' commands, all your `@section' command are
+formatted as if they were `@subsection' commands, and so on.
+
+  `@raisesections' raises a command one level in the chapter
+structuring hierarchy:
+
+       Change           To
+     
+     @subsection     @section,
+     @section        @chapter,
+     @heading        @chapheading,
+               etc.
+
+  `@lowersections' lowers a command one level in the chapter
+structuring hierarchy:
+
+       Change           To
+     
+     @chapter        @section,
+     @subsection     @subsubsection,
+     @heading        @subheading,
+               etc.
+
+  An `@raisesections' or `@lowersections' command changes only those
+structuring commands that follow the command in the Texinfo file.
+Write an `@raisesections' or `@lowersections' command on a line of its
+own.
+
+  An `@lowersections' command cancels an `@raisesections' command, and
+vice versa.  Typically, the commands are used like this:
+
+     @lowersections
+     @include somefile.texi
+     @raisesections
+
+  Without the `@raisesections', all the subsequent sections in your
+document will be lowered.
+
+  Repeated use of the commands continue to raise or lower the
+hierarchical level a step at a time.
+
+  An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
+\1f
+File: texinfo.info,  Node: Nodes,  Next: Menus,  Prev: Structuring,  Up: Top
+
+Nodes
+*****
+
+"Nodes" are the primary segments of a Texinfo file.  They do not
+themselves impose a hierarchic or any other kind of structure on a file.
+Nodes contain "node pointers" that name other nodes, and can contain
+"menus" which are lists of nodes.  In Info, the movement commands can
+carry you to a pointed-to node or to a node listed in a menu.  Node
+pointers and menus provide structure for Info files just as chapters,
+sections, subsections, and the like, provide structure for printed
+books.
+
+* Menu:
+
+* Two Paths::                   Different commands to structure
+                                  Info output and printed output.
+* Node Menu Illustration::      A diagram, and sample nodes and menus.
+* node::                        How to write a node, in detail.
+* makeinfo Pointer Creation::   How to create node pointers with `makeinfo'.
+
+\1f
+File: texinfo.info,  Node: Two Paths,  Next: Node Menu Illustration,  Prev: Nodes,  Up: Nodes
+
+Two Paths
+=========
+
+  The node and menu commands and the chapter structuring commands are
+independent of each other:
+
+   * In Info, node and menu commands provide structure.  The chapter
+     structuring commands generate headings with different kinds of
+     underlining--asterisks for chapters, hyphens for sections, and so
+     on; they do nothing else.
+
+   * In TeX, the chapter structuring commands generate chapter and
+     section numbers and tables of contents.  The node and menu
+     commands provide information for cross references; they do nothing
+     else.
+
+  You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output.  However, most Texinfo
+files are written such that the structure for the Info output
+corresponds to the structure for the printed output.  It is not
+convenient to do otherwise.
+
+  Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out.  Similarly, node pointers and menus are organized to create a
+matching structure in the Info output.
+
+\1f
+File: texinfo.info,  Node: Node Menu Illustration,  Next: node,  Prev: Two Paths,  Up: Nodes
+
+Node and Menu Illustration
+==========================
+
+Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two sections.
+
+  Note that the "root" is at the top of the diagram and the "leaves"
+are at the bottom.  This is how such a diagram is drawn conventionally;
+it illustrates an upside-down tree.  For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
+root.
+
+                               Top
+                                |
+              -------------------------------------
+             |                  |                  |
+          Chapter 1          Chapter 2          Chapter 3
+             |                  |                  |
+          --------           --------           --------
+         |        |         |        |         |        |
+      Section  Section   Section  Section   Section  Section
+        1.1      1.2       2.1      2.2       3.1      3.2
+
+  Write the beginning of the node for Chapter 2 like this:
+
+     @node     Chapter 2,  Chapter 3, Chapter 1, top
+     @comment  node-name,  next,      previous,  up
+
+This `@node' line says that the name of this node is "Chapter 2", the
+name of the `Next' node is "Chapter 3", the name of the `Previous' node
+is "Chapter 1", and the name of the `Up' node is "Top".
+
+     *Please Note:* `Next' refers to the next node at the same
+     hierarchical level in the manual, not necessarily to the next node
+     within the Texinfo file.  In the Texinfo file, the subsequent node
+     may be at a lower level--a section-level node may follow a
+     chapter-level node, and a subsection-level node may follow a
+     section-level node.  `Next' and `Previous' refer to nodes at the
+     _same_ hierarchical level.  (The `Top' node contains the exception
+     to this rule.  Since the `Top' node is the only node at that
+     level, `Next' refers to the first following node, which is almost
+     always a chapter or chapter-level node.)
+
+  To go to Sections 2.1 and 2.2 using Info, you need a menu inside
+Chapter 2.  (*Note Menus::.)  You would write the menu just before the
+beginning of Section 2.1, like this:
+
+         @menu
+         * Sect. 2.1::    Description of this section.
+         * Sect. 2.2::
+         @end menu
+
+  Write the node for Sect. 2.1 like this:
+
+         @node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+         @comment  node-name, next,      previous,  up
+
+  In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level--from chapter to chapter or from
+section to section (sometimes, as shown, the `Previous' pointer points
+up); an `Up' pointer usually leads to a node at the level above (closer
+to the `Top' node); and a `Menu' leads to nodes at a level below (closer
+to `leaves').  (A cross reference can point to a node at any level; see
+*Note Cross References::.)
+
+  Usually, an `@node' command and a chapter structuring command are
+used in sequence, along with indexing commands.  (You may follow the
+`@node' line with a comment line that reminds you which pointer is
+which.)
+
+  Here is the beginning of the chapter in this manual called "Ending a
+Texinfo File".  This shows an `@node' line followed by a comment line,
+an `@chapter' line, and then by indexing lines.
+
+     @node    Ending a File, Structuring, Beginning a File, Top
+     @comment node-name,     next,        previous,         up
+     @chapter Ending a Texinfo File
+     @cindex Ending a Texinfo file
+     @cindex Texinfo file ending
+     @cindex File ending
+
+\1f
+File: texinfo.info,  Node: node,  Next: makeinfo Pointer Creation,  Prev: Node Menu Illustration,  Up: Nodes
+
+The `@node' Command
+===================
+
+A "node" is a segment of text that begins at an `@node' command and
+continues until the next `@node' command.  The definition of node is
+different from that for chapter or section.  A chapter may contain
+sections and a section may contain subsections; but a node cannot
+contain subnodes; the text of a node continues only until the next
+`@node' command in the file.  A node usually contains only one chapter
+structuring command, the one that follows the `@node' line.  On the
+other hand, in printed output nodes are used only for cross references,
+so a chapter or section may contain any number of nodes.  Indeed, a
+chapter usually contains several nodes, one for each section,
+subsection, and subsubsection.
+
+  To create a node, write an `@node' command at the beginning of a
+line, and follow it with four arguments, separated by commas, on the
+rest of the same line.  These arguments are the name of the node, and
+the names of the `Next', `Previous', and `Up' pointers, in that order.
+You may insert spaces before each pointer if you wish; the spaces are
+ignored.  You must write the name of the node, and the names of the
+`Next', `Previous', and `Up' pointers, all on the same line.  Otherwise,
+the formatters fail.  (*note info: (info)Top, for more information
+about nodes in Info.)
+
+  Usually, you write one of the chapter-structuring command lines
+immediately after an `@node' line--for example, an `@section' or
+`@subsection' line.  (*Note Types of Structuring Commands: Structuring
+Command Types.)
+
+     *Please note:* The GNU Emacs Texinfo mode updating commands work
+     only with Texinfo files in which `@node' lines are followed by
+     chapter structuring lines.  *Note Updating Requirements::.
+
+  TeX uses `@node' lines to identify the names to use for cross
+references.  For this reason, you must write `@node' lines in a Texinfo
+file that you intend to format for printing, even if you do not intend
+to format it for Info.  (Cross references, such as the one at the end
+of this sentence, are made with `@xref' and its related commands; see
+*Note Cross References::.)
+
+* Menu:
+
+* Node Names::                  How to choose node and pointer names.
+* Writing a Node::              How to write an `@node' line.
+* Node Line Tips::              Keep names short.
+* Node Line Requirements::      Keep names unique, without @-commands.
+* First Node::                  How to write a `Top' node.
+* makeinfo top command::        How to use the `@top' command.
+* Top Node Summary::            Write a brief description for readers.
+
+\1f
+File: texinfo.info,  Node: Node Names,  Next: Writing a Node,  Prev: node,  Up: node
+
+Choosing Node and Pointer Names
+-------------------------------
+
+  The name of a node identifies the node.  The pointers enable you to
+reach other nodes and consist of the names of those nodes.
+
+  Normally, a node's `Up' pointer contains the name of the node whose
+menu mentions that node.  The node's `Next' pointer contains the name
+of the node that follows that node in that menu and its `Previous'
+pointer contains the name of the node that precedes it in that menu.
+When a node's `Previous' node is the same as its `Up' node, both node
+pointers name the same node.
+
+  Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' and `Previous' pointers point to the `dir' file, which contains
+the main menu for all of Info.
+
+  The `Top' node itself contains the main or master menu for the manual.
+Also, it is helpful to include a brief description of the manual in the
+`Top' node.  *Note First Node::, for information on how to write the
+first node of a Texinfo file.
+
+\1f
+File: texinfo.info,  Node: Writing a Node,  Next: Node Line Tips,  Prev: Node Names,  Up: node
+
+How to Write an `@node' Line
+----------------------------
+
+The easiest way to write an `@node' line is to write `@node' at the
+beginning of a line and then the name of the node, like this:
+
+     @node NODE-NAME
+
+  If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers; or you
+can leave the pointers out of the Texinfo file and let `makeinfo'
+insert node pointers into the Info file it creates.  (*Note Texinfo
+Mode::, and *Note makeinfo Pointer Creation::.)
+
+  Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself.  If you do this, you may find it helpful to use the
+Texinfo mode keyboard command `C-c C-c n'.  This command inserts
+`@node' and a comment line listing the names of the pointers in their
+proper order.  The comment line helps you keep track of which arguments
+are for which pointers.  This comment line is especially useful if you
+are not familiar with Texinfo.
+
+  The template for a node line with `Next', `Previous', and `Up'
+pointers looks like this:
+
+     @node NODE-NAME, NEXT, PREVIOUS, UP
+
+  If you wish, you can ignore `@node' lines altogether in your first
+draft and then use the `texinfo-insert-node-lines' command to create
+`@node' lines for you.  However, we do not recommend this practice.  It
+is better to name the node itself at the same time that you write a
+segment so you can easily make cross references.  A large number of
+cross references are an especially important feature of a good Info
+file.
+
+  After you have inserted an `@node' line, you should immediately write
+an @-command for the chapter or section and insert its name.  Next (and
+this is important!), put in several index entries.  Usually, you will
+find at least two and often as many as four or five ways of referring
+to the node in the index.  Use them all.  This will make it much easier
+for people to find the node.
+
+\1f
+File: texinfo.info,  Node: Node Line Tips,  Next: Node Line Requirements,  Prev: Writing a Node,  Up: node
+
+`@node' Line Tips
+-----------------
+
+Here are three suggestions:
+
+   * Try to pick node names that are informative but short.
+
+     In the Info file, the file name, node name, and pointer names are
+     all inserted on one line, which may run into the right edge of the
+     window.  (This does not cause a problem with Info, but is ugly.)
+
+   * Try to pick node names that differ from each other near the
+     beginnings of their names.  This way, it is easy to use automatic
+     name completion in Info.
+
+   * By convention, node names are capitalized just as they would be for
+     section or chapter titles--initial and significant words are
+     capitalized; others are not.
+
+\1f
+File: texinfo.info,  Node: Node Line Requirements,  Next: First Node,  Prev: Node Line Tips,  Up: node
+
+`@node' Line Requirements
+-------------------------
+
+Here are several requirements for `@node' lines:
+
+   * All the node names for a single Info file must be unique.
+
+     Duplicates confuse the Info movement commands.  This means, for
+     example, that if you end every chapter with a summary, you must
+     name each summary node differently.  You cannot just call each one
+     "Summary".  You may, however, duplicate the titles of chapters,
+     sections, and the like.  Thus you can end each chapter in a book
+     with a section called "Summary", so long as the node names for
+     those sections are all different.
+
+   * A pointer name must be the name of a node.
+
+     The node to which a pointer points may come before or after the
+     node containing the pointer.
+
+   * You cannot use any of the Texinfo @-commands in a node name;
+     @-commands confuse Info.
+
+     Thus, the beginning of the section called `@chapter' looks like
+     this:
+
+          @node  chapter, unnumbered & appendix, makeinfo top, Structuring
+          @comment  node-name,  next,  previous,  up
+          @section @code{@@chapter}
+          @findex chapter
+
+   * You cannot use commas or apostrophes within a node name; these
+     confuse TeX or the Info formatters.
+
+     For example, the following is a section title:
+
+          @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
+
+     The corresponding node name is:
+
+          unnumberedsec appendixsec heading
+
+   * Case is significant.
+
+\1f
+File: texinfo.info,  Node: First Node,  Next: makeinfo top command,  Prev: Node Line Requirements,  Up: node
+
+The First Node
+--------------
+
+The first node of a Texinfo file is the "Top" node, except in an
+included file (*note Include Files::).  The Top node contains the main
+or master menu for the document, and a short summary of the document
+(*note Top Node Summary::).
+
+  The Top node (which must be named `top' or `Top') should have as its
+`Up' node the name of a node in another file, where there is a menu
+that leads to this file.  Specify the file name in parentheses.  If the
+file is to be installed directly in the Info directory file, use
+`(dir)' as the parent of the Top node; this is short for `(dir)top',
+and specifies the Top node in the `dir' file, which contains the main
+menu for the Info system as a whole.  For example, the `@node Top' line
+of this manual looks like this:
+
+     @node Top, Copying, , (dir)
+
+(You can use the Texinfo updating commands or the `makeinfo' utility to
+insert these pointers automatically.)
+
+  Do not define the `Previous' node of the Top node to be `(dir)', as
+it causes confusing behavior for users: if you are in the Top node and
+hit <DEL> to go backwards, you wind up in the middle of some other
+entry in the `dir' file, which has nothing to do with what you were
+reading.
+
+  *Note Install an Info File::, for more information about installing
+an Info file in the `info' directory.
+
+\1f
+File: texinfo.info,  Node: makeinfo top command,  Next: Top Node Summary,  Prev: First Node,  Up: node
+
+The `@top' Sectioning Command
+-----------------------------
+
+A special sectioning command, `@top', has been created for use with the
+`@node Top' line.  The `@top' sectioning command tells `makeinfo' that
+it marks the `Top' node in the file.  It provides the information that
+`makeinfo' needs to insert node pointers automatically.  Write the
+`@top' command at the beginning of the line immediately following the
+`@node Top' line.  Write the title on the remaining part of the same
+line as the `@top' command.
+
+  In Info, the `@top' sectioning command causes the title to appear on a
+line by itself, with a line of asterisks inserted underneath.
+
+  In TeX and `texinfo-format-buffer', the `@top' sectioning command is
+merely a synonym for `@unnumbered'.  Neither of these formatters
+require an `@top' command, and do nothing special with it.  You can use
+`@chapter' or `@unnumbered' after the `@node Top' line when you use
+these formatters.  Also, you can use `@chapter' or `@unnumbered' when
+you use the Texinfo updating commands to create or update pointers and
+menus.
+
+\1f
+File: texinfo.info,  Node: Top Node Summary,  Prev: makeinfo top command,  Up: node
+
+The `Top' Node Summary
+----------------------
+
+You can help readers by writing a summary in the `Top' node, after the
+`@top' line, before the main or master menu.  The summary should
+briefly describe the document.  In Info, this summary will appear just
+before the master menu.  In a printed manual, this summary will appear
+on a page of its own.
+
+  If you do not want the summary to appear on a page of its own in a
+printed manual, you can enclose the whole of the `Top' node, including
+the `@node Top' line and the `@top' sectioning command line or other
+sectioning command line between `@ifinfo' and `@end ifinfo'.  This
+prevents any of the text from appearing in the printed output. (*note
+Conditionally Visible Text: Conditionals.).  You can repeat the brief
+description from the `Top' node within `@iftex' ... `@end iftex' at the
+beginning of the first chapter, for those who read the printed manual.
+This saves paper and may look neater.
+
+  You should write the version number of the program to which the manual
+applies in the summary.  This helps the reader keep track of which
+manual is for which version of the program.  If the manual changes more
+frequently than the program or is independent of it, you should also
+include an edition number for the manual.  (The title page should also
+contain this information: see *Note `@titlepage': titlepage.)
+
+\1f
+File: texinfo.info,  Node: makeinfo Pointer Creation,  Prev: node,  Up: Nodes
+
+Creating Pointers with `makeinfo'
+=================================
+
+The `makeinfo' program has a feature for automatically creating node
+pointers for a hierarchically organized file that lacks them.
+
+  When you take advantage of this feature, you do not need to write the
+`Next', `Previous', and `Up' pointers after the name of a node.
+However, you must write a sectioning command, such as `@chapter' or
+`@section', on the line immediately following each truncated `@node'
+line.  You cannot write a comment line after a node line; the section
+line must follow it immediately.
+
+  In addition, you must follow the `Top' `@node' line with a line
+beginning with `@top' to mark the `Top' node in the file. *Note `@top':
+makeinfo top.
+
+  Finally, you must write the name of each node (except for the `Top'
+node) in a menu that is one or more hierarchical levels above the
+node's hierarchical level.
+
+  This node pointer insertion feature in `makeinfo' is an alternative
+to the menu and pointer creation and update commands in Texinfo mode.
+(*Note Updating Nodes and Menus::.)  It is especially helpful to people
+who do not use GNU Emacs for writing Texinfo documents.
+
+\1f
+File: texinfo.info,  Node: Menus,  Next: Cross References,  Prev: Nodes,  Up: Top
+
+Menus
+*****
+
+"Menus" contain pointers to subordinate nodes.(1) (*note
+Menus-Footnote-1::) In Info, you use menus to go to such nodes.  Menus
+have no effect in printed manuals and do not appear in them.
+
+  By convention, a menu is put at the end of a node since a reader who
+uses the menu may not see text that follows it.
+
+  A node that has a menu should _not_ contain much text.  If you have a
+lot of text and a menu, move most of the text into a new subnode--all
+but a few lines.
+
+* Menu:
+
+* Menu Location::               Put a menu in a short node.
+* Writing a Menu::              What is a menu?
+* Menu Parts::                  A menu entry has three parts.
+* Less Cluttered Menu Entry::   Two part menu entry.
+* Menu Example::                Two and three part menu entries.
+* Other Info Files::            How to refer to a different Info file.
+
+\1f
+File: texinfo.info,  Node: Menus-Footnotes,  Up: Menus
+
+  (1) Menus can carry you to any node, regardless of the hierarchical
+structure; even to nodes in a different Info file.  However, the GNU
+Emacs Texinfo mode updating commands work only to create menus of
+subordinate nodes.  Conventionally, cross references are used to refer
+to other nodes.
+
+\1f
+File: texinfo.info,  Node: Menu Location,  Next: Writing a Menu,  Prev: Menus,  Up: Menus
+
+Menus Need Short Nodes
+======================
+
+  A reader can easily see a menu that is close to the beginning of the
+node.  The node should be short.  As a practical matter, you should
+locate a menu within 20 lines of the beginning of the node.  Otherwise,
+a reader with a terminal that displays only a few lines may miss the
+menu and its associated text.
+
+  The short text before a menu may look awkward in a printed manual.  To
+avoid this, you can write a menu near the beginning of its node and
+follow the menu by an `@node' line, and then an `@heading' line located
+within `@ifinfo' and `@end ifinfo'.  This way, the menu, `@node' line,
+and title appear only in the Info file, not the printed document.
+
+  For example, the preceding two paragraphs follow an Info-only menu,
+`@node' line, and heading, and look like this:
+
+     @menu
+     * Menu Location::             Put a menu in a short node.
+     * Writing a Menu::            What is a menu?
+     * Menu Parts::                A menu entry has three parts.
+     * Less Cluttered Menu Entry:: Two part menu entry.
+     * Menu Example::              Two and three part entries.
+     * Other Info Files::          How to refer to a different
+                                     Info file.
+     @end menu
+     
+     @node Menu Location, Writing a Menu, , Menus
+     @ifinfo
+     @heading Menus Need Short Nodes
+     @end ifinfo
+
+  The Texinfo file for this document contains more than a dozen
+examples of this procedure.  One is at the beginning of this chapter;
+another is at the beginning of the "Cross References" chapter.
+
+\1f
+File: texinfo.info,  Node: Writing a Menu,  Next: Menu Parts,  Prev: Menu Location,  Up: Menus
+
+Writing a Menu
+==============
+
+A menu consists of an `@menu' command on a line by itself followed by
+menu entry lines or menu comment lines and then by an `@end menu'
+command on a line by itself.
+
+  A menu looks like this:
+
+     @menu
+     Larger Units of Text
+     
+     * Files::                       All about handling files.
+     * Multiples: Buffers.           Multiple buffers; editing
+                                       several files at once.
+     @end menu
+
+  In a menu, every line that begins with an `* ' is a "menu entry".
+(Note the space after the asterisk.)  A line that does not start with
+an `* ' may also appear in a menu.  Such a line is not a menu entry but
+is a menu comment line that appears in the Info file.  In the example
+above, the line `Larger Units of Text' is a menu comment line; the two
+lines starting with `* ' are menu entries.
+
+\1f
+File: texinfo.info,  Node: Menu Parts,  Next: Less Cluttered Menu Entry,  Prev: Writing a Menu,  Up: Menus
+
+The Parts of a Menu
+===================
+
+A menu entry has three parts, only the second of which is required:
+
+  1. The menu entry name (optional).
+
+  2. The name of the node (required).
+
+  3. A description of the item (optional).
+
+  The template for a menu entry looks like this:
+
+     * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION
+
+  Follow the menu entry name with a single colon and follow the node
+name with tab, comma, period, or newline.
+
+  In Info, a user selects a node with the `m' (`Info-menu') command.
+The menu entry name is what the user types after the `m' command.
+
+  The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about.  A useful description
+complements the node name rather than repeats it.  The description,
+which is optional, can spread over two or more lines; if it does, some
+authors prefer to indent the second line while others prefer to align it
+with the first (and all others).  It's up to you.
+
+\1f
+File: texinfo.info,  Node: Less Cluttered Menu Entry,  Next: Menu Example,  Prev: Menu Parts,  Up: Menus
+
+Less Cluttered Menu Entry
+=========================
+
+When the menu entry name and node name are the same, you can write the
+name immediately after the asterisk and space at the beginning of the
+line and follow the name with two colons.
+
+  For example, write
+
+     * Name::                                    DESCRIPTION
+
+instead of
+
+     * Name: Name.                               DESCRIPTION
+
+  You should use the node name for the menu entry name whenever
+possible, since it reduces visual clutter in the menu.
+
+\1f
+File: texinfo.info,  Node: Menu Example,  Next: Other Info Files,  Prev: Less Cluttered Menu Entry,  Up: Menus
+
+A Menu Example
+==============
+
+A menu looks like this in Texinfo:
+
+     @menu
+     * menu entry name: Node name.   A short description.
+     * Node name::                   This form is preferred.
+     @end menu
+
+This produces:
+
+     * menu:
+     
+     * menu entry name: Node name.   A short description.
+     * Node name::                   This form is preferred.
+
+  Here is an example as you might see it in a Texinfo file:
+
+     @menu
+     Larger Units of Text
+     
+     * Files::                       All about handling files.
+     * Multiples: Buffers.           Multiple buffers; editing
+                                       several files at once.
+     @end menu
+
+This produces:
+
+     * menu:
+     Larger Units of Text
+     
+     * Files::                       All about handling files.
+     * Multiples: Buffers.           Multiple buffers; editing
+                                       several files at once.
+
+  In this example, the menu has two entries.  `Files' is both a menu
+entry name and the name of the node referred to by that name.
+`Multiples' is the menu entry name; it refers to the node named
+`Buffers'. The line `Larger Units of Text' is a comment; it appears in
+the menu, but is not an entry.
+
+  Since no file name is specified with either `Files' or `Buffers',
+they must be the names of nodes in the same Info file (*note Referring
+to Other Info Files: Other Info Files.).
+
+\1f
+File: texinfo.info,  Node: Other Info Files,  Prev: Menu Example,  Up: Menus
+
+Referring to Other Info Files
+=============================
+
+You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name.  In this case, you should use the three-part menu
+entry format, which saves the reader from having to type the file name.
+
+  The format looks like this:
+
+     @menu
+     * FIRST-ENTRY-NAME:(FILENAME)NODENAME.     DESCRIPTION
+     * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
+     @end menu
+
+  For example, to refer directly to the `Outlining' and `Rebinding'
+nodes in the `XEmacs User's Manual', you would write a menu like this:
+
+     @menu
+     * Outlining: (xemacs)Outline Mode. The major mode for
+                                        editing outlines.
+     * Rebinding: (xemacs)Rebinding.    How to redefine the
+                                        meaning of a key.
+     @end menu
+
+  If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' node.
+
+  The `dir' file that contains the main menu for Info has menu entries
+that list only file names.  These take you directly to the `Top' nodes
+of each Info document.  (*Note Install an Info File::.)
+
+  For example:
+
+     * Info: (info).         Documentation browsing system.
+     * Emacs: (emacs).       The extensible, self-documenting
+                             text editor.
+
+(The `dir' top level directory for the Info system is an Info file, not
+a Texinfo file, but a menu entry looks the same in both types of file.)
+
+  Note that the GNU Emacs Texinfo mode menu updating commands only work
+with nodes within the current buffer, so you cannot use them to create
+menus that refer to other files.  You must write such menus by hand.
+
+\1f
+File: texinfo.info,  Node: Cross References,  Next: Marking Text,  Prev: Menus,  Up: Top
+
+Cross References
+****************
+
+"Cross references" are used to refer the reader to other parts of the
+same or different Texinfo files.  In Texinfo, nodes are the places to
+which cross references can refer.
+
+* Menu:
+
+* References::                  What cross references are for.
+* Cross Reference Commands::    A summary of the different commands.
+* Cross Reference Parts::       A cross reference has several parts.
+* xref::                        Begin a reference with `See' ...
+* Top Node Naming::             How to refer to the beginning of another file.
+* ref::                         A reference for the last part of a sentence.
+* pxref::                       How to write a parenthetical cross reference.
+* inforef::                     How to refer to an Info-only file.
+* uref::                        How to refer to a uniform resource locator.
+
+\1f
+File: texinfo.info,  Node: References,  Next: Cross Reference Commands,  Prev: Cross References,  Up: Cross References
+
+What References Are For
+=======================
+
+  Often, but not always, a printed document should be designed so that
+it can be read sequentially.  People tire of flipping back and forth to
+find information that should be presented to them as they need it.
+
+  However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information.  Also, an on-line help system or a
+reference manual is not like a novel; few read such documents in
+sequence from beginning to end.  Instead, people look up what they
+need.  For this reason, such creations should contain many cross
+references to help readers find other information that they may not
+have read.
+
+  In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that manual.
+
+  In Info, a cross reference results in an entry that you can follow
+using the Info `f' command.  (*note Some advanced Info commands:
+(info)Help-Adv.)
+
+  The various cross reference commands use nodes to define cross
+reference locations.  This is evident in Info, in which a cross
+reference takes you to the specified node.  TeX also uses nodes to
+define cross reference locations, but the action is less obvious.  When
+TeX generates a DVI file, it records nodes' page numbers and uses the
+page numbers in making references.  Thus, if you are writing a manual
+that will only be printed, and will not be used on-line, you must
+nonetheless write `@node' lines to name the places to which you make
+cross references.
+
+\1f
+File: texinfo.info,  Node: Cross Reference Commands,  Next: Cross Reference Parts,  Prev: References,  Up: Cross References
+
+Different Cross Reference Commands
+==================================
+
+There are four different cross reference commands:
+
+`@xref'
+     Used to start a sentence in the printed manual saying `See ...'
+     or an Info cross-reference saying `*Note NAME: NODE.'.
+
+`@ref'
+     Used within or, more often, at the end of a sentence; same as
+     `@xref' for Info; produces just the reference in the printed
+     manual without a preceding `See'.
+
+`@pxref'
+     Used within parentheses to make a reference that suits both an Info
+     file and a printed book.  Starts with a lower case `see' within the
+     printed manual. (`p' is for `parenthesis'.)
+
+`@inforef'
+     Used to make a reference to an Info file for which there is no
+     printed manual.
+
+(The `@cite' command is used to make references to books and manuals
+for which there is no corresponding Info file and, therefore, no node
+to which to point.   *Note `@cite': cite.)
+
+\1f
+File: texinfo.info,  Node: Cross Reference Parts,  Next: xref,  Prev: Cross Reference Commands,  Up: Cross References
+
+Parts of a Cross Reference
+==========================
+
+A cross reference command requires only one argument, which is the name
+of the node to which it refers.  But a cross reference command may
+contain up to four additional arguments.  By using these arguments, you
+can provide a cross reference name for Info, a topic description or
+section title for the printed output, the name of a different Info
+file, and the name of a different printed manual.
+
+  Here is a simple cross reference example:
+
+     @xref{Node name}.
+
+which produces
+
+     *Note Node name::.
+
+and
+
+     See Section NNN [Node name], page PPP.
+
+  Here is an example of a full five-part cross reference:
+
+     @xref{Node name, Cross Reference Name, Particular Topic,
+     info-file-name, A Printed Manual}, for details.
+
+which produces
+
+     *Note Cross Reference Name: (info-file-name)Node name,
+     for details.
+
+in Info and
+
+     See section "Particular Topic" in A Printed Manual, for details.
+
+in a printed book.
+
+  The five possible arguments for a cross reference are:
+
+  1. The node name (required).  This is the node to which the cross
+     reference takes you.  In a printed document, the location of the
+     node provides the page reference only for references within the
+     same document.
+
+  2. The cross reference name for the Info reference, if it is to be
+     different from the node name.  If you include this argument, it
+     becomes the first part of the cross reference.  It is usually
+     omitted.
+
+  3. A topic description or section name.  Often, this is the title of
+     the section.  This is used as the name of the reference in the
+     printed manual.  If omitted, the node name is used.
+
+  4. The name of the Info file in which the reference is located, if it
+     is different from the current file.  You need not include any
+     `.info' suffix on the file name, since Info readers try appending
+     it automatically.
+
+  5. The name of a printed manual from a different Texinfo file.
+
+  The template for a full five argument cross reference looks like this:
+
+     @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+     INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+  Cross references with one, two, three, four, and five arguments are
+described separately following the description of `@xref'.
+
+  Write a node name in a cross reference in exactly the same way as in
+the `@node' line, including the same capitalization; otherwise, the
+formatters may not find the reference.
+
+  You can write cross reference commands within a paragraph, but note
+how Info and TeX format the output of each of the various commands:
+write `@xref' at the beginning of a sentence; write `@pxref' only
+within parentheses, and so on.
+
+\1f
+File: texinfo.info,  Node: xref,  Next: Top Node Naming,  Prev: Cross Reference Parts,  Up: Cross References
+
+`@xref'
+=======
+
+The `@xref' command generates a cross reference for the beginning of a
+sentence.  The Info formatting commands convert it into an Info cross
+reference, which the Info `f' command can use to bring you directly to
+another node.  The TeX typesetting commands convert it into a page
+reference, or a reference to another book or manual.
+
+* Menu:
+
+* Reference Syntax::            What a reference looks like and requires.
+* One Argument::                `@xref' with one argument.
+* Two Arguments::               `@xref' with two arguments.
+* Three Arguments::             `@xref' with three arguments.
+* Four and Five Arguments::     `@xref' with four and five arguments.
+
+\1f
+File: texinfo.info,  Node: Reference Syntax,  Next: One Argument,  Prev: xref,  Up: xref
+
+What a Reference Looks Like and Requires
+----------------------------------------
+
+  Most often, an Info cross reference looks like this:
+
+     *Note NODE-NAME::.
+
+or like this
+
+     *Note CROSS-REFERENCE-NAME: NODE-NAME.
+
+In TeX, a cross reference looks like this:
+
+     See Section SECTION-NUMBER [NODE-NAME], page PAGE.
+
+or like this
+
+     See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
+
+  The `@xref' command does not generate a period or comma to end the
+cross reference in either the Info file or the printed output.  You
+must write that period or comma yourself; otherwise, Info will not
+recognize the end of the reference.  (The `@pxref' command works
+differently.  *Note `@pxref': pxref.)
+
+     *Please note:* A period or comma *must* follow the closing brace
+     of an `@xref'.  It is required to terminate the cross reference.
+     This period or comma will appear in the output, both in the Info
+     file and in the printed manual.
+
+  `@xref' must refer to an Info node by name.  Use `@node' to define
+the node (*note Writing a Node::).
+
+  `@xref' is followed by several arguments inside braces, separated by
+commas.  Whitespace before and after these commas is ignored.
+
+  A cross reference requires only the name of a node; but it may contain
+up to four additional arguments.  Each of these variations produces a
+cross reference that looks somewhat different.
+
+     *Please note:* Commas separate arguments in a cross reference;
+     avoid including them in the title or other part lest the formatters
+     mistake them for separators.
+
+\1f
+File: texinfo.info,  Node: One Argument,  Next: Two Arguments,  Prev: Reference Syntax,  Up: xref
+
+`@xref' with One Argument
+-------------------------
+
+The simplest form of `@xref' takes one argument, the name of another
+node in the same Info file.    The Info formatters produce output that
+the Info readers can use to jump to the reference; TeX produces output
+that specifies the page and section number for you.
+
+For example,
+
+     @xref{Tropical Storms}.
+
+produces
+
+     *Note Tropical Storms::.
+
+and
+
+     See Section 3.1 [Tropical Storms], page 24.
+
+(Note that in the preceding example the closing brace is followed by a
+period.)
+
+  You can write a clause after the cross reference, like this:
+
+     @xref{Tropical Storms}, for more info.
+
+which produces
+
+     *Note Tropical Storms::, for more info.
+
+     See Section 3.1 [Tropical Storms], page 24, for more info.
+
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+\1f
+File: texinfo.info,  Node: Two Arguments,  Next: Three Arguments,  Prev: One Argument,  Up: xref
+
+`@xref' with Two Arguments
+--------------------------
+
+With two arguments, the second is used as the name of the Info cross
+reference, while the first is still the name of the node to which the
+cross reference points.
+
+The template is like this:
+
+     @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
+
+For example,
+
+     @xref{Electrical Effects, Lightning}.
+
+produces:
+
+     *Note Lightning: Electrical Effects.
+
+and
+
+     See Section 5.2 [Electrical Effects], page 57.
+
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference
+name.)
+
+  You can write a clause after the cross reference, like this:
+
+     @xref{Electrical Effects, Lightning}, for more info.
+
+which produces
+     *Note Lightning: Electrical Effects, for more info.
+
+and
+
+     See Section 5.2 [Electrical Effects], page 57, for more info.
+
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+\1f
+File: texinfo.info,  Node: Three Arguments,  Next: Four and Five Arguments,  Prev: Two Arguments,  Up: xref
+
+`@xref' with Three Arguments
+----------------------------
+
+A third argument replaces the node name in the TeX output.  The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section.  Often, you will want to
+use initial upper case letters so it will be easier to read when the
+reference is printed.  Use a third argument when the node name is
+unsuitable because of syntax or meaning.
+
+  Remember to avoid placing a comma within the title or topic section of
+a cross reference, or within any other section.  The formatters divide
+cross references into arguments according to the commas; a comma within
+a title or other section will divide it into two arguments.  In a
+reference, you need to write a title such as "Clouds, Mist, and Fog"
+without the commas.
+
+  Also, remember to write a comma or period after the closing brace of a
+`@xref' to terminate the cross reference.  In the following examples, a
+clause follows a terminating comma.
+
+The template is like this:
+
+     @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
+
+For example,
+
+     @xref{Electrical Effects, Lightning, Thunder and Lightning},
+     for details.
+
+produces
+
+     *Note Lightning: Electrical Effects, for details.
+
+and
+
+     See Section 5.2 [Thunder and Lightning], page 57, for details.
+
+  If a third argument is given and the second one is empty, then the
+third argument serves both.  (Note how two commas, side by side, mark
+the empty second argument.)
+
+     @xref{Electrical Effects, , Thunder and Lightning},
+     for details.
+
+produces
+
+     *Note Thunder and Lightning: Electrical Effects, for details.
+
+and
+
+     See Section 5.2 [Thunder and Lightning], page 57, for details.
+
+  As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same, and with the first and third arguments if the node name and title
+are different.
+
+  Here are several examples from `The GNU Awk User's Guide':
+
+     @xref{Sample Program}.
+     @xref{Glossary}.
+     @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
+     @xref{Close Output, , Closing Output Files and Pipes},
+        for more information.
+     @xref{Regexp, , Regular Expressions as Patterns}.
+
+\1f
+File: texinfo.info,  Node: Four and Five Arguments,  Prev: Three Arguments,  Up: xref
+
+`@xref' with Four and Five Arguments
+------------------------------------
+
+In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed manual.
+
+  Remember that a comma or period must follow the closing brace of an
+`@xref' command to terminate the cross reference.  In the following
+examples, a clause follows a terminating comma.
+
+The template is:
+
+     @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+     INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+For example,
+
+     @xref{Electrical Effects, Lightning, Thunder and Lightning,
+     weather, An Introduction to Meteorology}, for details.
+
+produces
+
+     *Note Lightning: (weather)Electrical Effects, for details.
+
+The name of the Info file is enclosed in parentheses and precedes the
+name of the node.
+
+In a printed manual, the reference looks like this:
+
+     See section "Thunder and Lightning" in An Introduction to
+     Meteorology, for details.
+
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since TeX cannot know to which page a
+reference refers when that reference is to another manual.
+
+  Often, you will leave out the second argument when you use the long
+version of `@xref'.  In this case, the third argument, the topic
+description, will be used as the cross reference name in Info.
+
+The template looks like this:
+
+     @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
+     PRINTED-MANUAL-TITLE}, for details.
+
+which produces
+
+     *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
+
+and
+
+     See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
+
+For example,
+
+     @xref{Electrical Effects, , Thunder and Lightning,
+     weather, An Introduction to Meteorology}, for details.
+
+produces
+
+     *Note Thunder and Lightning: (weather)Electrical Effects,
+     for details.
+
+and
+
+     See section "Thunder and Lightning" in An Introduction to
+     Meteorology, for details.
+
+  On rare occasions, you may want to refer to another Info file that is
+within a single printed manual--when multiple Texinfo files are
+incorporated into the same TeX run but make separate Info files.  In
+this case, you need to specify only the fourth argument, and not the
+fifth.
+
+\1f
+File: texinfo.info,  Node: Top Node Naming,  Next: ref,  Prev: xref,  Up: Cross References
+
+Naming a `Top' Node
+===================
+
+In a cross reference, you must always name a node.  This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the `@xref' command.  (This is
+different from the way you write a menu entry; see *Note Referring to
+Other Info Files: Other Info Files.)  At the same time, to provide a
+meaningful section topic or title in the printed cross reference
+(instead of the word `Top'), you must write an appropriate entry for
+the third argument to the `@xref' command.
+
+Thus, to make a cross reference to `The GNU Make Manual', write:
+
+     @xref{Top, , Overview, make, The GNU Make Manual}.
+
+which produces
+
+     *Note Overview: (make)Top.
+
+and
+
+     See section "Overview" in The GNU Make Manual.
+
+In this example, `Top' is the name of the first node, and `Overview' is
+the name of the first section of the manual.
+
+\1f
+File: texinfo.info,  Node: ref,  Next: pxref,  Prev: Top Node Naming,  Up: Cross References
+
+`@ref'
+======
+
+`@ref' is nearly the same as `@xref' except that it does not generate a
+`See' in the printed output, just the reference itself.  This makes it
+useful as the last part of a sentence.
+
+For example,
+
+     For more information, see @ref{Hurricanes}.
+
+produces
+
+     For more information, see *Note Hurricanes::.
+
+and
+
+     For more information, see Section 8.2 [Hurricanes], page 123.
+
+  The `@ref' command sometimes leads writers to express themselves in a
+manner that is suitable for a printed manual but looks awkward in the
+Info format.  Bear in mind that your audience will be using both the
+printed and the Info format.
+
+For example,
+
+     Sea surges are described in @ref{Hurricanes}.
+
+produces
+
+     Sea surges are described in Section 6.7 [Hurricanes], page 72.
+
+in a printed document, and the following in Info:
+
+     Sea surges are described in *Note Hurricanes::.
+
+     *Caution:* You _must_ write a period or comma immediately after an
+     `@ref' command with two or more arguments.  Otherwise, Info will
+     not find the end of the cross reference entry and its attempt to
+     follow the cross reference will fail.  As a general rule, you
+     should write a period or comma after every `@ref' command.  This
+     looks best in both the printed and the Info output.
+
+\1f
+File: texinfo.info,  Node: pxref,  Next: inforef,  Prev: ref,  Up: Cross References
+
+`@pxref'
+========
+
+The parenthetical reference command, `@pxref', is nearly the same as
+`@xref', but you use it _only_ inside parentheses and you do _not_ type
+a comma or period after the command's closing brace.  The command
+differs from `@xref' in two ways:
+
+  1. TeX typesets the reference for the printed manual with a lower case
+     `see' rather than an upper case `See'.
+
+  2. The Info formatting commands automatically end the reference with a
+     closing colon or period.
+
+  Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use `@pxref' _only_
+inside parentheses as part of another sentence.  Also, you yourself
+should not insert punctuation after the reference, as you do with
+`@xref'.
+
+  `@pxref' is designed so that the output looks right and works right
+between parentheses both in printed output and in an Info file.  In a
+printed manual, a closing comma or period should not follow a cross
+reference within parentheses; such punctuation is wrong.  But in an
+Info file, suitable closing punctuation must follow the cross reference
+so Info can recognize its end.  `@pxref' spares you the need to use
+complicated methods to put a terminator into one form of the output and
+not the other.
+
+With one argument, a parenthetical cross reference looks like this:
+
+     ... storms cause flooding (@pxref{Hurricanes}) ...
+
+which produces
+
+     ... storms cause flooding (*Note Hurricanes::) ...
+
+and
+
+     ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
+     ...
+
+  With two arguments, a parenthetical cross reference has this template:
+
+     ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
+
+which produces
+
+     ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
+
+and
+
+     ... (see Section NNN [NODE-NAME], page PPP) ...
+
+  `@pxref' can be used with up to five arguments just like `@xref'
+(*note `@xref': xref.).
+
+     *Please note:* Use `@pxref' only as a parenthetical reference.  Do
+     not try to use `@pxref' as a clause in a sentence.  It will look
+     bad in either the Info file, the printed output, or both.
+
+     Also, parenthetical cross references look best at the ends of
+     sentences.  Although you may write them in the middle of a
+     sentence, that location breaks up the flow of text.
+
+\1f
+File: texinfo.info,  Node: inforef,  Next: uref,  Prev: pxref,  Up: Cross References
+
+`@inforef'
+==========
+
+`@inforef' is used for cross references to Info files for which there
+are no printed manuals.  Even in a printed manual, `@inforef' generates
+a reference directing the user to look in an Info file.
+
+  The command takes either two or three arguments, in the following
+order:
+
+  1. The node name.
+
+  2. The cross reference name (optional).
+
+  3. The Info file name.
+
+Separate the arguments with commas, as with `@xref'.  Also, you must
+terminate the reference with a comma or period after the `}', as you do
+with `@xref'.
+
+The template is:
+
+     @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
+
+Thus,
+
+     @inforef{Expert, Advanced Info commands, info},
+     for more information.
+
+produces
+
+     *Note Advanced Info commands: (info)Expert,
+     for more information.
+
+and
+
+     See Info file `info', node `Expert', for more information.
+
+Similarly,
+
+     @inforef{Expert, , info}, for more information.
+
+produces
+
+     *Note (info)Expert::, for more information.
+
+and
+
+     See Info file `info', node `Expert', for more information.
+
+  The converse of `@inforef' is `@cite', which is used to refer to
+printed works for which no Info form exists.  *Note `@cite': cite.
+
+\1f
+File: texinfo.info,  Node: uref,  Prev: inforef,  Up: Cross References
+
+`@uref{URL[, DISPLAYED-TEXT]}'
+==============================
+
+`@uref' produces a reference to a uniform resource locator (URL).  It
+takes one mandatory argument, the URL, and one optional argument, the
+text to display (the default is the URL itself).  In HTML output,
+`@uref' produces a link you can follow.  For example:
+
+     The official GNU ftp site is
+     @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
+
+produces (in text):
+     The official GNU ftp site is
+     `ftp://ftp.gnu.ai.mit.edu/pub/gnu'
+
+whereas
+     The official
+     @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
+       GNU ftp site} holds programs and texts.
+
+produces (in text):
+     The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds
+     programs and texts.
+
+and (in HTML):
+     The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
+     site</A> holds programs and texts.
+
+  To merely indicate a URL, use `@url' (*note `@url': url.).
+
+\1f
+File: texinfo.info,  Node: Marking Text,  Next: Quotations and Examples,  Prev: Cross References,  Up: Top
+
+Marking Words and Phrases
+*************************
+
+In Texinfo, you can mark words and phrases in a variety of ways.  The
+Texinfo formatters use this information to determine how to highlight
+the text.  You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program.  Also, you can emphasize text.
+
+* Menu:
+
+* Indicating::                  How to indicate definitions, files, etc.
+* Emphasis::                    How to emphasize text.
+
+\1f
+File: texinfo.info,  Node: Indicating,  Next: Emphasis,  Prev: Marking Text,  Up: Marking Text
+
+Indicating Definitions, Commands, etc.
+======================================
+
+Texinfo has commands for indicating just what kind of object a piece of
+text refers to.  For example, metasyntactic variables are marked by
+`@var', and code by `@code'.  Since the pieces of text are labelled by
+commands that tell what kind of object they are, it is easy to change
+the way the Texinfo formatters prepare such text.  (Texinfo is an
+_intentional_ formatting language rather than a _typesetting_
+formatting language.)
+
+  For example, in a printed manual, code is usually illustrated in a
+typewriter font; `@code' tells TeX to typeset this text in this font.
+But it would be easy to change the way TeX highlights code to use
+another font, and this change would not effect how keystroke examples
+are highlighted.  If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be changed.
+
+* Menu:
+
+* Useful Highlighting::         Highlighting provides useful information.
+* code::                        How to indicate code.
+* kbd::                         How to show keyboard input.
+* key::                         How to specify keys.
+* samp::                        How to show a literal sequence of characters.
+* var::                         How to indicate a metasyntactic variable.
+* file::                        How to indicate the name of a file.
+* dfn::                         How to specify a definition.
+* cite::                        How to refer to a book that is not in Info.
+* url::                         How to indicate a world wide web reference.
+* email::                       How to indicate an electronic mail address.
+
+\1f
+File: texinfo.info,  Node: Useful Highlighting,  Next: code,  Prev: Indicating,  Up: Indicating
+
+Highlighting Commands are Useful
+--------------------------------
+
+  The highlighting commands can be used to generate useful information
+from the file, such as lists of functions or file names.  It is
+possible, for example, to write a program in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+words or phrases marked by a specified command.  You could do this to
+construct an index of functions if you had not already made the entries.
+
+  The commands serve a variety of purposes:
+
+`@code{SAMPLE-CODE}'
+     Indicate text that is a literal example of a piece of a program.
+
+`@kbd{KEYBOARD-CHARACTERS}'
+     Indicate keyboard input.
+
+`@key{KEY-NAME}'
+     Indicate the conventional name for a key on a keyboard.
+
+`@samp{TEXT}'
+     Indicate text that is a literal example of a sequence of
+     characters.
+
+`@var{METASYNTACTIC-VARIABLE}'
+     Indicate a metasyntactic variable.
+
+`@url{UNIFORM-RESOURCE-LOCATOR}'
+     Indicate a uniform resource locator for the World Wide Web.
+
+`@file{FILE-NAME}'
+     Indicate the name of a file.
+
+`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
+     Indicate an electronic mail address.
+
+`@dfn{TERM}'
+     Indicate the introductory or defining use of a term.
+
+`@cite{REFERENCE}'
+     Indicate the name of a book.
+
+
+\1f
+File: texinfo.info,  Node: code,  Next: kbd,  Prev: Useful Highlighting,  Up: Indicating
+
+`@code'{SAMPLE-CODE}
+--------------------
+
+Use the `@code' command to indicate text that is a piece of a program
+and which consists of entire syntactic tokens.  Enclose the text in
+braces.
+
+  Thus, you should use `@code' for an expression in a program, for the
+name of a variable or function used in a program, or for a keyword.
+Also, you should use `@code' for the name of a program, such as `diff',
+that is a name used in the machine. (You should write the name of a
+program in the ordinary text font if you regard it as a new English
+word, such as `Emacs' or `Bison'.)
+
+  Use `@code' for environment variables such as `TEXINPUTS', and other
+variables.
+
+  Use `@code' for command names in command languages that resemble
+programming languages, such as Texinfo or the shell.  For example,
+`@code' and `@samp' are produced by writing `@code{@@code}' and
+`@code{@@samp}' in the Texinfo source, respectively.
+
+  Note, however, that you should not use `@code' for shell options such
+as `-c' when such options stand alone. (Use `@samp'.)  Also, an entire
+shell command often looks better if written using `@samp' rather than
+`@code'.  In this case, the rule is to choose the more pleasing format.
+
+  It is incorrect to alter the case of a word inside an `@code' command
+when it appears at the beginning of a sentence.  Most computer
+languages are case sensitive.  In C, for example, `Printf' is different
+from the identifier `printf', and most likely is a misspelling of it.
+Even in languages which are not case sensitive, it is confusing to a
+human reader to see identifiers spelled in different ways.  Pick one
+spelling and always use that.  If you do not want to start a sentence
+with a command written all in lower case, you should rearrange the
+sentence.
+
+  Do not use the `@code' command for a string of characters shorter
+than a syntactic token.  If you are writing about `TEXINPU', which is
+just a part of the name for the `TEXINPUTS' environment variable, you
+should use `@samp'.
+
+  In particular, you should not use the `@code' command when writing
+about the characters used in a token; do not, for example, use `@code'
+when you are explaining what letters or printable symbols can be used
+in the names of functions.  (Use `@samp'.)  Also, you should not use
+`@code' to mark text that is considered input to programs unless the
+input is written in a language that is like a programming language.
+For example, you should not use `@code' for the keystroke commands of
+GNU Emacs (use `@kbd' instead) although you may use `@code' for the
+names of the Emacs Lisp functions that the keystroke commands invoke.
+
+  In the printed manual, `@code' causes TeX to typeset the argument in
+a typewriter face.  In the Info file, it causes the Info formatting
+commands to use single quotation marks around the text.
+
+  For example,
+
+     Use @code{diff} to compare two files.
+
+produces this in the printed manual:
+
+     Use `diff' to compare two files.
+
+\1f
+File: texinfo.info,  Node: kbd,  Next: key,  Prev: code,  Up: Indicating
+
+`@kbd'{KEYBOARD-CHARACTERS}
+---------------------------
+
+Use the `@kbd' command for characters of input to be typed by users.
+For example, to refer to the characters `M-a', write
+
+     @kbd{M-a}
+
+and to refer to the characters `M-x shell', write
+
+     @kbd{M-x shell}
+
+  The `@kbd' command has the same effect as `@code' in Info, but by
+default produces a different font (slanted typewriter instead of normal
+typewriter) in the printed manual, so users can distinguish the
+characters they are supposed to type from those the computer outputs.
+
+  Since the usage of `@kbd' varies from manual to manual, you can
+control the font switching with the `@kbdinputstyle' command.  This
+command has no effect on Info output.  Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
+`code'
+     Always use the same font for `@kbd' as `@code'.
+
+`example'
+     Use the distinguishing font for `@kbd' only in `@example' and
+     similar environments.
+
+`example'
+     (the default) Always use the distinguishing font for `@kbd'.
+
+  You can embed another @-command inside the braces of an `@kbd'
+command.  Here, for example, is the way to describe a command that
+would be described more verbosely as "press an `r' and then press the
+<RET> key":
+
+     @kbd{r @key{RET}}
+
+This produces: `r <RET>'
+
+  You also use the `@kbd' command if you are spelling out the letters
+you type; for example:
+
+     To give the @code{logout} command,
+     type the characters @kbd{l o g o u t @key{RET}}.
+
+This produces:
+
+     To give the `logout' command, type the characters `l o g o u t
+     <RET>'.
+
+  (Also, this example shows that you can add spaces for clarity.  If you
+really want to mention a space character as one of the characters of
+input, write `@key{SPC}' for it.)
+
+\1f
+File: texinfo.info,  Node: key,  Next: samp,  Prev: kbd,  Up: Indicating
+
+`@key'{KEY-NAME}
+----------------
+
+Use the `@key' command for the conventional name for a key on a
+keyboard, as in:
+
+     @key{RET}
+
+  You can use the `@key' command within the argument of an `@kbd'
+command when the sequence of characters to be typed includes one or
+more keys that are described by name.
+
+  For example, to produce `C-x <ESC>' you would type:
+
+     @kbd{C-x @key{ESC}}
+
+  Here is a list of the recommended names for keys:
+
+    SPC
+          Space
+
+    RET
+          Return
+
+    LFD
+          Linefeed (however, since most keyboards nowadays do not have
+          a Linefeed key, it might be better to call this character
+          `C-j'.
+
+    TAB
+          Tab
+
+    BS
+          Backspace
+
+    ESC
+          Escape
+
+    DEL
+          Delete
+
+    SHIFT
+          Shift
+
+    CTRL
+          Control
+
+    META
+          Meta
+
+  There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys.  When mentioning a character in which the
+modifier key is used, such as `Meta-a', use the `@kbd' command alone;
+do not use the `@key' command; but when you are referring to the
+modifier key in isolation, use the `@key' command.  For example, write
+`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.
+
+\1f
+File: texinfo.info,  Node: samp,  Next: var,  Prev: key,  Up: Indicating
+
+`@samp'{TEXT}
+-------------
+
+Use the `@samp' command to indicate text that is a literal example or
+`sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces.  The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width font.
+
+     To match @samp{foo} at the end of the line,
+     use the regexp @samp{foo$}.
+
+produces
+
+     To match `foo' at the end of the line, use the regexp `foo$'.
+
+  Any time you are referring to single characters, you should use
+`@samp' unless `@kbd' or `@key' is more appropriate.  Use `@samp' for
+the names of command-line options (except in an `@table', where `@code'
+seems to read more easily).  Also, you may use `@samp' for entire
+statements in C and for entire shell commands--in this case, `@samp'
+often looks better than `@code'.  Basically, `@samp' is a catchall for
+whatever is not covered by `@code', `@kbd', or `@key'.
+
+  Only include punctuation marks within braces if they are part of the
+string you are specifying.  Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string.  In the following sentence, for example, the commas and
+period are outside of the braces:
+
+     In English, the vowels are @samp{a}, @samp{e},
+     @samp{i}, @samp{o}, @samp{u}, and sometimes
+     @samp{y}.
+
+This produces:
+
+     In English, the vowels are `a', `e', `i', `o', `u',  and sometimes
+     `y'.
+
+\1f
+File: texinfo.info,  Node: var,  Next: file,  Prev: samp,  Up: Indicating
+
+`@var'{METASYNTACTIC-VARIABLE}
+------------------------------
+
+Use the `@var' command to indicate metasyntactic variables.  A
+"metasyntactic variable" is something that stands for another piece of
+text.  For example, you should use a metasyntactic variable in the
+documentation of a function to describe the arguments that are passed
+to that function.
+
+  Do not use `@var' for the names of particular variables in
+programming languages.  These are specific names from a program, so
+`@code' is correct for them.  For example, the Emacs Lisp variable
+`texinfo-tex-command' is not a metasyntactic variable; it is properly
+formatted using `@code'.
+
+  The effect of `@var' in the Info file is to change the case of the
+argument to all upper case; in the printed manual, to italicize it.
+
+  For example,
+
+     To delete file @var{filename},
+     type @code{rm @var{filename}}.
+
+produces
+
+     To delete file FILENAME, type `rm FILENAME'.
+
+(Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
+
+  Write a metasyntactic variable all in lower case without spaces, and
+use hyphens to make it more readable.  Thus, the Texinfo source for the
+illustration of how to begin a Texinfo manual looks like this:
+
+     \input texinfo
+     @@setfilename @var{info-file-name}
+     @@settitle @var{name-of-manual}
+
+This produces:
+
+     \input texinfo
+     @setfilename INFO-FILE-NAME
+     @settitle NAME-OF-MANUAL
+
+  In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:
+
+     ..., type rm <filename>
+
+However, that is not the style that Texinfo uses.  (You can, of course,
+modify the sources to TeX and the Info formatting commands to output
+the `<...>' format if you wish.)
+
+\1f
+File: texinfo.info,  Node: file,  Next: dfn,  Prev: var,  Up: Indicating
+
+`@file'{FILE-NAME}
+------------------
+
+Use the `@file' command to indicate text that is the name of a file,
+buffer, or directory, or is the name of a node in Info.  You can also
+use the command for file name suffixes.  Do not use `@file' for symbols
+in a programming language; use `@code'.
+
+  Currently, `@file' is equivalent to `@samp' in its effects.  For
+example,
+
+     The @file{.el} files are in
+     the @file{/usr/local/emacs/lisp} directory.
+
+produces
+
+     The `.el' files are in the `/usr/local/emacs/lisp' directory.
+
+\1f
+File: texinfo.info,  Node: dfn,  Next: cite,  Prev: file,  Up: Indicating
+
+`@dfn'{TERM}
+------------
+
+Use the `@dfn' command to identify the introductory or defining use of
+a technical term.  Use the command only in passages whose purpose is to
+introduce a term which will be used again or which the reader ought to
+know.  Mere passing mention of a term for the first time does not
+deserve `@dfn'.  The command generates italics in the printed manual,
+and double quotation marks in the Info file.  For example:
+
+     Getting rid of a file is called @dfn{deleting} it.
+
+produces
+
+     Getting rid of a file is called "deleting" it.
+
+  As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term.  The sentence does not need to
+say explicitly that it is a definition, but it should contain the
+information of a definition--it should make the meaning clear.
+
+\1f
+File: texinfo.info,  Node: cite,  Next: url,  Prev: dfn,  Up: Indicating
+
+`@cite'{REFERENCE}
+------------------
+
+Use the `@cite' command for the name of a book that lacks a companion
+Info file. The command produces italics in the printed manual, and
+quotation marks in the Info file.
+
+  (If a book is written in Texinfo, it is better to use a cross
+reference command since a reader can easily follow such a reference in
+Info.  *Note `@xref': xref.)
+
+\1f
+File: texinfo.info,  Node: url,  Next: email,  Prev: cite,  Up: Indicating
+
+`@url'{UNIFORM-RESOURCE-LOCATOR}
+--------------------------------
+
+Use the `@url' to indicate a uniform resource locator on the World Wide
+Web.  This is analogous to `@file', `@var', etc., and is purely for
+markup purposes.  It does not produce a link you can follow in HTML
+output (the `@uref' command does, *note `@uref': uref.).  It is useful
+for example URL's which do not actually exist.  For example:
+
+     For example, the url might be
+     @url{http://host.domain.org/path}.
+
+\1f
+File: texinfo.info,  Node: email,  Prev: url,  Up: Indicating
+
+`@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
+-----------------------------------------
+
+Use the `@email' command to indicate an electronic mail address.  It
+takes one mandatory argument, the address, and one optional argument,
+the text to display (the default is the address itself).
+
+  In Info and TeX, the address is shown in angle brackets, preceded by
+the text to display if any.  In HTML output, `@email' produces a
+`mailto' link that usually brings up a mail composition window.  For
+example:
+
+     Send bug reports to @email{bug-texinfo@@gnu.org}.
+     Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
+
+produces
+     Send bug reports to <bug-texinfo@gnu.org>.
+     Send suggestions to the same place <bug-texinfo@gnu.org>.
+
+\1f
+File: texinfo.info,  Node: Emphasis,  Prev: Indicating,  Up: Marking Text
+
+Emphasizing Text
+================
+
+Usually, Texinfo changes the font to mark words in the text according to
+what category the words belong to; an example is the `@code' command.
+Most often, this is the best way to mark words.  However, sometimes you
+will want to emphasize text without indicating a category.  Texinfo has
+two commands to do this.  Also, Texinfo has several commands that
+specify the font in which TeX will typeset text.  These commands have
+no affect on Info and only one of them, the `@r' command, has any
+regular use.
+
+* Menu:
+
+* emph & strong::               How to emphasize text in Texinfo.
+* Smallcaps::                   How to use the small caps font.
+* Fonts::                       Various font commands for printed output.
+* Customized Highlighting::     How to define highlighting commands.
+
+\1f
+File: texinfo.info,  Node: emph & strong,  Next: Smallcaps,  Prev: Emphasis,  Up: Emphasis
+
+`@emph'{TEXT} and `@strong'{TEXT}
+---------------------------------
+
+The `@emph' and `@strong' commands are for emphasis; `@strong' is
+stronger.  In printed output, `@emph' produces _italics_ and `@strong'
+produces *bold*.
+
+  For example,
+
+     @quotation
+     @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
+     files in the directory.
+     @end quotation
+
+produces:
+
+          *Caution*: `rm * .[^.]*' removes *all*
+          files in the directory.
+
+  The `@strong' command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
+  In the Info file, both `@emph' and `@strong' put asterisks around the
+text.
+
+     *Caution:* Do not use `@emph' or `@strong' with the word `Note';
+     Info will mistake the combination for a cross reference.  Use a
+     phrase such as *Please note* or *Caution* instead.
+
+\1f
+File: texinfo.info,  Node: Smallcaps,  Next: Fonts,  Prev: emph & strong,  Up: Emphasis
+
+`@sc'{TEXT}: The Small Caps Font
+--------------------------------
+
+Use the `@sc' command to set text in the printed output in a small caps
+font and set text in the Info file in upper case letters.
+
+Write the text between braces in lower case, like this:
+
+     The @sc{acm} and @sc{ieee} are technical societies.
+
+This produces:
+
+     The ACM and IEEE are technical societies.
+
+  TeX typesets the small caps font in a manner that prevents the
+letters from `jumping out at you on the page'.  This makes small caps
+text easier to read than text in all upper case.  The Info formatting
+commands set all small caps text in upper case.
+
+  If the text between the braces of an `@sc' command is upper case, TeX
+typesets in full-size capitals.  Use full-size capitals sparingly.
+
+  You may also use the small caps font for a jargon word such as ATO (a
+NASA word meaning `abort to orbit').
+
+  There are subtleties to using the small caps font with a jargon word
+such as CDR, a word used in Lisp programming.  In this case, you should
+use the small caps font when the word refers to the second and
+subsequent elements of a list (the CDR of the list), but you should use
+`@code' when the word refers to the Lisp function of the same spelling.
+
+\1f
+File: texinfo.info,  Node: Fonts,  Next: Customized Highlighting,  Prev: Smallcaps,  Up: Emphasis
+
+Fonts for Printing, Not Info
+----------------------------
+
+Texinfo provides four font commands that specify font changes in the
+printed manual but have no effect in the Info file.  `@i' requests
+italic font (in some versions of TeX, a slanted font is used), `@b'
+requests bold face, `@t' requests the fixed-width, typewriter-style
+font used by `@code', and `@r' requests a roman font, which is the
+usual font in which text is printed.  All four commands apply to an
+argument that follows, surrounded by braces.
+
+  Only the `@r' command has much use: in example programs, you can use
+the `@r' command to convert code comments from the fixed-width font to
+a roman font.  This looks better in printed output.
+
+  For example,
+
+     @lisp
+     (+ 2 2)    ; @r{Add two plus two.}
+     @end lisp
+
+produces
+
+     (+ 2 2)    ; Add two plus two.
+
+  If possible, you should avoid using the other three font commands.  If
+you need to use one, it probably indicates a gap in the Texinfo
+language.
+
+\1f
+File: texinfo.info,  Node: Customized Highlighting,  Prev: Fonts,  Up: Emphasis
+
+Customized Highlighting
+-----------------------
+
+You can use regular TeX commands inside of `@iftex' ...  `@end iftex'
+to create your own customized highlighting commands for Texinfo.  The
+easiest way to do this is to equate your customized commands with
+pre-existing commands, such as those for italics.  Such new commands
+work only with TeX.
+
+  You can use the `@definfoenclose' command inside of `@ifinfo' ...
+`@end ifinfo' to define commands for Info with the same names as new
+commands for TeX.  `@definfoenclose' creates new commands for Info that
+mark text by enclosing it in strings that precede and follow the text.
+(1) (*note Customized Highlighting-Footnote-1::)
+
+  Here is how to create a new @-command called `@phoo' that causes TeX
+to typeset its argument in italics and causes Info to display the
+argument between `//' and `\\'.
+
+  For TeX, write the following to equate the `@phoo' command with the
+existing `@i' italics command:
+
+     @iftex
+     @global@let@phoo=@i
+     @end iftex
+
+This defines `@phoo' as a command that causes TeX to typeset the
+argument to `@phoo' in italics.  `@global@let' tells TeX to equate the
+next argument with the argument that follows the equals sign.
+
+  For Info, write the following to tell the Info formatters to enclose
+the argument between `//' and `\\':
+
+     @ifinfo
+     @definfoenclose phoo, //, \\
+     @end ifinfo
+
+Write the `@definfoenclose' command on a line and follow it with three
+arguments separated by commas (commas are used as separators in an
+`@node' line in the same way).
+
+   * The first argument to `@definfoenclose' is the @-command name
+     *without* the `@';
+
+   * the second argument is the Info start delimiter string; and,
+
+   * the third argument is the Info end delimiter string.
+
+The latter two arguments enclose the highlighted text in the Info file.
+A delimiter string may contain spaces.  Neither the start nor end
+delimiter is required.  However, if you do not provide a start
+delimiter, you must follow the command name with two commas in a row;
+otherwise, the Info formatting commands will misinterpret the end
+delimiter string as a start delimiter string.
+
+  After you have defined `@phoo' both for TeX and for Info, you can
+then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
+italics in printed output.
+
+  Note that each definition applies to its own formatter: one for TeX,
+the other for Info.
+
+  Here is another example:
+
+     @ifinfo
+     @definfoenclose headword, , :
+     @end ifinfo
+     @iftex
+     @global@let@headword=@b
+     @end iftex
+
+This defines `@headword' as an Info formatting command that inserts
+nothing before and a colon after the argument and as a TeX formatting
+command to typeset its argument in bold.
+
+\1f
+File: texinfo.info,  Node: Customized Highlighting-Footnotes,  Up: Customized Highlighting
+
+  (1) Currently, `@definfoenclose' works only with
+`texinfo-format-buffer' and `texinfo-format-region', not with
+`makeinfo'.
+
+\1f
+File: texinfo.info,  Node: Quotations and Examples,  Next: Lists and Tables,  Prev: Marking Text,  Up: Top
+
+Quotations and Examples
+***********************
+
+Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and treated
+differently.  They are usually indented.
+
+  In Texinfo, you always begin a quotation or example by writing an
+@-command at the beginning of a line by itself, and end it by writing
+an `@end' command that is also at the beginning of a line by itself.
+For instance, you begin an example by writing `@example' by itself at
+the beginning of a line and end the example by writing `@end example'
+on a line by itself, at the beginning of that line.
+
+* Menu:
+
+* Block Enclosing Commands::    Use different constructs for
+                                  different purposes.
+* quotation::                   How to write a quotation.
+* example::                     How to write an example in a fixed-width font.
+* noindent::                    How to prevent paragraph indentation.
+* Lisp Example::                How to illustrate Lisp code.
+* smallexample & smalllisp::    Forms for the `@smallbook' option.
+* display::                     How to write an example in the current font.
+* format::                      How to write an example that does not narrow
+                                  the margins.
+* exdent::                      How to undo the indentation of a line.
+* flushleft & flushright::      How to push text flushleft or flushright.
+* cartouche::                   How to draw cartouches around examples.
+
+\1f
+File: texinfo.info,  Node: Block Enclosing Commands,  Next: quotation,  Prev: Quotations and Examples,  Up: Quotations and Examples
+
+The Block Enclosing Commands
+============================
+
+Here are commands for quotations and examples:
+
+`@quotation'
+     Indicate text that is quoted. The text is filled, indented, and
+     printed in a roman font by default.
+
+`@example'
+     Illustrate code, commands, and the like. The text is printed in a
+     fixed-width font, and indented but not filled.
+
+`@lisp'
+     Illustrate Lisp code. The text is printed in a fixed-width font,
+     and indented but not filled.
+
+`@smallexample'
+     Illustrate code, commands, and the like.  Similar to `@example',
+     except that in TeX this command typesets text in a smaller font
+     for the smaller `@smallbook' format than for the 8.5 by 11 inch
+     format.
+
+`@smalllisp'
+     Illustrate Lisp code.  Similar to `@lisp', except that in TeX this
+     command typesets text in a smaller font for the smaller
+     `@smallbook' format than for the 8.5 by 11 inch format.
+
+`@display'
+     Display illustrative text.  The text is indented but not filled,
+     and no font is specified (so, by default, the font is roman).
+
+`@format'
+     Print illustrative text.  The text is not indented and not filled
+     and no font is specified (so, by default, the font is roman).
+
+  The `@exdent' command is used within the above constructs to undo the
+indentation of a line.
+
+  The `@flushleft' and `@flushright' commands are used to line up the
+left or right margins of unfilled text.
+
+  The `@noindent' command may be used after one of the above constructs
+to prevent the following text from being indented as a new paragraph.
+
+  You can use the `@cartouche' command within one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it.  (The `@cartouche' command affects only the
+printed manual; it has no effect in the Info file; see *Note Drawing
+Cartouches Around Examples: cartouche.)
+
+\1f
+File: texinfo.info,  Node: quotation,  Next: example,  Prev: Block Enclosing Commands,  Up: Quotations and Examples
+
+`@quotation'
+============
+
+The text of a quotation is processed normally except that:
+
+   * the margins are closer to the center of the page, so the whole of
+     the quotation is indented;
+
+   * the first lines of paragraphs are indented no more than other
+     lines;
+
+   * in the printed output, interparagraph spacing is reduced.
+
+     This is an example of text written between an `@quotation' command
+     and an `@end quotation' command.  An `@quotation' command is most
+     often used to indicate text that is excerpted from another (real
+     or hypothetical) printed work.
+
+  Write an `@quotation' command as text on a line by itself.  This line
+will disappear from the output.  Mark the end of the quotation with a
+line beginning with and containing only `@end quotation'.  The `@end
+quotation' line will likewise disappear from the output.  Thus, the
+following,
+
+     @quotation
+     This is
+     a foo.
+     @end quotation
+
+produces
+
+     This is a foo.
+
+\1f
+File: texinfo.info,  Node: example,  Next: noindent,  Prev: quotation,  Up: Quotations and Examples
+
+`@example'
+==========
+
+The `@example' command is used to indicate an example that is not part
+of the running text, such as computer input or output.
+
+     This is an example of text written between an
+     `@example' command
+     and an `@end example' command.
+     The text is indented but not filled.
+     
+     In the printed manual, the text is typeset in a
+     fixed-width font, and extra spaces and blank lines are
+     significant.  In the Info file, an analogous result is
+     obtained by indenting each line with five spaces.
+
+  Write an `@example' command at the beginning of a line by itself.
+This line will disappear from the output.  Mark the end of the example
+with an `@end example' command, also written at the beginning of a line
+by itself.  The `@end example' will disappear from the output.
+
+  For example,
+
+     @example
+     mv foo bar
+     @end example
+
+produces
+
+     mv foo bar
+
+  Since the lines containing `@example' and `@end example' will
+disappear, you should put a blank line before the `@example' and
+another blank line after the `@end example'.  (Remember that blank
+lines between the beginning `@example' and the ending `@end example'
+will appear in the output.)
+
+     *Caution:* Do not use tabs in the lines of an example (or anywhere
+     else in Texinfo, for that matter)!  TeX treats tabs as single
+     spaces, and that is not what they look like.  This is a problem
+     with TeX.  (If necessary, in Emacs, you can use `M-x untabify' to
+     convert tabs in a region to multiple spaces.)
+
+  Examples are often, logically speaking, "in the middle" of a
+paragraph, and the text continues after an example should not be
+indented.  The `@noindent' command prevents a piece of text from being
+indented as if it were a new paragraph.  (*Note noindent::.)
+
+  (The `@code' command is used for examples of code that are embedded
+within sentences, not set off from preceding and following text.  *Note
+`@code': code.)
+
+\1f
+File: texinfo.info,  Node: noindent,  Next: Lisp Example,  Prev: example,  Up: Quotations and Examples
+
+`@noindent'
+===========
+
+An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph.  However, you can prevent this by writing `@noindent' at the
+beginning of a line by itself preceding the continuation text.
+
+  For example:
+
+     @example
+     This is an example
+     @end example
+     
+     @noindent
+     This line is not indented.  As you can see, the
+     beginning of the line is fully flush left with the line
+     that follows after it.  (This whole example is between
+     @code{@@display} and @code{@@end display}.)
+
+produces
+
+          This is an example
+     
+     
+     This line is not indented.  As you can see, the
+     beginning of the line is fully flush left with the line
+     that follows after it.  (This whole example is between
+     `@display' and `@end display'.)
+
+  To adjust the number of blank lines properly in the Info file output,
+remember that the line containing `@noindent' does not generate a blank
+line, and neither does the `@end example' line.
+
+  In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing `@noindent'.
+
+  Do not put braces after an `@noindent' command; they are not
+necessary, since `@noindent' is a command used outside of paragraphs
+(*note Command Syntax::).
+
+\1f
+File: texinfo.info,  Node: Lisp Example,  Next: smallexample & smalllisp,  Prev: noindent,  Up: Quotations and Examples
+
+`@lisp'
+=======
+
+The `@lisp' command is used for Lisp code.  It is synonymous with the
+`@example' command.
+
+     This is an example of text written between an
+     `@lisp' command and an `@end lisp' command.
+
+  Use `@lisp' instead of `@example' to preserve information regarding
+the nature of the example.  This is useful, for example, if you write a
+function that evaluates only and all the Lisp code in a Texinfo file.
+Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
+Example-Footnote-1::)
+
+  Mark the end of `@lisp' with `@end lisp' on a line by itself.
+
+\1f
+File: texinfo.info,  Node: Lisp Example-Footnotes,  Up: Lisp Example
+
+  (1) It would be straightforward to extend Texinfo to work in a
+similar fashion for C, Fortran, or other languages.
+
+\1f
+File: texinfo.info,  Node: smallexample & smalllisp,  Next: display,  Prev: Lisp Example,  Up: Quotations and Examples
+
+`@smallexample' and `@smalllisp'
+================================
+
+In addition to the regular `@example' and `@lisp' commands, Texinfo has
+two other "example-style" commands.  These are the `@smallexample' and
+`@smalllisp' commands.  Both these commands are designed for use with
+the `@smallbook' command that causes TeX to produce a printed manual in
+a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format.
+
+  In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
+a smaller font for the smaller `@smallbook' format than for the 8.5 by
+11 inch format.  Consequently, many examples containing long lines fit
+in a narrower, `@smallbook' page without needing to be shortened.  Both
+commands typeset in the normal font size when you format for the 8.5 by
+11 inch size; indeed, in this situation, the `@smallexample' and
+`@smalllisp' commands are defined to be the `@example' and `@lisp'
+commands.
+
+  In Info, the `@smallexample' and `@smalllisp' commands are equivalent
+to the `@example' and `@lisp' commands, and work exactly the same.
+
+  Mark the end of `@smallexample' or `@smalllisp' with `@end
+smallexample' or `@end smalllisp', respectively.
+
+     This is an example of text written between `@smallexample' and
+     `@end smallexample'.  In Info and in an 8.5 by 11 inch manual,
+     this text appears in its normal size; but in a 7 by 9.25 inch manual,
+     this text appears in a smaller font.
+
+  The `@smallexample' and `@smalllisp' commands make it easier to
+prepare smaller format manuals without forcing you to edit examples by
+hand to fit them onto narrower pages.
+
+  As a general rule, a printed document looks better if you write all
+the examples in a chapter consistently in `@example' or in
+`@smallexample'.  Only occasionally should you mix the two formats.
+
+  *Note Printing "Small" Books: smallbook, for more information about
+the `@smallbook' command.
+
+\1f
+File: texinfo.info,  Node: display,  Next: format,  Prev: smallexample & smalllisp,  Up: Quotations and Examples
+
+`@display'
+==========
+
+The `@display' command begins a kind of example.  It is like the
+`@example' command except that, in a printed manual, `@display' does
+not select the fixed-width font.  In fact, it does not specify the font
+at all, so that the text appears in the same font it would have
+appeared in without the `@display' command.
+
+     This is an example of text written between an `@display' command
+     and an `@end display' command.  The `@display' command
+     indents the text, but does not fill it.
+
+\1f
+File: texinfo.info,  Node: format,  Next: exdent,  Prev: display,  Up: Quotations and Examples
+
+`@format'
+=========
+
+The `@format' command is similar to `@example' except that, in the
+printed manual, `@format' does not select the fixed-width font and does
+not narrow the margins.
+
+This is an example of text written between an `@format' command
+and an `@end format' command.  As you can see
+from this example,
+the `@format' command does not fill the text.
+
+\1f
+File: texinfo.info,  Node: exdent,  Next: flushleft & flushright,  Prev: format,  Up: Quotations and Examples
+
+`@exdent': Undoing a Line's Indentation
+=======================================
+
+The `@exdent' command removes any indentation a line might have.  The
+command is written at the beginning of a line and applies only to the
+text that follows the command that is on the same line.  Do not use
+braces around the text.  In a printed manual, the text on an `@exdent'
+line is printed in the roman font.
+
+  `@exdent' is usually used within examples.  Thus,
+
+     @example
+     This line follows an @@example command.
+     @exdent This line is exdented.
+     This line follows the exdented line.
+     The @@end example comes on the next line.
+     @end group
+
+produces
+
+     This line follows an @example command.
+This line is exdented.
+     This line follows the exdented line.
+     The @end example comes on the next line.
+
+  In practice, the `@exdent' command is rarely used.  Usually, you
+un-indent text by ending the example and returning the page to its
+normal width.
+
+\1f
+File: texinfo.info,  Node: flushleft & flushright,  Next: cartouche,  Prev: exdent,  Up: Quotations and Examples
+
+`@flushleft' and `@flushright'
+==============================
+
+The `@flushleft' and `@flushright' commands line up the ends of lines
+on the left and right margins of a page, but do not fill the text.  The
+commands are written on lines of their own, without braces.  The
+`@flushleft' and `@flushright' commands are ended by `@end flushleft'
+and `@end flushright' commands on lines of their own.
+
+  For example,
+
+     @flushleft
+     This text is
+     written flushleft.
+     @end flushleft
+
+produces
+
+     This text is
+     written flushleft.
+
+  `@flushright' produces the type of indentation often used in the
+return address of letters.  For example,
+
+     @flushright
+     Here is an example of text written
+     flushright.  The @code{@flushright} command
+     right justifies every line but leaves the
+     left end ragged.
+     @end flushright
+
+produces
+
+                                     Here is an example of text written
+                                 flushright.  The `@flushright' command
+                              right justifies every line but leaves the
+                                                       left end ragged.
+
+\1f
+File: texinfo.info,  Node: cartouche,  Prev: flushleft & flushright,  Up: Quotations and Examples
+
+Drawing Cartouches Around Examples
+==================================
+
+In a printed manual, the `@cartouche' command draws a box with rounded
+corners around its contents.  You can use this command to further
+highlight an example or quotation.  For instance, you could write a
+manual in which one type of example is surrounded by a cartouche for
+emphasis.
+
+  The `@cartouche' command affects only the printed manual; it has no
+effect in the Info file.
+
+  For example,
+
+     @example
+     @cartouche
+     % pwd
+     /usr/local/share/emacs
+     @end cartouche
+     @end example
+
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+\1f
+File: texinfo.info,  Node: Lists and Tables,  Next: Indices,  Prev: Quotations and Examples,  Up: Top
+
+Lists and Tables
+****************
+
+Texinfo has several ways of making lists and tables.  Lists can be
+bulleted or numbered; two-column tables can highlight the items in the
+first column; multi-column tables are also supported.
+
+* Menu:
+
+* Introducing Lists::           Texinfo formats lists for you.
+* itemize::                     How to construct a simple list.
+* enumerate::                   How to construct a numbered list.
+* Two-column Tables::           How to construct a two-column table.
+* Multi-column Tables::         How to construct generalized tables.
+
+\1f
+File: texinfo.info,  Node: Introducing Lists,  Next: itemize,  Prev: Lists and Tables,  Up: Lists and Tables
+
+Introducing Lists
+=================
+
+  Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list.  This last feature is useful if you modify the
+list, since you do not need to renumber it yourself.
+
+  Numbered lists and tables begin with the appropriate @-command at the
+beginning of a line, and end with the corresponding `@end' command on a
+line by itself.  The table and itemized-list commands also require that
+you write formatting information on the same line as the beginning
+@-command.
+
+  Begin an enumerated list, for example, with an `@enumerate' command
+and end the list with an `@end enumerate' command.  Begin an itemized
+list with an `@itemize' command, followed on the same line by a
+formatting command such as `@bullet', and end the list with an `@end
+itemize' command.
+
+  Precede each element of a list with an `@item' or `@itemx' command.
+
+
+Here is an itemized list of the different kinds of table and lists:
+
+   * Itemized lists with and without bullets.
+
+   * Enumerated lists, using numbers or letters.
+
+   * Two-column tables with highlighting.
+
+
+Here is an enumerated list with the same items:
+
+  1. Itemized lists with and without bullets.
+
+  2. Enumerated lists, using numbers or letters.
+
+  3. Two-column tables with highlighting.
+
+
+And here is a two-column table with the same items and their @-commands:
+
+`@itemize'
+     Itemized lists with and without bullets.
+
+`@enumerate'
+     Enumerated lists, using numbers or letters.
+
+`@table'
+`@ftable'
+`@vtable'
+     Two-column tables with indexing.
+
+\1f
+File: texinfo.info,  Node: itemize,  Next: enumerate,  Prev: Introducing Lists,  Up: Lists and Tables
+
+Making an Itemized List
+=======================
+
+The `@itemize' command produces sequences of indented paragraphs, with
+a bullet or other mark inside the left margin at the beginning of each
+paragraph for which such a mark is desired.
+
+  Begin an itemized list by writing `@itemize' at the beginning of a
+line.  Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark.  Usually, you will write
+`@bullet' after `@itemize', but you can use `@minus', or any character
+or any special symbol that results in a single character in the Info
+file.  (When you write `@bullet' or `@minus' after an `@itemize'
+command, you may omit the `{}'.)
+
+  Write the text of the indented paragraphs themselves after the
+`@itemize', up to another line that says `@end itemize'.
+
+  Before each paragraph for which a mark in the margin is desired, write
+a line that says just `@item'.  Do not write any other text on this
+line.
+
+  Usually, you should put a blank line before an `@item'.  This puts a
+blank line in the Info file. (TeX inserts the proper interline
+whitespace in either case.)  Except when the entries are very brief,
+these blank lines make the list look better.
+
+  Here is an example of the use of `@itemize', followed by the output
+it produces.  Note that `@bullet' produces a `*' in Info and a round
+dot in TeX.
+
+     @itemize @bullet
+     @item
+     Some text for foo.
+     
+     @item
+     Some text
+     for bar.
+     @end itemize
+
+This produces:
+
+        * Some text for foo.
+
+        * Some text for bar.
+
+  Itemized lists may be embedded within other itemized lists.  Here is a
+list marked with dashes embedded in a list marked with bullets:
+
+     @itemize @bullet
+     @item
+     First item.
+     
+     @itemize @minus
+     @item
+     Inner item.
+     
+     @item
+     Second inner item.
+     @end itemize
+     
+     @item
+     Second outer item.
+     @end itemize
+
+This produces:
+
+        * First item.
+
+             - Inner item.
+
+             - Second inner item.
+
+        * Second outer item.
+
+\1f
+File: texinfo.info,  Node: enumerate,  Next: Two-column Tables,  Prev: itemize,  Up: Lists and Tables
+
+Making a Numbered or Lettered List
+==================================
+
+`@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
+that the labels on the items are successive integers or letters instead
+of bullets.
+
+  Write the `@enumerate' command at the beginning of a line.  The
+command does not require an argument, but accepts either a number or a
+letter as an option.  Without an argument, `@enumerate' starts the list
+with the number `1'.  With a numeric argument, such as `3', the command
+starts the list with that number.  With an upper or lower case letter,
+such as `a' or `A', the command starts the list with that letter.
+
+  Write the text of the enumerated list in the same way you write an
+itemized list: put `@item' on a line of its own before the start of
+each paragraph that you want enumerated.  Do not write any other text
+on the line beginning with `@item'.
+
+  You should put a blank line between entries in the list.  This
+generally makes it easier to read the Info file.
+
+  Here is an example of `@enumerate' without an argument:
+
+     @enumerate
+     @item
+     Underlying causes.
+     
+     @item
+     Proximate causes.
+     @end enumerate
+
+This produces:
+
+  1. Underlying causes.
+
+  2. Proximate causes.
+
+
+  Here is an example with an argument of `3':
+
+     @enumerate 3
+     @item
+     Predisposing causes.
+     
+     @item
+     Precipitating causes.
+     
+     @item
+     Perpetuating causes.
+     @end enumerate
+
+This produces:
+
+  3. Predisposing causes.
+
+  4. Precipitating causes.
+
+  5. Perpetuating causes.
+
+
+  Here is a brief summary of the alternatives.  The summary is
+constructed using `@enumerate' with an argument of `a'.
+
+  a. `@enumerate'
+
+     Without an argument, produce a numbered list, starting with the
+     number 1.
+
+  b. `@enumerate POSITIVE-INTEGER'
+
+     With a (positive) numeric argument, start a numbered list with that
+     number.  You can use this to continue a list that you interrupted
+     with other text.
+
+  c. `@enumerate UPPER-CASE-LETTER'
+
+     With an upper case letter as argument, start a list in which each
+     item is marked by a letter, beginning with that upper case letter.
+
+  d. `@enumerate LOWER-CASE-LETTER'
+
+     With a lower case letter as argument, start a list in which each
+     item is marked by a letter, beginning with that lower case letter.
+
+  You can also nest enumerated lists, as in an outline.
+
+\1f
+File: texinfo.info,  Node: Two-column Tables,  Next: Multi-column Tables,  Prev: enumerate,  Up: Lists and Tables
+
+Making a Two-column Table
+=========================
+
+`@table' is similar to `@itemize' (*note `@itemize': itemize.), but
+allows you to specify a name or heading line for each item.  The
+`@table' command is used to produce two-column tables, and is
+especially useful for glossaries, explanatory exhibits, and
+command-line option summaries.
+
+* Menu:
+
+* table::                       How to construct a two-column table.
+* ftable vtable::               Automatic indexing for two-column tables.
+* itemx::                       How to put more entries in the first column.
+
+\1f
+File: texinfo.info,  Node: table,  Next: ftable vtable,  Prev: Two-column Tables,  Up: Two-column Tables
+
+Using the `@table' Command
+--------------------------
+
+Use the `@table' command to produce two-column tables.
+
+  Write the `@table' command at the beginning of a line and follow it
+on the same line with an argument that is a Texinfo "indicating"
+command such as `@code', `@samp', `@var', or `@kbd' (*note
+Indicating::).  Although these commands are usually followed by
+arguments in braces, in this case you use the command name without an
+argument because `@item' will supply the argument.  This command will
+be applied to the text that goes into the first column of each item and
+determines how it will be highlighted.  For example, `@code' will cause
+the text in the first column to be highlighted with an `@code' command.
+(We recommend `@code' for `@table''s of command-line options.)
+
+  You may also choose to use the `@asis' command as an argument to
+`@table'.  `@asis' is a command that does nothing; if you use this
+command after `@table', TeX and the Info formatting commands output the
+first column entries without added highlighting ("as is").
+
+  (The `@table' command may work with other commands besides those
+listed here.  However, you can only use commands that normally take
+arguments in braces.)
+
+  Begin each table entry with an `@item' command at the beginning of a
+line.  Write the first column text on the same line as the `@item'
+command.  Write the second column text on the line following the
+`@item' line and on subsequent lines.  (You do not need to type
+anything for an empty second column entry.)  You may write as many
+lines of supporting text as you wish, even several paragraphs.  But
+only text on the same line as the `@item' will be placed in the first
+column.
+
+  Normally, you should put a blank line before an `@item' line.  This
+puts a blank like in the Info file.  Except when the entries are very
+brief, a blank line looks better.
+
+  The following table, for example, highlights the text in the first
+column with an `@samp' command:
+
+     @table @samp
+     @item foo
+     This is the text for
+     @samp{foo}.
+     
+     @item bar
+     Text for @samp{bar}.
+     @end table
+
+This produces:
+
+`foo'
+     This is the text for `foo'.
+
+`bar'
+     Text for `bar'.
+
+  If you want to list two or more named items with a single block of
+text, use the `@itemx' command.  (*Note `@itemx': itemx.)
+
+\1f
+File: texinfo.info,  Node: ftable vtable,  Next: itemx,  Prev: table,  Up: Two-column Tables
+
+`@ftable' and `@vtable'
+-----------------------
+
+The `@ftable' and `@vtable' commands are the same as the `@table'
+command except that `@ftable' automatically enters each of the items in
+the first column of the table into the index of functions and `@vtable'
+automatically enters each of the items in the first column of the table
+into the index of variables.  This simplifies the task of creating
+indices.  Only the items on the same line as the `@item' commands are
+indexed, and they are indexed in exactly the form that they appear on
+that line.  *Note Creating Indices: Indices, for more information about
+indices.
+
+  Begin a two-column table using `@ftable' or `@vtable' by writing the
+@-command at the beginning of a line, followed on the same line by an
+argument that is a Texinfo command such as `@code', exactly as you
+would for an `@table' command; and end the table with an `@end ftable'
+or `@end vtable' command on a line by itself.
+
+  See the example for `@table' in the previous section.
+
+\1f
+File: texinfo.info,  Node: itemx,  Prev: ftable vtable,  Up: Two-column Tables
+
+`@itemx'
+--------
+
+Use the `@itemx' command inside a table when you have two or more first
+column entries for the same item, each of which should appear on a line
+of its own.  Use `@itemx' for all but the first entry; `@itemx' should
+always follow an `@item' command.  The `@itemx' command works exactly
+like `@item' except that it does not generate extra vertical space
+above the first column text.
+
+  For example,
+
+     @table @code
+     @item upcase
+     @itemx downcase
+     These two functions accept a character or a string as
+     argument, and return the corresponding upper case (lower
+     case) character or string.
+     @end table
+
+This produces:
+
+`upcase'
+`downcase'
+     These two functions accept a character or a string as argument,
+     and return the corresponding upper case (lower case) character or
+     string.
+
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)
+
+\1f
+File: texinfo.info,  Node: Multi-column Tables,  Prev: Two-column Tables,  Up: Lists and Tables
+
+Multi-column Tables
+===================
+
+`@multitable' allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+  You define the column widths on the `@multitable' line itself, and
+write each row of the actual table following an `@item' command, with
+columns separated by an `@tab' command.  Finally, `@end multitable'
+completes the table.  Details in the sections below.
+
+* Menu:
+
+* Multitable Column Widths::    Defining multitable column widths.
+* Multitable Rows::             Defining multitable rows, with examples.
+
+\1f
+File: texinfo.info,  Node: Multitable Column Widths,  Next: Multitable Rows,  Prev: Multi-column Tables,  Up: Multi-column Tables
+
+Multitable Column Widths
+------------------------
+
+You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row.  Mixing the two
+methods is not supported.  In either case, the widths are defined
+entirely on the same line as the `@multitable' command.
+
+  1. To specify column widths as fractions of the line length, write
+     `@columnfractions' and the decimal numbers (presumably less than
+     1) after the `@multitable' command, as in:
+
+          @multitable @columnfractions .33 .33 .33
+
+     The fractions need not add up exactly to 1.0, as these do not.
+     This allows you to produce tables that do not need the full line
+     length.
+
+  2. To specify a prototype row, write the longest entry for each column
+     enclosed in braces after the `@multitable' command.  For example:
+
+          @multitable {some text for column one} {for column two}
+
+     The first column will then have the width of the typeset `some
+     text for column one', and the second column the width of `for
+     column two'.
+
+     The prototype entries need not appear in the table itself.
+
+     Although we used simple text in this example, the prototype
+     entries can contain Texinfo commands; markup commands such as
+     `@code' are particularly likely to be useful.
+
+
+\1f
+File: texinfo.info,  Node: Multitable Rows,  Prev: Multitable Column Widths,  Up: Multi-column Tables
+
+Multitable Rows
+---------------
+
+After the `@multitable' command defining the column widths (see the
+previous section), you begin each row in the body of a multitable with
+`@item', and separate the column entries with `@tab'.  Line breaks are
+not special within the table body, and you may break input lines in
+your source file as necessary.
+
+  Here is a complete example of a multi-column table (the text is from
+`The XEmacs Users' Manual', *note Splitting Windows: (xemacs)Split
+Window.):
+
+     @multitable @columnfractions .15 .45 .4
+     @item Key @tab Command @tab Description
+     @item C-x 2
+     @tab @code{split-window-vertically}
+     @tab Split the selected window into two windows,
+     with one above the other.
+     @item C-x 3
+     @tab @code{split-window-horizontally}
+     @tab Split the selected window into two windows
+     positioned side by side.
+     @item C-Mouse-2
+     @tab
+     @tab In the mode line or scroll bar of a window,
+     split that window.
+     @end multitable
+
+produces:
+
+Key         Command                          Description
+C-x 2       `split-window-vertically'        Split the selected window
+                                             into two windows, with one
+                                             above the other.
+C-x 3       `split-window-horizontally'      Split the selected window
+                                             into two windows positioned
+                                             side by side.
+C-Mouse-2                                    In the mode line or scroll
+                                             bar of a window, split that
+                                             window.
+
+\1f
+File: texinfo.info,  Node: Indices,  Next: Insertions,  Prev: Lists and Tables,  Up: Top
+
+Creating Indices
+****************
+
+Using Texinfo, you can generate indices without having to sort and
+collate entries manually.  In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry.  In a printed manual, this information
+consists of page numbers.  In an Info file, this information is a menu
+entry leading to the first node referenced.
+
+  Texinfo provides several predefined kinds of index: an index for
+functions, an index for variables, an index for concepts, and so on.
+You can combine indices or use them for other than their canonical
+purpose.  If you wish, you can define your own indices.
+
+* Menu:
+
+* Index Entries::               Choose different words for index entries.
+* Predefined Indices::          Use different indices for different kinds
+                                  of entry.
+* Indexing Commands::           How to make an index entry.
+* Combining Indices::           How to combine indices.
+* New Indices::                 How to define your own indices.
+
+\1f
+File: texinfo.info,  Node: Index Entries,  Next: Predefined Indices,  Prev: Indices,  Up: Indices
+
+Making Index Entries
+====================
+
+When you are making index entries, it is good practice to think of the
+different ways people may look for something.  Different people _do
+not_ think of the same words when they look something up.  A helpful
+index will have items indexed under all the different words that people
+may use.  For example, one reader may think it obvious that the
+two-letter names for indices should be listed under "Indices,
+two-letter names", since the word "Index" is the general concept.  But
+another reader may remember the specific concept of two-letter names
+and search for the entry listed as "Two letter names for indices".  A
+good index will have both entries and will help both readers.
+
+  Like typesetting, the construction of an index is a highly skilled,
+professional art, the subtleties of which are not appreciated until you
+need to do it yourself.
+
+  *Note Printing Indices & Menus::, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+\1f
+File: texinfo.info,  Node: Predefined Indices,  Next: Indexing Commands,  Prev: Index Entries,  Up: Indices
+
+Predefined Indices
+==================
+
+Texinfo provides six predefined indices:
+
+   * A "concept index" listing concepts that are discussed.
+
+   * A "function index" listing functions (such as entry points of
+     libraries).
+
+   * A "variables index" listing variables (such as global variables of
+     libraries).
+
+   * A "keystroke index" listing keyboard commands.
+
+   * A "program index" listing names of programs.
+
+   * A "data type index" listing data types (such as structures defined
+     in header files).
+
+Not every manual needs all of these, and most manuals use two or three
+of them.  This manual has two indices: a concept index and an @-command
+index (that is actually the function index but is called a command
+index in the chapter heading).  Two or more indices can be combined
+into one using the `@synindex' or `@syncodeindex' commands.  *Note
+Combining Indices::.
+
+\1f
+File: texinfo.info,  Node: Indexing Commands,  Next: Combining Indices,  Prev: Predefined Indices,  Up: Indices
+
+Defining the Entries of an Index
+================================
+
+The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file.  Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the reference.
+
+  An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the entry.
+
+  For example, this section begins with the following five entries for
+the concept index:
+
+     @cindex Defining indexing entries
+     @cindex Index entries
+     @cindex Entries for an index
+     @cindex Specifying index entries
+     @cindex Creating index entries
+
+  Each predefined index has its own indexing command--`@cindex' for the
+concept index, `@findex' for the function index, and so on.
+
+  Concept index entries consist of text.  The best way to write an index
+is to choose entries that are terse yet clear.  If you can do this, the
+index often looks better if the entries are not capitalized, but
+written just as they would appear in the middle of a sentence.
+(Capitalize proper names and acronyms that always call for upper case
+letters.)  This is the case convention we use in most GNU manuals'
+indices.
+
+  If you don't see how to make an entry terse yet clear, make it longer
+and clear--not terse and confusing.  If many of the entries are several
+words long, the index may look better if you use a different convention:
+to capitalize the first word of each entry.  But do not capitalize a
+case-sensitive name such as a C or Lisp function name or a shell
+command; that would be a spelling error.
+
+  Whichever case convention you use, please use it consistently!
+
+  Entries in indices other than the concept index are symbol names in
+programming languages, or program names; these names are usually
+case-sensitive, so use upper and lower case as required for them.
+
+  By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small `@code'
+font.  You may change the way part of an entry is printed with the
+usual Texinfo commands, such as `@file' for file names and `@emph' for
+emphasis (*note Marking Text::).
+
+  The six indexing commands for predefined indices are:
+
+`@cindex CONCEPT'
+     Make an entry in the concept index for CONCEPT.
+
+`@findex FUNCTION'
+     Make an entry in the function index for FUNCTION.
+
+`@vindex VARIABLE'
+     Make an entry in the variable index for VARIABLE.
+
+`@kindex KEYSTROKE'
+     Make an entry in the key index for KEYSTROKE.
+
+`@pindex PROGRAM'
+     Make an entry in the program index for PROGRAM.
+
+`@tindex DATA TYPE'
+     Make an entry in the data type index for DATA TYPE.
+
+     *Caution:* Do not use a colon in an index entry.  In Info, a colon
+     separates the menu entry name from the node name.  An extra colon
+     confuses Info.  *Note The Parts of a Menu: Menu Parts, for more
+     information about the structure of a menu entry.
+
+  If you write several identical index entries in different places in a
+Texinfo file, the index in the printed manual will list all the pages to
+which those entries refer.  However, the index in the Info file will
+list *only* the node that references the *first* of those index
+entries.  Therefore, it is best to write indices in which each entry
+refers to only one place in the Texinfo file.  Fortunately, this
+constraint is a feature rather than a loss since it means that the index
+will be easy to use.  Otherwise, you could create an index that lists
+several pages for one entry and your reader would not know to which page
+to turn.  If you have two identical entries for one topic, change the
+topics slightly, or qualify them to indicate the difference.
+
+  You are not actually required to use the predefined indices for their
+canonical purposes.  For example, suppose you wish to index some C
+preprocessor macros.  You could put them in the function index along
+with actual functions, just by writing `@findex' commands for them;
+then, when you print the "Function Index" as an unnumbered chapter, you
+could give it the title `Function and Macro Index' and all will be
+consistent for the reader.  Or you could put the macros in with the
+data types by writing `@tindex' commands for them, and give that index
+a suitable title so the reader will understand.  (*Note Printing
+Indices & Menus::.)
+
+\1f
+File: texinfo.info,  Node: Combining Indices,  Next: New Indices,  Prev: Indexing Commands,  Up: Indices
+
+Combining Indices
+=================
+
+Sometimes you will want to combine two disparate indices such as
+functions and concepts, perhaps because you have few enough of one of
+them that a separate index for them would look silly.
+
+  You could put functions into the concept index by writing `@cindex'
+commands for them instead of `@findex' commands, and produce a
+consistent manual by printing the concept index with the title
+`Function and Concept Index' and not printing the `Function Index' at
+all; but this is not a robust procedure.  It works only if your
+document is never included as part of another document that is designed
+to have a separate function index; if your document were to be included
+with such a document, the functions from your document and those from
+the other would not end up together.  Also, to make your function names
+appear in the right font in the concept index, you would need to
+enclose every one of them between the braces of `@code'.
+
+* Menu:
+
+* syncodeindex::                How to merge two indices, using `@code'
+                                  font for the merged-from index.
+* synindex::                    How to merge two indices, using the
+                                  default font of the merged-to index.
+
+\1f
+File: texinfo.info,  Node: syncodeindex,  Next: synindex,  Prev: Combining Indices,  Up: Combining Indices
+
+`@syncodeindex'
+---------------
+
+When you want to combine functions and concepts into one index, you
+should index the functions with `@findex' and index the concepts with
+`@cindex', and use the `@syncodeindex' command to redirect the function
+index entries into the concept index.
+
+  The `@syncodeindex' command takes two arguments; they are the name of
+the index to redirect, and the name of the index to redirect it to.
+The template looks like this:
+
+     @syncodeindex FROM TO
+
+  For this purpose, the indices are given two-letter names:
+
+`cp'
+     concept index
+
+`fn'
+     function index
+
+`vr'
+     variable index
+
+`ky'
+     key index
+
+`pg'
+     program index
+
+`tp'
+     data type index
+
+  Write an `@syncodeindex' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file.  For example, to
+merge a function index with a concept index, write the following:
+
+     @syncodeindex fn cp
+
+This will cause all entries designated for the function index to merge
+in with the concept index instead.
+
+  To merge both a variables index and a function index into a concept
+index, write the following:
+
+     @syncodeindex vr cp
+     @syncodeindex fn cp
+
+  The `@syncodeindex' command puts all the entries from the `from'
+index (the redirected index) into the `@code' font, overriding whatever
+default font is used by the index to which the entries are now
+directed.  This way, if you direct function names from a function index
+into a concept index, all the function names are printed in the `@code'
+font as you would expect.
+
+\1f
+File: texinfo.info,  Node: synindex,  Prev: syncodeindex,  Up: Combining Indices
+
+`@synindex'
+-----------
+
+The `@synindex' command is nearly the same as the `@syncodeindex'
+command, except that it does not put the `from' index  entries into the
+`@code' font; rather it puts them in the roman font.  Thus, you use
+`@synindex' when you merge a concept index into a function index.
+
+  *Note Printing Indices & Menus::, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+\1f
+File: texinfo.info,  Node: New Indices,  Prev: Combining Indices,  Up: Indices
+
+Defining New Indices
+====================
+
+In addition to the predefined indices, you may use the `@defindex' and
+`@defcodeindex' commands to define new indices.  These commands create
+new indexing @-commands with which you mark index entries.  The
+`@defindex 'command is used like this:
+
+     @defindex NAME
+
+  The name of an index should be a two letter word, such as `au'.  For
+example:
+
+     @defindex au
+
+  This defines a new index, called the `au' index.  At the same time,
+it creates a new indexing command, `@auindex', that you can use to make
+index entries.  Use the new indexing command just as you would use a
+predefined indexing command.
+
+  For example, here is a section heading followed by a concept index
+entry and two `au' index entries.
+
+     @section Cognitive Semantics
+     @cindex kinesthetic image schemas
+     @auindex Johnson, Mark
+     @auindex Lakoff, George
+
+(Evidently, `au' serves here as an abbreviation for "author".)  Texinfo
+constructs the new indexing command by concatenating the name of the
+index with `index'; thus, defining an `au' index leads to the automatic
+creation of an `@auindex' command.
+
+  Use the `@printindex' command to print the index, as you do with the
+predefined indices.  For example:
+
+     @node Author Index, Subject Index, , Top
+     @unnumbered Author Index
+     
+     @printindex au
+
+  The `@defcodeindex' is like the `@defindex' command, except that, in
+the printed output, it prints entries in an `@code' font instead of a
+roman font.  Thus, it parallels the `@findex' command rather than the
+`@cindex' command.
+
+  You should define new indices within or right after the end-of-header
+line of a Texinfo file, before any `@synindex' or `@syncodeindex'
+commands (*note Header::).
+
+\1f
+File: texinfo.info,  Node: Insertions,  Next: Breaks,  Prev: Indices,  Up: Top
+
+Special Insertions
+******************
+
+Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
+* Menu:
+
+* Braces Atsigns::              How to insert braces, `@'.
+* Inserting Space::             How to insert the right amount of space
+                                  within a sentence.
+* Inserting Accents::           How to insert accents and special characters.
+* Dots Bullets::                How to insert dots and bullets.
+* TeX and copyright::           How to insert the TeX logo
+                                  and the copyright symbol.
+* pounds::                      How to insert the pounds currency symbol.
+* minus::                       How to insert a minus sign.
+* math::                        How to format a mathematical expression.
+* Glyphs::                      How to indicate results of evaluation,
+                                  expansion of macros, errors, etc.
+* Images::                      How to include graphics.
+
+\1f
+File: texinfo.info,  Node: Braces Atsigns,  Next: Inserting Space,  Prev: Insertions,  Up: Insertions
+
+Inserting @ and Braces
+======================
+
+`@' and curly braces are special characters in Texinfo.  To insert
+these characters so they appear in text, you must put an `@' in front
+of these characters to prevent Texinfo from misinterpreting them.
+
+  Do not put braces after any of these commands; they are not necessary.
+
+* Menu:
+
+* Inserting An Atsign::         How to insert `@'.
+* Inserting Braces::            How to insert `{' and `}'.
+
+\1f
+File: texinfo.info,  Node: Inserting An Atsign,  Next: Inserting Braces,  Prev: Braces Atsigns,  Up: Braces Atsigns
+
+Inserting `@' with @@
+---------------------
+
+`@@' stands for a single `@' in either printed or Info output.
+
+  Do not put braces after an `@@' command.
+
+\1f
+File: texinfo.info,  Node: Inserting Braces,  Prev: Inserting An Atsign,  Up: Braces Atsigns
+
+Inserting `{' and `}'with @{ and @}
+-----------------------------------
+
+`@{' stands for a single `{' in either printed or Info output.
+
+  `@}' stands for a single `}' in either printed or Info output.
+
+  Do not put braces after either an `@{' or an `@}' command.
+
+\1f
+File: texinfo.info,  Node: Inserting Space,  Next: Inserting Accents,  Prev: Braces Atsigns,  Up: Insertions
+
+Inserting Space
+===============
+
+The following sections describe commands that control spacing of various
+kinds within and after sentences.
+
+* Menu:
+
+* Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
+* Ending a Sentence::           Sometimes it does.
+* Multiple Spaces::             Inserting multiple spaces.
+* dmn::                         How to format a dimension.
+
+\1f
+File: texinfo.info,  Node: Not Ending a Sentence,  Next: Ending a Sentence,  Prev: Inserting Space,  Up: Inserting Space
+
+Not Ending a Sentence
+---------------------
+
+Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual.  Since it is not always possible for
+Texinfo to determine when a period ends a sentence and when it is used
+in an abbreviation, special commands are needed in some circumstances.
+(Usually, Texinfo can guess how to handle periods, so you do not need to
+use the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period, question mark, or exclamation mark that ends a sentence.)
+
+  Use the `@:' command after a period, question mark, exclamation mark,
+or colon that should not be followed by extra space.  For example, use
+`@:' after periods that end abbreviations which are not at the ends of
+sentences.
+
+  For example,
+
+     The s.o.p.@: has three parts ...
+     The s.o.p. has three parts ...
+
+produces
+
+     The s.o.p. has three parts ...
+     The s.o.p. has three parts ...
+
+(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
+Procedure".)
+
+  `@:' has no effect on the Info output.  Do not put braces after `@:'.
+
+\1f
+File: texinfo.info,  Node: Ending a Sentence,  Next: Multiple Spaces,  Prev: Not Ending a Sentence,  Up: Inserting Space
+
+Ending a Sentence
+-----------------
+
+Use `@.' instead of a period, `@!' instead of an exclamation point, and
+`@?' instead of a question mark at the end of a sentence that ends with
+a single capital letter.  Otherwise, TeX will think the letter is an
+abbreviation and will not insert the correct end-of-sentence spacing.
+Here is an example:
+
+     Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
+     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
+
+produces
+
+     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
+     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
+
+  In the Info file output, `@.' is equivalent to a simple `.'; likewise
+for `@!' and `@?'.
+
+  The meanings of `@:' and `@.' in Texinfo are designed to work well
+with the Emacs sentence motion commands (*note Sentences:
+(xemacs)Sentences.).  This made it necessary for them to be
+incompatible with some other formatting systems that use @-commands.
+
+  Do not put braces after any of these commands.
+
+\1f
+File: texinfo.info,  Node: Multiple Spaces,  Next: dmn,  Prev: Ending a Sentence,  Up: Inserting Space
+
+Multiple Spaces
+---------------
+
+Ordinarily, TeX collapses multiple whitespace characters (space, tab,
+and newline) into a single space.  Info output, on the other hand,
+preserves whitespace as you type it, except for changing a newline into
+a space; this is why it is important to put two spaces at the end of
+sentences in Texinfo documents.
+
+  Occasionally, you may want to actually insert several consecutive
+spaces, either for purposes of example (what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists.  Texinfo supports three commands: `@SPACE', `@TAB',
+and `@NL', all of which insert a single space into the output.  (Here,
+`@SPACE' represents an `@' character followed by a space, i.e., `@ ',
+and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
+when `@' is the last character on a line.)
+
+  For example,
+     Spacey@ @ @ @
+     example.
+
+produces
+
+     Spacey    example.
+
+  Other possible uses of `@SPACE' have been subsumed by `@multitable'
+(*note Multi-column Tables::).
+
+  Do not follow any of these commands with braces.
+
+\1f
+File: texinfo.info,  Node: dmn,  Prev: Multiple Spaces,  Up: Inserting Space
+
+`@dmn'{DIMENSION}: Format a Dimension
+-------------------------------------
+
+At times, you may want to write `12pt' or `8.5in' with little or no
+space between the number and the abbreviation for the dimension.  You
+can use the `@dmn' command to do this.  On seeing the command, TeX
+inserts just enough space for proper typesetting; the Info formatting
+commands insert no space at all, since the Info file does not require
+it.
+
+  To use the `@dmn' command, write the number and then follow it
+immediately, with no intervening space, by `@dmn', and then by the
+dimension within braces.  For example,
+
+     A4 paper is 8.27@dmn{in} wide.
+
+produces
+
+     A4 paper is 8.27in wide.
+
+  Not everyone uses this style.  Some people prefer `8.27 in.@:' or
+`8.27 inches' to `8.27@dmn{in}' in the Texinfo file.  In these cases,
+however, the formatters may insert a line break between the number and
+the dimension, so use `@w' (*note w::).  Also, if you write a period
+after an abbreviation within a sentence, you should write `@:' after
+the period to prevent TeX from inserting extra whitespace, as shown
+here.  *Note Inserting Space::.
+
+\1f
+File: texinfo.info,  Node: Inserting Accents,  Next: Dots Bullets,  Prev: Inserting Space,  Up: Insertions
+
+Inserting Accents
+=================
+
+Here is a table with the commands Texinfo provides for inserting
+floating accents.  The commands with non-alphabetic names do not take
+braces around their argument (which is taken to be the next character).
+(Exception: `@,' _does_ take braces around its argument.)  This is so
+as to make the source as convenient to type and read as possible, since
+accented characters are very common in some languages.
+
+Command           Output   What
+@"o               o"       umlaut accent
+@'o               o'       acute accent
+@,{c}             c,       cedilla accent
+@=o               o=       macron/overbar accent
+@^o               o^       circumflex accent
+@`o               o`       grave accent
+@~o               o~       tilde accent
+@dotaccent{o}     o.       overdot accent
+@H{o}             o''      long Hungarian umlaut
+@ringaccent{o}    o*       ring accent
+@tieaccent{oo}    oo[      tie-after accent
+@u{o}             o(       breve accent
+@ubaraccent{o}    o_       underbar accent
+@udotaccent{o}    .o       underdot accent
+@v{o}             o<       hacek or check accent
+
+  This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
+@exclamdown{}     !       upside-down !
+@questiondown{}   ?       upside-down ?
+@aa{},@AA{}       aa,AA   A,a with circle
+@ae{},@AE{}       ae,AE   ae,AE ligatures
+@dotless{i}       i       dotless i
+@dotless{j}       j       dotless j
+@l{},@L{}         /l,/L   suppressed-L,l
+@o{},@O{}         /o,/O   O,o with slash
+@oe{},@OE{}       oe,OE   OE,oe ligatures
+@ss{}             ss      es-zet or sharp S
+
+\1f
+File: texinfo.info,  Node: Dots Bullets,  Next: TeX and copyright,  Prev: Inserting Accents,  Up: Insertions
+
+Inserting Ellipsis, Dots, and Bullets
+=====================================
+
+An "ellipsis" (a line of dots) is not typeset as a string of periods,
+so a special command is used for ellipsis in Texinfo.  The `@bullet'
+command is special, too.  Each of these commands is followed by a pair
+of braces, `{}', without any whitespace between the name of the command
+and the braces.  (You need to use braces with these commands because
+you can use them next to other text; without the braces, the formatters
+would be confused.  *Note @-Command Syntax: Command Syntax, for further
+information.)
+
+* Menu:
+
+* dots::                        How to insert dots ...
+* bullet::                      How to insert a bullet.
+
+\1f
+File: texinfo.info,  Node: dots,  Next: bullet,  Prev: Dots Bullets,  Up: Dots Bullets
+
+`@dots'{} (...)
+---------------
+
+Use the `@dots{}' command to generate an ellipsis, which is three dots
+in a row, appropriately spaced, like this: `...'.  Do not simply write
+three periods in the input file; that would work for the Info file
+output, but would produce the wrong amount of space between the periods
+in the printed manual.
+
+  Similarly, the `@enddots{}' command generates an end-of-sentence
+ellipsis (four dots) ....
+
+\1f
+File: texinfo.info,  Node: bullet,  Prev: dots,  Up: Dots Bullets
+
+`@bullet'{} (*)
+---------------
+
+Use the `@bullet{}' command to generate a large round dot, or the
+closest possible thing to one.  In Info, an asterisk is used.
+
+  Here is a bullet: *
+
+  When you use `@bullet' in `@itemize', you do not need to type the
+braces, because `@itemize' supplies them.  (*Note `@itemize': itemize.)
+
+\1f
+File: texinfo.info,  Node: TeX and copyright,  Next: pounds,  Prev: Dots Bullets,  Up: Insertions
+
+Inserting TeX and the Copyright Symbol
+======================================
+
+The logo `TeX' is typeset in a special fashion and it needs an
+@-command.  The copyright symbol, `(C)', is also special.  Each of
+these commands is followed by a pair of braces, `{}', without any
+whitespace between the name of the command and the braces.
+
+* Menu:
+
+* tex::                         How to insert the TeX logo.
+* copyright symbol::            How to use `@copyright'{}.
+
+\1f
+File: texinfo.info,  Node: tex,  Next: copyright symbol,  Prev: TeX and copyright,  Up: TeX and copyright
+
+`@TeX'{} (TeX)
+--------------
+
+Use the `@TeX{}' command to generate `TeX'.  In a printed manual, this
+is a special logo that is different from three ordinary letters.  In
+Info, it just looks like `TeX'.  The `@TeX{}' command is unique among
+Texinfo commands in that the `T' and the `X' are in upper case.
+
+\1f
+File: texinfo.info,  Node: copyright symbol,  Prev: tex,  Up: TeX and copyright
+
+`@copyright'{} ((C))
+--------------------
+
+Use the `@copyright{}' command to generate `(C)'.  In a printed manual,
+this is a `c' inside a circle, and in Info, this is `(C)'.
+
+\1f
+File: texinfo.info,  Node: pounds,  Next: minus,  Prev: TeX and copyright,  Up: Insertions
+
+`@pounds{}' (#): Pounds Sterling
+================================
+
+Use the `@pounds{}' command to generate `#'.  In a printed manual, this
+is the symbol for the currency pounds sterling.  In Info, it is a `#'.
+Other currency symbols are unfortunately not available.
+
+\1f
+File: texinfo.info,  Node: minus,  Next: math,  Prev: pounds,  Up: Insertions
+
+`@minus'{} (-): Inserting a Minus Sign
+======================================
+
+Use the `@minus{}' command to generate a minus sign.  In a fixed-width
+font, this is a single hyphen, but in a proportional font, the symbol
+is the customary length for a minus sign--a little longer than a
+hyphen, shorter than an em-dash:
+
+     `-' is a minus sign generated with `@minus{}',
+     
+     `-' is a hyphen generated with the character `-',
+     
+     `---' is an em-dash for text.
+
+In the fixed-width font used by Info, `@minus{}' is the same as a
+hyphen.
+
+  You should not use `@minus{}' inside `@code' or `@example' because
+the width distinction is not made in the fixed-width font they use.
+
+  When you use `@minus' to specify the mark beginning each entry in an
+itemized list, you do not need to type the braces (*note `@itemize':
+itemize..)
+
+\1f
+File: texinfo.info,  Node: math,  Next: Glyphs,  Prev: minus,  Up: Insertions
+
+`@math' - Inserting Mathematical Expressions
+============================================
+
+You can write a short mathematical expression with the `@math' command.
+Write the mathematical expression between braces, like this:
+
+     @math{(a + b)(a + b) = a^2 + 2ab + b^2}
+
+This produces the following in Info:
+
+     (a + b)(a + b) = a^2 + 2ab + b^2
+
+  Thus, the `@math' command has no effect on the Info output.
+
+  For complex mathematical expressions, you can also use TeX directly
+(*note Raw Formatter Commands::).  When you use TeX directly, remember
+to write the mathematical expression between one or two `$'
+(dollar-signs) as appropriate.
+
+\1f
+File: texinfo.info,  Node: Glyphs,  Next: Images,  Prev: math,  Up: Insertions
+
+Glyphs for Examples
+===================
+
+In Texinfo, code is often illustrated in examples that are delimited by
+`@example' and `@end example', or by `@lisp' and `@end lisp'.  In such
+examples, you can indicate the results of evaluation or an expansion
+using `=>' or `==>'.  Likewise, there are commands to insert glyphs to
+indicate printed output, error messages, equivalence of expressions,
+and the location of point.
+
+  The glyph-insertion commands do not need to be used within an
+example, but most often they are.  Every  glyph-insertion command is
+followed by a pair of left- and right-hand braces.
+
+* Menu:
+
+* Glyphs Summary::
+* result::                      How to show the result of expression.
+* expansion::                   How to indicate an expansion.
+* Print Glyph::                 How to indicate printed output.
+* Error Glyph::                 How to indicate an error message.
+* Equivalence::                 How to indicate equivalence.
+* Point Glyph::                 How to indicate the location of point.
+
+\1f
+File: texinfo.info,  Node: Glyphs Summary,  Next: result,  Prev: Glyphs,  Up: Glyphs
+
+Glyphs Summary
+--------------
+
+Here are the different glyph commands:
+
+=>
+     `@result{}' points to the result of an expression.
+
+==>
+     `@expansion{}' shows the results of a macro expansion.
+
+-|
+     `@print{}' indicates printed output.
+
+error-->
+     `@error{}' indicates that the following text is an error message.
+
+==
+     `@equiv{}' indicates the exact equivalence of two forms.
+
+-!-
+     `@point{}' shows the location of point.
+
+* Menu:
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+\1f
+File: texinfo.info,  Node: result,  Next: expansion,  Prev: Glyphs Summary,  Up: Glyphs
+
+`@result{}' (=>): Indicating Evaluation
+---------------------------------------
+
+Use the `@result{}' command to indicate the result of evaluating an
+expression.
+
+  The `@result{}' command is displayed as `=>' in Info and as a double
+stemmed arrow in the printed output.
+
+  Thus, the following,
+
+     (cdr '(1 2 3))
+          => (2 3)
+
+may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
+
+\1f
+File: texinfo.info,  Node: expansion,  Next: Print Glyph,  Prev: result,  Up: Glyphs
+
+`@expansion{}' (==>): Indicating an Expansion
+---------------------------------------------
+
+When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the `@expansion{}'
+command.
+
+  The `@expansion{}' command is displayed as `==>' in Info and as a
+long arrow with a flat base in the printed output.
+
+  For example, the following
+
+     @lisp
+     (third '(a b c))
+          @expansion{} (car (cdr (cdr '(a b c))))
+          @result{} c
+     @end lisp
+
+produces
+
+     (third '(a b c))
+          ==> (car (cdr (cdr '(a b c))))
+          => c
+
+which may be read as:
+
+     `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
+     result of evaluating the expression is `c'.
+
+Often, as in this case, an example looks better if the `@expansion{}'
+and `@result{}' commands are indented five spaces.
+
+\1f
+File: texinfo.info,  Node: Print Glyph,  Next: Error Glyph,  Prev: expansion,  Up: Glyphs
+
+`@print{}' (-|): Indicating Printed Output
+------------------------------------------
+
+Sometimes an expression will print output during its execution.  You
+can indicate the printed output with the `@print{}' command.
+
+  The `@print{}' command is displayed as `-|' in Info and similarly, as
+a horizontal dash butting against a vertical bar, in the printed output.
+
+  In the following example, the printed text is indicated with `-|',
+and the value of the expression follows on the last line.
+
+     (progn (print 'foo) (print 'bar))
+          -| foo
+          -| bar
+          => bar
+
+In a Texinfo source file, this example is written as follows:
+
+     @lisp
+     (progn (print 'foo) (print 'bar))
+          @print{} foo
+          @print{} bar
+          @result{} bar
+     @end lisp
+
+\1f
+File: texinfo.info,  Node: Error Glyph,  Next: Equivalence,  Prev: Print Glyph,  Up: Glyphs
+
+`@error{}' (error-->): Indicating an Error Message
+--------------------------------------------------
+
+A piece of code may cause an error when you evaluate it.  You can
+designate the error message with the `@error{}' command.
+
+  The `@error{}' command is displayed as `error-->' in Info and as the
+word `error' in a box in the printed output.
+
+  Thus,
+
+     @lisp
+     (+ 23 'x)
+     @error{} Wrong type argument: integer-or-marker-p, x
+     @end lisp
+
+produces
+
+     (+ 23 'x)
+     error--> Wrong type argument: integer-or-marker-p, x
+
+This indicates that the following error message is printed when you
+evaluate the expression:
+
+     Wrong type argument: integer-or-marker-p, x
+
+  `error-->' itself is not part of the error message.
+
+\1f
+File: texinfo.info,  Node: Equivalence,  Next: Point Glyph,  Prev: Error Glyph,  Up: Glyphs
+
+`@equiv{}' (==): Indicating Equivalence
+---------------------------------------
+
+Sometimes two expressions produce identical results.  You can indicate
+the exact equivalence of two forms with the `@equiv{}' command.
+
+  The `@equiv{}' command is displayed as `==' in Info and as a three
+parallel horizontal lines in the printed output.
+
+  Thus,
+
+     @lisp
+     (make-sparse-keymap) @equiv{} (list 'keymap)
+     @end lisp
+
+produces
+
+     (make-sparse-keymap) == (list 'keymap)
+
+This indicates that evaluating `(make-sparse-keymap)' produces
+identical results to evaluating `(list 'keymap)'.
+
+\1f
+File: texinfo.info,  Node: Point Glyph,  Prev: Equivalence,  Up: Glyphs
+
+`@point{}' (-!-): Indicating Point in a Buffer
+----------------------------------------------
+
+Sometimes you need to show an example of text in an Emacs buffer.  In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
+name.
+
+  You can use the `@point{}' command to show the location of point in
+the text in the buffer.  (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.)
+
+  The `@point{}' command is displayed as `-!-' in Info and as a small
+five pointed star in the printed output.
+
+  The following example shows the contents of buffer `foo' before and
+after evaluating a Lisp command to insert the word `changed'.
+
+     ---------- Buffer: foo ----------
+     This is the -!-contents of foo.
+     ---------- Buffer: foo ----------
+
+     (insert "changed ")
+          => nil
+     ---------- Buffer: foo ----------
+     This is the changed -!-contents of foo.
+     ---------- Buffer: foo ----------
+
+  In a Texinfo source file, the example is written like this:
+
+     @example
+     ---------- Buffer: foo ----------
+     This is the @point{}contents of foo.
+     ---------- Buffer: foo ----------
+     
+     (insert "changed ")
+          @result{} nil
+     ---------- Buffer: foo ----------
+     This is the changed @point{}contents of foo.
+     ---------- Buffer: foo ----------
+     @end example
+
+\1f
+File: texinfo.info,  Node: Images,  Prev: Glyphs,  Up: Insertions
+
+Inserting Images
+================
+
+You can insert an image in an external file with the `@image' command:
+
+     @image{FILENAME, [WIDTH], [HEIGHT]}
+
+  The FILENAME argument is mandatory, and must not have an extension,
+because the different processors support different formats: TeX reads
+the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
+uses `FILENAME.txt' verbatim for Info output (more or less as if it was
+an `@example').  HTML output requires `FILENAME.jpg'.
+
+  The optional WIDTH and HEIGHT arguments specify the size to scale the
+image to (they are ignored for Info output).  If they are both
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
+  The WIDTH and HEIGHT may be specified using any valid TeX dimension,
+namely:
+
+pt
+     point (72.27pt = 1in)
+
+pc
+     pica (1pc = 12pt)
+
+bp
+     big point (72bp = 1in)
+
+in
+     inch
+
+cm
+     centimeter (2.54cm = 1in)
+
+mm
+     millimeter (10mm = 1cm)
+
+dd
+     dido^t point (1157dd = 1238pt)
+
+cc
+     cicero (1cc = 12dd)
+
+sp
+     scaled point (65536sp = 1pt)
+
+  For example, the following will scale a file `ridt.eps' to one inch
+vertically, with the width scaled proportionately:
+
+     @image{ridt,,1in}
+
+  For `@image' to work with TeX, the file `epsf.tex' must be installed
+somewhere that TeX can find it.  This file is included in the Texinfo
+distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
+
+\1f
+File: texinfo.info,  Node: Breaks,  Next: Definition Commands,  Prev: Insertions,  Up: Top
+
+Making and Preventing Breaks
+****************************
+
+Usually, a Texinfo file is processed both by TeX and by one of the Info
+formatting commands.  Line, paragraph, or page breaks sometimes occur
+in the `wrong' place in one or other form of output.  You must ensure
+that text looks right both in the printed manual and in the Info file.
+
+  For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages.  Conversely, you may want to force a page break where none
+would occur normally.  Fortunately, problems like these do not often
+arise.  When they do, use the break, break prevention, or pagination
+commands.
+
+* Menu:
+
+* Break Commands::              Cause and prevent splits.
+* Line Breaks::                 How to force a single line to use two lines.
+* - and hyphenation::           How to tell TeX about hyphenation points.
+* w::                           How to prevent unwanted line breaks.
+* sp::                          How to insert blank lines.
+* page::                        How to force the start of a new page.
+* group::                       How to prevent unwanted page breaks.
+* need::                        Another way to prevent unwanted page breaks.
+
+\1f
+File: texinfo.info,  Node: Break Commands,  Next: Line Breaks,  Prev: Breaks,  Up: Breaks
+
+The Break Commands
+==================
+
+  The break commands create or allow line and paragraph breaks:
+
+`@*'
+     Force a line break.
+
+`@sp N'
+     Skip N blank lines.
+
+`@-'
+     Insert a discretionary hyphen.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+     Define hyphen points in HY-PHEN-A-TED WORDS.
+
+  The line-break-prevention command holds text together all on one line:
+
+`@w{TEXT}'
+     Prevent TEXT from being split and hyphenated across two lines.
+
+  The pagination commands apply only to printed output, since Info
+files do not have pages.
+
+`@page'
+     Start a new page in the printed manual.
+
+`@group'
+     Hold text together that must appear on one printed page.
+
+`@need MILS'
+     Start a new printed page if not enough space on this one.
+
+\1f
+File: texinfo.info,  Node: Line Breaks,  Next: - and hyphenation,  Prev: Break Commands,  Up: Breaks
+
+`@*': Generate Line Breaks
+==========================
+
+The `@*' command forces a line break in both the printed manual and in
+Info.
+
+  For example,
+
+     This line @* is broken @*in two places.
+
+produces
+
+     This line
+      is broken
+     in two places.
+
+(Note that the space after the first `@*' command is faithfully carried
+down to the next line.)
+
+  The `@*' command is often used in a file's copyright page:
+
+     This is edition 2.0 of the Texinfo documentation,@*
+     and is for ...
+
+In this case, the `@*' command keeps TeX from stretching the line
+across the whole page in an ugly manner.
+
+     *Please note:* Do not write braces after an `@*' command; they are
+     not needed.
+
+     Do not write an `@refill' command at the end of a paragraph
+     containing an `@*' command; it will cause the paragraph to be
+     refilled after the line break occurs, negating the effect of the
+     line break.
+
+\1f
+File: texinfo.info,  Node: - and hyphenation,  Next: w,  Prev: Line Breaks,  Up: Breaks
+
+`@-' and `@hyphenation': Helping TeX hyphenate
+==============================================
+
+Although TeX's hyphenation algorithm is generally pretty good, it does
+miss useful hyphenation points from time to time.  (Or, far more
+rarely, insert an incorrect hyphenation.)  So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help TeX out.  Texinfo supports two commands for this:
+
+`@-'
+     Insert a discretionary hyphen, i.e., a place where TeX can (but
+     does not have to) hyphenate.  This is especially useful when you
+     notice an overfull hbox is due to TeX missing a hyphenation (*note
+     Overfull hboxes::).  TeX will not insert any hyphenation points in
+     a word containing `@-'.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+     Tell TeX how to hyphenate HY-PHEN-A-TED WORDS.  As shown, you put
+     a `-' at each hyphenation point.  For example:
+          @hyphenation{man-u-script man-u-scripts}
+
+     TeX only uses the specified hyphenation points when the words
+     match exactly, so give all necessary variants.
+
+  Info output is not hyphenated, so these commands have no effect there.
+
+\1f
+File: texinfo.info,  Node: w,  Next: sp,  Prev: - and hyphenation,  Up: Breaks
+
+`@w'{TEXT}: Prevent Line Breaks
+===============================
+
+`@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
+
+  You can use the `@w' command to prevent TeX from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line.
+
+     You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
+
+produces
+
+     You can copy GNU software from `ftp.gnu.ai.mit.edu'.
+
+     *Caution:* Do not write an `@refill' command at the end of a
+     paragraph containing an `@w' command; it will cause the paragraph
+     to be refilled and may thereby negate the effect of the `@w'
+     command.
+
+\1f
+File: texinfo.info,  Node: sp,  Next: page,  Prev: w,  Up: Breaks
+
+`@sp' N: Insert Blank Lines
+===========================
+
+A line beginning with and containing only `@sp N' generates N blank
+lines of space in both the printed manual and the Info file.  `@sp'
+also forces a paragraph break.  For example,
+
+     @sp 2
+
+generates two blank lines.
+
+  The `@sp' command is most often used in the title page.
+
+\1f
+File: texinfo.info,  Node: page,  Next: group,  Prev: sp,  Up: Breaks
+
+`@page': Start a New Page
+=========================
+
+A line containing only `@page' starts a new page in a printed manual.
+The command has no effect on Info files since they are not paginated.
+An `@page' command is often used in the `@titlepage' section of a
+Texinfo file to start the copyright page.
+
+\1f
+File: texinfo.info,  Node: group,  Next: need,  Prev: page,  Up: Breaks
+
+`@group': Prevent Page Breaks
+=============================
+
+The `@group' command (on a line by itself) is used inside an `@example'
+or similar construct to begin an unsplittable vertical group, which
+will appear entirely on one page in the printed output.  The group is
+terminated by a line containing only `@end group'.  These two lines
+produce no output of their own, and in the Info file output they have
+no effect at all.
+
+  Although `@group' would make sense conceptually in a wide variety of
+contexts, its current implementation works reliably only within
+`@example' and variants, and within `@display', `@format', `@flushleft'
+and `@flushright'.  *Note Quotations and Examples::.  (What all these
+commands have in common is that each line of input produces a line of
+output.)  In other contexts, `@group' can cause anomalous vertical
+spacing.
+
+  This formatting requirement means that you should write:
+
+     @example
+     @group
+     ...
+     @end group
+     @end example
+
+with the `@group' and `@end group' commands inside the `@example' and
+`@end example' commands.
+
+  The `@group' command is most often used to hold an example together
+on one page.  In this Texinfo manual, more than 100 examples contain
+text that is enclosed between `@group' and `@end group'.
+
+  If you forget to end a group, you may get strange and unfathomable
+error messages when you run TeX.  This is because TeX keeps trying to
+put the rest of the Texinfo file onto the one page and does not start
+to generate error messages until it has processed considerable text.
+It is a good rule of thumb to look for a missing `@end group' if you
+get incomprehensible error messages in TeX.
+
+\1f
+File: texinfo.info,  Node: need,  Prev: group,  Up: Breaks
+
+`@need MILS': Prevent Page Breaks
+=================================
+
+A line containing only `@need N' starts a new page in a printed manual
+if fewer than N mils (thousandths of an inch) remain on the current
+page.  Do not use braces around the argument N.  The `@need' command
+has no effect on Info files since they are not paginated.
+
+  This paragraph is preceded by an `@need' command that tells TeX to
+start a new page if fewer than 800 mils (eight-tenths inch) remain on
+the page.  It looks like this:
+
+     @need 800
+     This paragraph is preceded by ...
+
+  The `@need' command is useful for preventing orphans (single lines at
+the bottoms of printed pages).
+
+\1f
+File: texinfo.info,  Node: Definition Commands,  Next: Footnotes,  Prev: Breaks,  Up: Top
+
+Definition Commands
+*******************
+
+The `@deffn' command and the other "definition commands" enable you to
+describe functions, variables, macros, commands, user options, special
+forms and other such artifacts in a uniform format.
+
+  In the Info file, a definition causes the entity
+category--`Function', `Variable', or whatever--to appear at the
+beginning of the first line of the definition, followed by the entity's
+name and arguments.  In the printed manual, the command causes TeX to
+print the entity's name and its arguments on the left margin and print
+the category next to the right margin.  In both output formats, the
+body of the definition is indented.  Also, the name of the entity is
+entered into the appropriate index: `@deffn' enters the name into the
+index of functions, `@defvr' enters it into the index of variables, and
+so on.
+
+  A manual need not and should not contain more than one definition for
+a given name.  An appendix containing a summary should use `@table'
+rather than the definition commands.
+
+* Menu:
+
+* Def Cmd Template::            How to structure a description using a
+                                  definition command.
+* Optional Arguments::          How to handle optional and repeated arguments.
+* deffnx::                      How to group two or more `first' lines.
+* Def Cmds in Detail::          All the definition commands.
+* Def Cmd Conventions::         Conventions for writing definitions.
+* Sample Function Definition::
+
+\1f
+File: texinfo.info,  Node: Def Cmd Template,  Next: Optional Arguments,  Prev: Definition Commands,  Up: Definition Commands
+
+The Template for a Definition
+=============================
+
+The `@deffn' command is used for definitions of entities that resemble
+functions.  To write a definition using the `@deffn' command, write the
+`@deffn' command at the beginning of a line and follow it on the same
+line by the category of the entity, the name of the entity itself, and
+its arguments (if any).  Then write the body of the definition on
+succeeding lines.  (You may embed examples in the body.)  Finally, end
+the definition with an `@end deffn' command written on a line of its
+own.  (The other definition commands follow the same format.)
+
+  The template for a definition looks like this:
+
+     @deffn CATEGORY NAME ARGUMENTS...
+     BODY-OF-DEFINITION
+     @end deffn
+
+For example,
+
+     @deffn Command forward-word count
+     This command moves point forward @var{count} words
+     (or backward if @var{count} is negative). ...
+     @end deffn
+
+produces
+
+      - Command: forward-word count
+          This function moves point forward COUNT words (or backward if
+          COUNT is negative). ...
+
+  Capitalize the category name like a title.  If the name of the
+category contains spaces, as in the phrase `Interactive Command', write
+braces around it.  For example:
+
+     @deffn {Interactive Command} isearch-forward
+     ...
+     @end deffn
+
+Otherwise, the second word will be mistaken for the name of the entity.
+
+  Some of the definition commands are more general than others.  The
+`@deffn' command, for example, is the general definition command for
+functions and the like--for entities that may take arguments.  When you
+use this command, you specify the category to which the entity belongs.
+The `@deffn' command possesses three predefined, specialized
+variations, `@defun', `@defmac', and `@defspec', that specify the
+category for you: "Function", "Macro", and "Special Form" respectively.
+(In Lisp, a special form is an entity much like a function.)  The
+`@defvr' command also is accompanied by several predefined, specialized
+variations for describing particular kinds of variables.
+
+  The template for a specialized definition, such as `@defun', is
+similar to the template for a generalized definition, except that you
+do not need to specify the category:
+
+     @defun NAME ARGUMENTS...
+     BODY-OF-DEFINITION
+     @end defun
+
+Thus,
+
+     @defun buffer-end flag
+     This function returns @code{(point-min)} if @var{flag}
+     is less than 1, @code{(point-max)} otherwise.
+     ...
+     @end defun
+
+produces
+
+      - Function: buffer-end flag
+          This function returns `(point-min)' if FLAG is less than 1,
+          `(point-max)' otherwise.  ...
+
+*Note Sample Function Definition: Sample Function Definition, for a
+more detailed example of a function definition, including the use of
+`@example' inside the definition.
+
+  The other specialized commands work like `@defun'.
+

diff --git a/info/texinfo.info-2 b/info/texinfo.info-2
index fc54512..cf8eff3 100644 (file)
--- a/info/texinfo.info-2
+++ b/info/texinfo.info-2
@@ -1,4 +1,4 @@
-This is ../info/texinfo.info, produced by makeinfo version 4.0 from
+This is ../info/texinfo.info, produced by makeinfo version 4.6 from

 texinfo.texi.
 
 INFO-DIR-SECTION Texinfo documentation system
 texinfo.texi.
 
 INFO-DIR-SECTION Texinfo documentation system

@@ -33,27 +33,3872 @@ versions, except that this permission notice may be stated in a
 translation approved by the Free Software Foundation.
 
 \1f
 translation approved by the Free Software Foundation.
 
 \1f

-File: texinfo.info,  Node: Short Sample,  Next: Acknowledgements,  Prev: Six Parts,  Up: Overview
+File: texinfo.info,  Node: Optional Arguments,  Next: deffnx,  Prev: Def Cmd Template,  Up: Definition Commands

 
 

-A Short Sample Texinfo File
+Optional and Repeated Arguments
+===============================
+
+Some entities take optional or repeated arguments, which may be
+specified by a distinctive glyph that uses square brackets and
+ellipses.  For example, a special form often breaks its argument list
+into separate arguments in more complicated ways than a straightforward
+function.
+
+  An argument enclosed within square brackets is optional.  Thus,
+[OPTIONAL-ARG] means that OPTIONAL-ARG is optional.  An argument
+followed by an ellipsis is optional and may be repeated more than once.
+Thus, REPEATED-ARGS... stands for zero or more arguments.  Parentheses
+are used when several arguments are grouped into additional levels of
+list structure in Lisp.
+
+  Here is the `@defspec' line of an example of an imaginary special
+form:
+
+      - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
+
+In this example, 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.
+
+  In a Texinfo source file, this `@defspec' line is written like this
+(except it would not be split over two lines, as it is in this example).
+
+     @defspec foobar (@var{var} [@var{from} @var{to}
+          [@var{inc}]]) @var{body}@dots{}
+
+The function is listed in the Command and Variable Index under `foobar'.
+
+\1f
+File: texinfo.info,  Node: deffnx,  Next: Def Cmds in Detail,  Prev: Optional Arguments,  Up: Definition Commands
+
+Two or More `First' Lines
+=========================
+
+To create two or more `first' or header lines for a definition, follow
+the first `@deffn' line by a line beginning with `@deffnx'.  The
+`@deffnx' command works exactly like `@deffn' except that it does not
+generate extra vertical white space between it and the preceding line.
+
+  For example,
+
+     @deffn {Interactive Command} isearch-forward
+     @deffnx {Interactive Command} isearch-backward
+     These two search commands are similar except ...
+     @end deffn
+
+produces
+
+ - Interactive Command: isearch-forward
+ - Interactive Command: isearch-backward
+     These two search commands are similar except ...
+
+  Each of the other definition commands has an `x' form: `@defunx',
+`@defvrx', `@deftypefunx', etc.
+
+  The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
+
+\1f
+File: texinfo.info,  Node: Def Cmds in Detail,  Next: Def Cmd Conventions,  Prev: deffnx,  Up: Definition Commands
+
+The Definition Commands
+=======================
+
+Texinfo provides more than a dozen definition commands, all of which
+are described in this section.
+
+  The definition commands automatically enter the name of the entity in
+the appropriate index: for example, `@deffn', `@defun', and `@defmac'
+enter function names in the index of functions; `@defvr' and `@defvar'
+enter variable names in the index of variables.
+
+  Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming languages.
+
+* Menu:
+
+* Functions Commands::          Commands for functions and similar entities.
+* Variables Commands::          Commands for variables and similar entities.
+* Typed Functions::             Commands for functions in typed languages.
+* Typed Variables::             Commands for variables in typed languages.
+* Abstract Objects::            Commands for object-oriented programming.
+* Data Types::                  The definition command for data types.
+
+\1f
+File: texinfo.info,  Node: Functions Commands,  Next: Variables Commands,  Prev: Def Cmds in Detail,  Up: Def Cmds in Detail
+
+Functions and Similar Entities
+------------------------------
+
+This section describes the commands for describing functions and similar
+entities:
+
+`@deffn CATEGORY NAME ARGUMENTS...'
+     The `@deffn' command is the general definition command for
+     functions, interactive commands, and similar entities that may take
+     arguments.  You must choose a term to describe the category of
+     entity being defined; for example, "Function" could be used if the
+     entity is a function.  The `@deffn' command is written at the
+     beginning of a line and is followed on the same line by the
+     category of entity being described, the name of this particular
+     entity, and its arguments, if any.  Terminate the definition with
+     `@end deffn' on a line of its own.
+
+     For example, here is a definition:
+
+          @deffn Command forward-char nchars
+          Move point forward @var{nchars} characters.
+          @end deffn
+
+     This shows a rather terse definition for a "command" named
+     `forward-char' with one argument, NCHARS.
+
+     `@deffn' prints argument names such as NCHARS in italics or upper
+     case, as if `@var' had been used, because we think of these names
+     as metasyntactic variables--they stand for the actual argument
+     values.  Within the text of the description, write an argument name
+     explicitly with `@var' to refer to the value of the argument.  In
+     the example above, we used `@var{nchars}' in this way.
+
+     The template for `@deffn' is:
+
+          @deffn CATEGORY NAME ARGUMENTS...
+          BODY-OF-DEFINITION
+          @end deffn
+
+`@defun NAME ARGUMENTS...'
+     The `@defun' command is the definition command for functions.
+     `@defun' is equivalent to `@deffn Function ...'.
+
+     For example,
+
+          @defun set symbol new-value
+          Change the value of the symbol @var{symbol}
+          to @var{new-value}.
+          @end defun
+
+     shows a rather terse definition for a function `set' whose
+     arguments are SYMBOL and NEW-VALUE.  The argument names on the
+     `@defun' line automatically appear in italics or upper case as if
+     they were enclosed in `@var'.  Terminate the definition with `@end
+     defun' on a line of its own.
+
+     The template is:
+
+          @defun FUNCTION-NAME ARGUMENTS...
+          BODY-OF-DEFINITION
+          @end defun
+
+     `@defun' creates an entry in the index of functions.
+
+`@defmac NAME ARGUMENTS...'
+     The `@defmac' command is the definition command for macros.
+     `@defmac' is equivalent to `@deffn Macro ...' and works like
+     `@defun'.
+
+`@defspec NAME ARGUMENTS...'
+     The `@defspec' command is the definition command for special
+     forms.  (In Lisp, a special form is an entity much like a function,
+     *note Special Forms: (lispref)Special Forms..)  `@defspec' is
+     equivalent to `@deffn {Special Form} ...' and works like `@defun'.
+
+\1f
+File: texinfo.info,  Node: Variables Commands,  Next: Typed Functions,  Prev: Functions Commands,  Up: Def Cmds in Detail
+
+Variables and Similar Entities
+------------------------------
+
+Here are the commands for defining variables and similar entities:
+
+`@defvr CATEGORY NAME'
+     The `@defvr' command is a general definition command for something
+     like a variable--an entity that records a value.  You must choose
+     a term to describe the category of entity being defined; for
+     example, "Variable" could be used if the entity is a variable.
+     Write the `@defvr' command at the beginning of a line and followed
+     it on the same line by the category of the entity and the name of
+     the entity.
+
+     Capitalize the category name like a title.  If the name of the
+     category contains spaces, as in the name "User Option", enclose it
+     in braces.  Otherwise, the second word will be mistaken for the
+     name of the entity.  For example,
+
+          @defvr {User Option} fill-column
+          This buffer-local variable specifies
+          the maximum width of filled lines.
+          ...
+          @end defvr
+
+     Terminate the definition with `@end defvr' on a line of its own.
+
+     The template is:
+
+          @defvr CATEGORY NAME
+          BODY-OF-DEFINITION
+          @end defvr
+
+     `@defvr' creates an entry in the index of variables for NAME.
+
+`@defvar NAME'
+     The `@defvar' command is the definition command for variables.
+     `@defvar' is equivalent to `@defvr Variable ...'.
+
+     For example:
+
+          @defvar kill-ring
+          ...
+          @end defvar
+
+     The template is:
+
+          @defvar NAME
+          BODY-OF-DEFINITION
+          @end defvar
+
+     `@defvar' creates an entry in the index of variables for NAME.
+
+`@defopt NAME'
+     The `@defopt' command is the definition command for "user
+     options", i.e., variables intended for users to change according to
+     taste; Emacs has many such (*note Variables: (xemacs)Variables.).
+     `@defopt' is equivalent to `@defvr {User Option} ...' and works
+     like `@defvar'.
+
+\1f
+File: texinfo.info,  Node: Typed Functions,  Next: Typed Variables,  Prev: Variables Commands,  Up: Def Cmds in Detail
+
+Functions in Typed Languages
+----------------------------
+
+The `@deftypefn' command and its variations are for describing
+functions in languages in which you must declare types of variables and
+functions, such as C and C++.
+
+`@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
+     The `@deftypefn' command is the general definition command for
+     functions and similar entities that may take arguments and that are
+     typed.  The `@deftypefn' command is written at the beginning of a
+     line and is followed on the same line by the category of entity
+     being described, the type of the returned value, the name of this
+     particular entity, and its arguments, if any.
+
+     For example,
+
+          @deftypefn {Library Function} int foobar
+             (int @var{foo}, float @var{bar})
+          ...
+          @end deftypefn
+
+     (where the text before the "...", shown above as two lines, would
+     actually be a single line in a real Texinfo file) produces the
+     following in Info:
+
+          -- Library Function: int foobar (int FOO, float BAR)
+          ...
+
+     This means that `foobar' is a "library function" that returns an
+     `int', and its arguments are FOO (an `int') and BAR (a `float').
+
+     The argument names that you write in `@deftypefn' are not subject
+     to an implicit `@var'--since the actual names of the arguments in
+     `@deftypefn' are typically scattered among data type names and
+     keywords, Texinfo cannot find them without help.  Instead, you
+     must write `@var' explicitly around the argument names.  In the
+     example above, the argument names are `foo' and `bar'.
+
+     The template for `@deftypefn' is:
+
+          @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
+          BODY-OF-DESCRIPTION
+          @end deftypefn
+
+     Note that if the CATEGORY or DATA TYPE is more than one word then
+     it must be enclosed in braces to make it a single argument.
+
+     If you are describing a procedure in a language that has packages,
+     such as Ada, you might consider using `@deftypefn' in a manner
+     somewhat contrary to the convention described in the preceding
+     paragraphs.
+
+     For example:
+
+          @deftypefn stacks private push
+                  (@var{s}:in out stack;
+                  @var{n}:in integer)
+          ...
+          @end deftypefn
+
+     (The `@deftypefn' arguments are shown split into three lines, but
+     would be a single line in a real Texinfo file.)
+
+     In this instance, the procedure is classified as belonging to the
+     package `stacks' rather than classified as a `procedure' and its
+     data type is described as `private'.  (The name of the procedure
+     is `push', and its arguments are S and N.)
+
+     `@deftypefn' creates an entry in the index of functions for NAME.
+
+`@deftypefun DATA-TYPE NAME ARGUMENTS...'
+     The `@deftypefun' command is the specialized definition command
+     for functions in typed languages.  The command is equivalent to
+     `@deftypefn Function ...'.
+
+     Thus,
+
+          @deftypefun int foobar (int @var{foo}, float @var{bar})
+          ...
+          @end deftypefun
+
+     produces the following in Info:
+
+          -- Function: int foobar (int FOO, float BAR)
+          ...
+
+     The template is:
+
+          @deftypefun TYPE NAME ARGUMENTS...
+          BODY-OF-DESCRIPTION
+          @end deftypefun
+
+     `@deftypefun' creates an entry in the index of functions for NAME.
+
+
+\1f
+File: texinfo.info,  Node: Typed Variables,  Next: Abstract Objects,  Prev: Typed Functions,  Up: Def Cmds in Detail
+
+Variables in Typed Languages
+----------------------------
+
+Variables in typed languages are handled in a manner similar to
+functions in typed languages.  *Note Typed Functions::.  The general
+definition command `@deftypevr' corresponds to `@deftypefn' and the
+specialized definition command `@deftypevar' corresponds to
+`@deftypefun'.
+
+`@deftypevr CATEGORY DATA-TYPE NAME'
+     The `@deftypevr' command is the general definition command for
+     something like a variable in a typed language--an entity that
+     records a value.  You must choose a term to describe the category
+     of the entity being defined; for example, "Variable" could be used
+     if the entity is a variable.
+
+     The `@deftypevr' command is written at the beginning of a line and
+     is followed on the same line by the category of the entity being
+     described, the data type, and the name of this particular entity.
+
+     For example:
+
+          @deftypevr {Global Flag} int enable
+          ...
+          @end deftypevr
+
+     produces the following in Info:
+
+          -- Global Flag: int enable
+          ...
+
+     The template is:
+
+          @deftypevr CATEGORY DATA-TYPE NAME
+          BODY-OF-DESCRIPTION
+          @end deftypevr
+
+     `@deftypevr' creates an entry in the index of variables for NAME.
+
+`@deftypevar DATA-TYPE NAME'
+     The `@deftypevar' command is the specialized definition command
+     for variables in typed languages.  `@deftypevar' is equivalent to
+     `@deftypevr Variable ...'.
+
+     For example:
+
+          @deftypevar int fubar
+          ...
+          @end deftypevar
+
+     produces the following in Info:
+
+          -- Variable: int fubar
+          ...
+
+     The template is:
+
+          @deftypevar DATA-TYPE NAME
+          BODY-OF-DESCRIPTION
+          @end deftypevar
+
+     `@deftypevar' creates an entry in the index of variables for NAME.
+
+\1f
+File: texinfo.info,  Node: Abstract Objects,  Next: Data Types,  Prev: Typed Variables,  Up: Def Cmds in Detail
+
+Object-Oriented Programming
+---------------------------
+
+Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming.  A class is a
+defined type of abstract object.  An instance of a class is a
+particular object that has the type of the class.  An instance variable
+is a variable that belongs to the class but for which each instance has
+its own value.
+
+  In a definition, if the name of a class is truly a name defined in the
+programming system for a class, then you should write an `@code' around
+it.  Otherwise, it is printed in the usual text font.
+
+`@defcv CATEGORY CLASS NAME'
+     The `@defcv' command is the general definition command for
+     variables associated with classes in object-oriented programming.
+     The `@defcv' command is followed by three arguments: the category
+     of thing being defined, the class to which it belongs, and its
+     name.  Thus,
+
+          @defcv {Class Option} Window border-pattern
+          ...
+          @end defcv
+
+     illustrates how you would write the first line of a definition of
+     the `border-pattern' class option of the class `Window'.
+
+     The template is
+
+          @defcv CATEGORY CLASS NAME
+          ...
+          @end defcv
+
+     `@defcv' creates an entry in the index of variables.
+
+`@defivar CLASS NAME'
+     The `@defivar' command is the definition command for instance
+     variables in object-oriented programming.  `@defivar' is
+     equivalent to `@defcv {Instance Variable} ...'
+
+     The template is:
+
+          @defivar CLASS INSTANCE-VARIABLE-NAME
+          BODY-OF-DEFINITION
+          @end defivar
+
+     `@defivar' creates an entry in the index of variables.
+
+`@defop CATEGORY CLASS NAME ARGUMENTS...'
+     The `@defop' command is the general definition command for
+     entities that may resemble methods in object-oriented programming.
+     These entities take arguments, as functions do, but are associated
+     with particular classes of objects.
+
+     For example, some systems have constructs called "wrappers" that
+     are associated with classes as methods are, but that act more like
+     macros than like functions.  You could use `@defop Wrapper' to
+     describe one of these.
+
+     Sometimes it is useful to distinguish methods and "operations".
+     You can think of an operation as the specification for a method.
+     Thus, a window system might specify that all window classes have a
+     method named `expose'; we would say that this window system
+     defines an `expose' operation on windows in general.  Typically,
+     the operation has a name and also specifies the pattern of
+     arguments; all methods that implement the operation must accept
+     the same arguments, since applications that use the operation do
+     so without knowing which method will implement it.
+
+     Often it makes more sense to document operations than methods.  For
+     example, window application developers need to know about the
+     `expose' operation, but need not be concerned with whether a given
+     class of windows has its own method to implement this operation.
+     To describe this operation, you would write:
+
+          @defop Operation windows expose
+
+     The `@defop' command is written at the beginning of a line and is
+     followed on the same line by the overall name of the category of
+     operation, the name of the class of the operation, the name of the
+     operation, and its arguments, if any.
+
+     The template is:
+
+          @defop CATEGORY CLASS NAME ARGUMENTS...
+          BODY-OF-DEFINITION
+          @end defop
+
+     `@defop' creates an entry, such as ``expose' on `windows'', in the
+     index of functions.
+
+`@defmethod CLASS NAME ARGUMENTS...'
+     The `@defmethod' command is the definition command for methods in
+     object-oriented programming.  A method is a kind of function that
+     implements an operation for a particular class of objects and its
+     subclasses.  In the Lisp Machine, methods actually were functions,
+     but they were usually defined with `defmethod'.
+
+     `@defmethod' is equivalent to `@defop Method ...'.  The command is
+     written at the beginning of a line and is followed by the name of
+     the class of the method, the name of the method, and its
+     arguments, if any.
+
+     For example,
+
+          @defmethod `bar-class' bar-method argument
+          ...
+          @end defmethod
+
+     illustrates the definition for a method called `bar-method' of the
+     class `bar-class'.  The method takes an argument.
+
+     The template is:
+
+          @defmethod CLASS METHOD-NAME ARGUMENTS...
+          BODY-OF-DEFINITION
+          @end defmethod
+
+     `@defmethod' creates an entry, such as ``bar-method' on
+     `bar-class'', in the index of functions.
+
+`@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
+     The `@deftypemethod' command is the definition command for methods
+     in object-oriented typed languages, such as C++ and Java.  It is
+     similar to the `@defmethod' command with the addition of the
+     DATA-TYPE parameter to specify the return type of the method.
+
+
+\1f
+File: texinfo.info,  Node: Data Types,  Prev: Abstract Objects,  Up: Def Cmds in Detail
+
+Data Types
+----------
+
+Here is the command for data types:
+
+`@deftp CATEGORY NAME ATTRIBUTES...'
+     The `@deftp' command is the generic definition command for data
+     types.  The command is written at the beginning of a line and is
+     followed on the same line by the category, by the name of the type
+     (which is a word like `int' or `float'), and then by names of
+     attributes of objects of that type.  Thus, you could use this
+     command for describing `int' or `float', in which case you could
+     use `data type' as the category.  (A data type is a category of
+     certain objects for purposes of deciding which operations can be
+     performed on them.)
+
+     In Lisp, for example,  "pair" names a particular data type, and an
+     object of that type has two slots called the CAR and the CDR.
+     Here is how you would write the first line of a definition of
+     `pair'.
+
+          @deftp {Data type} pair car cdr
+          ...
+          @end deftp
+
+     The template is:
+
+          @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
+          BODY-OF-DEFINITION
+          @end deftp
+
+     `@deftp' creates an entry in the index of data types.
+
+\1f
+File: texinfo.info,  Node: Def Cmd Conventions,  Next: Sample Function Definition,  Prev: Def Cmds in Detail,  Up: Definition Commands
+
+Conventions for Writing Definitions
+===================================
+
+When you write a definition using `@deffn', `@defun', or one of the
+other definition commands, please take care to use arguments that
+indicate the meaning, as with the COUNT argument to the `forward-word'
+function.  Also, if the name of an argument contains the name of a
+type, such as INTEGER, take care that the argument actually is of that
+type.
+
+\1f
+File: texinfo.info,  Node: Sample Function Definition,  Prev: Def Cmd Conventions,  Up: Definition Commands
+
+A Sample Function Definition
+============================
+
+A function definition uses the `@defun' and `@end defun' commands.  The
+name of the function follows immediately after the `@defun' command and
+it is followed, on the same line, by the parameter list.
+
+  Here is a definition from *Note Calling Functions: (lispref)Calling
+Functions.
+
+      - 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 this list is "appended" to the other
+          arguments.
+
+          `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)
+
+          An interesting example of using `apply' is found in the
+          description of `mapcar'.
+
+  In the Texinfo source file, this example looks like this:
+
+     @defun apply function &rest arguments
+     
+     @code{apply} calls @var{function} with
+     @var{arguments}, just like @code{funcall} but with one
+     difference: the last of @var{arguments} is a list of
+     arguments to give to @var{function}, rather than a single
+     argument.  We also say that this list is @dfn{appended}
+     to the other arguments.
+     
+     @code{apply} returns the result of calling
+     @var{function}.  As with @code{funcall},
+     @var{function} must either be a Lisp function or a
+     primitive function; special forms and macros do not make
+     sense in @code{apply}.
+     
+     @example
+     (setq f 'list)
+          @result{} list
+     (apply f 'x 'y 'z)
+     @error{} Wrong type argument: listp, z
+     (apply '+ 1 2 '(3 4))
+          @result{} 10
+     (apply '+ '(1 2 3 4))
+          @result{} 10
+     
+     (apply 'append '((a b c) nil (x y z) nil))
+          @result{} (a b c x y z)
+     @end example
+     
+     An interesting example of using @code{apply} is found
+     in the description of @code{mapcar}.@refill
+     @end defun
+
+In this manual, this function is listed in the Command and Variable
+Index under `apply'.
+
+  Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+\1f
+File: texinfo.info,  Node: Footnotes,  Next: Conditionals,  Prev: Definition Commands,  Up: Top
+
+Footnotes
+*********
+
+A "footnote" is for a reference that documents or elucidates the
+primary text.(1) (*note Footnotes-Footnote-1::)
+
+* Menu:
+
+* Footnote Commands::           How to write a footnote in Texinfo.
+* Footnote Styles::             Controlling how footnotes appear in Info.
+
+\1f
+File: texinfo.info,  Node: Footnotes-Footnotes,  Up: Footnotes
+
+  (1) A footnote should complement or expand upon the primary text, but
+a reader should not need to read a footnote to understand the primary
+text.  For a thorough discussion of footnotes, see `The Chicago Manual
+of Style', which is published by the University of Chicago Press.
+
+\1f
+File: texinfo.info,  Node: Footnote Commands,  Next: Footnote Styles,  Prev: Footnotes,  Up: Footnotes
+
+Footnote Commands
+=================
+
+In Texinfo, footnotes are created with the `@footnote' command.  This
+command is followed immediately by a left brace, then by the text of
+the footnote, and then by a terminating right brace.  Footnotes may be
+of any length (they will be broken across pages if necessary), but are
+usually short.  The template is:
+
+     ordinary text@footnote{TEXT OF FOOTNOTE}
+
+  As shown here, the `@footnote' command should come right after the
+text being footnoted, with no intervening space; otherwise, the
+formatters the footnote mark might end up starting up a line.
+
+  For example, this clause is followed by a sample footnote(1) (*note
+Footnote Commands-Footnote-1::); in the Texinfo source, it looks like
+this:
+
+     ...a sample footnote@footnote{Here is the sample
+     footnote.}; in the Texinfo source...
+
+  *Warning:* Don't use footnotes in the argument of the `@item' command
+for a `@table' table.  This doesn't work, and because of limitations of
+TeX, there is no way to fix it.  You must put the footnote into the
+body text of the table.
+
+  In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+  In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: `(1)'.
+
+\1f
+File: texinfo.info,  Node: Footnote Commands-Footnotes,  Up: Footnote Commands
+
+  (1) Here is the sample footnote.
+
+\1f
+File: texinfo.info,  Node: Footnote Styles,  Prev: Footnote Commands,  Up: Footnotes
+
+Footnote Styles
+===============
+
+Info has two footnote styles, which determine where the text of the
+footnote is located:
+
+   * In the `End' node style, all the footnotes for a single node are
+     placed at the end of that node.  The footnotes are separated from
+     the rest of the node by a line of dashes with the word `Footnotes'
+     within it.  Each footnote begins with an `(N)' reference mark.
+
+     Here is an example of a single footnote in the end of node style:
+
+           --------- Footnotes ---------
+          
+          (1)  Here is a sample footnote.
+
+   * In the `Separate' node style, all the footnotes for a single node
+     are placed in an automatically constructed node of their own.  In
+     this style, a "footnote reference" follows each `(N)' reference
+     mark in the body of the node.  The footnote reference is actually
+     a cross reference which you use to reach the footnote node.
+
+     The name of the node containing the footnotes is constructed by
+     appending `-Footnotes' to the name of the node that contains the
+     footnotes. (Consequently, the footnotes' node for the `Footnotes'
+     node is `Footnotes-Footnotes'!)  The footnotes' node has an `Up'
+     node pointer that leads back to its parent node.
+
+     Here is how the first footnote in this manual looks after being
+     formatted for Info in the separate node style:
+
+          File: texinfo.info  Node: Overview-Footnotes, Up: Overview
+          
+          (1) Note that the first syllable of "Texinfo" is
+          pronounced like "speck", not "hex". ...
+
+  A Texinfo file may be formatted into an Info file with either footnote
+style.
+
+  Use the `@footnotestyle' command to specify an Info file's footnote
+style.  Write this command at the beginning of a line followed by an
+argument, either `end' for the end node style or `separate' for the
+separate node style.
+
+  For example,
+
+     @footnotestyle end
+
+or
+     @footnotestyle separate
+
+  Write an `@footnotestyle' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file.  (If you include
+the `@footnotestyle' command between the start-of-header and
+end-of-header lines, the region formatting commands will format
+footnotes as specified.)
+
+  If you do not specify a footnote style, the formatting commands use
+their default style.  Currently, `texinfo-format-buffer' and
+`texinfo-format-region' use the `separate' style and `makeinfo' uses
+the `end' style.
+
+  This chapter contains two footnotes.
+
+\1f
+File: texinfo.info,  Node: Conditionals,  Next: Macros,  Prev: Footnotes,  Up: Top
+
+Conditionally Visible Text
+**************************
+
+Sometimes it is good to use different text for a printed manual and its
+corresponding Info file.  In this case, you can use the "conditional
+commands" to specify which text is for the printed manual and which is
+for the Info file.
+
+* Menu:
+
+* Conditional Commands::        Specifying text for HTML, Info, or TeX.
+* Conditional Not Commands::    Specifying text for not HTML, Info, or TeX.
+* Raw Formatter Commands::      Using raw TeX or HTML commands.
+* set clear value::             Designating which text to format (for
+                                  all output formats); and how to set a
+                                  flag to a string that you can insert.
+
+\1f
+File: texinfo.info,  Node: Conditional Commands,  Next: Conditional Not Commands,  Prev: Conditionals,  Up: Conditionals
+
+Conditional Commands
+====================
+
+  `@ifinfo' begins segments of text that should be ignored by TeX when
+it typesets the printed manual.  The segment of text appears only in
+the Info file.  The `@ifinfo' command should appear on a line by
+itself;  end the Info-only text with a line containing `@end ifinfo' by
+itself.  At the beginning of a Texinfo file, the Info permissions are
+contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
+Info Summary and Permissions::.)
+
+  The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
+and `@end ifinfo' commands, except that they specify text that will
+appear in the printed manual but not in the Info file.  Likewise for
+`@ifhtml' and `@end ifhtml', which specify text to appear only in HTML
+output.
+
+  For example,
+
+     @iftex
+     This text will appear only in the printed manual.
+     @end iftex
+     @ifinfo
+     However, this text will appear only in Info.
+     @end ifinfo
+
+The preceding example produces the following line: However, this text
+will appear only in Info.
+
+Note how you only see one of the two lines, depending on whether you
+are reading the Info version or the printed version of this manual.
+
+  The `@titlepage' command is a special variant of `@iftex' that is
+used for making the title and copyright pages of the printed manual.
+(*Note `@titlepage': titlepage.)
+
+\1f
+File: texinfo.info,  Node: Conditional Not Commands,  Next: Raw Formatter Commands,  Prev: Conditional Commands,  Up: Conditionals
+
+Conditional Not Commands
+========================
+
+You can specify text to be included in any output format _other_ than
+some given one with the `@ifnot...' commands:
+     @ifnothtml ... @end ifnothtml
+     @ifnotinfo ... @end ifnotinfo
+     @ifnottex ... @end ifnottex
+
+(The `@ifnot...' command and the `@end' command must actually appear on
+lines by themselves.)
+
+  If the output file is not being made for the given format, the region
+is included.  Otherwise, it is ignored.
+
+  The regions delimited by these commands are ordinary Texinfo source as
+with `@iftex', not raw formatter source as with `@tex'.
+
+\1f
+File: texinfo.info,  Node: Raw Formatter Commands,  Next: set clear value,  Prev: Conditional Not Commands,  Up: Conditionals
+
+Raw Formatter Commands
+======================
+
+Inside a region delineated by `@iftex' and `@end iftex', you can embed
+some raw TeX commands.  Info will ignore these commands since they are
+only in that part of the file which is seen by TeX.  You can write the
+TeX commands as you would write them in a normal TeX file, except that
+you must replace the `\' used by TeX with an `@'.  For example, in the
+`@titlepage' section of a Texinfo file, you can use the TeX command
+`@vskip' to format the copyright page.  (The `@titlepage' command
+causes Info to ignore the region automatically, as it does with the
+`@iftex' command.)
+
+  However, many features of plain TeX will not work, as they are
+overridden by Texinfo features.
+
+  You can enter plain TeX completely, and use `\' in the TeX commands,
+by delineating a region with the `@tex' and `@end tex' commands.  (The
+`@tex' command also causes Info to ignore the region, like the `@iftex'
+command.)  The sole exception is that `@' chracter still introduces a
+command, so that `@end tex' can be recognized properly.
+
+  For example, here is a mathematical expression written in plain TeX:
+
+     @tex
+     $$ \chi^2 = \sum_{i=1}^N
+               \left (y_i - (a + b x_i)
+               \over \sigma_i\right)^2 $$
+     @end tex
+
+The output of this example will appear only in a printed manual.  If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+
+  Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
+region to be included in HTML output only, and `@html ...  @end ifhtml'
+for a region of raw HTML (again, except that `@' is still the escape
+character, so the `@end' command can be recognized.)
+
+\1f
+File: texinfo.info,  Node: set clear value,  Prev: Raw Formatter Commands,  Up: Conditionals
+
+`@set', `@clear', and `@value'
+==============================
+
+You can direct the Texinfo formatting commands to format or ignore parts
+of a Texinfo file with the `@set', `@clear', `@ifset', and `@ifclear'
+commands.
+
+  In addition, you can use the `@set FLAG' command to set the value of
+FLAG to a string of characters; and use `@value{FLAG}' to insert that
+string.  You can use `@set', for example, to set a date and use
+`@value' to insert the date in several places in the Texinfo file.
+
+* Menu:
+
+* ifset ifclear::               Format a region if a flag is set.
+* value::                       Replace a flag with a string.
+* value Example::               An easy way to update edition information.
+
+\1f
+File: texinfo.info,  Node: ifset ifclear,  Next: value,  Prev: set clear value,  Up: set clear value
+
+`@ifset' and `@ifclear'
+-----------------------
+
+When a FLAG is set, the Texinfo formatting commands format text between
+subsequent pairs of `@ifset FLAG' and `@end ifset' commands.  When the
+FLAG is cleared, the Texinfo formatting commands do _not_ format the
+text.
+
+  Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
+can be any single word.  The format for the command looks like this:
+
+     @set FLAG
+
+  Write the conditionally formatted text between `@ifset FLAG' and
+`@end ifset' commands, like this:
+
+     @ifset FLAG
+     CONDITIONAL-TEXT
+     @end ifset
+
+  For example, you can create one document that has two variants, such
+as a manual for a `large' and `small' model:
+
+     You can use this machine to dig up shrubs
+     without hurting them.
+     
+     @set large
+     
+     @ifset large
+     It can also dig up fully grown trees.
+     @end ifset
+     
+     Remember to replant promptly ...
+
+In the example, the formatting commands will format the text between
+`@ifset large' and `@end ifset' because the `large' flag is set.
+
+  Use the `@clear FLAG' command to turn off, or "clear", a flag.
+Clearing a flag is the opposite of setting a flag.  The command looks
+like this:
+
+     @clear FLAG
+
+Write the command on a line of its own.
+
+  When FLAG is cleared, the Texinfo formatting commands do _not_ format
+the text between `@ifset FLAG' and `@end ifset'; that text is ignored
+and does not appear in either printed or Info output.
+
+  For example, if you clear the flag of the preceding example by writing
+an `@clear large' command after the `@set large' command (but before
+the conditional text), then the Texinfo formatting commands ignore the
+text between the `@ifset large' and `@end ifset' commands.  In the
+formatted output, that text does not appear; in both printed and Info
+output, you see only the lines that say, "You can use this machine to
+dig up shrubs without hurting them.  Remember to replant promptly ...".
+
+  If a flag is cleared with an `@clear FLAG' command, then the
+formatting commands format text between subsequent pairs of `@ifclear'
+and `@end ifclear' commands.  But if the flag is set with `@set FLAG',
+then the formatting commands do _not_ format text between an `@ifclear'
+and an `@end ifclear' command; rather, they ignore that text.  An
+`@ifclear' command looks like this:
+
+     @ifclear FLAG
+
+  In brief, the commands are:
+
+`@set FLAG'
+     Tell the Texinfo formatting commands that FLAG is set.
+
+`@clear FLAG'
+     Tell the Texinfo formatting commands that FLAG is cleared.
+
+`@ifset FLAG'
+     If FLAG is set, tell the Texinfo formatting commands to format the
+     text up to the following `@end ifset' command.
+
+     If FLAG is cleared, tell the Texinfo formatting commands to ignore
+     text up to the following `@end ifset' command.
+
+`@ifclear FLAG'
+     If FLAG is set, tell the Texinfo formatting commands to ignore the
+     text up to the following `@end ifclear' command.
+
+     If FLAG is cleared, tell the Texinfo formatting commands to format
+     the text up to the following `@end ifclear' command.
+
+\1f
+File: texinfo.info,  Node: value,  Next: value Example,  Prev: ifset ifclear,  Up: set clear value
+
+`@value'
+--------
+
+You can use the `@set' command to specify a value for a flag, which is
+expanded by the `@value' command.  The value is a string a characters.
+
+  Write the `@set' command like this:
+
+     @set foo This is a string.
+
+This sets the value of `foo' to "This is a string."
+
+  The Texinfo formatters replace an `@value{FLAG}' command with the
+string to which FLAG is set.
+
+  Thus, when `foo' is set as shown above, the Texinfo formatters convert
+
+     @value{foo}
+to
+     This is a string.
+
+  You can write an `@value' command within a paragraph; but you must
+write an `@set' command on a line of its own.
+
+  If you write the `@set' command like this:
+
+     @set foo
+
+without specifying a string, the value of `foo' is an empty string.
+
+  If you clear a previously set flag with an `@clear FLAG' command, a
+subsequent `@value{flag}' command is invalid and the string is replaced
+with an error message that says `{No value for "FLAG"}'.
+
+  For example, if you set `foo' as follows:
+
+     @set how-much very, very, very
+
+then the formatters transform
+
+     It is a @value{how-much} wet day.
+into
+     It is a very, very, very wet day.
+
+  If you write
+
+     @clear how-much
+
+then the formatters transform
+
+     It is a @value{how-much} wet day.
+into
+     It is a {No value for "how-much"} wet day.
+
+\1f
+File: texinfo.info,  Node: value Example,  Prev: value,  Up: set clear value
+
+`@value' Example
+----------------
+
+You can use the `@value' command to limit the number of places you need
+to change when you record an update to a manual.  Here is how it is
+done in `The GNU Make Manual':
+
+Set the flags:
+
+     @set EDITION 0.35 Beta
+     @set VERSION 3.63 Beta
+     @set UPDATED 14 August 1992
+     @set UPDATE-MONTH August 1992
+
+Write text for the first `@ifinfo' section, for people reading the
+Texinfo file:
+
+     This is Edition @value{EDITION},
+     last updated @value{UPDATED},
+     of @cite{The GNU Make Manual},
+     for @code{make}, Version @value{VERSION}.
+
+Write text for the title page, for people reading the printed manual:
+
+     @title GNU Make
+     @subtitle A Program for Directing Recompilation
+     @subtitle Edition @value{EDITION}, ...
+     @subtitle @value{UPDATE-MONTH}
+
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
+Write text for the Top node, for people reading the Info file:
+
+     This is Edition @value{EDITION}
+     of the @cite{GNU Make Manual},
+     last updated @value{UPDATED}
+     for @code{make} Version @value{VERSION}.
+
+  After you format the manual, the text in the first `@ifinfo' section
+looks like this:
+
+     This is Edition 0.35 Beta, last updated 14 August 1992,
+     of `The GNU Make Manual', for `make', Version 3.63 Beta.
+
+  When you update the manual, change only the values of the flags; you
+do not need to rewrite the three sections.
+
+\1f
+File: texinfo.info,  Node: Macros,  Next: Format/Print Hardcopy,  Prev: Conditionals,  Up: Top
+
+Macros: Defining New Texinfo Commands
+*************************************
+
+A Texinfo "macro" allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros).  The
+macro can have any number of "parameters"--text you supply each time
+you use the macro.  (This has nothing to do with the `@defmac' command,
+which is for documenting macros in the subject of the manual; *note Def
+Cmd Template::.)
+
+* Menu:
+
+* Defining Macros::             Both defining and undefining new commands.
+* Invoking Macros::             Using a macro, once you've defined it.
+
+\1f
+File: texinfo.info,  Node: Defining Macros,  Next: Invoking Macros,  Prev: Macros,  Up: Macros
+
+Defining Macros
+===============
+
+You use the Texinfo `@macro' command to define a macro.  For example:
+
+     @macro MACRO-NAME{PARAM1, PARAM2, ...}
+     TEXT ... \PARAM1\ ...
+     @end macro
+
+  The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
+when the macro is subsequently used in the document (see the next
+section).
+
+  If a macro needs no parameters, you can define it either with an empty
+list (`@macro foo {}') or with no braces at all (`@macro foo').
+
+  The definition or "body" of the macro can contain any Texinfo
+commands, including previously-defined macros.  (It is not possible to
+have mutually recursive Texinfo macros.)  In the body, instances of a
+parameter name surrounded by backslashes, as in `\PARAM1\' in the
+example above, are replaced by the corresponding argument from the
+macro invocation.
+
+  You can undefine a macro FOO with `@unmacro FOO'.  It is not an error
+to undefine a macro that is already undefined.  For example:
+
+     @unmacro foo
+
+\1f
+File: texinfo.info,  Node: Invoking Macros,  Prev: Defining Macros,  Up: Macros
+
+Invoking Macros
+===============
+
+After a macro is defined (see the previous section), you can use
+("invoke") it in your document like this:
+
+     @MACRO-NAME {ARG1, ARG2, ...}
+
+and the result will be just as if you typed the body of MACRO-NAME at
+that spot.  For example:
+
+     @macro foo {p, q}
+     Together: \p\ & \q\.
+     @end macro
+     @foo{a, b}
+
+produces:
+
+     Together: a & b.
+
+  Thus, the arguments and parameters are separated by commas and
+delimited by braces; any whitespace after (but not before) a comma is
+ignored.  To insert a comma, brace, or backslash in an argument,
+prepend a backslash, as in
+
+     @MACRO-NAME {\\\{\}\,}
+
+which will pass the (almost certainly error-producing) argument `\{},'
+to MACRO-NAME.
+
+  If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument.  For example:
+
+     @macro bar {p}
+     Twice: \p\, \p\.
+     @end macro
+     @bar aah
+
+produces:
+
+     Twice: aah, aah.
+
+\1f
+File: texinfo.info,  Node: Format/Print Hardcopy,  Next: Create an Info File,  Prev: Macros,  Up: Top
+
+Format and Print Hardcopy
+*************************
+
+There are three major shell commands for making a printed manual from a
+Texinfo file: one for converting the Texinfo file into a file that will
+be printed, a second for sorting indices, and a third for printing the
+formatted document.  When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside GNU Emacs.
+
+  If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands.  In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
+* Menu:
+
+* Use TeX::                     Use TeX to format for hardcopy.
+* Format with tex/texindex::    How to format in a shell.
+* Format with texi2dvi::        A simpler way to use the shell.
+* Print with lpr::              How to print.
+* Within Emacs::                How to format and print from an Emacs shell.
+* Texinfo Mode Printing::       How to format and print in Texinfo mode.
+* Compile-Command::             How to print using Emacs's compile command.
+* Requirements Summary::        TeX formatting requirements summary.
+* Preparing for TeX::           What you need to do to use TeX.
+* Overfull hboxes::             What are and what to do with overfull hboxes.
+* smallbook::                   How to print small format books and manuals.
+* A4 Paper::                    How to print on European A4 paper.
+* Cropmarks and Magnification::  How to print marks to indicate the size
+                                of pages and how to print scaled up output.
+
+\1f
+File: texinfo.info,  Node: Use TeX,  Next: Format with tex/texindex,  Prev: Format/Print Hardcopy,  Up: Format/Print Hardcopy
+
+Use TeX
+=======
+
+  The typesetting program called TeX is used for formatting a Texinfo
+file.  TeX is a very powerful typesetting program and, if used right,
+does an exceptionally good job.  (*Note How to Obtain TeX: Obtaining
+TeX, for information on how to obtain TeX.)
+
+  The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer'
+commands read the very same @-commands in the Texinfo file as does TeX,
+but process them differently to make an Info file; see *Note Create an
+Info File::.
+
+\1f
+File: texinfo.info,  Node: Format with tex/texindex,  Next: Format with texi2dvi,  Prev: Use TeX,  Up: Format/Print Hardcopy
+
+Format using `tex' and `texindex'
+=================================
+
+Format the Texinfo file with the shell command `tex' followed by the
+name of the Texinfo file.  For example:
+
+     tex foo.texi
+
+TeX will produce a "DVI file" as well as several auxiliary files
+containing information for indices, cross references, etc.  The DVI
+file (for "DeVice Independent" file) can be printed on virtually any
+printe (see the following sections).
+
+  The `tex' formatting command itself does not sort the indices; it
+writes an output file of unsorted index data.  (The `texi2dvi' command
+automatically generates indices; see *Note Format using `texi2dvi':
+Format with texi2dvi.)  To generate a printed index after running the
+`tex' command, you first need a sorted index to work from.  The
+`texindex' command sorts indices.  (The source file `texindex.c' comes
+as part of the standard Texinfo distribution, among other places.)
+
+  The `tex' formatting command outputs unsorted index files under names
+that obey a standard convention: the name of your main input file with
+any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.)
+extension removed, followed by the two letter names of indices.  For
+example, the raw index output files for the input file `foo.texinfo'
+would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.
+Those are exactly the arguments to give to `texindex'.
+
+  Instead of specifying all the unsorted index file names explicitly,
+you can use `??' as shell wildcards and give the command in this form:
+
+     texindex foo.??
+
+This command will run `texindex' on all the unsorted index files,
+including any that you have defined yourself using `@defindex' or
+`@defcodeindex'.  (You may execute `texindex foo.??' even if there are
+similarly named files with two letter extensions that are not index
+files, such as `foo.el'.  The `texindex' command reports but otherwise
+ignores such files.)
+
+  For each file specified, `texindex' generates a sorted index file
+whose name is made by appending `s' to the input file name.  The
+`@printindex' command knows to look for a file of that name (*note
+Printing Indices & Menus::).  `texindex' does not alter the raw index
+output file.
+
+  After you have sorted the indices, you need to rerun the `tex'
+formatting command on the Texinfo file.  This regenerates the DVI file,
+this time with up-to-date index entries.
+
+  Finally, you may need to run `tex' one more time, to get the page
+numbers in the cross-references correct.
+
+  To summarize, this is a four step process:
+
+  1. Run `tex' on your Texinfo file.  This generates a DVI file (with
+     undefined cross-references and no indices), and the raw index files
+     (with two letter extensions).
+
+  2. Run `texindex' on the raw index files.  This creates the
+     corresponding sorted index files (with three letter extensions).
+
+  3. Run `tex' again on your Texinfo file.  This regenerates the DVI
+     file, this time with indices and defined cross-references, but
+     with page numbers for the cross-references from last time,
+     generally incorrect.
+
+  4. Run `tex' one last time.  This time the correct page numbers are
+     written for the cross-references.
+
+  Alternatively, it's a one-step process: run `texi2dvi'.
+
+  You need not run `texindex' each time after you run `tex'.  If you do
+not, on the next run, the `tex' formatting command will use whatever
+sorted index files happen to exist from the previous use of `texindex'.
+This is usually ok while you are debugging.
+
+\1f
+File: texinfo.info,  Node: Format with texi2dvi,  Next: Print with lpr,  Prev: Format with tex/texindex,  Up: Format/Print Hardcopy
+
+Format using `texi2dvi'
+=======================
+
+The `texi2dvi' command automatically runs both `tex' and `texindex' as
+many times as necessary to produce a DVI file with up-to-date, sorted
+indices.  It simplifies the `tex'--`texindex'--`tex' sequence described
+in the previous section.
+
+  The syntax for `texi2dvi' is like this (where `prompt$' is your shell
+prompt):
+
+     prompt$ texi2dvi FILENAME...
+
+  For a list of options, run `texi2dvi --help'.
+
+\1f
+File: texinfo.info,  Node: Print with lpr,  Next: Within Emacs,  Prev: Format with texi2dvi,  Up: Format/Print Hardcopy
+
+Shell Print Using `lpr -d'
+==========================
+
+The precise command to print a DVI file depends on your system
+installation, but `lpr -d' is common.  The command may require the DVI
+file name without any extension or with a `.dvi' extension.  (If it is
+`lpr', you must include the `.dvi'.)
+
+  The following commands, for example, will (probably) suffice to sort
+the indices, format, and print the `Bison Manual':
+
+     tex bison.texinfo
+     texindex bison.??
+     tex bison.texinfo
+     lpr -d bison.dvi
+
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+  Using the `texi2dvi' shell script, you simply need type:
+
+     texi2dvi bison.texinfo
+     lpr -d bison.dvi
+
+\1f
+File: texinfo.info,  Node: Within Emacs,  Next: Texinfo Mode Printing,  Prev: Print with lpr,  Up: Format/Print Hardcopy
+
+From an Emacs Shell
+===================
+
+You can give formatting and printing commands from a shell within GNU
+Emacs.  To create a shell within Emacs, type `M-x shell'.  In this
+shell, you can format and print the document.  *Note Format and Print
+Hardcopy: Format/Print Hardcopy, for details.
+
+  You can switch to and from the shell buffer while `tex' is running
+and do other editing.  If you are formatting a long document on a slow
+machine, this can be very convenient.
+
+  You can also use `texi2dvi' from an Emacs shell.  For example, here
+is how to use `texi2dvi' to format and print `Using and Porting GNU CC'
+from a shell within Emacs:
+
+     texi2dvi gcc.texinfo
+     lpr -d gcc.dvi
+
+  *Note Texinfo Mode Printing::, for more information about formatting
+and printing in Texinfo mode.
+
+\1f
+File: texinfo.info,  Node: Texinfo Mode Printing,  Next: Compile-Command,  Prev: Within Emacs,  Up: Format/Print Hardcopy
+
+Formatting and Printing in Texinfo Mode
+=======================================
+
+Texinfo mode provides several predefined key commands for TeX
+formatting and printing.  These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations occur.
+
+`C-c C-t C-b'
+`M-x texinfo-tex-buffer'
+     Run `texi2dvi' on the current buffer.
+
+`C-c C-t C-r'
+`M-x texinfo-tex-region'
+     Run TeX on the current region.
+
+`C-c C-t C-i'
+`M-x texinfo-texindex'
+     Sort the indices of a Texinfo file formatted with
+     `texinfo-tex-region'.
+
+`C-c C-t C-p'
+`M-x texinfo-tex-print'
+     Print a DVI file that was made with `texinfo-tex-region' or
+     `texinfo-tex-buffer'.
+
+`C-c C-t C-q'
+`M-x tex-show-print-queue'
+     Show the print queue.
+
+`C-c C-t C-d'
+`M-x texinfo-delete-from-print-queue'
+     Delete a job from the print queue; you will be prompted for the job
+     number shown by a preceding `C-c C-t C-q' command
+     (`texinfo-show-tex-print-queue').
+
+`C-c C-t C-k'
+`M-x tex-kill-job'
+     Kill the currently running TeX job started by `texinfo-tex-region'
+     or `texinfo-tex-buffer', or any other process running in the
+     Texinfo shell buffer.
+
+`C-c C-t C-x'
+`M-x texinfo-quit-job'
+     Quit a TeX formatting job that has stopped because of an error by
+     sending an <x> to it.  When you do this, TeX preserves a record of
+     what it did in a `.log' file.
+
+`C-c C-t C-l'
+`M-x tex-recenter-output-buffer'
+     Redisplay the shell buffer in which the TeX printing and formatting
+     commands are run to show its most recent output.
+
+  Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):
+
+     C-c C-t C-b             Run `texi2dvi' on the buffer.
+     C-c C-t C-p             Print the DVI file.
+     C-c C-t C-q             Display the printer queue.
+
+  The Texinfo mode TeX formatting commands start a subshell in Emacs
+called the `*tex-shell*'.  The `texinfo-tex-command',
+`texinfo-texindex-command', and `tex-dvi-print-command' commands are
+all run in this shell.
+
+  You can watch the commands operate in the `*tex-shell*' buffer, and
+you can switch to and from and use the `*tex-shell*' buffer as you
+would any other shell buffer.
+
+  The formatting and print commands depend on the values of several
+variables.  The default values are:
+
+          Variable                              Default value
+     
+     texinfo-texi2dvi-command                  "texi2dvi"
+     texinfo-tex-command                       "tex"
+     texinfo-texindex-command                  "texindex"
+     texinfo-delete-from-print-queue-command   "lprm"
+     texinfo-tex-trailer                       "@bye"
+     tex-start-of-header                       "%**start"
+     tex-end-of-header                         "%**end"
+     tex-dvi-print-command                     "lpr -d"
+     tex-show-queue-command                    "lpq"
+
+  You can change the values of these variables with the `M-x
+edit-options' command (*note Editing Variable Values: (xemacs)Edit
+Options.), with the `M-x set-variable' command (*note Examining and
+Setting Variables: (xemacs)Examining.), or with your `.emacs'
+initialization file (*note Init File: (xemacs)Init File.).
+
+\1f
+File: texinfo.info,  Node: Compile-Command,  Next: Requirements Summary,  Prev: Texinfo Mode Printing,  Up: Format/Print Hardcopy
+
+Using the Local Variables List
+==============================
+
+Yet another way to apply the TeX formatting command to a Texinfo file
+is to put that command in a "local variables list" at the end of the
+Texinfo file.  You can then specify the `tex' or `texi2dvi' commands as
+a `compile-command' and have Emacs run it by typing `M-x compile'.
+This creates a special shell called the `*compilation*' buffer in which
+Emacs runs the compile command.  For example, at the end of the
+`gdb.texinfo' file, after the `@bye', you could put the following:
+
+     Local Variables:
+     compile-command: "texi2dvi gdb.texinfo"
+     End:
+
+This technique is most often used by programmers who also compile
+programs this way; see *Note Compilation: (xemacs)Compilation.
+
+\1f
+File: texinfo.info,  Node: Requirements Summary,  Next: Preparing for TeX,  Prev: Compile-Command,  Up: Format/Print Hardcopy
+
+TeX Formatting Requirements Summary
+===================================
+
+Every Texinfo file that is to be input to TeX must begin with a
+`\input' command and must contain an `@setfilename' command:
+
+     \input texinfo
+     @setfilename ARG-NOT-USED-BY-@TEX{}
+
+The first command instructs TeX to load the macros it needs to process
+a Texinfo file and the second command opens auxiliary files.
+
+  Every Texinfo file must end with a line that terminates TeX's
+processing and forces out unfinished pages:
+
+     @bye
+
+  Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by TeX.
+
+  Usually, however, the beginning includes an `@settitle' command to
+define the title of the printed manual, an `@setchapternewpage'
+command, a title page, a copyright page, and permissions.  Besides an
+`@bye', the end of a file usually includes indices and a table of
+contents.  (And of course most manuals contain a body of text as well.)
+
+For more information, see
+*Note `@settitle': settitle,
+*Note `@setchapternewpage': setchapternewpage,
+*Note Page Headings: Headings,
+*Note Titlepage & Copyright Page::,
+*Note Printing Indices & Menus::, and
+*Note Contents::.
+
+\1f
+File: texinfo.info,  Node: Preparing for TeX,  Next: Overfull hboxes,  Prev: Requirements Summary,  Up: Format/Print Hardcopy
+
+Preparing to Use TeX
+====================
+
+TeX needs to know where to find the `texinfo.tex' file that you have
+told it to input with the `\input texinfo' command at the beginning of
+the first line.  The `texinfo.tex' file tells TeX how to handle
+@-commands; it is included in all standard GNU distributions.
+
+  Usually, the `texinfo.tex' file is put under the default directory
+that contains TeX macros
+(`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when GNU
+Emacs or other GNU software is installed.  In this case, TeX will find
+the file and you do not need to do anything special.  Alternatively,
+you can put `texinfo.tex' in the current directory when you run TeX,
+and TeX will find it there.
+
+  Also, you should install `epsf.tex' in the same place as
+`texinfo.tex', if it is not already installed from another
+distribution.  This file is needed to support the `@image' command
+(*note Images::).
+
+  Optionally, you may create an additional `texinfo.cnf', and install
+it as well.  This file is read by TeX at the `@setfilename' command
+(*note `@setfilename': setfilename.).  You can put any commands you
+like there according to local site-wide conventions, and they will be
+read by TeX when processing any Texinfo document.  For example, if
+`texinfo.cnf' contains the a single line `@afourpaper' (*note A4
+Paper::), then all Texinfo documents will be processed with that page
+size in effect.  If you have nothing to put in `texinfo.cnf', you do
+not need to create it.
+
+  If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly.  For `texinfo.tex',
+you can do this by writing the complete path for the file after the
+`\input' command.  Another way, that works for both `texinfo.tex' and
+`texinfo.cnf' (and any other file TeX might read), is to set the
+`TEXINPUTS' environment variable in your `.cshrc' or `.profile' file.
+
+  Which you use of `.cshrc' or `.profile' depends on whether you use a
+Bourne shell-compatible (`sh', `bash', `ksh', ...) or C
+shell-compatible (`csh', `tcsh') command interpreter.  The latter read
+the `.cshrc' file for initialization information, and the former read
+`.profile'.
+
+  In a `.cshrc' file, you could use the following `csh' command
+sequence:
+
+     setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
+
+  In a `.profile' file, you could use the following `sh' command
+sequence:
+
+     TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
+     export TEXINPUTS
+
+This would cause TeX to look for `\input' file first in the current
+directory, indicated by the `.', then in a hypothetical user's
+`me/mylib' directory, and finally in a system directory.
+
+\1f
+File: texinfo.info,  Node: Overfull hboxes,  Next: smallbook,  Prev: Preparing for TeX,  Up: Format/Print Hardcopy
+
+Overfull "hboxes"
+=================
+
+TeX is sometimes unable to typeset a line without extending it into the
+right margin.  This can occur when TeX comes upon what it interprets as
+a long word that it cannot hyphenate, such as an electronic mail
+network address or a very long title.  When this happens, TeX prints an
+error message like this:
+
+     Overfull \hbox (20.76302pt too wide)
+
+(In TeX, lines are in "horizontal boxes", hence the term, "hbox".  The
+backslash, `\', is the TeX equivalent of `@'.)
+
+  TeX also provides the line number in the Texinfo source file and the
+text of the offending line, which is marked at all the places that TeX
+knows how to hyphenate words.  *Note Catching Errors with TeX
+Formatting: Debugging with TeX, for more information about typesetting
+errors.
+
+  If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it.  A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+  However, unless told otherwise, TeX will print a large, ugly, black
+rectangle beside the line that contains the overfull hbox.  This is so
+you will notice the location of the problem if you are correcting a
+draft.
+
+  To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the `@titlepage' command:
+
+     @finalout
+
+\1f
+File: texinfo.info,  Node: smallbook,  Next: A4 Paper,  Prev: Overfull hboxes,  Up: Format/Print Hardcopy
+
+Printing "Small" Books
+======================
+
+By default, TeX typesets pages for printing in an 8.5 by 11 inch
+format.  However, you can direct TeX to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:
+
+     @smallbook
+
+(Since regular sized books are often about 7 by 9.25 inches, this
+command might better have been called the `@regularbooksize' command,
+but it came to be called the `@smallbook' command by comparison to the
+8.5 by 11 inch format.)
+
+  If you write the `@smallbook' command between the start-of-header and
+end-of-header lines, the Texinfo mode TeX region formatting command,
+`texinfo-tex-region', will format the region in "small" book size
+(*note Start of Header::).
+
+  The Free Software Foundation distributes printed copies of `The GNU
+Emacs Manual' and other manuals in the "small" book size.  *Note
+`@smallexample' and `@smalllisp': smallexample & smalllisp, for
+information about commands that make it easier to produce examples for
+a smaller manual.
+
+  Alternatively, to avoid embedding this physical paper size in your
+document, use `texi2dvi' to format your document (*note Format with
+texi2dvi::), and supply `-t @smallbook' as an argument.  Then other
+people do not have to change the document source file to format it
+differently.
+
+\1f
+File: texinfo.info,  Node: A4 Paper,  Next: Cropmarks and Magnification,  Prev: smallbook,  Up: Format/Print Hardcopy
+
+Printing on A4 Paper
+====================
+
+You can tell TeX to typeset a document for printing on European size A4
+paper with the `@afourpaper' command.  Write the command on a line by
+itself between `@iftex' and `@end iftex' lines near the beginning of
+the Texinfo file, before the title page:
+
+  For example, this is how you would write the header for this manual:
+
+     \input texinfo    @c -*-texinfo-*-
+     @c %**start of header
+     @setfilename texinfo
+     @settitle Texinfo
+     @syncodeindex vr fn
+     @iftex
+     @afourpaper
+     @end iftex
+     @c %**end of header
+
+  Alternatively, to avoid embedding this physical paper size in your
+document, use `texi2dvi' to format your document (*note Format with
+texi2dvi::), and supply `-t @afourpaper' as an argument.  Then other
+people do not have to change the document source file to format it
+differently.
+
+  Another alternative: put the `@afourpaper' command in the file
+`texinfo.cnf' that TeX will read.  (No need for `@iftex' there.)  This
+will automatically typeset all the Texinfo documents at your site with
+that paper size in effect.
+
+\1f
+File: texinfo.info,  Node: Cropmarks and Magnification,  Prev: A4 Paper,  Up: Format/Print Hardcopy
+
+Cropmarks and Magnification

 ===========================
 
 ===========================
 

-  Here is a complete but very short Texinfo file, in six parts.  The
-first three parts of the file, from `\input texinfo' through to `@end
-titlepage', look more intimidating than they are.  Most of the material
-is standard boilerplate; when you write a manual, simply insert the
-names for your own manual in this segment. (*Note Beginning a File::.)
+You can attempt to direct TeX to print cropmarks at the corners of
+pages with the `@cropmarks' command.  Write the `@cropmarks' command on
+a line by itself between `@iftex' and `@end iftex' lines near the
+beginning of the Texinfo file, before the title page, like this:
+
+     @iftex
+     @cropmarks
+     @end iftex
+
+  This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the `@smallbook' command.  (Printers
+will not produce cropmarks for regular sized output that is printed on
+regular sized paper.)  Since different printing machines work in
+different ways, you should explore the use of this command with a
+spirit of adventure.  You may have to redefine the command in the
+`texinfo.tex' definitions file.
+
+  You can attempt to direct TeX to typeset pages larger or smaller than
+usual with the `\mag' TeX command.  Everything that is typeset is
+scaled proportionally larger or smaller.  (`\mag' stands for
+"magnification".)  This is _not_ a Texinfo @-command, but is a plain
+TeX command that is prefixed with a backslash.  You have to write this
+command between `@tex' and `@end tex' (*note Raw Formatter Commands::).
+
+  Follow the `\mag' command with an `=' and then a number that is 1000
+times the magnification you desire.  For example, to print pages at 1.2
+normal size, write the following near the beginning of the Texinfo
+file, before the title page:
+
+     @tex
+     \mag=1200
+     @end tex
+
+  With some printing technologies, you can print normal-sized copies
+that look better than usual by using a larger-than-normal master.
+
+  Depending on your system, `\mag' may not work or may work only at
+certain magnifications.  Be prepared to experiment.
+
+\1f
+File: texinfo.info,  Node: Create an Info File,  Next: Install an Info File,  Prev: Format/Print Hardcopy,  Up: Top
+
+Creating an Info File
+*********************
+
+`makeinfo' is a utility that converts a Texinfo file into an Info file;
+`texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
+functions that do the same.
+
+  A Texinfo file must contain an `@setfilename' line near its
+beginning, otherwise the Info formatting commands will fail.
+
+  For information on installing the Info file in the Info system, see
+*Note Install an Info File::.
+
+* Menu:
+
+* makeinfo advantages::         `makeinfo' provides better error checking.
+* Invoking makeinfo::           How to run `makeinfo' from a shell.
+* makeinfo options::            Specify fill-column and other options.
+* Pointer Validation::          How to check that pointers point somewhere.
+* makeinfo in Emacs::           How to run `makeinfo' from Emacs.
+* texinfo-format commands::     Two Info formatting commands written
+                                  in Emacs Lisp are an alternative
+                                  to `makeinfo'.
+* Batch Formatting::            How to format for Info in Emacs Batch mode.
+* Tag and Split Files::         How tagged and split files help Info
+                                  to run better.
+
+\1f
+File: texinfo.info,  Node: makeinfo advantages,  Next: Invoking makeinfo,  Prev: Create an Info File,  Up: Create an Info File
+
+`makeinfo' Preferred
+====================
+
+  The `makeinfo' utility creates an Info file from a Texinfo source
+file more quickly than either of the Emacs formatting commands and
+provides better error messages.  We recommend it.  `makeinfo' is a C
+program that is independent of Emacs.  You do not need to run Emacs to
+use `makeinfo', which means you can use `makeinfo' on machines that are
+too small to run Emacs. You can run `makeinfo' in any one of three
+ways: from an operating system shell, from a shell inside Emacs, or by
+typing a key command in Texinfo mode in Emacs.
+
+  The `texinfo-format-region' and the `texinfo-format-buffer' commands
+are useful if you cannot run `makeinfo'.  Also, in some circumstances,
+they format short regions or buffers more quickly than `makeinfo'.
+
+\1f
+File: texinfo.info,  Node: Invoking makeinfo,  Next: makeinfo options,  Prev: makeinfo advantages,  Up: Create an Info File
+
+Running `makeinfo' from a Shell
+===============================
+
+To create an Info file from a Texinfo file, type `makeinfo' followed by
+the name of the Texinfo file.  Thus, to create the Info file for Bison,
+type the following to the shell: is the prompt):
+
+     makeinfo bison.texinfo
+
+  (You can run a shell inside Emacs by typing `M-x shell'.)
+
+  Sometimes you will want to specify options.  For example, if you wish
+to discover which version of `makeinfo' you are using, type:
+
+     makeinfo --version
+
+  *Note makeinfo options::, for more information.
+
+\1f
+File: texinfo.info,  Node: makeinfo options,  Next: Pointer Validation,  Prev: Invoking makeinfo,  Up: Create an Info File
+
+Options for `makeinfo'
+======================
+
+The `makeinfo' command takes a number of options.  Most often, options
+are used to set the value of the fill column and specify the footnote
+style.  Each command line option is a word preceded by `--' or a letter
+preceded by `-'.  You can use abbreviations for the long option names
+as long as they are unique.
+
+  For example, you could use the following shell command to create an
+Info file for `bison.texinfo' in which each line is filled to only 68
+columns:
+
+     makeinfo --fill-column=68 bison.texinfo
+
+  You can write two or more options in sequence, like this:
+
+     makeinfo --no-split --fill-column=70 ...
+
+This would keep the Info file together as one possibly very long file
+and would also set the fill column to 70.
+
+  The options are:
+
+`-D VAR'
+     Cause the variable VAR to be defined.  This is equivalent to `@set
+     VAR' in the Texinfo file (*note set clear value::).
+
+`--error-limit=LIMIT'
+     Set the maximum number of errors that `makeinfo' will report
+     before exiting (on the assumption that continuing would be
+     useless); default 100.
+
+`--fill-column=WIDTH'
+     Specify the maximum number of columns in a line; this is the
+     right-hand edge of a line.  Paragraphs that are filled will be
+     filled to this width.  (Filling is the process of breaking up and
+     connecting lines so that lines are the same length as or shorter
+     than the number specified as the fill column.  Lines are broken
+     between words.) The default value is 72.
+
+`--footnote-style=STYLE'
+     Set the footnote style to STYLE, either `end' for the end node
+     style (the default) or `separate' for the separate node style.
+     The value set by this option overrides the value set in a Texinfo
+     file by an `@footnotestyle' command (*note Footnotes::).  When the
+     footnote style is `separate', `makeinfo' makes a new node
+     containing the footnotes found in the current node.  When the
+     footnote style is `end', `makeinfo' places the footnote references
+     at the end of the current node.
+
+`--force'
+     Ordinarily, if the input file has errors, the output files are not
+     created.  With this option, they are preserved.
+
+`--help'
+     Print a usage message listing all available options, then exit
+     successfully.
+
+`-I DIR'
+     Add `dir' to the directory search list for finding files that are
+     included using the `@include' command.  By default, `makeinfo'
+     searches only the current directory.
+
+`--no-headers'
+     Do not include menus or node lines in the output.  This results in
+     an ASCII file that you cannot read in Info since it does not
+     contain the requisite nodes or menus. It is primarily useful to
+     extract certain pieces of a manual into separate files to be
+     included in a distribution, such as `INSTALL' files.
+
+`--no-split'
+     Suppress the splitting stage of `makeinfo'.  By default, large
+     output files (where the size is greater than 70k bytes) are split
+     into smaller subfiles, each one approximately 50k bytes.
+
+`--no-pointer-validate'
+`--no-validate'
+     Suppress the pointer-validation phase of `makeinfo'.  Normally,
+     after a Texinfo file is processed, some consistency checks are
+     made to ensure that cross references can be resolved, etc.  *Note
+     Pointer Validation::.
+
+`--no-warn'
+     Suppress warning messages (but _not_ error messages).  You might
+     want this if the file you are creating has examples of Texinfo
+     cross references within it, and the nodes that are referenced do
+     not actually exist.
+
+`--no-number-footnotes'
+     Suppress automatic footnote numbering.  By default, `makeinfo'
+     numbers each footnote sequentially in a single node, resetting the
+     current footnote number to 1 at the start of each node.
+
+`--output=FILE'
+`-o FILE'
+     Specify that the output should be directed to FILE and not to the
+     file name specified in the `@setfilename' command found in the
+     Texinfo source (*note setfilename::).  If FILE is `-', output goes
+     to standard output and `--no-split' is implied.
+
+`-P DIR'
+     Prepend `dir' to the directory search list for `@include'.  See
+     `-I' for more details.
+
+`--paragraph-indent=INDENT'
+     Set the paragraph indentation style to INDENT.  The value set by
+     this option overrides the value set in a Texinfo file by an
+     `@paragraphindent' command (*note paragraphindent::).  The value
+     of INDENT is interpreted as follows:
+
+    `asis'
+          Preserve any existing indentation at the starts of paragraphs.
+
+    `0' or `none'
+          Delete any existing indentation.
+
+    NUM
+          Indent each paragraph by that number of spaces.
+
+`--reference-limit=LIMIT'
+     Set the value of the number of references to a node that
+     `makeinfo' will make without reporting a warning.  If a node has
+     more than this number of references in it, `makeinfo' will make the
+     references but also report a warning.  The default is 1000.
+
+`-U VAR'
+     Cause VAR to be undefined.  This is equivalent to `@clear VAR' in
+     the Texinfo file (*note set clear value::).
+
+`--verbose'
+     Cause `makeinfo' to display messages saying what it is doing.
+     Normally, `makeinfo' only outputs messages if there are errors or
+     warnings.
+
+`--version'
+     Print the version number, then exit successfully.
+
+
+\1f
+File: texinfo.info,  Node: Pointer Validation,  Next: makeinfo in Emacs,  Prev: makeinfo options,  Up: Create an Info File
+
+Pointer Validation
+==================
+
+If you do not suppress pointer-validation, `makeinfo' will check the
+validity of the final Info file.  Mostly, this means ensuring that
+nodes you have referenced really exist.  Here is a complete list of what
+is checked:
+
+  1. If a `Next', `Previous', or `Up' node reference is a reference to a
+     node in the current file and is not an external reference such as
+     to `(dir)', then the referenced node must exist.
+
+  2. In every node, if the `Previous' node is different from the `Up'
+     node, then the `Previous' node must also be pointed to by a `Next'
+     node.
+
+  3. Every node except the `Top' node must have an `Up' pointer.
+
+  4. The node referenced by an `Up' pointer must contain a reference to
+     the current node in some manner other than through a `Next'
+     reference.  This includes menu entries and cross references.
+
+  5. If the `Next' reference of a node is not the same as the `Next'
+     reference of the `Up' reference, then the node referenced by the
+     `Next' pointer must have a `Previous' pointer that points back to
+     the current node.  This rule allows the last node in a section to
+     point to the first node of the next chapter.
+
+\1f
+File: texinfo.info,  Node: makeinfo in Emacs,  Next: texinfo-format commands,  Prev: Pointer Validation,  Up: Create an Info File
+
+Running `makeinfo' inside Emacs
+===============================
+
+You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
+`makeinfo-region' or the `makeinfo-buffer' commands.  In Texinfo mode,
+the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
+
+`C-c C-m C-r'
+`M-x makeinfo-region'
+     Format the current region for Info.
+
+`C-c C-m C-b'
+`M-x makeinfo-buffer'
+     Format the current buffer for Info.
+
+  When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
+prompts for a file name, offering the name of the visited file as the
+default.  You can edit the default file name in the minibuffer if you
+wish, before pressing <RET> to start the `makeinfo' process.
+
+  The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
+`makeinfo' program in a temporary shell buffer.  If `makeinfo' finds
+any errors, Emacs displays the error messages in the temporary buffer.
+
+  You can parse the error messages by typing `C-x `' (`next-error').
+This causes Emacs to go to and position the cursor on the line in the
+Texinfo source that `makeinfo' thinks caused the error.  *Note Running
+`make' or Compilers Generally: (xemacs)Compilation, for more
+information about using the `next-error' command.
+
+  In addition, you can kill the shell in which the `makeinfo' command
+is running or make the shell buffer display its most recent output.
+
+`C-c C-m C-k'
+`M-x makeinfo-kill-job'
+     Kill the current running `makeinfo' job created by
+     `makeinfo-region' or `makeinfo-buffer'.
+
+`C-c C-m C-l'
+`M-x makeinfo-recenter-output-buffer'
+     Redisplay the `makeinfo' shell buffer to display its most recent
+     output.
+
+(Note that the parallel commands for killing and recentering a TeX job
+are `C-c C-t C-k' and `C-c C-t C-l'.  *Note Texinfo Mode Printing::.)
+
+  You can specify options for `makeinfo' by setting the
+`makeinfo-options' variable with either the `M-x edit-options' or the
+`M-x set-variable' command, or by setting the variable in your `.emacs'
+initialization file.
+
+  For example, you could write the following in your `.emacs' file:
+
+     (setq makeinfo-options
+           "--paragraph-indent=0 --no-split
+            --fill-column=70 --verbose")
+
+For more information, see
+*Note Editing Variable Values: (xemacs)Edit Options,
+*Note Examining and Setting Variables: (xemacs)Examining,
+*Note Init File: (xemacs)Init File, and
+*Note Options for `makeinfo': makeinfo options.
+
+\1f
+File: texinfo.info,  Node: texinfo-format commands,  Next: Batch Formatting,  Prev: makeinfo in Emacs,  Up: Create an Info File
+
+The `texinfo-format...' Commands
+================================
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the `texinfo-format-region' command.  This formats the
+current region and displays the formatted text in a temporary buffer
+called `*Info Region*'.
+
+  Similarly, you can format a buffer with the `texinfo-format-buffer'
+command.  This command creates a new buffer and generates the Info file
+in it.  Typing `C-x C-s' will save the Info file under the name
+specified by the `@setfilename' line which must be near the beginning
+of the Texinfo file.
+
+`C-c C-e C-r'
+``texinfo-format-region''
+     Format the current region for Info.
+
+`C-c C-e C-b'
+``texinfo-format-buffer''
+     Format the current buffer for Info.
+
+  The `texinfo-format-region' and `texinfo-format-buffer' commands
+provide you with some error checking, and other functions can provide
+you with further help in finding formatting errors.  These procedures
+are described in an appendix; see *Note Catching Mistakes::.  However,
+the `makeinfo' program is often faster and provides better error
+checking (*note makeinfo in Emacs::).
+
+\1f
+File: texinfo.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Create an Info File
+
+Batch Formatting
+================
+
+You can format Texinfo files for Info using `batch-texinfo-format' and
+Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs.  (*Note Command Line Switches and
+Arguments: (xemacs)Command Switches.)
+
+  Here is a shell command to format all the files that end in
+`.texinfo' in the current directory:
+
+     emacs -batch -funcall batch-texinfo-format *.texinfo
+
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of them.
+
+  Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
+is not interactive.  It kills the Batch mode Emacs on completion.
+
+  `batch-texinfo-format' is convenient if you lack `makeinfo' and want
+to format several Texinfo files at once.  When you use Batch mode, you
+create a new Emacs process.  This frees your current Emacs, so you can
+continue working in it.  (When you run `texinfo-format-region' or
+`texinfo-format-buffer', you cannot use that Emacs for anything else
+until the command finishes.)
+
+\1f
+File: texinfo.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Create an Info File
+
+Tag Files and Split Files
+=========================
+
+If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
+automatically creates a tag table for its Info file;  `makeinfo' always
+creates a tag table.  With a "tag table", Info can jump to new nodes
+more quickly than it can otherwise.
+
+  In addition, if the Texinfo file contains more than about 70,000
+bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
+into shorter "indirect" subfiles of about 50,000 bytes each.  Big files
+are split into smaller files so that Emacs does not need to make a
+large buffer to hold the whole of a large Info file; instead, Emacs
+allocates just enough memory for the small, split off file that is
+needed at the time.  This way, Emacs avoids wasting memory when you run
+Info.  (Before splitting was implemented, Info files were always kept
+short and "include files" were designed as a way to create a single,
+large printed manual out of the smaller Info files.  *Note Include
+Files::, for more information.  Include files are still used for very
+large documents, such as `The XEmacs Lisp Reference Manual', in which
+each chapter is a separate file.)
+
+  When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off.  The split off files are called
+"indirect" files.
+
+  The split off files have names that are created by appending `-1',
+`-2', `-3' and so on to the file name specified by the `@setfilename'
+command.  The shortened version of the original file continues to have
+the name specified by `@setfilename'.
+
+  At one stage in writing this document, for example, the Info file was
+saved as `test-texinfo' and that file looked like this:
+
+     Info file: test-texinfo,    -*-Text-*-
+     produced by texinfo-format-buffer
+     from file: new-texinfo-manual.texinfo
+     
+     ^_
+     Indirect:
+     test-texinfo-1: 102
+     test-texinfo-2: 50422
+     test-texinfo-3: 101300
+     ^_^L
+     Tag table:
+     (Indirect)
+     Node: overview^?104
+     Node: info file^?1271
+     Node: printed manual^?4853
+     Node: conventions^?6855
+     ...
+
+(But `test-texinfo' had far more nodes than are shown here.)  Each of
+the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
+`test-texinfo-3', is listed in this file after the line that says
+`Indirect:'.  The tag table is listed after the line that says `Tag
+table:'.
+
+  In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file.  In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning.
+
+  If you are using `texinfo-format-buffer' to create Info files, you
+may want to run the `Info-validate' command.  (The `makeinfo' command
+does such a good job on its own, you do not need `Info-validate'.)
+However, you cannot run the `M-x Info-validate' node-checking command
+on indirect files.  For information on how to prevent files from being
+split and how to validate the structure of the nodes, see *Note Using
+Info-validate::.
+
+\1f
+File: texinfo.info,  Node: Install an Info File,  Next: Command List,  Prev: Create an Info File,  Up: Top
+
+Installing an Info File
+***********************
+
+Info files are usually kept in the `info' directory.  You can read Info
+files using the standalone Info program or the Info reader built into
+Emacs.  (*note info: (info)Top, for an introduction to Info.)
+
+* Menu:
+
+* Directory file::              The top level menu for all Info files.
+* New Info File::               Listing a new info file.
+* Other Info Directories::      How to specify Info files that are
+                                  located in other directories.
+* Installing Dir Entries::      How to specify what menu entry to add
+                                  to the Info directory.
+* Invoking install-info::       `install-info' options.
+
+\1f
+File: texinfo.info,  Node: Directory file,  Next: New Info File,  Prev: Install an Info File,  Up: Install an Info File
+
+The `dir' File
+==============
+
+  For Info to work, the `info' directory must contain a file that
+serves as a top level directory for the Info system.  By convention,
+this file is called `dir'.  (You can find the location of this file
+within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
+to see the pathname to the `info' directory.)
+
+  The `dir' file is itself an Info file.  It contains the top level
+menu for all the Info files in the system.  The menu looks like this:
+
+     * Menu:
+     
+     * Info:    (info).     Documentation browsing system.
+     * Emacs:   (emacs).    The extensible, self-documenting
+                            text editor.
+     * Texinfo: (texinfo).  With one source file, make
+                            either a printed manual using
+                            TeX or an Info file.
+     ...
+
+  Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses.  (The menu entry does not need to specify
+the `Top' node, since Info goes to the `Top' node if no node name is
+mentioned.  *Note Nodes in Other Info Files: Other Info Files.)
+
+  Thus, the `Info' entry points to the `Top' node of the `info' file
+and the `Emacs' entry points to the `Top' node of the `emacs' file.
+
+  In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the `dir' file.  For example, the line for the `Top' node of
+the Emacs manual looks like this in Info:
+
+     File: emacs  Node: Top, Up: (DIR), Next: Distrib
+
+(Note that in this case, the `dir' file name is written in upper case
+letters--it can be written in either upper or lower case.  Info has a
+feature that it will change the case of the file name to lower case if
+it cannot find the name as written.)
+
+\1f
+File: texinfo.info,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory file,  Up: Install an Info File
+
+Listing a New Info File
+=======================
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the `dir' file in the `info' directory.  For
+example, if you were adding documentation for GDB, you would write the
+following new entry:
+
+     * GDB: (gdb).           The source-level C debugger.
+
+The first part of the menu entry is the menu entry name, followed by a
+colon.  The second part is the name of the Info file, in parentheses,
+followed by a period.  The third part is the description.
+
+  The name of an Info file often has a `.info' extension.  Thus, the
+Info file for GDB might be called either `gdb' or `gdb.info'.  The Info
+reader programs automatically try the file name both with and without
+`.info'; so it is better to avoid clutter and not to write `.info'
+explicitly in the menu entry.  For example, the GDB menu entry should
+use just `gdb' for the file name, not `gdb.info'.
+
+\1f
+File: texinfo.info,  Node: Other Info Directories,  Next: Installing Dir Entries,  Prev: New Info File,  Up: Install an Info File
+
+Info Files in Other Directories
+===============================
+
+If an Info file is not in the `info' directory, there are three ways to
+specify its location:
+
+   * Write the pathname in the `dir' file as the second part of the
+     menu.
+
+   * If you are using Emacs, list the name of the file in a second `dir'
+     file, in its directory; and then add the name of that directory to
+     the `Info-directory-list' variable in your personal or site
+     initialization file.
+
+     This tells Emacs where to look for `dir' files.  Emacs merges the
+     files named `dir' from each of the listed directories.  (In Emacs
+     version 18, you can set the `Info-directory' variable to the name
+     of only one directory.)
+
+   * Specify the Info directory name in the `INFOPATH' environment
+     variable in your `.profile' or `.cshrc' initialization file.
+     (Only you and others who set this environment variable will be
+     able to find Info files whose location is specified this way.)
+
+  For example, to reach a test file in the `/home/bob/manuals'
+directory, you could add an entry like this to the menu in the `dir'
+file:
+
+     * Test: (/home/bob/manuals/info-test).  Bob's own test file.
+
+In this case, the absolute file name of the `info-test' file is written
+as the second part of the menu entry.
+
+  Alternatively, you could write the following in your `.emacs' file:
+
+     (setq Info-directory-list
+           '("/home/bob/manuals"
+             "/usr/local/info"))
+
+  This tells Emacs to merge the `dir' file from the `/home/bob/manuals'
+directory with the `dir' file from the `/usr/local/info' directory.
+Info will list the `/home/bob/manuals/info-test' file as a menu entry
+in the `/home/bob/manuals/dir' file.
+
+  Finally, you can tell Info where to look by setting the `INFOPATH'
+environment variable in your `.cshrc' or `.profile' file.  If you use a
+Bourne-compatible shell such as `sh' or `bash' for your shell command
+interpreter, you set the `INFOPATH' environment variable in the
+`.profile' initialization file; but if you use `csh' or `tcsh', you
+must set the variable in the `.cshrc' initialization file.  The two
+types of shells use different syntax.
+
+   * In a `.cshrc' file, you could set the `INFOPATH' variable as
+     follows:
+
+          setenv INFOPATH .:~/manuals:/usr/local/emacs/info
+
+   * In a `.profile' file, you would achieve the same effect by writing:
+
+          INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
+          export INFOPATH
+
+The `.' indicates the current directory as usual.  Emacs uses the
+`INFOPATH' environment variable to initialize the value of Emacs's own
+`Info-directory-list' variable.
+
+  However you set `INFOPATH', if its last character is a colon, this is
+replaced by the default (compiled-in) path.  This gives you a way to
+augment the default path with new directories without having to list all
+the standard places.  For example (using `sh' syntax:
+
+     INFOPATH=/local/info:
+     export INFOPATH
+
+will search `/local/info' first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
+\1f
+File: texinfo.info,  Node: Installing Dir Entries,  Next: Invoking install-info,  Prev: Other Info Directories,  Up: Install an Info File
+
+Installing Info Directory Files
+===============================
+
+When you install an Info file onto your system, you can use the program
+`install-info' to update the Info directory file `dir'.  Normally the
+makefile for the package runs `install-info', just after copying the
+Info file into its proper installed location.
+
+  In order for the Info file to work with `install-info', you should
+use the commands `@dircategory' and `@direntry' in the Texinfo source
+file.  Use `@direntry' to specify the menu entry to add to the Info
+directory file, and use `@dircategory' to specify which part of the
+Info directory to put it in.  Here is how these commands are used in
+this manual:
+
+     @dircategory Texinfo documentation system
+     @direntry
+     * Texinfo: (texinfo).           The GNU documentation format.
+     * install-info: (texinfo)Invoking install-info. ...
+     ...
+     @end direntry
+
+  Here's what this produces in the Info file:
+
+     INFO-DIR-SECTION Texinfo documentation system
+     START-INFO-DIR-ENTRY
+     * Texinfo: (texinfo).           The GNU documentation format.
+     * install-info: (texinfo)Invoking install-info. ...
+     ...
+     END-INFO-DIR-ENTRY
+
+The `install-info' program sees these lines in the Info file, and that
+is how it knows what to do.
+
+  Always use the `@direntry' and `@dircategory' commands near the
+beginning of the Texinfo input, before the first `@node' command.  If
+you use them later on in the input, `install-info' will not notice them.
+
+  If you use `@dircategory' more than once in the Texinfo source, each
+usage specifies one category; the new menu entry is added to the Info
+directory file in each of the categories you specify.  If you use
+`@direntry' more than once, each usage specifies one menu entry; each
+of these menu entries is added to the directory in each of the
+specified categories.
+
+\1f
+File: texinfo.info,  Node: Invoking install-info,  Prev: Installing Dir Entries,  Up: Install an Info File
+
+Invoking install-info
+=====================
+
+`install-info' inserts menu entries from an Info file into the
+top-level `dir' file in the Info system (see the previous sections for
+an explanation of how the `dir' file works).  It's most often run as
+part of software installation, or when constructing a dir file for all
+manuals on a system.  Synopsis:
+
+     install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+
+  If INFO-FILE or DIR-FILE are not specified, the various options
+(described below) that define them must be.  There are no compile-time
+defaults, and standard input is never used.  `install-info' can read
+only one info file and write only one dir file per invocation.
+
+  If DIR-FILE (however specified) does not exist, `install-info'
+creates it if possible (with no entries).
+
+  Options:
+
+`--delete'
+     Delete the entries in INFO-FILE from DIR-FILE.  The file name in
+     the entry in DIR-FILE must be INFO-FILE (except for an optional
+     `.info' in either one).  Don't insert any new entries.
+
+`--dir-file=NAME'
+     Specify file name of the Info directory file.  This is equivalent
+     to using the DIR-FILE argument.
+
+`--entry=TEXT'
+     Insert TEXT as an Info directory entry; TEXT should have the form
+     of an Info menu item line plus zero or more extra lines starting
+     with whitespace.  If you specify more than one entry, they are all
+     added.  If you don't specify any entries, they are determined from
+     information in the Info file itself.
+
+`--help'
+     Display a usage message listing basic usage and all available
+     options, then exit successfully.
+
+`--info-file=FILE'
+     Specify Info file to install in the directory.  This is equivalent
+     to using the INFO-FILE argument.
+
+`--info-dir=DIR'
+     Equivalent to `--dir-file=DIR/dir'.
+
+`--item=TEXT'
+     Same as `--entry=TEXT'.  An Info directory entry is actually a
+     menu item.
+
+`--quiet'
+     Suppress warnings.
+
+`--remove'
+     Same as `--delete'.
+
+`--section=SEC'
+     Put this file's entries in section SEC of the directory.  If you
+     specify more than one section, all the entries are added in each
+     of the sections.  If you don't specify any sections, they are
+     determined from information in the Info file itself.
+
+`--version'
+     Display version information and exit successfully.
+
+
+\1f
+File: texinfo.info,  Node: Command List,  Next: Tips,  Prev: Install an Info File,  Up: Top
+
+@-Command List
+**************
+
+Here is an alphabetical list of the @-commands in Texinfo.  Square
+brackets, [ ], indicate optional arguments; an ellipsis, `...',
+indicates repeated text.
+
+
+`@WHITESPACE'
+     An `@' followed by a space, tab, or newline produces a normal,
+     stretchable, interword space.  *Note Multiple Spaces::.
+
+`@!'
+     Generate an exclamation point that really does end a sentence
+     (usually after an end-of-sentence capital letter).  *Note Ending a
+     Sentence::.
+
+`@"'
+`@''
+     Generate an umlaut or acute accent, respectively, over the next
+     character, as in o" and o'.  *Note Inserting Accents::.
+
+`@*'
+     Force a line break. Do not end a paragraph that uses `@*' with an
+     `@refill' command.  *Note Line Breaks::.
+
+`@,{C}'
+     Generate a cedilla accent under C, as in c,.  *Note Inserting
+     Accents::.
+
+`@-'
+     Insert a discretionary hyphenation point.  *Note - and
+     hyphenation::.
+
+`@.'
+     Produce a period that really does end a sentence (usually after an
+     end-of-sentence capital letter).  *Note Ending a Sentence::.
+
+`@:'
+     Indicate to TeX that an immediately preceding period, question
+     mark, exclamation mark, or colon does not end a sentence.  Prevent
+     TeX from inserting extra whitespace as it does at the end of a
+     sentence.  The command has no effect on the Info file output.
+     *Note Not Ending a Sentence::.
+
+`@='
+     Generate a macro (bar) accent over the next character, as in o=.
+     *Note Inserting Accents::.
+
+`@?'
+     Generate a question mark that really does end a sentence (usually
+     after an end-of-sentence capital letter).  *Note Ending a
+     Sentence::.
+
+`@@'
+     Stands for an at sign, `@'.  *Note Inserting @ and braces: Braces
+     Atsigns.
+
+`@^'
+`@`'
+     Generate a circumflex (hat) or grave accent, respectively, over
+     the next character, as in o^.  *Note Inserting Accents::.
+
+`@{'
+     Stands for a left brace, `{'.  *Note Inserting @ and braces:
+     Braces Atsigns.
+
+`@}'
+     Stands for a right-hand brace, `}'.
+     *Note Inserting @ and braces: Braces Atsigns.
+
+`@='
+     Generate a tilde accent over the next character, as in N~.  *Note
+     Inserting Accents::.
+
+`@AA{}'
+`@aa{}'
+     Generate the uppercase and lowercase Scandinavian A-ring letters,
+     respectively: AA, aa.  *Note Inserting Accents::.
+
+`@AE{}'
+`@ae{}'
+     Generate the uppercase and lowercase AE ligatures, respectively:
+     AE, ae.  *Note Inserting Accents::.
+
+`@afourpaper'
+     Change page dimensions for the A4 paper size.  Only allowed inside
+     `@iftex' ... `@end iftex'.  *Note A4 Paper::.
+
+`@appendix TITLE'
+     Begin an appendix.  The title appears in the table of contents of
+     a printed manual.  In Info, the title is underlined with
+     asterisks.  *Note The `@unnumbered' and `@appendix' Commands:
+     unnumbered & appendix.
+
+`@appendixsec TITLE'
+`@appendixsection TITLE'
+     Begin an appendix section within an appendix.  The section title
+     appears in the table of contents of a printed manual.  In Info,
+     the title is underlined with equal signs.  `@appendixsection' is a
+     longer spelling of the `@appendixsec' command.  *Note Section
+     Commands: unnumberedsec appendixsec heading.
+
+`@appendixsubsec TITLE'
+     Begin an appendix subsection within an appendix.  The title appears
+     in the table of contents of a printed manual.  In Info, the title
+     is underlined with hyphens.  *Note Subsection Commands:
+     unnumberedsubsec appendixsubsec subheading.
+
+`@appendixsubsubsec TITLE'
+     Begin an appendix subsubsection within an appendix subsection.  The
+     title appears in the table of contents of a printed manual.  In
+     Info, the title is underlined with periods.  *Note The `subsub'
+     Commands: subsubsection.
+
+`@asis'
+     Used following `@table', `@ftable', and `@vtable' to print the
+     table's first column without highlighting ("as is").  *Note Making
+     a Two-column Table: Two-column Tables.
+
+`@author AUTHOR'
+     Typeset AUTHOR flushleft and underline it.  *Note The `@title' and
+     `@author' Commands: title subtitle author.
+
+`@b{TEXT}'
+     Print TEXT in bold font.  No effect in Info.  *Note Fonts::.
+
+`@bullet{}'
+     Generate a large round dot, or the closest possible thing to one.
+     *Note `@bullet': bullet.
+
+`@bye'
+     Stop formatting a file.  The formatters do not see the contents of
+     a file following an `@bye' command.  *Note Ending a File::.
+
+`@c COMMENT'
+     Begin a comment in Texinfo.  The rest of the line does not appear
+     in either the Info file or the printed manual.  A synonym for
+     `@comment'.  *Note Comments: Comments.
+
+`@cartouche'
+     Highlight an example or quotation by drawing a box with rounded
+     corners around it.  Pair with `@end cartouche'.  No effect in
+     Info.  *Note Drawing Cartouches Around Examples: cartouche.)
+
+`@center LINE-OF-TEXT'
+     Center the line of text following the command.  *Note `@center':
+     titlefont center sp.
+
+`@centerchap LINE-OF-TEXT'
+     Like `@chapter', but centers the chapter title.  *Note `@chapter':
+     chapter.
+
+`@chapheading TITLE'
+     Print a chapter-like heading in the text, but not in the table of
+     contents of a printed manual.  In Info, the title is underlined
+     with asterisks.  *Note `@majorheading' and `@chapheading':
+     majorheading & chapheading.
+
+`@chapter TITLE'
+     Begin a chapter.  The chapter title appears in the table of
+     contents of a printed manual.  In Info, the title is underlined
+     with asterisks.  *Note `@chapter': chapter.
+
+`@cindex ENTRY'
+     Add ENTRY to the index of concepts.  *Note Defining the Entries of
+     an Index: Index Entries.
+
+`@cite{REFERENCE}'
+     Highlight the name of a book or other reference that lacks a
+     companion Info file.  *Note `@cite': cite.
+
+`@clear FLAG'
+     Unset FLAG, preventing the Texinfo formatting commands from
+     formatting text between subsequent pairs of `@ifset FLAG' and
+     `@end ifset' commands, and preventing `@value{FLAG}' from
+     expanding to the value to which FLAG is set.  *Note `@set'
+     `@clear' `@value': set clear value.
+
+`@code{SAMPLE-CODE}'
+     Highlight text that is an expression, a syntactically complete
+     token of a program, or a program name.  *Note `@code': code.
+
+`@comment COMMENT'
+     Begin a comment in Texinfo.  The rest of the line does not appear
+     in either the Info file or the printed manual.  A synonym for `@c'.
+     *Note Comments: Comments.
+
+`@contents'
+     Print a complete table of contents.  Has no effect in Info, which
+     uses menus instead.  *Note Generating a Table of Contents:
+     Contents.
+
+`@copyright{}'
+     Generate a copyright symbol.  *Note `@copyright': copyright symbol.
+
+`@defcodeindex INDEX-NAME'
+     Define a new index and its indexing command.  Print entries in an
+     `@code' font.  *Note Defining New Indices: New Indices.
+
+`@defcv CATEGORY CLASS NAME'
+`@defcvx CATEGORY CLASS NAME'
+     Format a description for a variable associated with a class in
+     object-oriented programming.  Takes three arguments: the category
+     of thing being defined, the class to which it belongs, and its
+     name.  *Note Definition Commands::, and *Note Def Cmds in Detail:
+     deffnx.
+
+`@deffn CATEGORY NAME ARGUMENTS...'
+`@deffnx CATEGORY NAME ARGUMENTS...'
+     Format a description for a function, interactive command, or
+     similar entity that may take arguments.  `@deffn' takes as
+     arguments the category of entity being described, the name of this
+     particular entity, and its arguments, if any.  *Note Definition
+     Commands::.
+
+`@defindex INDEX-NAME'
+     Define a new index and its indexing command.  Print entries in a
+     roman font.  *Note Defining New Indices: New Indices.
+
+`@definfoenclose NEW-COMMAND, BEFORE, AFTER,'
+     Create new @-command for Info that marks text by enclosing it in
+     strings that precede and follow the text.  Write definition inside
+     of `@ifinfo' ... `@end ifinfo'. *Note Customized Highlighting::.
+
+`@defivar CLASS INSTANCE-VARIABLE-NAME'
+`@defivarx CLASS INSTANCE-VARIABLE-NAME'
+     This command formats a description for an instance variable in
+     object-oriented programming.  The command is equivalent to `@defcv
+     {Instance Variable} ...'.  *Note Definition Commands::, and *Note
+     Def Cmds in Detail: deffnx.
+
+`@defmac MACRO-NAME ARGUMENTS...'
+`@defmacx MACRO-NAME ARGUMENTS...'
+     Format a description for a macro.  The command is equivalent to
+     `@deffn Macro ...'.  *Note Definition Commands::, and *Note Def
+     Cmds in Detail: deffnx.
+
+`@defmethod CLASS METHOD-NAME ARGUMENTS...'
+`@defmethodx CLASS METHOD-NAME ARGUMENTS...'
+     Format a description for a method in object-oriented programming.
+     The command is equivalent to `@defop Method ...'.  Takes as
+     arguments the name of the class of the method, the name of the
+     method, and its arguments, if any.  *Note Definition Commands::,
+     and *Note Def Cmds in Detail: deffnx.
+
+`@defop CATEGORY CLASS NAME ARGUMENTS...'
+`@defopx CATEGORY CLASS NAME ARGUMENTS...'
+     Format a description for an operation in object-oriented
+     programming.  `@defop' takes as arguments the overall name of the
+     category of operation, the name of the class of the operation, the
+     name of the operation, and its arguments, if any.  *Note
+     Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@defopt OPTION-NAME'
+`@defoptx OPTION-NAME'
+     Format a description for a user option.  The command is equivalent
+     to `@defvr {User Option} ...'.  *Note Definition Commands::, and
+     *Note Def Cmds in Detail: deffnx.
+
+`@defspec SPECIAL-FORM-NAME ARGUMENTS...'
+`@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
+     Format a description for a special form.  The command is
+     equivalent to `@deffn {Special Form} ...'.  *Note Definition
+     Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
+`@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
+     Format a description for a data type.  `@deftp' takes as arguments
+     the category, the name of the type (which is a word like `int' or
+     `float'), and then the names of attributes of objects of that type.
+     *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
+`@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
+     Format a description for a function or similar entity that may take
+     arguments and that is typed.  `@deftypefn' takes as arguments the
+     classification of entity being described, the type, the name of the
+     entity, and its arguments, if any.  *Note Definition Commands::,
+     and *Note Def Cmds in Detail: deffnx.
+
+`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
+`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
+     Format a description for a function in a typed language.  The
+     command is equivalent to `@deftypefn Function ...'.  *Note
+     Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
+`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
+     Format a description for a typed method in object-oriented
+     programming.  Takes as arguments the name of the class of the
+     method, the return type of the method, the name of the method, and
+     its arguments, if any.  *Note Definition Commands::, and *Note Def
+     Cmds in Detail: deffnx.
+
+`@deftypevr CLASSIFICATION DATA-TYPE NAME'
+`@deftypevrx CLASSIFICATION DATA-TYPE NAME'
+     Format a description for something like a variable in a typed
+     language--an entity that records a value.  Takes as arguments the
+     classification of entity being described, the type, and the name
+     of the entity.  *Note Definition Commands::, and *Note Def Cmds in
+     Detail: deffnx.
+
+`@deftypevar DATA-TYPE VARIABLE-NAME'
+`@deftypevarx DATA-TYPE VARIABLE-NAME'
+     Format a description for a variable in a typed language.  The
+     command is equivalent to `@deftypevr Variable ...'.  *Note
+     Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@defun FUNCTION-NAME ARGUMENTS...'
+`@defunx FUNCTION-NAME ARGUMENTS...'
+     Format a description for functions.  The command is equivalent to
+     `@deffn Function ...'.  *Note Definition Commands::, and *Note Def
+     Cmds in Detail: deffnx.
+
+`@defvar VARIABLE-NAME'
+`@defvarx VARIABLE-NAME'
+     Format a description for variables.  The command is equivalent to
+     `@defvr Variable ...'.  *Note Definition Commands::, and *Note Def
+     Cmds in Detail: deffnx.
+
+`@defvr CATEGORY NAME'
+`@defvrx CATEGORY NAME'
+     Format a description for any kind of variable.  `@defvr' takes as
+     arguments the category of the entity and the name of the entity.
+     *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@detailmenu{}'
+     Avoid `makeinfo' confusion stemming from the detailed node listing
+     in a master menu.  *Note Master Menu Parts::.
+
+`@dfn{TERM}'
+     Highlight the introductory or defining use of a term.  *Note
+     `@dfn': dfn.
+
+`@dircategory DIRPART'
+     Specify a part of the Info directory menu where this file's entry
+     should go.  *Note Installing Dir Entries::.
+
+`@direntry'
+     Begin the Info directory menu entry for this file.  *Note
+     Installing Dir Entries::.
+
+`@display'
+     Begin a kind of example.  Indent text, do not fill, do not select a
+     new font.  Pair with `@end display'.  *Note `@display': display.
+
+`@dmn{DIMENSION}'
+     Format a unit of measure, as in 12pt.  Causes TeX to insert a thin
+     space before DIMENSION.  No effect in Info.  *Note `@dmn': dmn.
+
+`@dotaccent{C}'
+     Generate a dot accent over the character C, as in oo..  *Note
+     Inserting Accents::.
+
+`@dots{}'
+     Insert an ellipsis: `...'.  *Note `@dots{}': dots.
+
+`@email{ADDRESS[, DISPLAYED-TEXT]}'
+     Indicate an electronic mail address.  *Note `@email': email.
+
+`@emph{TEXT}'
+     Highlight TEXT; text is displayed in _italics_ in printed output,
+     and surrounded by asterisks in Info.  *Note Emphasizing Text:
+     Emphasis.
+
+`@end ENVIRONMENT'
+     Ends ENVIRONMENT, as in `@end example'.  *Note @-commands:
+     Formatting Commands.
+
+`@enddots{}'
+     Generate an end-of-sentence of ellipsis, like this ....  *Note
+     `@dots{}': dots.
+
+`@enumerate [NUMBER-OR-LETTER]'
+     Begin a numbered list, using `@item' for each entry.  Optionally,
+     start list with NUMBER-OR-LETTER.  Pair with `@end enumerate'.
+     *Note `@enumerate': enumerate.
+
+`@equiv{}'
+     Indicate to the reader the exact equivalence of two forms with a
+     glyph: `=='.  *Note Equivalence::.
+
+`@error{}'
+     Indicate to the reader with a glyph that the following text is an
+     error message: `error-->'.  *Note Error Glyph::.
+
+`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
+     Specify page footings resp. headings for even-numbered (left-hand)
+     pages.  Only allowed inside `@iftex'.  *Note How to Make Your Own
+     Headings: Custom Headings.
+
+`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
+     Specify page footings resp. headings for every page.  Not relevant
+     to Info.  *Note How to Make Your Own Headings: Custom Headings.
+
+`@example'
+     Begin an example.  Indent text, do not fill, and select
+     fixed-width font.  Pair with `@end example'.  *Note `@example':
+     example.
+
+`@exclamdown{}'
+     Produce an upside-down exclamation point.  *Note Inserting
+     Accents::.
+
+`@exdent LINE-OF-TEXT'
+     Remove any indentation a line might have.  *Note Undoing the
+     Indentation of a Line: exdent.
+
+`@expansion{}'
+     Indicate the result of a macro expansion to the reader with a
+     special glyph: `==>'.  *Note ==> Indicating an Expansion:
+     expansion.
+
+`@file{FILENAME}'
+     Highlight the name of a file, buffer, node, or directory.  *Note
+     `@file': file.
+
+`@finalout'
+     Prevent TeX from printing large black warning rectangles beside
+     over-wide lines.  *Note Overfull hboxes::.
+
+`@findex ENTRY'
+     Add ENTRY to the index of functions.  *Note Defining the Entries
+     of an Index: Index Entries.
+
+`@flushleft'
+`@flushright'
+     Left justify every line but leave the right end ragged.  Leave
+     font as is.  Pair with `@end flushleft'.  `@flushright' analogous.
+     *Note `@flushleft' and `@flushright': flushleft & flushright.
+
+`@footnote{TEXT-OF-FOOTNOTE}'
+     Enter a footnote.  Footnote text is printed at the bottom of the
+     page by TeX; Info may format in either `End' node or `Separate'
+     node style.  *Note Footnotes::.
+
+`@footnotestyle STYLE'
+     Specify an Info file's footnote style, either `end' for the end
+     node style or `separate' for the separate node style.  *Note
+     Footnotes::.
+
+`@format'
+     Begin a kind of example.  Like `@example' or `@display', but do
+     not narrow the margins and do not select the fixed-width font.
+     Pair with `@end format'.  *Note `@example': example.
+
+`@ftable FORMATTING-COMMAND'
+     Begin a two-column table, using `@item' for each entry.
+     Automatically enter each of the items in the first column into the
+     index of functions.  Pair with `@end ftable'.  The same as
+     `@table', except for indexing.  *Note `@ftable' and `@vtable':
+     ftable vtable.
+
+`@group'
+     Hold text together that must appear on one printed page.  Pair with
+     `@end group'.  Not relevant to Info.  *Note `@group': group.
+
+`@H{C}'
+     Generate the long Hungarian umlaut accent over C, as in o''.
+
+`@heading TITLE'
+     Print an unnumbered section-like heading in the text, but not in
+     the table of contents of a printed manual.  In Info, the title is
+     underlined with equal signs.  *Note Section Commands:
+     unnumberedsec appendixsec heading.
+
+`@headings ON-OFF-SINGLE-DOUBLE'
+     Turn page headings on or off, and/or specify single-sided or
+     double-sided page headings for printing.  *Note The `@headings'
+     Command: headings on off.
+
+`@html'
+     Enter HTML completely.  Pair with `@end html'.  *Note Raw
+     Formatter Commands::.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+     Explicitly define hyphenation points.  *Note `@-' and
+     `@hyphenation': - and hyphenation.
+
+`@i{TEXT}'
+     Print TEXT in italic font.  No effect in Info.  *Note Fonts::.
+
+`@ifclear FLAG'
+     If FLAG is cleared, the Texinfo formatting commands format text
+     between `@ifclear FLAG' and the following `@end ifclear' command.
+     *Note `@set' `@clear' `@value': set clear value.
+
+`@ifhtml'
+`@ifinfo'
+     Begin a stretch of text that will be ignored by TeX when it
+     typesets the printed manual.  The text appears only in the HTML
+     resp. Info file.  Pair with `@end ifhtml' resp. `@end ifinfo'.
+     *Note Conditionals::.
+
+`@ifnothtml'
+`@ifnotinfo'
+`@ifnottex'
+     Begin a stretch of text that will be ignored in one output format
+     but not the others.  The text appears only in the format not
+     specified.  Pair with `@end ifnothtml' resp. `@end ifnotinfo' resp.
+     `@end ifnotinfo'.  *Note Conditionals::.
+
+`@ifset FLAG'
+     If FLAG is set, the Texinfo formatting commands format text
+     between `@ifset FLAG' and the following `@end ifset' command.
+     *Note `@set' `@clear' `@value': set clear value.
+
+`@iftex'
+     Begin a stretch of text that will not appear in the Info file, but
+     will be processed only by TeX.  Pair with `@end iftex'.  *Note
+     Conditionally Visible Text: Conditionals.
+
+`@ignore'
+     Begin a stretch of text that will not appear in either the Info
+     file or the printed output.  Pair with `@end ignore'.  *Note
+     Comments and Ignored Text: Comments.
+
+`@image{FILENAME, [WIDTH], [HEIGHT]}'
+     Include graphics image in external FILENAME scaled to the given
+     WIDTH and/or HEIGHT.  *Note Images::.
+
+`@include FILENAME'
+     Incorporate the contents of the file FILENAME into the Info file
+     or printed document.  *Note Include Files::.
+
+`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
+     Make a cross reference to an Info file for which there is no
+     printed manual.  *Note Cross references using `@inforef': inforef.
+
+`\input MACRO-DEFINITIONS-FILE'
+     Use the specified macro definitions file.  This command is used
+     only in the first line of a Texinfo file to cause TeX to make use
+     of the `texinfo' macro definitions file.  The backslash in `\input'
+     is used instead of an `@' because TeX does not recognize `@' until
+     after it has read the definitions file.  *Note The Texinfo File
+     Header: Header.
+
+`@item'
+     Indicate the beginning of a marked paragraph for `@itemize' and
+     `@enumerate'; indicate the beginning of the text of a first column
+     entry for `@table', `@ftable', and `@vtable'.  *Note Lists and
+     Tables::.
+
+`@itemize  MARK-GENERATING-CHARACTER-OR-COMMAND'
+     Produce a sequence of indented paragraphs, with a mark inside the
+     left margin at the beginning of each paragraph.  Pair with `@end
+     itemize'.  *Note `@itemize': itemize.
+
+`@itemx'
+     Like `@item' but do not generate extra vertical space above the
+     item text.  *Note `@itemx': itemx.
+
+`@kbd{KEYBOARD-CHARACTERS}'
+     Indicate text that is characters of input to be typed by users.
+     *Note `@kbd': kbd.
+
+`@kbdinputstyle STYLE'
+     Specify when `@kbd' should use a font distinct from `@code'.
+     *Note `@kbd': kbd.
+
+`@key{KEY-NAME}'
+     Indicate a name for a key on a keyboard.  *Note `@key': key.
+
+`@kindex ENTRY'
+     Add ENTRY to the index of keys.  *Note Defining the Entries of an
+     Index: Index Entries.
+
+`@L{}'
+`@l{}'
+     Generate the uppercase and lowercase Polish suppressed-L letters,
+     respectively: /L, /l.
+
+`@lisp'
+     Begin an example of Lisp code.  Indent text, do not fill, and
+     select fixed-width font.  Pair with `@end lisp'.  *Note `@lisp':
+     Lisp Example.
+
+`@lowersections'
+     Change subsequent chapters to sections, sections to subsections,
+     and so on. *Note `@raisesections' and `@lowersections':
+     Raise/lower sections.
+
+`@macro MACRO-NAME {PARAMS}'
+     Define a new Texinfo command `@MACRO-NAME{PARAMS}'.  Only
+     supported by `makeinfo' and `texi2dvi'.  *Note Defining Macros::.
+
+`@majorheading TITLE'
+     Print a chapter-like heading in the text, but not in the table of
+     contents of a printed manual.  Generate more vertical whitespace
+     before the heading than the `@chapheading' command.  In Info, the
+     chapter heading line is underlined with asterisks.  *Note
+     `@majorheading' and `@chapheading': majorheading & chapheading.
+
+`@math{MATHEMATICAL-EXPRESSION}'
+     Format a mathematical expression.  *Note `@math' - Inserting
+     Mathematical Expressions: math.
+
+`@menu'
+     Mark the beginning of a menu of nodes in Info.  No effect in a
+     printed manual.  Pair with `@end menu'.  *Note Menus::.
+
+`@minus{}'
+     Generate a minus sign, `-'.  *Note `@minus': minus.
+
+`@multitable COLUMN-WIDTH-SPEC'
+     Begin a multi-column table.  Pair with `@end multitable'.  *Note
+     Multitable Column Widths::.
+
+`@need N'
+     Start a new page in a printed manual if fewer than N mils
+     (thousandths of an inch) remain on the current page.  *Note
+     `@need': need.
+
+`@node NAME, NEXT, PREVIOUS, UP'
+     Define the beginning of a new node in Info, and serve as a locator
+     for references for TeX.  *Note `@node': node.
+
+`@noindent'
+     Prevent text from being indented as if it were a new paragraph.
+     *Note `@noindent': noindent.
+
+`@O{}'
+`@o{}'
+     Generate the uppercase and lowercase O-with-slash letters,
+     respectively: /O, /o.
+
+`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
+     Specify page footings resp. headings for odd-numbered (right-hand)
+     pages.  Only allowed inside `@iftex'.  *Note How to Make Your Own
+     Headings: Custom Headings.
+
+`@OE{}'
+`@oe{}'
+     Generate the uppercase and lowercase OE ligatures, respectively:
+     OE, oe.  *Note Inserting Accents::.
+
+`@page'
+     Start a new page in a printed manual.  No effect in Info.  *Note
+     `@page': page.
+
+`@paragraphindent INDENT'
+     Indent paragraphs by INDENT number of spaces; delete indentation
+     if the value of INDENT is 0; and do not change indentation if
+     INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.
+
+`@pindex ENTRY'
+     Add ENTRY to the index of programs.  *Note Defining the Entries of
+     an Index: Index Entries.
+
+`@point{}'
+     Indicate the position of point in a buffer to the reader with a
+     glyph: `-!-'.  *Note Indicating Point in a Buffer: Point Glyph.
+
+`@pounds{}'
+     Generate the pounds sterling currency sign.  *Note `@pounds{}':
+     pounds.
+
+`@print{}'
+     Indicate printed output to the reader with a glyph: `-|'.  *Note
+     Print Glyph::.
+
+`@printindex INDEX-NAME'
+     Print an alphabetized two-column index in a printed manual or
+     generate an alphabetized menu of index entries for Info.  *Note
+     Printing Indices & Menus::.
+
+`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+     Make a reference that starts with a lower case `see' in a printed
+     manual.  Use within parentheses only.  Do not follow command with a
+     punctuation mark--the Info formatting commands automatically insert
+     terminating punctuation as needed.  Only the first argument is
+     mandatory.  *Note `@pxref': pxref.
+
+`@questiondown{}'
+     Generate an upside-down question mark.  *Note Inserting Accents::.
+
+`@quotation'
+     Narrow the margins to indicate text that is quoted from another
+     real or imaginary work.  Write command on a line of its own.  Pair
+     with `@end quotation'.  *Note `@quotation': quotation.
+
+`@r{TEXT}'
+     Print TEXT in roman font.  No effect in Info.  *Note Fonts::.
+
+`@raisesections'
+     Change subsequent sections to chapters, subsections to sections,
+     and so on.  *Note `@raisesections' and `@lowersections':
+     Raise/lower sections.
+
+`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+     Make a reference.  In a printed manual, the reference does not
+     start with a `See'.  Follow command with a punctuation mark.  Only
+     the first argument is mandatory.  *Note `@ref': ref.
+
+`@refill'
+     In Info, refill and indent the paragraph after all the other
+     processing has been done.  No effect on TeX, which always refills.
+     This command is no longer needed, since all formatters now
+     automatically refill.  *Note Refilling Paragraphs::.
+
+`@result{}'
+     Indicate the result of an expression to the reader with a special
+     glyph: `=>'.  *Note `@result': result.
+
+`@ringaccent{C}'
+     Generate a ring accent over the next character, as in o*.  *Note
+     Inserting Accents::.
+
+`@samp{TEXT}'
+     Highlight TEXT that is a literal example of a sequence of
+     characters.  Used for single characters, for statements, and often
+     for entire shell commands.  *Note `@samp': samp.
+
+`@sc{TEXT}'
+     Set TEXT in a printed output in THE SMALL CAPS FONT and set text
+     in the Info file in uppercase letters.  *Note Smallcaps::.
+
+`@section TITLE'
+     Begin a section within a chapter.  In a printed manual, the section
+     title is numbered and appears in the table of contents.  In Info,
+     the title is underlined with equal signs.  *Note `@section':
+     section.
+
+`@set FLAG [STRING]'
+     Make FLAG active, causing the Texinfo formatting commands to
+     format text between subsequent pairs of `@ifset FLAG' and `@end
+     ifset' commands.  Optionally, set value of FLAG to STRING.  *Note
+     `@set' `@clear' `@value': set clear value.
+
+`@setchapternewpage ON-OFF-ODD'
+     Specify whether chapters start on new pages, and if so, whether on
+     odd-numbered (right-hand) new pages.  *Note `@setchapternewpage':
+     setchapternewpage.
+
+`@setfilename INFO-FILE-NAME'
+     Provide a name to be used by the Info file.  This command is
+     essential for TeX formatting as well, even though it produces no
+     output.  *Note `@setfilename': setfilename.
+
+`@settitle TITLE'
+     Provide a title for page headers in a printed manual.  *Note
+     `@settitle': settitle.
+
+`@shortcontents'
+     Print a short table of contents.  Not relevant to Info, which uses
+     menus rather than tables of contents.  A synonym for
+     `@summarycontents'.  *Note Generating a Table of Contents:
+     Contents.
+
+`@shorttitlepage{TITLE}'
+     Generate a minimal title page.  *Note `@titlepage': titlepage.
+
+`@smallbook'
+     Cause TeX to produce a printed manual in a 7 by 9.25 inch format
+     rather than the regular 8.5 by 11 inch format.  *Note Printing
+     Small Books: smallbook.  Also, see *Note `@smallexample' and
+     `@smalllisp': smallexample & smalllisp.
+
+`@smallexample'
+     Indent text to indicate an example.  Do not fill, select
+     fixed-width font.  In `@smallbook' format, print text in a smaller
+     font than with `@example'.  Pair with `@end smallexample'.  *Note
+     `@smallexample' and `@smalllisp': smallexample & smalllisp.
+
+`@smalllisp'
+     Begin an example of Lisp code.  Indent text, do not fill, select
+     fixed-width font.  In `@smallbook' format, print text in a smaller
+     font.  Pair with `@end smalllisp'.  *Note `@smallexample' and
+     `@smalllisp': smallexample & smalllisp.
+
+`@sp N'
+     Skip N blank lines.  *Note `@sp': sp.
+
+`@ss{}'
+     Generate the German sharp-S es-zet letter, ss.  *Note Inserting
+     Accents::.
+
+`@strong TEXT'
+     Emphasize TEXT by typesetting it in a *bold* font for the printed
+     manual and by surrounding it with asterisks for Info.  *Note
+     Emphasizing Text: emph & strong.
+
+`@subheading TITLE'
+     Print an unnumbered subsection-like heading in the text, but not in
+     the table of contents of a printed manual.  In Info, the title is
+     underlined with hyphens.  *Note `@unnumberedsubsec'
+     `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
+     subheading.
+
+`@subsection TITLE'
+     Begin a subsection within a section.  In a printed manual, the
+     subsection title is numbered and appears in the table of contents.
+     In Info, the title is underlined with hyphens.  *Note
+     `@subsection': subsection.
+
+`@subsubheading TITLE'
+     Print an unnumbered subsubsection-like heading in the text, but
+     not in the table of contents of a printed manual.  In Info, the
+     title is underlined with periods.  *Note The `subsub' Commands:
+     subsubsection.
+
+`@subsubsection TITLE'
+     Begin a subsubsection within a subsection.  In a printed manual,
+     the subsubsection title is numbered and appears in the table of
+     contents.  In Info, the title is underlined with periods.  *Note
+     The `subsub' Commands: subsubsection.
+
+`@subtitle TITLE'
+     In a printed manual, set a subtitle in a normal sized font flush to
+     the right-hand side of the page.  Not relevant to Info, which does
+     not have title pages.  *Note `@title' `@subtitle' and `@author'
+     Commands: title subtitle author.
+
+`@summarycontents'
+     Print a short table of contents.  Not relevant to Info, which uses
+     menus rather than tables of contents.  A synonym for
+     `@shortcontents'.  *Note Generating a Table of Contents: Contents.
+
+`@syncodeindex FROM-INDEX INTO-INDEX'
+     Merge the index named in the first argument into the index named in
+     the second argument, printing the entries from the first index in
+     `@code' font.  *Note Combining Indices::.
+
+`@synindex FROM-INDEX INTO-INDEX'
+     Merge the index named in the first argument into the index named in
+     the second argument.  Do not change the font of FROM-INDEX
+     entries.  *Note Combining Indices::.
+
+`@t{TEXT}'
+     Print TEXT in a fixed-width, typewriter-like font.  No effect in
+     Info.  *Note Fonts::.
+
+`@tab'
+     Separate columns in a multitable.  *Note Multitable Rows::.
+
+`@table FORMATTING-COMMAND'
+     Begin a two-column table, using `@item' for each entry.  Write
+     each first column entry on the same line as `@item'.  First column
+     entries are printed in the font resulting from FORMATTING-COMMAND.
+     Pair with `@end table'.  *Note Making a Two-column Table:
+     Two-column Tables.  Also see *Note `@ftable' and `@vtable': ftable
+     vtable, and *Note `@itemx': itemx.
+
+`@TeX{}'
+     Insert the logo TeX.  *Note Inserting TeX and (C): TeX and
+     copyright.
+
+`@tex'
+     Enter TeX completely.  Pair with `@end tex'.  *Note Raw Formatter
+     Commands::.
+
+`@thischapter'
+`@thischaptername'
+`@thisfile'
+`@thispage'
+`@thistitle'
+     Only allowed in a heading or footing.  Stands for the number and
+     name of the current chapter (in the format `Chapter 1: Title'),
+     the chapter name only, the filename, the current page number, and
+     the title of the document, respectively.  *Note How to Make Your
+     Own Headings: Custom Headings.
+
+`@tieaccent{CC}'
+     Generate a tie-after accent over the next two characters CC, as in
+     `oo['.  *Note Inserting Accents::.
+
+`@tindex ENTRY'
+     Add ENTRY to the index of data types.  *Note Defining the Entries
+     of an Index: Index Entries.
+
+`@title TITLE'
+     In a printed manual, set a title flush to the left-hand side of the
+     page in a larger than normal font and underline it with a black
+     rule.  Not relevant to Info, which does not have title pages.
+     *Note The `@title' `@subtitle' and `@author' Commands: title
+     subtitle author.
+
+`@titlefont{TEXT}'
+     In a printed manual, print TEXT in a larger than normal font.  Not
+     relevant to Info, which does not have title pages.  *Note The
+     `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
+
+`@titlepage'
+     Indicate to Texinfo the beginning of the title page.  Write
+     command on a line of its own.  Pair with `@end titlepage'.
+     Nothing between `@titlepage' and `@end titlepage' appears in Info.
+     *Note `@titlepage': titlepage.
+
+`@today{}'
+     Insert the current date, in `1 Jan 1900' style.  *Note How to Make
+     Your Own Headings: Custom Headings.
+
+`@top TITLE'
+     In a Texinfo file to be formatted with `makeinfo', identify the
+     topmost `@node' line in the file, which must be written on the line
+     immediately preceding the `@top' command.  Used for `makeinfo''s
+     node pointer insertion feature.  The title is underlined with
+     asterisks.  Both the `@node' line and the `@top' line normally
+     should be enclosed by `@ifinfo' and `@end ifinfo'.  In TeX and
+     `texinfo-format-buffer', the `@top' command is merely a synonym
+     for `@unnumbered'.  *Note Creating Pointers with `makeinfo':
+     makeinfo Pointer Creation.
+
+`@u{C}'
+`@ubaraccent{C}'
+`@udotaccent{C}'
+     Generate a breve, underbar, or underdot accent, respectively, over
+     or under the character C, as in o(, o_, .o.  *Note Inserting
+     Accents::.
+
+`@unnumbered TITLE'
+     In a printed manual, begin a chapter that appears without chapter
+     numbers of any kind.  The title appears in the table of contents
+     of a printed manual.  In Info, the title is underlined with
+     asterisks.  *Note `@unnumbered' and `@appendix': unnumbered &
+     appendix.
+
+`@unnumberedsec TITLE'
+     In a printed manual, begin a section that appears without section
+     numbers of any kind.  The title appears in the table of contents
+     of a printed manual.  In Info, the title is underlined with equal
+     signs.  *Note Section Commands: unnumberedsec appendixsec heading.
+
+`@unnumberedsubsec TITLE'
+     In a printed manual, begin an unnumbered subsection within a
+     chapter.  The title appears in the table of contents of a printed
+     manual.  In Info, the title is underlined with hyphens.  *Note
+     `@unnumberedsubsec' `@appendixsubsec' `@subheading':
+     unnumberedsubsec appendixsubsec subheading.
+
+`@unnumberedsubsubsec TITLE'
+     In a printed manual, begin an unnumbered subsubsection within a
+     chapter.  The title appears in the table of contents of a printed
+     manual.  In Info, the title is underlined with periods.  *Note The
+     `subsub' Commands: subsubsection.
+
+`@uref{URL[, DISPLAYED-TEXT}'
+     Define a cross reference to an external uniform resource locator
+     for the World Wide Web.  *Note `@url': url.
+
+`@url{URL}'
+     Indicate text that is a uniform resource locator for the World Wide
+     Web.  *Note `@url': url.
+
+`@v{C}'
+     Generate check accent over the character C, as in o<.  *Note
+     Inserting Accents::.
+
+`@value{FLAG}'
+     Replace FLAG with the value to which it is set by `@set FLAG'.
+     *Note `@set' `@clear' `@value': set clear value.
+
+`@var{METASYNTACTIC-VARIABLE}'
+     Highlight a metasyntactic variable, which is something that stands
+     for another piece of text.  *Note Indicating Metasyntactic
+     Variables: var.
+
+`@vindex ENTRY'
+     Add ENTRY to the index of variables.  *Note Defining the Entries
+     of an Index: Index Entries.
+
+`@vskip AMOUNT'
+     In a printed manual, insert whitespace so as to push text on the
+     remainder of the page towards the bottom of the page.  Used in
+     formatting the copyright page with the argument `0pt plus 1filll'.
+     (Note spelling of `filll'.)  `@vskip' may be used only in
+     contexts ignored for Info.  *Note The Copyright Page and Printed
+     Permissions: Copyright & Permissions.
+
+`@vtable FORMATTING-COMMAND'
+     Begin a two-column table, using `@item' for each entry.
+     Automatically enter each of the items in the first column into the
+     index of variables.  Pair with `@end vtable'.  The same as
+     `@table', except for indexing.  *Note `@ftable' and `@vtable':
+     ftable vtable.
+
+`@w{TEXT}'
+     Prevent TEXT from being split across two lines.  Do not end a
+     paragraph that uses `@w' with an `@refill' command.  *Note `@w': w.
+
+`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+     Make a reference that starts with `See' in a printed manual.
+     Follow command with a punctuation mark.  Only the first argument is
+     mandatory.  *Note `@xref': xref.
+
+\1f
+File: texinfo.info,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top
+
+Tips and Hints
+**************
+
+Here are some tips for writing Texinfo documentation:
+
+   * Write in the present tense, not in the past or the future.
+
+   * Write actively!  For example, write "We recommend that ..." rather
+     than "It is recommended that ...".
+
+   * Use 70 or 72 as your fill column.  Longer lines are hard to read.
+
+   * Include a copyright notice and copying permissions.
+
+Index, Index, Index!
+....................
+
+Write many index entries, in different ways.  Readers like indices;
+they are helpful and convenient.
+
+  Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards.  In either
+case, write an entry before the paragraph to which it applies.  This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+  Here are more hints we have found valuable:
+
+   * Write each index entry differently, so each entry refers to a
+     different place in the document.
+
+   * Write index entries only where a topic is discussed significantly.
+     For example, it is not useful to index "debugging information" in
+     a chapter on reporting bugs.  Someone who wants to know about
+     debugging information will certainly not find it in that chapter.
+
+   * Consistently capitalize the first word of every concept index
+     entry, or else consistently use lower case.  Terse entries often
+     call for lower case; longer entries for capitalization.  Whichever
+     case convention you use, please use one or the other consistently!
+     Mixing the two styles looks bad.
+
+   * Always capitalize or use upper case for those words in an index for
+     which this is proper, such as names of countries or acronyms.
+     Always use the appropriate case for case-sensitive names, such as
+     those in C or Lisp.
+
+   * Write the indexing commands that refer to a whole section
+     immediately after the section command, and write the indexing
+     commands that refer to the paragraph before the paragraph.
+
+     In the example that follows, a blank line comes after the index
+     entry for "Leaping":
+
+          @section The Dog and the Fox
+          @cindex Jumping, in general
+          @cindex Leaping
+          
+          @cindex Dog, lazy, jumped over
+          @cindex Lazy dog jumped over
+          @cindex Fox, jumps over dog
+          @cindex Quick fox jumps over dog
+          The quick brown fox jumps over the lazy dog.
+
+     (Note that the example shows entries for the same concept that are
+     written in different ways--`Lazy dog', and `Dog, lazy'--so readers
+     can look up the concept in different ways.)
+
+Blank Lines
+...........
+
+   * Insert a blank line between a sectioning command and the first
+     following sentence or paragraph, or between the indexing commands
+     associated with the sectioning command and the first following
+     sentence or paragraph, as shown in the tip on indexing.
+     Otherwise, a formatter may fold title and paragraph together.
+
+   * Always insert a blank line before an `@table' command and after an
+     `@end table' command; but never insert a blank line after an
+     `@table' command or before an `@end table' command.
+
+     For example,
+
+          Types of fox:
+          
+          @table @samp
+          @item Quick
+          Jump over lazy dogs.
+          
+          @item Brown
+          Also jump over lazy dogs.
+          @end table
+          @noindent
+          On the other hand, ...
+
+     Insert blank lines before and after `@itemize' ... `@end itemize'
+     and `@enumerate' ... `@end enumerate' in the same way.
+
+Complete Phrases
+................
+
+Complete phrases are easier to read than ...
+
+   * Write entries in an itemized list as complete sentences; or at
+     least, as complete phrases.  Incomplete expressions ... awkward
+     ... like this.
+
+   * Write the prefatory sentence or phrase for a multi-item list or
+     table as a complete expression.  Do not write "You can set:";
+     instead, write "You can set these variables:".  The former
+     expression sounds cut off.
+
+Editions, Dates and Versions
+............................
+
+Write the edition and version numbers and date in three places in every
+manual:
+
+  1. In the first `@ifinfo' section, for people reading the Texinfo
+     file.
+
+  2. In the `@titlepage' section, for people reading the printed manual.
+
+  3. In the `Top' node, for people reading the Info file.
+
+Also, it helps to write a note before the first `@ifinfo' section to
+explain what you are doing.
+
+For example:
+
+     @c ===> NOTE! <==
+     @c Specify the edition and version numbers and date
+     @c in *three* places:
+     @c   1. First ifinfo section  2. title page  3. top node
+     @c To find the locations, search for !!set
+     
+     @ifinfo
+     @c !!set edition, date, version
+     This is Edition 4.03, January 1992,
+     of the @cite{GDB Manual} for GDB Version 4.3.
+     ...
+
+--or use `@set' and `@value' (*note `@value' Example: value Example.).
+
+Definition Commands
+...................
+
+Definition commands are `@deffn', `@defun', `@defmac', and the like,
+and enable you to write descriptions in a uniform format.
+
+   * Write just one definition command for each entity you define with a
+     definition command.  The automatic indexing feature creates an
+     index entry that leads the reader to the definition.
+
+   * Use `@table' ... `@end table' in an appendix that contains a
+     summary of functions, not `@deffn' or other definition commands.
+
+Capitalization
+..............
+
+   * Capitalize "Texinfo"; it is a name.  Do not write the `x' or `i'
+     in upper case.
+
+   * Capitalize "Info"; it is a name.
+
+   * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
+     `X'.  This command causes the formatters to typeset the name
+     according to the wishes of Donald Knuth, who wrote TeX.
+
+Spaces
+......
+
+Do not use spaces to format a Texinfo file, except inside of `@example'
+... `@end example' and similar commands.
+
+  For example, TeX fills the following:
+
+         @kbd{C-x v}
+         @kbd{M-x vc-next-action}
+            Perform the next logical operation
+            on the version-controlled file
+            corresponding to the current buffer.
+
+so it looks like this:
+
+     `C-x v' `M-x vc-next-action' Perform the next logical operation on
+     the version-controlled file corresponding to the current buffer.
+
+In this case, the text should be formatted with `@table', `@item', and
+`@itemx', to create a table.
+
+@code, @samp, @var, and `---'
+.............................
+
+   * Use `@code' around Lisp symbols, including command names.  For
+     example,

 
 

-In the following, the sample text is _indented_; comments on it are
-not.  The complete file, without any comments, is shown in *Note Sample
-Texinfo File::.
+          The main function is @code{vc-next-action}, ...

 
 

-Part 1: Header
---------------
+   * Avoid putting letters such as `s' immediately after an `@code'.
+     Such letters look bad.
+
+   * Use `@var' around meta-variables.  Do not write angle brackets
+     around them.
+
+   * Use three hyphens in a row, `---', to indicate a long dash.  TeX
+     typesets these as a long dash and the Info formatters reduce three
+     hyphens to two.
+
+Periods Outside of Quotes
+.........................
+
+Place periods and other punctuation marks _outside_ of quotations,
+unless the punctuation is part of the quotation.  This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+  For example, you should write the following sentence with the period
+outside the end quotation marks:
+
+     Evidently, `au' is an abbreviation for ``author''.
+
+since `au' does _not_ serve as an abbreviation for `author.' (with a
+period following the word).
+
+Introducing New Terms
+.....................
+
+   * Introduce new terms so that a reader who does not know them can
+     understand them from context; or write a definition for the term.
+
+     For example, in the following, the terms "check in", "register" and
+     "delta" are all appearing for the first time; the example sentence
+     should be rewritten so they are understandable.
+
+          The major function assists you in checking in a file to your
+          version control system and registering successive sets of
+          changes to it as deltas.
+
+   * Use the `@dfn' command around a word being introduced, to indicate
+     that the reader should not expect to know the meaning already, and
+     should expect to learn the meaning from this passage.
+
+@pxref
+......
+
+Absolutely never use `@pxref' except in the special context for which
+it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace.  One formatter
+automatically inserts closing punctuation and the other does not.  This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
+Invoking from a Shell
+.....................
+
+You can invoke programs such as Emacs, GCC, and `gawk' from a shell.
+The documentation for each program should contain a section that
+describes this.  Unfortunately, if the node names and titles for these
+sections are all different, readers find it hard to search for the
+section.
+
+  Name such sections with a phrase beginning with the word
+`Invoking ...', as in `Invoking Emacs'; this way users can find the
+section easily.
+
+ANSI C Syntax
+.............
+
+When you use `@example' to describe a C function's calling conventions,
+use the ANSI C syntax, like this:
+
+     void dld_init (char *@var{path});
+
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with `@var'.
+
+  Avoid the obsolete style that looks like this:
+
+     #include <dld.h>
+     
+     dld_init (path)
+     char *path;
+
+  Also, it is best to avoid writing `#include' above the declaration
+just to indicate that the function is declared in a header file.  The
+practice may give the misimpression that the `#include' belongs near
+the declaration of the function.  Either state explicitly which header
+file holds the declaration or, better yet, name the header file used
+for a group of functions at the beginning of the section that describes
+the functions.
+
+Bad Examples
+............
+
+Here are several examples of bad writing to avoid:
+
+  In this example, say, " ... you must `@dfn'{check in} the new
+version."  That flows better.
+
+     When you are done editing the file, you must perform a
+     `@dfn'{check in}.
+
+  In the following example, say, "... makes a unified interface such as
+VC mode possible."
+
+     SCCS, RCS and other version-control systems all perform similar
+     functions in broadly similar ways (it is this resemblance which
+     makes a unified control mode like this possible).
+
+  And in this example, you should specify what `it' refers to:
+
+     If you are working with other people, it assists in coordinating
+     everyone's changes so they do not step on each other.
+
+And Finally ...
+...............
+
+   * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
+     in the name `Bach'.  But pronounce Texinfo as in `speck':
+     "teckinfo".
+
+   * Write notes for yourself at the very end of a Texinfo file after
+     the `@bye'.  None of the formatters process text after the `@bye';
+     it is as if the text were within `@ignore' ...  `@end ignore'.
+
+\1f
+File: texinfo.info,  Node: Sample Texinfo File,  Next: Sample Permissions,  Prev: Tips,  Up: Top
+
+A Sample Texinfo File
+*********************
+
+Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter.  *Note A
+Short Sample Texinfo File: Short Sample.

 
 

-The header does not appear in either the Info file or the printed
-output.  It sets various parameters, including the name of the Info
-file and the title used in the header.

 
      \input texinfo   @c -*-texinfo-*-
      @c %**start of header
 
      \input texinfo   @c -*-texinfo-*-
      @c %**start of header

@@ -62,24 +3907,13 @@ file and the title used in the header.
      @c %**end of header
      
      @setchapternewpage odd
      @c %**end of header
      
      @setchapternewpage odd

-
-Part 2: Summary Description and Copyright
------------------------------------------
-
-The summary description and copyright segment does not appear in the
-printed document.
-
+     

      @ifinfo
      This is a short example of a complete Texinfo file.
      
      @ifinfo
      This is a short example of a complete Texinfo file.
      

-     Copyright @copyright{} 1990 Free Software Foundation, Inc.
+     Copyright 1990 Free Software Foundation, Inc.

      @end ifinfo
      @end ifinfo

-
-Part 3: Titlepage and Copyright
--------------------------------
-
-The titlepage segment does not appear in the Info file.
-
+     

      @titlepage
      @sp 10
      @comment The title is printed in a large font.
      @titlepage
      @sp 10
      @comment The title is printed in a large font.

@@ -90,30 +3924,16 @@ The titlepage segment does not appear in the Info file.
      @vskip 0pt plus 1filll
      Copyright @copyright{} 1990 Free Software Foundation, Inc.
      @end titlepage
      @vskip 0pt plus 1filll
      Copyright @copyright{} 1990 Free Software Foundation, Inc.
      @end titlepage

-
-Part 4: `Top' Node and Master Menu
-----------------------------------
-
-The `Top' node contains the master menu for the Info file.  Since a
-printed manual uses a table of contents rather than a menu, the master
-menu appears only in the Info file.
-
-     @node    Top,       First Chapter, ,         (dir)
+     
+     @node    Top,       First Chapter,         , (dir)

      @comment node-name, next,          previous, up
      @comment node-name, next,          previous, up

-
+     

      @menu
      * First Chapter::    The first chapter is the
                           only chapter in this sample.
      * Concept Index::    This index has two entries.
      @end menu
      @menu
      * First Chapter::    The first chapter is the
                           only chapter in this sample.
      * Concept Index::    This index has two entries.
      @end menu

-
-Part 5:  The Body of the Document
----------------------------------
-
-The body segment contains all the text of the document, but not the
-indices or table of contents.  This example illustrates a node and a
-chapter containing an enumerated list.
-
+     

      @node    First Chapter, Concept Index, Top,      Top
      @comment node-name,     next,          previous, up
      @chapter First Chapter
      @node    First Chapter, Concept Index, Top,      Top
      @comment node-name,     next,          previous, up
      @chapter First Chapter

@@ -136,15 +3956,7 @@ chapter containing an enumerated list.
      commands transform a Texinfo file such as this into
      an Info file; and @TeX{} typesets it for a printed
      manual.
      commands transform a Texinfo file such as this into
      an Info file; and @TeX{} typesets it for a printed
      manual.

-
-Part 6: The End of the Document
--------------------------------
-
-The end segment contains commands both for generating an index in a node
-and unnumbered chapter of its own and for generating the table of
-contents; and it contains the `@bye' command that marks the end of the
-document.
-
+     

      @node    Concept Index,    ,  First Chapter, Top
      @comment node-name,    next,  previous,      up
      @unnumbered Concept Index
      @node    Concept Index,    ,  First Chapter, Top
      @comment node-name,    next,  previous,      up
      @unnumbered Concept Index

@@ -154,1131 +3966,2203 @@ document.
      @contents
      @bye
 
      @contents
      @bye
 

-The Results
------------
+\1f
+File: texinfo.info,  Node: Sample Permissions,  Next: Include Files,  Prev: Sample Texinfo File,  Up: Top
+
+Sample Permissions
+******************

 
 

-  Here is what the contents of the first chapter of the sample look
-like:
+Texinfo files should contain sections that tell the readers that they
+have the right to copy and distribute the Texinfo file, the Info file,
+and the printed manual.

 
 

+  Also, if you are writing a manual about software, you should explain
+that the software is free and either include the GNU General Public
+License (GPL) or provide a reference to it.  *Note Distribution:
+(xemacs)Distrib, for an example of the text that could be used in the
+software "Distribution", "General Public License", and "NO WARRANTY"
+sections of a document.  *Note Texinfo Copying Conditions: Copying, for
+an example of a brief explanation of how the copying conditions provide
+you with rights.

 
 

-     This is the contents of the first chapter.
+* Menu:

 
 

-     Here is a numbered list.
+* Inserting Permissions::       How to put permissions in your document.
+* ifinfo Permissions::          Sample `ifinfo' copying permissions.
+* Titlepage Permissions::       Sample Titlepage copying permissions.

 
 

-       1. This is the first item.
+\1f
+File: texinfo.info,  Node: Inserting Permissions,  Next: ifinfo Permissions,  Prev: Sample Permissions,  Up: Sample Permissions

 
 

-       2. This is the second item.
+Inserting Permissions
+=====================

 
 

-     The `makeinfo' and `texinfo-format-buffer' commands transform a
-     Texinfo file such as this into an Info file; and TeX typesets it
-     for a printed manual.
+  In a Texinfo file, the first `@ifinfo' section usually begins with a
+line that says what the file documents.  This is what a person reading
+the unprocessed Texinfo file or using the advanced Info command `g *'
+sees first.  *note Advanced Info commands: (info)Expert, for more
+information. (A reader using the regular Info commands usually starts
+reading at the first node and skips this first section, which is not in
+a node.)
+
+  In the `@ifinfo' section, the summary sentence is followed by a
+copyright notice and then by the copying permission notice.  One of the
+copying permission paragraphs is enclosed in `@ignore' and `@end
+ignore' commands.  This paragraph states that the Texinfo file can be
+processed through TeX and printed, provided the printed manual carries
+the proper copying permission notice.  This paragraph is not made part
+of the Info file since it is not relevant to the Info file; but it is a
+mandatory part of the Texinfo file since it permits people to process
+the Texinfo file in TeX and print the results.
+
+  In the printed manual, the Free Software Foundation copying permission
+notice follows the copyright notice and publishing information and is
+located within the region delineated by the `@titlepage' and `@end
+titlepage' commands.  The copying permission notice is exactly the same
+as the notice in the `@ifinfo' section except that the paragraph
+enclosed in `@ignore' and `@end ignore' commands is not part of the
+notice.
+
+  To make it simple to insert a permission notice into each section of
+the Texinfo file, sample permission notices for each section are
+reproduced in full below.
+
+  Note that you may need to specify the correct name of a section
+mentioned in the permission notice.  For example, in `The GDB Manual',
+the name of the section referring to the General Public License is
+called the "GDB General Public License", but in the sample shown below,
+that section is referred to generically as the "GNU General Public
+License".  If the Texinfo file does not carry a copy of the General
+Public License, leave out the reference to it, but be sure to include
+the rest of the sentence.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Acknowledgements,  Prev: Short Sample,  Up: Overview
+File: texinfo.info,  Node: ifinfo Permissions,  Next: Titlepage Permissions,  Prev: Inserting Permissions,  Up: Sample Permissions

 
 

-Acknowledgements
-================
+`ifinfo' Copying Permissions
+============================

 
 

-  Richard M. Stallman wrote Edition 1.0 of this manual.
-Robert J. Chassell revised and extended it, starting with Edition 1.1.
-Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
-starting with Edition 2.22.
+In the `@ifinfo' section of a Texinfo file, the standard Free Software
+Foundation permission notice reads as follows:

 
 

-  Our thanks go out to all who helped improve this work, particularly to
-Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
-reported mistakes and obscurities; our special thanks go to Melissa
-Weisshaus for her frequent and often tedious reviews of nearly similar
-editions.  Our mistakes are our own.
+     This file documents ...
+     
+     Copyright 1998 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.
+     
+     @ignore
+     Permission is granted to process this file through TeX
+     and print the results, provided the printed document
+     carries a copying permission notice identical to this
+     one except for the removal of this paragraph (this
+     paragraph not being relevant to the printed manual).
+     
+     @end ignore
+     Permission is granted to copy and distribute modified
+     versions of this manual under the conditions for
+     verbatim copying, provided also that the sections
+     entitled ``Copying'' and ``GNU General Public License''
+     are 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 this permission notice may be stated in a
+     translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info,  Node: Titlepage Permissions,  Prev: ifinfo Permissions,  Up: Sample Permissions

 
 

-  Please send suggestions and corrections to:
+Titlepage Copying Permissions
+=============================

 
 

-     Internet address:
-         bug-texinfo@gnu.org
+In the `@titlepage' section of a Texinfo file, the standard Free
+Software Foundation copying permission notice follows the copyright
+notice and publishing information.  The standard phrasing is as follows:

 
 

-Please include the manual's edition number and update date in your
-messages.
+     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 sections
+     entitled ``Copying'' and ``GNU General Public License''
+     are 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 this permission notice may be stated in a
+     translation approved by the Free Software Foundation.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Texinfo Mode,  Next: Beginning a File,  Prev: Overview,  Up: Top
+File: texinfo.info,  Node: Include Files,  Next: Headings,  Prev: Sample Permissions,  Up: Top

 
 

-Using Texinfo Mode
-******************
+Include Files
+*************

 
 

-  You may edit a Texinfo file with any text editor you choose.  A
-Texinfo file is no different from any other ASCII file.  However, GNU
-Emacs comes with a special mode, called Texinfo mode, that provides
-Emacs commands and tools to help ease your work.
+When TeX or an Info formatting command sees an `@include' command in a
+Texinfo file, it processes the contents of the file named by the
+command and incorporates them into the DVI or Info file being created.
+Index entries from the included file are incorporated into the indices
+of the output file.

 
 

-  This chapter describes features of GNU Emacs' Texinfo mode but not any
-features of the Texinfo formatting language.  If you are reading this
-manual straight through from the beginning, you may want to skim through
-this chapter briefly and come back to it after reading succeeding
-chapters which describe the Texinfo formatting language in detail.
+  Include files let you keep a single large document as a collection of
+conveniently small parts.

 
 * Menu:
 
 
 * Menu:
 

-* Texinfo Mode Overview::       How Texinfo mode can help you.
-* Emacs Editing::               Texinfo mode adds to GNU Emacs' general
-                                  purpose editing features.
-* Inserting::                   How to insert frequently used @-commands.
-* Showing the Structure::       How to show the structure of a file.
-* Updating Nodes and Menus::    How to update or create new nodes and menus.
-* Info Formatting::             How to format for Info.
-* Printing::                    How to format and print part or all of a file.
-* Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
+* Using Include Files::         How to use the `@include' command.
+* texinfo-multiple-files-update::  How to create and update nodes and
+                                  menus when using included files.
+* Include File Requirements::   What `texinfo-multiple-files-update' expects.
+* Sample Include File::         A sample outer file with included files
+                                  within it; and a sample included file.
+* Include Files Evolution::     How use of the `@include' command
+                                  has changed over time.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Texinfo Mode Overview,  Next: Emacs Editing,  Prev: Texinfo Mode,  Up: Texinfo Mode
+File: texinfo.info,  Node: Using Include Files,  Next: texinfo-multiple-files-update,  Prev: Include Files,  Up: Include Files

 
 

-Texinfo Mode Overview
-=====================
+How to Use Include Files
+========================
+
+To include another file within a Texinfo file, write the `@include'
+command at the beginning of a line and follow it on the same line by
+the name of a file to be included.  For example:
+
+     @include buffers.texi
+
+  An included file should simply be a segment of text that you expect to
+be included as is into the overall or "outer" Texinfo file; it should
+not contain the standard beginning and end parts of a Texinfo file.  In
+particular, you should not start an included file with a line saying
+`\input texinfo'; if you do, that phrase is inserted into the output
+file as is.  Likewise, you should not end an included file with an
+`@bye' command; nothing after `@bye' is formatted.
+
+  In the past, you were required to write an `@setfilename' line at the
+beginning of an included file, but no longer.  Now, it does not matter
+whether you write such a line.  If an `@setfilename' line exists in an
+included file, it is ignored.
+
+  Conventionally, an included file begins with an `@node' line that is
+followed by an `@chapter' line.  Each included file is one chapter.
+This makes it easy to use the regular node and menu creating and
+updating commands to create the node pointers and menus within the
+included file.  However, the simple Emacs node and menu creating and
+updating commands do not work with multiple Texinfo files.  Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the `@node' line that begins the included file.  Also, you
+cannot use the regular commands to create a master menu for the whole
+file.  Either you must insert the menus and the `Next', `Previous', and
+`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
+command, `texinfo-multiple-files-update', that is designed for
+`@include' files.
+
+\1f
+File: texinfo.info,  Node: texinfo-multiple-files-update,  Next: Include File Requirements,  Prev: Using Include Files,  Up: Include Files
+
+`texinfo-multiple-files-update'
+===============================
+
+GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update'
+command.  This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first `@node' line of the included
+files or all of them:
+
+`M-x texinfo-multiple-files-update'
+     Called without any arguments:
+
+        - Create or update the `Next', `Previous', and `Up' pointers of
+          the first `@node' line in each file included in an outer or
+          overall Texinfo file.
+
+        - Create or update the `Top' level node pointers of the outer or
+          overall file.
+
+        - Create or update a main menu in the outer file.

 
 

-  Texinfo mode provides special features for working with Texinfo files:
+`C-u M-x texinfo-multiple-files-update'
+     Called with `C-u' as a prefix argument:

 
 

-   * Insert frequently used @-commands.
+        - Create or update pointers in the first `@node' line in each
+          included file.

 
 

-   * Automatically create `@node' lines.
+        - Create or update the `Top' level node pointers of the outer
+          file.

 
 

-   * Show the structure of a Texinfo source file.
+        - Create and insert a master menu in the outer file.  The
+          master menu is made from all the menus in all the included
+          files.

 
 

-   * Automatically create or update the `Next', `Previous', and `Up'
-     pointers of a node.
+`C-u 8 M-x texinfo-multiple-files-update'
+     Called with a numeric prefix argument, such as `C-u 8':

 
 

-   * Automatically create or update menus.
+        - Create or update *all* the `Next', `Previous', and `Up'
+          pointers of all the included files.

 
 

-   * Automatically create a master menu.
+        - Create or update *all* the menus of all the included files.

 
 

-   * Format a part or all of a file for Info.
+        - Create or update the `Top' level node pointers of the outer or
+          overall file.

 
 

-   * Typeset and print part or all of a file.
+        - And then create a master menu in the outer file.  This is
+          similar to invoking `texinfo-master-menu' with an argument
+          when you are working with just one file.

 
 

-  Perhaps the two most helpful features are those for inserting
-frequently used @-commands and for creating node pointers and menus.
+  Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just `C-u', the `texinfo-multiple-files-update'
+command inserts a master menu; with a numeric prefix argument, such as
+`C-u 8', the command updates *every* pointer and menu in *all* the
+files and then inserts a master menu.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Emacs Editing,  Next: Inserting,  Prev: Texinfo Mode Overview,  Up: Texinfo Mode
+File: texinfo.info,  Node: Include File Requirements,  Next: Sample Include File,  Prev: texinfo-multiple-files-update,  Up: Include Files
+
+Include File Requirements
+=========================
+
+If you plan to use the `texinfo-multiple-files-update' command, the
+outer Texinfo file that lists included files within it should contain
+nothing but the beginning and end parts of a Texinfo file, and a number
+of `@include' commands listing the included files.  It should not even
+include indices, which should be listed in an included file of their
+own.
+
+  Moreover, each of the included files must contain exactly one highest
+level node (conventionally, `@chapter' or equivalent), and this node
+must be the first node in the included file.  Furthermore, each of
+these highest level nodes in each included file must be at the same
+hierarchical level in the file structure.  Usually, each is an
+`@chapter', an `@appendix', or an `@unnumbered' node.  Thus, normally,
+each included file contains one, and only one, chapter or
+equivalent-level node.
+
+  The outer file should contain only _one_ node, the `Top' node.  It
+should _not_ contain any nodes besides the single `Top' node.  The
+`texinfo-multiple-files-update' command will not process them.

 
 

-The Usual GNU Emacs Editing Commands
-====================================
+\1f
+File: texinfo.info,  Node: Sample Include File,  Next: Include Files Evolution,  Prev: Include File Requirements,  Up: Include Files

 
 

-  In most cases, the usual Text mode commands work the same in Texinfo
-mode as they do in Text mode.  Texinfo mode adds new editing commands
-and tools to GNU Emacs' general purpose editing features.  The major
-difference concerns filling.  In Texinfo mode, the paragraph separation
-variable and syntax table are redefined so that Texinfo commands that
-should be on lines of their own are not inadvertently included in
-paragraphs.  Thus, the `M-q' (`fill-paragraph') command will refill a
-paragraph but not mix an indexing command on a line adjacent to it into
-the paragraph.
-
-  In addition, Texinfo mode sets the `page-delimiter' variable to the
-value of `texinfo-chapter-level-regexp'; by default, this is a regular
-expression matching the commands for chapters and their equivalents,
-such as appendices.  With this value for the page delimiter, you can
-jump from chapter title to chapter title with the `C-x ]'
-(`forward-page') and `C-x [' (`backward-page') commands and narrow to a
-chapter with the `C-x p' (`narrow-to-page') command.  (*Note Pages:
-(xemacs)Pages, for details about the page commands.)
-
-  You may name a Texinfo file however you wish, but the convention is to
-end a Texinfo file name with one of the three extensions `.texinfo',
-`.texi', or `.tex'.  A longer extension is preferred, since it is
-explicit, but a shorter extension may be necessary for operating
-systems that limit the length of file names.  GNU Emacs automatically
-enters Texinfo mode when you visit a file with a `.texinfo' or  `.texi'
-extension.  Also, Emacs switches to Texinfo mode when you visit a file
-that has `-*-texinfo-*-' in its first line.  If ever you are in another
-mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
-
-  Like all other Emacs features, you can customize or enhance Texinfo
-mode as you wish.  In particular, the keybindings are very easy to
-change.  The keybindings described here are the default or standard
-ones.
-
-\1f
-File: texinfo.info,  Node: Inserting,  Next: Showing the Structure,  Prev: Emacs Editing,  Up: Texinfo Mode
-
-Inserting Frequently Used Commands
-==================================
-
-  Texinfo mode provides commands to insert various frequently used
-@-commands into the buffer.  You can use these commands to save
-keystrokes.
-
-  The insert commands are invoked by typing `C-c' twice and then the
-first letter of the @-command:
-
-`C-c C-c c'
-`M-x texinfo-insert-@code'
-     Insert `@code{}' and put the cursor between the braces.
-
-`C-c C-c d'
-`M-x texinfo-insert-@dfn'
-     Insert `@dfn{}' and put the cursor between the braces.
-
-`C-c C-c e'
-`M-x texinfo-insert-@end'
-     Insert `@end' and attempt to insert the correct following word,
-     such as `example' or `table'.  (This command does not handle
-     nested lists correctly, but inserts the word appropriate to the
-     immediately preceding list.)
-
-`C-c C-c i'
-`M-x texinfo-insert-@item'
-     Insert `@item' and put the cursor at the beginning of the next
-     line.
-
-`C-c C-c k'
-`M-x texinfo-insert-@kbd'
-     Insert `@kbd{}' and put the cursor between the braces.
-
-`C-c C-c n'
-`M-x texinfo-insert-@node'
-     Insert `@node' and a comment line listing the sequence for the
-     `Next', `Previous', and `Up' nodes.  Leave point after the `@node'.
-
-`C-c C-c o'
-`M-x texinfo-insert-@noindent'
-     Insert `@noindent' and put the cursor at the beginning of the next
-     line.
-
-`C-c C-c s'
-`M-x texinfo-insert-@samp'
-     Insert `@samp{}' and put the cursor between the braces.
-
-`C-c C-c t'
-`M-x texinfo-insert-@table'
-     Insert `@table' followed by a <SPC> and leave the cursor after the
-     <SPC>.
-
-`C-c C-c v'
-`M-x texinfo-insert-@var'
-     Insert `@var{}' and put the cursor between the braces.
-
-`C-c C-c x'
-`M-x texinfo-insert-@example'
-     Insert `@example' and put the cursor at the beginning of the next
-     line.
-
-`C-c C-c {'
-`M-x texinfo-insert-braces'
-     Insert `{}' and put the cursor between the braces.
-
-`C-c C-c }'
-`C-c C-c ]'
-`M-x up-list'
-     Move from between a pair of braces forward past the closing brace.
-     Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
-     however, more mnemonic; hence the two keybindings.  (Also, you can
-     move out from between braces by typing `C-f'.)
-
-  To put a command such as `@code{...}' around an _existing_ word,
-position the cursor in front of the word and type `C-u 1 C-c C-c c'.
-This makes it easy to edit existing plain text.  The value of the
-prefix argument tells Emacs how many words following point to include
-between braces--`1' for one word, `2' for two words, and so on.  Use a
-negative argument to enclose the previous word or words.  If you do not
-specify a prefix argument, Emacs inserts the @-command string and
-positions the cursor between the braces.  This feature works only for
-those @-commands that operate on a word or words within one line, such
-as `@kbd' and `@var'.
-
-  This set of insert commands was created after analyzing the frequency
-with which different @-commands are used in the `GNU Emacs Manual' and
-the `GDB Manual'.  If you wish to add your own insert commands, you can
-bind a keyboard macro to a key, use abbreviations, or extend the code
-in `texinfo.el'.
-
-  `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
-that works differently from the other insert commands.  It inserts a
-node's section or chapter title in the space for the description in a
-menu entry line.  (A menu entry has three parts, the entry name, the
-node name, and the description.  Only the node name is required, but a
-description helps explain what the node is about.  *Note The Parts of a
-Menu: Menu Parts.)
-
-  To use `texinfo-start-menu-description', position point in a menu
-entry line and type `C-c C-c C-d'.  The command looks for and copies
-the title that goes with the node name, and inserts the title as a
-description; it positions point at beginning of the inserted text so you
-can edit it.  The function does not insert the title if the menu entry
-line already contains a description.
-
-  This command is only an aid to writing descriptions; it does not do
-the whole job.  You must edit the inserted text since a title tends to
-use the same words as a node name but a useful description uses
-different words.
-
-\1f
-File: texinfo.info,  Node: Showing the Structure,  Next: Updating Nodes and Menus,  Prev: Inserting,  Up: Texinfo Mode
-
-Showing the Section Structure of a File
-=======================================
+Sample File with `@include'
+===========================

 
 

-  You can show the section structure of a Texinfo file by using the
-`C-c C-s' command (`texinfo-show-structure').  This command shows the
-section structure of a Texinfo file by listing the lines that begin
-with the @-commands for `@chapter', `@section', and the like.  It
-constructs what amounts to a table of contents.  These lines are
-displayed in another buffer called the `*Occur*' buffer.  In that
-buffer, you can position the cursor over one of the lines and use the
-`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
-corresponding spot in the Texinfo file.
-
-`C-c C-s'
-`M-x texinfo-show-structure'
-     Show the `@chapter', `@section', and such lines of a Texinfo file.
-
-`C-c C-c'
-`M-x occur-mode-goto-occurrence'
-     Go to the line in the Texinfo file corresponding to the line under
-     the cursor in the `*Occur*' buffer.
+Here is an example of a complete outer Texinfo file with `@include'
+files within it before running `texinfo-multiple-files-update', which
+would insert a main or master menu:

 
 

-  If you call `texinfo-show-structure' with a prefix argument by typing
-`C-u C-c C-s', it will list not only those lines with the @-commands
-for `@chapter', `@section', and the like, but also the `@node' lines.
-(This is how the `texinfo-show-structure' command worked without an
-argument in the first version of Texinfo.  It was changed because
-`@node' lines clutter up the `*Occur*' buffer and are usually not
-needed.)  You can use `texinfo-show-structure' with a prefix argument
-to check whether the `Next', `Previous', and `Up' pointers of an
-`@node' line are correct.
-
-  Often, when you are working on a manual, you will be interested only
-in the structure of the current chapter.  In this case, you can mark
-off the region of the buffer that you are interested in by using the
-`C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
-will work on only that region.  To see the whole buffer again, use
-`C-x n w' (`widen').  (*Note Narrowing: (xemacs)Narrowing, for more
-information about the narrowing commands.)
-
-  In addition to providing the `texinfo-show-structure' command,
-Texinfo mode sets the value of the page delimiter variable to match the
-chapter-level @-commands.  This enables you to use the `C-x ]'
-(`forward-page') and `C-x [' (`backward-page') commands to move forward
-and backward by chapter, and to use the `C-x p' (`narrow-to-page')
-command to narrow to a chapter.  *Note Pages: (xemacs)Pages, for more
-information about the page commands.
-
-\1f
-File: texinfo.info,  Node: Updating Nodes and Menus,  Next: Info Formatting,  Prev: Showing the Structure,  Up: Texinfo Mode
-
-Updating Nodes and Menus
-========================
+     \input texinfo @c -*-texinfo-*-
+     @setfilename  include-example.info
+     @settitle Include Example
+     
+     @setchapternewpage odd
+     @titlepage
+     @sp 12
+     @center @titlefont{Include Example}
+     @sp 2
+     @center by Whom Ever
+     
+     @page
+     @vskip 0pt plus 1filll
+     Copyright @copyright{} 1998 Free Software Foundation, Inc.
+     @end titlepage
+     
+     @ifinfo
+     @node Top, First, , (dir)
+     @top Master Menu
+     @end ifinfo
+     
+     @include foo.texinfo
+     @include bar.texinfo
+     @include concept-index.texinfo
+     
+     @summarycontents
+     @contents
+     
+     @bye

 
 

-  Texinfo mode provides commands for automatically creating or updating
-menus and node pointers.  The commands are called "update" commands
-because their most frequent use is for updating a Texinfo file after
-you have worked on it; but you can use them to insert the `Next',
-`Previous', and `Up' pointers into an `@node' line that has none and to
-create menus in a file that has none.
+  An included file, such as `foo.texinfo', might look like this:

 
 

-  If you do not use the updating commands, you need to write menus and
-node pointers by hand, which is a tedious task.
+     @node First, Second, , Top
+     @chapter First Chapter
+     
+     Contents of first chapter ...

 
 

-* Menu:
+  The full contents of `concept-index.texinfo' might be as simple as
+this:

 
 

-* Updating Commands::           Five major updating commands.
-* Updating Requirements::       How to structure a Texinfo file for
-                                  using the updating command.
-* Other Updating Commands::     How to indent descriptions, insert
-                                  missing nodes lines, and update
-                                  nodes in sequence.
-
-\1f
-File: texinfo.info,  Node: Updating Commands,  Next: Updating Requirements,  Prev: Updating Nodes and Menus,  Up: Updating Nodes and Menus
-
-The Updating Commands
----------------------
-
-  You can use the updating commands
-
-   * to insert or update the `Next', `Previous', and `Up' pointers of a
-     node,
-
-   * to insert or update the menu for a section, and
-
-   * to create a master menu for a Texinfo source file.
-
-  You can also use the commands to update all the nodes and menus in a
-region or in a whole Texinfo file.
-
-  The updating commands work only with conventional Texinfo files, which
-are structured hierarchically like books.  In such files, a structuring
-command line must follow closely after each `@node' line, except for
-the `Top' `@node' line.  (A "structuring command line" is a line
-beginning with `@chapter', `@section', or other similar command.)
-
-  You can write the structuring command line on the line that follows
-immediately after an `@node' line or else on the line that follows
-after a single `@comment' line or a single `@ifinfo' line.  You cannot
-interpose more than one line between the `@node' line and the
-structuring command line; and you may interpose only an `@comment' line
-or an `@ifinfo' line.
-
-  Commands which work on a whole buffer require that the `Top' node be
-followed by a node with an `@chapter' or equivalent-level command.
-Note that the menu updating commands will not create a main or master
-menu for a Texinfo file that has only `@chapter'-level nodes!  The menu
-updating commands only create menus _within_ nodes for lower level
-nodes.  To create a menu of chapters, you must provide a `Top' node.
-
-  The menu updating commands remove menu entries that refer to other
-Info files since they do not refer to nodes within the current buffer.
-This is a deficiency.  Rather than use menu entries, you can use cross
-references to refer to other Info files.  None of the updating commands
-affect cross references.
-
-  Texinfo mode has five updating commands that are used most often: two
-are for updating the node pointers or menu of a single node (or a
-region); two are for updating every node pointer and menu in a file;
-and one, the `texinfo-master-menu' command, is for creating a master
-menu for a complete file, and optionally, for updating every node and
-menu in the whole Texinfo file.
-
-  The `texinfo-master-menu' command is the primary command:
-
-`C-c C-u m'
-`M-x texinfo-master-menu'
-     Create or update a master menu that includes all the other menus
-     (incorporating the descriptions from pre-existing menus, if any).
-
-     With an argument (prefix argument, `C-u,' if interactive), first
-     create or update all the nodes and all the regular menus in the
-     buffer before constructing the master menu.  (*Note The Top Node
-     and Master Menu: The Top Node, for more about a master menu.)
-
-     For `texinfo-master-menu' to work, the Texinfo file must have a
-     `Top' node and at least one subsequent node.
-
-     After extensively editing a Texinfo file, you can type the
-     following:
-
-          C-u M-x texinfo-master-menu
-     or
-          C-u C-c C-u m
-
-     This updates all the nodes and menus completely and all at once.
-
-  The other major updating commands do smaller jobs and are designed for
-the person  who updates nodes and menus as he or she writes a Texinfo
-file.
-
-  The commands are:
-
-`C-c C-u C-n'
-`M-x texinfo-update-node'
-     Insert the `Next', `Previous', and `Up' pointers for the node that
-     point is within (i.e., for the `@node' line preceding point).  If
-     the `@node' line has pre-existing `Next', `Previous', or `Up'
-     pointers in it, the old pointers are removed and new ones inserted.
-     With an argument (prefix argument, `C-u', if interactive), this
-     command updates all `@node' lines in the region (which is the text
-     between point and mark).
-
-`C-c C-u C-m'
-`M-x texinfo-make-menu'
-     Create or update the menu in the node that point is within.  With
-     an argument (`C-u' as prefix argument, if interactive), the
-     command makes or updates menus for the nodes which are either
-     within or a part of the region.
-
-     Whenever `texinfo-make-menu' updates an existing menu, the
-     descriptions from that menu are incorporated into the new menu.
-     This is done by copying descriptions from the existing menu to the
-     entries in the new menu that have the same node names.  If the
-     node names are different, the descriptions are not copied to the
-     new menu.
-
-`C-c C-u C-e'
-`M-x texinfo-every-node-update'
-     Insert or update the `Next', `Previous', and `Up' pointers for
-     every node in the buffer.
-
-`C-c C-u C-a'
-`M-x texinfo-all-menus-update'
-     Create or update all the menus in the buffer.  With an argument
-     (`C-u' as prefix argument, if interactive), first insert or update
-     all the node pointers before working on the menus.
-
-     If a master menu exists, the `texinfo-all-menus-update' command
-     updates it; but the command does not create a new master menu if
-     none already exists.  (Use the `texinfo-master-menu' command for
-     that.)
-
-     When working on a document that does not merit a master menu, you
-     can type the following:
-
-          C-u C-c C-u C-a
-     or
-          C-u M-x texinfo-all-menus-update
-
-     This updates all the nodes and menus.
-
-  The `texinfo-column-for-description' variable specifies the column to
-which menu descriptions are indented.  By default, the value is 32
-although it is often useful to reduce it to as low as 24.  You can set
-the variable with the `M-x edit-options' command (*note Editing
-Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
-command (*note Examining and Setting Variables: (xemacs)Examining.).
-
-  Also, the `texinfo-indent-menu-description' command may be used to
-indent existing menu descriptions to a specified column.  Finally, if
-you wish, you can use the `texinfo-insert-node-lines' command to insert
-missing `@node' lines into a file.  (*Note Other Updating Commands::,
-for more information.)
-
-\1f
-File: texinfo.info,  Node: Updating Requirements,  Next: Other Updating Commands,  Prev: Updating Commands,  Up: Updating Nodes and Menus
-
-Updating Requirements
----------------------
-
-  To use the updating commands, you must organize the Texinfo file
-hierarchically with chapters, sections, subsections, and the like.
-When you construct the hierarchy of the manual, do not `jump down' more
-than one level at a time: you can follow the `Top' node with a chapter,
-but not with a section; you can follow a chapter with a section, but
-not with a subsection.  However, you may `jump up' any number of levels
-at one time--for example, from a subsection to a chapter.
-
-  Each `@node' line, with the exception of the line for the `Top' node,
-must be followed by a line with a structuring command such as
-`@chapter', `@section', or `@unnumberedsubsec'.
-
-  Each `@node' line/structuring-command line combination must look
-either like this:
-
-     @node     Comments,  Minimum, Conventions, Overview
-     @comment  node-name, next,    previous,    up
-     @section Comments
-
-  or like this (without the `@comment' line):
-
-     @node Comments, Minimum, Conventions, Overview
-     @section Comments
-
-In this example, `Comments' is the name of both the node and the
-section.  The next node is called `Minimum' and the previous node is
-called `Conventions'.  The `Comments' section is within the `Overview'
-node, which is specified by the `Up' pointer.  (Instead of an
-`@comment' line, you can write an `@ifinfo' line.)
-
-  If a file has a `Top' node, it must be called `top' or `Top' and be
-the first node in the file.
-
-  The menu updating commands create a menu of sections within a chapter,
-a menu of subsections within a section, and so on.  This means that you
-must have a `Top' node if you want a menu of chapters.
-
-  Incidentally, the `makeinfo' command will create an Info file for a
-hierarchically organized Texinfo file that lacks `Next', `Previous' and
-`Up' pointers.  Thus, if you can be sure that your Texinfo file will be
-formatted with `makeinfo', you have no need for the `update node'
-commands.  (*Note Creating an Info File: Create an Info File, for more
-information about `makeinfo'.)  However, both `makeinfo' and the
-`texinfo-format-...' commands require that you insert menus in the file.
-
-\1f
-File: texinfo.info,  Node: Other Updating Commands,  Prev: Updating Requirements,  Up: Updating Nodes and Menus
+     @node Concept Index, , Second, Top
+     @unnumbered Concept Index
+     
+     @printindex cp

 
 

-Other Updating Commands
------------------------
+  The outer Texinfo source file for `The XEmacs Lisp Reference Manual'
+is named `elisp.texi'.  This outer file contains a master menu with 417
+entries and a list of 41 `@include' files.

 
 

-  In addition to the five major updating commands, Texinfo mode
-possesses several less frequently used updating commands:
+\1f
+File: texinfo.info,  Node: Include Files Evolution,  Prev: Sample Include File,  Up: Include Files
+
+Evolution of Include Files
+==========================
+
+When Info was first created, it was customary to create many small Info
+files on one subject.  Each Info file was formatted from its own
+Texinfo source file.  This custom meant that Emacs did not need to make
+a large buffer to hold the whole of a large Info file when someone
+wanted information; instead, Emacs allocated just enough memory for the
+small Info file that contained the particular information sought.  This
+way, Emacs could avoid wasting memory.
+
+  References from one file to another were made by referring to the file
+name as well as the node name. (*Note Referring to Other Info Files:
+Other Info Files.  Also, see *Note `@xref' with Four and Five
+Arguments: Four and Five Arguments.)
+
+  Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files.  In a printed
+manual, all the references were within the same document, so TeX could
+automatically determine the references' page numbers.  The Info
+formatting commands used include files only for creating joint indices;
+each of the individual Texinfo files had to be formatted for Info
+individually.  (Each, therefore, required its own `@setfilename' line.)
+
+  However, because large Info files are now split automatically, it is
+no longer necessary to keep them small.
+
+  Nowadays, multiple Texinfo files are used mostly for large documents,
+such as `The XEmacs Lisp Reference Manual', and for projects in which
+several different people write different sections of a document
+simultaneously.
+
+  In addition, the Info formatting commands have been extended to work
+with the `@include' command so as to create a single large Info file
+that is split into smaller files if necessary.  This means that you can
+write menus and cross references without naming the different Texinfo
+files.

 
 

-`M-x texinfo-insert-node-lines'
-     Insert `@node' lines before the `@chapter', `@section', and other
-     sectioning commands wherever they are missing throughout a region
-     in a Texinfo file.
+\1f
+File: texinfo.info,  Node: Headings,  Next: Catching Mistakes,  Prev: Include Files,  Up: Top

 
 

-     With an argument (`C-u' as prefix argument, if interactive), the
-     `texinfo-insert-node-lines' command not only inserts `@node' lines
-     but also inserts the chapter or section titles as the names of the
-     corresponding nodes.  In addition, it inserts the titles as node
-     names in pre-existing `@node' lines that lack names.  Since node
-     names should be more concise than section or chapter titles, you
-     must manually edit node names so inserted.
+Page Headings
+*************

 
 

-     For example, the following marks a whole buffer as a region and
-     inserts `@node' lines and titles throughout:
+Most printed manuals contain headings along the top of every page
+except the title and copyright pages.  Some manuals also contain
+footings.  (Headings and footings have no meaning to Info, which is not
+paginated.)

 
 

-          C-x h C-u M-x texinfo-insert-node-lines
+* Menu:

 
 

-     (Note that this command inserts titles as node names in `@node'
-     lines; the `texinfo-start-menu-description' command (*note
-     Inserting Frequently Used Commands: Inserting.) inserts titles as
-     descriptions in menu entries, a different action.  However, in both
-     cases, you need to edit the inserted text.)
+* Headings Introduced::         Conventions for using page headings.
+* Heading Format::              Standard page heading formats.
+* Heading Choice::              How to specify the type of page heading.
+* Custom Headings::             How to create your own headings and footings.

 
 

-`M-x texinfo-multiple-files-update'
-     Update nodes and menus in a document built from several separate
-     files.  With `C-u' as a prefix argument, create and insert a
-     master menu in the outer file.  With a numeric prefix argument,
-     such as `C-u 2', first update all the menus and all the `Next',
-     `Previous', and `Up' pointers of all the included files before
-     creating and inserting a master menu in the outer file.  The
-     `texinfo-multiple-files-update' command is described in the
-     appendix on `@include' files.  *Note
-     texinfo-multiple-files-update::.
-
-`M-x texinfo-indent-menu-description'
-     Indent every description in the menu following point to the
-     specified column.  You can use this command to give yourself more
-     space for descriptions.  With an argument (`C-u' as prefix
-     argument, if interactive), the `texinfo-indent-menu-description'
-     command indents every description in every menu in the region.
-     However, this command does not indent the second and subsequent
-     lines of a multi-line description.
-
-`M-x texinfo-sequential-node-update'
-     Insert the names of the nodes immediately following and preceding
-     the current node as the `Next' or `Previous' pointers regardless
-     of those nodes' hierarchical level.  This means that the `Next'
-     node of a subsection may well be the next chapter.  Sequentially
-     ordered nodes are useful for novels and other documents that you
-     read through sequentially.  (However, in Info, the `g *' command
-     lets you look through the file sequentially, so sequentially
-     ordered nodes are not strictly necessary.)  With an argument
-     (prefix argument, if interactive), the
-     `texinfo-sequential-node-update' command sequentially updates all
-     the nodes in the region.
-
-\1f
-File: texinfo.info,  Node: Info Formatting,  Next: Printing,  Prev: Updating Nodes and Menus,  Up: Texinfo Mode
-
-Formatting for Info
+\1f
+File: texinfo.info,  Node: Headings Introduced,  Next: Heading Format,  Prev: Headings,  Up: Headings
+
+Headings Introduced

 ===================
 
 ===================
 

-  Texinfo mode provides several commands for formatting part or all of a
-Texinfo file for Info.  Often, when you are writing a document, you
-want to format only part of a file--that is, a region.
+  Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper.  Typically, you will use these
+formats, but you can specify your own format if you wish.
+
+  In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered pages.
+
+  By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and chapters
+begin on right-hand pages--a preceding left-hand page is left blank if
+necessary.  Reports, however, are often printed on just one side of
+paper, and chapters begin on a fresh page immediately following the end
+of the preceding chapter.  In short or informal reports, chapters often
+do not begin on a new page at all, but are separated from the preceding
+text by a small amount of whitespace.
+
+  The `@setchapternewpage' command controls whether chapters begin on
+new pages, and whether one of the standard heading formats is used.  In
+addition, Texinfo has several heading and footing commands that you can
+use to generate your own heading and footing formats.
+
+  In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part.  Any part, or a whole line, may be left
+blank.  Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set flushright.

 
 

-  You can use either the `texinfo-format-region' or the
-`makeinfo-region' command to format a region:
+\1f
+File: texinfo.info,  Node: Heading Format,  Next: Heading Choice,  Prev: Headings Introduced,  Up: Headings

 
 

-`C-c C-e C-r'
-`M-x texinfo-format-region'
-`C-c C-m C-r'
-`M-x makeinfo-region'
-     Format the current region for Info.
+Standard Heading Formats
+========================

 
 

-  You can use either the `texinfo-format-buffer' or the
-`makeinfo-buffer' command to format a whole buffer:
+Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+  By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains blank.
+
+  The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page number.
+
+  A single-sided page looks like this:
+
+        _______________________
+       |                       |
+       | chapter   page number |
+       |                       |
+       | Start of text ...     |
+       | ...                   |
+       |                       |
+
+  The standard format for two-sided printing depends on whether the page
+number is even or odd.  By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right.  (TeX will adjust the
+widths of the left- and right-hand margins.  Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly--sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)
+
+  In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
+`@settitle' command).  The left part of the right-hand (odd-numbered)
+page contains the name of the chapter, the central part is blank, and
+the right part contains the page number.
+
+  Two pages, side by side as in an open book, look like this:
+
+        _______________________     _______________________
+       |                       |   |                       |
+       | page number     title |   | chapter   page number |
+       |                       |   |                       |
+       | Start of text ...     |   | More  text ...        |
+       | ...                   |   | ...                   |
+       |                       |   |                       |
+
+The chapter name is preceded by the word "Chapter", the chapter number
+and a colon.  This makes it easier to keep track of where you are in the
+manual.

 
 

-`C-c C-e C-b'
-`M-x texinfo-format-buffer'
-`C-c C-m C-b'
-`M-x makeinfo-buffer'
-     Format the current buffer for Info.
+\1f
+File: texinfo.info,  Node: Heading Choice,  Next: Custom Headings,  Prev: Heading Format,  Up: Headings

 
 

-  For example, after writing a Texinfo file, you can type the following:
+Specifying the Type of Heading
+==============================

 
 

-     C-u C-c C-u m
-or
-     C-u M-x texinfo-master-menu
+TeX does not begin to generate page headings for a standard Texinfo
+file until it reaches the `@end titlepage' command.  Thus, the title
+and copyright pages are not numbered.  The `@end titlepage' command
+causes TeX to begin to generate page headings according to a standard
+format specified by the `@setchapternewpage' command that precedes the
+`@titlepage' section.

 
 

-This updates all the nodes and menus.  Then type the following to create
-an Info file:
+  There are four possibilities:

 
 

-     C-c C-m C-b
-or
-     M-x makeinfo-buffer
+No `@setchapternewpage' command
+     Cause TeX to specify the single-sided heading format, with chapters
+     on new pages. This is the same as `@setchapternewpage on'.
+
+`@setchapternewpage on'
+     Specify the single-sided heading format, with chapters on new
+     pages.

 
 

-  For TeX or the Info formatting commands to work, the file _must_
-include a line that has `@setfilename' in its header.
+`@setchapternewpage off'
+     Cause TeX to start a new chapter on the same page as the last page
+     of the preceding chapter, after skipping some vertical whitespace.
+     Also cause TeX to typeset for single-sided printing.  (You can
+     override the headers format with the `@headings double' command;
+     see *Note The `@headings' Command: headings on off.)

 
 

-  *Note Create an Info File::, for details about Info formatting.
+`@setchapternewpage odd'
+     Specify the double-sided heading format, with chapters on new
+     pages.
+
+Texinfo lacks an `@setchapternewpage even' command.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Printing,  Next: Texinfo Mode Summary,  Prev: Info Formatting,  Up: Texinfo Mode
+File: texinfo.info,  Node: Custom Headings,  Prev: Heading Choice,  Up: Headings

 
 

-Formatting and Printing
-=======================
+How to Make Your Own Headings
+=============================

 
 

-  Typesetting and printing a Texinfo file is a multi-step process in
-which you first create a file for printing (called a DVI file), and then
-print the file.  Optionally, you may also create indices.  To do this,
-you must run the `texindex' command after first running the `tex'
-typesetting command; and then you must run the `tex' command again.  Or
-else run the `texi2dvi' command which automatically creates indices as
-needed (*note Format with texi2dvi::).
+You can use the standard headings provided with Texinfo or specify your
+own.  By default, Texinfo has no footers, so if you specify them, the
+available page size for the main text will be slightly reduced.
+
+  Texinfo provides six commands for specifying headings and footings.
+The `@everyheading' command and `@everyfooting' command generate page
+headers and footers that are the same for both even- and odd-numbered
+pages.  The `@evenheading' command and `@evenfooting' command generate
+headers and footers for even-numbered (left-hand) pages; and the
+`@oddheading' command and `@oddfooting' command generate headers and
+footers for odd-numbered (right-hand) pages.
+
+  Write custom heading specifications in the Texinfo file immediately
+after the `@end titlepage' command.  Enclose your specifications
+between `@iftex' and `@end iftex' commands since the
+`texinfo-format-buffer' command may not recognize them.  Also, you must
+cancel the predefined heading commands with the `@headings off' command
+before defining your own specifications.
+
+  Here is how to tell TeX to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:
+
+     @iftex
+     @headings off
+     @everyheading @thischapter @| @thispage @| @today{}
+     @end iftex
+
+You need to divide the left part from the central part and the central
+part from the right part by inserting `@|' between parts.  Otherwise,
+the specification command will not be able to tell where the text for
+one part ends and the next part begins.
+
+  Each part can contain text or @-commands.  The text is printed as if
+the part were within an ordinary paragraph in the body of the page.
+The @-commands replace themselves with the page number, date, chapter
+name, or whatever.
+
+  Here are the six heading and footing commands:
+
+`@everyheading LEFT @| CENTER @| RIGHT'
+`@everyfooting LEFT @| CENTER @| RIGHT'
+     The `every' commands specify the format for both even- and
+     odd-numbered pages.  These commands are for documents that are
+     printed on one side of each sheet of paper, or for documents in
+     which you want symmetrical headers or footers.
+
+`@evenheading LEFT @| CENTER @| RIGHT'
+`@oddheading  LEFT @| CENTER @| RIGHT'
+`@evenfooting LEFT @| CENTER @| RIGHT'
+`@oddfooting  LEFT @| CENTER @| RIGHT'
+     The `even' and `odd' commands specify the format for even-numbered
+     pages and odd-numbered pages.  These commands are for books and
+     manuals that are printed on both sides of each sheet of paper.
+
+  Use the `@this...' series of @-commands to provide the names of
+chapters and sections and the page number.  You can use the `@this...'
+commands in the left, center, or right portions of headers and footers,
+or anywhere else in a Texinfo file so long as they are between `@iftex'
+and `@end iftex' commands.
+
+  Here are the `@this...' commands:
+
+`@thispage'
+     Expands to the current page number.
+
+`@thischaptername'
+     Expands to the name of the current chapter.
+
+`@thischapter'
+     Expands to the number and name of the current chapter, in the
+     format `Chapter 1: Title'.
+
+`@thistitle'
+     Expands to the name of the document, as specified by the
+     `@settitle' command.
+
+`@thisfile'
+     For `@include' files only: expands to the name of the current
+     `@include' file.  If the current Texinfo source file is not an
+     `@include' file, this command has no effect.  This command does
+     _not_ provide the name of the current Texinfo source file unless
+     it is an `@include' file.  (*Note Include Files::, for more
+     information about `@include' files.)
+
+You can also use the `@today{}' command, which expands to the current
+date, in `1 Jan 1900' format.
+
+  Other @-commands and text are printed in a header or footer just as
+if they were in the body of a page.  It is useful to incorporate text,
+particularly when you are writing drafts:
+
+     @iftex
+     @headings off
+     @everyheading @emph{Draft!} @| @thispage @| @thischapter
+     @everyfooting @| @| Version: 0.27: @today{}
+     @end iftex
+
+  Beware of overlong titles: they may overlap another part of the
+header or footer and blot it out.

 
 

-  Often, when you are writing a document, you want to typeset and print
-only part of a file to see what it will look like.  You can use the
-`texinfo-tex-region' and related commands for this purpose.  Use the
-`texinfo-tex-buffer' command to format all of a buffer.
+\1f
+File: texinfo.info,  Node: Catching Mistakes,  Next: Refilling Paragraphs,  Prev: Headings,  Up: Top

 
 

-`C-c C-t C-b'
-`M-x texinfo-tex-buffer'
-     Run `texi2dvi' on the buffer.  In addition to running TeX on the
-     buffer, this command automatically creates or updates indices as
-     needed.
+Formatting Mistakes
+*******************

 
 

-`C-c C-t C-r'
-`M-x texinfo-tex-region'
-     Run TeX on the region.
+Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo:  you can make mistakes with
+@-commands, and you can make mistakes with the structure of the nodes
+and chapters.

 
 

-`C-c C-t C-i'
-`M-x texinfo-texindex'
-     Run `texindex' to sort the indices of a Texinfo file formatted with
-     `texinfo-tex-region'.  The `texinfo-tex-region' command does not
-     run `texindex' automatically; it only runs the `tex' typesetting
-     command.  You must run the `texinfo-tex-region' command a second
-     time after sorting the raw index files with the `texindex'
-     command.  (Usually, you do not format an index when you format a
-     region, only when you format a buffer.  Now that the `texi2dvi'
-     command exists, there is little or no need for this command.)
+  Emacs has two tools for catching the @-command mistakes and two for
+catching structuring mistakes.

 
 

-`C-c C-t C-p'
-`M-x texinfo-tex-print'
-     Print the file (or the part of the file) previously formatted with
-     `texinfo-tex-buffer' or `texinfo-tex-region'.
+  For finding problems with @-commands, you can run TeX or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write it.

 
 

-  For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
-_must_ start with a `\input texinfo' line and must include an
-`@settitle' line.  The file must end with `@bye' on a line by itself.
-(When you use `texinfo-tex-region', you must surround the `@settitle'
-line with start-of-header and end-of-header lines.)
+  For finding problems with the structure of nodes and chapters, you
+can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
+command and you can use the `M-x Info-validate' command.

 
 

-  *Note Format/Print Hardcopy::, for a description of the other TeX
-related commands, such as `tex-show-print-queue'.
+* Menu:
+
+* makeinfo Preferred::          `makeinfo' finds errors.
+* Debugging with Info::         How to catch errors with Info formatting.
+* Debugging with TeX::          How to catch errors with TeX formatting.
+* Using texinfo-show-structure::  How to use `texinfo-show-structure'.
+* Using occur::                 How to list all lines containing a pattern.
+* Running Info-Validate::       How to find badly referenced nodes.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Texinfo Mode Summary,  Prev: Printing,  Up: Texinfo Mode
+File: texinfo.info,  Node: makeinfo Preferred,  Next: Debugging with Info,  Prev: Catching Mistakes,  Up: Catching Mistakes

 
 

-Texinfo Mode Summary
-====================
+`makeinfo' Find Errors
+======================

 
 

-  In Texinfo mode, each set of commands has default keybindings that
-begin with the same keys.  All the commands that are custom-created for
-Texinfo mode begin with `C-c'.  The keys are somewhat mnemonic.
-
-Insert Commands
----------------
-
-  The insert commands are invoked by typing `C-c' twice and then the
-first letter of the @-command to be inserted.  (It might make more
-sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
-is quick to type.)
-
-     C-c C-c c       Insert `@code'.
-     C-c C-c d       Insert `@dfn'.
-     C-c C-c e       Insert `@end'.
-     C-c C-c i       Insert `@item'.
-     C-c C-c n       Insert `@node'.
-     C-c C-c s       Insert `@samp'.
-     C-c C-c v       Insert `@var'.
-     C-c C-c {       Insert braces.
-     C-c C-c ]
-     C-c C-c }       Move out of enclosing braces.
-     
-     C-c C-c C-d     Insert a node's section title
-                     in the space for the description
-                     in a menu entry line.
+  The `makeinfo' program does an excellent job of catching errors and
+reporting them--far better than `texinfo-format-region' or
+`texinfo-format-buffer'.  In addition, the various functions for
+automatically creating and updating node pointers and menus remove many
+opportunities for human error.

 
 

-Show Structure
---------------
+  If you can, use the updating commands to create and insert pointers
+and menus.  These prevent many errors.  Then use `makeinfo' (or its
+Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
+to format your file and check for other errors.  This is the best way
+to work with Texinfo.  But if you cannot use `makeinfo', or your
+problem is very puzzling, then you may want to use the tools described
+in this appendix.

 
 

-  The `texinfo-show-structure' command is often used within a narrowed
-region.
+\1f
+File: texinfo.info,  Node: Debugging with Info,  Next: Debugging with TeX,  Prev: makeinfo Preferred,  Up: Catching Mistakes
+
+Catching Errors with Info Formatting
+====================================

 
 

-     C-c C-s         List all the headings.
+After you have written part of a Texinfo file, you can use the
+`texinfo-format-region' or the `makeinfo-region' command to see whether
+the region formats properly.

 
 

-The Master Update Command
--------------------------
+  Most likely, however, you are reading this section because for some
+reason you cannot use the `makeinfo-region' command; therefore, the
+rest of this section presumes that you are using
+`texinfo-format-region'.

 
 

-  The `texinfo-master-menu' command creates a master menu; and can be
-used to update every node and menu in a file as well.
+  If you have made a mistake with an @-command, `texinfo-format-region'
+will stop processing at or after the error and display an error
+message.  To see where in the buffer the error occurred, switch to the
+`*Info Region*' buffer; the cursor will be in a position that is after
+the location of the error.  Also, the text will not be formatted after
+the place where the error occurred (or more precisely, where it was
+detected).

 
 

-     C-c C-u m
-     M-x texinfo-master-menu
-                     Create or update a master menu.
+  For example, if you accidentally end a menu with the command `@end
+menus' with an `s' on the end, instead of with `@end menu', you will
+see an error message that says:
+
+     @end menus is not handled by texinfo
+
+The cursor will stop at the point in the buffer where the error occurs,
+or not long after it.  The buffer will look like this:
+
+     ---------- Buffer: *Info Region* ----------
+     * Menu:

      
      

-     C-u C-c C-u m   With `C-u' as a prefix argument, first
-                     create or update all nodes and regular
-                     menus, and then create a master menu.
+     * Using texinfo-show-structure::  How to use
+                                       `texinfo-show-structure'
+                                       to catch mistakes.
+     * Running Info-Validate::         How to check for
+                                       unreferenced nodes.
+     @end menus
+     -!-
+     ---------- Buffer: *Info Region* ----------

 
 

-Update Pointers
----------------
+  The `texinfo-format-region' command sometimes provides slightly odd
+error messages.  For example, the following cross reference fails to
+format:

 
 

-  The update pointer commands are invoked by typing `C-c C-u' and then
-either `C-n' for `texinfo-update-node' or `C-e' for
-`texinfo-every-node-update'.
+     (@xref{Catching Mistakes, for more info.)

 
 

-     C-c C-u C-n     Update a node.
-     C-c C-u C-e     Update every node in the buffer.
+In this case, `texinfo-format-region' detects the missing closing brace
+but displays a message that says `Unbalanced parentheses' rather than
+`Unbalanced braces'.  This is because the formatting command looks for
+mismatches between braces as if they were parentheses.

 
 

-Update Menus
-------------
+  Sometimes `texinfo-format-region' fails to detect mistakes.  For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:

 
 

-  Invoke the  update menu commands by typing `C-c C-u' and then either
-`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
-To update both nodes and menus at the same time, precede `C-c C-u C-a'
-with `C-u'.
+     (@xref{Catching Mistakes), for more info.}

 
 

-     C-c C-u C-m     Make or update a menu.
-     
-     C-c C-u C-a     Make or update all
-                     menus in a buffer.
-     
-     C-u C-c C-u C-a With `C-u' as a prefix argument,
-                     first create or update all nodes and
-                     then create or update all menus.
+Formatting produces:
+     (*Note for more info.: Catching Mistakes)

 
 

-Format for Info
----------------
+  The only way for you to detect this error is to realize that the
+reference should have looked like this:

 
 

-  The Info formatting commands that are written in Emacs Lisp are
-invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
-for the whole buffer.
+     (*Note Catching Mistakes::, for more info.)

 
 

-  The Info formatting commands that are written in C and based on the
-`makeinfo' program are invoked by typing `C-c C-m' and then either
-`C-r' for a region or `C-b' for the whole buffer.
+  Incidentally, if you are reading this node in Info and type `f <RET>'
+(`Info-follow-reference'), you will generate an error message that says:

 
 

-Use the `texinfo-format...' commands:
+     No such node: "Catching Mistakes) The only way ...

 
 

-     C-c C-e C-r     Format the region.
-     C-c C-e C-b     Format the buffer.
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a <RET> immediately after
+typing the Info `f' command, Info will attempt to go to the referenced
+node.  If you type `f catch <TAB> <RET>', Info will complete the node
+name of the correctly written example and take you to the `Catching
+Mistakes' node.  (If you try this, you can return from the `Catching
+Mistakes' node by typing `l' (`Info-last').)

 
 

-Use `makeinfo':
+\1f
+File: texinfo.info,  Node: Debugging with TeX,  Next: Using texinfo-show-structure,  Prev: Debugging with Info,  Up: Catching Mistakes
+
+Catching Errors with TeX Formatting
+===================================
+
+You can also catch mistakes when you format a file with TeX.
+
+  Usually, you will want to do this after you have run
+`texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same
+file, because `texinfo-format-buffer' sometimes displays error messages
+that make more sense than TeX.  (*Note Debugging with Info::, for more
+information.)
+
+  For example, TeX was run on a Texinfo file, part of which is shown
+here:
+
+     ---------- Buffer: texinfo.texi ----------
+     name of the Texinfo file as an extension.  The
+     @samp{??} are `wildcards' that cause the shell to
+     substitute all the raw index files.  (@xref{sorting
+     indices, for more information about sorting
+     indices.)@refill
+     ---------- Buffer: texinfo.texi ----------
+
+(The cross reference lacks a closing brace.)  TeX produced the
+following output, after which it stopped:
+
+     ---------- Buffer: *tex-shell* ----------
+     Runaway argument?
+     {sorting indices, for more information about sorting
+     indices.) @refill @ETC.
+     ! Paragraph ended before @xref was complete.
+     <to be read again>
+                        @par
+     l.27
+     
+     ?
+     ---------- Buffer: *tex-shell* ----------

 
 

-     C-c C-m C-r     Format the region.
-     C-c C-m C-b     Format the buffer.
-     C-c C-m C-l     Recenter the `makeinfo' output buffer.
-     C-c C-m C-k     Kill the `makeinfo' formatting job.
+  In this case, TeX produced an accurate and understandable error
+message:

 
 

-Typeset and Print
------------------
+     Paragraph ended before @xref was complete.

 
 

-  The TeX typesetting and printing commands are invoked by typing `C-c
-C-t' and then another control command: `C-r' for `texinfo-tex-region',
-`C-b' for `texinfo-tex-buffer', and so on.
+`@par' is an internal TeX command of no relevance to Texinfo.  `l.27'
+means that TeX detected the problem on line 27 of the Texinfo file.
+The `?' is the prompt TeX uses in this circumstance.

 
 

-     C-c C-t C-r     Run TeX on the region.
-     C-c C-t C-b     Run `texi2dvi' on the buffer.
-     C-c C-t C-i     Run `texindex'.
-     C-c C-t C-p     Print the DVI file.
-     C-c C-t C-q     Show the print queue.
-     C-c C-t C-d     Delete a job from the print queue.
-     C-c C-t C-k     Kill the current TeX formatting job.
-     C-c C-t C-x     Quit a currently stopped TeX formatting job.
-     C-c C-t C-l     Recenter the output buffer.
+  Unfortunately, TeX is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went wrong.

 
 

-Other Updating Commands
------------------------
+  In any case, if you run into a problem like this, you can do one of
+three things.

 
 

-  The `other updating commands' do not have standard keybindings because
-they are rarely used.
+  1. You can tell TeX to continue running and ignore just this error by
+     typing <RET> at the `?' prompt.

 
 

-     M-x texinfo-insert-node-lines
-                     Insert missing `@node' lines in region.
-                     With `C-u' as a prefix argument,
-                     use section titles as node names.
-     
-     M-x texinfo-multiple-files-update
-                     Update a multi-file document.
-                     With `C-u 2' as a prefix argument,
-                     create or update all nodes and menus
-                     in all included files first.
-     
-     M-x texinfo-indent-menu-description
-                     Indent descriptions.
-     
-     M-x texinfo-sequential-node-update
-                     Insert node pointers in strict sequence.
+  2. You can tell TeX to continue running and to ignore all errors as
+     best it can by typing `r <RET>' at the `?' prompt.

 
 

-\1f
-File: texinfo.info,  Node: Beginning a File,  Next: Ending a File,  Prev: Texinfo Mode,  Up: Top
+     This is often the best thing to do.  However, beware: the one error
+     may produce a cascade of additional error messages as its
+     consequences are felt through the rest of the file.  To stop TeX
+     when it is producing such an avalanche of error messages, type
+     `C-c' (or `C-c C-c', if you are running a shell inside Emacs).

 
 

-Beginning a Texinfo File
-************************
+  3. You can tell TeX to stop this run by typing `x <RET>' at the `?'
+     prompt.

 
 

-  Certain pieces of information must be provided at the beginning of a
-Texinfo file, such as the name of the file and the title of the
-document.
+  Please note that if you are running TeX inside Emacs, you need to
+switch to the shell buffer and line at which TeX offers the `?' prompt.

 
 

-* Menu:
+  Sometimes TeX will format a file without producing error messages even
+though there is a problem.  This usually occurs if a command is not
+ended but TeX is able to continue processing anyhow.  For example, if
+you fail to end an itemized list with the `@end itemize' command, TeX
+will write a DVI file that you can print out.  The only error message
+that TeX will give you is the somewhat mysterious comment that
+
+     (@end occurred inside a group at level 1)
+
+However, if you print the DVI file, you will find that the text of the
+file that follows the itemized list is entirely indented as if it were
+part of the last item in the itemized list.  The error message is the
+way TeX says that it expected to find an `@end' command somewhere in
+the file; but that it could not determine where it was needed.
+
+  Another source of notoriously hard-to-find errors is a missing `@end
+group' command.  If you ever are stumped by incomprehensible errors,
+look for a missing `@end group' command first.

 
 

-* Four Parts::                  Four parts begin a Texinfo file.
-* Sample Beginning::            Here is a sample beginning for a Texinfo file.
-* Header::                      The very beginning of a Texinfo file.
-* Info Summary and Permissions::  Summary and copying permissions for Info.
-* Titlepage & Copyright Page::  Creating the title and copyright pages.
-* The Top Node::                Creating the `Top' node and master menu.
-* Software Copying Permissions::  Ensure that you and others continue to
-                                  have the right to use and share software.
+  If the Texinfo file lacks header lines, TeX may stop in the beginning
+of its run and display output that looks like the following.  The `*'
+indicates that TeX is waiting for input.
+
+     This is TeX, Version 3.14159 (Web2c 7.0)
+     (test.texinfo [1])
+     *
+
+In this case, simply type `\end <RET>' after the asterisk.  Then write
+the header lines in the Texinfo file and run the TeX command again.
+(Note the use of the backslash, `\'.  TeX uses `\' instead of `@'; and
+in this circumstance, you are working directly with TeX, not with
+Texinfo.)

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Four Parts,  Next: Sample Beginning,  Prev: Beginning a File,  Up: Beginning a File
+File: texinfo.info,  Node: Using texinfo-show-structure,  Next: Using occur,  Prev: Debugging with TeX,  Up: Catching Mistakes
+
+Using `texinfo-show-structure'
+==============================
+
+It is not always easy to keep track of the nodes, chapters, sections,
+and subsections of a Texinfo file.  This is especially true if you are
+revising or adding to a Texinfo file that someone else has written.
+
+  In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
+lists all the lines that begin with the @-commands that specify the
+structure: `@chapter', `@section', `@appendix', and so on.  With an
+argument (`C-u' as prefix argument, if interactive), the command also
+shows the `@node' lines.  The `texinfo-show-structure' command is bound
+to `C-c C-s' in Texinfo mode, by default.
+
+  The lines are displayed in a buffer called the `*Occur*' buffer,
+indented by hierarchical level.  For example, here is a part of what was
+produced by running `texinfo-show-structure' on this manual:
+
+      Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
+      unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+      in buffer texinfo.texi.
+      ...
+      4177:@chapter Nodes
+      4198:    @heading Two Paths
+      4231:    @section Node and Menu Illustration
+      4337:    @section The @code{@@node} Command
+      4393:        @subheading Choosing Node and Pointer Names
+      4417:        @subsection How to Write an @code{@@node} Line
+      4469:        @subsection @code{@@node} Line Tips
+      ...
+
+  This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
+with the `@section', `@subheading', and `@subsection' commands
+respectively.  If you move your cursor into the `*Occur*' window, you
+can position the cursor over one of the lines and use the `C-c C-c'
+command (`occur-mode-goto-occurrence'), to jump to the corresponding
+spot in the Texinfo file.  *Note Using Occur: (xemacs)Other Repeating
+Search, for more information about `occur-mode-goto-occurrence'.
+
+  The first line in the `*Occur*' window describes the "regular
+expression" specified by TEXINFO-HEADING-PATTERN.  This regular
+expression is the pattern that `texinfo-show-structure' looks for.
+*Note Using Regular Expressions: (xemacs)Regexps, for more information.
+
+  When you invoke the `texinfo-show-structure' command, Emacs will
+display the structure of the whole buffer.  If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the `C-x n n' (`narrow-to-region') command to mark the region.
+(*Note Narrowing: (xemacs)Narrowing.)  This is how the example used
+above was generated.  (To see the whole buffer again, use `C-x n w'
+(`widen').)

 
 

-Four Parts Begin a File
-=======================
+  If you call `texinfo-show-structure' with a prefix argument by typing
+`C-u C-c C-s', it will list lines beginning with `@node' as well as the
+lines beginning with the @-sign commands for `@chapter', `@section',
+and the like.

 
 

-  Generally, the beginning of a Texinfo file has four parts:
+  You can remind yourself of the structure of a Texinfo file by looking
+at the list in the `*Occur*' window; and if you have mis-named a node
+or left out a section, you can correct the mistake.

 
 

-  1. The header, delimited by special comment lines, that includes the
-     commands for naming the Texinfo file and telling TeX what
-     definitions file to use when processing the Texinfo file.
+\1f
+File: texinfo.info,  Node: Using occur,  Next: Running Info-Validate,  Prev: Using texinfo-show-structure,  Up: Catching Mistakes
+
+Using `occur'
+=============

 
 

-  2. A short statement of what the file is about, with a copyright
-     notice and copying permissions.  This is enclosed in `@ifinfo' and
-     `@end ifinfo' commands so that the formatters place it only in the
-     Info file.
+Sometimes the `texinfo-show-structure' command produces too much
+information.  Perhaps you want to remind yourself of the overall
+structure of a Texinfo file, and are overwhelmed by the detailed list
+produced by `texinfo-show-structure'.  In this case, you can use the
+`occur' command directly.  To do this, type

 
 

-  3. A title page and copyright page, with a copyright notice and
-     copying permissions.  This is enclosed between `@titlepage' and
-     `@end titlepage' commands.  The title and copyright page appear
-     only in the printed manual.
+     M-x occur

 
 

-  4. The `Top' node that contains a menu for the whole Info file.  The
-     contents of this node appear only in the Info file.
+and then, when prompted, type a "regexp", a regular expression for the
+pattern you want to match.  (*Note Regular Expressions:
+(xemacs)Regexps.)  The `occur' command works from the current location
+of the cursor in the buffer to the end of the buffer.  If you want to
+run `occur' on the whole buffer, place the cursor at the beginning of
+the buffer.

 
 

-  Also, optionally, you may include the copying conditions for a program
-and a warranty disclaimer.  The copying section will be followed by an
-introduction or else by the first chapter of the manual.
+  For example, to see all the lines that contain the word `@chapter' in
+them, just type `@chapter'.  This will produce a list of the chapters.
+It will also list all the sentences with `@chapter' in the middle of
+the line.

 
 

-  Since the copyright notice and copying permissions for the Texinfo
-document (in contrast to the copying permissions for a program) are in
-parts that appear only in the Info file or only in the printed manual,
-this information must be given twice.
+  If you want to see only those lines that start with the word
+`@chapter', type `^@chapter' when prompted by `occur'.  If you want to
+see all the lines that end with a word or phrase, end the last word
+with a `$'; for example, `catching mistakes$'.  This can be helpful
+when you want to see all the nodes that are part of the same chapter or
+section and therefore have the same `Up' pointer.
+
+  *Note Using Occur: (xemacs)Other Repeating Search, for more
+information.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Sample Beginning,  Next: Header,  Prev: Four Parts,  Up: Beginning a File
+File: texinfo.info,  Node: Running Info-Validate,  Prev: Using occur,  Up: Catching Mistakes

 
 

-Sample Texinfo File Beginning
-=============================
+Finding Badly Referenced Nodes
+==============================

 
 

-  The following sample shows what is needed.
+You can use the `Info-validate' command to check whether any of the
+`Next', `Previous', `Up' or other node pointers fail to point to a
+node.  This command checks that every node pointer points to an
+existing node.  The `Info-validate' command works only on Info files,
+not on Texinfo files.

 
 

-     \input texinfo   @c -*-texinfo-*-
-     @c %**start of header
-     @setfilename NAME-OF-INFO-FILE
-     @settitle NAME-OF-MANUAL
-     @setchapternewpage odd
-     @c %**end of header
-     
-     @ifinfo
-     This file documents ...
-     
-     Copyright YEAR COPYRIGHT-OWNER
-     
-     Permission is granted to ...
-     @end ifinfo
-     
-     @c  This title page illustrates only one of the
-     @c  two methods of forming a title page.
-     
-     @titlepage
-     @title NAME-OF-MANUAL-WHEN-PRINTED
-     @subtitle SUBTITLE-IF-ANY
-     @subtitle SECOND-SUBTITLE
-     @author AUTHOR
-     
-     @c  The following two commands
-     @c  start the copyright page.
-     @page
-     @vskip 0pt plus 1filll
-     Copyright @copyright{} YEAR COPYRIGHT-OWNER
-     
-     Published by ...
-     
-     Permission is granted to ...
-     @end titlepage
-     
-     @node Top, Overview, , (dir)
-     
-     @ifinfo
-     This document describes ...
-     
-     This document applies to version ...
-     of the program named ...
-     @end ifinfo
-     
-     @menu
-     * Copying::          Your rights and freedoms.
-     * First Chapter::    Getting started ...
-     * Second Chapter::              ...
-       ...
-       ...
-     @end menu
-     
-     @node    First Chapter, Second Chapter, top,      top
-     @comment node-name,     next,           previous, up
-     @chapter First Chapter
-     @cindex Index entry for First Chapter
+  The `makeinfo' program validates pointers automatically, so you do
+not need to use the `Info-validate' command if you are using
+`makeinfo'.  You only may need to use `Info-validate' if you are unable
+to run `makeinfo' and instead must create an Info file using
+`texinfo-format-region' or `texinfo-format-buffer', or if you write an
+Info file from scratch.
+
+* Menu:
+
+* Using Info-validate::         How to run `Info-validate'.
+* Unsplit::                     How to create an unsplit file.
+* Tagifying::                   How to tagify a file.
+* Splitting::                   How to split a file manually.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Header,  Next: Info Summary and Permissions,  Prev: Sample Beginning,  Up: Beginning a File
+File: texinfo.info,  Node: Using Info-validate,  Next: Unsplit,  Prev: Running Info-Validate,  Up: Running Info-Validate

 
 

-The Texinfo File Header
-=======================
+Running `Info-validate'
+-----------------------

 
 

-  Texinfo files start with at least three lines that provide Info and
-TeX with necessary information.  These are the `\input texinfo' line,
-the `@settitle' line, and the `@setfilename' line.  If you want to run
-TeX on just a part of the Texinfo File, you must write the `@settitle'
-and `@setfilename' lines between start-of-header and end-of-header
-lines.
+To use `Info-validate', visit the Info file you wish to check and type:

 
 

-  Thus, the beginning of a Texinfo file looks like this:
+     M-x Info-validate

 
 

-     \input texinfo   @c -*-texinfo-*-
-     @setfilename sample.info
-     @settitle Sample Document
+(Note that the `Info-validate' command requires an upper case `I'.  You
+may also need to create a tag table before running `Info-validate'.
+*Note Tagifying::.)

 
 

-or else like this:
+  If your file is valid, you will receive a message that says "File
+appears valid".  However, if you have a pointer that does not point to
+a node, error messages will be displayed in a buffer called `*problems
+in info file*'.

 
 

-     \input texinfo   @c -*-texinfo-*-
-     @c %**start of header
-     @setfilename sample.info
-     @settitle Sample Document
-     @c %**end of header
+  For example, `Info-validate' was run on a test file that contained
+only the first node of this manual.  One of the messages said:

 
 

-* Menu:
+     In node "Overview", invalid Next: Texinfo Mode
+
+This meant that the node called `Overview' had a `Next' pointer that
+did not point to anything (which was true in this case, since the test
+file had only one node in it).

 
 

-* First Line::                  The first line of a Texinfo file.
-* Start of Header::             Formatting a region requires this.
-* setfilename::                 Tell Info the name of the Info file.
-* settitle::                    Create a title for the printed work.
-* setchapternewpage::           Start chapters on right-hand pages.
-* paragraphindent::             An option to specify paragraph indentation.
-* End of Header::               Formatting a region requires this.
+  Now suppose we add a node named `Texinfo Mode' to our test case but
+we do not specify a `Previous' for this node.  Then we will get the
+following error message:
+
+     In node "Texinfo Mode", should have Previous: Overview
+
+This is because every `Next' pointer should be matched by a `Previous'
+(in the node where the `Next' points) which points back.
+
+  `Info-validate' also checks that all menu entries and cross references
+point to actual nodes.
+
+  Note that `Info-validate' requires a tag table and does not work with
+files that have been split.  (The `texinfo-format-buffer' command
+automatically splits large files.)  In order to use `Info-validate' on
+a large file, you must run `texinfo-format-buffer' with an argument so
+that it does not split the Info file; and you must create a tag table
+for the unsplit file.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: First Line,  Next: Start of Header,  Prev: Header,  Up: Header
+File: texinfo.info,  Node: Unsplit,  Next: Tagifying,  Prev: Using Info-validate,  Up: Running Info-Validate

 
 

-The First Line of a Texinfo File
---------------------------------
+Creating an Unsplit File
+------------------------

 
 

-  Every Texinfo file that is to be the top-level input to TeX must begin
-with a line that looks like this:
+You can run `Info-validate' only on a single Info file that has a tag
+table.  The command will not work on the indirect subfiles that are
+generated when a master file is split.  If you have a large file
+(longer than 70,000 bytes or so), you need to run the
+`texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
+it does not create indirect subfiles.  You will also need to create a
+tag table for the Info file.  After you have done this, you can run
+`Info-validate' and look for badly referenced nodes.

 
 

-     \input texinfo   @c -*-texinfo-*-
+  The first step is to create an unsplit Info file.  To prevent
+`texinfo-format-buffer' from splitting a Texinfo file into smaller Info
+files, give a prefix to the `M-x texinfo-format-buffer' command:
+
+     C-u M-x texinfo-format-buffer

 
 

-This line serves two functions:
+or else

 
 

-  1. When the file is processed by TeX, the `\input texinfo' command
-     tells TeX to load the macros needed for processing a Texinfo file.
-     These are in a file called `texinfo.tex', which is usually located
-     in the `/usr/lib/tex/macros' directory.  TeX uses the backslash,
-     `\', to mark the beginning of a command, just as Texinfo uses `@'.
-     The `texinfo.tex' file causes the switch from `\' to `@'; before
-     the switch occurs, TeX requires `\', which is why it appears at
-     the beginning of the file.
+     C-u C-c C-e C-b

 
 

-  2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
-     specification tells Emacs to use Texinfo mode.
+When you do this, Texinfo will not split the file and will not create a
+tag table for it.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: Start of Header,  Next: setfilename,  Prev: First Line,  Up: Header
+File: texinfo.info,  Node: Tagifying,  Next: Splitting,  Prev: Unsplit,  Up: Running Info-Validate

 
 

-Start of Header
----------------
+Tagifying a File
+----------------

 
 

-  Write a start-of-header line on the second line of a Texinfo file.
-Follow the start-of-header line with `@setfilename' and `@settitle'
-lines and, optionally, with other command lines, such as `@smallbook'
-or `@footnotestyle'; and then by an end-of-header line (*note End of
-Header::).
+After creating an unsplit Info file, you must create a tag table for
+it.  Visit the Info file you wish to tagify and type:

 
 

-  With these lines, you can format part of a Texinfo file for Info or
-typeset part for printing.
+     M-x Info-tagify

 
 

-  A start-of-header line looks like this:
+(Note the upper case `I' in `Info-tagify'.)  This creates an Info file
+with a tag table that you can validate.

 
 

-     @c %**start of header
+  The third step is to validate the Info file:
+
+     M-x Info-validate

 
 

-  The odd string of characters, `%**', is to ensure that no other
-comment is accidentally taken for a start-of-header line.
+(Note the upper case `I' in `Info-validate'.)  In brief, the steps are:
+
+     C-u M-x texinfo-format-buffer
+     M-x Info-tagify
+     M-x Info-validate
+
+  After you have validated the node structure, you can rerun
+`texinfo-format-buffer' in the normal way so it will construct a tag
+table and split the file automatically, or you can make the tag table
+and split the file manually.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: setfilename,  Next: settitle,  Prev: Start of Header,  Up: Header
+File: texinfo.info,  Node: Splitting,  Prev: Tagifying,  Up: Running Info-Validate
+
+Splitting a File Manually
+-------------------------
+
+You should split a large file or else let the `texinfo-format-buffer'
+or `makeinfo-buffer' command do it for you automatically.  (Generally
+you will let one of the formatting commands do this job for you.  *Note
+Create an Info File::.)
+
+  The split-off files are called the indirect subfiles.
+
+  Info files are split to save memory.  With smaller files, Emacs does
+not have make such a large buffer to hold the information.
+
+  If an Info file has more than 30 nodes, you should also make a tag
+table for it. *Note Using Info-validate::, for information about
+creating a tag table.  (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually.  Most likely, you
+will do this for a large, unsplit file on which you have run
+`Info-validate'.)

 
 

-`@setfilename'
---------------
+  Visit the Info file you wish to tagify and split and type the two
+commands:

 
 

-  In order to serve as the primary input file for either `makeinfo' or
-TeX, a Texinfo file must contain a line that looks like this:
+     M-x Info-tagify
+     M-x Info-split

 
 

-     @setfilename INFO-FILE-NAME
+(Note that the `I' in `Info' is upper case.)

 
 

-  Write the `@setfilename' command at the beginning of a line and
-follow it on the same line by the Info file name.  Do not write anything
-else on the line; anything on the line after the command is considered
-part of the file name, including what would otherwise be a comment.
+  When you use the `Info-split' command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles.  This file should
+be saved in place of the original visited file.  The indirect subfiles
+are written in the same directory the original file is in, with names
+generated by appending `-' and a number to the original file name.

 
 

-  The `@setfilename' line specifies the name of the Info file to be
-generated.  This name should be different from the name of the Texinfo
-file.  There are two conventions for choosing the name: you can either
-remove the `.texi' extension from the input file name, or replace it
-with the `.info' extension.
+  The primary file still functions as an Info file, but it contains just
+the tag table and a directory of subfiles.

 
 

-  Some operating systems cannot handle long file names.  You can run
-into a problem even when the file name you specify is itself short
-enough.  This occurs because the Info formatters split a long Info file
-into short indirect subfiles, and name them by appending `-1', `-2',
-..., `-10', `-11', and so on, to the original file name.  (*Note Tag
-Files and Split Files: Tag and Split Files.)  The subfile name
-`texinfo.info-10', for example, is too long for some systems; so the
-Info file name for this document is `texinfo' rather than
-`texinfo.info'.
+\1f
+File: texinfo.info,  Node: Refilling Paragraphs,  Next: Command Syntax,  Prev: Catching Mistakes,  Up: Top
+
+Refilling Paragraphs
+********************
+
+The `@refill' command refills and, optionally, indents the first line
+of a paragraph.(1) (*note Refilling Paragraphs-Footnote-1::) The
+`@refill' command is no longer important, but we describe it here
+because you once needed it.  You will see it in many old Texinfo files.
+
+  Without refilling, paragraphs containing long @-constructs may look
+bad after formatting because the formatter removes @-commands and
+shortens some lines more than others.  In the past, neither the
+`texinfo-format-region' command nor the `texinfo-format-buffer' command
+refilled paragraphs automatically.  The `@refill' command had to be
+written at the end of every paragraph to cause these formatters to fill
+them.  (Both TeX and `makeinfo' have always refilled paragraphs
+automatically.)  Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and indented.
+
+  The `@refill' command causes `texinfo-format-region' and
+`texinfo-format-buffer' to refill a paragraph in the Info file _after_
+all the other processing has been done.  For this reason, you can not
+use `@refill' with a paragraph containing either `@*' or `@w{ ... }'
+since the refilling action will override those two commands.
+
+  The `texinfo-format-region' and `texinfo-format-buffer' commands now
+automatically append `@refill' to the end of each paragraph that should
+be filled.  They do not append `@refill' to the ends of paragraphs that
+contain `@*' or `@w{ ...}' and therefore do not refill or indent them.
+
+\1f
+File: texinfo.info,  Node: Refilling Paragraphs-Footnotes,  Up: Refilling Paragraphs

 
 

-  The Info formatting commands ignore everything written before the
-`@setfilename' line, which is why the very first line of the file (the
-`\input' line) does not show up in the output.
+  (1) Perhaps the command should have been called the
+`@refillandindent' command, but `@refill' is shorter and the name was
+chosen before indenting was possible.

 
 

-  The `@setfilename' line produces no output when you typeset a manual
-with TeX, but it nevertheless is essential: it opens the index,
-cross-reference, and other auxiliary files used by Texinfo, and also
-reads `texinfo.cnf' if that file is present on your system (*note
-Preparing to Use TeX: Preparing for TeX.).
+\1f
+File: texinfo.info,  Node: Command Syntax,  Next: Obtaining TeX,  Prev: Refilling Paragraphs,  Up: Top
+
+@-Command Syntax
+****************
+
+The character `@' is used to start special Texinfo commands.  (It has
+the same meaning that `\' has in plain TeX.)  Texinfo has four types of
+@-command:
+
+1. Non-alphabetic commands.
+     These commands consist of an @ followed by a punctuation mark or
+     other character that is not part of the alphabet.  Non-alphabetic
+     commands are almost always part of the text within a paragraph,
+     and never take any argument.  The two characters (@ and the other
+     one) are complete in themselves; none is followed by braces.  The
+     non-alphabetic commands are: `@.', `@:', `@*', `@SPACE', `@TAB',
+     `@NL', `@@', `@{', and `@}'.
+
+2. Alphabetic commands that do not require arguments.
+     These commands start with @ followed by a word followed by left-
+     and right-hand braces.  These commands insert special symbols in
+     the document; they do not require arguments.  For example,
+     `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
+     `@bullet{}' => `*'.
+
+3. Alphabetic commands that require arguments within braces.
+     These commands start with @ followed by a letter or a word,
+     followed by an argument within braces.  For example, the command
+     `@dfn' indicates the introductory or defining use of a term; it is
+     used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
+     commands.'
+
+4. Alphabetic commands that occupy an entire line.
+     These commands occupy an entire line.  The line starts with @,
+     followed by the name of the command (a word); for example,
+     `@center' or `@cindex'.  If no argument is needed, the word is
+     followed by the end of the line.  If there is an argument, it is
+     separated from the command name by a space.  Braces are not used.
+
+  Thus, the alphabetic commands fall into classes that have different
+argument syntaxes.  You cannot tell to which class a command belongs by
+the appearance of its name, but you can tell by the command's meaning:
+if the command stands for a glyph, it is in class 2 and does not
+require an argument; if it makes sense to use the command together with
+other text as part of a paragraph, the command is in class 3 and must
+be followed by an argument in braces; otherwise, it is in class 4 and
+uses the rest of the line as its argument.
+
+  The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+Emacs paragraph and filling commands work properly.  There is only one
+exception to this rule: the command `@refill', which is always used at
+the end of a paragraph immediately following the final period or other
+punctuation character.  `@refill' takes no argument and does _not_
+require braces.  `@refill' never confuses the Emacs paragraph commands
+because it cannot appear at the beginning of a line.

 
 \1f
 
 \1f

-File: texinfo.info,  Node: settitle,  Next: setchapternewpage,  Prev: setfilename,  Up: Header
+File: texinfo.info,  Node: Obtaining TeX,  Next: Command and Variable Index,  Prev: Command Syntax,  Up: Top
+
+How to Obtain TeX
+*****************
+
+TeX is freely redistributable.  You can obtain TeX for Unix systems via
+anonymous ftp or on physical media.  The core material consists of the
+Web2c TeX distribution (`http://tug.org/web2c').
+
+  Instructions for retrieval by anonymous ftp and information on other
+available distributions:
+     `ftp://tug.org/tex/unixtex.ftp'
+     `http://tug.org/unixtex.ftp'
+
+  The Free Software Foundation provides a core distribution on its
+Source Code CD-ROM suitable for printing Texinfo manuals; the
+University of Washington maintains and supports a tape distribution;
+the TeX Users Group co-sponsors a complete CD-ROM TeX distribution.
+
+   * For the FSF Source Code CD-ROM, please contact:
+
+          Free Software Foundation, Inc.
+          59 Temple Place Suite 330
+          Boston, MA   02111-1307
+          USA
+          
+          Telephone: +1-617-542-5942
+          Fax: (including Japan) +1-617-542-2652
+          Free Dial Fax (in Japan):
+                0031-13-2473 (KDD)
+                0066-3382-0158 (IDC)
+          Electronic mail: `gnu@gnu.org'
+
+   * To order a complete distribution on CD-ROM, please see
+     `http://tug.org/tex-live.html'.  (This distribution is also
+     available by FTP; see the URL's above.)
+
+   * To order a full distribution from the University of Washington on
+     either a 1/4in 4-track QIC-24 cartridge or a 4mm DAT cartridge,
+     send $210 to:
+
+          Pierre A. MacKay
+          Denny Hall, Mail Stop DH-10
+          University of Washington
+          Seattle, WA   98195
+          USA
+          Telephone: +1-206-543-2268
+          Electronic mail: `mackay@cs.washington.edu'
+
+     Please make checks payable to the University of Washington.
+     Checks must be in U.S. dollars, drawn on a U.S. bank.  Overseas
+     sites: please add to the base cost, if desired, $20.00 for
+     shipment via air parcel post, or $30.00 for shipment via courier.
+
+
+  Many other TeX distributions are available; see `http://tug.org/'.

 
 

-`@settitle'
------------
+\1f
+File: texinfo.info,  Node: Command and Variable Index,  Next: Concept Index,  Prev: Obtaining TeX,  Up: Top

 
 

-  In order to be made into a printed manual, a Texinfo file must contain
-a line that looks like this:
+Command and Variable Index
+**************************

 
 

-     @settitle TITLE
+This is an alphabetical list of all the @-commands, assorted Emacs Lisp
+functions, and several variables.  To make the list easier to use, the
+commands are listed without their preceding `@'.

 
 

-  Write the `@settitle' command at the beginning of a line and follow
-it on the same line by the title.  This tells TeX the title to use in a
-header or footer.  Do not write anything else on the line; anything on
-the line after the command is considered part of the title, including a
-comment.
+* Menu:

 
 

-  Conventionally, when TeX formats a Texinfo file for double-sided
-output, the title is printed in the left-hand (even-numbered) page
-headings and the current chapter title is printed in the right-hand
-(odd-numbered) page headings.  (TeX learns the title of each chapter
-from each `@chapter' command.)  Page footers are not printed.
+* ! (end of sentence):                   Ending a Sentence.
+* ":                                     Inserting Accents.
+* ':                                     Inserting Accents.
+* (newline):                             Multiple Spaces.
+* (space):                               Multiple Spaces.
+* (tab):                                 Multiple Spaces.
+* * (force line break):                  Line Breaks.
+* ,:                                     Inserting Accents.
+* -:                                     - and hyphenation.
+* .  (end of sentence):                  Ending a Sentence.
+* : (suppress widening):                 Not Ending a Sentence.
+* =:                                     Inserting Accents.
+* ? (end of sentence):                   Ending a Sentence.
+* @ (single @):                          Inserting An Atsign.
+* ^:                                     Inserting Accents.
+* `:                                     Inserting Accents.
+* AA:                                    Inserting Accents.
+* aa:                                    Inserting Accents.
+* AE:                                    Inserting Accents.
+* ae:                                    Inserting Accents.
+* afourpaper:                            A4 Paper.
+* appendix:                              unnumbered & appendix.
+* appendixsec:                           unnumberedsec appendixsec heading.
+* appendixsection:                       unnumberedsec appendixsec heading.
+* appendixsubsec:                        unnumberedsubsec appendixsubsec subheading.
+* appendixsubsubsec:                     subsubsection.
+* apply:                                 Sample Function Definition.
+* asis:                                  table.
+* author:                                title subtitle author.
+* b (bold font):                         Fonts.
+* buffer-end:                            Def Cmd Template.
+* bullet:                                bullet.
+* bye <1>:                               File End.
+* bye:                                   Ending a File.
+* c (comment):                           Comments.
+* cartouche:                             cartouche.
+* center:                                titlefont center sp.
+* centerchap:                            chapter.
+* chapheading:                           majorheading & chapheading.
+* chapter:                               chapter.
+* cindex:                                Indexing Commands.
+* cite:                                  cite.
+* clear:                                 ifset ifclear.
+* code:                                  code.
+* columnfractions:                       Multitable Column Widths.
+* comment:                               Comments.
+* contents:                              Contents.
+* copyright <1>:                         copyright symbol.
+* copyright:                             Copyright & Permissions.
+* cropmarks:                             Cropmarks and Magnification.
+* defcodeindex:                          New Indices.
+* defcv:                                 Abstract Objects.
+* deffn:                                 Functions Commands.
+* deffnx:                                deffnx.
+* defindex:                              New Indices.
+* definfoenclose:                        Customized Highlighting.
+* defivar:                               Abstract Objects.
+* defmac:                                Functions Commands.
+* defmethod:                             Abstract Objects.
+* defop:                                 Abstract Objects.
+* defopt:                                Variables Commands.
+* defspec:                               Functions Commands.
+* deftp:                                 Data Types.
+* deftypefn:                             Typed Functions.
+* deftypefun:                            Typed Functions.
+* deftypevar:                            Typed Variables.
+* deftypevr:                             Typed Variables.
+* defun:                                 Functions Commands.
+* defvar:                                Variables Commands.
+* defvr:                                 Variables Commands.
+* dfn:                                   dfn.
+* dircategory:                           Installing Dir Entries.
+* direntry:                              Installing Dir Entries.
+* display:                               display.
+* dmn:                                   dmn.
+* dotaccent:                             Inserting Accents.
+* dotless:                               Inserting Accents.
+* dots:                                  dots.
+* email:                                 email.
+* emph:                                  emph & strong.
+* end <1>:                               Introducing Lists.
+* end:                                   Quotations and Examples.
+* end titlepage:                         end titlepage.
+* enumerate:                             enumerate.
+* evenfooting:                           Custom Headings.
+* evenheading:                           Custom Headings.
+* everyfooting:                          Custom Headings.
+* everyheading:                          Custom Headings.
+* example:                               example.
+* exclamdown:                            Inserting Accents.
+* exdent:                                exdent.
+* file:                                  file.
+* filll:                                 Copyright & Permissions.
+* finalout:                              Overfull hboxes.
+* findex:                                Indexing Commands.
+* flushleft:                             flushleft & flushright.
+* flushright:                            flushleft & flushright.
+* foobar:                                Optional Arguments.
+* footnote:                              Footnotes.
+* footnotestyle:                         Footnote Styles.
+* format:                                format.
+* forward-word:                          Def Cmd Template.
+* ftable:                                ftable vtable.
+* group:                                 group.
+* H:                                     Inserting Accents.
+* heading:                               unnumberedsec appendixsec heading.
+* headings:                              headings on off.
+* html:                                  Raw Formatter Commands.
+* hyphenation:                           - and hyphenation.
+* i (italic font):                       Fonts.
+* ifclear:                               ifset ifclear.
+* ifhtml <1>:                            Raw Formatter Commands.
+* ifhtml:                                Conditional Commands.
+* ifinfo:                                Conditional Commands.
+* ifnothtml:                             Conditional Not Commands.
+* ifnotinfo:                             Conditional Not Commands.
+* ifnottex:                              Conditional Not Commands.
+* ifset:                                 ifset ifclear.
+* iftex:                                 Conditional Commands.
+* ignore:                                Comments.
+* image:                                 Images.
+* include:                               Using Include Files.
+* Info-validate:                         Running Info-Validate.
+* inforef:                               inforef.
+* input (TeX command):                   Minimum.
+* isearch-backward:                      deffnx.
+* isearch-forward:                       deffnx.
+* item <1>:                              Multitable Rows.
+* item <2>:                              table.
+* item:                                  itemize.
+* itemize:                               itemize.
+* itemx:                                 itemx.
+* kbd:                                   kbd.
+* kbdinputstyle:                         kbd.
+* key:                                   key.
+* kindex:                                Indexing Commands.
+* L:                                     Inserting Accents.
+* l:                                     Inserting Accents.
+* lisp:                                  Lisp Example.
+* lowersections:                         Raise/lower sections.
+* macro:                                 Defining Macros.
+* mag (TeX command):                     Cropmarks and Magnification.
+* majorheading:                          majorheading & chapheading.
+* makeinfo-buffer:                       makeinfo in Emacs.
+* makeinfo-kill-job:                     makeinfo in Emacs.
+* makeinfo-recenter-output-buffer:       makeinfo in Emacs.
+* makeinfo-region:                       makeinfo in Emacs.
+* math:                                  math.
+* menu:                                  Menus.
+* minus:                                 minus.
+* multitable:                            Multi-column Tables.
+* need:                                  need.
+* next-error:                            makeinfo in Emacs.
+* noindent:                              noindent.
+* O:                                     Inserting Accents.
+* o:                                     Inserting Accents.
+* occur:                                 Using occur.
+* occur-mode-goto-occurrence:            Showing the Structure.
+* oddfooting:                            Custom Headings.
+* oddheading:                            Custom Headings.
+* OE:                                    Inserting Accents.
+* oe:                                    Inserting Accents.
+* page:                                  page.
+* paragraphindent:                       paragraphindent.
+* pindex:                                Indexing Commands.
+* pounds:                                pounds.
+* printindex:                            Printing Indices & Menus.
+* pxref:                                 pxref.
+* questiondown:                          Inserting Accents.
+* quotation:                             quotation.
+* r (Roman font):                        Fonts.
+* raisesections:                         Raise/lower sections.
+* ref:                                   ref.
+* refill:                                Refilling Paragraphs.
+* ringaccent:                            Inserting Accents.
+* samp:                                  samp.
+* sc (small caps font):                  Smallcaps.
+* section:                               section.
+* set:                                   ifset ifclear.
+* setchapternewpage:                     setchapternewpage.
+* setfilename:                           setfilename.
+* settitle:                              settitle.
+* shortcontents:                         Contents.
+* shorttitlepage:                        titlepage.
+* smallbook:                             smallbook.
+* smallexample:                          smallexample & smalllisp.
+* smalllisp:                             smallexample & smalllisp.
+* sp (line spacing):                     sp.
+* sp (titlepage line spacing):           titlefont center sp.
+* ss:                                    Inserting Accents.
+* strong:                                emph & strong.
+* subheading:                            unnumberedsubsec appendixsubsec subheading.
+* subsection:                            subsection.
+* subsubheading:                         subsubsection.
+* subsubsection:                         subsubsection.
+* subtitle:                              title subtitle author.
+* summarycontents:                       Contents.
+* syncodeindex:                          syncodeindex.
+* synindex:                              synindex.
+* t (typewriter font):                   Fonts.
+* table:                                 Two-column Tables.
+* tex:                                   Raw Formatter Commands.
+* tex (command):                         tex.
+* texinfo-all-menus-update:              Updating Commands.
+* texinfo-every-node-update:             Updating Commands.
+* texinfo-format-buffer <1>:             texinfo-format commands.
+* texinfo-format-buffer:                 Info Formatting.
+* texinfo-format-region <1>:             texinfo-format commands.
+* texinfo-format-region:                 Info Formatting.
+* texinfo-indent-menu-description:       Other Updating Commands.
+* texinfo-insert-@code:                  Inserting.
+* texinfo-insert-@dfn:                   Inserting.
+* texinfo-insert-@end:                   Inserting.
+* texinfo-insert-@example:               Inserting.
+* texinfo-insert-@item:                  Inserting.
+* texinfo-insert-@kbd:                   Inserting.
+* texinfo-insert-@node:                  Inserting.
+* texinfo-insert-@noindent:              Inserting.
+* texinfo-insert-@samp:                  Inserting.
+* texinfo-insert-@table:                 Inserting.
+* texinfo-insert-@var:                   Inserting.
+* texinfo-insert-braces:                 Inserting.
+* texinfo-insert-node-lines:             Other Updating Commands.
+* texinfo-make-menu:                     Updating Commands.
+* texinfo-master-menu:                   Updating Commands.
+* texinfo-multiple-files-update:         texinfo-multiple-files-update.
+* texinfo-multiple-files-update (in brief): Other Updating Commands.
+* texinfo-sequential-node-update:        Other Updating Commands.
+* texinfo-show-structure <1>:            Using texinfo-show-structure.
+* texinfo-show-structure:                Showing the Structure.
+* texinfo-start-menu-description:        Inserting.
+* texinfo-tex-buffer:                    Printing.
+* texinfo-tex-print:                     Printing.
+* texinfo-tex-region:                    Printing.
+* texinfo-update-node:                   Updating Commands.
+* thischapter:                           Custom Headings.
+* thischaptername:                       Custom Headings.
+* thisfile:                              Custom Headings.
+* thispage:                              Custom Headings.
+* thistitle:                             Custom Headings.
+* tieaccent:                             Inserting Accents.
+* tindex:                                Indexing Commands.
+* title:                                 title subtitle author.
+* titlefont:                             titlefont center sp.
+* titlepage:                             titlepage.
+* today:                                 Custom Headings.
+* top (@-command):                       makeinfo top command.
+* u:                                     Inserting Accents.
+* ubaraccent:                            Inserting Accents.
+* udotaccent:                            Inserting Accents.
+* unmacro:                               Defining Macros.
+* unnumbered:                            unnumbered & appendix.
+* unnumberedsec:                         unnumberedsec appendixsec heading.
+* unnumberedsubsec:                      unnumberedsubsec appendixsubsec subheading.
+* unnumberedsubsubsec:                   subsubsection.
+* up-list:                               Inserting.
+* uref:                                  uref.
+* url:                                   url.
+* v:                                     Inserting Accents.
+* value:                                 value.
+* var:                                   var.
+* vindex:                                Indexing Commands.
+* vskip:                                 Copyright & Permissions.
+* vtable:                                ftable vtable.
+* w (prevent line break):                w.
+* xref:                                  xref.
+* { (single {):                          Inserting Braces.
+* } (single }):                          Inserting Braces.
+* ~:                                     Inserting Accents.

 
 

-  Even if you are printing in a single-sided style, TeX looks for an
-`@settitle' command line, in case you include the manual title in the
-heading.
+\1f
+File: texinfo.info,  Node: Concept Index,  Prev: Command and Variable Index,  Up: Top

 
 

-  The `@settitle' command should precede everything that generates
-actual output in TeX.
+Concept Index
+*************

 
 

-  Although the title in the `@settitle' command is usually the same as
-the title on the title page, it does not affect the title as it appears
-on the title page.  Thus, the two do not need not match exactly;  and
-the title in the `@settitle' command can be a shortened or expanded
-version of the title as it appears on the title page. (*Note
-`@titlepage': titlepage.)
+* Menu:

 
 

-  TeX prints page headings only for that text that comes after the
-`@end titlepage' command in the Texinfo file, or that comes after an
-`@headings' command that turns on headings.  (*Note The `@headings'
-Command: headings on off, for more information.)
+* !:                                     Inserting Accents.
+* (dir) as Up node of Top node:          First Node.
+* --delete:                              Invoking install-info.
+* --dir-file=NAME:                       Invoking install-info.
+* --entry=TEXT:                          Invoking install-info.
+* --error-limit=LIMIT:                   makeinfo options.
+* --fill-column=WIDTH:                   makeinfo options.
+* --footnote-style=STYLE:                makeinfo options.
+* --force:                               makeinfo options.
+* --help <1>:                            Invoking install-info.
+* --help:                                makeinfo options.
+* --info-dir=DIR:                        Invoking install-info.
+* --info-file=FILE:                      Invoking install-info.
+* --item=TEXT:                           Invoking install-info.
+* --no-headers:                          makeinfo options.
+* --no-number-footnotes:                 makeinfo options.
+* --no-pointer-validate:                 makeinfo options.
+* --no-split:                            makeinfo options.
+* --no-validate:                         makeinfo options.
+* --no-warn:                             makeinfo options.
+* --output=FILE:                         makeinfo options.
+* --paragraph-indent=INDENT:             makeinfo options.
+* --quiet:                               Invoking install-info.
+* --reference-limit=LIMIT:               makeinfo options.
+* --remove:                              Invoking install-info.
+* --section=SEC:                         Invoking install-info.
+* --verbose:                             makeinfo options.
+* --version <1>:                         Invoking install-info.
+* --version:                             makeinfo options.
+* -D VAR:                                makeinfo options.
+* -I DIR:                                makeinfo options.
+* -o FILE:                               makeinfo options.
+* -P DIR:                                makeinfo options.
+* .cshrc initialization file:            Preparing for TeX.
+* .profile initialization file:          Preparing for TeX.
+* /L:                                    Inserting Accents.
+* /l:                                    Inserting Accents.
+* /O:                                    Inserting Accents.
+* /o:                                    Inserting Accents.
+* ?:                                     Inserting Accents.
+* @-command in nodename:                 Node Line Requirements.
+* @-command list:                        Command List.
+* @-command syntax:                      Command Syntax.
+* @-commands:                            Formatting Commands.
+* @include file sample:                  Sample Include File.
+* @menu parts:                           Menu Parts.
+* @node line writing:                    Writing a Node.
+* A4 paper, printing on:                 A4 Paper.
+* AA:                                    Inserting Accents.
+* aa:                                    Inserting Accents.
+* Abbreviations for keys:                key.
+* Accents, inserting:                    Inserting Accents.
+* Acute accent:                          Inserting Accents.
+* Adding a new info file:                New Info File.
+* AE:                                    Inserting Accents.
+* ae:                                    Inserting Accents.
+* Alphabetical @-command list:           Command List.
+* Another Info directory:                Other Info Directories.
+* Apostrophe in nodename:                Node Line Requirements.
+* Arguments, repeated and optional:      Optional Arguments.
+* Aspect ratio of images:                Images.
+* Automatic pointer creation with makeinfo: makeinfo Pointer Creation.
+* Automatically insert nodes, menus:     Updating Nodes and Menus.
+* Backslash, and macros:                 Invoking Macros.
+* Badly referenced nodes:                Running Info-Validate.
+* Batch formatting for Info:             Batch Formatting.
+* Beginning a Texinfo file:              Beginning a File.
+* Beginning line of a Texinfo file:      First Line.
+* Berry, Karl:                           Acknowledgements.
+* Big points:                            Images.
+* Black rectangle in hardcopy:           Overfull hboxes.
+* Blank lines:                           sp.
+* Body of a macro:                       Defining Macros.
+* Book characteristics, printed:         Printed Books.
+* Book, printing small:                  smallbook.
+* Box with rounded corners:              cartouche.
+* Braces and argument syntax:            Command Syntax.
+* Braces, inserting:                     Braces Atsigns.
+* Braces, when to use:                   Formatting Commands.
+* Breaks in a line:                      Line Breaks.
+* Breve accent:                          Inserting Accents.
+* Buffer formatting and printing:        Printing.
+* Bullets, inserting:                    Dots Bullets.
+* Case in nodename:                      Node Line Requirements.
+* Catching errors with Info formatting:  Debugging with Info.
+* Catching errors with TeX formatting:   Debugging with TeX.
+* Catching mistakes:                     Catching Mistakes.
+* Cedilla accent:                        Inserting Accents.
+* Centimeters:                           Images.
+* Chapter structuring:                   Structuring.
+* Characteristics, printed books or manuals: Printed Books.
+* Chassell, Robert J.:                   Acknowledgements.
+* Check accent:                          Inserting Accents.
+* Checking for badly referenced nodes:   Running Info-Validate.
+* Ciceros:                               Images.
+* Circumflex accent:                     Inserting Accents.
+* code, arg to @kbdinputstyle:           kbd.
+* colon last in INFOPATH:                Other Info Directories.
+* Column widths, defining for multitables: Multitable Column Widths.
+* Combining indices:                     Combining Indices.
+* Comma in nodename:                     Node Line Requirements.
+* Command definitions:                   Sample Function Definition.
+* Commands to insert special characters: Braces Atsigns.
+* Commands using raw HTML:               Raw Formatter Commands.
+* Commands using raw TeX:                Raw Formatter Commands.
+* Commands, inserting them:              Inserting.
+* Comments:                              Comments.
+* Compile command for formatting:        Compile-Command.
+* Conditionally visible text:            Conditionals.
+* Conditions for copying Texinfo:        Copying.
+* Contents, Table of:                    Contents.
+* Contents-like outline of file structure: Showing the Structure.
+* Conventions for writing definitions:   Def Cmd Conventions.
+* Conventions, syntactic:                Conventions.
+* Copying conditions:                    Copying.
+* Copying permissions:                   Sample Permissions.
+* Copying software:                      Software Copying Permissions.
+* Copyright page:                        Copyright & Permissions.
+* Correcting mistakes:                   Catching Mistakes.
+* Create nodes, menus automatically:     Updating Nodes and Menus.
+* Creating an Info file:                 Create an Info File.
+* Creating an unsplit file:              Unsplit.
+* Creating index entries:                Indexing Commands.
+* Creating indices:                      Indices.
+* Creating pointers with makeinfo:       makeinfo Pointer Creation.
+* Cropmarks for printing:                Cropmarks and Magnification.
+* Cross reference parts:                 Cross Reference Parts.
+* Cross references:                      Cross References.
+* Cross references using @inforef:       inforef.
+* Cross references using @pxref:         pxref.
+* Cross references using @ref:           ref.
+* Cross references using @xref:          xref.
+* Customized highlighting:               Customized Highlighting.
+* Customizing of TeX for Texinfo:        Preparing for TeX.
+* Debugging the Texinfo structure:       Catching Mistakes.
+* Debugging with Info formatting:        Debugging with Info.
+* Debugging with TeX formatting:         Debugging with TeX.
+* Defining indexing entries:             Indexing Commands.
+* Defining macros:                       Defining Macros.
+* Defining new indices:                  New Indices.
+* Defining new Texinfo commands:         Macros.
+* Definition commands:                   Definition Commands.
+* Definition conventions:                Def Cmd Conventions.
+* Definition template:                   Def Cmd Template.
+* Definitions grouped together:          deffnx.
+* Description for menu, start:           Inserting.
+* Dido^t points:                         Images.
+* Different cross reference commands:    Cross Reference Commands.
+* Dimension formatting:                  dmn.
+* Dimensions and image sizes:            Images.
+* dir directory for Info installation:   Install an Info File.
+* dir file listing:                      New Info File.
+* dir, created by install-info:          Invoking install-info.
+* Display formatting:                    display.
+* distinct, arg to @kbdinputstyle:       kbd.
+* Distorting images:                     Images.
+* Distribution:                          Software Copying Permissions.
+* Dot accent:                            Inserting Accents.
+* Dotless i, j:                          Inserting Accents.
+* Dots, inserting <1>:                   dots.
+* Dots, inserting:                       Dots Bullets.
+* Double-colon menu entries:             Less Cluttered Menu Entry.
+* DVI file:                              Format with tex/texindex.
+* Ellipsis, inserting:                   Dots Bullets.
+* Emacs:                                 Texinfo Mode.
+* Emacs shell, format, print from:       Within Emacs.
+* Emphasizing text:                      Emphasis.
+* Emphasizing text, font for:            emph & strong.
+* Enclosure command for Info:            Customized Highlighting.
+* End node footnote style:               Footnote Styles.
+* End of header line:                    End of Header.
+* End titlepage starts headings:         end titlepage.
+* Ending a Sentence:                     Ending a Sentence.
+* Ending a Texinfo file:                 Ending a File.
+* Entries for an index:                  Indexing Commands.
+* Entries, making index:                 Index Entries.
+* Enumeration:                           enumerate.
+* epsf.tex:                              Images.
+* epsf.tex, installing:                  Preparing for TeX.
+* Equivalence, indicating it:            Equivalence.
+* Error message, indicating it:          Error Glyph.
+* Errors, parsing:                       makeinfo in Emacs.
+* Es-zet:                                Inserting Accents.
+* European A4 paper:                     A4 Paper.
+* Evaluation glyph:                      result.
+* Example for a small book:              smallexample & smalllisp.
+* Example menu:                          Menu Example.
+* example, arg to @kbdinputstyle:        kbd.
+* Examples, formatting them:             example.
+* Expansion, indicating it:              expansion.
+* File beginning:                        Beginning a File.
+* File ending:                           Ending a File.
+* File section structure, showing it:    Showing the Structure.
+* Filling paragraphs:                    Refilling Paragraphs.
+* Final output:                          Overfull hboxes.
+* Finding badly referenced nodes:        Running Info-Validate.
+* Fine-tuning, and hyphenation:          - and hyphenation.
+* First line of a Texinfo file:          First Line.
+* First node:                            First Node.
+* Floating accents, inserting:           Inserting Accents.
+* Fonts for indices:                     syncodeindex.
+* Fonts for printing, not for Info:      Fonts.
+* Footings:                              Headings.
+* Footnotes:                             Footnotes.
+* Format a dimension:                    dmn.
+* Format and print hardcopy:             Format/Print Hardcopy.
+* Format and print in Texinfo mode:      Texinfo Mode Printing.
+* Format with the compile command:       Compile-Command.
+* Format, print from Emacs shell:        Within Emacs.
+* Formats for images:                    Images.
+* Formatting a file for Info:            Create an Info File.
+* Formatting commands:                   Formatting Commands.
+* Formatting examples:                   example.
+* Formatting for Info:                   Info Formatting.
+* Formatting for printing:               Printing.
+* Formatting headings and footings:      Headings.
+* Formatting requirements:               Requirements Summary.
+* Formatting with tex and texindex:      Format with tex/texindex.
+* Frequently used commands, inserting:   Inserting.
+* Function definitions:                  Sample Function Definition.
+* General syntactic conventions:         Conventions.
+* Generating menus with indices:         Printing Indices & Menus.
+* German S:                              Inserting Accents.
+* Globbing:                              Format with tex/texindex.
+* Glyphs:                                Glyphs.
+* GNU Emacs:                             Texinfo Mode.
+* GNU Emacs shell, format, print from:   Within Emacs.
+* Going to other Info files' nodes:      Other Info Files.
+* Grave accent:                          Inserting Accents.
+* Group (hold text together vertically): group.
+* Grouping two definitions together:     deffnx.
+* Hardcopy, printing it:                 Format/Print Hardcopy.
+* hboxes, overfull:                      Overfull hboxes.
+* Header for Texinfo files:              Header.
+* Header of a Texinfo file:              First Line.
+* Headings:                              Headings.
+* Headings, page, begin to appear:       end titlepage.
+* Height of images:                      Images.
+* Highlighting text:                     Indicating.
+* Highlighting, customized:              Customized Highlighting.
+* Hints:                                 Tips.
+* Holding text together vertically:      group.
+* HTML commands, using ordinary:         Raw Formatter Commands.
+* Hungariam umlaut accent:               Inserting Accents.
+* Hyphenation, helping TeX do:           - and hyphenation.
+* Hyphenation, preventing:               w.
+* i:                                     Inserting Accents.
+* If text conditionally visible:         Conditionals.
+* ifinfo permissions:                    ifinfo Permissions.
+* Ignored before @setfilename:           setfilename.
+* Ignored text:                          Comments.
+* Image formats:                         Images.
+* Images, inserting:                     Images.
+* Inches:                                Images.
+* Include file requirements:             Include File Requirements.
+* Include file sample:                   Sample Include File.
+* Include files:                         Include Files.
+* Include files, and section levels:     Raise/lower sections.
+* Indentation undoing:                   exdent.
+* Indenting paragraphs:                  paragraphindent.
+* Index entries:                         Indexing Commands.
+* Index entries, making:                 Index Entries.
+* Index entry writing:                   Indexing Commands.
+* Index font types:                      Indexing Commands.
+* Indexing commands, predefined:         Indexing Commands.
+* Indexing table entries automatically:  ftable vtable.
+* Indicating commands, definitions, etc.: Indicating.
+* Indicating evaluation:                 result.
+* Indices:                               Indices.
+* Indices, combining them:               Combining Indices.
+* Indices, defining new:                 New Indices.
+* Indices, printing and menus:           Printing Indices & Menus.
+* Indices, sorting:                      Format/Print Hardcopy.
+* Indices, two letter names:             syncodeindex.
+* Indirect subfiles:                     Tag and Split Files.
+* Info batch formatting:                 Batch Formatting.
+* Info file installation:                Install an Info File.
+* Info file requires @setfilename:       setfilename.
+* Info file, listing new one:            New Info File.
+* Info file, splitting manually:         Splitting.
+* Info files:                            Info Files.
+* Info formatting:                       Info Formatting.
+* Info installed in another directory:   Other Info Directories.
+* Info validating a large file:          Using Info-validate.
+* Info, creating an on-line file:        Create an Info File.
+* Info-directory-list:                   Other Info Directories.
+* Info; other files' nodes:              Other Info Files.
+* INFOPATH:                              Other Info Directories.
+* Initialization file for TeX input:     Preparing for TeX.
+* Insert nodes, menus automatically:     Updating Nodes and Menus.
+* Inserting @, braces:                   Braces Atsigns.
+* Inserting accents:                     Inserting Accents.
+* Inserting dots <1>:                    dots.
+* Inserting dots:                        Dots Bullets.
+* Inserting ellipsis:                    Dots Bullets.
+* Inserting frequently used commands:    Inserting.
+* Inserting space:                       Inserting Space.
+* Inserting special characters and symbols: Insertions.
+* install-info:                          Invoking install-info.
+* Installing an Info file:               Install an Info File.
+* Installing Info in another directory:  Other Info Directories.
+* Introduction, as part of file:         Software Copying Permissions.
+* Invoking macros:                       Invoking Macros.
+* Itemization:                           itemize.
+* j:                                     Inserting Accents.
+* keyboard input:                        kbd.
+* Keys, recommended names:               key.
+* Knuth, Donald:                         Printed Books.
+* Larger or smaller pages:               Cropmarks and Magnification.
+* Less cluttered menu entry:             Less Cluttered Menu Entry.
+* License agreement:                     Software Copying Permissions.
+* Line breaks:                           Line Breaks.
+* Line breaks, preventing:               w.
+* Line length, column widths as fraction of: Multitable Column Widths.
+* Line spacing:                          sp.
+* Lisp example:                          Lisp Example.
+* Lisp example for a small book:         smallexample & smalllisp.
+* List of  @-commands:                   Command List.
+* Listing a new info file:               New Info File.
+* Lists and tables, making:              Lists and Tables.
+* Local variables:                       Compile-Command.
+* Location of menus:                     Menu Location.
+* Looking for badly referenced nodes:    Running Info-Validate.
+* lpr (DVI print command):               Print with lpr.
+* Macro definitions <1>:                 Defining Macros.
+* Macro definitions:                     Sample Function Definition.
+* Macro invocation:                      Invoking Macros.
+* Macron accent:                         Inserting Accents.
+* Macros:                                Macros.
+* Macros, undefining:                    Defining Macros.
+* Magnified printing:                    Cropmarks and Magnification.
+* mailto link:                           email.
+* makeinfo inside Emacs:                 makeinfo in Emacs.
+* makeinfo options:                      makeinfo options.
+* Making a printed manual:               Format/Print Hardcopy.
+* Making a tag table automatically:      Tag and Split Files.
+* Making a tag table manually:           Unsplit.
+* Making cross references:               Cross References.
+* Making line and page breaks:           Breaks.
+* Making lists and tables:               Lists and Tables.
+* Manual characteristics, printed:       Printed Books.
+* Marking text within a paragraph:       Marking Text.
+* Marking words and phrases:             Marking Text.
+* Master menu:                           The Top Node.
+* Master menu parts:                     Master Menu Parts.
+* Mathematical expressions <1>:          Raw Formatter Commands.
+* Mathematical expressions:              math.
+* Menu description, start:               Inserting.
+* Menu entries with two colons:          Less Cluttered Menu Entry.
+* Menu example:                          Menu Example.
+* Menu location:                         Menu Location.
+* Menu parts:                            Menu Parts.
+* Menu writing:                          Writing a Menu.
+* Menus:                                 Menus.
+* Menus generated with indices:          Printing Indices & Menus.
+* META key:                              key.
+* Meta-syntactic chars for arguments:    Optional Arguments.
+* Millimeters:                           Images.
+* Minimal requirements for formatting:   Requirements Summary.
+* Minimal Texinfo file (requirements):   Minimum.
+* Mistakes, catching:                    Catching Mistakes.
+* Mode, using Texinfo:                   Texinfo Mode.
+* Multiple spaces:                       Multiple Spaces.
+* Multitable column widths:              Multitable Column Widths.
+* Multitable rows:                       Multitable Rows.
+* Must have in Texinfo file:             Minimum.
+* Mutually recursive macros:             Defining Macros.
+* Names for indices:                     syncodeindex.
+* Names of index files:                  Format with tex/texindex.
+* Names recommended for keys:            key.
+* Naming a `Top' Node in references:     Top Node Naming.
+* Need space at page bottom:             need.
+* New index defining:                    New Indices.
+* New info file, listing it in dir file: New Info File.
+* New Texinfo commands, defining:        Macros.
+* Node line requirements:                Node Line Requirements.
+* Node line writing:                     Writing a Node.
+* Node, `Top':                           The Top Node.
+* Node, defined:                         node.
+* Nodename must be unique:               Node Line Requirements.
+* Nodename, cannot contain:              Node Line Requirements.
+* Nodes for menus are short:             Menu Location.
+* Nodes in other Info files:             Other Info Files.
+* Nodes, catching mistakes:              Catching Mistakes.
+* Nodes, checking for badly referenced:  Running Info-Validate.
+* Not ending a sentence:                 Not Ending a Sentence.
+* Obtaining TeX:                         Obtaining TeX.
+* Occurrences, listing with @occur:      Using occur.
+* OE:                                    Inserting Accents.
+* oe:                                    Inserting Accents.
+* Optional and repeated arguments:       Optional Arguments.
+* Options for makeinfo:                  makeinfo options.
+* Ordinary HTML commands, using:         Raw Formatter Commands.
+* Ordinary TeX commands, using:          Raw Formatter Commands.
+* Other Info files' nodes:               Other Info Files.
+* Outline of file structure, showing it: Showing the Structure.
+* Overfull hboxes:                       Overfull hboxes.
+* Overview of Texinfo:                   Overview.
+* Page breaks:                           page.
+* Page delimiter in Texinfo mode:        Showing the Structure.
+* Page headings:                         Headings.
+* Page numbering:                        Headings.
+* Page sizes for books:                  smallbook.
+* page-delimiter:                        Showing the Structure.
+* Pages, starting odd:                   setchapternewpage.
+* Paper size, European A4:               A4 Paper.
+* Paragraph indentation:                 paragraphindent.
+* Paragraph, marking text within:        Marking Text.
+* Parsing errors:                        makeinfo in Emacs.
+* Part of file formatting and printing:  Printing.
+* Parts of a cross reference:            Cross Reference Parts.
+* Parts of a master menu:                Master Menu Parts.
+* Parts of a menu:                       Menu Parts.
+* Periods, inserting:                    Not Ending a Sentence.
+* Permissions:                           Sample Permissions.
+* Permissions, printed:                  Copyright & Permissions.
+* Picas:                                 Images.
+* Pictures, inserting:                   Images.
+* Pinard, Franc,ois:                     Acknowledgements.
+* plain TeX:                             Raw Formatter Commands.
+* Point, indicating it in a buffer:      Point Glyph.
+* Pointer creation with makeinfo:        makeinfo Pointer Creation.
+* Pointer validation with makeinfo:      Pointer Validation.
+* Points (dimension):                    Images.
+* Predefined indexing commands:          Indexing Commands.
+* Predefined names for indices:          syncodeindex.
+* Preparing to use TeX:                  Preparing for TeX.
+* Preventing line and page breaks:       Breaks.
+* Previous node of Top node:             First Node.
+* Print and format in Texinfo mode:      Texinfo Mode Printing.
+* Print, format from Emacs shell:        Within Emacs.
+* Printed book and manual characteristics: Printed Books.
+* Printed output, indicating it:         Print Glyph.
+* Printed permissions:                   Copyright & Permissions.
+* Printing a region or buffer:           Printing.
+* Printing an index:                     Printing Indices & Menus.
+* Printing cropmarks:                    Cropmarks and Magnification.
+* Problems, catching:                    Catching Mistakes.
+* Prototype row, column widths defined by: Multitable Column Widths.
+* Quotations:                            quotation.
+* Raising and lowering sections:         Raise/lower sections.
+* Raw formatter commands:                Raw Formatter Commands.
+* Recommended names for keys:            key.
+* Rectangle, ugly, black in hardcopy:    Overfull hboxes.
+* Recursion, mutual:                     Defining Macros.
+* References:                            Cross References.
+* References using @inforef:             inforef.
+* References using @pxref:               pxref.
+* References using @ref:                 ref.
+* References using @xref:                xref.
+* Referring to other Info files:         Other Info Files.
+* Refilling paragraphs:                  Refilling Paragraphs.
+* Region formatting and printing:        Printing.
+* Region printing in Texinfo mode:       Texinfo Mode Printing.
+* Repeated and optional arguments:       Optional Arguments.
+* Required in Texinfo file:              Minimum.
+* Requirements for formatting:           Requirements Summary.
+* Requirements for include files:        Include File Requirements.
+* Requirements for updating commands:    Updating Requirements.
+* Result of an expression:               result.
+* ridt.eps:                              Images.
+* Ring accent:                           Inserting Accents.
+* Rows, of a multitable:                 Multitable Rows.
+* Running an Info formatter:             Info Formatting.
+* Running Info-validate:                 Using Info-validate.
+* Running makeinfo in Emacs:             makeinfo in Emacs.
+* Sample @include file:                  Sample Include File.
+* Sample function definition:            Sample Function Definition.
+* Sample Texinfo file:                   Short Sample.
+* Sample Texinfo file, no comments:      Sample Texinfo File.
+* Scaled points:                         Images.
+* Section structure of a file, showing it: Showing the Structure.
+* Sections, raising and lowering:        Raise/lower sections.
+* Sentence ending punctuation:           Ending a Sentence.
+* Sentence non-ending punctuation:       Not Ending a Sentence.
+* Separate footnote style:               Footnote Styles.
+* Sharp S:                               Inserting Accents.
+* Shell formatting with tex and texindex: Format with tex/texindex.
+* Shell, format, print from:             Within Emacs.
+* Shell, running makeinfo in:            makeinfo in Emacs.
+* Short nodes for menus:                 Menu Location.
+* Showing the section structure of a file: Showing the Structure.
+* Showing the structure of a file:       Using texinfo-show-structure.
+* Site-wide Texinfo configuration file:  Preparing for TeX.
+* Size of printed book:                  smallbook.
+* slanted typewriter font, for @kbd:     kbd.
+* Small book example:                    smallexample & smalllisp.
+* Small book size:                       smallbook.
+* Small caps font:                       Smallcaps.
+* Software copying permissions:          Software Copying Permissions.
+* Sorting indices:                       Format/Print Hardcopy.
+* Spaces (blank lines):                  sp.
+* Spacing, inserting:                    Inserting Space.
+* Special characters, commands to insert: Braces Atsigns.
+* Special insertions:                    Insertions.
+* Special typesetting commands:          Dots Bullets.
+* Specifying index entries:              Indexing Commands.
+* Splitting an Info file manually:       Splitting.
+* ss:                                    Inserting Accents.
+* Stallman, Richard M.:                  Acknowledgements.
+* Start of header line:                  Start of Header.
+* Starting chapters:                     setchapternewpage.
+* Structure of a file, showing it:       Showing the Structure.
+* Structure, catching mistakes in:       Catching Mistakes.
+* Structuring of chapters:               Structuring.
+* Subsection-like commands:              unnumberedsubsec appendixsubsec subheading.
+* Subsub commands:                       subsubsection.
+* Syntactic conventions:                 Conventions.
+* Syntax, optional & repeated arguments: Optional Arguments.
+* tab:                                   Multitable Rows.
+* Table of contents:                     Contents.
+* Tables and lists, making:              Lists and Tables.
+* Tables with indexes:                   ftable vtable.
+* Tables, making multi-column:           Multi-column Tables.
+* Tables, making two-column:             Two-column Tables.
+* Tabs; don't use!:                      Conventions.
+* Tag table, making automatically:       Tag and Split Files.
+* Tag table, making manually:            Unsplit.
+* Template for a definition:             Def Cmd Template.
+* TeX commands, using ordinary:          Raw Formatter Commands.
+* TeX index sorting:                     Format/Print Hardcopy.
+* TeX input initialization:              Preparing for TeX.
+* TeX, how to obtain:                    Obtaining TeX.
+* texi2dvi:                              Format with tex/texindex.
+* texi2dvi (shell script):               Format with texi2dvi.
+* texindex <1>:                          Format with tex/texindex.
+* texindex:                              Format/Print Hardcopy.
+* Texinfo commands, defining new:        Macros.
+* Texinfo file beginning:                Beginning a File.
+* Texinfo file ending:                   Ending a File.
+* Texinfo file header:                   Header.
+* Texinfo file minimum:                  Minimum.
+* Texinfo file section structure, showing it: Showing the Structure.
+* Texinfo mode:                          Texinfo Mode.
+* Texinfo overview:                      Overview.
+* Texinfo printed book characteristics:  Printed Books.
+* texinfo.cnf <1>:                       A4 Paper.
+* texinfo.cnf:                           setfilename.
+* texinfo.cnf installation:              Preparing for TeX.
+* texinfo.tex, installing:               Preparing for TeX.
+* TEXINPUTS:                             Preparing for TeX.
+* TEXINPUTS environment variable:        Preparing for TeX.
+* Text, conditionally visible:           Conditionals.
+* Thin space between number, dimension:  dmn.
+* Tie-after accent:                      Inserting Accents.
+* Tilde accent:                          Inserting Accents.
+* Tips:                                  Tips.
+* Title page:                            titlepage.
+* Titlepage end starts headings:         end titlepage.
+* Titlepage permissions:                 Titlepage Permissions.
+* Top node:                              The Top Node.
+* Top node is first:                     First Node.
+* Top node naming for references:        Top Node Naming.
+* Top node summary:                      Top Node Summary.
+* Tree structuring:                      Tree Structuring.
+* Two `First' Lines for @deffn:          deffnx.
+* Two letter names for indices:          syncodeindex.
+* Two named items for @table:            itemx.
+* Two part menu entry:                   Less Cluttered Menu Entry.
+* Typesetting commands for dots, etc.:   Dots Bullets.
+* Umlaut accent:                         Inserting Accents.
+* Uncluttered menu entry:                Less Cluttered Menu Entry.
+* Undefining macros:                     Defining Macros.
+* Underbar accent:                       Inserting Accents.
+* Underdot accent:                       Inserting Accents.
+* Uniform resource locator, indicating:  url.
+* Uniform resource locator, referring to: uref.
+* Unique nodename requirement:           Node Line Requirements.
+* Unprocessed text:                      Comments.
+* Unsplit file creation:                 Unsplit.
+* Up node of Top node:                   First Node.
+* Updating nodes and menus:              Updating Nodes and Menus.
+* Updating requirements:                 Updating Requirements.
+* URL, indicating:                       url.
+* URL, referring to:                     uref.
+* Usage tips:                            Tips.
+* user input:                            kbd.
+* User options, marking:                 Variables Commands.
+* User-defined Texinfo commands:         Macros.
+* Validating a large file:               Using Info-validate.
+* Validation of pointers:                Pointer Validation.
+* Value of an expression, indicating:    result.
+* version number, finding:               Invoking install-info.
+* Vertical whitespace (vskip):           Copyright & Permissions.
+* Vertically holding text together:      group.
+* Visibility of conditional text:        Conditionals.
+* Weisshaus, Melissa:                    Acknowledgements.
+* Whitespace, inserting <1>:             Multiple Spaces.
+* Whitespace, inserting:                 Inserting Space.
+* Width of images:                       Images.
+* Widths, defining multitable column:    Multitable Column Widths.
+* Wildcards:                             Format with tex/texindex.
+* Words and phrases, marking them:       Marking Text.
+* Writing a menu:                        Writing a Menu.
+* Writing an @node line:                 Writing a Node.
+* Writing index entries:                 Indexing Commands.
+* Zuhn, David D.:                        Acknowledgements.

 
 

-  You may, if you wish, create your own, customized headings and
-footings.  *Note Page Headings: Headings, for a detailed discussion of
-this process.

 
 

diff --git a/info/widget.info b/info/widget.info
index 425627c..9190fc7 100644 (file)
--- a/info/widget.info
+++ b/info/widget.info
@@ -1,4 +1,4 @@
-This is ../info/widget.info, produced by makeinfo version 4.0 from
+This is ../info/widget.info, produced by makeinfo version 4.6 from

 widget.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 widget.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -26,6 +26,7 @@ The Emacs Widget Library
 * Widget Minor Mode::
 * Utilities::
 * Widget Wishlist::
 * Widget Minor Mode::
 * Utilities::
 * Widget Wishlist::

+* Widget Internals::

 
 \1f
 File: widget.info,  Node: Introduction,  Next: User Interface,  Prev: Top,  Up: Top
 
 \1f
 File: widget.info,  Node: Introduction,  Next: User Interface,  Prev: Top,  Up: Top

@@ -33,8 +34,8 @@ File: widget.info,  Node: Introduction,  Next: User Interface,  Prev: Top,  Up:
 Introduction
 ============
 
 Introduction
 ============
 

-   Most graphical user interface toolkits, such as Motif and XView,
-provide a number of standard user interface controls (sometimes known as
+Most graphical user interface toolkits, such as Motif and XView, provide
+a number of standard user interface controls (sometimes known as

 `widgets' or `gadgets').  Emacs doesn't really support anything like
 this, except for an incredible powerful text "widget".  On the other
 hand, Emacs does provide the necessary primitives to implement many
 `widgets' or `gadgets').  Emacs doesn't really support anything like
 this, except for an incredible powerful text "widget".  On the other
 hand, Emacs does provide the necessary primitives to implement many

@@ -68,9 +69,8 @@ this task.
      and `radio-button-choice' widgets.
 
 `choice-item'
      and `radio-button-choice' widgets.
 
 `choice-item'

-     An button item only intended for use in choices.  When invoked,
-     the user will be asked to select another option from the choice
-     widget.
+     A button item only intended for use in choices.  When invoked, the
+     user will be asked to select another option from the choice widget.

 
 `toggle'
      A simple `on'/`off' switch.
 
 `toggle'
      A simple `on'/`off' switch.

@@ -118,7 +118,7 @@ create any widgets, the code has been split in two files:
 
 `widget.el'
      This will declare the user variables, define the function
 
 `widget.el'
      This will declare the user variables, define the function

-     `widget-define', and autoload the function `widget-create'.
+     `define-widget', and autoload the function `widget-create'.

 
 `wid-edit.el'
      Everything else is here, there is no reason to load it explicitly,
 
 `wid-edit.el'
      Everything else is here, there is no reason to load it explicitly,

@@ -130,10 +130,11 @@ File: widget.info,  Node: User Interface,  Next: Programming Example,  Prev: Int
 User Interface
 ==============
 
 User Interface
 ==============
 

-   A form consist of read only text for documentation and some fields,
-where each the fields contain two parts, as tag and a value.  The tags
-are used to identify the fields, so the documentation can refer to the
-foo field, meaning the field tagged with `Foo'. Here is an example form:
+A form consists of read only text for documentation and some fields,
+where each of the fields contains two parts, a tag and a value.  The
+tags are used to identify the fields, so the documentation can refer to
+the foo field, meaning the field tagged with `Foo'. Here is an example
+form:

 
      Here is some documentation.
      
 
      Here is some documentation.
      

@@ -173,12 +174,12 @@ activating the buttons.
 Editable Text Fields
 --------------------
 
 Editable Text Fields
 --------------------
 

-   In the example, the value for the `Name' is most likely displayed in
-an editable text field, and so are values for each of the members of
-the `Numbers' list.  All the normal Emacs editing operations are
-available for editing these fields.  The only restriction is that each
-change you make must be contained within a single editable text field.
-For example, capitalizing all text from the middle of one field to the
+In the example, the value for the `Name' is most likely displayed in an
+editable text field, and so are values for each of the members of the
+`Numbers' list.  All the normal Emacs editing operations are available
+for editing these fields.  The only restriction is that each change you
+make must be contained within a single editable text field.  For
+example, capitalizing all text from the middle of one field to the

 middle of another field is prohibited.
 
    Editing text fields are created by the `editable-field' widget.
 middle of another field is prohibited.
 
    Editing text fields are created by the `editable-field' widget.

@@ -192,8 +193,8 @@ face, making them easy to find.
 Buttons
 -------
 
 Buttons
 -------
 

-   Some portions of the buffer have an associated "action", which can
-be "invoked" by a standard key or mouse command.  These portions are
+Some portions of the buffer have an associated "action", which can be
+"invoked" by a standard key or mouse command.  These portions are

 called "buttons".  The default commands for activating a button are:
 
 `<RET>'
 called "buttons".  The default commands for activating a button are:
 
 `<RET>'

@@ -219,7 +220,7 @@ _The Option Field Tags._
      widget.  In the example, `Choose' is an option field tag.
 
 _The `[INS]' and `[DEL]' buttons._
      widget.  In the example, `Choose' is an option field tag.
 
 _The `[INS]' and `[DEL]' buttons._

-     Activating these will insert or delete elements from a editable
+     Activating these will insert or delete elements from an editable

      list.  The list is created by the `editable-list' widget.
 
 _Embedded Buttons._
      list.  The list is created by the `editable-list' widget.
 
 _Embedded Buttons._

@@ -255,7 +256,7 @@ _The `[Apply Form]' `[Reset Form]' buttons._
 Navigation
 ----------
 
 Navigation
 ----------
 

-   You can use all the normal Emacs commands to move around in a form
+You can use all the normal Emacs commands to move around in a form

 buffer, plus you will have these additional commands:
 
 `<TAB>'
 buffer, plus you will have these additional commands:
 
 `<TAB>'

@@ -272,7 +273,7 @@ File: widget.info,  Node: Programming Example,  Next: Setting Up the Buffer,  Pr
 Programming Example
 ===================
 
 Programming Example
 ===================
 

-   Here is the code to implement the user interface example (see *Note
+Here is the code to implement the user interface example (see *Note

 User Interface::).
 
      (require 'widget)
 User Interface::).
 
      (require 'widget)

@@ -364,7 +365,7 @@ File: widget.info,  Node: Setting Up the Buffer,  Next: Basic Types,  Prev: Prog
 Setting Up the Buffer
 =====================
 
 Setting Up the Buffer
 =====================
 

-   Widgets are created with `widget-create', which returns a "widget"
+Widgets are created with `widget-create', which returns a "widget"

 object.  This object can be queried and manipulated by other widget
 functions, until it is deleted with `widget-delete'.  After the widgets
 have been created, `widget-setup' must be called to enable them.
 object.  This object can be queried and manipulated by other widget
 functions, until it is deleted with `widget-delete'.  After the widgets
 have been created, `widget-setup' must be called to enable them.

@@ -411,7 +412,7 @@ File: widget.info,  Node: Basic Types,  Next: Sexp Types,  Prev: Setting Up the
 Basic Types
 ===========
 
 Basic Types
 ===========
 

-   The syntax of a type specification is given below:
+The syntax of a type specification is given below:

 
      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
           |   NAME
 
      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
           |   NAME

@@ -521,7 +522,9 @@ widget specific way.
      changed.  The function is called with two or three arguments.  The
      first argument is the widget itself, the second argument is the
      widget that was changed, and the third argument is the event
      changed.  The function is called with two or three arguments.  The
      first argument is the widget itself, the second argument is the
      widget that was changed, and the third argument is the event

-     leading to the change, if any.
+     leading to the change, if any.  In editable fields, this includes
+     all insertions, deletions, _etc_.  To watch only for "final"
+     actions, redefine the `:action' callback.

 
 `:menu-tag'
      Tag used in the menu when the widget is used as an option in a
 
 `:menu-tag'
      Tag used in the menu when the widget is used as an option in a

@@ -566,7 +569,7 @@ widget specific way.
 
 `:parent'
      The parent of a nested widget (e.g. a `menu-choice' item or an
 
 `:parent'
      The parent of a nested widget (e.g. a `menu-choice' item or an

-     element of a `editable-list' widget).
+     element of an `editable-list' widget).

 
 `:sibling-args'
      This keyword is only used for members of a `radio-button-choice' or
 
 `:sibling-args'
      This keyword is only used for members of a `radio-button-choice' or

@@ -574,6 +577,7 @@ widget specific way.
      arguments, which will be used when creating the `radio-button' or
      `checkbox' associated with this item.
 
      arguments, which will be used when creating the `radio-button' or
      `checkbox' associated with this item.
 

+

  - User Option: widget-glyph-directory
      Directory where glyphs are found.  Widget will look here for a
      file with the same name as specified for the image, with either a
  - User Option: widget-glyph-directory
      Directory where glyphs are found.  Widget will look here for a
      file with the same name as specified for the image, with either a

@@ -607,7 +611,7 @@ File: widget.info,  Node: link,  Next: url-link,  Prev: Basic Types,  Up: Basic
 The `link' Widget
 -----------------
 
 The `link' Widget
 -----------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (link [KEYWORD ARGUMENT]...  [ VALUE ])
 
 
      TYPE ::= (link [KEYWORD ARGUMENT]...  [ VALUE ])
 

@@ -628,7 +632,7 @@ File: widget.info,  Node: url-link,  Next: info-link,  Prev: link,  Up: Basic Ty
 The `url-link' Widget
 ---------------------
 
 The `url-link' Widget
 ---------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (url-link [KEYWORD ARGUMENT]...  URL)
 
 
      TYPE ::= (url-link [KEYWORD ARGUMENT]...  URL)
 

@@ -641,7 +645,7 @@ File: widget.info,  Node: info-link,  Next: push-button,  Prev: url-link,  Up: B
 The `info-link' Widget
 ----------------------
 
 The `info-link' Widget
 ----------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (info-link [KEYWORD ARGUMENT]...  ADDRESS)
 
 
      TYPE ::= (info-link [KEYWORD ARGUMENT]...  ADDRESS)
 

@@ -654,7 +658,7 @@ File: widget.info,  Node: push-button,  Next: editable-field,  Prev: info-link,
 The `push-button' Widget
 ------------------------
 
 The `push-button' Widget
 ------------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (push-button [KEYWORD ARGUMENT]...  [ VALUE ])
 
 
      TYPE ::= (push-button [KEYWORD ARGUMENT]...  [ VALUE ])
 

@@ -675,7 +679,7 @@ File: widget.info,  Node: editable-field,  Next: text,  Prev: push-button,  Up:
 The `editable-field' Widget
 ---------------------------
 
 The `editable-field' Widget
 ---------------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
 
 
      TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
 

@@ -717,7 +721,7 @@ File: widget.info,  Node: text,  Next: menu-choice,  Prev: editable-field,  Up:
 The `text' Widget
 -----------------
 
 The `text' Widget
 -----------------
 

-   This is just like `editable-field', but intended for multiline text
+This is just like `editable-field', but intended for multiline text

 fields.  The default `:keymap' is `widget-text-keymap', which does not
 rebind the return key.
 
 fields.  The default `:keymap' is `widget-text-keymap', which does not
 rebind the return key.
 

@@ -727,7 +731,7 @@ File: widget.info,  Node: menu-choice,  Next: radio-button-choice,  Prev: text,
 The `menu-choice' Widget
 ------------------------
 
 The `menu-choice' Widget
 ------------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
 
 
      TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
 

@@ -759,7 +763,7 @@ File: widget.info,  Node: radio-button-choice,  Next: item,  Prev: menu-choice,
 The `radio-button-choice' Widget
 --------------------------------
 
 The `radio-button-choice' Widget
 --------------------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]...  TYPE ... )
 
 
      TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]...  TYPE ... )
 

@@ -815,7 +819,7 @@ File: widget.info,  Node: item,  Next: choice-item,  Prev: radio-button-choice,
 The `item' Widget
 -----------------
 
 The `item' Widget
 -----------------
 

-   Syntax:
+Syntax:

 
      ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
 
 
      ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
 

@@ -829,7 +833,7 @@ File: widget.info,  Node: choice-item,  Next: toggle,  Prev: item,  Up: Basic Ty
 The `choice-item' Widget
 ------------------------
 
 The `choice-item' Widget
 ------------------------
 

-   Syntax:
+Syntax:

 
      ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
 
 
      ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
 

@@ -845,7 +849,7 @@ File: widget.info,  Node: toggle,  Next: checkbox,  Prev: choice-item,  Up: Basi
 The `toggle' Widget
 -------------------
 
 The `toggle' Widget
 -------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (toggle [KEYWORD ARGUMENT]...)
 
 
      TYPE ::= (toggle [KEYWORD ARGUMENT]...)
 

@@ -874,8 +878,8 @@ File: widget.info,  Node: checkbox,  Next: checklist,  Prev: toggle,  Up: Basic
 The `checkbox' Widget
 ---------------------
 
 The `checkbox' Widget
 ---------------------
 

-   The widget has two possible states, `selected' and `unselected',
-which corresponds to a `t' or `nil' value.
+The widget has two possible states, `selected' and `unselected', which
+corresponds to a `t' or `nil' value.

 
    Syntax:
 
 
    Syntax:
 

@@ -887,7 +891,7 @@ File: widget.info,  Node: checklist,  Next: editable-list,  Prev: checkbox,  Up:
 The `checklist' Widget
 ----------------------
 
 The `checklist' Widget
 ----------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (checklist [KEYWORD ARGUMENT]...  TYPE ... )
 
 
      TYPE ::= (checklist [KEYWORD ARGUMENT]...  TYPE ... )
 

@@ -936,7 +940,7 @@ File: widget.info,  Node: editable-list,  Next: group,  Prev: checklist,  Up: Ba
 The `editable-list' Widget
 --------------------------
 
 The `editable-list' Widget
 --------------------------
 

-   Syntax:
+Syntax:

 
      TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
 
 
      TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
 

@@ -979,13 +983,14 @@ TYPE.
 `:args'
      List whose car is the type of the list elements.
 
 `:args'
      List whose car is the type of the list elements.
 

+

 \1f
 File: widget.info,  Node: group,  Prev: editable-list,  Up: Basic Types
 
 The `group' Widget
 ------------------
 
 \1f
 File: widget.info,  Node: group,  Prev: editable-list,  Up: Basic Types
 
 The `group' Widget
 ------------------
 

-   This widget simply group other widget together.
+This widget simply groups other widgets together.

 
    Syntax:
 
 
    Syntax:
 

@@ -999,7 +1004,7 @@ File: widget.info,  Node: Sexp Types,  Next: Widget Properties,  Prev: Basic Typ
 Sexp Types
 ==========
 
 Sexp Types
 ==========
 

-   A number of widgets for editing s-expressions (lisp types) are also
+A number of widgets for editing s-expressions (lisp types) are also

 available.  These basically fall in the following categories.
 
 * Menu:
 available.  These basically fall in the following categories.
 
 * Menu:

@@ -1015,9 +1020,9 @@ File: widget.info,  Node: constants,  Next: generic,  Prev: Sexp Types,  Up: Sex
 The Constant Widgets.
 ---------------------
 
 The Constant Widgets.
 ---------------------
 

-   The `const' widget can contain any lisp expression, but the user is
-prohibited from editing edit it, which is mainly useful as a component
-of one of the composite widgets.
+The `const' widget can contain any lisp expression, but the user is
+prohibited from editing it, which is mainly useful as a component of one
+of the composite widgets.

 
    The syntax for the `const' widget is
 
 
    The syntax for the `const' widget is
 

@@ -1048,8 +1053,8 @@ File: widget.info,  Node: generic,  Next: atoms,  Prev: constants,  Up: Sexp Typ
 Generic Sexp Widget.
 --------------------
 
 Generic Sexp Widget.
 --------------------
 

-   The `sexp' widget can contain any lisp expression, and allows the
-user to edit it inline in the buffer.
+The `sexp' widget can contain any lisp expression, and allows the user
+to edit it inline in the buffer.

 
    The syntax for the `sexp' widget is
 
 
    The syntax for the `sexp' widget is
 

@@ -1068,7 +1073,7 @@ File: widget.info,  Node: atoms,  Next: composite,  Prev: generic,  Up: Sexp Typ
 Atomic Sexp Widgets.
 --------------------
 
 Atomic Sexp Widgets.
 --------------------
 

-   The atoms are s-expressions that does not consist of other
+The atoms are s-expressions that does not consist of other

 s-expressions.  A string is an atom, while a list is a composite type.
 You can edit the value of an atom with the following widgets.
 
 s-expressions.  A string is an atom, while a list is a composite type.
 You can edit the value of an atom with the following widgets.
 

@@ -1132,7 +1137,7 @@ File: widget.info,  Node: composite,  Prev: atoms,  Up: Sexp Types
 Composite Sexp Widgets.
 -----------------------
 
 Composite Sexp Widgets.
 -----------------------
 

-   The syntax for the composite are
+The syntax for the composite are

 
      TYPE ::= (NAME [KEYWORD ARGUMENT]...  COMPONENT...)
 
 
      TYPE ::= (NAME [KEYWORD ARGUMENT]...  COMPONENT...)
 

@@ -1196,8 +1201,8 @@ File: widget.info,  Node: Widget Properties,  Next: Defining New Widgets,  Prev:
 Properties
 ==========
 
 Properties
 ==========
 

-   You can examine or set the value of a widget by using the widget
-object that was returned by `widget-create'.
+You can examine or set the value of a widget by using the widget object
+that was returned by `widget-create'.

 
  - Function: widget-value widget
      Return the current value contained in WIDGET.  It is an error to
 
  - Function: widget-value widget
      Return the current value contained in WIDGET.  It is an error to

@@ -1274,12 +1279,12 @@ File: widget.info,  Node: Defining New Widgets,  Next: Widget Browser,  Prev: Wi
 Defining New Widgets
 ====================
 
 Defining New Widgets
 ====================
 

-   You can define specialized widgets with `define-widget'.  It allows
-you to create a shorthand for more complex widgets.  This includes
+You can define specialized widgets with `define-widget'.  It allows you
+to create a shorthand for more complex widgets.  This includes

 specifying component widgets and new default values for the keyword
 arguments.
 
 specifying component widgets and new default values for the keyword
 arguments.
 

- - Function: widget-define name class doc &rest args
+ - Function: define-widget name class doc &rest args

      Define a new widget type named NAME from `class'.
 
      NAME and class should both be symbols, `class' should be one of
      Define a new widget type named NAME from `class'.
 
      NAME and class should both be symbols, `class' should be one of

@@ -1295,29 +1300,44 @@ arguments.
         *      (apply widget-create CLASS ARGS)
 
 
         *      (apply widget-create CLASS ARGS)
 
 

-   Using `widget-define' just stores the definition of the widget type
+   Using `define-widget' just stores the definition of the widget type

 in the `widget-type' property of NAME, which is what `widget-create'
 uses.
 
    If you just want to specify defaults for keywords with no complex
 in the `widget-type' property of NAME, which is what `widget-create'
 uses.
 
    If you just want to specify defaults for keywords with no complex

-conversions, you can use `identity' as your conversion function.
+conversions, you can use `identity' as your `:convert-widget' function.

 
    The following additional keyword arguments are useful when defining
 new widgets:
 `:convert-widget'
 
    The following additional keyword arguments are useful when defining
 new widgets:
 `:convert-widget'

-     Function to convert a widget type before creating a widget of that
-     type.  It takes a widget type as an argument, and returns the
-     converted widget type.  When a widget is created, this function is
-     called for the widget type and all the widget's parent types, most
-     derived first.
+     Method to convert type-specific components of a widget type before
+     instantiating a widget of that type.  Not normally called from user
+     code, it is invoked by `widget-convert'.  Typical operations
+     include converting types of child widgets to widget instances and
+     converting values from external format (_i.e._, as expected by the
+     calling code) to internal format (which is often different for the
+     convenience of widget manipulation).  It takes a widget type as an
+     argument, and returns the converted widget type.  When a widget is
+     created, the value of this property is called for the widget type,
+     then for all the widget's parent types, most derived first.  (The
+     property is reevaluated for each parent type.)

 
      The following predefined functions can be used here:
 
       - Function: widget-types-convert-widget widget
 
      The following predefined functions can be used here:
 
       - Function: widget-types-convert-widget widget

-          Convert `:args' as widget types in WIDGET.
+          Convert each member of `:args' in WIDGET from a widget type
+          to a widget.

 
       - Function: widget-value-convert-widget widget
 
       - Function: widget-value-convert-widget widget

-          Initialize `:value' from `:args' in WIDGET.
+          Initialize `:value' from `(car :args)' in WIDGET, and reset
+          `:args'.
+
+`:copy'
+     A method to implement deep copying of the type.  Any member of the
+     widget which might be changed in place (rather than replaced)
+     should be copied by this method.  (`widget-copy' uses
+     `copy-sequence' to ensure that the top-level list is a copy.)
+     This particularly applies to child widgets.

 
 `:value-to-internal'
      Function to convert the value to the internal format.  The function
 
 `:value-to-internal'
      Function to convert the value to the internal format.  The function

@@ -1335,8 +1355,14 @@ new widgets:
 
 `:create'
      Function to create a widget from scratch.  The function takes one
 
 `:create'
      Function to create a widget from scratch.  The function takes one

-     argument, a widget type, and creates a widget of that type,
-     inserts it in the buffer, and returns a widget object.
+     argument, a widget, and inserts it in the buffer.  Not normally
+     called from user code.  Instead, call `widget-create' or related
+     functions, which take a type argument, (usually) convert it to a
+     widget, call the `:create' function to insert it in the buffer,
+     and then return the (possibly converted) widget.
+
+     The default, `widget-default-create', is invariably appropriate.
+     (None of the standard widgets specify `:create'.)

 
 `:delete'
      Function to delete a widget.  The function takes one argument, a
 
 `:delete'
      Function to delete a widget.  The function takes one argument, a

@@ -1379,7 +1405,9 @@ new widgets:
 
 `:action'
      Function to handle user initiated events.  By default, `:notify'
 
 `:action'
      Function to handle user initiated events.  By default, `:notify'

-     the parent.
+     the parent.  Actions normally do not include mere edits, but refer
+     to things like invoking buttons or hitting enter in an editable
+     field.  To watch for any change, redefine the `:notify' callback.

 
      The following predefined function can be used here:
 
 
      The following predefined function can be used here:
 

@@ -1405,16 +1433,47 @@ widget as its base.
      It provides most of the functionality that is referred to as "by
      default" in this text.
 
      It provides most of the functionality that is referred to as "by
      default" in this text.
 

+   In implementing complex hierarchical widgets (_e.g._, using the
+`group' widget), the following functions may be useful.  The syntax for
+the TYPE arguments to these functions is described in *Note Basic
+Types::.
+
+ - Function: widget-create-child-and-convert parent type &rest args
+     As a child of PARENT, create a widget with type TYPE and value
+     VALUE.  TYPE is copied, and the `:widget-contvert' method is
+     applied to the optional keyword arguments from ARGS.
+
+ - Function: widget-create-child parent type
+     As a child of PARENT, create a widget with type TYPE.  TYPE is
+     copied, but no conversion method is applied.
+
+ - Function: widget-create-child-value parent type value
+     As a child of PARENT, create a widget with type TYPE and value
+     VALUE.  TYPE is copied, but no conversion method is applied.
+
+ - Function: widget-convert type &rest args
+     Convert TYPE to a widget without inserting it in the buffer.  The
+     optional ARGS are additional keyword arguments.
+
+     The widget's `:args' property is set from the longest tail of ARGS
+     whose `cdr' is not a keyword, or if that is null, from the longest
+     tail of TYPE's `:args' property whose cdr is not a keyword.
+     Keyword arguments from ARGS are set, and the `:value' property (if
+     any) is converted from external to internal format.
+
+   `widget-convert' is typically not called from user code; rather it
+is called implicitly through the `widget-create*' functions.
+

 \1f
 File: widget.info,  Node: Widget Browser,  Next: Widget Minor Mode,  Prev: Defining New Widgets,  Up: Top
 
 Widget Browser
 ==============
 
 \1f
 File: widget.info,  Node: Widget Browser,  Next: Widget Minor Mode,  Prev: Defining New Widgets,  Up: Top
 
 Widget Browser
 ==============
 

-   There is a separate package to browse widgets.  This is intended to
-help programmers who want to examine the content of a widget.  The
-browser shows the value of each keyword, but uses links for certain
-keywords such as `:parent', which avoids printing cyclic structures.
+There is a separate package to browse widgets.  This is intended to help
+programmers who want to examine the content of a widget.  The browser
+shows the value of each keyword, but uses links for certain keywords
+such as `:parent', which avoids printing cyclic structures.

 
  - Command: widget-browse WIDGET
      Create a widget browser for WIDGET.  When called interactively,
 
  - Command: widget-browse WIDGET
      Create a widget browser for WIDGET.  When called interactively,

@@ -1434,7 +1493,7 @@ File: widget.info,  Node: Widget Minor Mode,  Next: Utilities,  Prev: Widget Bro
 Widget Minor Mode
 =================
 
 Widget Minor Mode
 =================
 

-   There is a minor mode for manipulating widgets in major modes that
+There is a minor mode for manipulating widgets in major modes that

 doesn't provide any support for widgets themselves.  This is mostly
 intended to be useful for programmers doing experiments.
 
 doesn't provide any support for widgets themselves.  This is mostly
 intended to be useful for programmers doing experiments.
 

@@ -1461,7 +1520,7 @@ Utilities.
      This is only meaningful for radio buttons or checkboxes in a list.
 
 \1f
      This is only meaningful for radio buttons or checkboxes in a list.
 
 \1f

-File: widget.info,  Node: Widget Wishlist,  Prev: Utilities,  Up: Top
+File: widget.info,  Node: Widget Wishlist,  Next: Widget Internals,  Prev: Utilities,  Up: Top

 
 Wishlist
 ========
 
 Wishlist
 ========

@@ -1506,7 +1565,7 @@ Wishlist
    * `C-e e' in a fixed size field should go to the end of the text in
      the field, not the end of the field itself.
 
    * `C-e e' in a fixed size field should go to the end of the text in
      the field, not the end of the field itself.
 

-   * Use and overlay instead of markers to delimit the widget.  Create
+   * Use an overlay instead of markers to delimit the widget.  Create

      accessors for the end points.
 
    * Clicking on documentation links should call `describe-function' or
      accessors for the end points.
 
    * Clicking on documentation links should call `describe-function' or

@@ -1515,40 +1574,75 @@ Wishlist
      symbol, it should pop up a menu.
 
 
      symbol, it should pop up a menu.
 
 

+\1f
+File: widget.info,  Node: Widget Internals,  Prev: Widget Wishlist,  Up: Top
+
+Internals
+=========
+
+This (very brief!) section provides a few notes on the internal
+structure and implementation of Emacs widgets.  Avoid relying on this
+information.  (We intend to improve it, but this will take some time.)
+To the extent that it actually describes APIs, the information will be
+moved to appropriate sections of the manual in due course.
+
+The "Widget" and "Type" Structures
+----------------------------------
+
+Widgets and types are currently both implemented as lists.
+
+   A symbol may be defined as a "type name" using `define-widget'.
+*Note Defining New Widgets::.  A "type" is a list whose car is a
+previously defined type name, nil, or (recursively) a type.  The car is
+the "class" or parent type of the type, and properties which are not
+specified in the new type will be inherited from ancestors.  Probably
+the only type without a class should be the `default' type.  The cdr of
+a type is a plist whose keys are widget property keywords.
+
+   A type or type name may also be referred to as an "unconverted
+widget".
+
+   A "converted widget" or "widget instance" is a list whose car is a
+type name or a type, and whose cdr is a property list.  Furthermore,
+all children of the converted widget must be converted.  Finally, in the
+process of appropriate parts of the list structure are copied to ensure
+that changes in values of one instance do not affect another's.
+

 
 \1f
 Tag Table:
 Node: Top\7f211
 
 \1f
 Tag Table:
 Node: Top\7f211

-Node: Introduction\7f591
-Node: User Interface\7f4075
-Node: Programming Example\7f8970
-Node: Setting Up the Buffer\7f13120
+Node: Introduction\7f612
+Node: User Interface\7f4087
+Node: Programming Example\7f8976
+Node: Setting Up the Buffer\7f13123

 Node: Basic Types\7f14837
 Node: Basic Types\7f14837

-Node: link\7f20895
-Node: url-link\7f21409
-Node: info-link\7f21721
-Node: push-button\7f22012
-Node: editable-field\7f22585
-Node: text\7f24068
-Node: menu-choice\7f24366
-Node: radio-button-choice\7f25219
-Node: item\7f26786
-Node: choice-item\7f27174
-Node: toggle\7f27672
-Node: checkbox\7f28409
-Node: checklist\7f28715
-Node: editable-list\7f30159
-Node: group\7f31341
-Node: Sexp Types\7f31628
-Node: constants\7f31941
-Node: generic\7f33020
-Node: atoms\7f33553
-Node: composite\7f35500
-Node: Widget Properties\7f37970
-Node: Defining New Widgets\7f41035
-Node: Widget Browser\7f46335
-Node: Widget Minor Mode\7f47193
-Node: Utilities\7f47750
-Node: Widget Wishlist\7f48231
+Node: link\7f21042
+Node: url-link\7f21553
+Node: info-link\7f21862
+Node: push-button\7f22150
+Node: editable-field\7f22720
+Node: text\7f24200
+Node: menu-choice\7f24495
+Node: radio-button-choice\7f25345
+Node: item\7f26909
+Node: choice-item\7f27294
+Node: toggle\7f27789
+Node: checkbox\7f28523
+Node: checklist\7f28826
+Node: editable-list\7f30267
+Node: group\7f31447
+Node: Sexp Types\7f31733
+Node: constants\7f32043
+Node: generic\7f33114
+Node: atoms\7f33644
+Node: composite\7f35588
+Node: Widget Properties\7f38055
+Node: Defining New Widgets\7f41117
+Node: Widget Browser\7f49281
+Node: Widget Minor Mode\7f50136
+Node: Utilities\7f50690
+Node: Widget Wishlist\7f51171
+Node: Widget Internals\7f52892

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

diff --git a/info/xemacs-faq.info b/info/xemacs-faq.info
index 96e328c..d8c7476 100644 (file)
--- a/info/xemacs-faq.info
+++ b/info/xemacs-faq.info
@@ -1,4 +1,4 @@
-This is ../info/xemacs-faq.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs-faq.info, produced by makeinfo version 4.6 from

 xemacs-faq.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 xemacs-faq.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -7,262 +7,7430 @@ START-INFO-DIR-ENTRY
 END-INFO-DIR-ENTRY
 
 \1f
 END-INFO-DIR-ENTRY
 
 \1f

-Indirect:
-xemacs-faq.info-1: 205
-xemacs-faq.info-2: 50095
-xemacs-faq.info-3: 99803
-xemacs-faq.info-4: 149685
-xemacs-faq.info-5: 199368
+File: xemacs-faq.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
+
+XEmacs FAQ
+**********
+
+This is the guide to the XEmacs Frequently Asked Questions list--a
+compendium of questions and answers pertaining to one of the finest
+programs ever written.  XEmacs is much more than just a Text Editor.
+
+   This FAQ is freely redistributable.  This FAQ 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.
+
+   If you have a Web browser, the official hypertext version is at
+`http://www.xemacs.org/FAQ/xemacs-faq.html'
+
+* Menu:
+
+* Introduction::        Introduction, Policy, Credits.
+* Installation::        Installation and Trouble Shooting.
+* Customization::       Customization and Options.
+* Subsystems::          Major Subsystems.
+* Miscellaneous::       The Miscellaneous Stuff.
+* MS Windows::          XEmacs on Microsoft Windows.
+* Current Events::      What the Future Holds.
+* Legacy Versions::     New information about old XEmacsen.
+
+
+ --- The Detailed Node Listing ---
+
+Introduction, Policy, Credits
+
+* Q1.0.1::      What is XEmacs?
+* Q1.0.2::      What is the current version of XEmacs?
+* Q1.0.3::      Where can I find it?
+* Q1.0.4::      Why Another Version of Emacs?
+* Q1.0.5::      Why Haven't XEmacs and GNU Emacs Merged?
+* Q1.0.6::      Where can I get help?
+* Q1.0.7::      Where are the mailing lists archived?
+* Q1.0.8::      How do you pronounce XEmacs?
+* Q1.0.9::      What does XEmacs look like?
+* Q1.0.10::     Is there a port of XEmacs to Microsoft ('95 or NT)?
+* Q1.0.11::     Is there a port of XEmacs to the Macintosh?
+* Q1.0.12::     Is there a port of XEmacs to NextStep?
+* Q1.0.13::     Is there a port of XEmacs to OS/2?
+* Q1.0.14::     Where can I get a printed copy of the XEmacs users manual?
+
+Policies:
+* Q1.1.1::      What is the FAQ editorial policy?
+* Q1.1.2::      How do I become a Beta Tester?
+* Q1.1.3::      How do I contribute to XEmacs itself?
+
+Credits:
+* Q1.2.1::      Who wrote XEmacs?
+* Q1.2.2::      Who contributed to this version of the FAQ?
+* Q1.2.3::      Who contributed to the FAQ in the past?
+
+Internationalization:
+* Q1.3.1::      What is the status of internationalization support aka MULE (including Asian language support?
+* Q1.3.2::      How can I help with internationalization?
+* Q1.3.3::      How do I type non-ASCII characters?
+* Q1.3.4::      Can XEmacs messages come out in a different language?
+* Q1.3.5::      Please explain the various input methods in MULE/XEmacs
+* Q1.3.6::      How do I portably code for MULE/XEmacs?
+* Q1.3.7::      How about Cyrillic Modes?
+* Q1.3.8::      Does XEmacs support Unicode?
+* Q1.3.9::      How does XEmacs display Unicode?
+
+Getting Started:
+* Q1.4.1::      What is an `init.el' or `.emacs' and is there a sample one?
+* Q1.4.2::      Can I use the same `init.el'/`.emacs' with the other Emacs?
+* Q1.4.3::      Any good XEmacs tutorials around?
+* Q1.4.4::      May I see an example of a useful XEmacs Lisp function?
+* Q1.4.5::      And how do I bind it to a key?
+* Q1.4.6::      What's the difference between a macro and a function?
+
+Installation and Trouble Shooting
+
+* Q2.0.1::      Running XEmacs without installing.
+* Q2.0.2::      XEmacs is too big.
+* Q2.0.3::      Compiling XEmacs with Netaudio.
+* Q2.0.4::      Problems with Linux and ncurses.
+* Q2.0.5::      Do I need X11 to run XEmacs?
+* Q2.0.6::      I'm having strange crashes.  What do I do?
+* Q2.0.7::      Libraries in non-standard locations.
+* Q2.0.8::      can't resolve symbol _h_errno
+* Q2.0.9::      Where do I find external libraries?
+* Q2.0.10::     After I run configure I find a coredump, is something wrong?
+* Q2.0.11::     XEmacs can't resolve host names.
+* Q2.0.12::     Why can't I strip XEmacs?
+* Q2.0.13::     I don't need no steenkin' packages.  Do I?
+* Q2.0.14::     How do I figure out which packages to install?
+* Q2.0.15::     EFS fails with "500 AUTH not understood" (NEW)
+* Q2.0.16::     Cygwin XEmacs won't start: cygXpm-noX4.dll was not found (NEW)
+
+Trouble Shooting:
+* Q2.1.1::      XEmacs just crashed on me!
+* Q2.1.2::      Cryptic Minibuffer messages.
+* Q2.1.3::      Translation Table Syntax messages at Startup.
+* Q2.1.4::      Startup warnings about deducing proper fonts?
+* Q2.1.5::      XEmacs cannot connect to my X Terminal.
+* Q2.1.6::      XEmacs just locked up my Linux X server.
+* Q2.1.7::      HP Alt key as Meta.
+* Q2.1.8::      got (wrong-type-argument color-instance-p nil)!
+* Q2.1.9::      XEmacs causes my OpenWindows 3.0 server to crash.
+* Q2.1.10::     Warnings from incorrect key modifiers.
+* Q2.1.11::     Can't instantiate image error... in toolbar
+* Q2.1.12::     Regular Expression Problems on DEC OSF1.
+* Q2.1.13::     HP/UX 10.10 and `create_process' failure
+* Q2.1.14::     C-g doesn't work for me.  Is it broken?
+* Q2.1.15::     How to debug an XEmacs problem with a debugger.
+* Q2.1.16::     XEmacs crashes in `strcat' on HP/UX 10.
+* Q2.1.17::     `Marker does not point anywhere'.
+* Q2.1.18::     XEmacs is outputting lots of X errors.
+* Q2.1.19::     XEmacs does not follow the local timezone.
+* Q2.1.20::     `Symbol's function definition is void: hkey-help-show.'
+* Q2.1.21::     [This question intentionally left blank]
+* Q2.1.22::     XEmacs seems to take a really long time to do some things.
+* Q2.1.23::     Movemail on Linux does not work for XEmacs 19.15 and later.
+* Q2.1.24::     XEmacs won't start without network.
+* Q2.1.25::     After upgrading, XEmacs won't do `foo' any more!
+
+Customization and Options
+
+* Q3.0.1::      What version of Emacs am I running?
+* Q3.0.2::      How do I evaluate Elisp expressions?
+* Q3.0.3::      `(setq tab-width 6)' behaves oddly.
+* Q3.0.4::      How can I add directories to the `load-path'?
+* Q3.0.5::      How to check if a lisp function is defined?
+* Q3.0.6::      Can I force the output of `(face-list)' to a buffer?
+* Q3.0.7::      Font selections don't get saved after `Save Options'.
+* Q3.0.8::      How do I make a single minibuffer frame?
+* Q3.0.9::      What is `Customize'?
+
+X Window System & Resources:
+* Q3.1.1::      Where is a list of X resources?
+* Q3.1.2::      How can I detect a color display?
+* Q3.1.3::      [This question intentionally left blank]
+* Q3.1.4::      [This question intentionally left blank]
+* Q3.1.5::      How can I get the icon to just say `XEmacs'?
+* Q3.1.6::      How can I have the window title area display the full path?
+* Q3.1.7::      `xemacs -name junk' doesn't work?
+* Q3.1.8::      `-iconic' doesn't work.
+
+Textual Fonts & Colors:
+* Q3.2.1::      How can I set color options from `init.el'/`.emacs'?
+* Q3.2.2::      How do I set the text, menu and modeline fonts?
+* Q3.2.3::      How can I set the colors when highlighting a region?
+* Q3.2.4::      How can I limit color map usage?
+* Q3.2.5::      My tty supports color, but XEmacs doesn't use them.
+* Q3.2.6::      Can I have pixmap backgrounds in XEmacs?
+
+The Modeline:
+* Q3.3.1::      How can I make the modeline go away?
+* Q3.3.2::      How do you have XEmacs display the line number in the modeline?
+* Q3.3.3::      How do I get XEmacs to put the time of day on the modeline?
+* Q3.3.4::      How do I turn off current chapter from AUC TeX modeline?
+* Q3.3.5::      How can one change the modeline color based on the mode used?
+
+Multiple Device Support:
+* Q3.4.1::      How do I open a frame on another screen of my multi-headed display?
+* Q3.4.2::      Can I really connect to a running XEmacs after calling up over a modem?  How?
+
+The Keyboard:
+* Q3.5.1::      How can I bind complex functions (or macros) to keys?
+* Q3.5.2::      How can I stop down-arrow from adding empty lines to the bottom of my buffers?
+* Q3.5.3::      How do I bind C-. and C-; to scroll one line up and down?
+* Q3.5.4::      Globally binding Delete?
+* Q3.5.5::      Scrolling one line at a time.
+* Q3.5.6::      How to map Help key alone on Sun type4 keyboard?
+* Q3.5.7::      How can you type in special characters in XEmacs?
+* Q3.5.8::      [This question intentionally left blank]
+* Q3.5.9::      How do I make the Delete key delete forward?
+* Q3.5.10::     Can I turn on "sticky" modifier keys?
+* Q3.5.11::     How do I map the arrow keys?
+
+The Cursor:
+* Q3.6.1::      Is there a way to make the bar cursor thicker?
+* Q3.6.2::      Is there a way to get back the old block cursor where the cursor covers the character in front of the point?
+* Q3.6.3::      Can I make the cursor blink?
+
+The Mouse and Highlighting:
+* Q3.7.1::      How can I turn off Mouse pasting?
+* Q3.7.2::      How do I set control/meta/etc modifiers on mouse buttons?
+* Q3.7.3::      Clicking the left button does not do anything in buffer list.
+* Q3.7.4::      How can I get a list of buffers when I hit mouse button 3?
+* Q3.7.5::      Why does cut-and-paste not work between XEmacs and a cmdtool?
+* Q3.7.6::      How I can set XEmacs up so that it pastes where the text cursor is?
+* Q3.7.7::      How do I select a rectangular region?
+* Q3.7.8::      Why does M-w take so long?
+
+The Menubar and Toolbar:
+* Q3.8.1::      How do I get rid of the menu (or menubar)?
+* Q3.8.2::      Can I customize the basic menubar?
+* Q3.8.3::      How do I control how many buffers are listed in the menu `Buffers' list?
+* Q3.8.4::      Resources like `Emacs*menubar*font' are not working?
+* Q3.8.5::      How can I bind a key to a function to toggle the toolbar?
+
+Scrollbars:
+* Q3.9.1::      How can I disable the scrollbar?
+* Q3.9.2::      How can one use resources to change scrollbar colors?
+* Q3.9.3::      Moving the scrollbar can move the point; can I disable this?
+* Q3.9.4::      How can I turn off automatic horizontal scrolling in specific modes?
+
+Text Selections:
+* Q3.10.1::     How can I turn off or change highlighted selections?
+* Q3.10.2::     How do I get that typing on an active region removes it?
+* Q3.10.3::     Can I turn off the highlight during isearch?
+* Q3.10.4::     How do I turn off highlighting after C-x C-p (mark-page)?
+* Q3.10.5::     The region disappears when I hit the end of buffer while scrolling.
+* Q3.10.6::     Why is killing so slow?
+
+Major Subsystems
+
+* Q4.0.1::      How do I set up VM to retrieve remote mail using POP?
+* Q4.0.2::      How do I get VM to filter mail for me?
+* Q4.0.3::      How can I get VM to automatically check for new mail?
+* Q4.0.4::      [This question intentionally left blank]
+* Q4.0.5::      How do I get my outgoing mail archived?
+* Q4.0.6::      I have various addresses at which I receive mail.  How can I tell VM to ignore them when doing a "reply-all"?
+* Q4.0.7::      Is there a mailing list or FAQ for VM?
+* Q4.0.8::      Remote mail reading with VM.
+* Q4.0.9::      rmail or VM gets an error incorporating new mail.
+* Q4.0.10::     How do I make VM stay in a single frame?
+* Q4.0.11::     How do I make VM or mh-e display graphical smilies?
+* Q4.0.12::     Customization of VM not covered in the manual or here.
+
+Web browsing with W3:
+* Q4.1.1::      What is W3?
+* Q4.1.2::      How do I run W3 from behind a firewall?
+* Q4.1.3::      Is it true that W3 supports style sheets and tables?
+
+Reading Netnews and Mail with Gnus:
+* Q4.2.1::      GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus, Quassia Gnus, argh!
+* Q4.2.2::      [This question intentionally left blank]
+* Q4.2.3::      How do I make Gnus stay within a single frame?
+* Q4.2.4::      How do I customize the From: line?
+
+Other Mail & News:
+* Q4.3.1::      How can I read and/or compose MIME messages?
+* Q4.3.2::      What is TM and where do I get it?
+* Q4.3.3::      Why isn't this `movemail' program working?
+* Q4.3.4::      Movemail is also distributed by Netscape?  Can that cause problems?
+* Q4.3.5::      Where do I find pstogif (required by tm)?
+
+Sparcworks, EOS, and WorkShop:
+* Q4.4.1::      What is SPARCworks, EOS, and WorkShop
+* Q4.4.2::      How do I start the Sun Workshop support in XEmacs 21?
+
+Energize:
+* Q4.5.1::      What is/was Energize?
+
+Infodock:
+* Q4.6.1::      What is Infodock?
+
+Other Unbundled Packages:
+* Q4.7.1::      What is AUC TeX?  Where do you get it?
+* Q4.7.2::      Are there any Emacs Lisp Spreadsheets?
+* Q4.7.3::      [This question intentionally left blank]
+* Q4.7.4::      Problems installing AUC TeX
+* Q4.7.5::      Is there a reason for an Emacs package not to be included in XEmacs?
+* Q4.7.6::      Is there a MatLab mode?
+* Q4.7.7::      Can I edit files on other hosts?
+
+The Miscellaneous Stuff
+
+* Q5.0.1::      How can I do source code highlighting using font-lock?
+* Q5.0.2::      I do not like cc-mode.  How do I use the old c-mode?
+* Q5.0.3::      How do I get `More' Syntax Highlighting on by default?
+* Q5.0.4::      How can I enable auto-indent and/or Filladapt?
+* Q5.0.5::      How can I get XEmacs to come up in text/auto-fill mode by default?
+* Q5.0.6::      How do I start up a second shell buffer?
+* Q5.0.7::      Telnet from shell filters too much.
+* Q5.0.8::      Why does edt emulation not work?
+* Q5.0.9::      How can I emulate VI and use it as my default mode?
+* Q5.0.10::     [This question intentionally left blank]
+* Q5.0.11::     [This question intentionally left blank]
+* Q5.0.12::     How do I disable gnuserv from opening a new frame?
+* Q5.0.13::     How do I start gnuserv so that each subsequent XEmacs is a client?
+* Q5.0.14::     Strange things are happening in Shell Mode.
+* Q5.0.15::     Where do I get the latest CC Mode?
+* Q5.0.16::     I find auto-show-mode disconcerting.  How do I turn it off?
+* Q5.0.17::     How can I get two instances of info?
+* Q5.0.18::     [This question intentionally left blank]
+* Q5.0.19::     Is there something better than LaTeX mode?
+* Q5.0.20::     Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
+
+Emacs Lisp Programming Techniques:
+* Q5.1.1::      The difference in key sequences between XEmacs and GNU Emacs?
+* Q5.1.2::      Can I generate "fake" keyboard events?
+* Q5.1.3::      Could you explain `read-kbd-macro' in more detail?
+* Q5.1.4::      What is the performance hit of `let'?
+* Q5.1.5::      What is the recommended use of `setq'?
+* Q5.1.6::      What is the typical misuse of `setq' ?
+* Q5.1.7::      I like the `do' form of cl, does it slow things down?
+* Q5.1.8::      I like recursion, does it slow things down?
+* Q5.1.9::      How do I put a glyph as annotation in a buffer?
+* Q5.1.10::     `map-extents' won't traverse all of my extents!
+* Q5.1.11::     My elisp program is horribly slow.  Is there an easy way to find out where it spends time?
+
+Sound:
+* Q5.2.1::      How do I turn off the sound?
+* Q5.2.2::      How do I get funky sounds instead of a boring beep?
+* Q5.2.3::      What's NAS, how do I get it?
+* Q5.2.4::      Sunsite sounds don't play.
+
+Miscellaneous:
+* Q5.3.1::      How do you make XEmacs indent CL if-clauses correctly?
+* Q5.3.2::      [This question intentionally left blank]
+* Q5.3.3::      How can I print WYSIWYG a font-locked buffer?
+* Q5.3.4::      Getting M-x lpr to work with postscript printer.
+* Q5.3.5::      How do I specify the paths that XEmacs uses for finding files?
+* Q5.3.6::      [This question intentionally left blank]
+* Q5.3.7::      Can I have the end of the buffer delimited in some way?
+* Q5.3.8::      How do I insert today's date into a buffer?
+* Q5.3.9::      Are only certain syntactic character classes available for abbrevs?
+* Q5.3.10::     How can I get those oh-so-neat X-Face lines?
+* Q5.3.11::     How do I add new Info directories?
+* Q5.3.12::     What do I need to change to make printing work?
+
+XEmacs on MS Windows
+
+General Info:
+* Q6.0.1::      What is the status of the XEmacs port to Windows?
+* Q6.0.2::      What flavors of MS Windows are supported?  The list name implies NT only.
+* Q6.0.3::      Are binaries available?
+* Q6.0.4::      Can I build XEmacs on MS Windows with X support?  Do I need to?
+* Q6.0.5::      I'd like to help out.  What do I do?
+* Q6.0.6::      What are Cygwin and MinGW, and do I need them to run XEmacs?
+* Q6.0.7::      What exactly are all the different ways to build XEmacs under Windows?
+
+Building XEmacs on MS Windows:
+* Q6.1.1::      What compiler/libraries do I need to compile XEmacs?
+* Q6.1.2::      How do I compile the native port?
+* Q6.1.3::      What do I need for Cygwin?
+* Q6.1.4::      How do I compile under Cygwin?
+* Q6.1.5::      How do I compile using MinGW (aka `the -mno-cygwin flag to gcc')?
+* Q6.1.6::      I decided to run with X.  Where do I get an X server?
+* Q6.1.7::      How do I compile with X support?
+
+Customization and User Interface:
+* Q6.2.1::      How does the port cope with differences in the Windows user interface?
+* Q6.2.2::      How do I change fonts in XEmacs on MS Windows?
+* Q6.2.3::      Where do I put my `init.el'/`.emacs' file?
+* Q6.2.4::      How do I get Windows Explorer to associate a file type with XEmacs?
+* Q6.2.5::      Is it possible to print from XEmacs?
+
+Miscellaneous:
+* Q6.3.1::      Does XEmacs rename all the `win32-*' symbols to `w32-*'?
+* Q6.3.2::      What are the differences between the various MS Windows emacsen?
+* Q6.3.3::      XEmacs 21.1 on Windows used to spawn an ugly console window on every startup.  Has that been fixed?
+* Q6.3.4::      What is the porting team doing at the moment?
+
+Troubleshooting:
+* Q6.4.1::      XEmacs won't start on Windows.
+* Q6.4.2::      Why do I get a blank toolbar on Windows 95?
+* Q6.4.3::      XEmacs complains "No such file or directory, diff"
+
+What the Future Holds
+
+* Q7.0.1::      What new features will be in XEmacs soon?
+* Q7.0.2::      What's new in XEmacs 21.4?
+* Q7.0.3::      What's new in XEmacs 21.1?
+* Q7.0.4::      What's new in XEmacs 20.4?
+* Q7.0.5::      What's new in XEmacs 20.3?
+* Q7.0.6::      What's new in XEmacs 20.2?
+
+New information about old XEmacsen.
+
+XEmacs 21.1:
+* Q8.0.1::      Gnus 5.10 won't display smileys in XEmacs 21.1.
+
+\1f
+File: xemacs-faq.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top
+
+1 Introduction, Policy, Credits
+*******************************
+
+Learning XEmacs is a lifelong activity.  Even people who have used Emacs
+for years keep discovering new features.  Therefore this document cannot
+be complete.  Instead it is aimed at the person who is either
+considering XEmacs for their own use, or has just obtained it and is
+wondering what to do next.  It is also useful as a reference to
+available resources.
+
+   The previous maintainer of the FAQ was Anthony Rossini
+<rossini@biostat.washington.edu>, who started it, after getting tired
+of hearing JWZ complain about repeatedly having to answer questions.
+Ben Wing <ben@xemacs.org> and Chuck Thompson <cthomp@xemacs.org>, the
+principal authors of XEmacs, then took over and Ben did a massive
+update reorganizing the whole thing.  At which point Anthony took back
+over, but then had to give it up again.  Some of the other contributors
+to this FAQ are listed later in this document.
+
+   The previous version was converted to hypertext format, and edited by
+Steven L. Baur <steve@xemacs.org>.  It was converted back to texinfo by
+Hrvoje Niksic <hniksic@xemacs.org>.  The FAQ was then maintained by
+Andreas Kaempf <andreas@sccon.com>, who passed it on to ChristianNyb/o.
+
+   If you notice any errors or items which should be added or amended to
+this FAQ please send email to Sandra Wambold <faq@xemacs.org>.  Include
+`XEmacs FAQ' on the Subject: line.
+
+* Menu:
+
+Introduction:
+* Q1.0.1::      What is XEmacs?
+* Q1.0.2::      What is the current version of XEmacs?
+* Q1.0.3::      Where can I find it?
+* Q1.0.4::      Why Another Version of Emacs?
+* Q1.0.5::      Why Haven't XEmacs and GNU Emacs Merged?
+* Q1.0.6::      Where can I get help?
+* Q1.0.7::      Where are the mailing lists archived?
+* Q1.0.8::      How do you pronounce XEmacs?
+* Q1.0.9::      What does XEmacs look like?
+* Q1.0.10::     Is there a port of XEmacs to Microsoft ('95 or NT)?
+* Q1.0.11::     Is there a port of XEmacs to the Macintosh?
+* Q1.0.12::     Is there a port of XEmacs to NextStep?
+* Q1.0.13::     Is there a port of XEmacs to OS/2?
+* Q1.0.14::     Where can I get a printed copy of the XEmacs users manual?
+
+Policies:
+* Q1.1.1::      What is the FAQ editorial policy?
+* Q1.1.2::      How do I become a Beta Tester?
+* Q1.1.3::      How do I contribute to XEmacs itself?
+
+Credits:
+* Q1.2.1::      Who wrote XEmacs?
+* Q1.2.2::      Who contributed to this version of the FAQ?
+* Q1.2.3::      Who contributed to the FAQ in the past?
+
+Internationalization:
+* Q1.3.1::      What is the status of internationalization support aka MULE (including Asian language support?
+* Q1.3.2::      How can I help with internationalization?
+* Q1.3.3::      How do I type non-ASCII characters?
+* Q1.3.4::      Can XEmacs messages come out in a different language?
+* Q1.3.5::      Please explain the various input methods in MULE/XEmacs
+* Q1.3.6::      How do I portably code for MULE/XEmacs?
+* Q1.3.7::      How about Cyrillic Modes?
+* Q1.3.8::      Does XEmacs support Unicode?
+* Q1.3.9::      How does XEmacs display Unicode?
+
+Getting Started:
+* Q1.4.1::      What is an `init.el' or `.emacs' and is there a sample one?
+* Q1.4.2::      Can I use the same `init.el'/`.emacs' with the other Emacs?
+* Q1.4.3::      Any good XEmacs tutorials around?
+* Q1.4.4::      May I see an example of a useful XEmacs Lisp function?
+* Q1.4.5::      And how do I bind it to a key?
+* Q1.4.6::      What's the difference between a macro and a function?
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.1,  Next: Q1.0.2,  Prev: Introduction,  Up: Introduction
+
+1.0: Introduction
+=================
+
+Q1.0.1: What is XEmacs?
+-----------------------
+
+XEmacs is a powerful, highly customizable open source text editor and
+application development system, with full GUI support.  It is protected
+under the GNU Public License and related to other versions of Emacs, in
+particular GNU Emacs.  Its emphasis is on modern graphical user
+interface support and an open software development model, similar to
+Linux.  XEmacs has an active development community numbering in the
+hundreds (and thousands of active beta testers on top of this), and runs
+on all versions of MS Windows, on Linux, and on nearly every other
+version of Unix in existence.  Support for XEmacs has been supplied by
+Sun Microsystems, University of Illinois, Lucid, ETL/Electrotechnical
+Laboratory, Amdahl Corporation, BeOpen, and others, as well as the
+unpaid time of a great number of individual developers.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.2,  Next: Q1.0.3,  Prev: Q1.0.1,  Up: Introduction
+
+Q1.0.2: What is the current version of XEmacs?
+----------------------------------------------
+
+XEmacs versions 21.1.* are releases made from the current stable
+sources.  XEmacs versions 21.2.* are releases made from the development
+sources.  Check at `http://www.xemacs.org' for the current minor
+version.
+
+   XEmacs 19.16 was the last release of v19, released in November, 1997,
+which was also the last version without international language support.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.3,  Next: Q1.0.4,  Prev: Q1.0.2,  Up: Introduction
+
+Q1.0.3: Where can I find it?
+----------------------------
+
+The canonical source and binaries can be found via anonymous FTP at:
+
+     `ftp://ftp.xemacs.org/pub/xemacs/'
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.4,  Next: Q1.0.5,  Prev: Q1.0.3,  Up: Introduction
+
+Q1.0.4: Why Another Version of Emacs?
+-------------------------------------
+
+For a detailed description of the differences between GNU Emacs and
+XEmacs and a detailed history of XEmacs, check out the
+     NEWS file (http://www.xemacs.org/About/XEmacsVsGNUemacs.html)
+
+   However, here is a list of some of the reasons why we think you might
+consider using it:
+
+   * It looks nicer.
+
+   * The XEmacs maintainers are generally more receptive to suggestions
+     than the GNU Emacs maintainers.
+
+   * Many more bundled packages than GNU Emacs.
+
+   * Binaries are available for many common operating systems.
+
+   * Face support on TTY's.
+
+   * A built-in toolbar.
+
+   * Better Motif compliance.
+
+   * Some internationalization support (including full MULE support, if
+     compiled with it).
+
+   * Variable-width fonts.
+
+   * Variable-height lines.
+
+   * Marginal annotations.
+
+   * ToolTalk support.
+
+   * XEmacs can be used as an Xt widget, and can be embedded within
+     another application.
+
+   * Horizontal and vertical scrollbars (using real toolkit scrollbars).
+
+   * Better APIs (and performance) for attaching fonts, colors, and
+     other properties to text.
+
+   * The ability to embed arbitrary graphics in a buffer.
+
+   * Completely compatible (at the C level) with the Xt-based toolkits.
+
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.5,  Next: Q1.0.6,  Prev: Q1.0.4,  Up: Introduction
+
+Q1.0.5: Why Haven't XEmacs and GNU Emacs Merged?
+------------------------------------------------
+
+There are currently irreconcilable differences in the views about
+technical, programming, design and organizational matters between RMS
+and the XEmacs development team which provide little hope for a merge to
+take place in the short-term future.
+
+   If you have a comment to add regarding the merge, it is a good idea
+to avoid posting to the newsgroups,  because of the very heated
+flamewars that often result.  Mail your questions to
+<xemacs-beta@xemacs.org> and <bug-gnu-emacs@prep.ai.mit.edu>.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.6,  Next: Q1.0.7,  Prev: Q1.0.5,  Up: Introduction
+
+Q1.0.6: Where can I get help?
+-----------------------------
+
+Probably the easiest way, if everything is installed, is to use Info, by
+pressing `C-h i', or looking for an Info item on the Help Menu.  `M-x
+apropos' can be used to look for particular commands.
+
+   For items not found in the manual, try reading this FAQ and reading
+the Usenet group comp.emacs.xemacs.
+
+   If you choose to post to a newsgroup, *please use
+comp.emacs.xemacs*.  Please do not post XEmacs related questions to
+gnu.emacs.help.
+
+   If you cannot post or read Usenet news, there is a corresponding
+mailing list <xemacs-news@xemacs.org> which is available.  It can be
+subscribed to via the Mailman Web interface or by sending mail to to
+<xemacs-news-request@xemacs.org> with `subscribe' in the body of the
+message.  See also `http://www.xemacs.org/Lists/#xemacs-news'.  To
+cancel a subscription, you may use the <xemacs-news-request@xemacs.org>
+address or the Web interface.  Send a message with a subject of
+`unsubscribe' to be removed.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.7,  Next: Q1.0.8,  Prev: Q1.0.6,  Up: Introduction
+
+Q1.0.7: Where are the mailing lists archived?
+---------------------------------------------
+
+The archives can be found at `http://list-archive.xemacs.org'
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.8,  Next: Q1.0.9,  Prev: Q1.0.7,  Up: Introduction
+
+Q1.0.8: How do you pronounce XEmacs?
+------------------------------------
+
+The most common pronounciation is `Eks eemax'.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.9,  Next: Q1.0.10,  Prev: Q1.0.8,  Up: Introduction
+
+Q1.0.9: What does XEmacs look like?
+-----------------------------------
+
+Screen snapshots are available at
+`http://www.xemacs.org/About/Screenshots/index.html' as part of the
+XEmacs website.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.10,  Next: Q1.0.11,  Prev: Q1.0.9,  Up: Introduction
+
+Q1.0.10: Is there a port of XEmacs to Microsoft ('95 or NT)?
+------------------------------------------------------------
+
+Yes.  XEmacs can be built under MS Windows and is fully-featured and
+actively developed.  See *Note MS Windows::.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.11,  Next: Q1.0.12,  Prev: Q1.0.10,  Up: Introduction
+
+Q1.0.11: Is there a port of XEmacs to the Macintosh?
+----------------------------------------------------
+
+Yes.
+
+   XEmacs 21.5 (perhaps 21.4 also?) works on MacOS X, although it
+certainly will not feel very much like a Mac application as it has no
+Mac-specific code in it.
+
+   There is also a port of XEmacs 19.14 that works on all recent
+versions of MacOS, from 8.1 through MacOS X, by Pitts Jarvis
+<pjarvis@ispchannel.com>.  It runs in an equivalent of TTY mode only
+(one single Macintosh window, 25 colors), but has a large number of
+Mac-specific additions.  It's available at
+`http://homepage.mac.com/pjarvis/xemacs.html'.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.12,  Next: Q1.0.13,  Prev: Q1.0.11,  Up: Introduction
+
+Q1.0.12: Is there a port of XEmacs to NextStep?
+-----------------------------------------------
+
+Carl Edman, apparently no longer at <cedman@princeton.edu>, did the
+port of GNU Emacs to NeXTstep and expressed interest in doing the
+XEmacs port, but never went any farther.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.13,  Next: Q1.0.14,  Prev: Q1.0.12,  Up: Introduction
+
+Q1.0.13: Is there a port of XEmacs to OS/2?
+-------------------------------------------
+
+No, but Alexander Nikolaev <avn_1251@mail.ru> is working on it.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.0.14,  Next: Q1.1.1,  Prev: Q1.0.13,  Up: Introduction
+
+Q1.0.14: Where can I obtain a printed copy of the XEmacs User's Manual?
+-----------------------------------------------------------------------
+
+Pre-printed manuals are not available.  If you are familiar with TeX,
+you can generate your own manual from the XEmacs sources.
+
+   HTML and Postscript versions of XEmacs manuals are available from the
+XEmacs web site at `http://www.xemacs.org/Documentation/index.html'.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.1.1,  Next: Q1.1.2,  Prev: Q1.0.14,  Up: Introduction
+
+1.1: Policies
+=============
+
+Q1.1.1: What is the FAQ editorial policy?
+-----------------------------------------
+
+The FAQ is actively maintained and modified regularly.  All links should
+be up to date.  Unfortunately, some of the information is out of date -
+a situation which the FAQ maintainer is working on.  All submissions are
+welcome, please e-mail submissions to XEmacs FAQ maintainers
+<faq@xemacs.org>.
+
+   Please make sure that `XEmacs FAQ' appears on the Subject: line.  If
+you think you have a better way of answering a question, or think a
+question should be included, we'd like to hear about it.  Questions and
+answers included into the FAQ will be edited for spelling and grammar
+and will be attributed.  Answers appearing without attribution are
+either from versions of the FAQ dated before May 1996 or are from
+previous FAQ maintainers.  Answers quoted from Usenet news articles will
+always be attributed, regardless of the author.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.1.2,  Next: Q1.1.3,  Prev: Q1.1.1,  Up: Introduction
+
+Q1.1.2: How do I become a Beta Tester?
+--------------------------------------
+
+Send an email message to <xemacs-beta-request@xemacs.org> with the line
+`subscribe' in the body of the message.
+
+   Be prepared to get your hands dirty, as beta testers are expected to
+identify problems as best they can.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.1.3,  Next: Q1.2.1,  Prev: Q1.1.2,  Up: Introduction
+
+Q1.1.3: How do I contribute to XEmacs itself?
+---------------------------------------------
+
+Ben Wing <ben@xemacs.org> writes:
+
+     BTW if you have a wish list of things that you want added, you
+     have to speak up about it!  More specifically, you can do the
+     following if you want a feature added (in increasing order of
+     usefulness):
+
+        * Make a posting about a feature you want added.
+
+        * Become a beta tester and make more postings about those same
+          features.
+
+        * Convince us that you're going to use the features in some
+          cool and useful way.
+
+        * Come up with a clear and well-thought-out API concerning the
+          features.
+
+        * Write the code to implement a feature and send us a patch.
+
+     (not that we're necessarily requiring you to write the code, but
+     we can always hope :)
+
+\1f
+File: xemacs-faq.info,  Node: Q1.2.1,  Next: Q1.2.2,  Prev: Q1.1.3,  Up: Introduction
+
+1.2: Credits
+============
+
+Q1.2.1: Who wrote XEmacs?
+-------------------------
+
+XEmacs is the result of the time and effort of many people.  The
+developers responsible for recent releases are:
+
+   * Martin Buchholz <martin@xemacs.org>
+
+   * Stephen Turnbull <stephen@xemacs.org>
+
+   * Ben Wing <ben@xemacs.org>
+
+   * Hrvoje Niksic <hniksic@xemacs.org>
+
+
+   The developers responsible for older releases were:
+
+   * Steve Baur <steve@xemacs.org>
+
+   * Chuck Thompson <cthomp@xemacs.org>
+
+   * Jamie Zawinski <jwz@jwz.org>
+
+   * Richard Mlynarik <mly@adoc.xerox.com>
+
+     Steve Baur was the primary maintainer for 19.15 through 21.0.
+
+     Chuck Thompson and Ben Wing were the maintainers for 19.11 through
+     19.14 and heavy code contributors for 19.8 through 19.10.
+
+     Jamie Zawinski was the maintainer for 19.0 through 19.10 (the
+     entire history of Lucid Emacs).  Richard Mlynarik was a heavy code
+     contributor to 19.6 through 19.8.
+
+
+   Along with many other contributors, partially enumerated in the
+`About XEmacs' option in the Help menu.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.2.2,  Next: Q1.2.3,  Prev: Q1.2.1,  Up: Introduction
+
+Q1.2.2: Who contributed to this version of the FAQ?
+---------------------------------------------------
+
+The following people contributed valuable suggestions to building this
+version of the FAQ (listed in alphabetical order):
+
+   * SL Baur <steve@xemacs.org>
+
+   * Hrvoje Niksic <hniksic@xemacs.org>
+
+   * Aki Vehtari <Aki.Vehtari@hut.fi>
+
+
+\1f
+File: xemacs-faq.info,  Node: Q1.2.3,  Next: Q1.3.1,  Prev: Q1.2.2,  Up: Introduction
+
+Q1.2.3: Who contributed to the FAQ in the past?
+-----------------------------------------------
+
+This is only a partial list, as many names were lost in a hard disk
+crash some time ago.
+
+   * Curtis.N.Bingham <binge@aloft.att.com>
+
+   * Georges Brun-Cottan <bruncott@dormeur.inria.fr>
+
+   * Richard Caley <rjc@cogsci.ed.ac.uk>
+
+   * Richard Cognot <cognot@ensg.u-nancy.fr>
+
+   * Mark Daku <daku@nortel.ca>
+
+   * William G. Dubuque <wgd@martigny.ai.mit.edu>
+
+   * Eric Eide <eeide@cs.utah.edu>
+
+   * Alain Fauconnet <af@biomath.jussieu.fr>
+
+   * Chris Flatters <cflatter@nrao.edu>
+
+   * Evelyn Ginsparg <ginsparg@adra.com>
+
+   * Marty Hall <hall@aplcenmp.apl.jhu.edu>
+
+   * Darrell Kindred <dkindred@cmu.edu>
+
+   * David Moore <dmoore@ucsd.edu>
+
+   * Arup Mukherjee <arup+@cmu.edu>
+
+   * Juergen Nickelsen <nickel@prz.tu-berlin.de>
+
+   * Kevin R. Powell <powell@csl.ncsa.uiuc.edu>
+
+   * Justin Sheehy <dworkin@ccs.neu.edu>
+
+   * Stig <stig@hackvan.com>
+
+   * Aki Vehtari <Aki.Vehtari@hut.fi>
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.1,  Next: Q1.3.2,  Prev: Q1.2.3,  Up: Introduction
+
+1.3: Internationalization
+=========================
+
+Q1.3.1: What is the status of internationalization support aka MULE (including Asian language support?
+------------------------------------------------------------------------------------------------------
+
+Both the stable and development versions of XEmacs include
+internationalization support (aka MULE).  MULE currently (21.4) works on
+UNIX and Linux systems.  It is possible to build with MULE on Windows
+systems, but if you really need MULE on Windows, it is recommended that
+you build and use the development (21.5) version, and deal with the
+instability of the development tree.  Binaries compiled without MULE
+support run faster than MULE capable XEmacsen.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.2,  Next: Q1.3.3,  Prev: Q1.3.1,  Up: Introduction
+
+Q1.3.2: How can I help with internationalization?
+-------------------------------------------------
+
+If you would like to help, you may want to join the
+<xemacs-mule@xemacs.org> mailing list.  Especially needed are people
+who speak/write languages other than English, who are willing to use
+XEmacs/MULE regularly, and have some experience with Elisp.
+
+   Translations of the TUTORIAL and man page are welcome, and XEmacs
+does support multilingual menus, but we have few current translations.
+
+   *Note Q1.1.2::.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.3,  Next: Q1.3.4,  Prev: Q1.3.2,  Up: Introduction
+
+Q1.3.3: How do I type non-ASCII characters?
+-------------------------------------------
+
+See question 3.5.7 (*note Q3.5.7::) in part 3 of this FAQ for some
+simple methods that also work in non-MULE builds of XEmacs (but only for
+one-octet coded character sets, and mostly for ISO 8859/1).  Many of the
+methods available for Cyrillic (*note Q1.3.7::) work without MULE.
+MULE has more general capabilities.  *Note Q1.3.5::.
+
+   *Note Q3.2.7::, which covers display of non-ASCII characters.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.4,  Next: Q1.3.5,  Prev: Q1.3.3,  Up: Introduction
+
+Q1.3.4: Can XEmacs messages come out in a different language?
+-------------------------------------------------------------
+
+The message-catalog support was written but is badly bit-rotted.  XEmacs
+20 and 21 did _not_ support it, and early releases of XEmacs 22 will
+not either.
+
+   However, menubar localization _does_ work.  To enable it, add to
+your `Emacs' file entries like this:
+
+     Emacs*XlwMenu.resourceLabels:                   True
+     Emacs*XlwMenu.file.labelString:                 Fichier
+     Emacs*XlwMenu.openInOtherWindow.labelString:      In anderem Fenster oeffnen
+
+   The name of the resource is derived from the non-localized entry by
+removing punctuation and capitalizing as above.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.5,  Next: Q1.3.6,  Prev: Q1.3.4,  Up: Introduction
+
+Q1.3.5: Please explain the various input methods in MULE/XEmacs
+---------------------------------------------------------------
+
+Mule supports a wide variety of input methods.  There are three basic
+classes: Lisp implementations, generic platform support, and library
+interfaces.
+
+   _Lisp implementations_ include Quail, which provides table-driven
+input methods for almost all the character sets that Mule supports
+(including all of the ISO 8859 family, the Indic languages, Thai, and
+so on), and SKK, for Japanese.  (SKK also supports an interface to an
+external "dictionary server" process.)  Quail supports both typical
+"dead-key" methods (eg, in the "latin-1-prefix" method, `" a' produces
+ä, LATIN SMALL LETTER A WITH DIAERESIS), and the complex
+dictionary-based phonetic methods used for Asian ideographic languages
+like Chinese.
+
+   Lisp implementations can be less powerful (but they are not
+perceptibly inefficient), and of course are not portable to non-Emacs
+applications.  The incompatibility can be very annoying.  On the other
+hand, they require no special platform support or external libraries,
+so if you can display the characters, Mule can input them for you and
+you can edit, anywhere.
+
+   _Generic platform support_ is currently limited to the X Input
+Method (XIM) framework, although support for MSIME (for MS Windows) is
+planned, and IIIMF (Sun's Internet-Intranet Input Method Framework)
+support is extremely desirable.  XIM is enabled at build time by use of
+the `--with-xim' flag to `configure'.  For use of XIM, see your
+platform documentation.  However, normally the input method you use is
+specified via the `LANG' and `XMODIFIERS' environment variables.
+
+   Of course, input skills are portable across most applications.
+However, especially in modern GUI systems the habit of using bucky bits
+has fallen into sad disuse, and many XIM systems are poorly configured
+for use with Emacs.  For example, the kinput2 input manager (a separate
+process providing an interface between Japanese dictionary servers such
+as Canna and Wnn, and the application) tends to gobble up keystrokes
+generating Meta characters.  This means that to edit while using an XIM
+input method, you must toggle the input method off every time you want
+to use `M-f'.  Your mileage may vary.
+
+   _Library interfaces_ are most common for Japanese, although Wnn
+supports Chinese (traditional and simplified) and Korean.  There are
+Chinese and Korean input servers available, but we do not know of any
+patches for XEmacs to use them directly.  You can use them via
+IM-enabled terminals, by manipulating the terminal coding systems.  We
+describe only the Japanese-oriented systems here.  The advantage of
+these systems is that they are very powerful, and on platforms where
+they are available there is typically a wide range of applications that
+support them.  Thus your input skills are portable across applications.
+
+   Mule provides built-in interfaces to the following input methods:
+Wnn4, Wnn6, Canna, and SJ3.  These can be configured at build time.
+There are patches available (no URL, sorry) to support the SKK server,
+as well.  Wnn and SJ3 use the `egg' user interface.  The interface for
+Canna is specialized to Canna.
+
+   Wnn supports Japanese, Chinese and Korean. It is made by OMRON and
+Kyôto University. It is a powerful and complex system.  Wnn4 is free
+and Wnn6 is not.  Wnn uses grammatical hints and probability of word
+association, so in principle Wnn can be cleverer than other methods.
+
+   Canna, made by NEC, supports only Japanese.  It is a simple and
+powerful system. Canna uses only grammar, but its grammar and
+dictionary are quite sophisticated.  So for standard modern Japanese,
+Canna seems cleverer than Wnn4. In addition, the UNIX version of Canna
+is free (now there is a Microsoft Windows version).
+
+   SJ3, by Sony, supports only Japanese.
+
+   Egg consists of following parts:
+
+  1. Input character Translation System (ITS) layer.  It translates
+     ASCII inputs to Kana/PinYin/Hangul characters.
+
+  2. Kana/PinYin/Hangul to Kanji transfer layer.  The interface layer
+     to network Kana-Kanji server (Wnn and Sj3).
+
+   These input methods are modal.  They have a raw (alphabet) mode, a
+phonetic input mode, and Kana-Kanji transfer mode.  However there are
+mode-less input methods for Egg and Canna.  `boiled-egg' is a mode-less
+input method running on Egg.  For Canna, `canna.el' has a tiny
+boiled-egg-like command, `(canna-boil)', and there are some
+boiled-egg-like utilities.
+
+   Much of this information was provided by MORIOKA Tomohiko
+<morioka@jaist.ac.jp>.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.6,  Next: Q1.3.7,  Prev: Q1.3.5,  Up: Introduction
+
+Q1.3.6: How do I portably code for MULE/XEmacs?
+-----------------------------------------------
+
+MULE has evolved rapidly over the last few years, and the original third
+party patch (for GNU Emacs 19), GNU Emacs 20+, and XEmacs 20+ have quite
+different implementations.  The APIs also vary although recent versions
+of XEmacs have tended to converge to the GNU Emacs standard.
+
+   MULE implementations are going to continue to evolve.  Both GNU Emacs
+and XEmacs are working hard on Unicode support, which will involve new
+APIs and probably variations on old ones.  For XEmacs 22, the old ISO
+2022-based system for recognizing encodings will be replaced by a much
+more flexible system, which should improve accuracy of automatic coding
+detections, but will also involve new APIs.
+
+   MORIOKA Tomohiko <morioka@jaist.ac.jp> writes:
+
+     The application implementor must write separate code for these mule
+     variants.  [Please don't hesitate to report these variants to us;
+     they are not, strictly speaking, bugs, but they give third-party
+     developers the same kind of creepy-crawly feeling.  We'll do what
+     we can. - Ed.]
+
+     MULE and the next version of Emacs are similar but the symbols are
+     very different--requiring separate code as well.
+
+     Namely we must support 3 kinds of mule variants and 4 or 5 or 6
+     kinds of emacs variants... (;_;) I'm shocked, so I wrote a wrapper
+     package called `emu' to provide a common interface.  [There is an
+     XEmacs package of APEL which provides much more comprehensive
+     coverage.  Be careful, however; APEL has problems of its own. -
+     Ed.]
+
+     I have the following suggestions about dealing with mule variants:
+
+        * `(featurep 'mule)' `t' on all mule variants
+
+        * `(boundp 'MULE)' is `t' on only MULE.  Maybe the next version
+          of Emacs will not have this symbol.
+
+        * MULE has a variable `mule-version'.  Perhaps the next version
+          of Emacs will have this variable as well.
+
+     Following is a sample to distinguish mule variants:
+
+          (if (featurep 'mule)
+              (cond ((boundp 'MULE)
+                     ;; for original Mule
+                     )
+                    ((string-match "XEmacs" emacs-version)
+                     ;; for XEmacs with Mule
+                     )
+                    (t
+                     ;; for next version of Emacs
+                     ))
+            ;; for old emacs variants
+            )
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.7,  Next: Q1.3.8,  Prev: Q1.3.6,  Up: Introduction
+
+Q1.3.7: How about Cyrillic Modes?
+---------------------------------
+
+Ilya Zakharevich <ilya@math.ohio-state.edu> writes:
+
+     There is a cyrillic mode in the file `mysetup.zip' in
+     `ftp://ftp.math.ohio-state.edu/pub/users/ilya/emacs/'.  This is a
+     modification to Valery Alexeev's <ava@math.jhu.ed> `russian.el'
+     which can be obtained from
+
+   `http://www.math.uga.edu/~valery/russian.el'.
+
+   Dima Barsky <d.barsky@ee.surrey.ac.uk> writes:
+
+     There is another cyrillic mode for both GNU Emacs and XEmacs by
+     Dmitrii (Mitya) Manin <manin@camelot.mssm.edu> at
+     `http://kulichki-lat.rambler.ru/centrolit/manin/cyr.el'.
+
+   Rebecca Ore <rebecca.ore@op.net> writes:
+
+     The fullest resource I found on Russian language use (in and out of
+     XEmacs) is `http://www.ibiblio.org/sergei/Software/Software.html'
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.8,  Next: Q1.3.9,  Prev: Q1.3.7,  Up: Introduction
+
+Q1.3.8: Does XEmacs support Unicode?
+------------------------------------
+
+Partially, as an external encoding for files, processes, and terminals.
+It does not yet support Unicode fonts *Note Does XEmacs support Unicode
+Fonts?: Q1.3.9
+
+   To get Unicode support, you need a Mule-enabled XEmacs.  Install
+Mule-UCS from packages in the usual way.  Put
+
+     (require 'un-define)
+     (set-coding-priority-list '(utf-8))
+     (set-coding-category-system 'utf-8 'utf-8)
+
+   in your init file to enable the UTF-8 coding system.  You may wish to
+view the documentation of `set-coding-priority-list' if you find that
+files that are not UTF-8 are being mis-recognized as UTF-8.
+
+   Install standard national fonts (not Unicode fonts) for all
+character sets you use.  See *Note Q1.3.9::.
+
+   Mule-UCS also supports 16-bit forms of Unicode (UTF-16).  It does not
+support 31-bit forms of Unicode (UTF-32 or UCS-4).
+
+\1f
+File: xemacs-faq.info,  Node: Q1.3.9,  Next: Q1.4.1,  Prev: Q1.3.8,  Up: Introduction
+
+Q1.3.9: How does XEmacs display Unicode?
+----------------------------------------
+
+Mule doesn't have a Unicode charset internally, so there's nothing to
+bind a Unicode registry to.  It would not be straightforward to create,
+either, because Unicode is not ISO 2022-compatible.  You'd have to
+translate it to multiple 96x96 pages.
+
+   This means that Mule-UCS uses ordinary national fonts for display.
+This is not really a problem, except for those languages that use the
+Unified Han characters.  The problem here is that Mule-UCS maps from
+Unicode code points to national character sets in a deterministic way.
+By default, this means that Japanese fonts are tried first, then
+Chinese, then Korean.  To change the priority ordering, use the command
+`un-define-change-charset-order'.
+
+   It also means you can't use Unicode fonts directly, at least not
+without extreme hackery.  You can run -nw with
+(set-terminal-coding-system 'utf-8) if you really want a Unicode font
+for some reason.
+
+   Real Unicode support will be introduced in XEmacs 22.0.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.4.1,  Next: Q1.4.2,  Prev: Q1.3.9,  Up: Introduction
+
+1.4: Getting Started, Backing up & Recovery
+===========================================
+
+Q1.4.1: What is an `init.el' or `.emacs' and is there a sample one?
+-------------------------------------------------------------------
+
+The `init.el' or `.emacs' file is used to customize XEmacs to your
+tastes.  Starting in 21.4, the preferred location for the init file is
+`~/.xemacs/init.el'; in previous versions, it was `~/.emacs'.  21.4
+still accepts the old location, but the first time you run it, it will
+ask to migrate your file to the new location.  If you answer yes, the
+file will be moved, and a "compatibility" `.emacs' file will be placed
+in the old location so that you can still run older versions of XEmacs,
+and versions of GNU Emacs, which expect the old location.  The `.emacs'
+file present is just a stub that loads the real file in
+`~/.xemacs/init.el'.
+
+   No two init files are alike, nor are they expected to be alike, but
+that's the point.  The XEmacs distribution contains an excellent starter
+example in the `etc/' directory called `sample.init.el' (starting in
+21.4) or `sample.emacs' in older versions.  Copy this file from there
+to `~/.xemacs/init.el' (starting in 21.4) or `~/.emacs' in older
+versions, where `~' means your home directory, of course.  Then edit it
+to suit.
+
+   You may bring the `sample.init.el' or `sample.emacs' file into an
+XEmacs buffer from the menubar. (The menu entry for it is always under
+the `Help' menu, but its location under that has changed in various
+versions.  Recently, look under the `Samples' submenu.)  To determine
+the location of the `etc/' directory type the command `C-h v
+data-directory <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.4.2,  Next: Q1.4.3,  Prev: Q1.4.1,  Up: Introduction
+
+Q1.4.2: Can I use the same `init.el'/`.emacs' with the other Emacs?
+-------------------------------------------------------------------
+
+Yes.  The sample `init.el'/`.emacs' included in the XEmacs distribution
+will show you how to handle different versions and flavors of Emacs.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.4.3,  Next: Q1.4.4,  Prev: Q1.4.2,  Up: Introduction
+
+Q1.4.3: Any good tutorials around?
+----------------------------------
+
+There's the XEmacs tutorial available from the Help Menu under
+`Basics->Tutorials', or by typing `C-h t'. To check whether it's
+available in a non-english language, type `C-u C-h t TAB', type the
+first letters of your preferred language, then type <RET>.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.4.4,  Next: Q1.4.5,  Prev: Q1.4.3,  Up: Introduction
+
+Q1.4.4: May I see an example of a useful XEmacs Lisp function?
+--------------------------------------------------------------
+
+The following function does a little bit of everything useful.  It does
+something with the prefix argument, it examines the text around the
+cursor, and it's interactive so it may be bound to a key.  It inserts
+copies of the current word the cursor is sitting on at the cursor.  If
+you give it a prefix argument: `C-u 3 M-x double-word' then it will
+insert 3 copies.
+
+     (defun double-word (count)
+       "Insert a copy of the current word underneath the cursor"
+       (interactive "*p")
+       (let (here there string)
+         (save-excursion
+           (forward-word -1)
+           (setq here (point))
+           (forward-word 1)
+           (setq there (point))
+           (setq string (buffer-substring here there)))
+         (while (>= count 1)
+           (insert string)
+           (decf count))))
+
+   The best way to see what is going on here is to let XEmacs tell you.
+Put the code into an XEmacs buffer, and do a `C-h f' with the cursor
+sitting just to the right of the function you want explained.  Eg.  move
+the cursor to the SPACE between `interactive' and `"*p"' and hit `C-h
+f' to see what the function `interactive' does.  Doing this will tell
+you that the `*' requires a writable buffer, and `p' converts the
+prefix argument to a number, and `interactive' allows you to execute
+the command with `M-x'.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.4.5,  Next: Q1.4.6,  Prev: Q1.4.4,  Up: Introduction
+
+Q1.4.5: And how do I bind it to a key?
+--------------------------------------
+
+To bind to a key do:
+
+     (global-set-key "\C-cd" 'double-word)
+
+   Or interactively, `M-x global-set-key' and follow the prompts.
+
+\1f
+File: xemacs-faq.info,  Node: Q1.4.6,  Prev: Q1.4.5,  Up: Introduction
+
+Q1.4.6: What's the difference between a macro and a function?
+-------------------------------------------------------------
+
+Quoting from the Lisp Reference (a.k.a "Lispref") Manual:
+
+   "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.
+
+   Do not confuse the two terms with "keyboard macros", which are
+another matter, entirely.  A keyboard macro is a key bound to several
+other keys.  Refer to manual for details.
+
+\1f
+File: xemacs-faq.info,  Node: Installation,  Next: Customization,  Prev: Introduction,  Up: Top
+
+2 Installation and Trouble Shooting
+***********************************
+
+This is part 2 of the XEmacs Frequently Asked Questions list.  This
+section is devoted to Installation, Maintenance and Trouble Shooting.
+
+* Menu:
+
+Installation:
+* Q2.0.1::      Running XEmacs without installing.
+* Q2.0.2::      XEmacs is too big.
+* Q2.0.3::      Compiling XEmacs with Netaudio.
+* Q2.0.4::      Problems with Linux and ncurses.
+* Q2.0.5::      Do I need X11 to run XEmacs?
+* Q2.0.6::      I'm having strange crashes.  What do I do?
+* Q2.0.7::      Libraries in non-standard locations.
+* Q2.0.8::      can't resolve symbol _h_errno
+* Q2.0.9::      Where do I find external libraries?
+* Q2.0.10::     After I run configure I find a coredump, is something wrong?
+* Q2.0.11::     XEmacs can't resolve host names.
+* Q2.0.12::     Why can't I strip XEmacs?
+* Q2.0.13::     I don't need no steenkin' packages.  Do I?
+* Q2.0.14::     I don't want to install a million .els one at a time!
+* Q2.0.15::     EFS fails with "500 AUTH not understood" (NEW)
+* Q2.0.16::     Cygwin XEmacs won't start: cygXpm-noX4.dll was not found (NEW)
+
+Trouble Shooting:
+* Q2.1.1::      XEmacs just crashed on me!
+* Q2.1.2::      Cryptic Minibuffer messages.
+* Q2.1.3::      Translation Table Syntax messages at Startup.
+* Q2.1.4::      Startup warnings about deducing proper fonts?
+* Q2.1.5::      XEmacs cannot connect to my X Terminal.
+* Q2.1.6::      XEmacs just locked up my Linux X server.
+* Q2.1.7::      HP Alt key as Meta.
+* Q2.1.8::      got (wrong-type-argument color-instance-p nil)!
+* Q2.1.9::      XEmacs causes my OpenWindows 3.0 server to crash.
+* Q2.1.10::     Warnings from incorrect key modifiers.
+* Q2.1.11::     Can't instantiate image error... in toolbar
+* Q2.1.12::     Regular Expression Problems on DEC OSF1.
+* Q2.1.13::     HP/UX 10.10 and `create_process' failure
+* Q2.1.14::     C-g doesn't work for me.  Is it broken?
+* Q2.1.15::     How to debug an XEmacs problem with a debugger.
+* Q2.1.16::     XEmacs crashes in `strcat' on HP/UX 10.
+* Q2.1.17::     `Marker does not point anywhere'.
+* Q2.1.18::     XEmacs is outputting lots of X errors.
+* Q2.1.19::     XEmacs does not follow the local timezone.
+* Q2.1.20::     `Symbol's function definition is void: hkey-help-show.'
+* Q2.1.21::     [This question intentionally left blank]
+* Q2.1.22::     XEmacs seems to take a really long time to do some things.
+* Q2.1.23::     Movemail on Linux does not work for XEmacs 19.15 and later.
+* Q2.1.24::     XEmacs won't start without network.
+* Q2.1.25::     After upgrading, XEmacs won't do `foo' any more!
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.1,  Next: Q2.0.2,  Prev: Installation,  Up: Installation
+
+2.0: Installation
+=================
+
+Q2.0.1: Running XEmacs without installing
+-----------------------------------------
+
+How can I just try XEmacs without installing it?
+
+   XEmacs will run in place without requiring installation and copying
+of the Lisp directories, and without having to specify a special
+build-time flag.  It's the copying of the Lisp directories that
+requires so much space.  XEmacs is largely written in Lisp.
+
+   A good method is to make a shell alias for xemacs:
+
+     alias xemacs=/i/xemacs-20.2/src/xemacs
+
+   (You will obviously use whatever directory you downloaded the source
+tree to instead of `/i/xemacs-20.2').
+
+   This will let you run XEmacs without massive copying.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.2,  Next: Q2.0.3,  Prev: Q2.0.1,  Up: Installation
+
+Q2.0.2: XEmacs is too big
+-------------------------
+
+The space required by the installation directories can be reduced
+dramatically if desired.  Gzip all the .el files.  Remove all the
+packages you'll never want to use.  Remove the TexInfo manuals.  Remove
+the Info (and use just hardcopy versions of the manual).  Remove most
+of the stuff in etc.  Remove or gzip all the source code.  Gzip or
+remove the C source code.  Configure it so that copies are not made of
+the support lisp.
+
+   These are all Emacs Lisp source code and bytecompiled object code.
+You may safely gzip everything named *.el here.  You may remove any
+package you don't use.  _Nothing bad will happen if you delete a package
+that you do not use_.  You must be sure you do not use it though, so be
+conservative at first.
+
+   Any package with the possible exceptions of xemacs-base, and EFS are
+candidates for removal.  Ask yourself, _Do I ever want to use this
+package?_  If the answer is no, then it is a candidate for removal.
+
+   First, gzip all the .el files.  Then go about package by package and
+start gzipping the .elc files.  Then run XEmacs and do whatever it is
+you normally do.  If nothing bad happens, then remove the package.  You
+can remove a package via the PUI interface (`M-x pui-list-packages',
+then press `d' to mark the packages you wish to delete, and then `x' to
+delete them.
+
+   Another method is to do `M-x package-get-delete-package'.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.3,  Next: Q2.0.4,  Prev: Q2.0.2,  Up: Installation
+
+Q2.0.3: Compiling XEmacs with Netaudio.
+---------------------------------------
+
+What is the best way to compile XEmacs with the netaudio system, since I
+have got the netaudio system compiled but installed at a weird place, I
+am not root.  Also in the READMEs it does not say anything about
+compiling with the audioserver?
+
+   You should only need to add some stuff to the configure command line.
+To tell it to compile in netaudio support: `--with-sound=both', or
+`--with-sound=nas' if you don't want native sound support for some
+reason.) To tell it where to find the netaudio includes and libraries:
+
+     --site-libraries=WHATEVER
+     --site-includes=WHATEVER
+
+   Then (fingers crossed) it should compile and it will use netaudio if
+you have a server running corresponding to the X server. The netaudio
+server has to be there when XEmacs starts. If the netaudio server goes
+away and another is run, XEmacs should cope (fingers crossed, error
+handling in netaudio isn't perfect).
+
+   BTW, netaudio has been renamed as it has a name clash with something
+else, so if you see references to NAS or Network Audio System, it's the
+same thing.  It also might be found at
+`ftp://ftp.x.org/contrib/audio/nas/'.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.4,  Next: Q2.0.5,  Prev: Q2.0.3,  Up: Installation
+
+Q2.0.4: Problems with Linux and ncurses.
+----------------------------------------
+
+On Linux 1.3.98 with termcap 2.0.8 and the ncurses that came with libc
+5.2.18, XEmacs 20.0b20 is unable to open a tty device:
+
+     src/xemacs -nw -q
+     Initialization error:
+     Terminal type `xterm' undefined (or can't access database?)
+
+   Ben Wing <ben@xemacs.org> writes:
+
+     Your ncurses configuration is messed up.  Your /usr/lib/terminfo
+     is a bad pointer, perhaps to a CD-ROM that is not inserted.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.5,  Next: Q2.0.6,  Prev: Q2.0.4,  Up: Installation
+
+Q2.0.5: Do I need X11 to run XEmacs?
+------------------------------------
+
+No.  The name "XEmacs" is unfortunate in the sense that it is *not* an
+X Window System-only version of Emacs.  XEmacs has full color support
+on a color-capable character terminal.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.6,  Next: Q2.0.7,  Prev: Q2.0.5,  Up: Installation
+
+Q2.0.6: I'm having strange crashes.  What do I do?
+--------------------------------------------------
+
+There have been a variety of reports of crashes due to compilers with
+buggy optimizers.  Please see the `PROBLEMS' file that comes with
+XEmacs to read what it says about your platform.
+
+   If you compiled XEmacs using `--use-union-type' (or the option
+`USE_UNION_TYPE' in `config.inc' under Windows), try recompiling again
+without it.  The union type has been known to trigger compiler errors
+in a number of cases.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.7,  Next: Q2.0.8,  Prev: Q2.0.6,  Up: Installation
+
+Q2.0.7: Libraries in non-standard locations
+-------------------------------------------
+
+I have x-faces, jpeg, xpm etc. all in different places.  I've tried
+space-separated, comma-separated, several -site-libraries, all to no
+avail.
+
+     --site-libraries='/path/one /path/two /path/etc'
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.8,  Next: Q2.0.9,  Prev: Q2.0.7,  Up: Installation
+
+Q2.0.8: can't resolve symbol _h_errno
+-------------------------------------
+
+You are using the Linux/ELF distribution of XEmacs 19.14, and your ELF
+libraries are out of date.  You have the following options:
+
+  1. Upgrade your libc to at least 5.2.16 (better is 5.2.18, 5.3.12, or
+     5.4.10).
+
+  2. Patch the XEmacs binary by replacing all occurrences of
+     `_h_errno^@' with `h_errno^@^@'.  Any version of Emacs will
+     suffice.  If you don't understand how to do this, don't do it.
+
+  3. Rebuild XEmacs yourself--any working ELF version of libc should be
+     O.K.
+
+   Hrvoje Niksic <hniksic@xemacs.org> writes:
+
+     Why not use a Perl one-liner for No. 2?
+
+          perl -pi -e 's/_h_errno\0/h_errno\0\0/g' \
+          /usr/local/bin/xemacs-19.14
+
+     NB: You _must_ patch `/usr/local/bin/xemacs-19.14', and not
+     `xemacs' because `xemacs' is a link to `xemacs-19.14'; the Perl
+     `-i' option will cause unwanted side-effects if applied to a
+     symbolic link.
+
+   SL Baur <steve@xemacs.org> writes:
+
+     If you build against a recent libc-5.4 (late enough to have caused
+     problems earlier in the beta cycle) and then run with an earlier
+     version of libc, you get a
+
+          $ xemacs
+          xemacs: can't resolve symbol '__malloc_hook'
+          zsh: 7942 segmentation fault (core dumped)  xemacs
+
+     (Example binary compiled against libc-5.4.23 and run with
+     libc-5.4.16).
+
+     The solution is to upgrade to at least libc-5.4.23.  Sigh.  Drat.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.9,  Next: Q2.0.10,  Prev: Q2.0.8,  Up: Installation
+
+Q2.0.9: Where do I find external libraries?
+-------------------------------------------
+
+All external libraries used by XEmacs can be found at the XEmacs FTP
+site `ftp://ftp.xemacs.org/pub/xemacs/aux/'.  [These tarballs and this
+FAQ are wa-a-ay out of date.  Sorry, I'm not currently network-capable,
+and I will probably forgot to update this before submitting the patch.
+- Ed.]
+
+   The canonical locations (at the time of this writing) are as follows:
+
+JPEG
+     `ftp://ftp.uu.net/graphics/jpeg/'.  Version 6a is current.
+
+XPM
+     `ftp://ftp.x.org/contrib/libraries/'.  Version 3.4j is current.
+     Older versions of this package are known to cause XEmacs crashes.
+
+TIFF
+     `ftp://ftp.sgi.com/graphics/tiff/'.  v3.4 is current.  The latest
+     beta is v3.4b035.  There is a HOWTO here.
+
+PNG
+     `ftp://ftp.uu.net/graphics/png/'.  0.89c is current.  XEmacs
+     requires a fairly recent version to avoid using temporary files.
+
+     `ftp://swrinde.nde.swri.edu/pub/png/src/'
+
+Compface
+     `ftp://ftp.cs.indiana.edu/pub/faces/compface/'.  This library has
+     been frozen for about 6 years, and is distributed without version
+     numbers.  _It should be compiled with the same options that X11 was
+     compiled with on your system_.  The version of this library at
+     XEmacs.org includes the `xbm2xface.pl' script, written by
+     <stig@hackvan.com>, which may be useful when generating your own
+     xface.
+
+NAS
+     `ftp://ftp.x.org/contrib/audio/nas/'.  Version 1.2p5 is current.
+     There is a FAQ here.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.10,  Next: Q2.0.11,  Prev: Q2.0.9,  Up: Installation
+
+Q2.0.10: After I run configure I find a core dump, is something wrong?
+----------------------------------------------------------------------
+
+Not necessarily.  If you have GNU sed 3.0 you should downgrade it to
+2.05.  From the `README' at prep.ai.mit.edu:
+
+     sed 3.0 has been withdrawn from distribution.  It has major
+     revisions, which mostly seem to be improvements; but it turns out
+     to have bugs too which cause trouble in some common cases.
+
+     Tom Lord won't be able to work fixing the bugs until May.  So in
+     the mean time, we've decided to withdraw sed 3.0 from distribution
+     and make version 2.05 once again the recommended version.
+
+   It has also been observed that the vfork test on Solaris will leave a
+core dump.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.11,  Next: Q2.0.12,  Prev: Q2.0.10,  Up: Installation
+
+Q2.0.11: XEmacs doesn't resolve hostnames.
+------------------------------------------
+
+This is the result of a long-standing problem with SunOS and the fact
+that stock SunOS systems do not ship with DNS resolver code in libc.
+
+   Christopher Davis <ckd@loiosh.kei.com> writes:
+
+     That's correct [The SunOS 4.1.3 precompiled binaries don't do name
+     lookup].  Since Sun figured that everyone used NIS to do name
+     lookups (that DNS thing was apparently only a passing fad,
+     right?), the stock SunOS 4.x systems don't have DNS-based name
+     lookups in libc.
+
+     This is also why Netscape ships two binaries for SunOS 4.1.x.
+
+     The best solution is to compile it yourself; the configure script
+     will check to see if you've put DNS in the shared libc and will
+     then proceed to link against the DNS resolver library code.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.12,  Next: Q2.0.13,  Prev: Q2.0.11,  Up: Installation
+
+Q2.0.12: Why can't I strip XEmacs?
+----------------------------------
+
+Richard Cognot <cognot@fronsac.ensg.u-nancy.fr> writes:
+
+     Because of the way XEmacs (and every other Emacsen, AFAIK) is
+     built. The link gives you a bare-boned emacs (called temacs).
+     temacs is then run, preloading some of the lisp files. The result
+     is then dumped into a new executable, named xemacs, which will
+     contain all of the preloaded lisp functions and data.
+
+     Now, during the dump itself, the executable (code+data+symbols) is
+     written on disk using a special unexec() function. This function is
+     obviously heavily system dependent. And on some systems, it leads
+     to an executable which, although valid, cannot be stripped without
+     damage. If memory serves, this is especially the case for AIX
+     binaries. On other architectures it might work OK.
+
+     The Right Way to strip the emacs binary is to strip temacs prior to
+     dumping xemacs. This will always work, although you can do that
+     only if you install from sources (as temacs is `not' part of the
+     binary kits).
+
+   Nat Makarevitch <nat@nataa.fr.eu.org> writes:
+
+     Here is the trick:
+
+       1. [ ./configure; make ]
+
+       2. rm src/xemacs
+
+       3. strip src/temacs
+
+       4. make
+
+       5. cp src/xemacs /usr/local/bin/xemacs
+
+       6. cp lib-src/DOC-19.16-XEmacs
+          /usr/local/lib/xemacs-19.16/i586-unknown-linuxaout
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.13,  Next: Q2.0.14,  Prev: Q2.0.12,  Up: Installation
+
+Q2.0.13: I don't need no steenkin' packages.  Do I?
+---------------------------------------------------
+
+Strictly speaking, no.  XEmacs will build and install just fine without
+any packages installed.  However, only the most basic editing functions
+will be available with no packages installed, so installing packages is
+an essential part of making your installed XEmacs _useful_.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.14,  Next: Q2.0.15,  Prev: Q2.0.13,  Up: Installation
+
+Q2.0.14: How do I figure out which packages to install?
+-------------------------------------------------------
+
+Many people really liked the old way that packages were bundled and do
+not want to mess with packages at all.  You can grab all the packages at
+once like you used to with old XEmacs versions.  Download the file
+
+   `xemacs-sumo.tar.gz'
+
+   For an XEmacs compiled with Mule you also need
+
+   `xemacs-mule-sumo.tar.gz'
+
+   from the `packages' directory on your XEmacs mirror archive.  N.B.
+They are called 'Sumo Tarballs' for good reason. They are currently
+about 15MB and 2.3MB (gzipped) respectively.
+
+   Install them by
+
+   `cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xf -'
+
+   See README.packages for more detailed installation instructions.
+
+   As the Sumo tarballs are not regenerated as often as the individual
+packages, it is recommended that you use the automatic package tools
+afterwards to pick up any recent updates.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.15,  Next: Q2.0.16,  Prev: Q2.0.14,  Up: Installation
+
+Q2.0.15: EFS fails with "500 AUTH not understood" (NEW)
+-------------------------------------------------------
+
+A typical error: FTP Error: USER request failed; 500 AUTH not
+understood.
+
+   Thanks to giacomo boffi <giacomo.boffi@polimi.it> who recommends on
+comp.emacs.xemacs:
+
+   tell your ftp client to not attempt AUTH authentication (or do not
+use FTP servers that don't understand AUTH)
+
+   and notes that you need to add an element (often "-u") to
+`efs-ftp-program-args'.  Use M-x customize-variable, and verify the
+needed flag with `man ftp' or other local documentation.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.0.16,  Next: Q2.1.1,  Prev: Q2.0.15,  Up: Installation
+
+Q2.0.16: Cygwin XEmacs won't start: cygXpm-noX4.dll was not found (NEW)
+-----------------------------------------------------------------------
+
+The Cygwin binary distributed with the netinstaller uses an external DLL
+to handle XPM images (such as toolbar buttons).  You may get an error
+like
+
+   This application has failed to start because cygXpm-noX4.dll was not
+found.      Re-installing the application may fix this problem.
+
+   Andy Piper <andy@xemacs.org> sez:
+
+   cygXpm-noX4 is part of the cygwin distribution under libraries or
+graphics, but is not installed by default. You need to run the
+cygwin setup again and select this package.
+
+   Ie, reinstalling XEmacs won't help because it is not part of the
+XEmacs distribution.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.1,  Next: Q2.1.2,  Prev: Q2.0.16,  Up: Installation
+
+2.1: Trouble Shooting
+=====================
+
+Q2.1.1: Help!  XEmacs just crashed on me!
+-----------------------------------------
+
+First of all, don't panic.  Whenever XEmacs crashes, it tries extremely
+hard to auto-save all of your files before dying.  (The main time that
+this will not happen is if the machine physically lost power or if you
+killed the XEmacs process using `kill -9').  The next time you try to
+edit those files, you will be informed that a more recent auto-save
+file exists.  You can use `M-x recover-file' to retrieve the auto-saved
+version of the file.
+
+   You can use the command `M-x recover-session' after a crash to pick
+up where you left off.
+
+   Now, XEmacs is not perfect, and there may occasionally be times, or
+particular sequences of actions, that cause it to crash.  If you can
+come up with a reproducible way of doing this (or even if you have a
+pretty good memory of exactly what you were doing at the time), the
+maintainers would be very interested in knowing about it.  The best way
+to report a bug is using `M-x report-emacs-bug' (or by selecting `Send
+Bug Report...' from the Help menu).  If that won't work (e.g. you can't
+get XEmacs working at all), send ordinary mail to <crashes@xemacs.org>.
+_MAKE SURE_ to include the output from the crash, especially including
+the Lisp backtrace, as well as the XEmacs configuration from `M-x
+describe-installation' (or equivalently, the file `Installation' in the
+top of the build tree).  Please note that the `crashes' address is
+exclusively for crash reports.  The best way to report bugs in general
+is through the `M-x report-emacs-bug' interface just mentioned, or if
+necessary by emailing <xemacs-beta@xemacs.org>.  Note that the
+developers do _not_ usually follow `comp.emacs.xemacs' on a regular
+basis; thus, this is better for general questions about XEmacs than bug
+reports.
+
+   If at all possible, include a C stack backtrace of the core dump that
+was produced.  This shows where exactly things went wrong, and makes it
+much easier to diagnose problems.  To do this under Unix, you need to
+locate the core file (it's called `core', and is usually sitting in the
+directory that you started XEmacs from, or your home directory if that
+other directory was not writable).  Then, go to that directory and
+execute a command like:
+
+     gdb `which xemacs` core
+
+   and then issue the command `where' to get the stack backtrace.  You
+might have to use `dbx' or some similar debugger in place of `gdb'.  If
+you don't have any such debugger available, complain to your system
+administrator.
+
+   It's possible that a core file didn't get produced, in which case
+you're out of luck.  Go complain to your system administrator and tell
+him not to disable core files by default.  Also see *Note Q2.1.15::,
+for tips and techniques for dealing with a debugger.
+
+   If you're under Microsoft Windows, you're out of luck unless you
+happen to have a debugging aid installed on your system, for example
+Visual C++.  In this case, the crash will result in a message giving
+you the option to enter a debugger (for example, by pressing `Cancel').
+Do this and locate the stack-trace window. (If your XEmacs was built
+without debugging information, the stack trace may not be very useful.)
+
+   When making a problem report make sure that:
+
+  1. Report *all* of the information output by XEmacs during the crash.
+
+  2. You mention what O/S & Hardware you are running XEmacs on.
+
+  3. What version of XEmacs you are running.
+
+  4. What build options you are using.
+
+  5. If the problem is related to graphics and you are running Unix, we
+     will also need to know what version of the X Window System you are
+     running, and what window manager you are using.
+
+  6. If the problem happened on a TTY, please include the terminal type.
+
+   Much of the information above is automatically generated by `M-x
+report-emacs-bug'.  Even more, and often useful, information can be
+generated by redirecting the output of `make' and `make check' to a
+file (`beta.err' is the default used by `build-report'), and executing
+`M-x build-report'.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.2,  Next: Q2.1.3,  Prev: Q2.1.1,  Up: Installation
+
+Q2.1.2: Cryptic Minibuffer messages.
+------------------------------------
+
+When I try to use some particular option of some particular package, I
+get a cryptic error in the minibuffer.
+
+   If you can't figure out what's going on, select Options/General
+Options/Debug on Error from the Menubar and then try and make the error
+happen again.  This will give you a backtrace that may be enlightening.
+If not, try reading through this FAQ; if that fails, you could try
+posting to comp.emacs.xemacs (making sure to include the backtrace) and
+someone may be able to help.  If you can identify which Emacs lisp
+source file the error is coming from you can get a more detailed stack
+backtrace by doing the following:
+
+  1. Visit the .el file in an XEmacs buffer.
+
+  2. Issue the command `M-x eval-current-buffer'.
+
+  3. Reproduce the error.
+
+   Depending on the version of XEmacs, you may either select View->Show
+Message Log (recent versions), Edit->Show Messages (some earlier
+versions) or Help->Recent Keystrokes/Messages (other earlier versions)
+from the menubar to see the most recent messages.  This command is bound
+to `C-h l' by default.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.3,  Next: Q2.1.4,  Prev: Q2.1.2,  Up: Installation
+
+Q2.1.3: Translation Table Syntax messages at Startup
+----------------------------------------------------
+
+I get tons of translation table syntax error messages during startup.
+How do I get rid of them?
+
+   There are two causes of this problem.  The first usually only strikes
+people using the prebuilt binaries.  The culprit in both cases is the
+file `XKeysymDB'.
+
+   * The binary cannot find the `XKeysymDB' file.  The location is
+     hardcoded at compile time so if the system the binary was built on
+     puts it a different place than your system does, you have
+     problems.  To fix, set the environment variable `XKEYSYMDB' to the
+     location of the `XKeysymDB' file on your system or to the location
+     of the one included with XEmacs which should be at
+     `<xemacs_root_directory>/lib/xemacs-19.16/etc/XKeysymDB'.
+
+   * The binary is finding the XKeysymDB but it is out-of-date on your
+     system and does not contain the necessary lines.  Either ask your
+     system administrator to replace it with the one which comes with
+     XEmacs (which is the stock R6 version and is backwards compatible)
+     or set your `XKEYSYMDB' variable to the location of XEmacs's
+     described above.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.4,  Next: Q2.1.5,  Prev: Q2.1.3,  Up: Installation
+
+Q2.1.4: Startup warnings about deducing proper fonts?
+-----------------------------------------------------
+
+How can I avoid the startup warnings about deducing proper fonts?
+
+   This is highly dependent on your installation, but try with the
+following font as your base font for XEmacs and see what it does:
+
+-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
+
+   More precisely, do the following in your resource file:
+
+Emacs.default.attributeFont: \
+-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
+
+   If you just don't want to see the `*Warnings*' buffer at startup
+time, you can set this:
+
+     (setq display-warning-minimum-level 'error)
+
+   The buffer still exists; it just isn't in your face.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.5,  Next: Q2.1.6,  Prev: Q2.1.4,  Up: Installation
+
+Q2.1.5: XEmacs cannot connect to my X Terminal!
+-----------------------------------------------
+
+Help!  I can not get XEmacs to display on my Envizex X-terminal!
+
+   Try setting the `DISPLAY' variable using the numeric IP address of
+the host you are running XEmacs from.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.6,  Next: Q2.1.7,  Prev: Q2.1.5,  Up: Installation
+
+Q2.1.6: XEmacs just locked up my Linux X server!
+------------------------------------------------
+
+There have been several reports of the X server locking up under Linux.
+In all reported cases removing speedo and scaled fonts from the font
+path corrected the problem.  This can be done with the command `xset'.
+
+   It is possible that using a font server may also solve the problem.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.7,  Next: Q2.1.8,  Prev: Q2.1.6,  Up: Installation
+
+Q2.1.7: HP Alt key as Meta.
+---------------------------
+
+How can I make XEmacs recognize the Alt key of my HP workstation as a
+Meta key?
+
+   Put the following line into a file and load it with xmodmap(1) before
+starting XEmacs:
+
+     remove Mod1 = Mode_switch
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.8,  Next: Q2.1.9,  Prev: Q2.1.7,  Up: Installation
+
+Q2.1.8: got (wrong-type-argument color-instance-p nil)
+------------------------------------------------------
+
+Natalie Kershaw <nataliek@rd.scitec.com.au> writes:
+
+     I am trying to run xemacs 19.13 under X11R4. Whenever I move the
+     mouse I get the following error. Has anyone seen anything like
+     this? This doesn't occur on X11R5.
+
+          Signalling:
+          (error "got (wrong-type-argument color-instance-p nil)
+          and I don't know why!")
+
+   dinos <map01kd@gold.ac.uk> writes:
+
+     I think this is due to undefined resources; You need to define
+     color backgrounds and foregrounds into your
+     `.../app-defaults/Emacs' like:
+
+          *Foreground:    Black   ;everything will be of black on grey95,
+          *Background:    Grey95  ;unless otherwise specified.
+          *cursorColor:   Red3    ;red3 cursor with grey95 border.
+          *pointerColor:  Red3    ;red3 pointer with grey95 border.
+
+   Natalie Kershaw adds:
+
+     What fixed the problem was adding some more colors to the X color
+     database (copying the X11R5 colors over), and also defining the
+     following resources:
+
+          xemacs*cursorColor:    black
+          xemacs*pointerColor:   black
+
+     With the new colors installed the problem still occurs if the above
+     resources are not defined.
+
+     If the new colors are not present then an additional error occurs
+     on XEmacs startup, which says `Color Red3' not defined.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.9,  Next: Q2.1.10,  Prev: Q2.1.8,  Up: Installation
+
+Q2.1.9: XEmacs causes my OpenWindows 3.0 server to crash.
+---------------------------------------------------------
+
+The OpenWindows 3.0 server is incredibly buggy.  Your best bet is to
+replace it with one from the generic MIT X11 release.  You might also
+try disabling parts of your `init.el'/`.emacs', like those that enable
+background pixmaps.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.10,  Next: Q2.1.11,  Prev: Q2.1.9,  Up: Installation
+
+Q2.1.10: Warnings from incorrect key modifiers.
+-----------------------------------------------
+
+The following information comes from the `PROBLEMS' file that comes
+with XEmacs.
+
+   If you're having troubles with HP/UX it is because HP/UX defines the
+modifiers wrong in X.  Here is a shell script to fix the problem; be
+sure that it is run after VUE configures the X server.
+
+     #! /bin/sh
+     xmodmap 2> /dev/null - << EOF
+     keysym Alt_L = Meta_L
+     keysym Alt_R = Meta_R
+     EOF
+     
+     xmodmap - << EOF
+     clear mod1
+     keysym Mode_switch = NoSymbol
+     add mod1 = Meta_L
+     keysym Meta_R = Mode_switch
+     add mod2 = Mode_switch
+     EOF
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.11,  Next: Q2.1.12,  Prev: Q2.1.10,  Up: Installation
+
+Q2.1.11: `Can't instantiate image error...' in toolbar
+------------------------------------------------------
+
+Dr. Ram Samudrala <expt@alanine.ram.org> writes:
+
+   I just installed the XEmacs (20.4-2) RPMS that I downloaded from
+`http://www.xemacs.org/'.  Everything works fine, except that when I
+place my mouse over the toolbar, it beeps and gives me this message:
+
+      Can't instantiate image (probably cached):
+      [xbm :mask-file "/usr/include/X11/bitmaps/leftptrmsk :mask-data
+      (16 16 <strange control characters> ...
+
+   Kyle Jones <kyle_jones@wonderworks.com> writes:
+
+     This is problem specific to some Chips and Technologies video
+     chips, when running XFree86.  Putting
+
+     `Option "sw_cursor"'
+
+     in `XF86Config' gets rid of the problem.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.12,  Next: Q2.1.13,  Prev: Q2.1.11,  Up: Installation
+
+Q2.1.12: Problems with Regular Expressions on DEC OSF1.
+-------------------------------------------------------
+
+I have xemacs 19.13 running on an alpha running OSF1 V3.2 148 and ispell
+would not run because it claimed the version number was incorrect
+although it was indeed OK. I traced the problem to the regular
+expression handler.
+
+   Douglas Kosovic <douglask@dstc.edu.au> writes:
+
+     Actually it's a DEC cc optimization bug that screws up the regexp
+     handling in XEmacs.
+
+     Rebuilding using the `-migrate' switch for DEC cc (which uses a
+     different sort of optimization) works fine.
+
+   See `xemacs-19_13-dunix-3_2c.patch' at the following URL on how to
+build with the `-migrate' flag:
+
+     `http://www-digital.cern.ch/carney/emacs/emacs.html'
+
+   NOTE: There have been a variety of other problems reported that are
+fixed in this fashion.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.13,  Next: Q2.1.14,  Prev: Q2.1.12,  Up: Installation
+
+Q2.1.13: HP/UX 10.10 and `create_process' failure.
+--------------------------------------------------
+
+Dave Carrigan <Dave.Carrigan@ipl.ca> writes:
+
+     With XEmacs 19.13 and HP/UX 10.10, anything that relies on the
+     `create_process' function fails. This breaks a lot of things
+     (shell-mode, compile, ange-ftp, to name a few).
+
+   Phil Johnson <johnson@dtc.hp.com> writes:
+
+     This is a problem specific to HP-UX 10.10.  It only occurs when
+     XEmacs is compiled for shared libraries (the default), so you can
+     work around it by compiling a statically-linked binary (run
+     configure with `--dynamic=no').
+
+     I'm not sure whether the problem is with a particular shared
+     library or if it's a kernel problem which crept into 10.10.
+
+   Richard Cognot <cognot@ensg.u-nancy.fr> writes:
+
+     I had a few problems with 10.10. Apparently, some of them were
+     solved by forcing a static link of libc (manually).
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.14,  Next: Q2.1.15,  Prev: Q2.1.13,  Up: Installation
+
+Q2.1.14: `C-g' doesn't work for me.  Is it broken?
+--------------------------------------------------
+
+Ben Wing <ben@xemacs.org> writes:
+
+     `C-g' does work for most people in most circumstances.  If it
+     doesn't, there are only two explanations:
+
+       1. The code is wrapped with a binding of `inhibit-quit' to `t'.
+          `Ctrl-Shift-G' should still work, I think.
+
+       2. SIGIO is broken on your system, but BROKEN_SIGIO isn't
+          defined.
+
+     To test #2, try executing `(while t)' from the `*scratch*' buffer.
+     If `C-g' doesn't interrupt, then you're seeing #2.
+
+   Morten Welinder <terra@diku.dk> writes:
+
+     On some (but _not_ all) machines a hung XEmacs can be revived by
+     `kill -FPE <pid>'.  This is a hack, of course, not a solution.
+     This technique works on a Sun4 running 4.1.3_U1.  To see if it
+     works for you, start another XEmacs and test with that first.  If
+     you get a core dump the method doesn't work and if you get
+     `Arithmetic error' then it does.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.15,  Next: Q2.1.16,  Prev: Q2.1.14,  Up: Installation
+
+Q2.1.15: How to debug an XEmacs problem with a debugger
+-------------------------------------------------------
+
+If XEmacs does crash on you, one of the most productive things you can
+do to help get the bug fixed is to poke around a bit with the debugger.
+Here are some hints:
+
+   * First of all, if the crash is at all reproducible, consider very
+     strongly recompiling your XEmacs with debugging symbols and with no
+     optimization (e.g. with GCC use the compiler flags `-g -O0' -
+     that's an "oh" followed by a zero), and with the configure options
+     `--debug=yes' and `--error-checking=all'.  This will make your
+     XEmacs run somewhat slower, but you are a lot more likely to catch
+     the problem earlier (closer to its source).  It makes it a lot
+     easier to determine what's going on with a debugger.
+
+   * If it's not a true crash (_i.e._, XEmacs is hung, or a zombie
+     process), or it's inconvenient to run XEmacs again because XEmacs
+     is already running or is running in batch mode as part of a bunch
+     of scripts, you may be able to attach to the existing process with
+     your debugger.  Most debuggers let you do this by substituting the
+     process ID for the core file when you invoke the debugger from the
+     command line, or by using the `attach' command or something
+     similar.
+
+   * If you're able to run XEmacs under a debugger and reproduce the
+     crash, here are some things you can do:
+
+   * If XEmacs is hitting an assertion failure, put a breakpoint on
+     `assert_failed()'.
+
+   * If XEmacs is hitting some weird Lisp error that's causing it to
+     crash (e.g. during startup), put a breakpoint on
+     `signal_1()'--this is declared static in eval.c.
+
+   * If XEmacs is outputting lots of X errors, put a breakpoint on
+     `x_error_handler()'; that will tell you which call is causing them.
+
+   * Internally, you will probably see lots of variables that hold
+     objects of type `Lisp_Object'.  These are references to Lisp
+     objects.  Printing them out with the debugger probably won't be too
+     useful--you'll likely just see a number.  To decode them, do this:
+
+          call dp (OBJECT)
+
+     where OBJECT is whatever you want to decode (it can be a variable,
+     a function call, etc.).  This uses the Lisp printing routines to
+     out a readable representation on the TTY from which the xemacs
+     process was invoked.
+
+   * If you want to get a Lisp backtrace showing the Lisp call stack,
+     do this:
+
+          call db ()
+
+   * Using `dp' and `db' has two disadvantages - they can only be used
+     with a running (including hung or zombie) xemacs process, and they
+     do not display the internal C structure of a Lisp Object.  Even if
+     all you've got is a core dump, all is not lost.
+
+     If you're using GDB, there are some macros in the file
+     `src/.gdbinit' in the XEmacs source distribution that should make
+     it easier for you to decode Lisp objects.  This file is
+     automatically read by gdb if gdb is run in the directory where
+     xemacs was built, and contains these useful macros to inspect the
+     state of xemacs:
+
+    `pobj'
+          Usage: pobj lisp_object
+          Print the internal C representation of a lisp object.
+
+    `xtype'
+          Usage: xtype lisp_object
+          Print the Lisp type of a lisp object.
+
+    `lbt'
+          Usage: lbt
+          Print the current Lisp stack trace.  Requires a running
+          xemacs process.  (It works by calling the db routine
+          described above.)
+
+    `ldp'
+          Usage: ldp lisp_object
+          Print a Lisp Object value using the Lisp printer.  Requires a
+          running xemacs process.  (It works by calling the dp routine
+          described above.)
+
+    `run-temacs'
+          Usage: run-temacs
+          Run temacs interactively, like xemacs.  Use this with
+          debugging tools (like purify) that cannot deal with dumping,
+          or when temacs builds successfully, but xemacs does not.
+
+    `dump-temacs'
+          Usage: dump-temacs
+          Run the dumping part of the build procedure.  Use when
+          debugging temacs, not xemacs!  Use this when temacs builds
+          successfully, but xemacs does not.
+
+    `check-xemacs'
+          Usage: check-xemacs
+          Run the test suite.  Equivalent to 'make check'.
+
+    `check-temacs'
+          Usage: check-temacs
+          Run the test suite on temacs.  Equivalent to 'make
+          check-temacs'.  Use this with debugging tools (like purify)
+          that cannot deal with dumping, or when temacs builds
+          successfully, but xemacs does not.
+
+     If you are using Sun's `dbx' debugger, there is an equivalent file
+     `src/.dbxrc', which defines the same commands for dbx.
+
+   * If you're using a debugger to get a C stack backtrace and you're
+     seeing stack traces with some of the innermost frames mangled, it
+     may be due to dynamic linking. (This happens especially under
+     Linux.) Consider reconfiguring with `--dynamic=no'.  Also,
+     sometimes (again under Linux), stack backtraces of core dumps will
+     have the frame where the fatal signal occurred mangled; if you can
+     obtain a stack trace while running the XEmacs process under a
+     debugger, the stack trace should be clean.
+
+     Curtiss <1CMC3466@ibm.mtsac.edu> suggests upgrading to ld.so
+     version 1.8 if dynamic linking and debugging is a problem on Linux.
+
+   * If you're using a debugger to get a C stack backtrace and you're
+     getting a completely mangled and bogus stack trace, it's probably
+     due to one of the following:
+
+       a. Your executable has been stripped.  Bad news.  Tell your
+          sysadmin not to do this--it doesn't accomplish anything
+          except to save a bit of disk space, and makes debugging much
+          much harder.
+
+       b. Your stack is getting trashed.  Debugging this is hard; you
+          have to do a binary-search type of narrowing down where the
+          crash occurs, until you figure out exactly which line is
+          causing the problem.  Of course, this only works if the bug
+          is highly reproducible.  Also, in many cases if you run
+          XEmacs from the debugger, the debugger can protect the stack
+          somewhat.  However, if the stack is being smashed, it is
+          typically the case that there is a wild pointer somewhere in
+          the program, often quite far from where the crash occurs.
+
+       c. If your stack trace has exactly one frame in it, with address
+          0x0, this could simply mean that XEmacs attempted to execute
+          code at that address, e.g. through jumping to a null function
+          pointer.  Unfortunately, under those circumstances, GDB under
+          Linux doesn't know how to get a stack trace. (Yes, this is
+          the fourth Linux-related problem I've mentioned.  I have no
+          idea why GDB under Linux is so bogus.  Complain to the GDB
+          authors, or to comp.os.linux.development.system.) Again,
+          you'll have to use the narrowing-down process described above.
+
+       d. You will get a Lisp backtrace output when XEmacs crashes, so
+          you'll have something useful.
+
+
+   * If you compile with the newer gcc variants gcc-2.8 or egcs, you
+     will also need gdb 4.17 or above.  Earlier releases of gdb can't
+     handle the debug information generated by the newer compilers.
+
+   * In versions of XEmacs before 21.2.27, `src/.gdbinit' was named
+     `src/gdbinit'.  This had the disadvantage of not being sourced
+     automatically by gdb, so you had to set that up yourself.
+
+   * If you are running Microsoft Windows, the the file `nt/README' for
+     further information about debugging XEmacs.
+
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.16,  Next: Q2.1.17,  Prev: Q2.1.15,  Up: Installation
+
+Q2.1.16: XEmacs crashes in `strcat' on HP/UX 10
+-----------------------------------------------
+
+From the problems database (through the former address
+http://support.mayfield.hp.com/):
+
+     Problem Report: 5003302299
+     Status:         Open
+     
+     System/Model:   9000/700
+     Product Name:   HPUX S800 10.0X
+     Product Vers:   9245XB.10.00
+     
+     Description: strcat(3C) may read beyond
+     end of source string, can cause SIGSEGV
+     
+     
+     *** PROBLEM TEXT ***
+     strcat(3C) may read beyond the source string onto an unmapped page,
+     causing a segmentation violation.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.17,  Next: Q2.1.18,  Prev: Q2.1.16,  Up: Installation
+
+Q2.1.17: `Marker does not point anywhere'
+-----------------------------------------
+
+As with other errors, set `debug-on-error' to `t' to get the backtrace
+when the error occurs.  Specifically, two problems have been reported
+(and fixed).
+
+  1. A problem with line-number-mode in XEmacs 19.14 affected a large
+     number of other packages.  If you see this error message, turn off
+     line-number-mode.
+
+  2. A problem with some early versions of Gnus 5.4 caused this error.
+     Upgrade your Gnus.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.18,  Next: Q2.1.19,  Prev: Q2.1.17,  Up: Installation
+
+Q2.1.18: XEmacs is outputting lots of X errors.
+-----------------------------------------------
+
+If this is happening, we would very much like to know what's causing
+them.  To find this out, see *Note Q2.1.15::.  Try to get both a C and
+Lisp backtrace, and send them to <xemacs-beta@xemacs.org>.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.19,  Next: Q2.1.20,  Prev: Q2.1.18,  Up: Installation
+
+Q2.1.19: XEmacs does not follow the local timezone.
+---------------------------------------------------
+
+When using one of the prebuilt binaries many users have observed that
+XEmacs uses the timezone under which it was built, but not the timezone
+under which it is running.  The solution is to add:
+
+     (set-time-zone-rule "MET")
+
+   to your `init.el'/`.emacs' or the `site-start.el' file if you can.
+Replace `MET' with your local timezone.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.20,  Next: Q2.1.21,  Prev: Q2.1.19,  Up: Installation
+
+Q2.1.20: `Symbol's function definition is void: hkey-help-show.'
+----------------------------------------------------------------
+
+This is a problem with a partially loaded hyperbole.  Try adding:
+
+     (require 'hmouse-drv)
+
+   where you load hyperbole and the problem should go away.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.21,  Next: Q2.1.22,  Prev: Q2.1.20,  Up: Installation
+
+Q2.1.21: [This question intentionally left blank]
+-------------------------------------------------
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.22,  Next: Q2.1.23,  Prev: Q2.1.21,  Up: Installation
+
+Q2.1.22: XEmacs seems to take a really long time to do some things
+------------------------------------------------------------------
+
+David Moore <dmoore@ucsd.edu> writes:
+
+     Two things you can do:
+
+     1) C level:
+
+     When you see it going mad like this, you might want to use gdb
+     from an 'xterm' to attach to the running process and get a stack
+     trace.  To do this just run:
+
+          gdb /path/to/xemacs/xemacs ####
+
+     Where `####' is the process id of your xemacs, instead of
+     specifying the core.  When gdb attaches, the xemacs will stop [1]
+     and you can type `where' in gdb to get a stack trace as usual.  To
+     get things moving again, you can just type `quit' in gdb.  It'll
+     tell you the program is running and ask if you want to quit
+     anyways.  Say 'y' and it'll quit and have your emacs continue from
+     where it was at.
+
+     2) Lisp level:
+
+     Turn on debug-on-quit early on.  When you think things are going
+     slow hit C-g and it may pop you in the debugger so you can see
+     what routine is running.  Press `c' to get going again.
+
+     debug-on-quit doesn't work if something's turned on inhibit-quit
+     or in some other strange cases.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.23,  Next: Q2.1.24,  Prev: Q2.1.22,  Up: Installation
+
+Q2.1.23:  Movemail on Linux does not work for XEmacs 19.15 and later.
+---------------------------------------------------------------------
+
+Movemail used to work fine in 19.14 but has stopped working in 19.15
+and 20.x.  I am using Linux.
+
+   SL Baur <steve@xemacs.org> writes:
+
+     Movemail on Linux used to default to using flock file locking.
+     With 19.15 and later versions it now defaults to using `.lock' file
+     locking.  If this is not appropriate for your system, edit
+     src/s/linux.h and uncomment the line that reads:
+
+          #define MAIL_USE_FLOCK
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.24,  Next: Q2.1.25,  Prev: Q2.1.23,  Up: Installation
+
+Q2.1.24:  XEmacs won't start without network.
+---------------------------------------------
+
+If XEmacs starts when you're on the network, but fails when you're not
+on the network, you may be missing a "localhost" entry in your
+`/etc/hosts' file.  The file should contain an entry like:
+
+     127.0.0.1        localhost
+
+   Add that line, and XEmacs will be happy.
+
+\1f
+File: xemacs-faq.info,  Node: Q2.1.25,  Prev: Q2.1.24,  Up: Installation
+
+Q2.1.25::  After upgrading, XEmacs won't do `foo' any more!
+-----------------------------------------------------------
+
+You have been used to doing `foo', but now when you invoke it (or click
+the toolbar button or select the menu item), nothing (or an error)
+happens.  The simplest explanation is that you are missing a package
+that is essential to you.  You can either track it down and install it
+(there is a list of packages and brief descriptions of their contents in
+`etc/PACKAGES'), or install the `Sumo Tarball' (*note Q2.0.14::).
+
+\1f
+File: xemacs-faq.info,  Node: Customization,  Next: Subsystems,  Prev: Installation,  Up: Top
+
+3 Customization and Options
+***************************
+
+This is part 3 of the XEmacs Frequently Asked Questions list.  This
+section is devoted to Customization and screen settings.
+
+* Menu:
+
+Customization---Emacs Lisp and `init.el'/`.emacs':
+* Q3.0.1::      What version of Emacs am I running?
+* Q3.0.2::      How do I evaluate Elisp expressions?
+* Q3.0.3::      `(setq tab-width 6)' behaves oddly.
+* Q3.0.4::      How can I add directories to the `load-path'?
+* Q3.0.5::      How to check if a lisp function is defined?
+* Q3.0.6::      Can I force the output of `(face-list)' to a buffer?
+* Q3.0.7::      Font selections don't get saved after `Save Options'.
+* Q3.0.8::      How do I make a single minibuffer frame?
+* Q3.0.9::      What is `Customize'?
+
+X Window System & Resources:
+* Q3.1.1::      Where is a list of X resources?
+* Q3.1.2::      How can I detect a color display?
+* Q3.1.3::      [This question intentionally left blank]
+* Q3.1.4::      [This question intentionally left blank]
+* Q3.1.5::      How can I get the icon to just say `XEmacs'?
+* Q3.1.6::      How can I have the window title area display the full path?
+* Q3.1.7::      `xemacs -name junk' doesn't work?
+* Q3.1.8::      `-iconic' doesn't work.
+
+Textual Fonts & Colors:
+* Q3.2.1::      How can I set color options from `init.el'/`.emacs'?
+* Q3.2.2::      How do I set the text, menu and modeline fonts?
+* Q3.2.3::      How can I set the colors when highlighting a region?
+* Q3.2.4::      How can I limit color map usage?
+* Q3.2.5::      My tty supports color, but XEmacs doesn't use them.
+* Q3.2.6::      Can I have pixmap backgrounds in XEmacs?
+* Q3.2.7::      How do I display non-ASCII characters?
+
+The Modeline:
+* Q3.3.1::      How can I make the modeline go away?
+* Q3.3.2::      How do you have XEmacs display the line number in the modeline?
+* Q3.3.3::      How do I get XEmacs to put the time of day on the modeline?
+* Q3.3.4::      How do I turn off current chapter from AUC TeX modeline?
+* Q3.3.5::      How can one change the modeline color based on the mode used?
+
+3.4 Multiple Device Support:
+* Q3.4.1::      How do I open a frame on another screen of my multi-headed display?
+* Q3.4.2::      Can I really connect to a running XEmacs after calling up over a modem?  How?
+
+3.5 The Keyboard:
+* Q3.5.1::      How can I bind complex functions (or macros) to keys?
+* Q3.5.2::      How can I stop down-arrow from adding empty lines to the bottom of my buffers?
+* Q3.5.3::      How do I bind C-. and C-; to scroll one line up and down?
+* Q3.5.4::      Globally binding Delete?
+* Q3.5.5::      Scrolling one line at a time.
+* Q3.5.6::      How to map Help key alone on Sun type4 keyboard?
+* Q3.5.7::      How can you type in special characters in XEmacs?
+* Q3.5.8::      [This question intentionally left blank]
+* Q3.5.9::      How do I make the Delete key delete forward?
+* Q3.5.10::     Can I turn on "sticky" modifier keys?
+* Q3.5.11::     How do I map the arrow keys?
+
+The Cursor:
+* Q3.6.1::      Is there a way to make the bar cursor thicker?
+* Q3.6.2::      Is there a way to get back the old block cursor where the cursor covers the character in front of the point?
+* Q3.6.3::      Can I make the cursor blink?
+
+The Mouse and Highlighting:
+* Q3.7.1::      How can I turn off Mouse pasting?
+* Q3.7.2::      How do I set control/meta/etc modifiers on mouse buttons?
+* Q3.7.3::      Clicking the left button does not do anything in buffer list.
+* Q3.7.4::      How can I get a list of buffers when I hit mouse button 3?
+* Q3.7.5::      Why does cut-and-paste not work between XEmacs and a cmdtool?
+* Q3.7.6::      How I can set XEmacs up so that it pastes where the text cursor is?
+* Q3.7.7::      How do I select a rectangular region?
+* Q3.7.8::      Why does M-w take so long?
+
+The Menubar and Toolbar:
+* Q3.8.1::      How do I get rid of the menu (or menubar)?
+* Q3.8.2::      Can I customize the basic menubar?
+* Q3.8.3::      How do I control how many buffers are listed in the menu `Buffers' list?
+* Q3.8.4::      Resources like `Emacs*menubar*font' are not working?
+* Q3.8.5::      How can I bind a key to a function to toggle the toolbar?
+
+Scrollbars:
+* Q3.9.1::      How can I disable the scrollbar?
+* Q3.9.2::      How can one use resources to change scrollbar colors?
+* Q3.9.3::      Moving the scrollbar can move the point; can I disable this?
+* Q3.9.4::      How can I turn off automatic horizontal scrolling in specific modes?
+
+Text Selections:
+* Q3.10.1::     How can I turn off or change highlighted selections?
+* Q3.10.2::     How do I get that typing on an active region removes it?
+* Q3.10.3::     Can I turn off the highlight during isearch?
+* Q3.10.4::     How do I turn off highlighting after C-x C-p (mark-page)?
+* Q3.10.5::     The region disappears when I hit the end of buffer while scrolling.
+* Q3.10.6::     Why is killing so slow?
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.1,  Next: Q3.0.2,  Prev: Customization,  Up: Customization
+
+3.0: Customization - Emacs Lisp and `init.el'/`.emacs'
+======================================================
+
+Q3.0.1: What version of Emacs am I running?
+-------------------------------------------
+
+How can `init.el'/`.emacs' determine which of the family of Emacsen I
+am using?
+
+   To determine if you are currently running GNU Emacs 18, GNU Emacs 19,
+XEmacs 19, XEmacs 20, or Epoch, and use appropriate code, check out the
+example given in `etc/sample.init.el' (`etc/sample.emacs' in XEmacs
+versions prior to 21.4).  There are other nifty things in there as well!
+
+   For all new code, all you really need to do is:
+
+     (defvar running-xemacs (string-match "XEmacs\\|Lucid" emacs-version))
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.2,  Next: Q3.0.3,  Prev: Q3.0.1,  Up: Customization
+
+Q3.0.2: How can I evaluate Emacs-Lisp expressions?
+--------------------------------------------------
+
+I know I can evaluate Elisp expressions from `*scratch*' buffer with
+`C-j' after the expression.  How do I do it from another buffer?
+
+   Press `M-:' (the default binding of `eval-expression'), and enter
+the expression to the minibuffer.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.3,  Next: Q3.0.4,  Prev: Q3.0.2,  Up: Customization
+
+Q3.0.3: `(setq tab-width 6)' behaves oddly.
+-------------------------------------------
+
+If you put `(setq tab-width 6)' in your `init.el'/`.emacs' file it does
+not work!  Is there a reason for this?  If you do it at the EVAL prompt
+it works fine!! How strange.
+
+   Use `setq-default' instead, since `tab-width' is all-buffer-local.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.4,  Next: Q3.0.5,  Prev: Q3.0.3,  Up: Customization
+
+Q3.0.4: How can I add directories to the `load-path'?
+-----------------------------------------------------
+
+Here are two ways to do that, one that puts your directories at the
+front of the load-path, the other at the end:
+
+     ;;; Add things at the beginning of the load-path, do not add
+     ;;; duplicate directories:
+     (pushnew "bar" load-path :test 'equal)
+     
+     (pushnew "foo" load-path :test 'equal)
+     
+     ;;; Add things at the end, unconditionally
+     (setq load-path (nconc load-path '("foo" "bar")))
+
+   keith (k.p.) hanlan <keithh@nortel.ca> writes:
+
+     To add directories using Unix shell metacharacters use
+     `expand-file-name' like this:
+
+          (push (expand-file-name "~keithh/.emacsdir") load-path)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.5,  Next: Q3.0.6,  Prev: Q3.0.4,  Up: Customization
+
+Q3.0.5: How to check if a lisp function is defined?
+---------------------------------------------------
+
+Use the following elisp:
+
+     (fboundp 'foo)
+
+   It's almost always a mistake to test `emacs-version' or any similar
+variables.
+
+   Instead, use feature-tests, such as `featurep', `boundp', `fboundp',
+or even simple behavioral tests, eg.:
+
+     (defvar foo-old-losing-code-p
+       (condition-case nil (progn (losing-code t) nil)
+         (wrong-number-of-arguments t)))
+
+   There is an incredible amount of broken code out there which could
+work much better more often in more places if it did the above instead
+of trying to divine its environment from the value of one variable.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.6,  Next: Q3.0.7,  Prev: Q3.0.5,  Up: Customization
+
+Q3.0.6: Can I force the output of `(face-list)' to a buffer?
+------------------------------------------------------------
+
+It would be good having it in a buffer, as the output of `(face-list)'
+is too wide to fit to a minibuffer.
+
+   Evaluate the expression in the `*scratch*' buffer with point after
+the rightmost paren and typing `C-j'.
+
+   If the minibuffer smallness is the only problem you encounter, you
+can simply press `C-h l' to get the former minibuffer contents in a
+buffer.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.7,  Next: Q3.0.8,  Prev: Q3.0.6,  Up: Customization
+
+Q3.0.7: Font selections in don't get saved after `Save Options'.
+----------------------------------------------------------------
+
+John Mann <mannj@ll.mit.edu> writes:
+
+     You have to go to Options->Frame Appearance and unselect
+     `Frame-Local Font Menu'.  If this option is selected, font changes
+     are only applied to the _current_ frame and do _not_ get saved
+     when you save options.
+
+   Also, set the following in your `init.el'/`.emacs':
+
+     (setq options-save-faces t)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.8,  Next: Q3.0.9,  Prev: Q3.0.7,  Up: Customization
+
+Q3.0.8: How do I get a single minibuffer frame?
+-----------------------------------------------
+
+Vin Shelton <acs@acm.org> writes:
+
+     (setq initial-frame-plist '(minibuffer nil))
+     (setq default-frame-plist '(minibuffer nil))
+     (setq default-minibuffer-frame
+           (make-frame
+            '(minibuffer only
+                         width 86
+                         height 1
+                         menubar-visible-p nil
+                         default-toolbar-visible-p nil
+                         name "minibuffer"
+                         top -2
+                         left -2
+                         has-modeline-p nil)))
+     (frame-notice-user-settings)
+
+   *Please note:* The single minibuffer frame may not be to everyone's
+taste, and there any number of other XEmacs options settings that may
+make it difficult or inconvenient to use.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.0.9,  Next: Q3.1.1,  Prev: Q3.0.8,  Up: Customization
+
+Q3.0.9: What is `Customize'?
+----------------------------
+
+Starting with XEmacs 20.2 there is new system 'Customize' for
+customizing XEmacs options.
+
+   You can access `Customize' from the `Options' menu or invoking one
+of customize commands by typing eg.  `M-x customize', `M-x
+customize-face', `M-x customize-variable' or `M-x customize-apropos'.
+
+   Starting with XEmacs 20.3 there is also new `browser' mode for
+Customize.  Try it out with `M-x customize-browse'
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.1,  Next: Q3.1.2,  Prev: Q3.0.9,  Up: Customization
+
+3.1: X Window System & Resources
+================================
+
+Q3.1.1: Where is a list of X resources?
+---------------------------------------
+
+Search through the `NEWS' file for `X Resources'.  A fairly
+comprehensive list is given after it.
+
+   In addition, an `app-defaults' file `etc/Emacs.ad' is supplied,
+listing the defaults.  The file `etc/sample.Xresources' gives a
+different set of defaults that you might consider for installation in
+your `~/.Xresources' file.  It is nearly the same as `etc/Emacs.ad',
+but a few entries are altered.  Be careful about installing the
+contents of this file into your `.Xresources' (or legacy `.Xdefaults')
+file if you use GNU Emacs under X11 as well.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.2,  Next: Q3.1.3,  Prev: Q3.1.1,  Up: Customization
+
+Q3.1.2: How can I detect a color display?
+-----------------------------------------
+
+You can test the return value of the function `(device-class)', as in:
+
+     (when (eq (device-class) 'color)
+       (set-face-foreground  'font-lock-comment-face "Grey")
+       (set-face-foreground  'font-lock-string-face  "Red")
+       ....
+       )
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.3,  Next: Q3.1.4,  Prev: Q3.1.2,  Up: Customization
+
+Q3.1.3: [This question intentionally left blank]
+------------------------------------------------
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.4,  Next: Q3.1.5,  Prev: Q3.1.3,  Up: Customization
+
+Q3.1.4: [This question intentionally left blank]
+------------------------------------------------
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.5,  Next: Q3.1.6,  Prev: Q3.1.4,  Up: Customization
+
+Q3.1.5: How can I get the icon to just say `XEmacs'?
+----------------------------------------------------
+
+I'd like the icon to just say `XEmacs', and not include the name of the
+current file in it.
+
+   Add the following line to your `init.el'/`.emacs':
+
+     (setq frame-icon-title-format "XEmacs")
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.6,  Next: Q3.1.7,  Prev: Q3.1.5,  Up: Customization
+
+Q3.1.6: How can I have the window title area display the full path?
+-------------------------------------------------------------------
+
+I'd like to have the window title area display the full directory/name
+of the current buffer file and not just the name.
+
+   Add the following line to your `init.el'/`.emacs':
+
+     (setq frame-title-format "%S: %f")
+
+   A more sophisticated title might be:
+
+     (setq frame-title-format
+           '("%S: " (buffer-file-name "%f"
+                                      (dired-directory dired-directory "%b"))))
+
+   That is, use the file name, or the dired-directory, or the buffer
+name.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.7,  Next: Q3.1.8,  Prev: Q3.1.6,  Up: Customization
+
+Q3.1.7: `xemacs -name junk' doesn't work?
+-----------------------------------------
+
+When I run `xterm -name junk', I get an xterm whose class name
+according to xprop, is `junk'.  This is the way it's supposed to work,
+I think.  When I run `xemacs -name junk' the class name is not set to
+`junk'.  It's still `emacs'.  What does `xemacs -name' really do?  The
+reason I ask is that my window manager (fvwm) will make a window sticky
+and I use XEmacs to read my mail.  I want that XEmacs window to be
+sticky, without having to use the window manager's function to set the
+window sticky.  What gives?
+
+   `xemacs -name' sets the application name for the program (that is,
+the thing which normally comes from `argv[0]').  Using `-name' is the
+same as making a copy of the executable with that new name.  The
+`WM_CLASS' property on each frame is set to the frame-name, and the
+application-class.  So, if you did `xemacs -name FOO' and then created
+a frame named BAR, you'd get an X window with WM_CLASS = `( "BAR",
+"Emacs")'.  However, the resource hierarchy for this widget would be:
+
+     Name:    FOO   .shell             .container   .BAR
+     Class:   Emacs .TopLevelEmacsShell.EmacsManager.EmacsFrame
+
+   instead of the default
+
+     Name:    xemacs.shell             .container   .emacs
+     Class:   Emacs .TopLevelEmacsShell.EmacsManager.EmacsFrame
+
+   It is arguable that the first element of WM_CLASS should be set to
+the application-name instead of the frame-name, but I think that's less
+flexible, since it does not give you the ability to have multiple frames
+with different WM_CLASS properties.  Another possibility would be for
+the default frame name to come from the application name instead of
+simply being `emacs'.  However, at this point, making that change would
+be troublesome: it would mean that many users would have to make yet
+another change to their resource files (since the default frame name
+would suddenly change from `emacs' to `xemacs', or whatever the
+executable happened to be named), so we'd rather avoid it.
+
+   To make a frame with a particular name use:
+
+     (make-frame '((name . "the-name")))
+
+\1f
+File: xemacs-faq.info,  Node: Q3.1.8,  Next: Q3.2.1,  Prev: Q3.1.7,  Up: Customization
+
+Q3.1.8: `-iconic' doesn't work.
+-------------------------------
+
+When I start up XEmacs using `-iconic' it doesn't work right.  Using
+`-unmapped' on the command line, and setting the `initiallyUnmapped' X
+Resource don't seem to help much either...
+
+   Ben Wing <ben@xemacs.org> writes:
+
+     Ugh, this stuff is such an incredible mess that I've about given up
+     getting it to work.  The principal problem is numerous
+     window-manager bugs...
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.1,  Next: Q3.2.2,  Prev: Q3.1.8,  Up: Customization
+
+3.2: Textual Fonts & Colors
+===========================
+
+Q3.2.1: How can I set color options from `init.el'/`.emacs'?
+------------------------------------------------------------
+
+How can I set the most commonly used color options from my
+`init.el'/`.emacs' instead of from my `.Xresources'?
+
+   Like this:
+
+     (set-face-background 'default      "bisque") ; frame background
+     (set-face-foreground 'default      "black") ; normal text
+     (set-face-background 'zmacs-region "red") ; When selecting w/
+                                             ; mouse
+     (set-face-foreground 'zmacs-region "yellow")
+     (set-face-font       'default      "*courier-bold-r*120-100-100*")
+     (set-face-background 'highlight    "blue") ; Ie when selecting
+                                             ; buffers
+     (set-face-foreground 'highlight    "yellow")
+     (set-face-background 'modeline     "blue") ; Line at bottom
+                                             ; of buffer
+     (set-face-foreground 'modeline     "white")
+     (set-face-font       'modeline     "*bold-r-normal*140-100-100*")
+     (set-face-background 'isearch      "yellow") ; When highlighting
+                                             ; while searching
+     (set-face-foreground 'isearch      "red")
+     (setq x-pointer-foreground-color   "black") ; Adds to bg color,
+                                             ; so keep black
+     (setq x-pointer-background-color   "blue") ; This is color
+                                             ; you really
+                                             ; want ptr/crsr
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.2,  Next: Q3.2.3,  Prev: Q3.2.1,  Up: Customization
+
+Q3.2.2: How do I set the text, menu and modeline fonts?
+-------------------------------------------------------
+
+Note that you should use `Emacs.' and not `Emacs*' when setting face
+values.
+
+   In `.Xresources':
+
+     Emacs.default.attributeFont:  -*-*-medium-r-*-*-*-120-*-*-m-*-*-*
+     Emacs*menubar*font:           fixed
+     Emacs.modeline.attributeFont: fixed
+
+   This is confusing because `default' and `modeline' are face names,
+and can be found listed with all faces in the current mode by using
+`M-x set-face-font (enter) ?'.  They use the face-specific resource
+`attributeFont'.
+
+   On the other hand, `menubar' is a normal X thing that uses the
+resource `font'.  With Motif it _may be_ necessary to use `fontList'
+_instead of_ `font'.  In _non-Motif_ configurations with Mule it _is_
+necessary to use `fontSet' instead of `font'.  (Sorry, there just is no
+simple recipe here.)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.3,  Next: Q3.2.4,  Prev: Q3.2.2,  Up: Customization
+
+Q3.2.3: How can I set the colors when highlighting a region?
+------------------------------------------------------------
+
+How can I set the background/foreground colors when highlighting a
+region?
+
+   You can change the face `zmacs-region' either in your `.Xresources':
+
+     Emacs.zmacs-region.attributeForeground: firebrick
+     Emacs.zmacs-region.attributeBackground: lightseagreen
+
+   or in your `init.el'/`.emacs':
+
+     (set-face-background 'zmacs-region "red")
+     (set-face-foreground 'zmacs-region "yellow")
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.4,  Next: Q3.2.5,  Prev: Q3.2.3,  Up: Customization
+
+Q3.2.4: How can I limit color map usage?
+----------------------------------------
+
+I'm using Netscape (or another color grabber like XEmacs); is there any
+way to limit the number of available colors in the color map?
+
+   Answer: No, but you can start Netscape before XEmacs, and it will use
+the closest available color if the colormap is full.  You can also limit
+the number of colors Netscape uses, using the flags -mono, -ncols <#> or
+-install (for mono, limiting to <#> colors, or for using a private color
+map).
+
+   If you have the money, another solution would be to use a truecolor
+or direct color video.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.5,  Next: Q3.2.6,  Prev: Q3.2.4,  Up: Customization
+
+Q3.2.5: My tty supports color, but XEmacs doesn't use them.
+-----------------------------------------------------------
+
+XEmacs tries to automatically determine whether your tty supports color,
+but sometimes guesses wrong.  In that case, you can make XEmacs Do The
+Right Thing using this Lisp code:
+
+     (if (eq 'tty (device-type))
+         (set-device-class nil 'color))
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.6,  Next: Q3.2.7,  Prev: Q3.2.5,  Up: Customization
+
+Q3.2.6: Can I have pixmap backgrounds in XEmacs?
+------------------------------------------------
+
+Juan Villacis <jvillaci@wahnsinnig.extreme.indiana.edu> writes:
+
+     There are several ways to do it.  For example, you could specify a
+     default pixmap image to use in your `~/.Xresources', e.g.,
+
+            Emacs*EmacsFrame.default.attributeBackgroundPixmap: /path/to/image.xpm
+
+     and then reload ~/.Xresources and restart XEmacs.  Alternatively,
+     since each face can have its own pixmap background, a better way
+     would be to set a face's pixmap within your XEmacs init file, e.g.,
+
+            (set-face-background-pixmap 'default "/path/to/image.xpm")
+            (set-face-background-pixmap 'bold    "/path/to/another_image.xpm")
+
+     and so on.  You can also do this interactively via `M-x
+     edit-faces'.
+
+
+\1f
+File: xemacs-faq.info,  Node: Q3.2.7,  Next: Q3.3.1,  Prev: Q3.2.6,  Up: Customization
+
+Q3.2.7: How do I display non-ASCII characters?
+----------------------------------------------
+
+If you're using a Mule-enabled XEmacs, then display is automatic.  If
+you're not seeing the characters you expect, either (1) you don't have
+appropriate fonts available or (2) XEmacs did not correctly detect the
+coding system (*note Recognize Coding: (xemacs)Recognize Coding.).  In
+case (1), install fonts as is customary for your platform.  In case
+(2), you need to tell XEmacs explicitly what coding systems you're
+using.  *Note Specify Coding: (xemacs)Specify Coding.
+
+   If your XEmacs is not Mule-enabled, and for some reason getting a
+Mule-enabled XEmacs seems like the wrong thing to do, all is not lost.
+You can arrange it by brute force.  In `event-Xt.c' (suppress the urge
+to look in this file--play Doom instead, because you'll survive
+longer), it is written:
+
+     In a non-Mule world, a user can still have a multi-lingual editor,
+     by doing `(set-face-font "-*-iso8859-2" (current-buffer))' for all
+     their Latin-2 buffers, etc.
+
+   For the related problem of _inputting_ non-ASCII characters in a
+non-Mule XEmacs, *Note Q3.5.7::.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.3.1,  Next: Q3.3.2,  Prev: Q3.2.7,  Up: Customization
+
+3.3: The Modeline
+=================
+
+Q3.3.1: How can I make the modeline go away?
+--------------------------------------------
+
+     (set-specifier has-modeline-p nil)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.3.2,  Next: Q3.3.3,  Prev: Q3.3.1,  Up: Customization
+
+Q3.3.2: How do you have XEmacs display the line number in the modeline?
+-----------------------------------------------------------------------
+
+Add the following line to your `init.el'/`.emacs' file to display the
+line number:
+
+     (line-number-mode 1)
+
+   Use the following to display the column number:
+
+     (column-number-mode 1)
+
+   Or select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Basics->Line Number Mode' and/or `Advanced
+(Customize)->Emacs->Editing->Basics->Column Number Mode'
+
+   Or type `M-x customize <RET> editing-basics <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.3.3,  Next: Q3.3.4,  Prev: Q3.3.2,  Up: Customization
+
+Q3.3.3: How do I get XEmacs to put the time of day on the modeline?
+-------------------------------------------------------------------
+
+Add the following line to your `init.el'/`.emacs' file to display the
+time:
+
+     (display-time)
+
+   See `Customize' from the `Options' menu for customization.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.3.4,  Next: Q3.3.5,  Prev: Q3.3.3,  Up: Customization
+
+Q3.3.4: How do I turn off current chapter from AUC TeX modeline?
+----------------------------------------------------------------
+
+With AUC TeX, fast typing is hard because the current chapter, section
+etc. are given in the modeline.  How can I turn this off?
+
+   It's not AUC TeX, it comes from `func-menu' in `func-menu.el'.
+
+   David Hughes <dhughes@origin-at.co.uk> writes:
+
+     Try this; you'll still get the function name displayed in the
+     modeline, but it won't attempt to keep track when you modify the
+     file. To refresh when it gets out of synch, you simply need click
+     on the `Rescan Buffer' option in the function-menu.
+
+          (setq-default fume-auto-rescan-buffer-p nil)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.3.5,  Next: Q3.4.1,  Prev: Q3.3.4,  Up: Customization
+
+Q3.3.5: How can one change the modeline color based on the mode used?
+---------------------------------------------------------------------
+
+You can use something like the following:
+
+     (add-hook 'lisp-mode-hook
+               (lambda ()
+                 (set-face-background 'modeline "red" (current-buffer))))
+
+   Then, when editing a Lisp file (i.e. when in Lisp mode), the modeline
+colors change from the default set in your `init.el'/`.emacs'.  The
+change will only be made in the buffer you just entered (which contains
+the Lisp file you are editing) and will not affect the modeline colors
+anywhere else.
+
+   Notes:
+
+   * The hook is the mode name plus `-hook'.  eg. c-mode-hook,
+     c++-mode-hook, emacs-lisp-mode-hook (used for your
+     `init.el'/`.emacs' or a `xx.el' file), lisp-interaction-mode-hook
+     (the `*scratch*' buffer), text-mode-hook, etc.
+
+   * Be sure to use `add-hook', not `(setq c-mode-hook xxxx)',
+     otherwise you will erase anything that anybody has already put on
+     the hook.
+
+   * You can also do `(set-face-font 'modeline FONT)', eg.
+     `(set-face-font 'modeline "*bold-r-normal*140-100-100*"
+     (current-buffer))' if you wish the modeline font to vary based on
+     the current mode.
+
+   There are additional modeline faces, `modeline-buffer-id',
+`modeline-mousable', and `modeline-mousable-minor-mode', which you may
+want to customize.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.4.1,  Next: Q3.4.2,  Prev: Q3.3.5,  Up: Customization
+
+3.4: Multiple Device Support
+============================
+
+Q3.4.1: How do I open a frame on another screen of my multi-headed display?
+---------------------------------------------------------------------------
+
+Use the command `M-x make-frame-on-display'.  This command is also on
+the File menu in the menubar.
+
+   The command `make-frame-on-tty' also exists, which will establish a
+connection to any tty-like device.  Opening the TTY devices should be
+left to `gnuclient', though.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.4.2,  Next: Q3.5.1,  Prev: Q3.4.1,  Up: Customization
+
+Q3.4.2: Can I really connect to a running XEmacs after calling up over a modem?  How?
+-------------------------------------------------------------------------------------
+
+Yes.  Use `gnuclient -nw'. (Prior to 20.3, use the `gnuattach' program
+supplied with XEmacs instead.)
+
+   Also see *Note Q5.0.12::.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.1,  Next: Q3.5.2,  Prev: Q3.4.2,  Up: Customization
+
+3.5: The Keyboard
+=================
+
+Q3.5.1: How can I bind complex functions (or macros) to keys?
+-------------------------------------------------------------
+
+As an example, say you want the `paste' key on a Sun keyboard to insert
+the current Primary X selection at point. You can accomplish this with:
+
+     (define-key global-map [f18] 'x-insert-selection)
+
+   However, this only works if there is a current X selection (the
+selection will be highlighted).  The functionality I like is for the
+`paste' key to insert the current X selection if there is one,
+otherwise insert the contents of the clipboard.  To do this you need to
+pass arguments to `x-insert-selection'.  This is done by wrapping the
+call in a 'lambda form:
+
+     (global-set-key [f18]
+       (lambda () (interactive) (x-insert-selection t nil)))
+
+   This binds the f18 key to a "generic" functional object.  The
+interactive spec is required because only interactive functions can be
+bound to keys.
+
+   For the FAQ example you could use:
+
+     (global-set-key [(control ?.)]
+       (lambda () (interactive) (scroll-up 1)))
+     (global-set-key [(control ?;)]
+       (lambda () (interactive) (scroll-up -1)))
+
+   This is fine if you only need a few functions within the lambda body.
+If you're doing more it's cleaner to define a separate function as in
+question 3.5.3 (*note Q3.5.3::).
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.2,  Next: Q3.5.3,  Prev: Q3.5.1,  Up: Customization
+
+Q3.5.2: How can I stop down-arrow from adding empty lines to the bottom of my buffers?
+--------------------------------------------------------------------------------------
+
+Add the following line to your `init.el'/`.emacs' file:
+
+     (setq next-line-add-newlines nil)
+
+   This has been the default setting in XEmacs for some time.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.3,  Next: Q3.5.4,  Prev: Q3.5.2,  Up: Customization
+
+Q3.5.3: How do I bind C-. and C-; to scroll one line up and down?
+-----------------------------------------------------------------
+
+Add the following (Thanks to Richard Mlynarik <mly@adoc.xerox.com> and
+Wayne Newberry <wayne@zen.cac.stratus.com>) to `.emacs':
+
+     (defun scroll-up-one-line ()
+       (interactive)
+       (scroll-up 1))
+     
+     (defun scroll-down-one-line ()
+       (interactive)
+       (scroll-down 1))
+     
+     (global-set-key [(control ?.)] 'scroll-up-one-line) ; C-.
+     (global-set-key [(control ?;)] 'scroll-down-one-line) ; C-;
+
+   The key point is that you can only bind simple functions to keys; you
+can not bind a key to a function that you're also passing arguments to.
+(*note Q3.5.1:: for a better answer).
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.4,  Next: Q3.5.5,  Prev: Q3.5.3,  Up: Customization
+
+Q3.5.4: Globally binding `Delete'?
+----------------------------------
+
+I cannot manage to globally bind my `Delete' key to something other
+than the default.  How does one do this?
+
+   Answer: The problem is that many modes explicitly bind `Delete'.  To
+get around this, try the following:
+
+     (defun foo ()
+       (interactive)
+       (message "You hit DELETE"))
+     
+     (define-key key-translation-map 'delete 'redirected-delete)
+     (global-set-key 'redirected-delete 'foo)
+
+   Also see *Note Q3.5.10::.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.5,  Next: Q3.5.6,  Prev: Q3.5.4,  Up: Customization
+
+Q3.5.5: Scrolling one line at a time.
+-------------------------------------
+
+Can the cursor keys scroll the screen a line at a time, rather than the
+default half page jump?  I tend it to find it disorienting.
+
+   Try this:
+
+     (defun scroll-one-line-up (&optional arg)
+       "Scroll the selected window up (forward in the text) one line (or N lines)."
+       (interactive "p")
+       (scroll-up (or arg 1)))
+     
+     (defun scroll-one-line-down (&optional arg)
+       "Scroll the selected window down (backward in the text) one line (or N)."
+       (interactive "p")
+       (scroll-down (or arg 1)))
+     
+     (global-set-key [up]   'scroll-one-line-up)
+     (global-set-key [down] 'scroll-one-line-down)
+
+   The following will also work but will affect more than just the
+cursor keys (i.e. `C-n' and `C-p'):
+
+     (setq scroll-step 1)
+
+   Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Windows->Scroll Step...' or type `M-x
+customize <RET> windows <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.6,  Next: Q3.5.7,  Prev: Q3.5.5,  Up: Customization
+
+Q3.5.6: How to map `Help' key alone on Sun type4 keyboard?
+----------------------------------------------------------
+
+The following works in GNU Emacs 19:
+
+     (global-set-key [help] 'help-command);; Help
+
+   The following works in XEmacs with the addition of shift:
+
+     (global-set-key [(shift help)] 'help-command);; Help
+
+   But it doesn't work alone.  This is in the file `PROBLEMS' which
+should have come with your XEmacs installation: _Emacs ignores the
+`help' key when running OLWM_.
+
+   OLWM grabs the `help' key, and retransmits it to the appropriate
+client using `XSendEvent'.  Allowing Emacs to react to synthetic events
+is a security hole, so this is turned off by default.  You can enable
+it by setting the variable `x-allow-sendevents' to t.  You can also
+cause fix this by telling OLWM to not grab the help key, with the null
+binding `OpenWindows.KeyboardCommand.Help:'.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.7,  Next: Q3.5.8,  Prev: Q3.5.6,  Up: Customization
+
+Q3.5.7: How can you type in special characters in XEmacs?
+---------------------------------------------------------
+
+One way is to use the package `x-compose'.  Then you can use sequences
+like `Compose " a' to get ä, etc.
+
+   Another way is to use the `iso-insert' package. Then you can use
+sequences like `C-x 8 " a' to get ä, etc.
+
+   Glynn Clements <glynn@sensei.co.uk> writes:
+
+     It depends upon your X server.
+
+     Generally, the simplest way is to define a key as Multi_key with
+     xmodmap, e.g.
+                  xmodmap -e 'keycode 0xff20 = Multi_key'
+
+     You will need to pick an appropriate keycode. Use xev to find out
+     the keycodes for each key.
+
+     [NB: On a `Windows' keyboard, recent versions of XFree86
+     automatically define the right `Windows' key as Multi_key'.]
+
+     Once you have Multi_key defined, you can use e.g.
+                  Multi a '       => á
+                  Multi e "       => ë
+                  Multi c ,       => ç
+
+     etc.
+
+     Also, recent versions of XFree86 define various AltGr-<key>
+     combinations as dead keys, i.e.
+                  AltGr [         => dead_diaeresis
+                  AltGr ]         => dead_tilde
+                  AltGr ;         => dead_acute
+     etc.
+
+     Running `xmodmap -pk' will list all of the defined keysyms.
+
+   For the related problem of _displaying_ non-ASCII characters in a
+non-Mule XEmacs, *Note Q3.2.7::.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.8,  Next: Q3.5.9,  Prev: Q3.5.7,  Up: Customization
+
+Q3.5.8: [This question intentionally left blank]
+------------------------------------------------
+
+Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.9,  Next: Q3.5.10,  Prev: Q3.5.8,  Up: Customization
+
+Q3.5.9: How do I make the Delete key delete forward?
+----------------------------------------------------
+
+With XEmacs-20.2 use the `delbs' package:
+
+     (require 'delbs)
+
+   This will give you the functions `delbs-enable-delete-forward' to
+set things up, and `delbs-disable-delete-forward' to revert to "normal"
+behavior.  Note that `delbackspace' package is obsolete.
+
+   Starting with XEmacs-20.3 better solution is to set variable
+`delete-key-deletes-forward' to t.  You can also change this with
+Customize. Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Basics->Delete Key Deletes Forward' or
+type `M-x customize <RET> editing-basics <RET>'.
+
+   Also see *Note Q3.5.4::.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.10,  Next: Q3.5.11,  Prev: Q3.5.9,  Up: Customization
+
+Q3.5.10: Can I turn on "sticky" modifier keys?
+----------------------------------------------
+
+Yes, with `(setq modifier-keys-are-sticky t)'.  This will give the
+effect of being able to press and release Shift and have the next
+character typed come out in upper case.  This will affect all the other
+modifier keys like Control and Meta as well.
+
+   Ben Wing <ben@xemacs.org> writes:
+
+     One thing about the sticky modifiers is that if you move the mouse
+     out of the frame and back in, it cancels all currently "stuck"
+     modifiers.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.5.11,  Next: Q3.6.1,  Prev: Q3.5.10,  Up: Customization
+
+Q3.5.11: How do I map the arrow keys?
+-------------------------------------
+
+Say you want to map `C-<right>' to forward-word:
+
+   Sam Steingold <sds@usa.net> writes:
+
+          ; both XEmacs and Emacs
+          (define-key global-map [(control right)] 'forward-word)
+     or
+          ; Emacs only
+          (define-key global-map [C-right] 'forward-word)
+     or
+          ; ver > 20, both
+          (define-key global-map (kbd "C-<right>") 'forward-word)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.6.1,  Next: Q3.6.2,  Prev: Q3.5.11,  Up: Customization
+
+3.6: The Cursor
+===============
+
+Q3.6.1: Is there a way to make the bar cursor thicker?
+------------------------------------------------------
+
+I'd like to have the bar cursor a little thicker, as I tend to "lose" it
+often.
+
+   For a 1 pixel bar cursor, use:
+
+     (setq bar-cursor t)
+
+   For a 2 pixel bar cursor, use:
+
+     (setq bar-cursor 'anything-else)
+
+   Starting with XEmacs-20.3 you can also change these with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Display->Bar Cursor...' or type `M-x
+customize <RET> display <RET>'.
+
+   You can use a color to make it stand out better:
+
+     Emacs*cursorColor:      Red
+
+\1f
+File: xemacs-faq.info,  Node: Q3.6.2,  Next: Q3.6.3,  Prev: Q3.6.1,  Up: Customization
+
+Q3.6.2: Is there a way to get back the block cursor?
+----------------------------------------------------
+
+     (setq bar-cursor nil)
+
+   Starting with XEmacs 20.3 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Display->Bar Cursor...' or type `M-x
+customize <RET> display <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.6.3,  Next: Q3.7.1,  Prev: Q3.6.2,  Up: Customization
+
+Q3.6.3: Can I make the cursor blink?
+------------------------------------
+
+Yes, like this:
+
+     (blink-cursor-mode)
+
+   This function toggles between a steady cursor and a blinking cursor.
+You may also set this mode from the menu bar by selecting `Options =>
+Frame Appearance => Blinking Cursor'.  Remember to save options.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.1,  Next: Q3.7.2,  Prev: Q3.6.3,  Up: Customization
+
+3.7: The Mouse and Highlighting
+===============================
+
+Q3.7.1: How can I turn off Mouse pasting?
+-----------------------------------------
+
+I keep hitting the middle mouse button by accident and getting stuff
+pasted into my buffer so how can I turn this off?
+
+   Here is an alternative binding, whereby the middle mouse button
+selects (but does not cut) the expression under the mouse. Clicking
+middle on a left or right paren will select to the matching one.  Note
+that you can use `define-key' or `global-set-key'.
+
+     (defun mouse-set-point-and-select (event)
+       "Sets the point at the mouse location, then marks following form"
+       (interactive "@e")
+       (mouse-set-point event)
+       (mark-sexp 1))
+     (define-key global-map [button2] 'mouse-set-point-and-select)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.2,  Next: Q3.7.3,  Prev: Q3.7.1,  Up: Customization
+
+Q3.7.2: How do I set control/meta/etc modifiers on mouse buttons?
+-----------------------------------------------------------------
+
+Use, for instance, `[(meta button1)]'. For example, here is a common
+setting for Common Lisp programmers who use the bundled `ilisp'
+package, whereby meta-button1 on a function name will find the file
+where the function name was defined, and put you at that location in
+the source file.
+
+   [Inside a function that gets called by the lisp-mode-hook and
+ilisp-mode-hook]
+
+     (local-set-key [(meta button1)] 'edit-definitions-lisp)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.3,  Next: Q3.7.4,  Prev: Q3.7.2,  Up: Customization
+
+Q3.7.3: Clicking the left button does not do anything in buffer list.
+---------------------------------------------------------------------
+
+I do `C-x C-b' to get a list of buffers and the entries get highlighted
+when I move the mouse over them but clicking the left mouse does not do
+anything.
+
+   Use the middle mouse button.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.4,  Next: Q3.7.5,  Prev: Q3.7.3,  Up: Customization
+
+Q3.7.4: How can I get a list of buffers when I hit mouse button 3?
+------------------------------------------------------------------
+
+The following code will replace the default popup on button3:
+
+     (global-set-key [button3] 'popup-buffer-menu)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.5,  Next: Q3.7.6,  Prev: Q3.7.4,  Up: Customization
+
+Q3.7.5: Why does cut-and-paste not work between XEmacs and a cmdtool?
+---------------------------------------------------------------------
+
+We don't know.  It's a bug.  There does seem to be a work-around,
+however.  Try running xclipboard first.  It appears to fix the problem
+even if you exit it.  (This should be mostly fixed in 19.13, but we
+haven't yet verified that).
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.6,  Next: Q3.7.7,  Prev: Q3.7.5,  Up: Customization
+
+Q3.7.6: How I can set XEmacs up so that it pastes where the text cursor is?
+---------------------------------------------------------------------------
+
+By default XEmacs pastes X selections where the mouse pointer is.  How
+do I disable this?
+
+   Examine the function `mouse-yank', by typing `C-h f mouse-yank
+<RET>'.
+
+   To get XEmacs to paste at the text cursor, add this your
+`init.el'/`.emacs':
+
+     (setq mouse-yank-at-point t)
+
+   Starting with XEmacs-20.2 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Mouse->Yank At Point...' or type `M-x
+customize <RET> mouse <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.7,  Next: Q3.7.8,  Prev: Q3.7.6,  Up: Customization
+
+Q3.7.7: How do I select a rectangular region?
+---------------------------------------------
+
+Just select the region normally, then use the rectangle commands (e.g.
+`kill-rectangle' on it.  The region does not highlight as a rectangle,
+but the commands work just fine.
+
+   To actually sweep out rectangular regions with the mouse you can use
+`mouse-track-do-rectangle' which is assigned to `M-button1'.  Then use
+rectangle commands.
+
+   You can also do the following to change default behavior to sweep out
+rectangular regions:
+
+     (setq mouse-track-rectangle-p t)
+
+   Starting with XEmacs-20.2 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Mouse->Track Rectangle...' or type `M-x
+customize <RET> mouse <RET>'.
+
+      mouse-track-do-rectangle: (event)
+        -- an interactive compiled Lisp function.
+      Like `mouse-track' but selects rectangles instead of regions.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.7.8,  Next: Q3.8.1,  Prev: Q3.7.7,  Up: Customization
+
+Q3.7.8: Why does `M-w' take so long?
+------------------------------------
+
+It actually doesn't.  It leaves the region visible for a second so that
+you can see what area is being yanked.  If you start working, though, it
+will immediately complete its operation.  In other words, it will only
+delay for a second if you let it.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.8.1,  Next: Q3.8.2,  Prev: Q3.7.8,  Up: Customization
+
+3.8: The Menubar and Toolbar
+============================
+
+Q3.8.1: How do I get rid of the menu (or menubar)?
+--------------------------------------------------
+
+     (set-specifier menubar-visible-p nil)
+
+\1f
+File: xemacs-faq.info,  Node: Q3.8.2,  Next: Q3.8.3,  Prev: Q3.8.1,  Up: Customization
+
+Q3.8.2: Can I customize the basic menubar?
+------------------------------------------
+
+For an extensive menubar, add this line to your `init.el'/`.emacs':
+
+     (load "big-menubar")
+
+   If you'd like to write your own, this file provides as good a set of
+examples as any to start from.  The file is located in edit-utils
+package.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.8.3,  Next: Q3.8.4,  Prev: Q3.8.2,  Up: Customization
+
+Q3.8.3: How do I control how many buffers are listed in the menu `Buffers List'?
+--------------------------------------------------------------------------------
+
+Add the following to your `init.el'/`.emacs' (suit to fit):
+
+     (setq buffers-menu-max-size 20)
+
+   For no limit, use an argument of `nil'.
+
+   Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Menu->Buffers Menu->Max Size...' or
+type `M-x customize <RET> buffers-menu <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.8.4,  Next: Q3.8.5,  Prev: Q3.8.3,  Up: Customization
+
+Q3.8.4: Resources like `Emacs*menubar*font' are not working?
+------------------------------------------------------------
+
+I am trying to use a resource like `Emacs*menubar*font' to set the font
+of the menubar but it's not working.
+
+   In Motif, the use of `font' resources is obsoleted in order to
+support internationalization.  If you are using the real Motif menubar,
+this resource is not recognized at all; you have to say:
+
+     Emacs*menubar*fontList: FONT
+
+   If you are using the Lucid menubar, for backward compatibility with
+existing user configurations, the `font' resource is recognized.  Since
+this is not supported by Motif itself, the code is a kludge and the
+`font' resource will be recognized only if the `fontList' resource
+resource is unset.  This means that the resource
+
+     *fontList: FONT
+
+   will override
+
+     Emacs*menubar*font: FONT
+
+   even though the latter is more specific.
+
+   In non-Motif configurations using `--with-mule' and `--with-xfs' it
+_is_ necessary to use the `fontSet' resource _instead of_ the `font'
+resource.  The backward compatibility kludge was never implemented for
+non-Motif builds.  Example:
+
+     *fontSet: FONT
+
+\1f
+File: xemacs-faq.info,  Node: Q3.8.5,  Next: Q3.9.1,  Prev: Q3.8.4,  Up: Customization
+
+Q3.8.5: How can I bind a key to a function to toggle the toolbar?
+-----------------------------------------------------------------
+
+Try something like:
+
+     (defun my-toggle-toolbar ()
+       (interactive)
+       (set-specifier default-toolbar-visible-p
+                      (not (specifier-instance default-toolbar-visible-p))))
+     (global-set-key "\C-xT" 'my-toggle-toolbar)
+
+   There are redisplay bugs in 19.14 that may make the preceding result
+in a messed-up display, especially for frames with multiple windows.
+You may need to resize the frame before XEmacs completely realizes the
+toolbar is really gone.
+
+   Thanks to Martin Buchholz <martin@xemacs.org> for the correct code.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.9.1,  Next: Q3.9.2,  Prev: Q3.8.5,  Up: Customization
+
+3.9: Scrollbars
+===============
+
+Q3.9.1: How can I disable the scrollbar?
+----------------------------------------
+
+To disable them for all frames, add the following line to your
+`.Xresources':
+
+     Emacs.scrollBarWidth:  0
+
+   Or select from the `Options' menu `Frame Appearance->Scrollbars'.
+Remember to save options.
+
+   To turn the scrollbar off on a per-frame basis, use the following
+function:
+
+     (set-specifier scrollbar-width 0 (selected-frame))
+
+   You can actually turn the scrollbars on at any level you want by
+substituting for (selected-frame) in the above command.  For example, to
+turn the scrollbars off only in a single buffer:
+
+     (set-specifier scrollbar-width 0 (current-buffer))
+
+\1f
+File: xemacs-faq.info,  Node: Q3.9.2,  Next: Q3.9.3,  Prev: Q3.9.1,  Up: Customization
+
+Q3.9.2: How can one use resources to change scrollbar colors?
+-------------------------------------------------------------
+
+Here's a recap of how to use resources to change your scrollbar colors:
+
+     ! Motif scrollbars
+     
+     Emacs*XmScrollBar.Background: skyblue
+     Emacs*XmScrollBar.troughColor: lightgray
+     
+     ! Athena scrollbars
+     
+     Emacs*Scrollbar.Foreground: skyblue
+     Emacs*Scrollbar.Background: lightgray
+
+   Note the capitalization of `Scrollbar' for the Athena widget.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.9.3,  Next: Q3.9.4,  Prev: Q3.9.2,  Up: Customization
+
+Q3.9.3: Moving the scrollbar can move the point; can I disable this?
+--------------------------------------------------------------------
+
+When I move the scrollbar in an XEmacs window, it moves the point as
+well, which should not be the default behavior.  Is this a bug or a
+feature?  Can I disable it?
+
+   The current behavior is a feature, not a bug.  Point remains at the
+same buffer position as long as that position does not scroll off the
+screen.  In that event, point will end up in either the upper-left or
+lower-left hand corner.
+
+   This cannot be changed.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.9.4,  Next: Q3.10.1,  Prev: Q3.9.3,  Up: Customization
+
+Q3.9.4: How can I turn off automatic horizontal scrolling in specific modes?
+----------------------------------------------------------------------------
+
+Do `(setq truncate-lines t)' in the mode-hooks for any modes in which
+you want lines truncated.
+
+   More precisely: If `truncate-lines' is nil, horizontal scrollbars
+will never appear.  Otherwise, they will appear only if the value of
+`scrollbar-height' for that buffer/window/etc. is non-zero.  If you do
+
+     (set-specifier scrollbar-height 0)
+
+   then horizontal scrollbars will not appear in truncated buffers
+unless the package specifically asked for them.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.10.1,  Next: Q3.10.2,  Prev: Q3.9.4,  Up: Customization
+
+3.10: Text Selections
+=====================
+
+Q3.10.1: How can I turn off or change highlighted selections?
+-------------------------------------------------------------
+
+The `zmacs' mode allows for what some might call gratuitous
+highlighting for selected regions (either by setting mark or by using
+the mouse).  This is the default behavior.  To turn off, add the
+following line to your `init.el'/`.emacs' file:
+
+     (setq zmacs-regions nil)
+
+   Starting with XEmacs-20.2 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Basics->Zmacs Regions' or type `M-x
+customize <RET> editing-basics <RET>'.
+
+   To change the face for selection, look at `Options->Customize' on
+the menubar.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.10.2,  Next: Q3.10.3,  Prev: Q3.10.1,  Up: Customization
+
+Q3.10.2: How do I get that typing on an active region removes it?
+-----------------------------------------------------------------
+
+I want to change things so that if I select some text and start typing,
+the typed text replaces the selected text, similar to Motif.
+
+   You want to use something called "pending delete".  Pending delete
+is what happens when you select a region (with the mouse or keyboard)
+and you press a key to replace the selected region by the key you typed.
+Usually backspace kills the selected region.
+
+   To get this behavior, add the following lines to your
+`init.el'/`.emacs':
+
+     (cond
+      ((fboundp 'turn-on-pending-delete)
+       (turn-on-pending-delete))
+      ((fboundp 'pending-delete-on)
+       (pending-delete-on t)))
+
+   Note that this will work with both Backspace and Delete.  This code
+is a tad more complicated than it has to be for XEmacs in order to make
+it more portable.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.10.3,  Next: Q3.10.4,  Prev: Q3.10.2,  Up: Customization
+
+Q3.10.3: Can I turn off the highlight during isearch?
+-----------------------------------------------------
+
+I do not like my text highlighted while I am doing isearch as I am not
+able to see what's underneath.  How do I turn it off?
+
+   Put the following in your `init.el'/`.emacs':
+
+     (setq isearch-highlight nil)
+
+   Starting with XEmacs-20.2 you can also change this with Customize.
+Type `M-x customize-variable <RET> isearch-highlight <RET>'.
+
+   Note also that isearch-highlight affects query-replace and ispell.
+Instead of disabling isearch-highlight you may find that a better
+solution consists of customizing the `isearch' face.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.10.4,  Next: Q3.10.5,  Prev: Q3.10.3,  Up: Customization
+
+Q3.10.4: How do I turn off highlighting after `C-x C-p' (mark-page)?
+--------------------------------------------------------------------
+
+Put this in your `.emacs':
+
+     (setq zmacs-regions nil)
+
+   *Warning: This command turns off all region highlighting.*
+
+   Also see *Note Q3.10.1::.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.10.5,  Next: Q3.10.6,  Prev: Q3.10.4,  Up: Customization
+
+Q3.10.5: The region disappears when I hit the end of buffer while scrolling.
+----------------------------------------------------------------------------
+
+This has been fixed by default starting with XEmacs-20.3.
+
+   With older versions you can turn this feature (if it indeed is a
+feature) off like this:
+
+     (defadvice scroll-up (around scroll-up freeze)
+       (interactive "_P")
+       (let ((zmacs-region-stays t))
+         (if (interactive-p)
+             (condition-case nil
+                 ad-do-it
+               (end-of-buffer (goto-char (point-max))))
+           ad-do-it)))
+     
+     (defadvice scroll-down (around scroll-down freeze)
+       (interactive "_P")
+       (let ((zmacs-region-stays t))
+         (if (interactive-p)
+             (condition-case nil
+                 ad-do-it
+               (beginning-of-buffer (goto-char (point-min))))
+           ad-do-it)))
+
+   Thanks to T. V. Raman <raman@adobe.com> for assistance in deriving
+this answer.
+
+\1f
+File: xemacs-faq.info,  Node: Q3.10.6,  Prev: Q3.10.5,  Up: Customization
+
+Q3.10.6: Why is killing so slow?
+--------------------------------
+
+This actually is an X Windows question, although you'll notice it with
+keyboard operations as well as while using the GUI.  Basically, there
+are four ways to communicate interprogram via the X server:
+
+*Primary selection*
+     a transient selection that gets replaced every time a new
+     selection is made
+
+*Secondary selection*
+     for "exchanging" with the primary selection
+
+*Cut buffers*
+     a clipboard internal to the X server (deprecated)
+
+*Clipboard selection*
+     a selection with a notification protocol that allows a separate
+     app to manage the clipboard
+
+   The cut buffers are deprecated because managing them is even more
+inefficient than the clipboard notification protocol.  The primary
+selection works fine for many users and applications, but is not very
+robust under intensive or sophisticated use.
+
+   In Motif and MS Windows, a clipboard has become the primary means for
+managing cut and paste.  These means that "modern" applications tend to
+be oriented toward a true clipboard, rather than the primary selection.
+(On Windows, there is nothing equivalent to the primary selection.)
+It's not that XEmacs doesn't support the simple primary selection
+method, it's that more and more other applications don't.
+
+   So the slowdown occurs because XEmacs now engages in the clipboard
+notification protocol on _every_ kill.  This is especially slow on
+Motif.
+
+   With most people running most clients and server on the same host,
+and many of the rest working over very fast communication, you may
+expect that the situation is not going to improve.
+
+   There are a number of workarounds.  The most effective is to use a
+special command to do selection ownership only when you intend to paste
+to another application.  Useful commands are `kill-primary-selection'
+and `copy-primary-selection'.  These work only on text selected with
+the mouse (probably; experiment), and are bound by default to the `Cut'
+and `Copy', respectively, buttons on the toolbar.
+`copy-primary-selection' is also bound to `C-Insert'.  You can yank the
+clipboard contents with `yank-primary-selection', bound to the `Paste'
+toolbar button and `Sh-Insert'.
+
+   If you are communicating by cut and paste with applications that use
+the primary selection, then you can customize
+`interprogram-cut-function' to `nil', restoring the XEmacs version 20
+behavior.  How can you tell if a program will support this?
+Motifly-correct programs require the clipboard; you lose.  For others,
+only by trying it.  You also need to customize the complementary
+`interprogram-paste-function' to `nil'.  (Otherwise XEmacs-to-XEmacs
+pastes will not work correctly.)
+
+   You may get some relief on Motif by setting
+`x-selection-strict-motif-ownership' to nil, but this means you will
+only intermittently be able to paste XEmacs kills to Motif applications.
+
+   Thanks to Jeff Mincy and Glynn Clements for corrections.
+
+\1f
+File: xemacs-faq.info,  Node: Subsystems,  Next: Miscellaneous,  Prev: Customization,  Up: Top
+
+4 Major Subsystems
+******************
+
+This is part 4 of the XEmacs Frequently Asked Questions list.  This
+section is devoted to major XEmacs subsystems.
+
+* Menu:
+
+Reading Mail with VM:
+* Q4.0.1::      How do I set up VM to retrieve remote mail using POP?
+* Q4.0.2::      How do I get VM to filter mail for me?
+* Q4.0.3::      How can I get VM to automatically check for new mail?
+* Q4.0.4::      [This question intentionally left blank]
+* Q4.0.5::      How do I get my outgoing mail archived?
+* Q4.0.6::      I have various addresses at which I receive mail.  How can I tell VM to ignore them when doing a "reply-all"?
+* Q4.0.7::      Is there a mailing list or FAQ for VM?
+* Q4.0.8::      Remote mail reading with VM.
+* Q4.0.9::      rmail or VM gets an error incorporating new mail.
+* Q4.0.10::     How do I make VM stay in a single frame?
+* Q4.0.11::     How do I make VM or mh-e display graphical smilies?
+* Q4.0.12::     Customization of VM not covered in the manual or here.
+
+Web browsing with W3:
+* Q4.1.1::      What is W3?
+* Q4.1.2::      How do I run W3 from behind a firewall?
+* Q4.1.3::      Is it true that W3 supports style sheets and tables?
+
+Reading Netnews and Mail with Gnus:
+* Q4.2.1::      GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus,argh!
+* Q4.2.2::      [This question intentionally left blank]
+* Q4.2.3::      How do I make Gnus stay within a single frame?
+* Q4.2.4::      How do I customize the From: line?
+
+Other Mail & News:
+* Q4.3.1::      How can I read and/or compose MIME messages?
+* Q4.3.2::      What is TM and where do I get it?
+* Q4.3.3::      Why isn't this `movemail' program working?
+* Q4.3.4::      Movemail is also distributed by Netscape?  Can that cause problems?
+* Q4.3.5::      Where do I find pstogif (required by tm)?
+
+Sparcworks, EOS, and WorkShop:
+* Q4.4.1::      What is SPARCworks, EOS, and WorkShop
+* Q4.4.2::      How do I start the Sun Workshop support in XEmacs 21?
+
+Energize:
+* Q4.5.1::      What is/was Energize?
+
+Infodock:
+* Q4.6.1::      What is Infodock?
+
+Other Unbundled Packages:
+* Q4.7.1::      What is AUC TeX?  Where do you get it?
+* Q4.7.2::      Are there any Emacs Lisp Spreadsheets?
+* Q4.7.3::      [This question intentionally left blank]
+* Q4.7.4::      Problems installing AUC TeX
+* Q4.7.5::      Is there a reason for an Emacs package not to be included in XEmacs?
+* Q4.7.6::      Is there a MatLab mode?
+* Q4.7.7::      Can I edit files on other hosts?
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.1,  Next: Q4.0.2,  Prev: Subsystems,  Up: Subsystems
+
+4.0: Reading Mail with VM
+=========================
+
+Q4.0.1: How do I set up VM to retrieve mail from a remote site using POP?
+-------------------------------------------------------------------------
+
+Use `vm-spool-files', like this for example:
+
+     (setq vm-spool-files '("/var/spool/mail/wing"
+                            "netcom23.netcom.com:110:pass:wing:MYPASS"))
+
+   Of course substitute your actual password for MYPASS.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.2,  Next: Q4.0.3,  Prev: Q4.0.1,  Up: Subsystems
+
+Q4.0.2: How do I get VM to filter mail for me?
+----------------------------------------------
+
+One possibility is to use procmail to split your mail before it gets to
+VM.  I prefer this personally, since there are many strange and
+wonderful things one can do with procmail.  Procmail may be found at
+`ftp://ftp.informatik.rwth-aachen.de/pub/packages/procmail/'.
+
+   Also see the Mail Filtering FAQ at:
+`ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/filtering-faq'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.3,  Next: Q4.0.4,  Prev: Q4.0.2,  Up: Subsystems
+
+Q4.0.3: How can I get VM to automatically check for new mail?
+-------------------------------------------------------------
+
+John Turner <turner@lanl.gov> writes:
+
+     Use the following:
+
+          (setq vm-auto-get-new-mail 60)
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.4,  Next: Q4.0.5,  Prev: Q4.0.3,  Up: Subsystems
+
+Q4.0.4: [This question intentionally left blank]
+------------------------------------------------
+
+Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.5,  Next: Q4.0.6,  Prev: Q4.0.4,  Up: Subsystems
+
+Q4.0.5: How do I get my outgoing mail archived?
+-----------------------------------------------
+
+     (setq mail-archive-file-name "~/outbox")
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.6,  Next: Q4.0.7,  Prev: Q4.0.5,  Up: Subsystems
+
+Q4.0.6: I have various addresses at which I receive mail.  How can I tell VM to ignore them when doing a "reply-all"?
+---------------------------------------------------------------------------------------------------------------------
+
+Set `vm-reply-ignored-addresses' to a list, like
+
+     (setq vm-reply-ignored-addresses
+           '("wing@nuspl@nvwls.cc.purdue.edu,netcom[0-9]*.netcom.com"
+             "wing@netcom.com" "wing@xemacs.org"))
+
+   Note that each string is a regular expression.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.7,  Next: Q4.0.8,  Prev: Q4.0.6,  Up: Subsystems
+
+Q4.0.7: Is there a mailing list or FAQ for VM?
+----------------------------------------------
+
+A FAQ for VM exists at `http://www.wonderworks.com/vm/FAQ.html'.
+
+   VM has its own newsgroups gnu.emacs.vm.info and gnu.emacs.vm.bug.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.8,  Next: Q4.0.9,  Prev: Q4.0.7,  Up: Subsystems
+
+Q4.0.8: Remote mail reading with VM.
+------------------------------------
+
+My mailbox lives at the office on a big honkin server.  My regular INBOX
+lives on my honkin desktop machine.  I now can PPP to the office from
+home which is far from honking...  I'd like to be able to read mail at
+home without storing it here and I'd like to use xemacs and VM at
+home...  Is there a recommended setup?
+
+   Joseph J. Nuspl Jr. <nuspl@nvwls.cc.purdue.edu> writes:
+
+     There are several ways to do this.
+
+       1. Set your display to your home machine and run dxpc or one of
+          the other X compressors.
+
+       2. NFS mount your desktop machine on your home machine and
+          modify your pop command on your home machine to rsh to your
+          desktop machine and actually do the pop get's.
+
+       3. Run a POP server on your desktop machine as well and do a
+          sort of two tiered POP get.
+
+   William Perry <wmperry@monolith.spry.com> adds:
+
+     Or you could run a pop script periodically on your desktop
+     machine, and just use ange-ftp or NFS to get to your mailbox.  I
+     used to do this all the time back at IU.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.9,  Next: Q4.0.10,  Prev: Q4.0.8,  Up: Subsystems
+
+Q4.0.9: rmail or VM gets an error incorporating new mail.
+---------------------------------------------------------
+
+Quoting the XEmacs PROBLEMS file:
+
+     rmail and VM get new mail from `/usr/spool/mail/$USER' using a
+     program called `movemail'.  This program interlocks with
+     `/bin/mail' using the protocol defined by `/bin/mail'.
+
+     There are two different protocols in general use.  One of them
+     uses the `flock' system call.  The other involves creating a lock
+     file; `movemail' must be able to write in `/usr/spool/mail' in
+     order to do this.  You control which one is used by defining, or
+     not defining, the macro `MAIL_USE_FLOCK' in `config.h' or the m-
+     or s- file it includes.
+
+     *IF YOU DON'T USE THE FORM OF INTERLOCKING THAT IS NORMAL ON YOUR
+     SYSTEM, YOU CAN LOSE MAIL!*
+
+     If your system uses the lock file protocol, and fascist
+     restrictions prevent ordinary users from writing the lock files in
+     `/usr/spool/mail', you may need to make `movemail' setgid to a
+     suitable group such as `mail'.  You can use these commands (as
+     root):
+
+          chgrp mail movemail
+          chmod 2755 movemail
+
+     If your system uses the lock file protocol, and fascist
+     restrictions prevent ordinary users from writing the lock files in
+     `/usr/spool/mail', you may need to make `movemail' setgid to a
+     suitable group such as `mail'.  To do this, use the following
+     commands (as root) after doing the make install.
+
+          chgrp mail movemail
+          chmod 2755 movemail
+
+     Installation normally copies movemail from the build directory to
+     an installation directory which is usually under `/usr/local/lib'.
+     The installed copy of `movemail' is usually in the directory
+     `/usr/local/lib/emacs/VERSION/TARGET'.  You must change the group
+     and mode of the installed copy; changing the group and mode of the
+     build directory copy is ineffective.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.10,  Next: Q4.0.11,  Prev: Q4.0.9,  Up: Subsystems
+
+Q4.0.10: How do I make VM stay in a single frame?
+-------------------------------------------------
+
+John.John S Cooper <Cooper@Eng.Sun.COM> writes:
+
+                                                  ; Don't use multiple frames
+          (setq vm-frame-per-composition nil)
+          (setq vm-frame-per-folder nil)
+          (setq vm-frame-per-edit nil)
+          (setq vm-frame-per-summary nil)
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.11,  Next: Q4.0.12,  Prev: Q4.0.10,  Up: Subsystems
+
+Q4.0.11: How do I make VM or mh-e display graphical smilies?
+------------------------------------------------------------
+
+For mh-e use the following:
+
+     (add-hook 'mh-show-mode-hook '(lambda ()
+                                     (smiley-region (point-min)
+                                                    (point-max))))
+
+   WJCarpenter <bill@carpenter.ORG> writes: For VM use the following:
+            (autoload 'smiley-region "smiley" nil t)
+            (add-hook 'vm-select-message-hook
+                      '(lambda ()
+                         (smiley-region (point-min)
+                                        (point-max))))
+
+   For tm use the following:
+     (autoload 'smiley-buffer "smiley" nil t)
+     (add-hook 'mime-viewer/plain-text-preview-hook 'smiley-buffer)
+
+\1f
+File: xemacs-faq.info,  Node: Q4.0.12,  Next: Q4.1.1,  Prev: Q4.0.11,  Up: Subsystems
+
+Q4.0.12: Customization of VM not covered in the manual, or here.
+----------------------------------------------------------------
+
+giacomo boffi <boffi@hp735.stru.polimi.it> writes:
+
+     The meta-answer is to look into the file `vm-vars.el', in the vm
+     directory of the lisp library.
+
+     `vm-vars.el' contains, initializes and carefully describes, with
+     examples of usage, the plethora of user options that _fully_
+     control VM's behavior.
+
+     Enter vm-vars, `forward-search' for toolbar, find the variables
+     that control the toolbar placement, appearance, existence, copy to
+     your `init.el'/`.emacs' or `.vm' and modify according to the
+     detailed instructions.
+
+     The above also applies to all the various features of VM: search
+     for some keywords, maybe the first you conjure isn't appropriate,
+     find the appropriate variables, copy and experiment.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.1.1,  Next: Q4.1.2,  Prev: Q4.0.12,  Up: Subsystems
+
+4.1: Web browsing with W3
+=========================
+
+Q4.1.1: What is W3?
+-------------------
+
+W3 is an advanced graphical browser written in Emacs lisp that runs on
+XEmacs.  It has full support for cascaded style sheets, and more...
+
+   It has a home web page at
+`http://www.cs.indiana.edu/elisp/w3/docs.html'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.1.2,  Next: Q4.1.3,  Prev: Q4.1.1,  Up: Subsystems
+
+Q4.1.2: How do I run W3 from behind a firewall?
+-----------------------------------------------
+
+There is a long, well-written, detailed section in the W3 manual that
+describes how to do this.  Look in the section entitled "Firewalls".
+
+\1f
+File: xemacs-faq.info,  Node: Q4.1.3,  Next: Q4.2.1,  Prev: Q4.1.2,  Up: Subsystems
+
+Q4.1.3: Is it true that W3 supports style sheets and tables?
+------------------------------------------------------------
+
+Yes, and much more.  W3, as distributed with the latest XEmacs is a
+full-featured web browser.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.2.1,  Next: Q4.2.2,  Prev: Q4.1.3,  Up: Subsystems
+
+4.2: Reading Netnews and Mail with Gnus
+=======================================
+
+Q4.2.1: GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus, Quassia Gnus, argh!
+--------------------------------------------------------------------------------
+
+The Gnus numbering issues are not meant for mere mortals to know them.
+If you feel you _must_ enter the muddy waters of Gnus, visit the
+excellent FAQ, maintained by Justin Sheehy, at:
+
+     `http://www.ccs.neu.edu/software/contrib/gnus/'
+
+   See also Gnus home page
+     `http://www.gnus.org/'
+
+\1f
+File: xemacs-faq.info,  Node: Q4.2.2,  Next: Q4.2.3,  Prev: Q4.2.1,  Up: Subsystems
+
+Q4.2.2: This question intentionally left blank.
+-----------------------------------------------
+
+Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.2.3,  Next: Q4.2.4,  Prev: Q4.2.2,  Up: Subsystems
+
+Q4.2.3: How do I make Gnus stay within a single frame?
+------------------------------------------------------
+
+The toolbar code to start Gnus opens the new frame--and it's a feature
+rather than a bug.  If you don't like it, but would still like to click
+on the seemly icon, use the following code:
+
+     (defun toolbar-news ()
+       (gnus))
+
+   It will redefine the callback function of the icon to just call
+`gnus', without all the fancy frame stuff.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.2.4,  Next: Q4.3.1,  Prev: Q4.2.3,  Up: Subsystems
+
+Q4.2.4: How do I customize the From: line?
+------------------------------------------
+
+How do I change the `From:' line?  I have set gnus-user-from-line to
+     Gail Gurman <gail.gurman@sybase.com>
+    , but XEmacs Gnus doesn't use it. Instead it uses
+     Gail Mara Gurman <gailg@deall>
+ and then complains that it's incorrect. Also, as you perhaps can see,
+my Message-ID is screwy. How can I change that?
+
+Lars Magne Ingebrigtsen <larsi@ifi.uio.no> writes:
+
+     Set `user-mail-address' to `gail.gurman@sybase.com' or
+     `mail-host-address' to `sybase.com'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.3.1,  Next: Q4.3.2,  Prev: Q4.2.4,  Up: Subsystems
+
+4.3: Other Mail & News
+======================
+
+Q4.3.1: How can I read and/or compose MIME messages?
+----------------------------------------------------
+
+VM supports MIME natively.
+
+   You probably want to use the Tools for MIME (tm).  *Note Q4.3.2::,
+for details.
+
+   Trey Jackson <trey@cs.berkeley.edu> has an Emacs & MIME web page at
+`http://bmrc.berkeley.edu/~trey/emacs/mime.html'.
+
+   Another possibility is RMIME.  You may find RMIME at
+`http://www.cinti.net/~rmoody/rmime/index.html'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.3.2,  Next: Q4.3.3,  Prev: Q4.3.1,  Up: Subsystems
+
+Q4.3.2: What is TM and where do I get it?
+-----------------------------------------
+
+TM stands for "Tools for MIME" and not Tiny MIME.  TM integrates with
+all major XEmacs packages like Gnus (all flavors), VM, MH-E, and
+mailcrypt.  It provides totally transparent and trouble-free MIME
+support.  When appropriate a message will be decoded in place in an
+XEmacs buffer.
+
+   TM now comes as a package with XEmacs 19.16 and XEmacs 20.2.
+
+   TM was written by MORIOKA Tomohiko <morioka@jaist.ac.jp> and
+KOBAYASHI Shuhei <shuhei-k@jaist.ac.jp>.
+
+   It is based on the work of UMEDA Masanobu
+<umerin@mse.kyutech.ac.jp>, the original writer of GNUS.
+
+   The following information is from the `README':
+
+   "tm" is a MIME package for GNU Emacs.  tm has following functions:
+
+   * MIME style multilingual header.
+
+   * MIME message viewer (mime/viewer-mode).
+
+   * MIME message composer (mime/editor-mode).
+
+   * MIME extenders for mh-e, GNUS, RMAIL and VM.
+
+   tm is available from following anonymous ftp sites:
+   * `ftp://ftp.unicamp.br/pub/mail/mime/tm/' (Brasil).
+
+   * `ftp://ftp.th-darmstadt.de/pub/editors/GNU-Emacs/lisp/mime/'
+     (Germany).
+
+   * `ftp://ftp.tnt.uni-hannover.de/pub/editors/xemacs/contrib/'
+     (Germany).
+
+   Don't let the installation procedure & instructions stop you from
+trying this package out--it's much simpler than it looks, and once
+installed, trivial to use.
+
+   Steve Youngs <youngs@xemacs.org> writes:
+
+     All the major Emacs Lisp based MUAs (Gnus, MH-E, and VM) all do
+     their own thing when it comes to MIME so you won't need TM to get
+     MIME support in these packages.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.3.3,  Next: Q4.3.4,  Prev: Q4.3.2,  Up: Subsystems
+
+Q4.3.3: Why isn't this `movemail' program working?
+--------------------------------------------------
+
+Ben Wing <ben@xemacs.org> writes:
+
+     It wasn't chown'ed/chmod'd correctly.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.3.4,  Next: Q4.3.5,  Prev: Q4.3.3,  Up: Subsystems
+
+Q4.3.4: Movemail is also distributed by Netscape?  Can that cause problems?
+---------------------------------------------------------------------------
+
+Steve Baur <steve@xemacs.org> writes:
+
+     Yes.  Always use the movemail installed with your XEmacs.  Failure
+     to do so can result in lost mail.
+
+   Please refer to Jamie Zawinski's <jwz@jwz.org> notes at
+`http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/movemail.html'.
+In particular, this document will show you how to make Netscape use the
+version of movemail configured for your system by the person who built
+XEmacs.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.3.5,  Next: Q4.4.1,  Prev: Q4.3.4,  Up: Subsystems
+
+Q4.3.5: Where do I find pstogif (required by tm)?
+-------------------------------------------------
+
+pstogif is part of the latex2html package.
+
+   Jan Vroonhof <vroonhof@math.ethz.ch> writes:
+
+   latex2html is best found at the CTAN hosts and their mirrors in
+`tex-archive/support/latex2html'.
+
+   CTAN hosts are:
+
+   * `ftp://ftp.tex.ac.uk/tex-archive/support/latex2html/'.
+
+   * `ftp://ftp.dante.de/tex-archive/support/latex2html/'.
+
+   There is a good mirror at ftp.cdrom.com;
+`ftp://ftp.cdrom.com/pub/tex/ctan/support/latex2html/'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.4.1,  Next: Q4.4.2,  Prev: Q4.3.5,  Up: Subsystems
+
+4.4: Sparcworks, EOS, and WorkShop
+==================================
+
+Q4.4.1: What is SPARCworks, EOS, and WorkShop?
+----------------------------------------------
+
+John Turner <turner@lanl.gov> writes:
+
+     SPARCworks is SunSoft's development environment, comprising
+     compilers (C, C++, FORTRAN 77, Fortran 90, Ada, and Pascal), a
+     debugger, and other tools such as TeamWare (for configuration
+     management), MakeTool, etc.
+
+   See `http://www.sun.com/software/Developer-products/' for more info.
+
+   EOS stands for "Era on SPARCworks", but I don't know what Era stands
+for.
+
+   EOS is the integration of XEmacs with the SPARCworks debugger.  It
+allows one to use an XEmacs frame to view code (complete with
+fontification, etc.), set breakpoints, print variables, etc., while
+using the SPARCworks debugger.  It works very well and I use it all the
+time.
+
+   Chuck Thompson <cthomp@xemacs.org> writes:
+
+     Era stood for "Emacs Rewritten Again".  It was what we were
+     calling the modified version of Lucid Emacs for Sun when I was
+     dragged, er, allowed to work on this wonderful editor.
+
+   Martin Buchholz <martin@xemacs.org> writes:
+
+     EOS is being replaced with a new graphical development environment
+     called Sun WorkShop, which is currently (07/96) in Alpha Test.
+     For more details, check out
+     `http://www.sun.com/software/Products/Developer-products'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.4.2,  Next: Q4.5.1,  Prev: Q4.4.1,  Up: Subsystems
+
+Q4.4.2: How do I start the Sun Workshop support in XEmacs 21?
+-------------------------------------------------------------
+
+Add the switch --with-workshop to the configure command when building
+XEmacs and put the following in one of your startup files (e.g.
+site-start.el or .emacs):
+
+     (when (featurep 'tooltalk)
+       (load "tooltalk-macros")
+       (load "tooltalk-util")
+       (load "tooltalk-init"))
+     (when (featurep 'sparcworks)
+       (load "sunpro-init")
+       (load "ring")
+       (load "comint")
+       (load "annotations")
+       (sunpro-startup))
+
+   If you are not using the latest Workshop (5.0) you have to apply the
+following patch:
+
+--- /opt/SUNWspro/lib/eserve.el.ORIG    Fri May 14 15:23:26 1999
++++ /opt/SUNWspro/lib/eserve.el Fri May 14 15:24:54 1999
+@@ -42,7 +42,7 @@
+ (defvar running-xemacs nil "t if we're running XEmacs")
+ (defvar running-emacs  nil "t if we're running GNU Emacs 19")
+
+-(if (string-match "^\\(19\\|20\\)\..*\\(XEmacs\\|Lucid\\)" emacs-version)
++(if (string-match "\\(XEmacs\\|Lucid\\)" emacs-version)
+     (setq running-xemacs t)
+     (setq running-emacs  t))
+
+\1f
+File: xemacs-faq.info,  Node: Q4.5.1,  Next: Q4.6.1,  Prev: Q4.4.2,  Up: Subsystems
+
+4.5: Energize
+=============
+
+Q4.5.1: What is/was Energize?
+-----------------------------
+
+David N Gray <gray@meteor.harlequin.com> writes:
+
+     The files in `lisp/energize' are to enable Emacs to interface with
+     the "Energize Programming System", a C and C++ development
+     environment, which was a product of Lucid, Inc.  Tragically, Lucid
+     went out of business in 1994, so although Energize is still a
+     great system, if you don't already have it, there isn't any way to
+     get it now.  (Unless you happen to be in Japan; INS Engineering
+     may still be selling it there.  Tartan bought the rights to sell
+     it in the rest of the world, but never did so.)
+
+\1f
+File: xemacs-faq.info,  Node: Q4.6.1,  Next: Q4.7.1,  Prev: Q4.5.1,  Up: Subsystems
+
+4.6: Infodock
+=============
+
+Q4.6.1: What is Infodock?
+-------------------------
+
+InfoDock (http://sourceforge.net/projects/infodock/) is an integrated
+productivity toolset, mainly aimed at technical people, hosted at
+SourceForge.
+
+   InfoDock is built atop the XEmacs variant of GNU Emacs and so has
+all of the power of Emacs, but with an easier to use and more
+comprehensive menu-based user interface.  The bottom portion of this
+text describes how it differs from XEmacs and GNU Emacs from the Free
+Software Foundation.
+
+   InfoDock is aimed at people who want a free, turn-key productivity
+environment.  Although InfoDock is customizable, it is not intended for
+people who like basic versions of Emacs which need to be customized
+extensively for local use; standard Emacs distributions are better for
+such uses.  InfoDock is for those people who want a complete,
+pre-customized environment in one package, which they need not touch
+more than once or twice a year to update to new revisions.
+
+   InfoDock is pre-built for SPARC SunOS/Solaris systems, PA-RISC HP-UX,
+and Intel Linux systems.  It is intended for use on a color display,
+although most features will work on monochrome monitors.  Simply unpack
+InfoDock according to the instructions in the ID-INSTALL file and you
+are ready to run.
+
+   The InfoDock Manual is concise, yet sufficient as a user guide for
+users who have never used an Emacs-type editor before.  For users who
+are already familiar with Emacs, it supplements the information in the
+GNU Emacs Manual.
+
+   InfoDock menus are much more extensive and more mature than standard
+Emacs menus.  Each menu offers a `Manual' item which displays
+documentation associated with the menu's functions.
+
+Four types of menubars are provided:
+  1. An extensive menubar providing access to global InfoDock commands.
+
+  2. Mode-specific menubars tailored to the current major mode.
+
+  3. A simple menubar for basic editing to help novices get started
+     with InfoDock.
+
+  4. The standard XEmacs menubar.
+
+   Most modes also include mode-specific popup menus.  Additionally,
+region and rectangle popup menus are included.
+
+   `Hyperbole', the everyday information manager, is a core part of
+InfoDock.  This provides context-sensitive mouse keys, a rolodex-type
+contact manager, programmable hypertext buttons, and an autonumbered
+outliner with embedded hyperlink anchors.
+
+   The `OO-Browser', a multi-language object-oriented code browser, is a
+standard part of InfoDock.
+
+   InfoDock saves a more extensive set of user options than other Emacs
+versions.
+
+   InfoDock inserts a useful file header in many file types, showing the
+author, summary, and last modification time of each file.  A summary
+program can then be used to summarize all of the files in a directory,
+for easy MANIFEST file creation.
+
+   Your working set of buffers is automatically saved and restored (if
+you answer yes to a prompt) between InfoDock sessions.
+
+   Refined color choices for code highlighting are provided for both
+dark and light background display frames.
+
+   The `C-z' key prefix performs frame-based commands which parallel the
+`C-x' key prefix for window-based commands.
+
+   The Smart Menu system is included for producing command menus on dumb
+terminals.
+
+   Lisp libraries are better categorized according to function.
+
+   Extensions and improvements to many areas of Emacs are included,
+such as: paragraph filling, mail reading with Rmail, shell handling,
+outlining, code highlighting and browsing, and man page browsing.
+
+   InfoDock questions, answers and discussion should go to the mail list
+<infodock@infodock.com>.  Use <infodock-request@infodock.com> to be
+added or removed from the list.  Always include your InfoDock version
+number when sending help requests.
+
+   InfoDock is available across the Internet via anonymous FTP.  To get
+it, first move to a directory into which you want the InfoDock archive
+files placed.  We will call this <DIST-DIR>.
+
+        cd <DIST-DIR>
+
+   Ftp to ftp.xemacs.org  (Internet Host ID = 128.174.252.16):
+
+        prompt> ftp ftp.xemacs.org
+
+   Login as `anonymous' with your own <user-id>@<site-name> as a
+password.
+
+        Name (ftp.xemacs.org): anonymous
+        331 Guest login ok, send your complete e-mail address as password.
+        Password: -<your-user-id>@<your-domain>
+        230 Guest login ok, access restrictions apply.
+
+   Move to the location of the InfoDock archives:
+
+        ftp> cd pub/infodock
+
+   Set your transfer mode to binary:
+
+        ftp> bin
+        200 Type set to I.
+
+   Turn off prompting:
+
+        ftp> prompt
+        Interactive mode off.
+
+   Retrieve the InfoDock archives that you want, either by using a `get
+<file>' for each file you want or by using the following to get a
+complete distribution, including all binaries:
+
+        ftp> mget ID-INSTALL
+        ftp> mget id-*
+
+   Close the FTP connection:
+
+        ftp> quit
+        221 Goodbye.
+
+   Read the `ID-INSTALL' file which you just retrieved for step-by-step
+installation instructions.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.1,  Next: Q4.7.2,  Prev: Q4.6.1,  Up: Subsystems
+
+4.7: Other Unbundled Packages
+=============================
+
+Q4.7.1: What is AUC TeX?  Where do you get it?
+----------------------------------------------
+
+AUC TeX is a package written by Per Abrahamsen <abraham@dina.kvl.dk>.
+Starting with XEmacs 19.16, AUC TeX is bundled with XEmacs.  The
+following information is from the `README' and website.
+
+   AUC TeX is an extensible package that supports writing and formatting
+TeX files for most variants of GNU Emacs. Many different macro packages
+are supported, including AMS TeX, LaTeX, and TeXinfo.
+
+   The most recent version is always available by ftp at
+`ftp://sunsite.dk/packages/auctex/auctex.tar.gz'.
+
+   In case you don't have access to anonymous ftp, you can get it by an
+email request to <ftpmail@decwrl.dec.com>.
+
+   WWW users may want to check out the AUC TeX page at
+`http://sunsite.dk/auctex/'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.2,  Next: Q4.7.3,  Prev: Q4.7.1,  Up: Subsystems
+
+Q4.7.2: Are there any Emacs Lisp Spreadsheets?
+----------------------------------------------
+
+Yes.  Check out "dismal" (which stands for Dis' Mode Ain't Lotus) at
+`ftp://cs.nyu.edu/pub/local/fox/dismal/'.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.3,  Next: Q4.7.4,  Prev: Q4.7.2,  Up: Subsystems
+
+Q4.7.3: [This question intentionally left blank]
+------------------------------------------------
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.4,  Next: Q4.7.5,  Prev: Q4.7.3,  Up: Subsystems
+
+Q4.7.4: Problems installing AUC TeX.
+------------------------------------
+
+Jan Vroonhof <vroonhof@math.ethz.ch> writes:
+
+     AUC TeX works fine on both stock Emacs and XEmacs has been doing
+     so for a very very long time. This is mostly due to the work of
+     Per Abrahamsen <abraham@dina.kvl.dk> (clap clap) in particular his
+     `easymenu' package.  Which leads to what is probably the problem...
+
+   Most problems with AUC TeX are one of two things:
+
+   * The TeX-lisp-directory in `tex-site.el' and the makefile don't
+     match.
+
+     Fix: make sure you configure AUC TeX properly *before* installing.
+
+   * You have an old version of easymenu.el in your path.
+
+     Fix: use `locate-library' and remove old versions to make sure it
+     *only* finds the one that came with XEmacs.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.5,  Next: Q4.7.6,  Prev: Q4.7.4,  Up: Subsystems
+
+Q4.7.5: Is there a reason for an Emacs package not to be included in XEmacs?
+----------------------------------------------------------------------------
+
+The reason for an Emacs package not to be included in XEmacs is usually
+one or more of the following:
+
+  1. The package has not been ported to XEmacs.  This will typically
+     happen when it uses GNU-Emacs-specific features, which make it
+     fail under XEmacs.
+
+     Porting a package to XEmacs can range from a trivial amount of
+     change to a partial or full rewrite.  Fortunately, the authors of
+     modern packages usually choose to support both Emacsen themselves.
+
+  2. The package has been decided not to be appropriate for XEmacs.  It
+     may have an equivalent or better replacement within XEmacs, in
+     which case the developers may choose not to burden themselves with
+     supporting an additional package.
+
+     Each package bundled with XEmacs means more work for the
+     maintainers, whether they want it or not.  If you are ready to
+     take over the maintenance responsibilities for the package you
+     port, be sure to say so--we will more likely include it.
+
+  3. The package simply hasn't been noted by the XEmacs development.  If
+     that's the case, the messages like yours are very useful for
+     attracting our attention.
+
+  4. The package was noted by the developers, but they simply haven't
+     yet gotten around to including/porting it.  Wait for the next
+     release or, even better, offer your help.  It will be gladly
+     accepted and appreciated.
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.6,  Next: Q4.7.7,  Prev: Q4.7.5,  Up: Subsystems
+
+Q4.7.5: Is there a MatLab mode?
+-------------------------------
+
+Yes, a matlab mode and other items are available at the MathWorks'
+emacs_add_ons ftp directory
+(ftp://ftp.mathworks.com/pub/contrib/emacs_add_ons).
+
+\1f
+File: xemacs-faq.info,  Node: Q4.7.7,  Prev: Q4.7.6,  Up: Subsystems
+
+Q4.7.7: Can I edit files on other hosts?
+----------------------------------------
+
+Yes.  Of course XEmacs can use any network file system (such as NFS or
+Windows file sharing) you have available, and includes some
+optimizations and safety features appropriate to those environments.
+
+   It is also possible to transparently edit files via FTP, ssh, or
+rsh.  That is, XEmacs makes a local copy using the transport in the
+background, and automatically refreshes the remote original from that
+copy when you save it.  XEmacs also is capable of doing file system
+manipulations like creating and removing directories and files.  The
+FTP interface is provided by the standard `efs' package *Note EFS:
+(efs)Top.  The ssh/rsh interface is provided by the optional `tramp'
+package *Note TRAMP: (tramp)Top.
+
+\1f
+File: xemacs-faq.info,  Node: Miscellaneous,  Next: MS Windows,  Prev: Subsystems,  Up: Top
+
+5 The Miscellaneous Stuff
+*************************
+
+This is part 5 of the XEmacs Frequently Asked Questions list.  This
+section is devoted to anything that doesn't fit neatly into the other
+sections.
+
+* Menu:
+
+Major & Minor Modes:
+* Q5.0.1::      How can I do source code highlighting using font-lock?
+* Q5.0.2::      I do not like cc-mode.  How do I use the old c-mode?
+* Q5.0.3::      How do I get `More' Syntax Highlighting on by default?
+* Q5.0.4::      How can I enable auto-indent and/or Filladapt?
+* Q5.0.5::      How can I get XEmacs to come up in text/auto-fill mode by default?
+* Q5.0.6::      How do I start up a second shell buffer?
+* Q5.0.7::      Telnet from shell filters too much.
+* Q5.0.8::      Why does edt emulation not work?
+* Q5.0.9::      How can I emulate VI and use it as my default mode?
+* Q5.0.10::     [This question intentionally left blank]
+* Q5.0.11::     [This question intentionally left blank]
+* Q5.0.12::     How do I disable gnuserv from opening a new frame?
+* Q5.0.13::     How do I start gnuserv so that each subsequent XEmacs is a client?
+* Q5.0.14::     Strange things are happening in Shell Mode.
+* Q5.0.15::     Where do I get the latest CC Mode?
+* Q5.0.16::     I find auto-show-mode disconcerting.  How do I turn it off?
+* Q5.0.17::     How can I get two instances of info?
+* Q5.0.18::     [This question intentionally left blank]
+* Q5.0.19::     Is there something better than LaTeX mode?
+* Q5.0.20::     Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
+
+Emacs Lisp Programming Techniques:
+* Q5.1.1::      The difference in key sequences between XEmacs and GNU Emacs?
+* Q5.1.2::      Can I generate "fake" keyboard events?
+* Q5.1.3::      Could you explain `read-kbd-macro' in more detail?
+* Q5.1.4::      What is the performance hit of `let'?
+* Q5.1.5::      What is the recommended use of `setq'?
+* Q5.1.6::      What is the typical misuse of `setq'?
+* Q5.1.7::      I like the `do' form of cl, does it slow things down?
+* Q5.1.8::      I like recursion, does it slow things down?
+* Q5.1.9::      How do I put a glyph as annotation in a buffer?
+* Q5.1.10::     `map-extents' won't traverse all of my extents!
+* Q5.1.11::     My elisp program is horribly slow.  Is there an easy way to find out where it spends time?
+
+Sound:
+* Q5.2.1::      How do I turn off the sound?
+* Q5.2.2::      How do I get funky sounds instead of a boring beep?
+* Q5.2.3::      What's NAS, how do I get it?
+* Q5.2.4::      Sunsite sounds don't play.
+
+Miscellaneous:
+* Q5.3.1::      How do you make XEmacs indent CL if-clauses correctly?
+* Q5.3.2::      [This question intentionally left blank]
+* Q5.3.3::      How can I print WYSIWYG a font-locked buffer?
+* Q5.3.4::      Getting M-x lpr to work with postscript printer.
+* Q5.3.5::      How do I specify the paths that XEmacs uses for finding files?
+* Q5.3.6::      [This question intentionally left blank]
+* Q5.3.7::      Can I have the end of the buffer delimited in some way?
+* Q5.3.8::      How do I insert today's date into a buffer?
+* Q5.3.9::      Are only certain syntactic character classes available for abbrevs?
+* Q5.3.10::     How can I get those oh-so-neat X-Face lines?
+* Q5.3.11::     How do I add new Info directories?
+* Q5.3.12::     What do I need to change to make printing work?
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.1,  Next: Q5.0.2,  Prev: Miscellaneous,  Up: Miscellaneous
+
+5.0: Major & Minor Modes
+========================
+
+Q5.0.1: How can I do source code highlighting using font-lock?
+--------------------------------------------------------------
+
+For most modes, font-lock is already set up and just needs to be turned
+on.  This can be done by adding the line:
+
+     (require 'font-lock)
+
+   to your `init.el'/`.emacs'. (You can turn it on for the current
+buffer and session only by `M-x font-lock-mode'.) See the file
+`etc/sample.init.el' (`etc/sample.emacs' in XEmacs versions prior to
+21.4) for more information.
+
+   See also `Syntax Highlighting' from the `Options' menu.  Remember to
+save options.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.2,  Next: Q5.0.3,  Prev: Q5.0.1,  Up: Miscellaneous
+
+Q5.0.2: I do not like cc-mode.  How do I use the old c-mode?
+------------------------------------------------------------
+
+Well, first off, consider if you really want to do this.  cc-mode is
+much more powerful than the old c-mode.  If you're having trouble
+getting your old offsets to work, try using `c-set-offset' instead.
+You might also consider using the package `cc-compat'.
+
+   But, if you still insist, add the following lines to your
+`init.el'/`.emacs':
+
+     (fmakunbound 'c-mode)
+     (makunbound 'c-mode-map)
+     (fmakunbound 'c++-mode)
+     (makunbound 'c++-mode-map)
+     (makunbound 'c-style-alist)
+     (load-library "old-c-mode")
+     (load-library "old-c++-mode")
+
+   This must be done before any other reference is made to either
+c-mode or c++-mode.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.3,  Next: Q5.0.4,  Prev: Q5.0.2,  Up: Miscellaneous
+
+Q5.0.3: How do I get `More' Syntax Highlighting on by default?
+--------------------------------------------------------------
+
+Use the following code in your `init.el'/`.emacs':
+
+     (setq-default font-lock-maximum-decoration t)
+
+   See also `Syntax Highlighting' from the `Options' menu.  Remember to
+save options.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.4,  Next: Q5.0.5,  Prev: Q5.0.3,  Up: Miscellaneous
+
+Q5.0.4: How can I enable auto-indent and/or Filladapt?
+------------------------------------------------------
+
+Put the following line in your `init.el'/`.emacs':
+
+     (setq indent-line-function 'indent-relative-maybe)
+
+   If you want to get fancy, try the `filladapt' package available
+standard with XEmacs.  Put this into your `init.el'/`.emacs':
+
+     (require 'filladapt)
+     (setq-default filladapt-mode t)
+     (add-hook 'c-mode-hook 'turn-off-filladapt-mode)
+
+   This will enable Filladapt for all modes except C mode, where it
+doesn't work well.  To turn Filladapt on only in particular major
+modes, remove the `(setq-default ...)' line and use
+`turn-on-filladapt-mode', like this:
+
+     (add-hook 'text-mode-hook 'turn-on-filladapt-mode)
+
+   You can customize filling and adaptive filling with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Editing->Fill->Fill...' or type `M-x customize
+<RET> fill <RET>'.
+
+   Note that well-behaving text-lookalike modes will run
+`text-mode-hook' by default (e.g. that's what Message does).  For the
+nasty ones, you'll have to provide the `add-hook's yourself.
+
+   Please note that the `fa-extras' package is no longer useful.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.5,  Next: Q5.0.6,  Prev: Q5.0.4,  Up: Miscellaneous
+
+Q5.0.5: How can I get XEmacs to come up in text/auto-fill mode by default?
+--------------------------------------------------------------------------
+
+Try the following lisp in your `init.el'/`.emacs':
+
+     (setq default-major-mode 'text-mode)
+     (setq text-mode-hook 'turn-on-auto-fill)
+
+   *WARNING*: note that changing the value of `default-major-mode' from
+`fundamental-mode' can break a large amount of built-in code that
+expects newly created buffers to be in `fundamental-mode'.  (Changing
+from `fundamental-mode' to `text-mode' might not wreak too much havoc,
+but changing to something more exotic like a lisp-mode would break many
+Emacs packages).
+
+   Note that Emacs by default starts up in buffer `*scratch*' in
+`initial-major-mode', which defaults to `lisp-interaction-mode'. Thus
+adding the following form to your Emacs init file will cause the
+initial `*scratch*' buffer to be put into auto-fill'ed `text-mode':
+
+     (setq initial-major-mode
+           (lambda ()
+             (text-mode)
+             (turn-on-auto-fill)))
+
+   Note that after your init file is loaded, if
+`inhibit-startup-message' is `nil' (the default) and the startup buffer
+is `*scratch*' then the startup message will be inserted into
+`*scratch*'; it will be removed after a timeout by erasing the entire
+`*scratch*' buffer.  Keep in mind this default usage of `*scratch*' if
+you desire any prior manipulation of `*scratch*' from within your Emacs
+init file. In particular, anything you insert into `*scratch*' from
+your init file will be later erased. Also, if you change the mode of
+the `*scratch*' buffer, be sure that this will not interfere with
+possible later insertion of the startup message (e.g. if you put
+`*scratch*' into a nonstandard mode that has automatic font lock rules,
+then the startup message might get fontified in a strange foreign
+manner, e.g. as code in some programming language).
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.6,  Next: Q5.0.7,  Prev: Q5.0.5,  Up: Miscellaneous
+
+Q5.0.6: How do I start up a second shell buffer?
+------------------------------------------------
+
+In the `*shell*' buffer:
+
+     M-x rename-buffer <RET> *shell-1* <RET>
+     M-x shell RET
+
+   This will then start a second shell.  The key is that no buffer named
+`*shell*' can exist.  It might be preferable to use `M-x
+rename-uniquely' to rename the `*shell*' buffer instead of `M-x
+rename-buffer'.
+
+   Alternately, you can set the variable `shell-multiple-shells'.  If
+the value of this variable is non-nil, each time shell mode is invoked,
+a new shell is made
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.7,  Next: Q5.0.8,  Prev: Q5.0.6,  Up: Miscellaneous
+
+Q5.0.7: Telnet from shell filters too much
+------------------------------------------
+
+I'm using the Emacs `M-x shell' function, and I would like to invoke
+and use a telnet session within it.  Everything works fine except that
+now all `^M''s are filtered out by Emacs.  Fixes?
+
+   Use `M-x rsh' or `M-x telnet' to open remote sessions rather than
+doing rsh or telnet within the local shell buffer.  Starting with
+XEmacs-20.3 you can also use `M-x ssh' to open secure remote session if
+you have `ssh' installed.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.8,  Next: Q5.0.9,  Prev: Q5.0.7,  Up: Miscellaneous
+
+Q5.0.8: Why does edt emulation not work?
+----------------------------------------
+
+We don't know, but you can use tpu-edt emulation instead, which works
+fine and is a little fancier than the standard edt emulation.  To do
+this, add the following line to your `init.el'/`.emacs':
+
+     (tpu-edt)
+
+   If you don't want it to replace `C-h' with an edt-style help menu
+add this as well:
+
+     (global-set-key [(control h)] 'help-for-help)
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.9,  Next: Q5.0.10,  Prev: Q5.0.8,  Up: Miscellaneous
+
+Q5.0.9: How can I emulate VI and use it as my default mode?
+-----------------------------------------------------------
+
+Our recommended VI emulator is viper. To make viper-mode the default,
+add this to your `init.el'/`.emacs':
+
+     (viper-mode)
+
+   Michael Kifer <kifer@CS.SunySB.EDU> writes:
+
+     This should be added as close to the top of `init.el'/`.emacs' as
+     you can get it, otherwise some minor modes may not get viper-ized.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.10,  Next: Q5.0.11,  Prev: Q5.0.9,  Up: Miscellaneous
+
+Q5.0.10: [This question intentionally left blank]
+-------------------------------------------------
+
+Obsolete question, left blank to avoid renumbering
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.11,  Next: Q5.0.12,  Prev: Q5.0.10,  Up: Miscellaneous
+
+Q5.0.11: [This question intentionally left blank]
+-------------------------------------------------
+
+Obsolete question, left blank to avoid renumbering
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.12,  Next: Q5.0.13,  Prev: Q5.0.11,  Up: Miscellaneous
+
+Q5.0.12: How do I disable gnuserv from opening a new frame?
+-----------------------------------------------------------
+
+If you set the `gnuserv-frame' variable to the frame that should be
+used to display buffers that are pulled up, a new frame will not be
+created. For example, you could put
+
+     (setq gnuserv-frame (selected-frame))
+
+   early on in your `init.el'/`.emacs', to ensure that the first frame
+created is the one used for your gnuserv buffers.
+
+   There is an option to set the gnuserv target to the current frame.
+See `Options->Display->"Other Window" Location->Make Current Frame
+Gnuserv Target'
+
+   Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Gnuserv->Gnuserv Frame...' or type
+`M-x customize <RET> gnuserv <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.13,  Next: Q5.0.14,  Prev: Q5.0.12,  Up: Miscellaneous
+
+Q5.0.13: How do I start gnuserv so that each subsequent XEmacs is a client?
+---------------------------------------------------------------------------
+
+Put the following in your `init.el'/`.emacs' file to start the server:
+
+     (gnuserv-start)
+
+   Start your first XEmacs as usual.  After that, you can do:
+
+     gnuclient randomfilename
+
+   from the command line to get your existing XEmacs process to open a
+new frame and visit randomfilename in that window. When you're done
+editing randomfilename, hit `C-x #' to kill the buffer and get rid of
+the frame.
+
+   See also man page of gnuclient.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.14,  Next: Q5.0.15,  Prev: Q5.0.13,  Up: Miscellaneous
+
+Q5.0.14: Strange things are happening in Shell Mode.
+----------------------------------------------------
+
+Sometimes (i.e. it's not repeatable, and I can't work out why it
+happens) when I'm typing into shell mode, I hit return and only a
+portion of the command is given to the shell, and a blank prompt is
+returned.  If I hit return again, the rest of the previous command is
+given to the shell.
+
+   Martin Buchholz <martin@xemacs.org> writes:
+
+     There is a known problem with interaction between `csh' and the
+     `filec' option and XEmacs.  You should add the following to your
+     `.cshrc':
+
+          if ( "$TERM" == emacs || "$TERM" == unknown ) unset filec
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.15,  Next: Q5.0.16,  Prev: Q5.0.14,  Up: Miscellaneous
+
+Q5.0.15: Where do I get the latest CC Mode?
+-------------------------------------------
+
+Barry A. Warsaw <bwarsaw@cnri.reston.va.us> writes:
+
+     This can be had from `http://www.python.org/emacs/'.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.16,  Next: Q5.0.17,  Prev: Q5.0.15,  Up: Miscellaneous
+
+Q5.0.16: I find auto-show-mode disconcerting.  How do I turn it off?
+--------------------------------------------------------------------
+
+`auto-show-mode' controls whether or not a horizontal scrollbar
+magically appears when a line is too long to be displayed.  This is
+enabled by default.  To turn it off, put the following in your
+`init.el'/`.emacs':
+
+     (setq auto-show-mode nil)
+     (setq-default auto-show-mode nil)
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.17,  Next: Q5.0.18,  Prev: Q5.0.16,  Up: Miscellaneous
+
+Q5.0.17: How can I get two instances of info?
+---------------------------------------------
+
+Before 21.4, you can't.  The `info' package does not provide for
+multiple info buffers.  In 21.4, this should be fixed. #### how?
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.18,  Next: Q5.0.19,  Prev: Q5.0.17,  Up: Miscellaneous
+
+Q5.0.18: [This question intentionally left blank]
+-------------------------------------------------
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.19,  Next: Q5.0.20,  Prev: Q5.0.18,  Up: Miscellaneous
+
+Q5.0.19: Is there something better than LaTeX mode?
+---------------------------------------------------
+
+David Kastrup <dak@fsnif.neuroinformatik.ruhr-uni-bochum.de> writes:
+
+     The standard TeX modes leave much to be desired, and are somewhat
+     leniently maintained.  Serious TeX users use AUC TeX (*note
+     Q4.7.1::).
+
+\1f
+File: xemacs-faq.info,  Node: Q5.0.20,  Next: Q5.1.1,  Prev: Q5.0.19,  Up: Miscellaneous
+
+Q5.0.20: Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
+---------------------------------------------------------------------------------------------------------
+
+Jan Vroonhof <vroonhof@math.ethz.ch> writes:
+
+     Here is one of the solutions, we have this in a script called
+     `etc/editclient.sh'.
+           #!/bin/sh
+           if gnuclient -batch -eval t >/dev/null 2>&1
+           then
+             exec gnuclient ${1+"$@"}
+           else
+             xemacs -unmapped -f gnuserv-start &
+             until gnuclient -batch -eval t >/dev/null 2>&1
+             do
+                sleep 1
+             done
+             exec gnuclient ${1+"$@"}
+           fi
+
+     Note that there is a known problem when running XEmacs and
+     'gnuclient -nw' on the same TTY.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.1,  Next: Q5.1.2,  Prev: Q5.0.20,  Up: Miscellaneous
+
+5.1: Emacs Lisp Programming Techniques
+======================================
+
+Q5.1.1: What is the difference in key sequences between XEmacs and GNU Emacs?
+-----------------------------------------------------------------------------
+
+Erik Naggum <clerik@naggum.no> writes;
+
+     Emacs has a legacy of keyboards that produced characters with
+     modifier bits, and therefore map a variety of input systems into
+     this scheme even today.  XEmacs is instead optimized for X events.
+     This causes an incompatibility in the way key sequences are
+     specified, but both Emacs and XEmacs will accept a key sequence as
+     a vector of lists of modifiers that ends with a key, e.g., to bind
+     `M-C-a', you would say `[(meta control a)]' in both Emacsen.
+     XEmacs has an abbreviated form for a single key, just (meta
+     control a).  Emacs has an abbreviated form for the Control and the
+     Meta modifiers to string-characters (the ASCII characters), as in
+     `\M-\C-a'.  XEmacs users need to be aware that the abbreviated
+     form works only for one-character key sequences, while Emacs users
+     need to be aware that the string-character is rather limited.
+     Specifically, the string-character can accommodate only 256
+     different values, 128 of which have the Meta modifier and 128 of
+     which have not.  In each of these blocks, only 32 characters have
+     the Control modifier.  Whereas `[(meta control A)]' differs from
+     `[(meta control a)]' because the case differs, `\M-\C-a' and
+     `\M-\C-A' do not.  Programmers are advised to use the full common
+     form, both because it is more readable and less error-prone, and
+     because it is supported by both Emacsen.
+
+   Another (even safer) way to be sure of the key-sequences is to use
+the `read-kbd-macro' function, which takes a string like `C-c <up>',
+and converts it to the internal key representation of the Emacs you
+use.  The function is available both on XEmacs and GNU Emacs.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.2,  Next: Q5.1.3,  Prev: Q5.1.1,  Up: Miscellaneous
+
+Q5.1.2: Can I generate "fake" keyboard events?
+----------------------------------------------
+
+I wonder if there is an interactive function that can generate "fake"
+keyboard events.  This way, I could simply map them inside XEmacs.
+
+   This seems to work:
+
+     (defun cg--generate-char-event (ch)
+       "Generate an event, as if ch has been typed"
+       (dispatch-event (character-to-event ch)))
+     
+     ;;  Backspace and Delete stuff
+     (global-set-key [backspace]
+       (lambda () (interactive) (cg--generate-char-event 127)))
+     (global-set-key [unknown_keysym_0x4]
+       (lambda () (interactive) (cg--generate-char-event 4)))
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.3,  Next: Q5.1.4,  Prev: Q5.1.2,  Up: Miscellaneous
+
+Q5.1.3: Could you explain `read-kbd-macro' in more detail?
+----------------------------------------------------------
+
+The `read-kbd-macro' function returns the internal Emacs representation
+of a human-readable string (which is its argument).  Thus:
+
+     (read-kbd-macro "C-c C-a")
+     => [(control ?c) (control ?a)]
+     
+     (read-kbd-macro "C-c C-. <up>")
+     => [(control ?c) (control ?.) up]
+
+   In GNU Emacs the same forms will be evaluated to what GNU Emacs
+understands internally--the sequences `"\C-x\C-c"' and `[3 67108910
+up]', respectively.
+
+   The exact "human-readable" syntax is defined in the docstring of
+`edmacro-mode'.  I'll repeat it here, for completeness.
+
+     Format of keyboard macros during editing:
+
+     Text is divided into "words" separated by whitespace.  Except for
+     the words described below, the characters of each word go directly
+     as characters of the macro.  The whitespace that separates words is
+     ignored.  Whitespace in the macro must be written explicitly, as in
+     `foo <SPC> bar <RET>'.
+
+        * The special words `RET', `SPC', `TAB', `DEL', `LFD', `ESC',
+          and `NUL' represent special control characters.  The words
+          must be written in uppercase.
+
+        * A word in angle brackets, e.g., `<return>', `<down>', or
+          `<f1>', represents a function key.  (Note that in the standard
+          configuration, the function key `<return>' and the control key
+          <RET> are synonymous.)  You can use angle brackets on the
+          words <RET>, <SPC>, etc., but they are not required there.
+
+        * Keys can be written by their ASCII code, using a backslash
+          followed by up to six octal digits.  This is the only way to
+          represent keys with codes above \377.
+
+        * One or more prefixes `M-' (meta), `C-' (control), `S-'
+          (shift), `A-' (alt), `H-' (hyper), and `s-' (super) may
+          precede a character or key notation.  For function keys, the
+          prefixes may go inside or outside of the brackets: `C-<down>'
+          == `<C-down>'.  The prefixes may be written in any order:
+          `M-C-x' == `C-M-x'.
+
+          Prefixes are not allowed on multi-key words, e.g., `C-abc',
+          except that the Meta prefix is allowed on a sequence of
+          digits and optional minus sign: `M--123' == `M-- M-1 M-2 M-3'.
+
+        * The `^' notation for control characters also works: `^M' ==
+          `C-m'.
+
+        * Double angle brackets enclose command names: `<<next-line>>'
+          is shorthand for `M-x next-line <RET>'.
+
+        * Finally, `REM' or `;;' causes the rest of the line to be
+          ignored as a comment.
+
+     Any word may be prefixed by a multiplier in the form of a decimal
+     number and `*': `3*<right>' == `<right> <right> <right>', and
+     `10*foo' == `foofoofoofoofoofoofoofoofoofoo'.
+
+     Multiple text keys can normally be strung together to form a word,
+     but you may need to add whitespace if the word would look like one
+     of the above notations: `; ; ;' is a keyboard macro with three
+     semicolons, but `;;;' is a comment.  Likewise, `\ 1 2 3' is four
+     keys but `\123' is a single key written in octal, and `< right >'
+     is seven keys but `<right>' is a single function key.  When in
+     doubt, use whitespace.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.4,  Next: Q5.1.5,  Prev: Q5.1.3,  Up: Miscellaneous
+
+Q5.1.4: What is the performance hit of `let'?
+---------------------------------------------
+
+In most cases, not noticeable.  Besides, there's no avoiding `let'--you
+have to bind your local variables, after all.  Some pose a question
+whether to nest `let's, or use one `let' per function.  I think because
+of clarity and maintenance (and possible future implementation),
+`let'-s should be used (nested) in a way to provide the clearest code.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.5,  Next: Q5.1.6,  Prev: Q5.1.4,  Up: Miscellaneous
+
+Q5.1.5: What is the recommended use of `setq'?
+----------------------------------------------
+
+   * Global variables
+
+     You will typically `defvar' your global variable to a default
+     value, and use `setq' to set it later.
+
+     It is never a good practice to `setq' user variables (like
+     `case-fold-search', etc.), as it ignores the user's choice
+     unconditionally.  Note that `defvar' doesn't change the value of a
+     variable if it was bound previously.  If you wish to change a
+     user-variable temporarily, use `let':
+
+          (let ((case-fold-search nil))
+            ...                                   ; code with searches that must be case-sensitive
+            ...)
+
+     You will notice the user-variables by their docstrings beginning
+     with an asterisk (a convention).
+
+   * Local variables
+
+     Bind them with `let', which will unbind them (or restore their
+     previous value, if they were bound) after exiting from the `let'
+     form.  Change the value of local variables with `setq' or whatever
+     you like (e.g. `incf', `setf' and such).  The `let' form can even
+     return one of its local variables.
+
+     Typical usage:
+
+          ;; iterate through the elements of the list returned by
+          ;; `hairy-function-that-returns-list'
+          (let ((l (hairy-function-that-returns-list)))
+            (while l
+              ... do something with (car l) ...
+              (setq l (cdr l))))
+
+     Another typical usage includes building a value simply to work
+     with it.
+
+          ;; Build the mode keymap out of the key-translation-alist
+          (let ((inbox (file-truename (expand-file-name box)))
+                (i 0))
+            ... code dealing with inbox ...
+            inbox)
+
+     This piece of code uses the local variable `inbox', which becomes
+     unbound (or regains old value) after exiting the form.  The form
+     also returns the value of `inbox', which can be reused, for
+     instance:
+
+          (setq foo-processed-inbox
+                (let .....))
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.6,  Next: Q5.1.7,  Prev: Q5.1.5,  Up: Miscellaneous
+
+Q5.1.6: What is the typical misuse of `setq' ?
+----------------------------------------------
+
+A typical misuse is probably `setq'ing a variable that was meant to be
+local.  Such a variable will remain bound forever, never to be
+garbage-collected.  For example, the code doing:
+
+     (defun my-function (whatever)
+       (setq a nil)
+       ... build a large list ...
+       ... and exit ...)
+
+   does a bad thing, as `a' will keep consuming memory, never to be
+unbound.  The correct thing is to do it like this:
+
+     (defun my-function (whatever)
+       (let (a)                              ; default initialization is to nil
+         ... build a large list ...
+         ... and exit, unbinding `a' in the process  ...)
+
+   Not only is this prettier syntactically, but it makes it possible for
+Emacs to garbage-collect the objects which `a' used to reference.
+
+   Note that even global variables should not be `setq'ed without
+`defvar'ing them first, because the byte-compiler issues warnings.  The
+reason for the warning is the following:
+
+     (defun flurgoze nil)                    ; ok, global internal variable
+     ...
+     
+     (setq flurghoze t)                      ; ops!  a typo, but semantically correct.
+                                             ; however, the byte-compiler warns.
+     
+     While compiling toplevel forms:
+     ** assignment to free variable flurghoze
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.7,  Next: Q5.1.8,  Prev: Q5.1.6,  Up: Miscellaneous
+
+Q5.1.7: I like the `do' form of cl, does it slow things down?
+-------------------------------------------------------------
+
+It shouldn't.  Here is what Dave Gillespie has to say about cl.el
+performance:
+
+     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.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.8,  Next: Q5.1.9,  Prev: Q5.1.7,  Up: Miscellaneous
+
+Q5.1.8: I like recursion, does it slow things down?
+---------------------------------------------------
+
+Yes.  Emacs byte-compiler cannot do much to optimize recursion.  But
+think well whether this is a real concern in Emacs.  Much of the Emacs
+slowness comes from internal mechanisms such as redisplay, or from the
+fact that it is an interpreter.
+
+   Please try not to make your code much uglier to gain a very small
+speed gain.  It's not usually worth it.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.9,  Next: Q5.1.10,  Prev: Q5.1.8,  Up: Miscellaneous
+
+Q5.1.9: How do I put a glyph as annotation in a buffer?
+-------------------------------------------------------
+
+Here is a solution that will insert the glyph annotation at the
+beginning of buffer:
+
+     (make-annotation (make-glyph '([FORMAT :file FILE]
+                                    [string :data "fallback-text"]))
+                      (point-min)
+                      'text
+                      (current-buffer))
+
+   Replace `FORMAT' with an unquoted symbol representing the format of
+the image (e.g. `xpm', `xbm', `gif', `jpeg', etc.)  Instead of `FILE',
+use the image file name (e.g.
+`/usr/local/lib/xemacs-21.4/etc/recycle.xpm').
+
+   You can turn this to a function (that optionally prompts you for a
+file name), and inserts the glyph at `(point)' instead of `(point-min)'.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.10,  Next: Q5.1.11,  Prev: Q5.1.9,  Up: Miscellaneous
+
+Q5.1.10: `map-extents' won't traverse all of my extents!
+--------------------------------------------------------
+
+I tried to use `map-extents' to do an operation on all the extents in a
+region.  However, it seems to quit after processing a random number of
+extents.  Is it buggy?
+
+   No.  The documentation of `map-extents' states that it will iterate
+across the extents as long as FUNCTION returns `nil'.  Unexperienced
+programmers often forget to return `nil' explicitly, which results in
+buggy code.  For instance, the following code is supposed to delete all
+the extents in a buffer, and issue as many `fubar!' messages.
+
+     (map-extents (lambda (ext ignore)
+                    (delete-extent ext)
+                    (message "fubar!")))
+
+   Instead, it will delete only the first extent, and stop right there -
+because `message' will return a non-nil value.  The correct code is:
+
+     (map-extents (lambda (ext ignore)
+                    (delete-extent ext)
+                    (message "fubar!")
+                    nil))
+
+\1f
+File: xemacs-faq.info,  Node: Q5.1.11,  Next: Q5.2.1,  Prev: Q5.1.10,  Up: Miscellaneous
+
+Q5.1.11: My elisp program is horribly slow.  Is there
+-----------------------------------------------------
+
+an easy way to find out where it spends time?
+
+   Hrvoje Niksic <hniksic@xemacs.org> writes:
+
+     Under XEmacs 20.4 and later you can use `M-x profile-key-sequence',
+     press a key (say <RET> in the Gnus Group buffer), and get the
+     results using `M-x profile-results'.  It should give you an idea of
+     where the time is being spent.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.2.1,  Next: Q5.2.2,  Prev: Q5.1.11,  Up: Miscellaneous
+
+Q5.2.1: How do I turn off the sound?
+------------------------------------
+
+Add the following line to your `init.el'/`.emacs':
+
+     (setq bell-volume 0)
+     (setq sound-alist nil)
+
+   That will make your XEmacs totally silent--even the default ding
+sound (TTY beep on TTY-s) will be gone.
+
+   Starting with XEmacs 20.2 you can also change these with Customize.
+Select from the `Options' menu `Advanced
+(Customize)->Emacs->Environment->Sound->Sound...' or type `M-x
+customize <RET> sound <RET>'.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.2.2,  Next: Q5.2.3,  Prev: Q5.2.1,  Up: Miscellaneous
+
+Q5.2.2: How do I get funky sounds instead of a boring beep?
+-----------------------------------------------------------
+
+Make sure your XEmacs was compiled with sound support, and then put this
+in your `init.el'/`.emacs':
+
+     (load-default-sounds)
+
+\1f
+File: xemacs-faq.info,  Node: Q5.2.3,  Next: Q5.2.4,  Prev: Q5.2.2,  Up: Miscellaneous
+
+Q5.2.3: What's NAS, how do I get it?
+------------------------------------
+
+*Note Q2.0.3::, for an explanation of the "Network Audio System".
+
+\1f
+File: xemacs-faq.info,  Node: Q5.2.4,  Next: Q5.3.1,  Prev: Q5.2.3,  Up: Miscellaneous
+
+Q5.2.4: Sunsite sounds don't play.
+----------------------------------
+
+I'm having some trouble with sounds I've downloaded from sunsite.  They
+play when I run them through `showaudio' or cat them directly to
+`/dev/audio', but XEmacs refuses to play them.
+
+   Markus Gutschke <gutschk@uni-muenster.de> writes:
+
+     [Many of] These files have an (erroneous) 24byte header that tells
+     about the format that they have been recorded in. If you cat them
+     to `/dev/audio', the header will be ignored and the default
+     behavior for /dev/audio will be used. This happens to be 8kHz
+     uLaw. It is probably possible to fix the header by piping through
+     `sox' and passing explicit parameters for specifying the sampling
+     format; you then need to perform a 'null' conversion from SunAudio
+     to SunAudio.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.1,  Next: Q5.3.2,  Prev: Q5.2.4,  Up: Miscellaneous
+
+5.3: Miscellaneous
+==================
+
+Q5.3.1: How do you make XEmacs indent CL if-clauses correctly?
+--------------------------------------------------------------
+
+I'd like XEmacs to indent all the clauses of a Common Lisp `if' the
+same amount instead of indenting the 3rd clause differently from the
+first two.
+
+   One way is to add, to `init.el'/`.emacs':
+
+     (put 'if 'lisp-indent-function nil)
+
+   However, note that the package `cl-indent' that comes with XEmacs
+sets up this kind of indentation by default.  `cl-indent' also knows
+about many other CL-specific forms.  To use `cl-indent', one can do
+this:
+
+     (load "cl-indent")
+     (setq lisp-indent-function (function common-lisp-indent-function))
+
+   One can also customize `cl-indent.el' so it mimics the default `if'
+indentation `then' indented more than the `else'.  Here's how:
+
+     (put 'if 'common-lisp-indent-function '(nil nil &body))
+
+   Also, a new version (1.2) of `cl-indent.el' was posted to
+comp.emacs.xemacs on 12/9/94.  This version includes more documentation
+than previous versions.  This may prove useful if you need to customize
+any indent-functions.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.2,  Next: Q5.3.3,  Prev: Q5.3.1,  Up: Miscellaneous
+
+Q5.3.2: [This question intentionally left blank]
+------------------------------------------------
+
+Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.3,  Next: Q5.3.4,  Prev: Q5.3.2,  Up: Miscellaneous
+
+Q5.3.3: How can I print WYSIWYG a font-locked buffer?
+-----------------------------------------------------
+
+Font-lock looks nice.  How can I print (WYSIWYG) the highlighted
+document?
+
+   The package `ps-print', which is now included with XEmacs, provides
+the ability to do this.  The source code contains complete instructions
+on its use, in
+`$prefix/lib/xemacs/xemacs-packages/lisp/ps-print/ps-print.el', being
+the default location of an installed ps-print package.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.4,  Next: Q5.3.5,  Prev: Q5.3.3,  Up: Miscellaneous
+
+Q5.3.4: Getting `M-x lpr' to work with postscript printer.
+----------------------------------------------------------
+
+My printer is a Postscript printer and `lpr' only works for Postscript
+files, so how do I get `M-x lpr-region' and `M-x lpr-buffer' to work?
+
+   Put something like this in your `init.el'/`.emacs':
+
+     (setq lpr-command "a2ps")
+     (setq lpr-switches '("-p" "-1"))
+
+   If you don't use a2ps to convert ASCII to postscript (why not, it's
+free?), replace with the command you do use.  Note also that some
+versions of a2ps require a `-Pprinter' to ensure spooling.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.5,  Next: Q5.3.6,  Prev: Q5.3.4,  Up: Miscellaneous
+
+Q5.3.5: How do I specify the paths that XEmacs uses for finding files?
+----------------------------------------------------------------------
+
+You can specify what paths to use by using a number of different flags
+when running configure.  See the section MAKE VARIABLES in the top-level
+file INSTALL in the XEmacs distribution for a listing of those flags.
+
+   Most of the time, however, the simplest fix is: *do not* specify
+paths as you might for GNU Emacs.  XEmacs can generally determine the
+necessary paths dynamically at run time.  The only path that generally
+needs to be specified is the root directory to install into.  That can
+be specified by passing the `--prefix' flag to configure.  For a
+description of the XEmacs install tree, please consult the `NEWS' file.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.6,  Next: Q5.3.7,  Prev: Q5.3.5,  Up: Miscellaneous
+
+Q5.3.6: [This question intentionally left blank]
+------------------------------------------------
+
+Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.7,  Next: Q5.3.8,  Prev: Q5.3.6,  Up: Miscellaneous
+
+Q5.3.7: Can I have the end of the buffer delimited in some way?
+---------------------------------------------------------------
+
+Say, with: `[END]'?
+
+   Try this:
+
+     (let ((ext (make-extent (point-min) (point-max))))
+       (set-extent-property ext 'start-closed t)
+       (set-extent-property ext 'end-closed t)
+       (set-extent-property ext 'detachable nil)
+       (set-extent-end-glyph ext (make-glyph [string :data "[END]"])))
+
+   Since this is XEmacs, you can specify an icon to be shown on
+window-system devices.  To do so, change the `make-glyph' call to
+something like this:
+
+     (make-glyph '([xpm :file "~/something.xpm"]
+                   [string :data "[END]"]))
+
+   You can inline the XPM definition yourself by specifying `:data'
+instead of `:file'.  Here is such a full-featured version that works on
+both X and TTY devices:
+
+     (let ((ext (make-extent (point-min) (point-max))))
+       (set-extent-property ext 'start-closed t)
+       (set-extent-property ext 'end-closed t)
+       (set-extent-property ext 'detachable nil)
+       (set-extent-end-glyph ext (make-glyph '([xpm :data "\
+     /* XPM */
+     static char* eye = {
+     \"20 11 7 2\",
+     \"__ c None\"
+     \"_` c #7f7f7f\",
+     \"_a c #fefefe\",
+     \"_b c #7f0000\",
+     \"_c c #fefe00\",
+     \"_d c #fe0000\",
+     \"_e c #bfbfbf\",
+     \"___________`_`_`___b_b_b_b_________`____\",
+     \"_________`_`_`___b_c_c_c_b_b____________\",
+     \"_____`_`_`_e___b_b_c_c_c___b___b_______`\",
+     \"___`_`_e_a___b_b_d___b___b___b___b______\",
+     \"_`_`_e_a_e___b_b_d_b___b___b___b___b____\",
+     \"_`_`_a_e_a___b_b_d___b___b___b___b___b__\",
+     \"_`_`_e_a_e___b_b_d_b___b___b___b___b_b__\",
+     \"___`_`_e_a___b_b_b_d_c___b___b___d_b____\",
+     \"_____`_`_e_e___b_b_b_d_c___b_b_d_b______\",
+     \"_`_____`_`_`_`___b_b_b_d_d_d_d_b________\",
+     \"___`_____`_`_`_`___b_b_b_b_b_b__________\",
+     } ;"]
+                                               [string :data "[END]"]))))
+
+   Note that you might want to make this a function, and put it to a
+hook.  We leave that as an exercise for the reader.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.8,  Next: Q5.3.9,  Prev: Q5.3.7,  Up: Miscellaneous
+
+Q5.3.8: How do I insert today's date into a buffer?
+---------------------------------------------------
+
+Like this:
+
+     (insert (current-time-string))
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.9,  Next: Q5.3.10,  Prev: Q5.3.8,  Up: Miscellaneous
+
+Q5.3.9: Are only certain syntactic character classes available for abbrevs?
+---------------------------------------------------------------------------
+
+Markus Gutschke <gutschk@uni-muenster.de> writes:
+
+     Yes, abbrevs only expands word-syntax strings. While XEmacs does
+     not prevent you from defining (e.g. with `C-x a g' or `C-x a l')
+     abbrevs that contain special characters, it will refuse to expand
+     them. So you need to ensure, that the abbreviation contains
+     letters and digits only. This means that `xd', `d5', and `5d' are
+     valid abbrevs, but `&d', and `x d' are not.
+
+     If this sounds confusing to you, (re-)read the online
+     documentation for abbrevs (`C-h i m XEmacs <RET> m Abbrevs
+     <RET>'), and then come back and read this question/answer again.
+
+   Starting with XEmacs 20.3 this restriction has been lifted.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.10,  Next: Q5.3.11,  Prev: Q5.3.9,  Up: Miscellaneous
+
+Q5.3.10: How can I get those oh-so-neat X-Face lines?
+-----------------------------------------------------
+
+Firstly there is an ftp site which describes X-faces and has the
+associated tools mentioned below, at
+`ftp://ftp.cs.indiana.edu:/pub/faces/'.
+
+   Then the steps are
+
+  1. Create 48x48x1 bitmap with your favorite tool
+
+  2. Convert to "icon" format using one of xbm2ikon, pbmtoicon, etc.,
+     and then compile the face.
+
+  3.      cat file.xbm | xbm2ikon |compface > file.face
+
+  4. Then be sure to quote things that are necessary for emacs strings:
+
+          cat ./file.face | sed 's/\\/\\\\/g'
+          | sed 's/\"/\\\"/g' > ./file.face.quoted
+
+  5. Then set up emacs to include the file as a mail header - there
+     were a couple of suggestions here--either something like:
+
+          (setq  mail-default-headers
+                 "X-Face:  <Ugly looking text string here>")
+
+     Or, alternatively, as:
+
+          (defun mail-insert-x-face ()
+            (save-excursion
+              (goto-char (point-min))
+              (search-forward mail-header-separator)
+              (beginning-of-line)
+              (insert "X-Face:")
+              (insert-file-contents "~/.face")))
+          
+          (add-hook 'mail-setup-hook 'mail-insert-x-face)
+
+   However, 2 things might be wrong:
+
+   Some versions of pbmtoicon produces some header lines that is not
+expected by the version of compface that I grabbed. So I found I had to
+include a `tail +3' in the pipeline like this:
+
+     cat file.xbm | xbm2ikon | tail +3 |compface > file.face
+
+   Some people have also found that if one uses the `(insert-file)'
+method, one should NOT quote the face string using the sed script .
+
+   It might also be helpful to use Stig's <stig@hackvan.com> script
+(included in the compface distribution at XEmacs.org) to do the
+conversion.
+
+   Contributors for this item:
+
+   Paul Emsley, Ricardo Marek, Amir J. Katz, Glen McCort, Heinz Uphoff,
+Peter Arius, Paul Harrison, and Vegard Vesterheim
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.11,  Next: Q5.3.12,  Prev: Q5.3.10,  Up: Miscellaneous
+
+Q5.3.11: How do I add new Info directories?
+-------------------------------------------
+
+You use something like:
+
+     (setq Info-directory-list (cons
+                                (expand-file-name "~/info")
+                                Info-default-directory-list))
+
+   David Masterson <davidm@prism.kla.com> writes:
+
+     Emacs Info and XEmacs Info do many things differently.  If you're
+     trying to support a number of versions of Emacs, here are some
+     notes to remember:
+
+       1. Emacs Info scans `Info-directory-list' from right-to-left
+          while XEmacs Info reads it from left-to-right, so append to
+          the _correct_ end of the list.
+
+       2. Use `Info-default-directory-list' to initialize
+          `Info-directory-list' _if_ it is available at startup, but not
+          all Emacsen define it.
+
+       3. Emacs Info looks for a standard `dir' file in each of the
+          directories scanned from #1 and magically concatenates them
+          together.
+
+       4. XEmacs Info looks for a `localdir' file (which consists of
+          just the menu entries from a `dir' file) in each of the
+          directories scanned from #1 (except the first), does a simple
+          concatenation of them, and magically attaches the resulting
+          list to the end of the menu in the `dir' file in the first
+          directory.
+
+     Another alternative is to convert the documentation to HTML with
+     texi2html and read it from a web browser like Lynx or W3.
+
+\1f
+File: xemacs-faq.info,  Node: Q5.3.12,  Prev: Q5.3.11,  Up: Miscellaneous
+
+Q5.3.12: What do I need to change to make printing work?
+--------------------------------------------------------
+
+For regular printing there are two variables that can be customized.
+
+`lpr-command'
+     This should be set to a command that takes standard input and sends
+     it to a printer.  Something like:
+
+          (setq lpr-command "lp")
+
+`lpr-switches'
+     This should be set to a list that contains whatever the print
+     command requires to do its job.  Something like:
+
+          (setq lpr-switches '("-depson"))
+
+   For postscript printing there are three analogous variables to
+customize.
+
+`ps-lpr-command'
+     This should be set to a command that takes postscript on standard
+     input and directs it to a postscript printer.
+
+`ps-lpr-switches'
+     This should be set to a list of switches required for
+     `ps-lpr-command' to do its job.
+
+`ps-print-color-p'
+     This boolean variable should be set `t' if printing will be done in
+     color, otherwise it should be set to `nil'.
+
+   NOTE: It is an undocumented limitation in XEmacs that postscript
+printing (the `Pretty Print Buffer' menu item) *requires* a window
+system environment.  It cannot be used outside of X11.
+
+\1f
+File: xemacs-faq.info,  Node: MS Windows,  Next: Current Events,  Prev: Miscellaneous,  Up: Top
+
+6 XEmacs on MS Windows
+**********************
+
+This is part 6 of the XEmacs Frequently Asked Questions list, written by
+Hrvoje Niksic and others.  This section is devoted to the MS Windows
+port of XEmacs.
+
+* Menu:
+
+General Info
+* Q6.0.1::      What is the status of the XEmacs port to Windows?
+* Q6.0.2::      What flavors of MS Windows are supported?  The list name implies NT only.
+* Q6.0.3::      Are binaries available?
+* Q6.0.4::      Can I build XEmacs on MS Windows with X support?  Do I need to?
+* Q6.0.5::      I'd like to help out.  What do I do?
+* Q6.0.6::      What are Cygwin and MinGW, and do I need them to run XEmacs?
+* Q6.0.7::      What exactly are all the different ways to build XEmacs under Windows?
+
+Building XEmacs on MS Windows:
+* Q6.1.1::      What compiler/libraries do I need to compile XEmacs?
+* Q6.1.2::      How do I compile the native port?
+* Q6.1.3::      What do I need for Cygwin?
+* Q6.1.4::      How do I compile under Cygwin?
+* Q6.1.5::      How do I compile using MinGW (aka `the -mno-cygwin flag to gcc')?
+* Q6.1.6::      I decided to run with X.  Where do I get an X server?
+* Q6.1.7::      How do I compile with X support?
+
+Customization and User Interface:
+* Q6.2.1::      How does the port cope with differences in the Windows user interface?
+* Q6.2.2::      How do I change fonts in XEmacs on MS Windows?
+* Q6.2.3::      Where do I put my `init.el'/`.emacs' file?
+* Q6.2.4::      How do I get Windows Explorer to associate a file type with XEmacs?
+* Q6.2.5::      Is it possible to print from XEmacs?
+
+Miscellaneous:
+* Q6.3.1::      Does XEmacs rename all the `win32-*' symbols to `w32-*'?
+* Q6.3.2::      What are the differences between the various MS Windows emacsen?
+* Q6.3.3::      XEmacs 21.1 on Windows used to spawn an ugly console window on every startup.  Has that been fixed?
+* Q6.3.4::      What is the porting team doing at the moment?
+
+Troubleshooting:
+* Q6.4.1::      XEmacs won't start on Windows.
+* Q6.4.2::      Why do I get a blank toolbar on Windows 95?
+* Q6.4.3::      XEmacs complains "No such file or directory, diff"
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.1,  Next: Q6.0.2,  Prev: MS Windows,  Up: MS Windows
+
+6.0: General Info
+=================
+
+Q6.0.1: What is the status of the XEmacs port to Windows?
+---------------------------------------------------------
+
+Is XEmacs really ported to MS Windows?  What is the status of the port?
+
+   Beginning with release 21.0, XEmacs has worked under MS Windows.  A
+group of dedicated developers actively maintains and improves the
+Windows-specific portions of the code.  The mailing list at
+<xemacs-nt@xemacs.org> is dedicated to that effort (please use the
+-request address to subscribe). (Despite its name, XEmacs actually
+works on all versions of Windows.)
+
+   As of May 2001, XEmacs on MS Windows is stable and full-featured, and
+has been so for a year or more - in fact, some features, such as
+printing, actually work better on Windows than native Unix.  However,
+the internationalization (Mule) support does not work - although this
+is being actively worked on.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.2,  Next: Q6.0.3,  Prev: Q6.0.1,  Up: MS Windows
+
+Q6.0.2: What flavors of MS Windows are supported?  The list name implies NT only.
+---------------------------------------------------------------------------------
+
+The list name is misleading, as XEmacs supports and has been compiled on
+Windows 95, Windows 98, Windows NT, Windows 2000, Windows ME, Windows
+XP, and all newer versions of Windows.  The MS Windows-specific code is
+based on Microsoft Win32 API, and will not work on MS Windows 3.x or on
+MS-DOS.
+
+   XEmacs also supports the Cygwin and MinGW development and runtime
+environments, where it also uses native Windows code for graphical
+features.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.3,  Next: Q6.0.4,  Prev: Q6.0.2,  Up: MS Windows
+
+Q6.0.3: Are binaries available?
+-------------------------------
+
+Binaries are available at `http://www.xemacs.org/Download/win32/' for
+the native and Cygwin MS Windows versions of 21.4, and the native
+version of 21.1.
+
+   The 21.4 binaries use a modified version of the Cygwin installer.
+Run the provided `setup.exe', and follow the instructions.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.4,  Next: Q6.0.5,  Prev: Q6.0.3,  Up: MS Windows
+
+Q6.0.4: Can I build XEmacs on MS Windows with X support?  Do I need to?
+-----------------------------------------------------------------------
+
+Yes, you can, but no you do not need to.  In fact, we recommend that you
+use a native-GUI version unless you have a specific need for an X
+version.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.5,  Next: Q6.0.6,  Prev: Q6.0.4,  Up: MS Windows
+
+Q6.0.5: I'd like to help out.  What do I do?
+--------------------------------------------
+
+It depends on the knowledge and time you possess.  If you are a
+programmer, try to build XEmacs and see if you can improve it.
+Windows-specific improvements like integration with established Windows
+environments are especially sought after.
+
+   Otherwise, you can still help by downloading the binaries, using
+XEmacs as your everyday editor and reporting bugs you find to the
+mailing list.
+
+   Another area where we need help is the documentation: We need good
+documentation for building XEmacs and for using it.  This FAQ is a
+small step in that direction.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.6,  Next: Q6.0.7,  Prev: Q6.0.5,  Up: MS Windows
+
+Q6.0.6: What are Cygwin and MinGW, and do I need them to run XEmacs?
+--------------------------------------------------------------------
+
+To answer the second part of the question: No, you, you don't need
+Cygwin or MinGW to build or to run XEmacs.  But if you have them and
+want to use them, XEmacs supports these environments.
+
+   (One important reason to support Cygwin is that it lets the MS
+Windows developers test out their code in a Unix environment without
+actually having to have a Unix machine around.  For this reason alone,
+Cygwin support is likely to remain supported for a long time in XEmacs.
+Same goes for the X support under Cygwin, for the same reasons.  MinGW
+support, on the other hand, depends on volunteers to keep it up to date;
+but this is generally not hard.)
+
+   Cygwin is a set of tools providing Unix-like API on top of Win32.
+It makes it easy to port large Unix programs without significant
+changes to their source code.  It is a development environment as well
+as a runtime environment.
+
+   When built with Cygwin, XEmacs supports all display types - TTY, X &
+Win32 GUI, and can be built with support for all three simultaneously.
+If you build with Win32 GUI support then the Cygwin version uses the
+majority of the Windows-specific code, which is mostly related to
+display.  If you want to build with X support you need X libraries (and
+an X server to display XEmacs on); see *Note Q6.1.4::.  TTY and Win32
+GUI require no additional libraries beyond what comes standard with
+Cygwin.
+
+   The advantages of the Cygwin version are that it integrates well with
+the Cygwin environment for existing Cygwin users; uses configure so
+building with different features is very easy; and actively supports X &
+TTY.  Furthermore, the entire Cygwin environment and compiler are free,
+whereas Visual C++ costs money.
+
+   The disadvantage is that it requires the whole Cygwin environment,
+whereas the native port requires only a suitable MS Windows compiler.
+Also, it follows the Unix filesystem and process model very closely
+(some will undoubtedly view this as an advantage).
+
+   See `http://sources.redhat.com/cygwin/' for more information on
+Cygwin.
+
+   MinGW is a collection of header files and import libraries that allow
+one to use GCC under the Cygwin environment to compile and produce
+exactly the same native Win32 programs that you can using Visual C++.
+Programs compiled with MinGW make use of the standard Microsoft runtime
+library `MSVCRT.DLL', present on all Windows systems, and look, feel,
+and act like a standard Visual-C-produced application. (The only
+difference is the compiler.) This means that, unlike a
+standardly-compiled Cygwin application, no extra runtime support (e.g.
+Cygwin's `cygwin1.dll') is required.  This, along with the fact that
+GCC is free (and works in a nice Unix-y way in a nice Unix-y
+environment, for those die-hard Unix hackers out there), is the main
+advantage of MinGW.  It is also potentially faster than Cygwin because
+it has less overhead when calling Windows, but you lose the POSIX
+emulation layer, which makes Unix programs harder to port. (But this is
+irrelevant for XEmacs since it's already ported to Win32.)
+
+   See `http://www.mingw.org/' for more information on MinGW.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.0.7,  Next: Q6.1.1,  Prev: Q6.0.6,  Up: MS Windows
+
+Q6.0.7: What exactly are all the different ways to build XEmacs under Windows?
+------------------------------------------------------------------------------
+
+XEmacs can be built in several ways in the MS Windows environment.
+
+   The standard way is what we call the "native" port.  It uses the
+Win32 API and has no connection with X whatsoever - it does not require
+X libraries to build, nor does it require an X server to run.  The
+native port is the most reliable version and provides the best graphical
+support.  Almost all development is geared towards this version, and
+there is little reason not to use it.
+
+   The second way to build is the Cygwin port.  It takes advantage of
+Cygnus emulation library under Win32.  *Note Q6.0.6::, for more
+information.
+
+   A third way is the MinGW port.  It uses the Cygwin environment to
+build but does not require it at runtime.  *Note Q6.0.6::, for more
+information.
+
+   Finally, you might also be able to build the non-Cygwin, non-MinGW
+"X" port.  This was actually the first version of XEmacs that ran under
+MS Windows, and although the code is still in XEmacs, it's essentially
+orphaned and it's unlikely it will compile without a lot of work.  If
+you want an MS Windows versin of XEmacs that supports X, use the Cygwin
+version. (The X support there is actively maintained, so that Windows
+developers can test the X support in XEmacs.)
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.1,  Next: Q6.1.2,  Prev: Q6.0.7,  Up: MS Windows
+
+6.1: Building XEmacs on MS Windows
+==================================
+
+Q6.1.1: What compiler/libraries do I need to compile XEmacs?
+------------------------------------------------------------
+
+You need Visual C++ 4.2, 5.0, or 6.0 for the native version. (We have
+some beta testers currently trying to compile with VC.NET, aka version
+7.0, but we can't yet report complete success.) For the Cygwin and MinGW
+versions, you need the Cygwin environment, which comes with GCC, the
+compiler used for those versions.  *Note Q6.0.6::, for more information
+on Cygwin and MinGW.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.2,  Next: Q6.1.3,  Prev: Q6.1.1,  Up: MS Windows
+
+Q6.1.2: How do I compile the native port?
+-----------------------------------------
+
+Please read the file `nt/README' in the XEmacs distribution, which
+contains the full description.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.3,  Next: Q6.1.4,  Prev: Q6.1.2,  Up: MS Windows
+
+Q6.1.3: What do I need for Cygwin?
+----------------------------------
+
+You can find the Cygwin tools and compiler at:
+
+   `http://sources.redhat.com/cygwin/'
+
+   Click on the `Install now!' link, which will download a file
+`setup.exe', which you can use to download everything else. (You will
+need to pick a mirror site; `mirrors.rcn.net' is probably the best.)
+You should go ahead and install everything - you'll get various
+ancillary libraries that XEmacs needs or likes, e.g. XPM, PNG, JPEG,
+TIFF, etc.
+
+   If you want to compile under X, you will also need the X libraries;
+see *Note Q6.1.6::.
+
+   If you want to compile without X, you will need the `xpm-nox'
+library, which must be specifically selected in the Cygwin netinstaller;
+it is not selected by default.  The package has had various names.
+Currently it is called `cygXpm-noX4.dll'.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.4,  Next: Q6.1.5,  Prev: Q6.1.3,  Up: MS Windows
+
+Q6.1.4: How do I compile under Cygwin?
+--------------------------------------
+
+Similar as on Unix; use the usual `configure' and `make' process.  Some
+problems to watch out for:
+
+   * make sure HOME is set. This controls where you `init.el'/`.emacs'
+     file comes from;
+
+   * CYGWIN needs to be set to tty for process support to work, e.g.
+     CYGWIN=tty;
+
+   * picking up some other grep or other UNIX-like tools can kill
+     configure;
+
+   * static heap too small, adjust `src/sheap-adjust.h' to a more
+     positive number;
+
+   * (Unconfirmed) The Cygwin version doesn't understand
+     `//machine/path' type paths so you will need to manually mount a
+     directory of this form under a unix style directory for a build to
+     work on the directory;
+
+   * If you're building *WITHOUT* X11, don't forget to change symlinks
+     `/usr/lib/libXpm.a' and `/usr/lib/libXpm.dll.a' to point to the
+     non-X versions of these libraries.  By default they point to the X
+     versions.  So:
+
+          /usr/lib/libXpm.a     -> /usr/lib/libXpm-noX.a
+          /usr/lib/libXpm.dll.a -> /usr/lib/libXpm-noX.dll.a
+
+     (This advice may now be obsolete because of the availability of the
+     cygXpm-noX4.dll package from Cygwin.  Send confirmation to
+     <faq@xemacs.org>.)
+
+   * Other problems are listed in the `PROBLEMS' file, in the top-level
+     directory of the XEmacs sources.
+
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.5,  Next: Q6.1.6,  Prev: Q6.1.4,  Up: MS Windows
+
+Q6.1.5: How do I compile using MinGW (aka `the -mno-cygwin flag to gcc')?
+-------------------------------------------------------------------------
+
+Similar to the method for Unix.  Things to remember:
+
+   * Specify the target host on the command line for `./configure', e.g.
+     `./configure i586-pc-mingw32'.
+
+   * Be sure that your build directory is mounted such that it has the
+     same path either as a cygwin path (`/build/xemacs') or as a Windows
+     path (`c:\build\xemacs').
+
+   * Build `gcc -mno-cygwin' versions of the extra libs, i.e. `libpng',
+     `compface', etc.
+
+   * Specify the target location of the extra libs on the command line
+     to `configure', e.g.  `./configure --site-prefixes=/build/libs
+     i586-pc-mingw32'.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.6,  Next: Q6.1.7,  Prev: Q6.1.5,  Up: MS Windows
+
+Q6.1.6: I decided to run with X.  Where do I get an X server?
+-------------------------------------------------------------
+
+As of May 2001, we are recommending that you use the port of XFree86 to
+Cygwin.  This has recently stabilized, and will undoubtedly soon make
+most other MS Windows X servers obsolete.  It is what the Windows
+developers use to test the MS Windows X support.
+
+   To install, go to `http://xfree86.cygwin.com/'.  There is a detailed
+description on that site of exactly how to install it.  This
+installation also provides the libraries, include files, and other stuff
+needed for development; a large collection of internationalized fonts;
+the standard X utilities (xterm, twm, etc.) - in a word, the works.
+
+   NOTE: As of late May 2001, there is a bug in the file
+`startxwin.bat', used to start X Windows.  It passes the option
+`-engine -4' to the X server, which is bogus - you need to edit the
+file and change it to `-engine 4'.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.1.7,  Next: Q6.2.1,  Prev: Q6.1.6,  Up: MS Windows
+
+Q6.1.7: How do I compile with X support?
+----------------------------------------
+
+To compile under Cygwin, all you need to do is install XFree86 (*note
+Q6.1.6::).  Once installed, `configure' should automatically find the X
+libraries and compile with X support.
+
+   As noted above, the non-Cygwin X support is basically orphaned, and
+probably won't work.  But if it want to try, it's described in
+`nt/README' in some detail.  Basically, you need to get X11 libraries
+from ftp.x.org, and compile them.  If the precompiled versions are
+available somewhere, we don't know of it.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.2.1,  Next: Q6.2.2,  Prev: Q6.1.7,  Up: MS Windows
+
+6.2: Customization and User Interface
+=====================================
+
+Q6.2.1: How does the port cope with differences in the Windows user interface?
+------------------------------------------------------------------------------
+
+The XEmacs (and Emacs in general) user interface is pretty different
+from what is expected of a typical MS Windows program.  How does the MS
+Windows port cope with it?
+
+   As a general rule, we follow native MS Windows conventions as much as
+possible.  21.4 is a fairly complete Windows application, supporting
+native printing, system file dialog boxes, tool tips, etc.  In cases
+where there's a clear UI conflict, we currently use normal Unix XEmacs
+behavior by default, but make sure the MS Windows "look and feel" (mark
+via shift-arrow, self-inserting deletes region, Alt selects menu items,
+etc.) is easily configurable (respectively: using the variable
+`shifted-motion-keys-select-region' in 21.4 and above [it's in fact the
+default in these versions], or the `pc-select' package; using the
+`pending-del' package; and setting the variable
+`menu-accelerator-enabled' to `menu-force' in 21.4 and above).  In
+fact, if you use the sample `init.el' file as your init file, you will
+get all these behaviors automatically turned on.
+
+   In future versions, some of these features might be turned on by
+default in the MS Windows environment.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.2.2,  Next: Q6.2.3,  Prev: Q6.2.1,  Up: MS Windows
+
+Q6.2.2: How do I change fonts in XEmacs on MS Windows?
+------------------------------------------------------
+
+In 21.4 and above, you can use the "Options" menu to change the font.
+You can also do it in your init file, e.g. like this:
+
+         (set-face-font 'default "Lucida Console:Regular:10")
+         (set-face-font 'modeline "MS Sans Serif:Regular:10")
+
+\1f
+File: xemacs-faq.info,  Node: Q6.2.3,  Next: Q6.2.4,  Prev: Q6.2.2,  Up: MS Windows
+
+Q6.2.3: Where do I put my `init.el'/`.emacs' file?
+--------------------------------------------------
+
+`init.el' is the name of the init file starting with 21.4, and is
+located in the subdirectory `.xemacs/' of your home directory.  In
+prior versions, the init file is called `.emacs' and is located in your
+home directory.  Your home directory under Windows is determined by the
+`HOME' environment variable.  If this is not set, it defaults to `C:\'.
+
+   To set this variable, modify `AUTOEXEC.BAT' under Windows 95/98, or
+select `Control Panel->System->Advanced->Environment Variables...'
+under Windows NT/2000.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.2.4,  Next: Q6.2.5,  Prev: Q6.2.3,  Up: MS Windows
+
+Q6.2.4: How do I get Windows Explorer to associate a file type with XEmacs?
+---------------------------------------------------------------------------
+
+Associating a new file type with XEmacs.
+........................................
+
+In Explorer select `View/Options/File Types', press `[New Type...]' and
+fill in the dialog box, e.g.:
+
+             Description of type:    Emacs Lisp source
+             Associated extension:   el
+             Content Type (MIME):    text/plain
+
+   then press `[New...]' and fill in the `Action' dialog box as follows:
+
+             Action:
+             Open
+     
+             Application used to perform action:
+             D:\Full\path\for\xemacs.exe "%1"
+     
+             [x] Use DDE
+     
+             DDE Message:
+             open("%1")
+     
+             Application:
+             <leave blank>
+     
+             DDE Application Not Running:
+             <leave blank>
+     
+             Topic:
+             <leave blank>
+
+Associating an existing file type with XEmacs.
+..............................................
+
+In Explorer select `View/Options/File Types'.  Click on the file type
+in the list and press `[Edit...]'.  If the file type already has an
+`Open' action, double click on it and fill in the `Action' dialog box
+as described above; otherwise create a new action.
+
+   If the file type has more than one action listed, you probably want
+to make the `Open' action that you just edited the default by clicking
+on it and pressing `Set Default'.
+
+   Note for Windows 2000 users: Under Windows 2000, get to `File Types'
+using `Control Panel->Folder Options->File Types'.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.2.5,  Next: Q6.3.1,  Prev: Q6.2.4,  Up: MS Windows
+
+Q6.2.5: Is it possible to print from XEmacs?
+--------------------------------------------
+
+As of 21.4, printing works on Windows, using simply `File->Print', and
+can be configured with `File->Page Setup'.
+
+   Prior to 21.4, there is no built-in support, but there are some
+clever hacks out there.  If you know how, please let us know and we'll
+put it here.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.3.1,  Next: Q6.3.2,  Prev: Q6.2.5,  Up: MS Windows
+
+6.3: Miscellaneous
+==================
+
+Q6.3.1: Does XEmacs rename all the `win32-*' symbols to `w32-*'?
+----------------------------------------------------------------
+
+In his flavor of Emacs 20, Richard Stallman has renamed all the
+`win32-*' symbols to `w32-*'.  Does XEmacs do the same?
+
+   We consider such a move counter-productive, thus we do not use the
+`w32' prefix. (His rather questionable justification was that he did
+not consider Windows to be a "winning" platform.) However, the name
+`Win32' is not particularly descriptive outside the Windows world, and
+using just `windows-' would be too generic.  So we chose a compromise,
+the prefix `mswindows-' for Windows-related variables and functions.
+
+   Thus all the XEmacs variables and functions directly related to
+either the Windows GUI or OS are prefixed `mswindows-' (except for a
+couple of debugging variables, prefixed `debug-mswindows-').  From an
+architectural perspective, however, we believe that this is mostly a
+non-issue because there should be a very small number of
+window-systems-specific variables anyway.  Whenever possible, we try to
+provide generic interfaces that apply to all window systems.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.3.2,  Next: Q6.3.3,  Prev: Q6.3.1,  Up: MS Windows
+
+Q6.3.2: What are the differences between the various MS Windows emacsen?
+------------------------------------------------------------------------
+
+XEmacs, Win-Emacs, DOS Emacs, NT Emacs, this is all very confusing.
+Could you briefly explain the differences between them?
+
+   Here is a recount of various Emacs versions running on MS Windows:
+
+   * XEmacs
+
+        - Beginning with XEmacs 19.12, XEmacs' architecture was
+          redesigned in such a way to allow clean support of multiple
+          window systems.  At this time the TTY support was added,
+          making X and TTY the first two "window systems" supported by
+          XEmacs.  The 19.12 design is the basis for the current native
+          MS Windows code.
+
+        - Some time during 1997, David Hobley (soon joined by Marc
+          Paquette) imported some of the NT-specific portions of GNU
+          Emacs, making XEmacs with X support compile under Windows NT,
+          and creating the "X" port.
+
+        - Several months later, Jonathan Harris sent out initial
+          patches to use the Win32 API, thus creating the native port.
+          Since then, various people have contributed, including Kirill
+          M. Katsnelson (contributed support for menubars, subprocesses
+          and network, as well as loads of other code), Andy Piper
+          (ported XEmacs to Cygwin environment, contributed Windows
+          unexec, Windows-specific glyphs and toolbars code, and more),
+          Ben Wing (loads of improvements; primary MS Windows developer
+          since 2000), Jeff Sparkes (contributed scrollbars support)
+          and many others.
+
+   * NT Emacs
+
+        - NT Emacs is a version of GNU Emacs modified to compile and
+          run under MS Windows 95 and NT using the native Win32 API.
+          As such, it is close in spirit to the XEmacs "native" port.
+
+        - NT Emacs has been written by Geoff Voelker, and more
+          information can be found at
+          `http://www.gnu.org/software/emacs/windows/ntemacs.html'.
+
+   * Win-Emacs
+
+        - Win-Emacs was a port of Lucid Emacs 19.6 to MS Windows using X
+          compatibility libraries.  Win-Emacs was written by Ben Wing.
+          The MS Windows code never made it back to Lucid Emacs, and
+          its creator (Pearl Software) has long since gone out of
+          business.
+
+   * GNU Emacs for DOS
+
+        - GNU Emacs features support for MS-DOS and DJGPP (D.J.
+          Delorie's DOS port of GCC).  Such an Emacs is heavily
+          underfeatured, because it does not support long file names,
+          lacks proper subprocesses support, and is far too big
+          compared with typical DOS editors.
+
+   * GNU Emacs compiled with Win32
+
+        - Starting with version 19.30, it has been possible to compile
+          GNU Emacs under MS Windows using the DJGPP compiler and X
+          libraries.  The result is very similar to GNU Emacs compiled
+          under MS DOS, only it works somewhat better because it runs
+          in 32-bit mode, makes use of all the system memory, supports
+          long file names, etc.
+
+
+\1f
+File: xemacs-faq.info,  Node: Q6.3.3,  Next: Q6.3.4,  Prev: Q6.3.2,  Up: MS Windows
+
+Q6.3.3: XEmacs 21.1 on Windows used to spawn an ugly console window on every startup.  Has that been fixed?
+-----------------------------------------------------------------------------------------------------------
+
+Yes.
+
+   The console was there because `temacs' (and in turn, `xemacs') was a
+console application, and Windows typically creates a new console for a
+console process unless the creating process requests that one isn't
+created.  This used to be fixed with `runemacs', a small Windows
+application that existed merely to start `xemacs', stating that it
+didn't want a console.
+
+   XEmacs 21.4 fixes this cleanly by the virtue of being a true "GUI"
+application.  The explanation of what that means is included for
+educational value.
+
+   When building an application to be run in a Win32 environment, you
+must state which sub-system it is to run in.  Valid subsystems include
+"console" and "gui".  The subsystem you use affects the run time
+libraries linked into your application, the start up function that is
+run before control is handed over to your application, the entry point
+to your program, and how Windows normally invokes your program. (Console
+programs automatically get a console created for them at startup if
+their stdin/stdout don't point anywhere useful, which is the case when
+run from the GUI.  This is a stupid design, of course - instead, the
+console should get created only when the first I/O actually occurs!
+GUI programs have an equally stupid design: When called from
+`CMD.EXE'/`COMMAND.COM', their stdin/stdout will be set to point
+nowhere useful, even though the command shell has its own stdin/stdout.
+It's as if someone who had learned a bit about stdio but had no actual
+knowledge of interprocess communication designed the scheme;
+unfortunately, the whole process-communication aspect of the Win32 API
+is equally badly designed.) For example, the entry point for a console
+app is "main" (which is what you'd expect for a C/C++ program), but the
+entry point for a "gui" app is "WinMain".  This confuses and annoys a
+lot of programmers who've grown up on Unix systems, where the kernel
+doesn't really care whether your application is a gui program or not.
+
+   For reasons not altogether clear, and are lost in the mists of time
+and tradition, XEmacs on Win32 started out as a console application, and
+therefore a console was automatically created for it. (It may have been
+made a console application partly because a console is needed in some
+circumstances, especially under Win95, to interrupt, terminate, or send
+signals to a child process, and because of the bogosity mentioned above
+with GUI programs and the standard command shell.  Currently, XEmacs
+just creates and immediately hides a console when necessary, and works
+around the "no useful stdio" problem by creating its own console window
+as necessary to display messages in.)
+
+\1f
+File: xemacs-faq.info,  Node: Q6.3.4,  Next: Q6.4.1,  Prev: Q6.3.3,  Up: MS Windows
+
+Q6.3.4: What is the porting team doing at the moment?
+-----------------------------------------------------
+
+(as of June 2001)
+
+   The porting team is continuing work on the MS Windows-specific code.
+Major projects are the development of Mule (internationalization)
+support for Windows and the improvement of the widget support (better
+support for dialog boxes, buttons, edit fields, and similar UI
+elements).
+
+\1f
+File: xemacs-faq.info,  Node: Q6.4.1,  Next: Q6.4.2,  Prev: Q6.3.4,  Up: MS Windows
+
+6.3: Troubleshooting
+====================
+
+Q6.4.1 XEmacs won't start on Windows.
+-------------------------------------
+
+XEmacs relies on a process called "dumping" to generate a working
+executable. Under MS-Windows this process effectively fixes the memory
+addresses of information in the executable. When XEmacs starts up it
+tries to reserve these memory addresses so that the dumping process can
+be reversed - putting the information back at the correct addresses.
+Unfortunately some .DLLs (for instance the soundblaster driver) occupy
+memory addresses that can conflict with those needed by the dumped
+XEmacs executable. In this instance XEmacs will fail to start without
+any explanation. Note that this is extremely machine specific.
+
+   21.1.10 includes a fix for this that makes more intelligent guesses
+about which memory addresses will be free, and this should cure the
+problem for most people.  21.4 implements "portable dumping", which
+eliminates the problem altogether.  We recommend you use the 21.4
+binaries, but you can use the 21.1 binaries if you are very paranoid
+about stability.  *Note Q6.0.3::.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.4.2,  Next: Q6.4.3,  Prev: Q6.4.1,  Up: MS Windows
+
+Q6.4.2 Why do I get a blank toolbar on Windows 95?
+--------------------------------------------------
+
+You need at least version 4.71 of the system file `comctl32.dll'.  The
+updated version is supplied with Internet Explorer 4 and later but if
+you are avoiding IE you can also download it from the Microsoft web
+site.  Go into support and search for `comctl32.dll'.  The download is
+a self-installing executable.
+
+\1f
+File: xemacs-faq.info,  Node: Q6.4.3,  Prev: Q6.4.2,  Up: MS Windows
+
+Q6.4.3 XEmacs complains "No such file or directory, diff"
+---------------------------------------------------------
+
+or "ispell" or other commands that seem related to whatever you just
+tried to do (M-x ediff or M-$, for example).
+
+   There are a large number of common (in the sense that "everyone has
+these, they really do") Unix utilities that are not provided with
+XEmacs.  The GNU Project's implementations are available for Windows in
+the the Cygwin distribution (`http://www.cygwin.com/'), which also
+provides a complete Unix emulation environment (and thus makes ports of
+Unix utilities nearly trivial).  Another implementation is that from
+MinGW (`http://www.mingw.org/msys.shtml').  If you know of others,
+please let us know!
+
+\1f
+File: xemacs-faq.info,  Node: Current Events,  Next: Legacy Versions,  Prev: MS Windows,  Up: Top
+
+7 What the Future Holds
+***********************
+
+This is part 7 of the XEmacs Frequently Asked Questions list.  This
+section will change frequently, and (in theory) should contain any
+interesting items that have transpired recently. (But in practice it's
+not getting updated like this.)
+
+   This section also contains descriptions of the new features in all
+the recent releases of XEmacs.  For the most part, the information
+below is a synopsis of the more complete information that can be found
+in the file `NEWS' in the `etc' directory of the XEmacs distribution.
+You can view this file in XEmacs using `C-h n' or the `Help' menu.
+
+   Information on older versions of XEmacs can be find in `ONEWS' in
+the same directory, or `OONEWS' for really old versions.
+
+* Menu:
+
+* Q7.0.1::      What new features will be in XEmacs soon?
+* Q7.0.2::      What's new in XEmacs 21.4?
+* Q7.0.3::      What's new in XEmacs 21.1?
+* Q7.0.4::      What's new in XEmacs 20.4?
+* Q7.0.5::      What's new in XEmacs 20.3?
+* Q7.0.6::      What's new in XEmacs 20.2?
+
+\1f
+File: xemacs-faq.info,  Node: Q7.0.1,  Next: Q7.0.2,  Prev: Current Events,  Up: Current Events
+
+7.0: Changes
+============
+
+Q7.0.1: What new features will be in XEmacs soon?
+-------------------------------------------------
+
+Not yet written.
+
+\1f
+File: xemacs-faq.info,  Node: Q7.0.2,  Next: Q7.0.3,  Prev: Q7.0.1,  Up: Current Events
+
+Q7.0.2: What's new in XEmacs 21.4?
+----------------------------------
+
+21.4 was the "stable" version of the 21.2 series, which was considered
+"experimental" throughout its life; thus there were no "official"
+releases at all.  In essence, XEmacs is now following the "alternating"
+scheme of Linux, where at any point there are at least two different
+development branches, one "stable" and one "experimental".  Periodic
+releases happen in both branches, but those in the experimental branch
+are not tested as well, and there's no guarantee they will work at all.
+The experiemental branch is open to any and all code that's acceptable
+to the developers; the stable branch, however, is in general limited
+only to bug fixes, and all contributions are carefully reviewed to make
+sure they will increase and not decrease stability.
+
+   21.3 never existed at all; it was decided to follow the Linux scheme
+exactly, where odd-numbered series are experimental and even-numbered
+ones stable.
+
+   The following lists summarizes the essential changes made in this
+version.  For a fuller list, see the `NEWS' in the `etc' directory of
+the XEmacs distribution, or use `C-h n' or the `Help' menu to view this
+file inside of XEmacs.
+
+User-visible changes in XEmacs 21.4
+...................................
+
+   * The delete key now deletes forward by default.
+
+   * Shifted motion keys now select text by default.
+
+   * You can now build XEmacs with support for GTK+ widget set.
+
+   * ~/.xemacs/init.el is now the preferred location for the init file.
+     (XEmacs now supports a `~/.xemacs/init.el' startup file. Custom
+     file will move to ~/.xemacs/custom.el.)
+
+   * Much-improved sample init.el, showing how to use many useful
+     features.
+
+   * XEmacs support for menu accelerators has been much improved.
+
+   * Default menubar improvements. (Default menubar has many new
+     commands and better organization.  The font-menu is now available
+     under MS Windows.)
+
+   * Dialog box improvements, including a real file dialog box. (XEmacs
+     now has a proper file dialog box under MS Windows (and GTK)!  The
+     old clunky file dialog box is improved.  Keyboard traversal now
+     works correctly in MS Windows dialog boxes.  There is a Search
+     dialog box available from Edit->Find...)
+
+   * New buffer tabs.
+
+   * There is a new MS Windows installer, netinstall, ported from
+     Cygwin.
+
+   * The subprocess quote-handling mechanism under Windows is much
+     improved.
+
+   * Printing support now available under MS Windows.
+
+   * Selection improvements. (Kill and yank now interact with the
+     clipboard under Windows.  MS Windows support for selection is now
+     much more robust.  Motif selection support is now more correct
+     (but slower).)
+
+   * Mail spool locking now works correctly.
+
+   * International support changes. (The default coding-priority-list
+     is now safer.  International keysyms are now supported under X.
+     MS Windows 1251 code page now supported.  Czech, Thai,
+     Cyrillic-KOI8, Vietnamese, Ethiopic now supported.  Proper support
+     for words in Latin 3 and Latin 4.)
+
+   * Help buffers contain hyperlinks, and other changes.
+
+   * The modeline's text is now scrollable.
+
+   * The mouse wheel under MS Windows now functions correctly.
+
+   * Interactive searching and matching case improvements. (Incremental
+     search will now highlight all visible matches.  Interactive
+     searches always respect uppercase characters.)
+
+   * Rectangle functions rewritten to avoid inserting extra spaces.
+
+   * New command `kill-entire-line' that always kills the entire line.
+
+   * Default values correctly stored in minibuffer histories.
+
+   * You can now create "indirect buffers", like in GNU Emacs.
+
+   * Pixel-based scrolling has been implemented.
+
+   * Operation progress can be displayed using graphical widgets.
+
+   * User names following a tilde can now be completed at file name
+     prompts.
+
+   * XEmacs can now play sound using Enlightenment Sound Daemon (ESD).
+
+   * X-Face support is now available under MS Windows.
+
+   * The PostgreSQL Relational Database Management System is now
+     supported.
+
+   * Indentation no longer indents comments that begin at column zero.
+
+   * Face and variable settings can have comments in Customize.
+
+   * New locations for early package hierarchies.
+
+   * The `auto-save' library has been greatly improved.
+
+   * New variable `mswindows-alt-by-itself-activates-menu'.
+
+   * Other init-file-related changes. (Init file in your home directory
+     may be called `.emacs.el'.  New command-line switches
+     -user-init-file and -user-init-directory.)
+
+   * Etags changes.  See `NEWS' for full details.
+
+Lisp and internal changes in XEmacs 21.4
+........................................
+
+Not yet written.
+
+\1f
+File: xemacs-faq.info,  Node: Q7.0.3,  Next: Q7.0.4,  Prev: Q7.0.2,  Up: Current Events
+
+Q7.0.3: What's new in XEmacs 21.1?
+----------------------------------
+
+21.1 was the "stable" version of "experimental" 21.0 series.  *Note
+Q7.0.2::.
+
+   The following lists summarizes the essential changes made in this
+version.  For a fuller list, see the `NEWS' in the `etc' directory of
+the XEmacs distribution, or use `C-h n' or the `Help' menu to view this
+file inside of XEmacs.
+
+User-visible changes in XEmacs 21.1
+...................................
+
+   * XEmacs is now supported under Microsoft Windows 95/98 and Windows
+     NT operating systems.  To discuss Windows-specific issues,
+     subscribe to the mailing list at <xemacs-nt-request@xemacs.org>.
+
+   * XEmacs has been unbundled into constituent installable packages.
+
+   * *Other notable changes*: The `Options' menu has been ported to
+     Custom; XEmacs now is able to choose X visuals and use private
+     colormaps; You can drag the vertical divider of "horizontally"
+     (side-by-side) split windows.
+
+   * *Building changes*: XEmacs can be built with support for 31-bit
+     Lisp integers and 32-bit pointers (previously, it was 28-bit
+     integers and pointers); XEmacs can be built with LDAP support;
+     `dir' files can be removed in the Info subsystem, and will be
+     regenerated on-the-fly.
+
+   * *New packages*: `imenu', `popper', `gdb-highlight'
+
+   * *Package changes*: Many changes to `cc-mode', `gnus', `gnuclient'.
+     See `NEWS' for full details.
+
+   * *New commands, variables and functions*: `center-to-window-line'
+     (like `recenter' but doesn't force a redisplay); variable
+     `user-full-name' (customize what your full name looks like in
+     mail); `M-x customize-changed-options' (customize options whose
+     default values changes because you upgraded your XEmacs); `M-x
+     add-log-convert' (converts an old-style ChangeLog buffer to
+     new-style); `M-x zap-up-to-char' (like `zap-to-char' but doesn't
+     delete the char searched for); commands to store, retrieve and
+     increment numbers in registers, useful for macros.
+
+   * *Changes to commands, variables, and functions*: `M-x
+     query-replace' and friends operate only on the region when it's
+     active; `echo-keystrokes' can now be a floating-point number; `M-.'
+     searches exact tag matches before inexact ones; function
+     `user-full-name' with no arguments returns the var
+     `user-full-name'; a prefix arg to `M-:' and `C-h c' inserts the
+     result in the current buffer.
+
+   * *Other changes*: Under X, new application class `XEmacs';
+     byte-compilation of user-specs now works.
+
+   * *XEmacs/Mule (internationalization) changes*: Mule support now
+     works on TTY's; Egg/SJ3 input method now officially supported
+     (Quail and Egg/Skk already available through LEIM since 20.3);
+     localized Japanese menubars if XEmacs is built with the right
+     support.
+
+
+Lisp and internal changes in XEmacs 21.1
+........................................
+
+   * *Specifier changes*: The window locale now has a higher precedence
+     than the buffer locale when instantiating; new macro
+     `let-specifier'; new specifiers `vertical-scrollbar-visible-p',
+     horizontal-scrollbar-visible-p', `scrollbar-on-left-p',
+     `scrollbar-on-top-p', `vertical-divider-always-visible-p',
+     `vertical-divider-shadow-thickness',
+     `vertical-divider-line-width', `vertical-divider-spacing';
+     specifiers and symbols whose value is a specifier allowed as
+     modeline specifications.
+
+   * *Frame focus changes*: `focus-follows-mouse' works like FSF,
+     prevents any attempt to permanently change the selected frame; new
+     function `focus-frame' sets the window system focus a frame; new
+     special forms `save-selected-frame' and `with-selected-frame'.
+
+   * *Window function changes*: `select-window' now has optional
+     argument NORECORD to inhibit recording a buffer change;
+     `vertical-motion' now correctly handles optional WINDOW argument
+     and has new optional argument PIXELS, to have the returned values
+     be in pixels; new function `vertical-motion-pixels'; new functions
+     `window-text-area-pixel-{width,height,edges}'; new functions
+     `shrink-window-pixels' and `enlarge-window-pixels'; new function
+     `window-displayed-text-pixel-height'.
+
+   * *Other function changes*: Arithmetic comparison functions `<',
+     `>', `=', `/=' now accept a variable number of arguments;
+     hashtables now have a consistent read/print syntax; keyword
+     symbols cannot be set to a value other than themselves; `concat' no
+     longer accepts integer arguments; new function `string', like
+     `list', `vector', etc.; new function `temp-directory'
+     (OS-independent way to get a temp directory); `load-average' has
+     optional argument USE-FLOATS; `make-event' implemented completely;
+     new function `function-interactive' (returns a function's
+     interactive spec); new functions `lmessage', `lwarn' (printf-like
+     versions of `display-wessage', `display-warning'); new keyword
+     `:version' to `defcustom'.
+
+   * *Performance*: when the new GNU Malloc aka Doug Lea Malloc is
+     available, it will be used (better performance on libc6 Linux
+     systems); tracking line-numbers in modeline is now efficient;
+     profiling records a call-count of all called functions,
+     retrievable through `profile-call-count-results'.
+
+   * *Startup and path searching*: code to assemble paths at startup
+     rewritten for new package system; new function `split-path' (splits
+     by `path-separator'); `Info-default-directory-list' obsolete, use
+     `Info-directory-list' instead; site-lisp is deprecated and no
+     longer on the load-path by default.
+
+
+\1f
+File: xemacs-faq.info,  Node: Q7.0.4,  Next: Q7.0.5,  Prev: Q7.0.3,  Up: Current Events
+
+Q7.0.4: What's new in XEmacs 20.4?
+----------------------------------
+
+XEmacs 20.4 is a bugfix release with no user-visible changes.
+
+\1f
+File: xemacs-faq.info,  Node: Q7.0.5,  Next: Q7.0.6,  Prev: Q7.0.4,  Up: Current Events
+
+Q7.0.5: What's new in XEmacs 20.3?
+----------------------------------
+
+XEmacs 20.3 was released in November 1997. It contains many bugfixes,
+and a number of new features, including Autoconf 2 based configuration,
+additional support for Mule (Multi-language extensions to Emacs), many
+more customizations, multiple frames on TTY-s, support for multiple info
+directories, an enhanced gnuclient, improvements to regexp matching,
+increased MIME support, and many, many synches with GNU Emacs 20.
+
+   The XEmacs/Mule support has been only seriously tested in a Japanese
+locale, and no doubt many problems still remain.  The support for
+ISO-Latin-1 and Japanese is fairly strong.  MULE support comes at a
+price--about a 30% slowdown from 19.16.  We're making progress on
+improving performance and XEmacs 20.3 compiled without Mule (which is
+the default) is definitely faster than XEmacs 19.16.
+
+   XEmacs 20.3 is the first non-beta v20 release, and will be the basis
+for all further development.
+
+\1f
+File: xemacs-faq.info,  Node: Q7.0.6,  Prev: Q7.0.5,  Up: Current Events
+
+Q7.0.6: What's new in XEmacs 20.2?
+----------------------------------
+
+The biggest changes in 20.2 include integration of EFS (the next
+generation of ange-ftp) and AUC Tex (the Emacs subsystem that includes a
+major mode for editing Tex and LaTeX, and a lot of other stuff).  Many
+bugs from 20.0 have been fixed for this release.  20.2 also contains a
+new system for customizing XEmacs options, invoked via `M-x customize'.
+
+   XEmacs 20.2 is the development release (20.0 was beta), and is no
+longer considered unstable.
+
+   For older news, see the file `ONEWS' in the `etc' directory of the
+XEmacs distribution.
+
+\1f
+File: xemacs-faq.info,  Node: Legacy Versions,  Prev: Current Events,  Up: Top
+
+8 New information about old XEmacsen
+************************************
+
+This is part 8 of the XEmacs Frequently Asked Questions list.  It will
+occasionally be updated to reflect new information about versions which
+are no longer being revised by the XEmacs Project.  The primary purpose
+is advice on compatibility of older XEmacsen with new packages and
+updated versions of packages, but bug fixes (which will not be applied
+to released XEmacsen, but users can apply themselves) are also accepted.
+
+* Menu:
+
+* Q8.0.1::      Gnus 5.10 won't display smileys in XEmacs 21.1.
+
+\1f
+File: xemacs-faq.info,  Node: Q8.0.1,  Up: Legacy Versions
+
+Q8.0.1: Gnus 5.10 won't display smileys in XEmacs 21.1.
+-------------------------------------------------------
+
+Eric Eide <eeide@cs.utah.edu> wrote:
+
+     Previously I wrote:
+
+     Eric> Summary: with Gnus 5.10.1 in XEmacs 21.1.14, I don't see
+     Eric> any smileys :-(.
+
+     After a bit of sleuthing, I discovered the essence of the problem.
+     For me, the form:
+
+               (with-temp-buffer
+                 (insert-file-contents "foo.xpm")
+                 (buffer-string))
+
+     returns the empty string.  This is because something somewhere
+     replaces the XPM data with a glyph -- I haven't figured out where
+     this occurs.
+
+   Kyle Jones <kyle_jones@wonderworks.com> replies:
+
+     Do this:
+
+              (setq format-alist nil)
+
+     The image-mode stuff is gone from format-alist in the 21.4 branch,
+     praise be.
+
+

 \1f
 Tag Table:
 \1f
 Tag Table:

-(Indirect)

 Node: Top\7f205
 Node: Top\7f205

-Node: Introduction\7f16756
-Node: Q1.0.1\7f20222
-Node: Q1.0.2\7f21123
-Node: Q1.0.3\7f21668
-Node: Q1.0.4\7f21930
-Node: Q1.0.5\7f23322
-Node: Q1.0.6\7f24011
-Node: Q1.0.7\7f25014
-Node: Q1.0.8\7f25262
-Node: Q1.0.9\7f25477
-Node: Q1.0.10\7f25755
-Node: Q1.0.11\7f25998
-Node: Q1.0.12\7f26385
-Node: Q1.0.13\7f26753
-Node: Q1.0.14\7f27002
-Node: Q1.1.1\7f27514
-Node: Q1.1.2\7f28556
-Node: Q1.1.3\7f28949
-Node: Q1.2.1\7f29900
-Node: Q1.2.2\7f31056
-Node: Q1.2.3\7f31490
-Node: Q1.3.1\7f32574
-Node: Q1.3.2\7f33225
-Node: Q1.3.3\7f33689
-Node: Q1.3.4\7f33930
-Node: Q1.3.5\7f34703
-Node: Q1.3.6\7f37108
-Node: Q1.3.7\7f38639
-Node: Q1.4.1\7f39574
-Node: Q1.4.2\7f41325
-Node: Q1.4.3\7f41696
-Node: Q1.4.4\7f42115
-Node: Q1.4.5\7f43655
-Node: Q1.4.6\7f43959
-Node: Installation\7f44952
-Node: Q2.0.1\7f47527
-Node: Q2.0.2\7f48327
-Node: Q2.0.3\7f50095
-Node: Q2.0.4\7f51393
-Node: Q2.0.5\7f51985
-Node: Q2.0.6\7f52333
-Node: Q2.0.7\7f52714
-Node: Q2.0.8\7f53095
-Node: Q2.0.9\7f54672
-Node: Q2.0.10\7f56110
-Node: Q2.0.11\7f56954
-Node: Q2.0.12\7f57895
-Node: Q2.0.13\7f59419
-Node: Q2.0.14\7f59908
-Node: Q2.1.1\7f60966
-Node: Q2.1.2\7f63687
-Node: Q2.1.3\7f64917
-Node: Q2.1.4\7f66210
-Node: Q2.1.5\7f67009
-Node: Q2.1.6\7f67371
-Node: Q2.1.7\7f67848
-Node: Q2.1.8\7f68201
-Node: Q2.1.9\7f69735
-Node: Q2.1.10\7f70176
-Node: Q2.1.11\7f70933
-Node: Q2.1.12\7f71798
-Node: Q2.1.13\7f72753
-Node: Q2.1.14\7f73784
-Node: Q2.1.15\7f74895
-Node: Q2.1.16\7f81845
-Node: Q2.1.17\7f82539
-Node: Q2.1.18\7f83136
-Node: Q2.1.19\7f83263
-Node: Q2.1.20\7f83802
-Node: Q2.1.21\7f84184
-Node: Q2.1.22\7f84377
-Node: Q2.1.23\7f85674
-Node: Q2.1.24\7f86342
-Node: Q2.1.25\7f86814
-Node: Customization\7f87449
-Node: Q3.0.1\7f92303
-Node: Q3.0.2\7f93099
-Node: Q3.0.3\7f93534
-Node: Q3.0.4\7f93961
-Node: Q3.0.5\7f94794
-Node: Q3.0.6\7f95575
-Node: Q3.0.7\7f96155
-Node: Q3.0.8\7f96738
-Node: Q3.0.9\7f97696
-Node: Q3.1.1\7f98257
-Node: Q3.1.2\7f98994
-Node: Q3.1.3\7f99425
-Node: Q3.1.4\7f99614
-Node: Q3.1.5\7f99803
-Node: Q3.1.6\7f100197
-Node: Q3.1.7\7f100916
-Node: Q3.1.8\7f103140
-Node: Q3.2.1\7f103682
-Node: Q3.2.2\7f105365
-Node: Q3.2.3\7f106164
-Node: Q3.2.4\7f106776
-Node: Q3.2.5\7f107481
-Node: Q3.2.6\7f107948
-Node: Q3.3.1\7f108873
-Node: Q3.3.2\7f109132
-Node: Q3.3.3\7f109795
-Node: Q3.3.4\7f110186
-Node: Q3.3.5\7f110980
-Node: Q3.4.1\7f112461
-Node: Q3.4.2\7f113038
-Node: Q3.5.1\7f113433
-Node: Q3.5.2\7f114882
-Node: Q3.5.3\7f115310
-Node: Q3.5.4\7f116148
-Node: Q3.5.5\7f116750
-Node: Q3.5.6\7f117901
-Node: Q3.5.7\7f118885
-Node: Q3.5.8\7f120289
-Node: Q3.5.9\7f120534
-Node: Q3.5.10\7f121325
-Node: Q3.5.11\7f121961
-Node: Q3.6.1\7f122514
-Node: Q3.6.2\7f123270
-Node: Q3.6.3\7f123709
-Node: Q3.7.1\7f124128
-Node: Q3.7.2\7f125016
-Node: Q3.7.3\7f125675
-Node: Q3.7.4\7f126097
-Node: Q3.7.5\7f126440
-Node: Q3.7.6\7f126908
-Node: Q3.7.7\7f127644
-Node: Q3.7.8\7f128675
-Node: Q3.8.1\7f129094
-Node: Q3.8.2\7f129390
-Node: Q3.8.3\7f129863
-Node: Q3.8.4\7f130490
-Node: Q3.8.5\7f131209
-Node: Q3.9.1\7f131994
-Node: Q3.9.2\7f132793
-Node: Q3.9.3\7f133391
-Node: Q3.9.4\7f134053
-Node: Q3.10.1\7f134766
-Node: Q3.10.2\7f135605
-Node: Q3.10.3\7f136620
-Node: Q3.10.4\7f137358
-Node: Q3.10.5\7f137741
-Node: Subsystems\7f138793
-Node: Q4.0.1\7f141280
-Node: Q4.0.2\7f141805
-Node: Q4.0.3\7f142363
-Node: Q4.0.4\7f142684
-Node: Q4.0.5\7f142926
-Node: Q4.0.6\7f143157
-Node: Q4.0.7\7f143745
-Node: Q4.0.8\7f144070
-Node: Q4.0.9\7f145297
-Node: Q4.0.10\7f147335
-Node: Q4.0.11\7f147824
-Node: Q4.0.12\7f148702
-Node: Q4.1.1\7f149685
-Node: Q4.1.2\7f150088
-Node: Q4.1.3\7f150415
-Node: Q4.2.1\7f150724
-Node: Q4.2.2\7f151354
-Node: Q4.2.3\7f151594
-Node: Q4.2.4\7f152138
-Node: Q4.3.1\7f152791
-Node: Q4.3.2\7f153375
-Node: Q4.3.3\7f154856
-Node: Q4.3.4\7f155128
-Node: Q4.3.5\7f155805
-Node: Q4.4.1\7f156433
-Node: Q4.4.2\7f157919
-Node: Q4.5.1\7f159123
-Node: Q4.6.1\7f159892
-Node: Q4.7.1\7f165152
-Node: Q4.7.2\7f166107
-Node: Q4.7.3\7f166404
-Node: Q4.7.4\7f166590
-Node: Q4.7.5\7f167474
-Node: Q4.7.6\7f169115
-Node: Miscellaneous\7f169404
-Node: Q5.0.1\7f172823
-Node: Q5.0.2\7f173558
-Node: Q5.0.3\7f174422
-Node: Q5.0.4\7f174833
-Node: Q5.0.5\7f176124
-Node: Q5.0.6\7f178114
-Node: Q5.0.7\7f178771
-Node: Q5.0.8\7f179376
-Node: Q5.0.9\7f179905
-Node: Q5.0.10\7f180439
-Node: Q5.0.11\7f180687
-Node: Q5.0.12\7f180936
-Node: Q5.0.13\7f181863
-Node: Q5.0.14\7f182557
-Node: Q5.0.15\7f183322
-Node: Q5.0.16\7f183619
-Node: Q5.0.17\7f184141
-Node: Q5.0.18\7f184461
-Node: Q5.0.19\7f184655
-Node: Q5.0.20\7f185079
-Node: Q5.1.1\7f185994
-Node: Q5.1.2\7f188063
-Node: Q5.1.3\7f188799
-Node: Q5.1.4\7f192193
-Node: Q5.1.5\7f192728
-Node: Q5.1.6\7f194852
-Node: Q5.1.7\7f196338
-Node: Q5.1.8\7f197931
-Node: Q5.1.9\7f198483
-Node: Q5.1.10\7f199368
-Node: Q5.1.11\7f200499
-Node: Q5.2.1\7f201046
-Node: Q5.2.2\7f201637
-Node: Q5.2.3\7f201981
-Node: Q5.2.4\7f202216
-Node: Q5.3.1\7f203126
-Node: Q5.3.2\7f204357
-Node: Q5.3.3\7f204602
-Node: Q5.3.4\7f205086
-Node: Q5.3.5\7f205763
-Node: Q5.3.6\7f206632
-Node: Q5.3.7\7f206877
-Node: Q5.3.8\7f209067
-Node: Q5.3.9\7f209314
-Node: Q5.3.10\7f210267
-Node: Q5.3.11\7f212351
-Node: Q5.3.12\7f213942
-Node: MS Windows\7f215216
-Node: Q6.0.1\7f216712
-Node: Q6.0.2\7f217467
-Node: Q6.0.3\7f217997
-Node: Q6.0.4\7f218264
-Node: Q6.1.1\7f220417
-Node: Q6.1.2\7f221288
-Node: Q6.1.3\7f221743
-Node: Q6.1.4\7f222025
-Node: Q6.1.5\7f222403
-Node: Q6.1.6\7f223283
-Node: Q6.2.1\7f225589
-Node: Q6.2.2\7f226490
-Node: Q6.2.3\7f226902
-Node: Q6.3.1\7f227443
-Node: Q6.3.2\7f228758
-Node: Q6.3.3\7f231939
-Node: Q6.4.1\7f232441
-Node: Current Events\7f233776
-Node: Q7.0.1\7f234430
-Node: Q7.0.2\7f235069
-Node: Q7.0.3\7f236142
-Node: Q7.0.4\7f236370
+Node: Introduction\7f18020
+Node: Q1.0.1\7f21577
+Node: Q1.0.2\7f22578
+Node: Q1.0.3\7f23120
+Node: Q1.0.4\7f23379
+Node: Q1.0.5\7f24768
+Node: Q1.0.6\7f25454
+Node: Q1.0.7\7f26556
+Node: Q1.0.8\7f26801
+Node: Q1.0.9\7f27013
+Node: Q1.0.10\7f27295
+Node: Q1.0.11\7f27624
+Node: Q1.0.12\7f28345
+Node: Q1.0.13\7f28710
+Node: Q1.0.14\7f28956
+Node: Q1.1.1\7f29464
+Node: Q1.1.2\7f30503
+Node: Q1.1.3\7f30893
+Node: Q1.2.1\7f31841
+Node: Q1.2.2\7f32988
+Node: Q1.2.3\7f33419
+Node: Q1.3.1\7f34500
+Node: Q1.3.2\7f35308
+Node: Q1.3.3\7f35910
+Node: Q1.3.4\7f36488
+Node: Q1.3.5\7f37281
+Node: Q1.3.6\7f41962
+Node: Q1.3.7\7f44512
+Node: Q1.3.8\7f45433
+Node: Q1.3.9\7f46426
+Node: Q1.4.1\7f47561
+Node: Q1.4.2\7f49309
+Node: Q1.4.3\7f49677
+Node: Q1.4.4\7f50093
+Node: Q1.4.5\7f51630
+Node: Q1.4.6\7f51931
+Node: Installation\7f52921
+Node: Q2.0.1\7f55609
+Node: Q2.0.2\7f56406
+Node: Q2.0.3\7f57925
+Node: Q2.0.4\7f59220
+Node: Q2.0.5\7f59809
+Node: Q2.0.6\7f60154
+Node: Q2.0.7\7f60762
+Node: Q2.0.8\7f61140
+Node: Q2.0.9\7f62714
+Node: Q2.0.10\7f64325
+Node: Q2.0.11\7f65166
+Node: Q2.0.12\7f66104
+Node: Q2.0.13\7f67625
+Node: Q2.0.14\7f68099
+Node: Q2.0.15\7f69143
+Node: Q2.0.16\7f69816
+Node: Q2.1.1\7f70643
+Node: Q2.1.2\7f74829
+Node: Q2.1.3\7f76056
+Node: Q2.1.4\7f77350
+Node: Q2.1.5\7f78146
+Node: Q2.1.6\7f78507
+Node: Q2.1.7\7f78980
+Node: Q2.1.8\7f79330
+Node: Q2.1.9\7f80861
+Node: Q2.1.10\7f81299
+Node: Q2.1.11\7f82053
+Node: Q2.1.12\7f82916
+Node: Q2.1.13\7f83868
+Node: Q2.1.14\7f84896
+Node: Q2.1.15\7f86004
+Node: Q2.1.16\7f93822
+Node: Q2.1.17\7f94513
+Node: Q2.1.18\7f95107
+Node: Q2.1.19\7f95496
+Node: Q2.1.20\7f96032
+Node: Q2.1.21\7f96411
+Node: Q2.1.22\7f96604
+Node: Q2.1.23\7f97898
+Node: Q2.1.24\7f98563
+Node: Q2.1.25\7f99020
+Node: Customization\7f99636
+Node: Q3.0.1\7f104582
+Node: Q3.0.2\7f105375
+Node: Q3.0.3\7f105807
+Node: Q3.0.4\7f106231
+Node: Q3.0.5\7f107061
+Node: Q3.0.6\7f107839
+Node: Q3.0.7\7f108416
+Node: Q3.0.8\7f108996
+Node: Q3.0.9\7f109951
+Node: Q3.1.1\7f110509
+Node: Q3.1.2\7f111297
+Node: Q3.1.3\7f111725
+Node: Q3.1.4\7f111914
+Node: Q3.1.5\7f112103
+Node: Q3.1.6\7f112494
+Node: Q3.1.7\7f113210
+Node: Q3.1.8\7f115431
+Node: Q3.2.1\7f115970
+Node: Q3.2.2\7f117651
+Node: Q3.2.3\7f118631
+Node: Q3.2.4\7f119241
+Node: Q3.2.5\7f119943
+Node: Q3.2.6\7f120407
+Node: Q3.2.7\7f121329
+Node: Q3.3.1\7f122567
+Node: Q3.3.2\7f122826
+Node: Q3.3.3\7f123486
+Node: Q3.3.4\7f123874
+Node: Q3.3.5\7f124665
+Node: Q3.4.1\7f126143
+Node: Q3.4.2\7f126717
+Node: Q3.5.1\7f127113
+Node: Q3.5.2\7f128559
+Node: Q3.5.3\7f128984
+Node: Q3.5.4\7f129819
+Node: Q3.5.5\7f130422
+Node: Q3.5.6\7f131570
+Node: Q3.5.7\7f132551
+Node: Q3.5.8\7f134055
+Node: Q3.5.9\7f134297
+Node: Q3.5.10\7f135089
+Node: Q3.5.11\7f135722
+Node: Q3.6.1\7f136272
+Node: Q3.6.2\7f137025
+Node: Q3.6.3\7f137464
+Node: Q3.7.1\7f137880
+Node: Q3.7.2\7f138765
+Node: Q3.7.3\7f139421
+Node: Q3.7.4\7f139840
+Node: Q3.7.5\7f140180
+Node: Q3.7.6\7f140645
+Node: Q3.7.7\7f141379
+Node: Q3.7.8\7f142406
+Node: Q3.8.1\7f142822
+Node: Q3.8.2\7f143118
+Node: Q3.8.3\7f143539
+Node: Q3.8.4\7f144163
+Node: Q3.8.5\7f145422
+Node: Q3.9.1\7f146204
+Node: Q3.9.2\7f147001
+Node: Q3.9.3\7f147596
+Node: Q3.9.4\7f148255
+Node: Q3.10.1\7f148965
+Node: Q3.10.2\7f149801
+Node: Q3.10.3\7f150813
+Node: Q3.10.4\7f151548
+Node: Q3.10.5\7f151932
+Node: Q3.10.6\7f152997
+Node: Subsystems\7f156030
+Node: Q4.0.1\7f158563
+Node: Q4.0.2\7f159085
+Node: Q4.0.3\7f159640
+Node: Q4.0.4\7f159958
+Node: Q4.0.5\7f160197
+Node: Q4.0.6\7f160428
+Node: Q4.0.7\7f161013
+Node: Q4.0.8\7f161331
+Node: Q4.0.9\7f162555
+Node: Q4.0.10\7f164590
+Node: Q4.0.11\7f165076
+Node: Q4.0.12\7f165951
+Node: Q4.1.1\7f166931
+Node: Q4.1.2\7f167331
+Node: Q4.1.3\7f167655
+Node: Q4.2.1\7f167961
+Node: Q4.2.2\7f168587
+Node: Q4.2.3\7f168824
+Node: Q4.2.4\7f169365
+Node: Q4.3.1\7f170015
+Node: Q4.3.2\7f170596
+Node: Q4.3.3\7f172297
+Node: Q4.3.4\7f172566
+Node: Q4.3.5\7f173240
+Node: Q4.4.1\7f173865
+Node: Q4.4.2\7f175348
+Node: Q4.5.1\7f176549
+Node: Q4.6.1\7f177316
+Node: Q4.7.1\7f182430
+Node: Q4.7.2\7f183374
+Node: Q4.7.3\7f183668
+Node: Q4.7.4\7f183854
+Node: Q4.7.5\7f184735
+Node: Q4.7.6\7f186373
+Node: Q4.7.7\7f186674
+Node: Miscellaneous\7f187543
+Node: Q5.0.1\7f190959
+Node: Q5.0.2\7f191691
+Node: Q5.0.3\7f192552
+Node: Q5.0.4\7f192960
+Node: Q5.0.5\7f194248
+Node: Q5.0.6\7f196235
+Node: Q5.0.7\7f196889
+Node: Q5.0.8\7f197491
+Node: Q5.0.9\7f198017
+Node: Q5.0.10\7f198548
+Node: Q5.0.11\7f198793
+Node: Q5.0.12\7f199039
+Node: Q5.0.13\7f199963
+Node: Q5.0.14\7f200654
+Node: Q5.0.15\7f201416
+Node: Q5.0.16\7f201710
+Node: Q5.0.17\7f202229
+Node: Q5.0.18\7f202546
+Node: Q5.0.19\7f202740
+Node: Q5.0.20\7f203161
+Node: Q5.1.1\7f204074
+Node: Q5.1.2\7f206140
+Node: Q5.1.3\7f206873
+Node: Q5.1.4\7f210265
+Node: Q5.1.5\7f210797
+Node: Q5.1.6\7f212921
+Node: Q5.1.7\7f214404
+Node: Q5.1.8\7f215994
+Node: Q5.1.9\7f216543
+Node: Q5.1.10\7f217425
+Node: Q5.1.11\7f218553
+Node: Q5.2.1\7f219098
+Node: Q5.2.2\7f219686
+Node: Q5.2.3\7f220027
+Node: Q5.2.4\7f220259
+Node: Q5.3.1\7f221167
+Node: Q5.3.2\7f222395
+Node: Q5.3.3\7f222637
+Node: Q5.3.4\7f223196
+Node: Q5.3.5\7f223870
+Node: Q5.3.6\7f224736
+Node: Q5.3.7\7f224978
+Node: Q5.3.8\7f227165
+Node: Q5.3.9\7f227409
+Node: Q5.3.10\7f228359
+Node: Q5.3.11\7f230440
+Node: Q5.3.12\7f232028
+Node: MS Windows\7f233299
+Node: Q6.0.1\7f235483
+Node: Q6.0.2\7f236476
+Node: Q6.0.3\7f237171
+Node: Q6.0.4\7f237606
+Node: Q6.0.5\7f237987
+Node: Q6.0.6\7f238724
+Node: Q6.0.7\7f242055
+Node: Q6.1.1\7f243528
+Node: Q6.1.2\7f244186
+Node: Q6.1.3\7f244457
+Node: Q6.1.4\7f245391
+Node: Q6.1.5\7f246864
+Node: Q6.1.6\7f247698
+Node: Q6.1.7\7f248739
+Node: Q6.2.1\7f249404
+Node: Q6.2.2\7f250867
+Node: Q6.2.3\7f251315
+Node: Q6.2.4\7f252017
+Node: Q6.2.5\7f253732
+Node: Q6.3.1\7f254177
+Node: Q6.3.2\7f255440
+Node: Q6.3.3\7f258620
+Node: Q6.3.4\7f261583
+Node: Q6.4.1\7f262081
+Node: Q6.4.2\7f263284
+Node: Q6.4.3\7f263785
+Node: Current Events\7f264594
+Node: Q7.0.1\7f265739
+Node: Q7.0.2\7f265984
+Node: Q7.0.3\7f270859
+Node: Q7.0.4\7f276626
+Node: Q7.0.5\7f276851
+Node: Q7.0.6\7f277933
+Node: Legacy Versions\7f278623
+Node: Q8.0.1\7f279281

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

diff --git a/info/xemacs.info b/info/xemacs.info
index 0a3a6df..50b49e1 100644 (file)
--- a/info/xemacs.info
+++ b/info/xemacs.info
@@ -1,4 +1,4 @@
-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from

 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -32,408 +32,389 @@ translation approved by the author instead of in the original English.
 \1f
 Indirect:
 xemacs.info-1: 1350
 \1f
 Indirect:
 xemacs.info-1: 1350

-xemacs.info-2: 49148
-xemacs.info-3: 97130
-xemacs.info-4: 146370
-xemacs.info-5: 195521
-xemacs.info-6: 243181
-xemacs.info-7: 283264
-xemacs.info-8: 333227
-xemacs.info-9: 380697
-xemacs.info-10: 429215
-xemacs.info-11: 477039
-xemacs.info-12: 526210
-xemacs.info-13: 575703
-xemacs.info-14: 620063
-xemacs.info-15: 669495
-xemacs.info-16: 718900
-xemacs.info-17: 768577
-xemacs.info-18: 816830
-xemacs.info-19: 866461
-xemacs.info-20: 891448
-xemacs.info-21: 923102
-xemacs.info-22: 972506
-xemacs.info-23: 1015092
+xemacs.info-2: 301112
+xemacs.info-3: 599878
+xemacs.info-4: 892425

 \1f
 Tag Table:
 (Indirect)
 Node: Top\7f1350
 \1f
 Tag Table:
 (Indirect)
 Node: Top\7f1350

-Node: License\7f22942
-Node: Distrib\7f36224
-Node: Intro\7f37888
-Node: Frame\7f40759
-Node: Point\7f44804
-Node: Echo Area\7f46771
-Node: Mode Line\7f49148
-Node: GUI Components\7f53579
-Node: Menubar Basics\7f54860
-Node: Scrollbar Basics\7f56776
-Node: Mode Line Basics\7f57669
-Node: Toolbar Basics\7f58501
-Node: Gutter Basics\7f59168
-Node: Inhibiting\7f61222
-Node: Customizing\7f63593
-Node: XEmacs under X\7f63842
-Node: XEmacs under MS Windows\7f67056
-Node: Keystrokes\7f67471
-Node: Intro to Keystrokes\7f68315
-Node: Representing Keystrokes\7f70418
-Node: Key Sequences\7f71775
-Node: String Key Sequences\7f75116
-Node: Meta Key\7f75499
-Node: Super and Hyper Keys\7f76972
-Node: Character Representation\7f83217
-Node: Commands\7f84237
-Node: Pull-down Menus\7f87086
-Node: File Menu\7f90435
-Node: Edit Menu\7f94257
-Node: Apps Menu\7f96640
-Node: Options Menu\7f97130
-Node: Buffers Menu\7f101148
-Node: Tools Menu\7f101455
-Node: Help Menu\7f101946
-Node: Menu Customization\7f102347
-Node: Entering Emacs\7f106577
-Node: Exiting\7f109474
-Node: Command Switches\7f113947
-Node: Startup Paths\7f123969
-Node: Basic\7f131299
-Node: Inserting Text\7f132703
-Node: Moving Point\7f135699
-Node: Erasing\7f139305
-Node: Basic Files\7f140610
-Node: Basic Help\7f142532
-Node: Blank Lines\7f143127
-Node: Continuation Lines\7f144703
-Node: Position Info\7f146370
-Node: Arguments\7f149786
-Node: Undo\7f153885
-Node: Minibuffer\7f156832
-Node: Minibuffer File\7f159442
-Node: Minibuffer Edit\7f161247
-Node: Completion\7f164188
-Node: Completion Example\7f166119
-Node: Completion Commands\7f167214
-Node: Strict Completion\7f170190
-Node: Completion Options\7f171971
-Node: Minibuffer History\7f173479
-Node: Repetition\7f176663
-Node: M-x\7f179508
-Node: Help\7f184602
-Node: Help Summary\7f186012
-Node: Key Help\7f188798
-Node: Name Help\7f189757
-Node: Apropos\7f192402
-Node: Library Keywords\7f195521
-Node: Help Mode\7f197842
-Node: Misc Help\7f198339
-Node: Mark\7f201487
-Node: Setting Mark\7f203341
-Node: Using Region\7f206463
-Node: Marking Objects\7f207200
-Node: Mark Ring\7f209038
-Node: Mouse Selection\7f210754
-Node: Additional Mouse Operations\7f212761
-Node: Killing\7f216965
-Node: Yanking\7f222601
-Node: Kill Ring\7f223404
-Node: Appending Kills\7f225006
-Node: Earlier Kills\7f227043
-Node: Using X Selections\7f229656
-Node: X Clipboard Selection\7f230906
-Node: X Selection Commands\7f233083
-Node: X Cut Buffers\7f234169
-Node: Active Regions\7f235528
-Node: Accumulating Text\7f240108
-Node: Rectangles\7f243181
-Node: Registers\7f246700
-Node: RegPos\7f248154
-Node: RegText\7f249310
-Node: RegRect\7f250416
-Node: RegConfig\7f251295
-Node: RegNumbers\7f252235
-Node: RegFiles\7f252953
-Node: Bookmarks\7f253611
-Node: Display\7f256983
-Node: Scrolling\7f258478
-Node: Horizontal Scrolling\7f262621
-Node: Selective Display\7f263816
-Node: Display Vars\7f265035
-Node: Search\7f267713
-Node: Incremental Search\7f268906
-Node: Non-Incremental Search\7f277834
-Node: Word Search\7f279276
-Node: Regexp Search\7f280894
-Node: Regexps\7f283264
-Node: Search Case\7f297261
-Node: Replace\7f298042
-Node: Unconditional Replace\7f298990
-Node: Regexp Replace\7f300125
-Node: Replacement and Case\7f301060
-Node: Query Replace\7f302040
-Node: Other Repeating Search\7f305267
-Node: Fixit\7f306522
-Node: Kill Errors\7f307102
-Node: Transpose\7f308435
-Node: Fixing Case\7f310839
-Node: Spelling\7f311485
-Node: Files\7f312946
-Node: File Names\7f314256
-Node: Visiting\7f318593
-Node: Saving\7f325425
-Node: Backup\7f330348
-Node: Backup Names\7f331744
-Node: Backup Deletion\7f333227
-Node: Backup Copying\7f334377
-Node: Interlocking\7f336083
-Node: Reverting\7f340211
-Node: Auto Save\7f342123
-Node: Auto Save Files\7f343090
-Node: Auto Save Control\7f344931
-Node: Recover\7f346769
-Node: Version Control\7f347924
-Node: Concepts of VC\7f349962
-Node: Editing with VC\7f351572
-Node: Variables for Check-in/out\7f356828
-Node: Log Entries\7f358727
-Node: Change Logs and VC\7f359907
-Node: Old Versions\7f363174
-Node: VC Status\7f365177
-Node: Renaming and VC\7f366891
-Node: Snapshots\7f367570
-Node: Making Snapshots\7f368071
-Node: Snapshot Caveats\7f369364
-Node: Version Headers\7f371173
-Node: ListDir\7f373872
-Node: Comparing Files\7f375921
-Node: Dired\7f377454
-Node: Dired Enter\7f378125
-Node: Dired Edit\7f378950
-Node: Dired Deletion\7f380697
-Node: Dired Immed\7f383920
-Node: Misc File Ops\7f385196
-Node: Buffers\7f387684
-Node: Select Buffer\7f389842
-Node: List Buffers\7f391637
-Node: Misc Buffer\7f393395
-Node: Kill Buffer\7f395038
-Node: Several Buffers\7f396168
-Node: Windows\7f400035
-Node: Basic Window\7f400746
-Node: Split Window\7f402465
-Node: Other Window\7f404598
-Node: Pop Up Window\7f407029
-Node: Change Window\7f408534
-Node: Mule\7f411442
-Node: Mule Intro\7f412705
-Node: Language Environments\7f413721
-Node: Input Methods\7f415828
-Node: Select Input Method\7f419548
-Node: Coding Systems\7f421703
-Node: Recognize Coding\7f425889
-Node: Specify Coding\7f429215
-Node: Major Modes\7f434146
-Node: Choosing Modes\7f436365
-Node: Indentation\7f438755
-Node: Indentation Commands\7f440850
-Node: Tab Stops\7f443579
-Node: Just Spaces\7f445428
-Node: Text\7f446243
-Node: Text Mode\7f448226
-Node: Nroff Mode\7f450305
-Node: TeX Mode\7f451948
-Node: TeX Editing\7f454200
-Node: TeX Print\7f457634
-Node: Outline Mode\7f460853
-Node: Outline Format\7f462334
-Node: Outline Motion\7f465134
-Node: Outline Visibility\7f466687
-Node: Words\7f469608
-Node: Sentences\7f472555
-Node: Paragraphs\7f474751
-Node: Pages\7f477039
-Node: Filling\7f479639
-Node: Auto Fill\7f480210
-Node: Fill Commands\7f482357
-Node: Fill Prefix\7f484522
-Node: Case\7f486710
-Node: Programs\7f488738
-Node: Program Modes\7f491288
-Node: Lists\7f493520
-Node: Defuns\7f499360
-Node: Grinding\7f502013
-Node: Basic Indent\7f502641
-Node: Multi-line Indent\7f504662
-Node: Lisp Indent\7f506278
-Node: C Indent\7f509728
-Node: Matching\7f514968
-Node: Comments\7f516490
-Node: Balanced Editing\7f522942
-Node: Lisp Completion\7f523956
-Node: Documentation\7f524971
-Node: Change Log\7f526210
-Node: Tags\7f528788
-Node: Tag Syntax\7f530545
-Node: Create Tags Table\7f535245
-Node: Etags Regexps\7f539305
-Node: Select Tags Table\7f543963
-Node: Find Tag\7f547736
-Node: Tags Search\7f550700
-Node: List Tags\7f554156
-Node: Fortran\7f555185
-Node: Fortran Motion\7f556261
-Node: Fortran Indent\7f557081
-Node: ForIndent Commands\7f557766
-Node: ForIndent Num\7f558911
-Node: ForIndent Conv\7f560185
-Node: ForIndent Vars\7f560961
-Node: Fortran Comments\7f562129
-Node: Fortran Columns\7f565727
-Node: Fortran Abbrev\7f567150
-Node: Asm Mode\7f568059
-Node: Running\7f568611
-Node: Compilation\7f569580
-Node: Lisp Modes\7f574430
-Node: Lisp Libraries\7f575703
-Node: Loading\7f576257
-Node: Compiling Libraries\7f580717
-Node: Mocklisp\7f583608
-Node: Lisp Eval\7f584285
-Node: Lisp Debug\7f587925
-Node: Lisp Interaction\7f593352
-Node: External Lisp\7f594707
-Node: Packages\7f596781
-Node: Package Terminology\7f597690
-Node: Installing Packages\7f599300
-Node: Sumo\7f602210
-Node: Manually\7f603091
-Node: Automatically\7f604461
-Node: Which Packages\7f609024
-Node: Removing Packages\7f609833
-Node: Building Packages\7f610529
-Node: Local.rules File\7f613169
-Node: Creating Packages\7f615023
-Node: Available Packages\7f620063
-Node: Abbrevs\7f626778
-Node: Defining Abbrevs\7f628977
-Node: Expanding Abbrevs\7f631424
-Node: Editing Abbrevs\7f634126
-Node: Saving Abbrevs\7f635999
-Node: Dynamic Abbrevs\7f637954
-Node: Picture\7f639256
-Node: Basic Picture\7f641689
-Node: Insert in Picture\7f643974
-Node: Tabs in Picture\7f645396
-Node: Rectangles in Picture\7f646917
-Node: Sending Mail\7f648825
-Node: Mail Format\7f650536
-Node: Mail Headers\7f651886
-Node: Mail Mode\7f658294
-Node: Reading Mail\7f661907
-Node: Calendar/Diary\7f663482
-Node: Calendar Motion\7f665156
-Node: Calendar Unit Motion\7f666039
-Node: Move to Beginning or End\7f668362
-Node: Specified Dates\7f669495
-Node: Scroll Calendar\7f670383
-Node: Mark and Region\7f672174
-Node: General Calendar\7f674080
-Node: LaTeX Calendar\7f675688
-Node: Holidays\7f677702
-Node: Sunrise/Sunset\7f680804
-Node: Lunar Phases\7f683843
-Node: Other Calendars\7f685228
-Node: Calendar Systems\7f686715
-Node: To Other Calendar\7f689826
-Node: From Other Calendar\7f691817
-Node: Mayan Calendar\7f694122
-Node: Diary\7f697317
-Node: Diary Commands\7f699066
-Node: Format of Diary File\7f702389
-Node: Date Formats\7f705259
-Node: Adding to Diary\7f707833
-Node: Special Diary Entries\7f709464
-Node: Calendar Customization\7f714803
-Node: Calendar Customizing\7f715665
-Node: Holiday Customizing\7f718900
-Node: Date Display Format\7f725387
-Node: Time Display Format\7f726345
-Node: Daylight Savings\7f727483
-Node: Diary Customizing\7f730671
-Node: Hebrew/Islamic Entries\7f735292
-Node: Fancy Diary Display\7f738632
-Node: Included Diary Files\7f740548
-Node: Sexp Diary Entries\7f741529
-Node: Appt Customizing\7f746619
-Node: Sorting\7f747665
-Node: Shell\7f752471
-Node: Single Shell\7f753764
-Node: Interactive Shell\7f755378
-Node: Shell Mode\7f759143
-Node: Terminal emulator\7f761634
-Node: Term Mode\7f763943
-Node: Paging in Term\7f764857
-Node: Narrowing\7f765655
-Node: Hardcopy\7f767605
-Node: Recursive Edit\7f768577
-Node: Dissociated Press\7f771564
-Node: CONX\7f774127
-Node: Amusements\7f775151
-Node: Emulation\7f775631
-Node: Customization\7f777491
-Node: Minor Modes\7f779307
-Node: Variables\7f780939
-Node: Examining\7f782895
-Node: Easy Customization\7f784356
-Node: Customization Groups\7f785370
-Node: Changing an Option\7f788299
-Node: Face Customization\7f794569
-Node: Specific Customization\7f796333
-Node: Edit Options\7f798940
-Node: Locals\7f800524
-Node: File Variables\7f803703
-Node: Keyboard Macros\7f808253
-Node: Basic Kbd Macro\7f810424
-Node: Save Kbd Macro\7f812356
-Node: Kbd Macro Query\7f814014
-Node: Key Bindings\7f815956
-Node: Keymaps\7f816830
-Node: Rebinding\7f820680
-Node: Interactive Rebinding\7f821379
-Node: Programmatic Rebinding\7f823568
-Node: Key Bindings Using Strings\7f826375
-Node: Disabling\7f828002
-Node: Syntax\7f829781
-Node: Syntax Entry\7f830662
-Node: Syntax Change\7f834746
-Node: Init File\7f836915
-Node: Init Syntax\7f838379
-Node: Init Examples\7f840730
-Node: Terminal Init\7f844920
-Node: Audible Bell\7f846657
-Node: Faces\7f850088
-Node: Frame Components\7f854930
-Node: X Resources\7f855375
-Node: Geometry Resources\7f857034
-Node: Iconic Resources\7f859482
-Node: Resource List\7f859954
-Node: Face Resources\7f866461
-Node: Widgets\7f870138
-Node: Menubar Resources\7f871077
-Node: Quitting\7f872591
-Node: Lossage\7f875569
-Node: Stuck Recursive\7f876213
-Node: Screen Garbled\7f876919
-Node: Text Garbled\7f878053
-Node: Unasked-for Search\7f878692
-Node: Emergency Escape\7f879477
-Node: Total Frustration\7f881256
-Node: Bugs\7f881887
-Node: Glossary\7f891448
-Node: Manifesto\7f923102
-Node: Key Index\7f946579
-Node: Command Index\7f972506
-Node: Variable Index\7f1015092
-Node: Concept Index\7f1031178
+Node: License\7f22903
+Node: Distrib\7f36178
+Node: Intro\7f37836
+Node: Frame\7f40704
+Node: Point\7f44750
+Node: Echo Area\7f46715
+Node: Mode Line\7f49089
+Node: GUI Components\7f53517
+Node: Menubar Basics\7f54795
+Node: Scrollbar Basics\7f56708
+Node: Mode Line Basics\7f57599
+Node: Toolbar Basics\7f58428
+Node: Gutter Basics\7f59092
+Node: Inhibiting\7f61491
+Node: Customizing\7f63859
+Node: XEmacs under X\7f64105
+Node: XEmacs under MS Windows\7f67391
+Node: Keystrokes\7f67803
+Node: Intro to Keystrokes\7f68647
+Node: Representing Keystrokes\7f70747
+Node: Key Sequences\7f72105
+Node: String Key Sequences\7f75443
+Node: Meta Key\7f75823
+Node: Super and Hyper Keys\7f77294
+Node: Character Representation\7f83536
+Node: Commands\7f84553
+Node: Pull-down Menus\7f87398
+Node: File Menu\7f90744
+Node: Edit Menu\7f94563
+Node: Apps Menu\7f96943
+Node: Options Menu\7f97430
+Node: Buffers Menu\7f101445
+Node: Tools Menu\7f101749
+Node: Help Menu\7f102237
+Node: Menu Customization\7f102635
+Node: Entering Emacs\7f106863
+Node: Exiting\7f109756
+Node: Command Switches\7f114226
+Node: Startup Paths\7f124238
+Node: Basic\7f131556
+Node: Inserting Text\7f132957
+Node: Moving Point\7f135950
+Node: Erasing\7f139553
+Node: Basic Files\7f140858
+Node: Basic Help\7f142777
+Node: Blank Lines\7f143369
+Node: Continuation Lines\7f144942
+Node: Position Info\7f146606
+Node: Arguments\7f150019
+Node: Undo\7f154115
+Node: Minibuffer\7f157059
+Node: Minibuffer File\7f159666
+Node: Minibuffer Edit\7f161468
+Node: Completion\7f164406
+Node: Completion Example\7f166334
+Node: Completion Commands\7f167426
+Node: Strict Completion\7f170399
+Node: Completion Options\7f172177
+Node: Minibuffer History\7f173682
+Node: Repetition\7f176863
+Node: M-x\7f179705
+Node: Help\7f184797
+Node: Help Summary\7f186204
+Node: Key Help\7f188990
+Node: Name Help\7f189946
+Node: Apropos\7f192587
+Node: Library Keywords\7f195706
+Node: Help Mode\7f198024
+Node: Misc Help\7f198518
+Node: Mark\7f201663
+Node: Setting Mark\7f203511
+Node: Using Region\7f206630
+Node: Marking Objects\7f207364
+Node: Mark Ring\7f209199
+Node: Mouse Selection\7f210912
+Node: Additional Mouse Operations\7f212916
+Node: Killing\7f217117
+Node: Yanking\7f222750
+Node: Kill Ring\7f223550
+Node: Appending Kills\7f225149
+Node: Earlier Kills\7f227183
+Node: Using X Selections\7f229793
+Node: X Clipboard Selection\7f231040
+Node: X Selection Commands\7f233214
+Node: X Cut Buffers\7f234300
+Node: Active Regions\7f235656
+Node: Accumulating Text\7f240233
+Node: Rectangles\7f243303
+Node: Registers\7f246818
+Node: RegPos\7f248270
+Node: RegText\7f249423
+Node: RegRect\7f250526
+Node: RegConfig\7f251402
+Node: RegNumbers\7f252339
+Node: RegFiles\7f253054
+Node: Bookmarks\7f253709
+Node: Display\7f257078
+Node: Scrolling\7f258570
+Node: Horizontal Scrolling\7f262710
+Node: Selective Display\7f263902
+Node: Display Vars\7f265118
+Node: Search\7f267793
+Node: Incremental Search\7f268983
+Node: Non-Incremental Search\7f277906
+Node: Word Search\7f279345
+Node: Regexp Search\7f280960
+Node: Regexps\7f283327
+Node: Search Case\7f297322
+Node: Replace\7f298100
+Node: Unconditional Replace\7f299045
+Node: Regexp Replace\7f300180
+Node: Replacement and Case\7f301112
+Node: Query Replace\7f302089
+Node: Other Repeating Search\7f305339
+Node: Fixit\7f306590
+Node: Kill Errors\7f307167
+Node: Transpose\7f308500
+Node: Fixing Case\7f310904
+Node: Spelling\7f311550
+Node: Files\7f313011
+Node: File Names\7f314969
+Node: Visiting\7f319961
+Node: Saving\7f326793
+Node: Backup\7f331713
+Node: Backup Names\7f333105
+Node: Backup Deletion\7f334585
+Node: Backup Copying\7f335732
+Node: Interlocking\7f337435
+Node: Reverting\7f341560
+Node: Auto Save\7f343579
+Node: Auto Save Files\7f344542
+Node: Auto Save Control\7f346380
+Node: Recover\7f348215
+Node: Version Control\7f349367
+Node: Concepts of VC\7f351402
+Node: Editing with VC\7f353009
+Node: Variables for Check-in/out\7f358262
+Node: Log Entries\7f360158
+Node: Change Logs and VC\7f361335
+Node: Old Versions\7f364599
+Node: VC Status\7f366602
+Node: Renaming and VC\7f368313
+Node: Snapshots\7f368988
+Node: Making Snapshots\7f369486
+Node: Snapshot Caveats\7f370776
+Node: Version Headers\7f372582
+Node: ListDir\7f375278
+Node: Comparing Files\7f377324
+Node: Dired\7f378854
+Node: Dired Enter\7f379522
+Node: Dired Edit\7f380344
+Node: Dired Deletion\7f382089
+Node: Dired Immed\7f385309
+Node: Misc File Ops\7f386582
+Node: Buffers\7f389068
+Node: Select Buffer\7f391222
+Node: List Buffers\7f393017
+Node: Misc Buffer\7f394775
+Node: Kill Buffer\7f396418
+Node: Several Buffers\7f397545
+Node: Windows\7f401409
+Node: Basic Window\7f402117
+Node: Split Window\7f403833
+Node: Other Window\7f405966
+Node: Pop Up Window\7f408397
+Node: Change Window\7f409899
+Node: Mule\7f412807
+Node: Mule Intro\7f414126
+Node: Language Environments\7f417956
+Node: Input Methods\7f420217
+Node: Select Input Method\7f423934
+Node: Mule and Fonts\7f426089
+Node: Coding Systems\7f428626
+Node: Recognize Coding\7f432930
+Node: Specify Coding\7f436253
+Node: Major Modes\7f441315
+Node: Choosing Modes\7f443530
+Node: Indentation\7f445917
+Node: Indentation Commands\7f448012
+Node: Tab Stops\7f450738
+Node: Just Spaces\7f452584
+Node: Text\7f453396
+Node: Text Mode\7f455376
+Node: Nroff Mode\7f457453
+Node: TeX Mode\7f459093
+Node: TeX Editing\7f461342
+Node: TeX Print\7f464773
+Node: Outline Mode\7f467989
+Node: Outline Format\7f469467
+Node: Outline Motion\7f472264
+Node: Outline Visibility\7f473814
+Node: Words\7f476732
+Node: Sentences\7f479676
+Node: Paragraphs\7f481869
+Node: Pages\7f484154
+Node: Filling\7f486751
+Node: Auto Fill\7f487319
+Node: Fill Commands\7f489463
+Node: Fill Prefix\7f491628
+Node: Case\7f493813
+Node: Programs\7f495838
+Node: Program Modes\7f498385
+Node: Lists\7f500614
+Node: Defuns\7f506451
+Node: Grinding\7f509101
+Node: Basic Indent\7f509726
+Node: Multi-line Indent\7f511747
+Node: Lisp Indent\7f513360
+Node: C Indent\7f516807
+Node: Matching\7f522044
+Node: Comments\7f523563
+Node: Balanced Editing\7f530006
+Node: Lisp Completion\7f531020
+Node: Documentation\7f532032
+Node: Change Log\7f533268
+Node: Tags\7f535843
+Node: Tag Syntax\7f537602
+Node: Create Tags Table\7f542299
+Node: Etags Regexps\7f546357
+Node: Select Tags Table\7f551013
+Node: Find Tag\7f554783
+Node: Tags Search\7f557744
+Node: List Tags\7f561197
+Node: Fortran\7f562226
+Node: Fortran Motion\7f563299
+Node: Fortran Indent\7f564116
+Node: ForIndent Commands\7f564797
+Node: ForIndent Num\7f565942
+Node: ForIndent Conv\7f567212
+Node: ForIndent Vars\7f567985
+Node: Fortran Comments\7f569150
+Node: Fortran Columns\7f572745
+Node: Fortran Abbrev\7f574168
+Node: Asm Mode\7f575074
+Node: Running\7f575623
+Node: Compilation\7f576589
+Node: Lisp Modes\7f581436
+Node: Lisp Libraries\7f582706
+Node: Loading\7f583257
+Node: Compiling Libraries\7f587717
+Node: Mocklisp\7f590605
+Node: Lisp Eval\7f591279
+Node: Lisp Debug\7f594513
+Node: Lisp Interaction\7f599878
+Node: External Lisp\7f601230
+Node: Packages\7f603302
+Node: Package Terminology\7f604172
+Node: Installing Packages\7f605770
+Node: Automatically\7f608470
+Node: Manually\7f613151
+Node: Sumo\7f614518
+Node: Which Packages\7f615419
+Node: Removing Packages\7f616227
+Node: Building Packages\7f616911
+Node: Local.rules File\7f618019
+Node: Available Packages\7f618515
+Node: Abbrevs\7f626515
+Node: Defining Abbrevs\7f628711
+Node: Expanding Abbrevs\7f631158
+Node: Editing Abbrevs\7f633858
+Node: Saving Abbrevs\7f635731
+Node: Dynamic Abbrevs\7f637683
+Node: Picture\7f638982
+Node: Basic Picture\7f641412
+Node: Insert in Picture\7f643694
+Node: Tabs in Picture\7f645113
+Node: Rectangles in Picture\7f646631
+Node: Sending Mail\7f648536
+Node: Mail Format\7f650244
+Node: Mail Headers\7f651591
+Node: Mail Mode\7f657996
+Node: Reading Mail\7f661606
+Node: Calendar/Diary\7f663308
+Node: Calendar Motion\7f664979
+Node: Calendar Unit Motion\7f665859
+Node: Move to Beginning or End\7f668179
+Node: Specified Dates\7f669309
+Node: Scroll Calendar\7f670194
+Node: Mark and Region\7f671983
+Node: General Calendar\7f673886
+Node: LaTeX Calendar\7f675494
+Node: Holidays\7f677505
+Node: Sunrise/Sunset\7f680604
+Node: Lunar Phases\7f683640
+Node: Other Calendars\7f685022
+Node: Calendar Systems\7f686506
+Node: To Other Calendar\7f689614
+Node: From Other Calendar\7f691602
+Node: Mayan Calendar\7f693903
+Node: Diary\7f697095
+Node: Diary Commands\7f698841
+Node: Format of Diary File\7f702161
+Node: Date Formats\7f705028
+Node: Adding to Diary\7f707599
+Node: Special Diary Entries\7f709227
+Node: Calendar Customization\7f714563
+Node: Calendar Customizing\7f715422
+Node: Holiday Customizing\7f718654
+Node: Date Display Format\7f725137
+Node: Time Display Format\7f726093
+Node: Daylight Savings\7f727228
+Node: Diary Customizing\7f730413
+Node: Hebrew/Islamic Entries\7f735031
+Node: Fancy Diary Display\7f738368
+Node: Included Diary Files\7f740281
+Node: Sexp Diary Entries\7f741259
+Node: Appt Customizing\7f746346
+Node: Sorting\7f747389
+Node: Shell\7f752192
+Node: Single Shell\7f753482
+Node: Interactive Shell\7f755094
+Node: Shell Mode\7f758856
+Node: Terminal emulator\7f761344
+Node: Term Mode\7f763650
+Node: Paging in Term\7f764561
+Node: Narrowing\7f765356
+Node: Hardcopy\7f767302
+Node: Recursive Edit\7f768271
+Node: Dissociated Press\7f771255
+Node: CONX\7f773815
+Node: Amusements\7f774836
+Node: Emulation\7f775313
+Node: Customization\7f777169
+Node: Minor Modes\7f778982
+Node: Variables\7f780611
+Node: Examining\7f782564
+Node: Easy Customization\7f784025
+Node: Customization Groups\7f785073
+Node: Changing an Option\7f788012
+Node: Face Customization\7f794279
+Node: Specific Customization\7f796170
+Node: Edit Options\7f798774
+Node: Locals\7f800358
+Node: File Variables\7f803537
+Node: Keyboard Macros\7f808085
+Node: Basic Kbd Macro\7f810253
+Node: Save Kbd Macro\7f812181
+Node: Kbd Macro Query\7f813836
+Node: Key Bindings\7f815775
+Node: Keymaps\7f816646
+Node: Rebinding\7f820499
+Node: Interactive Rebinding\7f821196
+Node: Programmatic Rebinding\7f823385
+Node: Key Bindings Using Strings\7f826189
+Node: Disabling\7f827813
+Node: Syntax\7f829589
+Node: Syntax Entry\7f830467
+Node: Syntax Change\7f834635
+Node: Init File\7f836801
+Node: Init Syntax\7f838262
+Node: Init Examples\7f840610
+Node: Terminal Init\7f844797
+Node: Audible Bell\7f846531
+Node: Faces\7f849959
+Node: Frame Components\7f855959
+Node: X Resources\7f856401
+Node: Geometry Resources\7f858059
+Node: Iconic Resources\7f860504
+Node: Resource List\7f860973
+Node: Face Resources\7f867477
+Node: Widgets\7f871151
+Node: Menubar Resources\7f872087
+Node: Quitting\7f873598
+Node: Lossage\7f876576
+Node: Stuck Recursive\7f877217
+Node: Screen Garbled\7f877920
+Node: Text Garbled\7f879051
+Node: Unasked-for Search\7f879687
+Node: Emergency Escape\7f880469
+Node: Total Frustration\7f882245
+Node: Bugs\7f882873
+Node: Glossary\7f892425
+Node: Manifesto\7f924079
+Node: Key Index\7f947534
+Node: Command Index\7f973461
+Node: Variable Index\7f1016047
+Node: Concept Index\7f1032238

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

diff --git a/info/xemacs.info-1 b/info/xemacs.info-1
index b45fedf..16c530e 100644 (file)
--- a/info/xemacs.info-1
+++ b/info/xemacs.info-1
@@ -1,4 +1,4 @@
-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from

 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -35,7 +35,7 @@ File: xemacs.info,  Node: Top,  Next: License,  Up: (dir)
 The XEmacs Editor
 *****************
 
 The XEmacs Editor
 *****************
 

-   XEmacs is the extensible, customizable, self-documenting real-time
+XEmacs is the extensible, customizable, self-documenting real-time

 display editor.  This Info file describes how to edit with Emacs and
 some of how to customize it, but not how to extend it.  It corresponds
 to XEmacs version 21.0.
 display editor.  This Info file describes how to edit with Emacs and
 some of how to customize it, but not how to extend it.  It corresponds
 to XEmacs version 21.0.

@@ -182,7 +182,6 @@ Packages
 * Installing Packages:: How to install packages.
 * Building Packages::   Building packages from sources.
 * Local.rules File::    An important part of building packages.
 * Installing Packages:: How to install packages.
 * Building Packages::   Building packages from sources.
 * Local.rules File::    An important part of building packages.

-* Creating Packages::   The basics.

 * Available Packages::  A brief directory of packaged LISP.
 
 Basic Editing Commands
 * Available Packages::  A brief directory of packaged LISP.
 
 Basic Editing Commands

@@ -562,9 +561,9 @@ GNU GENERAL PUBLIC LICENSE
 Preamble
 ========
 
 Preamble
 ========
 

-   The license agreements of most software companies try to keep users
-at the mercy of those companies.  By contrast, our General Public
-License is intended to guarantee your freedom to share and change free
+The license agreements of most software companies try to keep users at
+the mercy of those companies.  By contrast, our 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.  The
 General Public License applies to the Free Software Foundation's
 software and to any other program whose authors commit to using it.
 software--to make sure the software is free for all its users.  The
 General Public License applies to the Free Software Foundation's
 software and to any other program whose authors commit to using it.

@@ -602,7 +601,6 @@ authors' reputations.
 modification follow.
 
                          TERMS AND CONDITIONS
 modification follow.
 
                          TERMS AND CONDITIONS

-

   1. This License Agreement 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
   1. This License Agreement 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

@@ -753,7 +751,7 @@ modification follow.
 Appendix: How to Apply These Terms to Your New Programs
 =======================================================
 
 Appendix: How to Apply These Terms to Your New Programs
 =======================================================
 

-   If you develop a new program, and you want it to be of the greatest
+If you develop a new program, and you want it to be of the greatest

 possible use to humanity, the best way to achieve this is to make it
 free software which everyone can redistribute and change under these
 terms.
 possible use to humanity, the best way to achieve this is to make it
 free software which everyone can redistribute and change under these
 terms.

@@ -816,8 +814,8 @@ File: xemacs.info,  Node: Distrib,  Next: Intro,  Prev: License,  Up: Top
 Distribution
 ************
 
 Distribution
 ************
 

-   XEmacs is "free"; this means that everyone is free to use it and
-free to redistribute it on a free basis.  XEmacs is not in the public
+XEmacs is "free"; this means that everyone is free to use it and free
+to redistribute it on a free basis.  XEmacs is not in the public

 domain; it is copyrighted and there are restrictions on its
 distribution, but these restrictions are designed to permit everything
 that a good cooperating citizen would want to do.  What is not allowed
 domain; it is copyrighted and there are restrictions on its
 distribution, but these restrictions are designed to permit everything
 that a good cooperating citizen would want to do.  What is not allowed

@@ -839,8 +837,8 @@ distribution for the latest known list.
 Getting Other Versions of Emacs
 ===============================
 
 Getting Other Versions of Emacs
 ===============================
 

-   The Free Software Foundation's version of Emacs (called "FSF Emacs"
-in this manual and often referred to as "GNU Emacs") is available by
+The Free Software Foundation's version of Emacs (called "FSF Emacs" in
+this manual and often referred to as "GNU Emacs") is available by

 anonymous FTP from `prep.ai.mit.edu'.
 
    Win-Emacs, an older version of XEmacs that runs on Microsoft Windows
 anonymous FTP from `prep.ai.mit.edu'.
 
    Win-Emacs, an older version of XEmacs that runs on Microsoft Windows

@@ -854,7 +852,7 @@ File: xemacs.info,  Node: Intro,  Next: Glossary,  Prev: Distrib,  Up: Top
 Introduction
 ************
 
 Introduction
 ************
 

-   You are reading about XEmacs, an incarnation of the advanced,
+You are reading about XEmacs, an incarnation of the advanced,

 self-documenting, customizable, extensible real-time display editor
 Emacs.  XEmacs provides many powerful display and user-interface
 capabilities not found in other Emacsen and is mostly upwardly
 self-documenting, customizable, extensible real-time display editor
 Emacs.  XEmacs provides many powerful display and user-interface
 capabilities not found in other Emacsen and is mostly upwardly

@@ -928,6 +926,7 @@ Window
      frames in different X windows, each with their own set of
      subwindows.
 
      frames in different X windows, each with their own set of
      subwindows.
 

+

    Each XEmacs frame displays a variety of information:
    * The biggest area usually displays the text you are editing.  It may
      consist of one window or of two or more windows if you need to
    Each XEmacs frame displays a variety of information:
    * The biggest area usually displays the text you are editing.  It may
      consist of one window or of two or more windows if you need to

@@ -994,10 +993,10 @@ File: xemacs.info,  Node: Point,  Next: Echo Area,  Prev: Frame,  Up: Frame
 Point
 =====
 
 Point
 =====
 

-   When XEmacs is running, the cursor shows the location at which
-editing commands will take effect.  This location is called "point".
-You can use keystrokes or the mouse cursor to move point through the
-text and edit the text at different places.
+When XEmacs is running, the cursor shows the location at which editing
+commands will take effect.  This location is called "point".  You can
+use keystrokes or the mouse cursor to move point through the text and
+edit the text at different places.

 
    While the cursor appears to point AT a character, you should think
 of point as BETWEEN two characters: it points BEFORE the character on
 
    While the cursor appears to point AT a character, you should think
 of point as BETWEEN two characters: it points BEFORE the character on

@@ -1036,8 +1035,8 @@ File: xemacs.info,  Node: Echo Area,  Next: Mode Line,  Prev: Point,  Up: Frame
 The Echo Area
 =============
 
 The Echo Area
 =============
 

-   The line at the bottom of the frame (below the mode line) is the
-"echo area".  XEmacs uses this area to communicate with the user:
+The line at the bottom of the frame (below the mode line) is the "echo
+area".  XEmacs uses this area to communicate with the user:

 
    *   "Echoing" means printing out the characters that the user types.
      XEmacs never echoes single-character commands.  Multi-character
 
    *   "Echoing" means printing out the characters that the user types.
      XEmacs never echoes single-character commands.  Multi-character

@@ -1075,3 +1074,5966 @@ The Echo Area
      The cursor appears after the prompt.  You can always get out of
      the minibuffer by typing `C-g'.  *Note Minibuffer::.
 
      The cursor appears after the prompt.  You can always get out of
      the minibuffer by typing `C-g'.  *Note Minibuffer::.
 

+\1f
+File: xemacs.info,  Node: Mode Line,  Next: GUI Components,  Prev: Echo Area,  Up: Frame
+
+The Mode Line
+=============
+
+Each text window's last line is a "mode line" which describes what is
+going on in that window.  When there is only one text window, the mode
+line appears right above the echo area.  The mode line is in inverse
+video if the terminal supports that, starts and ends with dashes, and
+contains text like `XEmacs: SOMETHING'.
+
+   If a mode line has something else in place of `XEmacs: SOMETHING',
+the window above it is in a special subsystem such as Dired.  The mode
+line then indicates the status of the subsystem.
+
+   Normally, the mode line has the following appearance:
+
+     --CH-XEmacs: BUF      (MAJOR MINOR)----POS------
+
+This gives information about the buffer being displayed in the window:
+the buffer's name, what major and minor modes are in use, whether the
+buffer's text has been changed, and how far down the buffer you are
+currently looking.
+
+   CH contains two stars (`**') if the text in the buffer has been
+edited (the buffer is "modified"), or two dashes (`--') if the buffer
+has not been edited.  Exception: for a read-only buffer, it is `%%'.
+
+   BUF is the name of the window's chosen "buffer".  The chosen buffer
+in the selected window (the window that the cursor is in) is also
+XEmacs's selected buffer, the buffer in which editing takes place.  When
+we speak of what some command does to "the buffer", we mean the
+currently selected buffer.  *Note Buffers::.
+
+   POS tells you whether there is additional text above the top of the
+screen or below the bottom.  If your file is small and it is completely
+visible on the screen, POS is `All'.  Otherwise, POS is `Top' if you
+are looking at the beginning of the file, `Bot' if you are looking at
+the end of the file, or `NN%', where NN is the percentage of the file
+above the top of the screen.
+
+   MAJOR is the name of the "major mode" in effect in the buffer.  At
+any time, each buffer is in one and only one major mode.  The available
+major modes include Fundamental mode (the least specialized), Text
+mode, Lisp mode, and C mode.  *Note Major Modes::, for details on how
+the modes differ and how you select one.
+
+   MINOR is a list of some of the "minor modes" that are turned on in
+the window's chosen buffer.  For example, `Fill' means that Auto Fill
+mode is on.  `Abbrev' means that Word Abbrev mode is on.  `Ovwrt' means
+that Overwrite mode is on.  *Note Minor Modes::, for more information.
+`Narrow' means that the buffer being displayed has editing restricted
+to only a portion of its text.  This is not really a minor mode, but is
+like one.  *Note Narrowing::.  `Def' means that a keyboard macro is
+being defined.  *Note Keyboard Macros::.
+
+   Some buffers display additional information after the minor modes.
+For example, Rmail buffers display the current message number and the
+total number of messages.  Compilation buffers and Shell mode display
+the status of the subprocess.
+
+   If XEmacs is currently inside a recursive editing level, square
+brackets (`[...]') appear around the parentheses that surround the
+modes.  If XEmacs is in one recursive editing level within another,
+double square brackets appear, and so on.  Since information on
+recursive editing applies to XEmacs in general and not to any one
+buffer, the square brackets appear in every mode line on the screen or
+not in any of them.  *Note Recursive Edit::.
+
+   XEmacs can optionally display the time and system load in all mode
+lines.  To enable this feature, type `M-x display-time'.  The
+information added to the mode line usually appears after the file name,
+before the mode names and their parentheses.  It looks like this:
+
+     HH:MMpm L.LL [D]
+
+(Some fields may be missing if your operating system cannot support
+them.)  HH and MM are the hour and minute, followed always by `am' or
+`pm'.  L.LL is the average number of running processes in the whole
+system recently.  D is an approximate index of the ratio of disk
+activity to CPU activity for all users.
+
+   The word `Mail' appears after the load level if there is mail for
+you that you have not read yet.
+
+   Customization note: the variable `mode-line-inverse-video' controls
+whether the mode line is displayed in inverse video (assuming the
+terminal supports it); `nil' means no inverse video.  The default is
+`t'.  For X frames, simply set the foreground and background colors
+appropriately.
+
+\1f
+File: xemacs.info,  Node: GUI Components,  Next: XEmacs under X,  Prev: Mode Line,  Up: Frame
+
+GUI Components
+==============
+
+When executed in a graphical windowing environment such as the X Window
+System or Microsoft Windows, XEmacs displays several graphical user
+interface components such as scrollbars, menubars, toolbars, and
+gutters.  By default there is a vertical scrollbar at the right of each
+frame, and at the top of the frame there is a menubar, a toolbar, and a
+gutter, in that order.  Gutters can contain any of several widgets, but
+the default configuration puts a set of "notebook tabs" which you can
+use as a shortcut for selecting any of several related buffers in a
+given frame.  Operating the GUI components is "obvious":  click on the
+menubar to pull down a menu, on a button in the toolbar to invoke a
+function, and on a tab in the gutter to switch buffers.
+
+* Menu:
+
+* Menubar Basics::      How XEmacs uses the menubar.
+* Scrollbar Basics::    How XEmacs uses scrollbars.
+* Mode Line Basics::    How XEmacs uses modelines.
+* Toolbar Basics::      How XEmacs uses toolbars.
+* Gutter Basics::       How XEmacs uses gutters.
+* Inhibiting::          What if you don't like GUI?
+* Customizing::         Position, orientation, and appearance of GUI objects.
+
+\1f
+File: xemacs.info,  Node: Menubar Basics,  Next: Scrollbar Basics,  Up: GUI Components
+
+The XEmacs Menubar
+==================
+
+The XEmacs menubar is intended to be conformant to the usual conventions
+for menubars, although conformance is not yet perfect.  The menu at the
+extreme right is the `Help' menu, which should always be available.  It
+provides access to all the XEmacs help facilities available through
+`C-h', as well as samples of various configuration files like
+`~/.Xdefaults' and `~/.emacs'.  At the extreme left is the `Files'
+menu, which provides the usual file reading, writing, and printing
+operations, as well as operations like revert buffer from most recent
+save.  The next menu from the left is the `Edit' menu, which provides
+the `Undo' operation as well as cutting and pasting, searching, and
+keyboard macro definition and execution.
+
+   XEmacs provides a very dynamic environment, and the Lisp language
+makes for highly flexible applications.  The menubar reflects this:
+many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
+determined by the current state of XEmacs, and most major modes and many
+minor modes add items to menus and even whole menus to the menubar.  In
+fact, some applications like w3.el and VM provide so many menus that
+they define a whole new menubar and add a button that allows convenient
+switching between the "XEmacs menubar" and the "application menubar".
+Such applications normally bind themselves to a particular frame, and
+this switching only takes place on frames where such an application is
+active (ie, the current window of the frame is displaying a buffer in
+the appropriate major mode).
+
+   Other menus which are typically available are the `Options',
+`Tools', `Buffers', `Apps', and `Mule' menus.  For detailed
+descriptions of these menus, *Note Pull-down Menus::.  (In 21.2
+XEmacsen, the `Mule' menu will be moved under `Options'.)
+
+\1f
+File: xemacs.info,  Node: Scrollbar Basics,  Next: Mode Line Basics,  Prev: Menubar Basics,  Up: GUI Components
+
+XEmacs Scrollbars
+=================
+
+XEmacs scrollbars provide the usual interface.  Arrow buttons at either
+end allow for line by line scrolling, including autorepeat.  Clicking in
+the scrollbar itself provides scrolling by windowsfull, depending on
+which side of the slider is clicked.  The slider itself may be dragged
+for smooth scrolling.
+
+   The position of the slider corresponds to the position of the window
+in the buffer.  In particular, the length of the slider is proportional
+to the fraction of the buffer which appears in the window.
+
+   The presence of the scrollbars is under control of the application or
+may be customized by the user.  By default a vertical scrollbar is
+present in all windows (except the minibuffer), and there is no
+horizontal scrollbar.
+
+\1f
+File: xemacs.info,  Node: Mode Line Basics,  Next: Toolbar Basics,  Prev: Scrollbar Basics,  Up: GUI Components
+
+XEmacs Mode Lines
+=================
+
+When used in a windowing system, the XEmacs modelines can be dragged
+vertically. The effect is to resize the windows above and below the
+modeline (this includes the minibuffer window).
+
+   Additionally, a modeline can be dragged horizontally, in which case
+it scrolls its own text. This behavior is not enabled by default
+because it could be considered as disturbing when dragging vertically.
+When this behavior is enabled, the modeline's text can be dragged
+either in the same direction as the mouse, or in the opposite sense,
+making the modeline act as a scrollbar for its own text.
+
+   You can select the behavior you want from the `Display' submenu of
+the `Options' menu.
+
+\1f
+File: xemacs.info,  Node: Toolbar Basics,  Next: Gutter Basics,  Prev: Mode Line Basics,  Up: GUI Components
+
+XEmacs Toolbars
+===============
+
+XEmacs has a default toolbar which provides shortcuts for some of the
+commonly used operations (such as opening files) and applications (such
+as the Info manual reader).  Operations which require arguments will pop
+up dialogs to get them.
+
+   The position of the default toolbar can be customized.  Also, several
+toolbars may be present simultaneously (in different positions).  VM,
+for example, provides an application toolbar which shortcuts for
+mail-specific operations like sending, saving, and deleting messages.
+
+\1f
+File: xemacs.info,  Node: Gutter Basics,  Next: Inhibiting,  Prev: Toolbar Basics,  Up: GUI Components
+
+XEmacs Gutters
+==============
+
+Gutters are the most flexible of the GUI components described in this
+section.  In theory, the other GUI components could be implemented by
+customizing a gutter, but in practice the other components were
+introduced earlier and have their own special implementations.  Gutters
+tend to be more transient than the other components.  Buffer tabs, for
+example, change every time the selected buffer in the frame changes.
+And for progress gauges a gutter to contain the gauge is typically
+created on the fly when needed, then destroyed when the operation whose
+staus is being displayed is completed.
+
+   Buffer tabs, having somewhat complex behavior, deserve a closer look.
+By default, a row of buffer tabs is displayed at the top of every frame.
+(The tabs could be placed in the bottom gutter, but would be oriented
+the same way and look rather odd.  The horizontal orientation makes
+putting them in a side gutter utterly impractical.)  The buffer
+displayed in the current window of a frame can be changed to a specific
+buffer by clicking [mouse-1] on the corresponding tab in the gutter.
+
+   Each tab contains the name of its buffer.  The tab for the current
+buffer in each frame is displayed in raised relief.  The list of buffers
+chosen for display in the buffer tab row is derived by filtering the
+buffer list (like the `Buffers' menu).  The list starts out with all
+existing buffers, with more recently selected buffers coming earlier in
+the list.
+
+   Then "uninteresting" buffers, like internal XEmacs buffers, the
+`*Message Log*' buffer, and so on are deleted from the list.  Next, the
+frame's selected buffer is determined.  Buffers with a different major
+mode from the selected buffer are removed from the list.  Finally, if
+the list is too long, the least recently used buffers are deleted from
+the list.  By default up to 6 most recently used buffers with the same
+mode are displayed on tabs in the gutter.
+
+   This behavior can be altered by customizing
+`buffers-tab-filter-functions'.  Setting this variable to `nil' forces
+display of all buffers, up to `buffers-tab-max-size' (also
+customizable).  More complex behavior may be available in 3rd party
+libraries.  These, and some more rarely customized options, are in the
+`buffers-tab' Customize group.
+
+\1f
+File: xemacs.info,  Node: Inhibiting,  Next: Customizing,  Prev: Gutter Basics,  Up: GUI Components
+
+Inhibiting Display of GUI Components
+====================================
+
+Use of GUI facilities is a personal thing.  Almost everyone agrees that
+drawing via keyboard-based "turtle graphics" is acceptable to hardly
+anyone if a mouse is available, but conversely emulating a keyboard with
+a screenful of buttons is a painful experience.  But between those
+extremes the complete novice will require a fair amount of time before
+toolbars and menus become dispensable, but many an "Ancien Haquer" sees
+them as a complete waste of precious frame space that could be filled
+with text.
+
+   Display of all of the GUI components created by XEmacs can be
+inhibited through the use of Customize.  Customize can be accessed
+through `Options | Customize' in the menu bar, or via `M-x customize'.
+Then navigate through the Customize tree to `Emacs | Environment'.
+Scrollbar and toolbar visibility is controlled via the `Display' group,
+options `Scrollbars visible' and  `Toolbar visible' respectively.
+Gutter visibility is controlled by group `Gutter', option `Visible'.
+
+   Or they can be controlled directly by `M-x customize-variable', by
+changing the values of the variables `menubar-visible-p',
+`scrollbars-visible-p', `toolbar-visible-p', or
+`gutter-buffers-tab-visible-p' respectively.  (The strange form of the
+last variable is due to the fact that gutters are often used to display
+transient widgets like progress gauges, which you probably don't want
+to inhibit.  It is more likely that you want to inhibit the default
+display of the buffers tab widget, which is what that variable controls.
+This interface is subject to change depending on developer experience
+and user feedback.)
+
+   Control of frame configuration can controlled automatically
+according to various parameters such as buffer or frame because these
+are "specifiers" *Note Specifiers: (lispref)Specifiers.  Using these
+features requires programming in Lisp; Customize is not yet that
+sophisticated.  Also, components that appear in various positions and
+orientations can have display suppressed according to position.  `C-h a
+visible-p' gives a list of variables which can be customized.  E.g., to
+control the visibility of specifically the left-side toolbar only,
+customize `left-toolbar-visible-p'.
+
+\1f
+File: xemacs.info,  Node: Customizing,  Prev: Inhibiting,  Up: GUI Components
+
+Changing the Position, Orientation, and Appearance of GUI Components
+====================================================================
+
+#### Not documented yet.
+
+\1f
+File: xemacs.info,  Node: XEmacs under X,  Next: XEmacs under MS Windows,  Prev: GUI Components,  Up: Frame
+
+Using XEmacs Under the X Window System
+======================================
+
+XEmacs can be used with the X Window System and a window manager like
+MWM or TWM.  In that case, the X window manager opens, closes, and
+resizes XEmacs frames.  You use the window manager's mouse gestures to
+perform the operations.  Consult your window manager guide or reference
+manual for information on manipulating X windows.
+
+   When you are working under X, each X window (that is, each XEmacs
+frame) has a menu bar for mouse-controlled operations (*note Pull-down
+Menus::).
+
+   XEmacs under X is also a multi-frame XEmacs.  You can use the New
+Frame menu item from the File menu to create a new XEmacs frame in a
+new X window from the same process.  The different frames will share the
+same buffer list, but you can look at different buffers in the different
+frames.
+
+   The function `find-file-other-frame' is just like `find-file', but
+creates a new frame to display the buffer in first.  This is normally
+bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
+does.
+
+   The function `switch-to-buffer-other-frame' is just like
+`switch-to-buffer', but creates a new frame to display the buffer in
+first.  This is normally bound to `C-x 5 b'.
+
+   You can specify a different default frame size other than the one
+provided.  Use the variable `default-frame-plist', which is a plist of
+default values for frame creation other than the first one.  These may
+be set in your init file, like this:
+
+       (setq default-frame-plist '(width 80 height 55))
+
+   This variable has replaced `default-frame-alist', which is
+considered obsolete.
+
+   For values specific to the first XEmacs frame, you must use X
+resources.  The variable `x-frame-defaults' takes an alist of default
+frame creation parameters for X window frames.  These override what is
+specified in `~/.Xdefaults' but are overridden by the arguments to the
+particular call to `x-create-frame'.
+
+   When you create a new frame, the variable `create-frame-hook' is
+called with one argument, the frame just created.
+
+   If you want to close one or more of the X windows you created using
+New Frame, use the Delete Frame menu item from the File menu.
+
+   If you are working with multiple frames, some special information
+applies:
+   * Two variables, `frame-title-format' and `frame-icon-title-format'
+     determine the title of the frame and the title of the icon that
+     results if you shrink the frame.
+
+   * The variables `auto-lower-frame' and `auto-raise-frame' position a
+     frame. If true, `auto-lower-frame' lowers a frame to the bottom
+     when it is no longer selected. If true, `auto-raise-frame' raises
+     a frame to the top when it is selected. Under X, most
+     ICCCM-compliant window managers will have options to do this for
+     you, but these variables are provided in case you are using a
+     broken window manager.
+
+   * There is a new frame/modeline format directive, %S, which expands
+     to the name of the current frame (a frame's name is distinct from
+     its title; the name is used for resource lookup, among other
+     things, and the title is simply what appears above the window.)
+
+\1f
+File: xemacs.info,  Node: XEmacs under MS Windows,  Prev: XEmacs under X,  Up: Frame
+
+Using XEmacs Under Microsoft Windows
+====================================
+
+Use of XEmacs under MS Windows is not separately documented here, but
+most operations available under the X Window System are also available
+with MS Windows.
+
+   Where possible, native MS Windows GUI components and capabilities are
+used in XEmacs.
+
+\1f
+File: xemacs.info,  Node: Keystrokes,  Next: Pull-down Menus,  Prev: Frame,  Up: Top
+
+Keystrokes, Key Sequences, and Key Bindings
+*******************************************
+
+* Menu:
+
+* Intro to Keystrokes::      Keystrokes as building blocks of key sequences.
+* Representing Keystrokes::  Using lists of modifiers and keysyms to
+                             represent keystrokes.
+* Key Sequences::            Combine key strokes into key sequences you can
+                             bind to commands.
+* String Key Sequences::     Available for upward compatibility.
+* Meta Key::                 Using <ESC> to represent <Meta>
+* Super and Hyper Keys::     Adding modifier keys on certain keyboards.
+* Character Representation:: How characters appear in Emacs buffers.
+* Commands::                 How commands are bound to key sequences.
+
+\1f
+File: xemacs.info,  Node: Intro to Keystrokes,  Next: Representing Keystrokes,  Prev: Keystrokes,  Up: Keystrokes
+
+Keystrokes as Building Blocks of Key Sequences
+==============================================
+
+Earlier versions of Emacs used only the ASCII character set, which
+defines 128 different character codes.  Some of these codes are
+assigned graphic symbols like `a' and `='; the rest are control
+characters, such as `Control-a' (also called `C-a').  `C-a' means you
+hold down the <CTRL> key and then press `a'.
+
+   Keybindings in XEmacs are not restricted to the set of keystrokes
+that can be represented in ASCII.  XEmacs can tell the difference
+between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
+
+   A keystroke is like a piano chord: you get it by simultaneously
+striking several keys.  To be more precise, a keystroke consists of a
+possibly empty set of modifiers followed by a single "keysym".  The set
+of modifiers is small; it consists of `Control', `Meta', `Super',
+`Hyper', and `Shift'.
+
+   The rest of the keys on your keyboard, along with the mouse buttons,
+make up the set of keysyms.  A keysym is usually what is printed on the
+keys on your keyboard.  Here is a table of some of the symbolic names
+for keysyms:
+`a,b,c...'
+     alphabetic keys
+
+`f1,f2...'
+     function keys
+
+`button1'
+     left mouse button
+
+`button2'
+     middle mouse button
+
+`button3'
+     right mouse button
+
+`button1up'
+     upstroke on the left mouse button
+
+`button2up'
+     upstroke on the middle mouse button
+
+`button3up'
+     upstroke on the right mouse button
+
+`return'
+     Return key
+
+   Use the variable `keyboard-translate-table' only if you are on a
+dumb tty, as it cannot handle input that cannot be represented as ASCII.
+The value of this variable is a string used as a translate table for
+keyboard input or `nil'.  Each character is looked up in this string
+and the contents used instead.  If the string is of length `n',
+character codes `N' and up are untranslated.  If you are running Emacs
+under X, you should do the translations with the `xmodmap' program
+instead.
+
+\1f
+File: xemacs.info,  Node: Representing Keystrokes,  Next: Key Sequences,  Prev: Intro to Keystrokes,  Up: Keystrokes
+
+Representing Keystrokes
+-----------------------
+
+XEmacs represents keystrokes as lists. Each list consists of an
+arbitrary combination of modifiers followed by a single keysym at the
+end of the list.  If the keysym corresponds to an ASCII character, you
+can use its character code.  (A keystroke may also be represented by an
+event object, as returned by the `read-key-sequence' function;
+non-programmers need not worry about this.)
+
+   The following table gives some examples of how to list
+representations for keystrokes.  Each list consists of sets of
+modifiers followed by keysyms:
+
+`(control a)'
+     Pressing <CTRL> and `a' simultaneously.
+
+`(control ?a)'
+     Another way of writing the keystroke `C-a'.
+
+`(control 65)'
+     Yet another way of writing the keystroke `C-a'.
+
+`(break)'
+     Pressing the <BREAK> key.
+
+`(control meta button2up)'
+     Release the middle mouse button, while pressing <CTRL> and <META>.
+     Note: As you define keystrokes, you can use the `shift' key only
+as a modifier with characters that do not have a second keysym on the
+same key, such as `backspace' and `tab'.  It is an error to define a
+keystroke using the <shift> modifier with keysyms such as `a' and `='.
+The correct forms are `A' and `+'.
+
+\1f
+File: xemacs.info,  Node: Key Sequences,  Next: String Key Sequences,  Prev: Representing Keystrokes,  Up: Keystrokes
+
+Representing Key Sequences
+--------------------------
+
+A "complete key sequence" is a sequence of keystrokes that Emacs
+understands as a unit.  Key sequences are significant because you can
+bind them to commands.  Note that not all sequences of keystrokes are
+possible key sequences.  In particular, the initial keystrokes in a key
+sequence must make up a "prefix key sequence".
+
+   Emacs represents a key sequence as a vector of keystrokes.  Thus, the
+schematic representation of a complete key sequence is as follows:
+
+       [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
+
+   Here are some examples of complete key sequences:
+
+`[(control c) (control a)]'
+     Typing `C-c' followed by `C-a'
+
+`[(control c) (control 65)]'
+     Typing `C-c' followed by `C-a'. (Using the ASCII code for the
+     character `a')
+
+`[(control c) (break)]'
+     Typing `C-c' followed by the `break' character.
+
+   A "prefix key sequence" is the beginning of a series of longer
+sequences that are valid key sequences; adding any single keystroke to
+the end of a prefix results in a valid key sequence.  For example,
+`control-x' is standardly defined as a prefix.  Thus there is a
+two-character key sequence starting with `C-x' for each valid
+keystroke, giving numerous possibilities.  Here are some samples:
+
+   * `[(control x) (c)]'
+
+   * `[(control x) (control c)]'
+
+   Adding one character to a prefix key does not have to form a complete
+key.  It could make another, longer prefix.  For example, `[(control x)
+(\4)]' is itself a prefix that leads to any number of different
+three-character keys, including `[(control x) (\4) (f)]', `[(control x)
+(\4) (b)]' and so on.  It would be possible to define one of those
+three-character sequences as a prefix, creating a series of
+four-character keys, but we did not define any of them this way.
+
+   By contrast, the two-character sequence `[(control f) (control k)]'
+is not a key, because the `(control f)' is a complete key sequence in
+itself.  You cannot give `[(control f (control k)]' an independent
+meaning as a command while `(control f)' is a complete sequence,
+because Emacs would understand <C-f C-k> as two commands.
+
+   The predefined prefix key sequences in Emacs are `(control c)',
+`(control x)', `(control h)', `[(control x) (\4)]', and `escape'.  You
+can customize Emacs and could make new prefix keys or eliminate the
+default key sequences.  *Note Key Bindings::.  For example, if you
+redefine `(control f)' as a prefix, `[(control f) (control k)]'
+automatically becomes a valid key sequence (complete, unless you define
+it as a prefix as well).  Conversely, if you remove the prefix
+definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
+`[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
+
+   Note that the above paragraphs uses \4 instead of simply 4, because
+\4 is the symbol whose name is "4", and plain 4 is the integer 4, which
+would have been interpreted as the ASCII value.  Another way of
+representing the symbol whose name is "4" is to write ?4, which would be
+interpreted as the number 52, which is the ASCII code for the character
+"4".  We could therefore actually have written 52 directly, but that is
+far less clear.
+
+\1f
+File: xemacs.info,  Node: String Key Sequences,  Next: Meta Key,  Prev: Key Sequences,  Up: Keystrokes
+
+String Key Sequences
+--------------------
+
+For backward compatibility, you may also represent a key sequence using
+strings.  For example, we have the following equivalent representations:
+
+`"\C-c\C-c"'
+     `[(control c) (control c)]'
+
+`"\e\C-c"'
+     `[(meta control c)]'
+
+\1f
+File: xemacs.info,  Node: Meta Key,  Next: Super and Hyper Keys,  Prev: String Key Sequences,  Up: Keystrokes
+
+Assignment of the <META> Key
+----------------------------
+
+Not all terminals have the complete set of modifiers.  Terminals that
+have a <Meta> key allow you to type Meta characters by just holding
+that key down.  To type `Meta-a', hold down <META> and press `a'.  On
+those terminals, the <META> key works like the <SHIFT> key.  Such a key
+is not always labeled <META>, however, as this function is often a
+special option for a key with some other primary purpose.
+
+   If there is no <META> key, you can still type Meta characters using
+two-character sequences starting with <ESC>.  To enter `M-a', you could
+type `<ESC> a'.  To enter `C-M-a', you would type `ESC C-a'.  <ESC> is
+allowed on terminals with Meta keys, too, in case you have formed a
+habit of using it.
+
+   If you are running under X and do not have a <META> key, it is
+possible to reconfigure some other key to be a <META> key.  *Note Super
+and Hyper Keys::.
+
+   Emacs believes the terminal has a <META> key if the variable
+`meta-flag' is non-`nil'.  Normally this is set automatically according
+to the termcap entry for your terminal type.  However, sometimes the
+termcap entry is wrong, and then it is useful to set this variable
+yourself.  *Note Variables::, for how to do this.
+
+   Note: If you are running under the X window system, the setting of
+the `meta-flag' variable is irrelevant.
+
+\1f
+File: xemacs.info,  Node: Super and Hyper Keys,  Next: Character Representation,  Prev: Meta Key,  Up: Keystrokes
+
+Assignment of the <SUPER> and <HYPER> Keys
+------------------------------------------
+
+Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
+keys.  Under X, you can simulate the <SUPER> or <HYPER> key if you want
+to bind keys to sequences using `super' and `hyper'.  You can use the
+`xmodmap' program to do this.
+
+   For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
+following:
+
+   Create a file called `~/.xmodmap'.  In this file, place the lines
+
+             remove Lock = Caps_Lock
+             keysym Caps_Lock = Super_L
+             add Mod2 = Super_L
+
+   The first line says that the key that is currently called `Caps_Lock'
+should no longer behave as a "lock" key.  The second line says that
+this should now be called `Super_L' instead.  The third line says that
+the key called `Super_L' should be a modifier key, which produces the
+`Mod2' modifier.
+
+   To create a <META> or <HYPER> key instead of a <SUPER> key, replace
+the word `Super' above with `Meta' or `Hyper'.
+
+   Just after you start up X, execute the command `xmodmap /.xmodmap'.
+You can add this command to the appropriate initialization file to have
+the command executed automatically.
+
+   If you have problems, see the documentation for the `xmodmap'
+program.  The X keyboard model is quite complicated, and explaining it
+is beyond the scope of this manual.  However, we reprint the following
+description from the X Protocol document for your convenience:
+
+   A list of keysyms is associated with each keycode. If that list
+(ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
+list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
+the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
+`K1 K2', then the list is treated as if it were the list ```K1 K2 K1
+K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
+of keysyms `K1 K2 K3', then the list is treated as if it were the list
+```K1 K2 K3 NoSymbol'''.
+
+   The first four elements of the list are split into two groups of
+keysyms. Group 1 contains the first and second keysyms; Group 2 contains
+third and fourth keysyms. Within each group, if the second element of
+the group is NoSymbol, then the group should be treated as if the second
+element were the same as the first element, except when the first
+element is an alphabetic keysym `K' for which both lowercase and
+uppercase forms are defined. In that case, the group should be treated
+as if the first element were the lowercase form of `K' and the second
+element were the uppercase form of `K'.
+
+   The standard rules for obtaining a keysym from a KeyPress event make
+use of only the Group 1 and Group 2 keysyms; no interpretation of other
+keysyms in the list is given here. (That is, the last four keysyms are
+unused.)
+
+   Which group to use is determined by modifier state. Switching between
+groups is controlled by the keysym named `Mode_switch'. Attach that
+keysym to some keycode and attach that keycode to any one of the
+modifiers Mod1 through Mod5. This modifier is called the "group
+modifier". For any keycode, Group 1 is used when the group modifier is
+off, and Group 2 is used when the group modifier is on.
+
+   Within a group, which keysym to use is also determined by modifier
+state. The first keysym is used when the `Shift' and `Lock' modifiers
+are off. The second keysym is used when the `Shift' modifier is on, or
+when the `Lock' modifier is on and the second keysym is uppercase
+alphabetic, or when the `Lock' modifier is on and is interpreted as
+`ShiftLock'. Otherwise, when the `Lock' modifier is on and is
+interpreted as `CapsLock', the state of the `Shift' modifier is applied
+first to select a keysym, but if that keysym is lower-case alphabetic,
+then the corresponding upper-case keysym is used instead.
+
+   In addition to the above information on keysyms, we also provide the
+following description of modifier mapping from the InterClient
+Communications Conventions Manual:
+
+   X11 supports 8 modifier bits, of which 3 are pre-assigned to
+`Shift', `Lock', and `Control'. Each modifier bit is controlled by the
+state of a set of keys, and these sets are specified in a table
+accessed by `GetModifierMapping()' and `SetModifierMapping()'.
+
+   A client needing to use one of the pre-assigned modifiers should
+assume that the modifier table has been set up correctly to control
+these modifiers. The `Lock' modifier should be interpreted as `Caps
+Lock' or `Shift Lock' according to whether the keycodes in its
+controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
+
+   Clients should determine the meaning of a modifier bit from the
+keysyms being used to control it.
+
+   A client needing to use an extra modifier, for example `Meta',
+should:
+
+  1. Scan the existing modifier mappings.
+
+       1. If it finds a modifier that contains a keycode whose set of
+          keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
+          that modifier bit.
+
+       2. If there is no existing modifier controlled by `XK_Meta_L' or
+          `XK_Meta_R', it should select an unused modifier bit (one with
+          an empty controlling set) and:
+
+  2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
+     that keycode to the set for the chosen modifier, and then:
+
+       1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
+          add that keycode to the set for the chosen modifier, and then:
+
+       2. If the controlling set is still empty, interact with the user
+          to select one or more keys to be `Meta'.
+
+  3. If there are no unused modifier bits, ask the user to take
+     corrective action.
+
+   This means that the `Mod1' modifier does not necessarily mean
+`Meta', although some applications (such as twm and emacs 18) assume
+that. Any of the five unassigned modifier bits could mean `Meta'; what
+matters is that a modifier bit is generated by a keycode which is bound
+to the keysym `Meta_L' or `Meta_R'.
+
+   Therefore, if you want to make a <META> key, the right way is to
+make the keycode in question generate both a `Meta' keysym and some
+previously-unassigned modifier bit.
+
+\1f
+File: xemacs.info,  Node: Character Representation,  Next: Commands,  Prev: Super and Hyper Keys,  Up: Keystrokes
+
+Representation of Characters
+============================
+
+This section briefly discusses how characters are represented in Emacs
+buffers.  *Note Key Sequences::, for information on representing key
+sequences to create key bindings.
+
+   ASCII graphic characters in Emacs buffers are displayed with their
+graphics.  <LFD> is the same as a newline character; it is displayed by
+starting a new line.  <TAB> is displayed by moving to the next tab stop
+column (usually every 8 spaces).  Other control characters are
+displayed as a caret (`^') followed by the non-control version of the
+character; thus, `C-a' is displayed as `^A'.  Non-ASCII characters 128
+and up are displayed with octal escape sequences; thus, character code
+243 (octal), also called `M-#' when used as an input character, is
+displayed as `\243'.
+
+   The variable `ctl-arrow' may be used to alter this behavior.  *Note
+Display Vars::.
+
+\1f
+File: xemacs.info,  Node: Commands,  Prev: Character Representation,  Up: Keystrokes
+
+Keys and Commands
+=================
+
+This manual is full of passages that tell you what particular keys do.
+But Emacs does not assign meanings to keys directly.  Instead, Emacs
+assigns meanings to "functions", and then gives keys their meanings by
+"binding" them to functions.
+
+   A function is a Lisp object that can be executed as a program.
+Usually it is a Lisp symbol that has been given a function definition;
+every symbol has a name, usually made of a few English words separated
+by dashes, such as `next-line' or `forward-word'.  It also has a
+"definition", which is a Lisp program.  Only some functions can be the
+bindings of keys; these are functions whose definitions use
+`interactive' to specify how to call them interactively.  Such
+functions are called "commands", and their names are "command names".
+More information on this subject will appear in the XEmacs Lisp
+Reference Manual.
+
+   The bindings between keys and functions are recorded in various
+tables called "keymaps".  *Note Key Bindings::, for more information on
+key sequences you can bind commands to.  *Note Keymaps::, for
+information on creating keymaps.
+
+   When we say  "`C-n' moves down vertically one line" we are glossing
+over a distinction that is irrelevant in ordinary use but is vital in
+understanding how to customize Emacs.  The function `next-line' is
+programmed to move down vertically.  `C-n' has this effect because it
+is bound to that function.  If you rebind `C-n' to the function
+`forward-word' then `C-n' will move forward by words instead.
+Rebinding keys is a common method of customization.
+
+   The rest of this manual usually ignores this subtlety to keep things
+simple.  To give the customizer the information needed, we often state
+the name of the command that really does the work in parentheses after
+mentioning the key that runs it.  For example, we will say that "The
+command `C-n' (`next-line') moves point vertically down," meaning that
+`next-line' is a command that moves vertically down and `C-n' is a key
+that is standardly bound to it.
+
+   While we are on the subject of information for customization only,
+it's a good time to tell you about "variables".  Often the description
+of a command will say, "To change this, set the variable `mumble-foo'."
+A variable is a name used to remember a value.  Most of the variables
+documented in this manual exist just to facilitate customization: some
+command or other part of Emacs uses the variable and behaves
+differently depending on its setting.  Until you are interested in
+customizing, you can ignore the information about variables.  When you
+are ready to be interested, read the basic information on variables, and
+then the information on individual variables will make sense.  *Note
+Variables::.
+
+\1f
+File: xemacs.info,  Node: Pull-down Menus,  Next: Entering Emacs,  Prev: Keystrokes,  Up: Top
+
+XEmacs Pull-down Menus
+======================
+
+If you are running XEmacs under X, a menu bar on top of the Emacs frame
+provides access to pull-down menus of file, edit, and help-related
+commands. The menus provide convenient shortcuts and an easy interface
+for novice users.  They do not provide additions to the functionality
+available via key commands; you can still invoke commands from the
+keyboard as in previous versions of Emacs.
+
+File
+     Perform file and buffer-related operations, such as opening and
+     closing files, saving and printing buffers, as well as exiting
+     Emacs.
+
+Edit
+     Perform standard editing operations, such as cutting, copying,
+     pasting, and killing selected text.
+
+Apps
+     Access to sub-applications implemented within XEmacs, such as the
+     mail reader, the World Wide Web browser, the spell-checker, and
+     the calendar program.
+
+Options
+     Control various options regarding the way XEmacs works, such as
+     controlling which elements of the frame are visible, selecting the
+     fonts to be used for text, specifying whether searches are
+     case-sensitive, etc.
+
+Buffers
+     Present a menu of buffers for selection as well as the option to
+     display a buffer list.
+
+Tools
+     Perform various actions designed to automate software development
+     and similar technical work, such as searching through many files,
+     compiling a program, and comparing or merging two or three files.
+
+Help
+     Access to Emacs Info.
+
+   There are two ways of selecting an item from a pull-down menu:
+
+   * Select an item in the menu bar by moving the cursor over it and
+     click the left mouse-button.  Then move the cursor over the menu
+     item you want to choose and click left again.
+
+   * Select an item in the menu bar by moving the cursor over it and
+     click and hold the left mouse-button.  With the mouse-button
+     depressed, move the cursor over the menu item you want, then
+     release it to make your selection.
+
+   If a command in the pull-down menu is not applicable in a given
+situation, the command is disabled and its name appears faded.  You
+cannot invoke items that are faded.  For example, many commands on the
+Edit menu appear faded until you select text on which they are to
+operate; after you select a block of text, edit commands are enabled.
+*Note Mouse Selection::, for information on using the mouse to select
+text.  *Note Using X Selections::, for related information.
+
+   There are also `M-x' equivalents for each menu item.  To find the
+equivalent for any left-button menu item, do the following:
+
+  1. Type `C-h k' to get the `Describe Key' prompt.
+
+  2. Select the menu item and click.
+
+   Emacs displays the function associated with the menu item in a
+separate window, usually together with some documentation.
+
+* Menu:
+
+* File Menu::           Items on the File menu.
+* Edit Menu::           Items on the Edit menu.
+* Apps Menu::          Items on the Apps menu.
+* Options Menu::        Items on the Options menu.
+* Buffers Menu::        Information about the Buffers menu.
+* Tools Menu::         Items on the Tools menu.
+* Help Menu::           Items on the Help menu.
+* Menu Customization::  Adding and removing menu items and related
+                        operations.
+
+\1f
+File: xemacs.info,  Node: File Menu,  Next: Edit Menu,  Up: Pull-down Menus
+
+The File Menu
+-------------
+
+The File menu bar item contains the items New Frame, Open File..., Save
+Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete Frame,
+Kill Buffer and Exit Emacs on the pull-down menu.  If you select a menu
+item, Emacs executes the equivalent command.
+
+Open File, New Frame...
+     Prompts you for a filename and loads that file into a new buffer
+     in a new Emacs frame, that is, a new X window running under the
+     same Emacs process.  You can remove the frame using the Delete
+     Frame menu item.  When you remove the last frame, you exit Emacs
+     and are prompted for confirmation.
+
+Open File...
+     Prompts you for a filename and loads that file into a new buffer.
+     Open File... is equivalent to the Emacs command `find-file' (`C-x
+     C-f').
+
+Insert File...
+     Prompts you for a filename and inserts the contents of that file
+     into the current buffer.  The file associated with the current
+     buffer is not changed by this command.  This is equivalent to the
+     Emacs command `insert-file' (`C-x i').
+
+Save Buffer
+     Writes and saves the current Emacs buffer as the latest version of
+     the current visited file.  Save Buffer is equivalent to the Emacs
+     command `save-buffer' (`C-x C-s').
+
+Save Buffer As...
+     Writes and saves the current Emacs buffer to the filename you
+     specify.  Save Buffer As... is equivalent to the Emacs command
+     `write-file' (`C-x C-w').
+
+Revert Buffer
+     Restores the last saved version of the file to the current buffer.
+     When you edit a buffer containing a text file, you must save the
+     buffer before your changes become effective.  Use Revert Buffer if
+     you do not want to keep the changes you have made in the buffer.
+     Revert Buffer is equivalent to the Emacs command `revert-file'
+     (`M-x revert-buffer').
+
+Kill Buffer
+     Kills the current buffer, prompting you first if there are unsaved
+     changes.  This is roughly equivalent to the Emacs command
+     `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
+     name of a buffer to kill.
+
+Print Buffer
+     Prints a hardcopy of the current buffer.  Equivalent to the Emacs
+     command `print-buffer' (`M-x print-buffer').
+
+New Frame
+     Creates a new Emacs frame displaying the `*scratch*' buffer.  This
+     is like the Open File, New Frame... menu item, except that it does
+     not prompt for or load a file.
+
+Delete Frame
+     Allows you to close all but one of the frames created by New Frame.
+     If you created several Emacs frames belonging to the same Emacs
+     process, you can close all but one of them.  When you attempt to
+     close the last frame, Emacs informs you that you are attempting to
+     delete the last frame.  You have to choose Exit Emacs for that.
+
+Split Frame
+     Divides the current window on the current frame into two
+     equal-sized windows, both displaying the same buffer.  Equivalent
+     to the Emacs command `split-window-vertically' (`C-x 2').
+
+Un-split (Keep This)
+     If the frame is divided into multiple windows, this removes all
+     windows other than the selected one.  Equivalent to the Emacs
+     command `delete-other-windows' (`C-x 1').
+
+Un-split (Keep Others)
+     If the frame is divided into multiple windows, this removes the
+     selected window from the frame, giving the space back to one of the
+     other windows.  Equivalent to the Emacs command `delete-window'
+     (`C-x 0').
+
+Exit Emacs
+     Shuts down (kills) the Emacs process.  Equivalent to the Emacs
+     command `save-buffers-kill-emacs' (`C-x C-c').  Before killing the
+     Emacs process, the system asks which unsaved buffers to save by
+     going through the list of all buffers in that Emacs process.
+
+\1f
+File: xemacs.info,  Node: Edit Menu,  Next: Apps Menu,  Prev: File Menu,  Up: Pull-down Menus
+
+The Edit Menu
+-------------
+
+The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and Clear
+menu items.  When you select a menu item, Emacs executes the equivalent
+command.  Most commands on the Edit menu work on a block of text, the X
+selection.  They appear faded until you select a block of text
+(activate a region) with the mouse.  *Note Using X Selections::, *note
+Killing::, and *note Yanking:: for more information.
+
+Undo
+     Undoes the previous command.  Undo is equivalent to the Emacs
+     command `undo' (`C-x u').
+
+Cut
+     Removes the selected text block from the current buffer, makes it
+     the X clipboard selection, and places it in the kill ring.  Before
+     executing this command, you have to select a region using Emacs
+     region selection commands or with the mouse.
+
+Copy
+     Makes a selected text block the X clipboard selection, and places
+     it in the kill ring.  You can select text using one of the Emacs
+     region selection commands or by selecting a text region with the
+     mouse.
+
+Paste
+     Inserts the current value of the X clipboard selection in the
+     current buffer.  Note that this is not necessarily the same as the
+     Emacs `yank' command, because the Emacs kill ring and the X
+     clipboard selection are not the same thing.  You can paste in text
+     you have placed in the clipboard using Copy or Cut.  You can also
+     use Paste to insert text that was pasted into the clipboard from
+     other applications.
+
+Clear
+     Removes the selected text block from the current buffer but does
+     not place it in the kill ring or the X clipboard selection.
+
+Start Macro Recording
+     After selecting this, Emacs will remember every keystroke you type
+     until End Macro Recording is selected.  This is the same as the
+     Emacs command `start-kbd-macro' (`C-x (').
+
+End Macro Recording
+     Selecting this tells emacs to stop remembering your keystrokes.
+     This is the same as the Emacs command `end-kbd-macro' (`C-x )').
+
+Execute Last Macro
+     Selecting this item will cause emacs to re-interpret all of the
+     keystrokes which were saved between selections of the Start Macro
+     Recording and End Macro Recording menu items.  This is the same as
+     the Emacs command `call-last-kbd-macro' (`C-x e').
+
+\1f
+File: xemacs.info,  Node: Apps Menu,  Next: Options Menu,  Prev: Edit Menu,  Up: Pull-down Menus
+
+The Apps Menu
+-------------
+
+The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
+(MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
+Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
+When you select a menu item, Emacs executes the equivalent command.
+For some of the menu items, there are sub-menus which you will need to
+select.
+
+\1f
+File: xemacs.info,  Node: Options Menu,  Next: Buffers Menu,  Prev: Apps Menu,  Up: Pull-down Menus
+
+The Options Menu
+----------------
+
+The Options pull-down menu contains the Read Only, Case Sensitive
+Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
+Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
+Menu Length..., Buffers Sub-Menus and Save Options menu items.  When
+you select a menu item, Emacs executes the equivalent command.  For
+some of the menu items, there are sub-menus which you will need to
+select.
+
+Read Only
+     Selecting this item will cause the buffer to visit the file in a
+     read-only mode. Changes to the file will not be allowed. This is
+     equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
+
+Case Sensitive Search
+     Selecting this item will cause searches to be case-sensitive. If
+     its not selected then searches will ignore case. This option is
+     local to the buffer.
+
+Overstrike
+     After selecting this item, when you type letters they will replace
+     existing text on a one-to-one basis, rather than pushing it to the
+     right. At the end of a line, such characters extend the line.
+     Before a tab, such characters insert until the tab is filled in.
+     This is the same as Emacs command `quoted-insert' (`C-q').
+
+Auto Delete Selection
+     Selecting this item will cause automatic deletion of the selected
+     region. The typed text will replace the selection if the selection
+     is active (i.e. if its highlighted). If the option is not selected
+     then the typed text is just inserted at the point.
+
+Teach Extended Commands
+     After you  select this item, any time you execute a command with
+     `M-x'which has a shorter keybinding, you will be shown the
+     alternate binding before the command executes.
+
+Syntax Highlighting
+     You can customize your init file to include the font-lock mode so
+     that when you select this item, the comments will be displayed in
+     one face, strings in another, reserved words in another, and so
+     on. *Note Init File::.  When Fonts is selected, different parts of
+     the program will appear in different Fonts. When Colors is
+     selected, then the program will be displayed in different colors.
+     Selecting None causes the program to appear in just one Font and
+     Color. Selecting Less resets the Fonts and Colors to a fast,
+     minimal set of decorations. Selecting More resets the Fonts and
+     Colors to a larger set of decorations. For example, if Less is
+     selected (which is the default setting) then you might have all
+     comments in green color.  Whereas, if More is selected then a
+     function name in the comments themselves might appear in a
+     different Color or Font.
+
+Paren Highlighting
+     After selecting Blink from this item, if you place the cursor on a
+     parenthesis, the matching parenthesis will blink. If you select
+     Highlight and place the cursor on a parenthesis, the whole
+     expression of the parenthesis under the cursor will be highlighted.
+     Selecting None will turn off the options (regarding Paren
+     Highlighting) which you had selected earlier.
+
+Font
+     You can select any Font for your program by choosing from one of
+     the available Fonts.
+
+Size
+     You can select any size ranging from 2 to 24 by selecting the
+     appropriate option.
+
+Weight
+     You can choose either Bold or Medium for the weight.
+
+Buffers Menu Length...
+     Prompts you for the number of buffers to display. Then it will
+     display that number of most recently selected buffers.
+
+Buffers Sub-Menus
+     After selection of this item the Buffers menu will contain several
+     commands, as submenus of each buffer line. If this item is
+     unselected, then there are no submenus for each buffer line, the
+     only command available will be selecting that buffer.
+
+Save Options
+     Selecting this item will save the current settings of your Options
+     menu to your init file.  *Note Init File::.
+
+\1f
+File: xemacs.info,  Node: Buffers Menu,  Next: Tools Menu,  Prev: Options Menu,  Up: Pull-down Menus
+
+The Buffers Menu
+----------------
+
+The Buffers menu provides a selection of up to ten buffers and the item
+List All Buffers, which provides a Buffer List. *Note List Buffers::,
+for more information.
+
+\1f
+File: xemacs.info,  Node: Tools Menu,  Next: Help Menu,  Prev: Buffers Menu,  Up: Pull-down Menus
+
+The Tools Menu
+--------------
+
+The Tools pull-down menu contains the Grep..., Compile..., Shell
+Command..., Shell Command on Region..., Debug(GDB)...  and
+Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
+sub-menus.  When you select a menu item, Emacs executes the equivalent
+command.  For some of the menu items, there are sub-menus which you
+will need to select.
+
+\1f
+File: xemacs.info,  Node: Help Menu,  Next: Menu Customization,  Prev: Tools Menu,  Up: Pull-down Menus
+
+The Help Menu
+-------------
+
+The Help Menu gives you access to Emacs Info and provides a menu
+equivalent for each of the choices you have when using `C-h'.  *Note
+Help::, for more information.
+
+   The Help menu also gives access to UNIX online manual pages via the
+UNIX Manual Page option.
+
+\1f
+File: xemacs.info,  Node: Menu Customization,  Prev: Help Menu,  Up: Pull-down Menus
+
+Customizing XEmacs Menus
+------------------------
+
+You can customize any of the pull-down menus by adding or removing menu
+items and disabling or enabling existing menu items.
+
+   The following functions are available:
+`add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
+     Add a menu to the menu bar or one of its submenus.
+
+`add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
+     ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
+     the menu first if necessary.
+
+`delete-menu-item: (PATH)'
+     Remove the menu item defined by PATH from the menu hierarchy.
+
+`disable-menu-item: (PATH)'
+     Disable the specified menu item.
+
+`enable-menu-item: (PATH)'
+     Enable the specified previously disabled menu item.
+
+`relabel-menu-item: (PATH NEW-NAME)'
+     Change the string of the menu item specified by PATH to NEW-NAME.
+
+
+   Use the function `add-menu' to add a new menu or submenu.  If a menu
+or submenu of the given name exists already, it is changed.
+
+   MENU-PATH identifies the menu under which the new menu should be
+inserted.  It is a list of strings; for example, `("File")' names the
+top-level File menu.  `("File" "Foo")' names a hypothetical submenu of
+File.  If MENU-PATH is `nil', the menu is added to the menu bar itself.
+
+   MENU-NAME is the string naming the menu to be added.
+
+   MENU-ITEMS is a list of menu item descriptions.  Each menu item
+should be a vector of three elements:
+
+   * A string, which is the name of the menu item
+
+   * A symbol naming a command, or a form to evaluate
+
+   * `t' or `nil' to indicate whether the item is selectable
+
+   The optional argument BEFORE is the name of the menu before which
+the new menu or submenu should be added.  If the menu is already
+present, it is not moved.
+
+   The function `add-menu-item' adds a menu item to the specified menu,
+creating the menu first if necessary.  If the named item already
+exists, the menu remains unchanged.
+
+   MENU-PATH identifies the menu into which the new menu item should be
+inserted.  It is a list of strings; for example, `("File")' names the
+top-level File menu.  `("File" "Foo")' names a hypothetical submenu of
+File.
+
+   ITEM-NAME is the string naming the menu item to add.
+
+   FUNCTION is the command to invoke when this menu item is selected.
+If it is a symbol, it is invoked with `call-interactively', in the same
+way that functions bound to keys are invoked.  If it is a list, the
+list is simply evaluated.
+
+   ENABLED-P controls whether the item is selectable or not.  It should
+be `t', `nil', or a form to evaluate to decide.  This form will be
+evaluated just before the menu is displayed, and the menu item will be
+selectable if that form returns non-`nil'.
+
+   For example, to make the `rename-file' command available from the
+File menu, use the following code:
+
+     (add-menu-item '("File") "Rename File" 'rename-file t)
+
+   To add a submenu of file management commands using a File Management
+item, use the following code:
+
+     (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
+     (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
+     (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
+
+   The optional BEFORE argument is the name of a menu item before which
+the new item should be added.  If the item is already present, it is
+not moved.
+
+   To remove a specified menu item from the menu hierarchy, use
+`delete-menu-item'.
+
+   PATH is a list of strings that identify the position of the menu
+item in the menu hierarchy.  `("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.
+
+   To disable a menu item, use `disable-menu-item'.  The disabled menu
+item is grayed and can no longer be selected.  To make the item
+selectable again, use `enable-menu-item'.  `disable-menu-item' and
+`enable-menu-item' both have the argument PATH.
+
+   To change the string of the specified menu item, use
+`relabel-menu-item'. This function also takes the argument PATH.
+
+   NEW-NAME is the string to which the menu item will be changed.
+
+\1f
+File: xemacs.info,  Node: Entering Emacs,  Next: Exiting,  Prev: Pull-down Menus,  Up: Top
+
+Entering and Exiting Emacs
+**************************
+
+The usual way to invoke XEmacs is to type `xemacs <RET>' at the shell.
+XEmacs clears the screen and then displays an initial advisory message
+and copyright notice.  You can begin typing XEmacs commands immediately
+afterward.
+
+   Some operating systems insist on discarding all type-ahead when
+XEmacs starts up; they give XEmacs no way to prevent this.  Therefore,
+it is advisable to wait until XEmacs clears the screen before typing
+your first editing command.
+
+   If you run XEmacs from a shell window under the X Window System, run
+it in the background with `xemacs&'.  This way, XEmacs does not tie up
+the shell window, so you can use that to run other shell commands while
+XEmacs operates its own X windows.  You can begin typing XEmacs commands
+as soon as you direct your keyboard input to the XEmacs frame.
+
+   Before Emacs reads the first command, you have not had a chance to
+give a command to specify a file to edit.  Since Emacs must always have
+a current buffer for editing, it presents a buffer, by default, a buffer
+named `*scratch*'.  The buffer is in Lisp Interaction mode; you can use
+it to type Lisp expressions and evaluate them, or you can ignore that
+capability and simply doodle.  (You can specify a different major mode
+for this buffer by setting the variable `initial-major-mode' in your
+init file.  *Note Init File::.)
+
+   It is possible to specify files to be visited, Lisp files to be
+loaded, and functions to be called, by giving Emacs arguments in the
+shell command line.  *Note Command Switches::.  But we don't recommend
+doing this.  The feature exists mainly for compatibility with other
+editors.
+
+   Many other editors are designed to be started afresh each time you
+want to edit.  You edit one file and then exit the editor.  The next
+time you want to edit either another file or the same one, you must run
+the editor again.  With these editors, it makes sense to use a
+command-line argument to say which file to edit.
+
+   But starting a new Emacs each time you want to edit a different file
+does not make sense.  For one thing, this would be annoyingly slow.  For
+another, this would fail to take advantage of Emacs's ability to visit
+more than one file in a single editing session.  And it would lose the
+other accumulated context, such as registers, undo history, and the mark
+ring.
+
+   The recommended way to use XEmacs is to start it only once, just
+after you log in, and do all your editing in the same Emacs session.
+Each time you want to edit a different file, you visit it with the
+existing Emacs, which eventually comes to have many files in it ready
+for editing.  Usually you do not kill the Emacs until you are about to
+log out.  *Note Files::, for more information on visiting more than one
+file.
+
+\1f
+File: xemacs.info,  Node: Exiting,  Next: Command Switches,  Prev: Entering Emacs,  Up: Top
+
+Exiting Emacs
+=============
+
+There are two commands for exiting Emacs because there are two kinds of
+exiting: "suspending" Emacs and "killing" Emacs.
+
+   "Suspending" means stopping Emacs temporarily and returning control
+to its parent process (usually a shell), allowing you to resume editing
+later in the same Emacs job, with the same buffers, same kill ring,
+same undo history, and so on.  This is the usual way to exit.
+
+   "Killing" Emacs means destroying the Emacs job.  You can run Emacs
+again later, but you will get a fresh Emacs; there is no way to resume
+the same editing session after it has been killed.
+
+`C-z'
+     Suspend Emacs or iconify a frame
+     (`suspend-emacs-or-iconify-frame').  If used under the X window
+     system, shrink the X window containing the Emacs frame to an icon
+     (see below).
+
+`C-x C-c'
+     Kill Emacs (`save-buffers-kill-emacs').
+
+   If you use XEmacs under the X window system, `C-z' shrinks the X
+window containing the Emacs frame to an icon.  The Emacs process is
+stopped temporarily, and control is returned to the window manager.  If
+more than one frame is associated with the Emacs process, only the
+frame from which you used `C-z' is iconified.
+
+   To activate the "suspended" Emacs, use the appropriate window manager
+mouse gestures.  Usually left-clicking on the icon reactivates and
+reopens the X window containing the Emacs frame, but the window manager
+you use determines what exactly happens.  To actually kill the Emacs
+process, use `C-x C-c' or the Exit XEmacs item on the File menu.
+
+   To suspend Emacs, type `C-z' (`suspend-emacs').  This takes you back
+to the shell from which you invoked Emacs.  You can resume Emacs with
+the shell command `%xemacs' in most common shells.
+
+   On systems that do not support suspending programs, `C-z' starts an
+inferior shell that communicates directly with the terminal.  Emacs
+waits until you exit the subshell.  (The way to do that is probably
+with `C-d' or `exit', but it depends on which shell you use.)  The only
+way on these systems to get back to the shell from which Emacs was run
+(to log out, for example) is to kill Emacs.
+
+   Suspending also fails if you run Emacs under a shell that doesn't
+support suspending programs, even if the system itself does support it.
+In such a case, you can set the variable `cannot-suspend' to a
+non-`nil' value to force `C-z' to start an inferior shell.  (One might
+also describe Emacs's parent shell as "inferior" for failing to support
+job control properly, but that is a matter of taste.)
+
+   When Emacs communicates directly with an X server and creates its own
+dedicated X windows, `C-z' has a different meaning.  Suspending an
+applications that uses its own X windows is not meaningful or useful.
+Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
+temporarily closes up the selected Emacs frame.  The way to get back to
+a shell window is with the window manager.
+
+   To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs').  A
+two-character key is used for this to make it harder to type.  Selecting
+the Exit XEmacs option of the File menu is an alternate way of issuing
+the command.
+
+   Unless a numeric argument is used, this command first offers to save
+any modified file-visiting buffers.  If you do not save all buffers,
+you are asked for reconfirmation with `yes' before killing Emacs, since
+any changes not saved will be lost forever.  If any subprocesses are
+still running, `C-x C-c' asks you to confirm killing them, since killing
+Emacs will kill the subprocesses immediately.
+
+   There is no way to restart an Emacs session once you have killed it.
+You can, however, arrange for Emacs to record certain session
+information, such as which files are visited, when you kill it, so that
+the next time you restart Emacs it will try to visit the same files and
+so on.
+
+   The operating system usually listens for certain special characters
+whose meaning is to kill or suspend the program you are running.  This
+operating system feature is turned off while you are in Emacs.  The
+meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
+use of `C-z' and `C-c' on several operating systems as the characters
+for stopping or killing a program, but that is their only relationship
+with the operating system.  You can customize these keys to run any
+commands of your choice (*note Keymaps::).
+
+\1f
+File: xemacs.info,  Node: Command Switches,  Next: Startup Paths,  Prev: Exiting,  Up: Top
+
+Command Line Switches and Arguments
+===================================
+
+XEmacs supports command line arguments you can use to request various
+actions when invoking Emacs.  The commands are for compatibility with
+other editors and for sophisticated activities.  If you are using
+XEmacs under the X window system, you can also use a number of standard
+Xt command line arguments. Command line arguments are not usually
+needed for editing with Emacs; new users can skip this section.
+
+   Many editors are designed to be started afresh each time you want to
+edit.  You start the editor to edit one file; then exit the editor.  The
+next time you want to edit either another file or the same one, you
+start the editor again.  Under these circumstances, it makes sense to
+use a command line argument to say which file to edit.
+
+   The recommended way to use XEmacs is to start it only once, just
+after you log in, and do all your editing in the same Emacs process.
+Each time you want to edit a file, you visit it using the existing
+Emacs.  Emacs creates a new buffer for each file, and (unless you kill
+some of the buffers) Emacs eventually has many files in it ready for
+editing.  Usually you do not kill the Emacs process until you are about
+to log out.  Since you usually read files by typing commands to Emacs,
+command line arguments for specifying a file when Emacs is started are
+seldom needed.
+
+   Emacs accepts command-line arguments that specify files to visit,
+functions to call, and other activities and operating modes.  If you
+are running XEmacs under the X window system, a number of standard Xt
+command line arguments are available, as well as a few X parameters
+that are XEmacs-specific.
+
+   Options with long names with a single initial hyphen are also
+recognized with the GNU double initial hyphen syntax.  (The reverse is
+not true.)
+
+   The following subsections list:
+   * Command line arguments that you can always use
+
+   * Command line arguments that have to appear at the beginning of the
+     argument list
+
+   * Command line arguments that are only relevant if you are running
+     XEmacs under X
+
+Command Line Arguments for Any Position
+---------------------------------------
+
+Command line arguments are processed in the order they appear on the
+command line; however, certain arguments (the ones in the second table)
+must be at the front of the list if they are used.
+
+   Here are the arguments allowed:
+
+`FILE'
+     Visit FILE using `find-file'.  *Note Visiting::.
+
+`+LINENUM FILE'
+     Visit FILE using `find-file', then go to line number LINENUM in it.
+
+`-load FILE'
+`-l FILE'
+     Load a file FILE of Lisp code with the function `load'.  *Note
+     Lisp Libraries::.
+
+`-funcall FUNCTION'
+`-f FUNCTION'
+     Call Lisp function FUNCTION with no arguments.
+
+`-eval FUNCTION'
+     Interpret the next argument as a Lisp expression, and evaluate it.
+     You must be very careful of the shell quoting here.
+
+`-insert FILE'
+`-i FILE'
+     Insert the contents of FILE into the current buffer.  This is like
+     what `M-x insert-buffer' does; *Note Misc File Ops::.
+
+`-kill'
+     Exit from Emacs without asking for confirmation.  Always the last
+     argument processed, no matter where it appears in the command line.
+
+`-version'
+`-V'
+     Prints version information.  This implies `-batch'.
+
+          % xemacs -version
+          XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
+
+`-help'
+     Prints a summary of command-line options and then exits.
+
+Command Line Arguments (Beginning of Line Only)
+-----------------------------------------------
+
+The following arguments are recognized only at the beginning of the
+command line.  If more than one of them appears, they must appear in the
+order in which they appear in this table.
+
+`--show-dump-id'
+`-sd'
+     Print the ID for the new portable dumper's dump file on the
+     terminal and exit.  (Prints an error message and exits if XEmacs
+     was not configured `--pdump'.)
+
+`--no-dump-file'
+`-nd'
+     Don't load the dump file.  Roughly equivalent to old temacs.
+     (Ignored if XEmacs was not configured `--pdump'.)
+
+`--terminal FILE'
+`-t FILE'
+     Use FILE instead of the terminal for input and output.  This
+     implies the `-nw' option, documented below.
+
+`-batch'
+     Run Emacs in "batch mode", which means that the text being edited
+     is not displayed and the standard Unix interrupt characters such as
+     `C-z' and `C-c' continue to have their normal effect.  Emacs in
+     batch mode outputs to `stderr' only what would normally be printed
+     in the echo area under program control.
+
+     Batch mode is used for running programs written in Emacs Lisp from
+     shell scripts, makefiles, and so on.  Normally the `-l' switch or
+     `-f' switch will be used as well, to invoke a Lisp program to do
+     the batch processing.
+
+     `-batch' implies `-q' (do not load an init file).  It also causes
+     Emacs to kill itself after all command switches have been
+     processed.  In addition, auto-saving is not done except in buffers
+     for which it has been explicitly requested.
+
+`--no-windows'
+`-nw'
+     Start up XEmacs in TTY mode (using the TTY XEmacs was started
+     from), rather than trying to connect to an X display.  Note that
+     this happens automatically if the `DISPLAY' environment variable
+     is not set.
+
+`-debug-init'
+     Enter the debugger if an error in the init file occurs.
+
+`-debug-paths'
+     Displays information on how XEmacs constructs the various paths
+     into its hierarchy on startup.  (See also *note Startup Paths::.)
+
+`-unmapped'
+     Do not map the initial frame.  This is useful if you want to start
+     up XEmacs as a server (e.g. for gnuserv screens or external client
+     widgets).
+
+`-no-init-file'
+`-q'
+     Do not load your Emacs init file.  *Note Init File::.
+
+`-no-site-file'
+     Do not load the site-specific init file `lisp/site-start.el'.
+
+`-no-autoloads'
+     Do not load global symbol files (`auto-autoloads') at startup.
+     This implies `-vanilla'.
+
+`-no-early-packages'
+     Do not process early packages.  (For more information on startup
+     issues concerning the package system, *Note Startup Paths::.)
+
+`-vanilla'
+     This is equivalent to `-q -no-site-file -no-early-packages'.
+
+`-user-init-file FILE'
+     Load FILE as your Emacs init file instead of
+     `~/.xemacs/init.el'/`~/.emacs'.
+
+`-user-init-directory DIRECTORY'
+     Use DIRECTORY as the location of your early package hierarchies
+     and the various user-specific initialization files.
+
+`-user USER'
+`-u USER'
+     Equivalent to `-user-init-file ~USER/.xemacs/init.el
+     -user-init-directory ~USER/.xemacs', or `-user-init-file
+     ~USER/.emacs -user-init-directory ~USER/.xemacs', whichever init
+     file comes first.  *Note Init File::.
+
+
+   Note that the init file can get access to the command line argument
+values as the elements of a list in the variable `command-line-args'.
+(The arguments in the second table above will already have been
+processed and will not be in the list.)  The init file can override the
+normal processing of the other arguments by setting this variable.
+
+   One way to use command switches is to visit many files automatically:
+
+     xemacs *.c
+
+passes each `.c' file as a separate argument to Emacs, so that Emacs
+visits each file (*note Visiting::).
+
+   Here is an advanced example that assumes you have a Lisp program file
+called `hack-c-program.el' which, when loaded, performs some useful
+operation on the current buffer, expected to be a C program.
+
+     xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
+
+Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
+makes changes in the visited file), save `foo.c' (note that
+`save-buffer' is the function that `C-x C-s' is bound to), and then
+exit to the shell from which the command was executed.  `-batch'
+guarantees there will be no problem redirecting output to `log',
+because Emacs will not assume that it has a display terminal to work
+with.
+
+Command Line Arguments (for XEmacs Under X)
+-------------------------------------------
+
+If you are running XEmacs under X, a number of options are available to
+control color, border, and window title and icon name:
+
+`-title TITLE'
+`-wn TITLE'
+`-T TITLE'
+     Use TITLE as the window title. This sets the `frame-title-format'
+     variable, which controls the title of the X window corresponding
+     to the selected frame.  This is the same format as
+     `mode-line-format'.
+
+`-iconname TITLE'
+`-in TITLE'
+     Use TITLE as the icon name. This sets the
+     `frame-icon-title-format' variable, which controls the title of
+     the icon corresponding to the selected frame.
+
+`-mc COLOR'
+     Use COLOR as the mouse color.
+
+`-cr COLOR'
+     Use COLOR as the text-cursor foreground color.
+
+`-private'
+     Install a private colormap for XEmacs.
+
+   In addition, XEmacs allows you to use a number of standard Xt
+command line arguments.
+
+`-background COLOR'
+`-bg COLOR'
+     Use COLOR as the background color.
+
+`-bordercolor COLOR'
+`-bd COLOR'
+     Use COLOR as the border color.
+
+`-borderwidth WIDTH'
+`-bw WIDTH'
+     Use WIDTH as the border width.
+
+`-display DISPLAY'
+`-d DISPLAY'
+     When running under the X window system, create the window
+     containing the Emacs frame on the display named DISPLAY.
+
+`-foreground COLOR'
+`-fg COLOR'
+     Use COLOR as the foreground color.
+
+`-font NAME'
+`-fn NAME'
+     Use NAME as the default font.
+
+`-geometry SPEC'
+`-geom SPEC'
+`-g SPEC'
+     Use the geometry (window size and/or position) specified by SPEC.
+
+`-iconic'
+     Start up iconified.
+
+`-rv'
+     Bring up Emacs in reverse video.
+
+`-name NAME'
+     Use the resource manager resources specified by NAME.  The default
+     is to use the name of the program (`argv[0]') as the resource
+     manager name.
+
+`-xrm'
+     Read something into the resource database for this invocation of
+     Emacs only.
+
+
+\1f
+File: xemacs.info,  Node: Startup Paths,  Next: Packages,  Prev: Command Switches,  Up: Top
+
+How XEmacs finds Directories and Files
+======================================
+
+XEmacs deals with a multitude of files during operation.  These files
+are spread over many directories, and XEmacs determines the location of
+most of these directories at startup and organizes them into various
+paths.  (A "path", for the purposes of this section, is simply a list
+of directories which XEmacs searches successively in order to locate a
+file.)
+
+XEmacs Directory Hierarchies
+----------------------------
+
+Many of the files XEmacs looks for are located within the XEmacs
+installation itself.  However, there are several views of what actually
+constitutes the "XEmacs installation": XEmacs may be run from the
+compilation directory, it may be installed into arbitrary directories,
+spread over several directories unrelated to each other.  Moreover, it
+may subsequently be moved to a different place.  (This last case is not
+as uncommon as it sounds.  Binary kits work this way.)  Consequently,
+XEmacs has quite complex procedures in place to find directories, no
+matter where they may be hidden.
+
+   XEmacs will always respect directory options passed to `configure'.
+However, if it cannot locate a directory at the configured place, it
+will initiate a search for the directory in any of a number of
+"hierarchies" rooted under a directory which XEmacs assumes contain
+parts of the XEmacs installation; it may locate several such hierarchies
+and search across them.  (Typically, there are just one or two
+hierarchies: the hierarchy where XEmacs was or will be installed, and
+the one where it is being built.)  Such a directory containing a
+hierarchy is called a "root".  Whenever this section refers to a
+directory using the shorthand `<root>', it means that XEmacs searches
+for it under all hierarchies XEmacs was able to scrounge up.  In a
+running XEmacs, the hierarchy roots are stored in the variable
+`emacs-roots'.
+
+Package Hierarchies
+-------------------
+
+Many relevant directories and files XEmacs uses are actually not part of
+the core installation.  They are part of any of the many packages
+usually installed on top of an XEmacs installation.  (*Note Packages::.)
+Hence, they play a prominent role in the various paths XEmacs sets up.
+
+   XEmacs locates packages in any of a number of package hierarchies.
+Package hierarchies fall into three groups: "early", "late", and "last",
+according to the relative location at which they show up in the various
+XEmacs paths.  Early package hierarchies are at the very front, late
+ones somewhere in the middle, and last hierarchies are (you guessed it)
+last.
+
+   By default, XEmacs expects an early package hierarchy in the
+subdirectory `.xemacs/xemacs-packages' of the user's home directory.
+
+   Moreover, XEmacs expects late hierarchies in the subdirectories
+`site-packages', `mule-packages', and `xemacs-packages' (in that order)
+of the `<root>/lib/xemacs' subdirectory of one of the installation
+hierarchies.  (If you run in-place, these are direct subdirectories of
+the build directory.)  Furthermore, XEmacs will also search these
+subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
+prefer directories found there.
+
+   By default, XEmacs does not have a pre-configured last package
+hierarchy.  Last hierarchies are primarily for using package hierarchies
+of outdated versions of XEmacs as a fallback option.  For example, it is
+possible to run XEmacs 21 with the 20.4 package hierarchy as a last
+hierarchy.
+
+   It is possible to specify at configure-time the location of the
+various package hierarchies with the `--package-path' option to
+configure.  The early, late, and last components of the package path
+are separated by double instead of single colons.  If all three
+components are present, they locate the early, late, and last package
+hierarchies respectively.  If two components are present, they locate
+the early and late hierarchies.  If only one component is present, it
+locates the late hierarchy.  At run time, the package path may also be
+specified via the `EMACSPACKAGEPATH' environment variable.
+
+   An XEmacs package is laid out just like a normal installed XEmacs
+lisp directory.  It may have `lisp', `etc', `info', and `lib-src'
+subdirectories.  XEmacs adds these at appropriate places within the
+various system-wide paths.
+
+   There may be any number of package hierarchy directories.
+
+Directories and Paths
+---------------------
+
+Here is a list of the various directories and paths XEmacs tries to
+locate during startup.  XEmacs distinguishes between directories and
+paths specific to "version", "site", and "architecture" when looking
+for them.
+
+`version-specific'
+     directories are specific to the version of XEmacs they belong to
+     and typically reside under `<root>/lib/xemacs-<VERSION>'.
+
+`site-specific'
+     directories are independent of the version of XEmacs they belong
+     to and typically reside under `<root>/lib/xemacs'
+
+`architecture-specific'
+     directories are specific both to the version of XEmacs and the
+     architecture it runs on and typically reside under
+     `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
+
+   During installation, all of these directories may also reside
+directly under `<root>', because that is where they are in the XEmacs
+tarball.
+
+   If XEmacs runs with the `-debug-paths' option (*note Command
+Switches::), it will print the values of these variables, hopefully
+aiding in debugging any problems which come up.
+
+`lisp-directory'
+     Contains the version-specific location of the Lisp files that come
+     with the core distribution of XEmacs.  XEmacs will search it
+     recursively to a depth of 1 when setting up `load-path'.
+
+`load-path'
+     Is where XEmacs searches for XEmacs Lisp files with commands like
+     `load-library'.  It contains the package lisp directories (see
+     further down) and the version-specific core Lisp directories.  If
+     the environment variable `EMACSLOADPATH' is set at startup, its
+     directories are prepended to `load-path'.
+
+`Info-directory-list'
+     Contains the location of info files.  (See *Note (info)::.)  It
+     contains the package info directories and the version-specific core
+     documentation.  Moreover, XEmacs will add `/usr/info',
+     `/usr/local/info' as well as the directories of the environment
+     variable `INFOPATH' to `Info-directory-list'.
+
+`exec-directory'
+     Is the directory of architecture-dependent files that come with
+     XEmacs, especially executable programs intended for XEmacs to
+     invoke.
+
+`exec-path'
+     Is the path for executables which XEmacs may want to start.  It
+     contains the package executable paths as well as `exec-directory',
+     and the directories of the environment variables `PATH' and
+     `EMACSPATH'.
+
+`doc-directory'
+     Is the directory containing the architecture-specific `DOC' file
+     that contains documentation for XEmacs' commands.
+
+`data-directory'
+     Is the version-specific directory that contains core data files
+     XEmacs uses.  It may be initialized from the `EMACSDATA'
+     environment variable.
+
+`data-directory-list'
+     Is the path where XEmacs looks for data files.  It contains
+     package data directories as well as `data-directory'.
+
+
+\1f
+File: xemacs.info,  Node: Basic,  Next: Undo,  Prev: Packages,  Up: Top
+
+Basic Editing Commands
+**********************
+
+We now give the basics of how to enter text, make corrections, and save
+the text in a file.  If this material is new to you, you might learn it
+more easily by running the Emacs learn-by-doing tutorial.  To use the
+tutorial, run Emacs and type `Control-h t' (`help-with-tutorial').  You
+can also use Tutorials item from the Help menu.
+
+   XEmacs comes with many translations of tutorial.  If your XEmacs is
+with MULE and you set up language environment correctly, XEmacs chooses
+right tutorial when available (*note Language Environments::).  If you
+want specific translation, give `C-h t' a prefix argument, like `C-u
+C-h t'.
+
+   To clear the screen and redisplay, type `C-l' (`recenter').
+
+* Menu:
+
+
+* Inserting Text::      Inserting text by simply typing it.
+* Moving Point::        How to move the cursor to the place where you want to
+                         change something.
+* Erasing::            Deleting and killing text.
+* Files: Basic Files.   Visiting, creating, and saving files.
+* Help: Basic Help.     Asking what a character does.
+* Blank Lines::                Commands to make or delete blank lines.
+* Continuation Lines::  Lines too wide for the screen.
+* Position Info::       What page, line, row, or column is point on?
+* Arguments::          Numeric arguments for repeating a command.
+
+\1f
+File: xemacs.info,  Node: Inserting Text,  Next: Moving Point,  Up: Basic
+
+Inserting Text
+==============
+
+To insert printing characters into the text you are editing, just type
+them.  This inserts the characters you type into the buffer at the
+cursor (that is, at "point"; *note Point::).  The cursor moves forward,
+and any text after the cursor moves forward too.  If the text in the
+buffer is `FOOBAR', with the cursor before the `B', then if you type
+`XX', you get `FOOXXBAR', with the cursor still before the `B'.
+
+   To "delete" text you have just inserted, use <BS>.  <BS> deletes the
+character _before_ the cursor (not the one that the cursor is on top of
+or under; that is the character AFTER the cursor).  The cursor and all
+characters after it move backwards.  Therefore, if you type a printing
+character and then type <BS>, they cancel out.
+
+   To end a line and start typing a new one, type <RET>.  This inserts
+a newline character in the buffer.  If point is in the middle of a
+line, <RET> splits the line.  Typing <DEL> when the cursor is at the
+beginning of a line deletes the preceding newline, thus joining the
+line with the preceding line.
+
+   Emacs can split lines automatically when they become too long, if you
+turn on a special minor mode called "Auto Fill" mode.  *Note Filling::,
+for how to use Auto Fill mode.
+
+   If you prefer to have text characters replace (overwrite) existing
+text rather than shove it to the right, you can enable Overwrite mode,
+a minor mode.  *Note Minor Modes::.
+
+   Direct insertion works for printing characters and <SPC>, but other
+characters act as editing commands and do not insert themselves.  If you
+need to insert a control character or a character whose code is above
+200 octal, you must "quote" it by typing the character `Control-q'
+(`quoted-insert') first.  (This character's name is normally written
+`C-q' for short.)  There are two ways to use `C-q':
+
+   * `C-q' followed by any non-graphic character (even `C-g') inserts
+     that character.
+
+   * `C-q' followed by a sequence of octal digits inserts the character
+     with the specified octal character code.  You can use any number of
+     octal digits; any non-digit terminates the sequence.  If the
+     terminating character is <RET>, it serves only to terminate the
+     sequence; any other non-digit is itself used as input after
+     terminating the sequence.  (The use of octal sequences is disabled
+     in ordinary non-binary Overwrite mode, to give you a convenient
+     way to insert a digit instead of overwriting with it.)
+
+A numeric argument to `C-q' specifies how many copies of the quoted
+character should be inserted (*note Arguments::).
+
+   Customization information: <DEL>, in most modes, runs the command
+`backward-or-forward-delete-char'; <RET> runs the command `newline',
+and self-inserting printing characters run the command `self-insert',
+which inserts whatever character was typed to invoke it.  Some major
+modes rebind <DEL> to other commands.
+
+\1f
+File: xemacs.info,  Node: Moving Point,  Next: Erasing,  Prev: Inserting Text,  Up: Basic
+
+Changing the Location of Point
+==============================
+
+To do more than insert characters, you have to know how to move point
+(*note Point::).  The simplest way to do this is with arrow keys, or by
+clicking the left mouse button where you want to move to.
+
+   NOTE: Many of the following commands have two versions, one that uses
+the function keys (e.g. <LEFT> or <END>) and one that doesn't.  The
+former versions may only be available on X terminals (i.e. not on
+TTY's), but the latter are available on all terminals.
+
+`C-a'
+`HOME'
+     Move to the beginning of the line (`beginning-of-line').
+
+`C-e'
+`END'
+     Move to the end of the line (`end-of-line').
+
+`C-f'
+`RIGHT'
+     Move forward one character (`forward-char').
+
+`C-b'
+`LEFT'
+     Move backward one character (`backward-char').
+
+`M-f'
+`C-RIGHT'
+     Move forward one word (`forward-word').
+
+`M-b'
+`C-LEFT'
+     Move backward one word (`backward-word').
+
+`C-n'
+`DOWN'
+     Move down one line, vertically (`next-line').  This command
+     attempts to keep the horizontal position unchanged, so if you
+     start in the middle of one line, you end in the middle of the
+     next.  When on the last line of text, `C-n' creates a new line and
+     moves onto it.
+
+`C-p'
+`UP'
+     Move up one line, vertically (`previous-line').
+
+`C-v'
+`PGDN'
+     Move down one page, vertically (`scroll-up').
+
+`M-v'
+`PGUP'
+     Move up one page, vertically (`scroll-down').
+
+`C-l'
+     Clear the frame and reprint everything (`recenter').  Text moves
+     on the frame to bring point to the center of the window.
+
+`M-r'
+     Move point to left margin, vertically centered in the window
+     (`move-to-window-line').  Text does not move on the screen.
+
+     A numeric argument says which screen line to place point on.  It
+     counts screen lines down from the top of the window (zero for the
+     top line).  A negative argument counts lines from the bottom (-1
+     for the bottom line).
+
+`C-t'
+     Transpose two characters, the ones before and after the cursor
+     (`transpose-chars').
+
+`M-<'
+`C-HOME'
+     Move to the top of the buffer (`beginning-of-buffer').  With
+     numeric argument N, move to N/10 of the way from the top.  *Note
+     Arguments::, for more information on numeric arguments.
+
+`M->'
+`C-END'
+     Move to the end of the buffer (`end-of-buffer').
+
+`M-x goto-char'
+     Read a number N and move point to buffer position N.  Position 1
+     is the beginning of the buffer.
+
+`M-g'
+     Read a number N and move point to line number N (`goto-line').
+     Line 1 is the beginning of the buffer.
+
+`M-x set-goal-column'
+     Use the current column of point as the "semi-permanent goal
+     column" for `C-n' and `C-p' (`set-goal-column').  Henceforth, those
+     commands always move to this column in each line moved into, or as
+     close as possible given the contents of the line.  This goal
+     column remains in effect until canceled.
+
+`C-u M-x set-goal-column'
+     Cancel the goal column.  Henceforth, `C-n' and `C-p' once again
+     try to avoid changing the horizontal position, as usual.
+
+   If you set the variable `track-eol' to a non-`nil' value, then `C-n'
+and `C-p' when at the end of the starting line move to the end of
+another line.  Normally, `track-eol' is `nil'.  *Note Variables::, for
+how to set variables such as `track-eol'.
+
+   Normally, `C-n' on the last line of a buffer appends a newline to
+it.  If the variable `next-line-add-newlines' is `nil', then `C-n' gets
+an error instead (like `C-p' on the first line).
+
+\1f
+File: xemacs.info,  Node: Erasing,  Next: Basic Files,  Prev: Moving Point,  Up: Basic
+
+Erasing Text
+============
+
+`<DEL>'
+     Delete the character before or after point
+     (`backward-or-forward-delete-char').  You can customize this
+     behavior by setting the variable `delete-key-deletes-forward'.
+
+`C-d'
+     Delete the character after point (`delete-char').
+
+`C-k'
+     Kill to the end of the line (`kill-line').
+
+`M-d'
+     Kill forward to the end of the next word (`kill-word').
+
+`M-<DEL>'
+     Kill back to the beginning of the previous word
+     (`backward-kill-word').
+
+   You already know about the <DEL> key which deletes the character
+before point (that is, before the cursor).  Another key, `Control-d'
+(`C-d' for short), deletes the character after point (that is, the
+character that the cursor is on).  This shifts the rest of the text on
+the line to the left.  If you type `C-d' at the end of a line, it joins
+together that line and the next line.
+
+   To erase a larger amount of text, use the `C-k' key, which kills a
+line at a time.  If you type `C-k' at the beginning or middle of a
+line, it kills all the text up to the end of the line.  If you type
+`C-k' at the end of a line, it joins that line and the next line.
+
+   *Note Killing::, for more flexible ways of killing text.
+
+\1f
+File: xemacs.info,  Node: Basic Files,  Next: Basic Help,  Prev: Erasing,  Up: Basic
+
+Files
+=====
+
+The commands described above are sufficient for creating and altering
+text in an Emacs buffer; the more advanced Emacs commands just make
+things easier.  But to keep any text permanently you must put it in a
+"file".  Files are named units of text which are stored by the
+operating system for you to retrieve later by name.  To look at or use
+the contents of a file in any way, including editing the file with
+Emacs, you must specify the file name.
+
+   Consider a file named `/usr/rms/foo.c'.  To begin editing this file
+from Emacs, type:
+
+     C-x C-f /usr/rms/foo.c <RET>
+
+Here the file name is given as an "argument" to the command `C-x C-f'
+(`find-file').  That command uses the "minibuffer" to read the
+argument, and you type <RET> to terminate the argument (*note
+Minibuffer::).
+
+   You can also use the Open... menu item from the File menu, then type
+the name of the file to the prompt.
+
+   Emacs obeys the command by "visiting" the file: creating a buffer,
+copying the contents of the file into the buffer, and then displaying
+the buffer for you to edit.  If you alter the text, you can "save" the
+new text in the file by typing `C-x C-s' (`save-buffer') or choosing
+Save Buffer from the File menu.  This makes the changes permanent by
+copying the altered buffer contents back into the file
+`/usr/rms/foo.c'.  Until you save, the changes exist only inside Emacs,
+and the file `foo.c' is unaltered.
+
+   To create a file, visit the file with `C-x C-f' as if it already
+existed or choose Open... from the File menu and provide the name for
+the new file.  Emacs will create an empty buffer in which you can
+insert the text you want to put in the file.  When you save the buffer
+with `C-x C-s', or by choosing Save Buffer from the File menu, the file
+is created.
+
+   To learn more about using files, *Note Files::.
+
+\1f
+File: xemacs.info,  Node: Basic Help,  Next: Blank Lines,  Prev: Basic Files,  Up: Basic
+
+Help
+====
+
+If you forget what a key does, you can find out with the Help
+character, which is `C-h' (or <F1>, which is an alias for `C-h').  Type
+`C-h k' followed by the key you want to know about; for example, `C-h k
+C-n' tells you all about what `C-n' does.  `C-h' is a prefix key; `C-h
+k' is just one of its subcommands (the command `describe-key').  The
+other subcommands of `C-h' provide different kinds of help.  Type `C-h'
+twice to get a description of all the help facilities.  *Note Help::.
+
+\1f
+File: xemacs.info,  Node: Blank Lines,  Next: Continuation Lines,  Prev: Basic Help,  Up: Basic
+
+Blank Lines
+===========
+
+Here are special commands and techniques for putting in and taking out
+blank lines.
+
+`C-o'
+     Insert one or more blank lines after the cursor (`open-line').
+
+`C-x C-o'
+     Delete all but one of many consecutive blank lines
+     (`delete-blank-lines').
+
+   When you want to insert a new line of text before an existing line,
+you can do it by typing the new line of text, followed by <RET>.
+However, it may be easier to see what you are doing if you first make a
+blank line and then insert the desired text into it.  This is easy to do
+using the key `C-o' (`open-line'), which inserts a newline after point
+but leaves point in front of the newline.  After `C-o', type the text
+for the new line.  `C-o F O O' has the same effect as `F O O <RET>',
+except for the final location of point.
+
+   You can make several blank lines by typing `C-o' several times, or
+by giving it a numeric argument to tell it how many blank lines to make.
+*Note Arguments::, for how.  If you have a fill prefix, then `C-o'
+command inserts the fill prefix on the new line, when you use it at the
+beginning of a line.  *Note Fill Prefix::.
+
+   The easy way to get rid of extra blank lines is with the command
+`C-x C-o' (`delete-blank-lines').  `C-x C-o' in a run of several blank
+lines deletes all but one of them.  `C-x C-o' on a solitary blank line
+deletes that blank line.  When point is on a nonblank line, `C-x C-o'
+deletes any blank lines following that nonblank line.
+
+\1f
+File: xemacs.info,  Node: Continuation Lines,  Next: Position Info,  Prev: Blank Lines,  Up: Basic
+
+Continuation Lines
+==================
+
+If you add too many characters to one line without breaking it with
+<RET>, the line will grow to occupy two (or more) lines on the screen,
+with a curved arrow at the extreme right margin of all but the last of
+them.  The curved arrow says that the following screen line is not
+really a distinct line in the text, but just the "continuation" of a
+line too long to fit the screen.  Continuation is also called "line
+wrapping".
+
+   Sometimes it is nice to have Emacs insert newlines automatically when
+a line gets too long.  Continuation on the screen does not do that.  Use
+Auto Fill mode (*note Filling::) if that's what you want.
+
+   Instead of continuation, long lines can be displayed by "truncation".
+This means that all the characters that do not fit in the width of the
+frame or window do not appear at all.  They remain in the buffer,
+temporarily invisible.  Right arrow in the last column (instead of the
+curved arrow) inform you that truncation is in effect.
+
+   Truncation instead of continuation happens whenever horizontal
+scrolling is in use, and optionally in all side-by-side windows (*note
+Windows::).  You can enable truncation for a particular buffer by
+setting the variable `truncate-lines' to non-`nil' in that buffer.
+(*Note Variables::.)  Altering the value of `truncate-lines' makes it
+local to the current buffer; until that time, the default value is in
+effect.  The default is initially `nil'.  *Note Locals::.
+
+   *Note Display Vars::, for additional variables that affect how text
+is displayed.
+
+\1f
+File: xemacs.info,  Node: Position Info,  Next: Arguments,  Prev: Continuation Lines,  Up: Basic
+
+Cursor Position Information
+===========================
+
+If you are accustomed to other display editors, you may be surprised
+that Emacs does not always display the page number or line number of
+point in the mode line.  In Emacs, this information is only rarely
+needed, and a number of commands are available to compute and print it.
+Since text is stored in a way that makes it difficult to compute the
+information, it is not displayed all the time.
+
+`M-x what-page'
+     Print page number of point, and line number within page.
+
+`M-x what-line'
+     Print line number of point in the buffer.
+
+`M-x line-number-mode'
+     Toggle automatic display of current line number.
+
+`M-='
+     Print number of lines and characters in the current region
+     (`count-lines-region').  *Note Mark::, for information about the
+     region.
+
+`C-x ='
+     Print character code of character after point, character position
+     of point, and column of point (`what-cursor-position').
+
+   There are several commands for printing line numbers:
+
+   * `M-x what-line' counts lines from the beginning of the file and
+     prints the line number point is on.  The first line of the file is
+     line number 1.  You can use these numbers as arguments to `M-x
+     goto-line'.
+
+   * `M-x what-page' counts pages from the beginning of the file, and
+     counts lines within the page, printing both of them.  *Note
+     Pages::, for the command `C-x l', which counts the lines in the
+     current page.
+
+   * `M-=' (`count-lines-region') prints the number of lines in the
+     region (*note Mark::).  *Note Pages::, for the command `C-x l'
+     which counts the lines in the
+
+   The command `C-x =' (`what-cursor-position') can be used to find out
+the column that the cursor is in, and other miscellaneous information
+about point.  It prints a line in the echo area that looks like this:
+
+     Char: c (0143, 99, 0x63)  point=18862 of 24800(76%)  column 53
+
+(In fact, this is the output produced when point is before `column 53'
+in the example.)
+
+   The four values after `Char:' describe the character that follows
+point, first by showing it and then by giving its character code in
+octal, decimal and hex.
+
+   `point=' is followed by the position of point expressed as a
+character count.  The front of the buffer counts as position 1, one
+character later as 2, and so on.  The next, larger number is the total
+number of characters in the buffer.  Afterward in parentheses comes the
+position expressed as a percentage of the total size.
+
+   `column' is followed by the horizontal position of point, in columns
+from the left edge of the window.
+
+   If the buffer has been narrowed, making some of the text at the
+beginning and the end temporarily invisible, `C-x =' prints additional
+text describing the current visible range.  For example, it might say:
+
+     Char: c (0143, 99, 0x63)  point=19674 of 24575(80%) <19591 - 19703>  column 69
+
+where the two extra numbers give the smallest and largest character
+position that point is allowed to assume.  The characters between those
+two positions are the visible ones.  *Note Narrowing::.
+
+   If point is at the end of the buffer (or the end of the visible
+part), `C-x =' omits any description of the character after point.  The
+output looks like
+
+     point=563026 of 563025(100%)  column 0
+
+\1f
+File: xemacs.info,  Node: Arguments,  Prev: Position Info,  Up: Basic
+
+Numeric Arguments
+=================
+
+In mathematics and computer usage, the word "argument" means "data
+provided to a function or operation."  Any Emacs command can be given a
+"numeric argument" (also called a "prefix argument").  Some commands
+interpret the argument as a repetition count.  For example, giving an
+argument of ten to the key `C-f' (the command `forward-char', move
+forward one character) moves forward ten characters.  With these
+commands, no argument is equivalent to an argument of one.  Negative
+arguments are allowed.  Often they tell a command to move or act  in
+the opposite direction.
+
+   If your keyboard has a <META> key (labelled with a diamond on
+Sun-type keyboards and labelled `Alt' on some other keyboards), the
+easiest way to specify a numeric argument is to type digits and/or a
+minus sign while holding down the <META> key.  For example,
+     M-5 C-n
+
+would move down five lines.  The characters `Meta-1', `Meta-2', and so
+on, as well as `Meta--', do this because they are keys bound to
+commands (`digit-argument' and `negative-argument') that are defined to
+contribute to an argument for the next command.  Digits and `-'
+modified with Control, or Control and Meta, also specify numeric
+arguments.
+
+   Another way of specifying an argument is to use the `C-u'
+(`universal-argument') command followed by the digits of the argument.
+With `C-u', you can type the argument digits without holding down
+modifier keys; `C-u' works on all terminals.  To type a negative
+argument, type a minus sign after `C-u'.  Just a minus sign without
+digits normally means -1.
+
+   `C-u' followed by a character which is neither a digit nor a minus
+sign has the special meaning of "multiply by four".  It multiplies the
+argument for the next command by four.  `C-u' twice multiplies it by
+sixteen.  Thus, `C-u C-u C-f' moves forward sixteen characters.  This
+is a good way to move forward "fast", since it moves about 1/5 of a line
+in the usual size frame.  Other useful combinations are `C-u C-n', `C-u
+C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a
+lot" of blank lines), and `C-u C-k' (kill four lines).
+
+   Some commands care only about whether there is an argument and not
+about its value.  For example, the command `M-q' (`fill-paragraph') with
+no argument fills text; with an argument, it justifies the text as well.
+(*Note Filling::, for more information on `M-q'.)  Just `C-u' is a
+handy way of providing an argument for such commands.
+
+   Some commands use the value of the argument as a repeat count, but do
+something peculiar when there is no argument.  For example, the command
+`C-k' (`kill-line') with argument N kills N lines, including their
+terminating newlines.  But `C-k' with no argument is special: it kills
+the text up to the next newline, or, if point is right at the end of
+the line, it kills the newline itself.  Thus, two `C-k' commands with
+no arguments can kill a non-blank line, just like `C-k' with an
+argument of one.  (*Note Killing::, for more information on `C-k'.)
+
+   A few commands treat a plain `C-u' differently from an ordinary
+argument.  A few others may treat an argument of just a minus sign
+differently from an argument of -1.  These unusual cases are described
+when they come up; they are always for reasons of convenience of use of
+the individual command.
+
+   You can use a numeric argument to insert multiple copies of a
+character.  This is straightforward unless the character is a digit; for
+example, `C-u 6 4 a' inserts 64 copies of the character `a'.  But this
+does not work for inserting digits; `C-u 6 4 1' specifies an argument
+of 641, rather than inserting anything.  To separate the digit to
+insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
+1' does insert 64 copies of the character `1'.
+
+   We use the term "prefix argument" as well as "numeric argument" to
+emphasize that you type the argument before the command, and to
+distinguish these arguments from minibuffer arguments that come after
+the command.
+
+\1f
+File: xemacs.info,  Node: Undo,  Next: Minibuffer,  Prev: Basic,  Up: Top
+
+Undoing Changes
+***************
+
+Emacs allows you to undo all changes you make to the text of a buffer,
+up to a certain amount of change (8000 characters).  Each buffer records
+changes individually, and the undo command always applies to the
+current buffer.  Usually each editing command makes a separate entry in
+the undo records, but some commands such as `query-replace' make many
+entries, and very simple commands such as self-inserting characters are
+often grouped to make undoing less tedious.
+
+`C-x u'
+     Undo one batch of changes (usually, one command's worth) (`undo').
+
+`C-_'
+     The same.
+
+   The command `C-x u' or `C-_' allows you to undo changes.  The first
+time you give this command, it undoes the last change.  Point moves to
+the text affected by the undo, so you can see what was undone.
+
+   Consecutive repetitions of the `C-_' or `C-x u' commands undo
+earlier and earlier changes, back to the limit of what has been
+recorded.  If all recorded changes have already been undone, the undo
+command prints an error message and does nothing.
+
+   Any command other than an undo command breaks the sequence of undo
+commands.  Starting at this moment, the previous undo commands are
+considered ordinary changes that can themselves be undone.  Thus, you
+can redo changes you have undone by typing `C-f' or any other command
+that have no important effect, and then using more undo commands.
+
+   If you notice that a buffer has been modified accidentally, the
+easiest way to recover is to type `C-_' repeatedly until the stars
+disappear from the front of the mode line.  When that happens, all the
+modifications you made have been canceled.  If you do not remember
+whether you changed the buffer deliberately, type `C-_' once. When you
+see Emacs undo the last change you made, you probably remember why you
+made it.  If the change was an accident, leave it undone.  If it was
+deliberate, redo the change as described in the preceding paragraph.
+
+   Whenever an undo command makes the stars disappear from the mode
+line, the buffer contents is the same as it was when the file was last
+read in or saved.
+
+   Not all buffers record undo information.  Buffers whose names start
+with spaces don't; these buffers are used internally by Emacs and its
+extensions to hold text that users don't normally look at or edit.
+Minibuffers, help buffers, and documentation buffers also don't record
+undo information.
+
+   Emacs can remember at most 8000 or so characters of deleted or
+modified text in any one buffer for reinsertion by the undo command.
+There is also a limit on the number of individual insert, delete, or
+change actions that Emacs can remember.
+
+   There are two keys to run the `undo' command, `C-x u' and `C-_',
+because on some keyboards, it is not obvious how to type `C-_'. `C-x u'
+is an alternative you can type in the same fashion on any terminal.
+
+\1f
+File: xemacs.info,  Node: Minibuffer,  Next: M-x,  Prev: Undo,  Up: Top
+
+The Minibuffer
+**************
+
+The "minibuffer" is the facility used by XEmacs commands to read
+arguments more complicated than a single number.  Minibuffer arguments
+can be file names, buffer names, Lisp function names, XEmacs command
+names, Lisp expressions, and many other things, depending on the command
+reading the argument.  You can use the usual XEmacs editing commands in
+the minibuffer to edit the argument text.
+
+   When the minibuffer is in use, it appears in the echo area, and the
+cursor moves there.  The beginning of the minibuffer line displays a
+"prompt" which says what kind of input you should supply and how it
+will be used.  Often this prompt is derived from the name of the command
+that the argument is for.  The prompt normally ends with a colon.
+
+   Sometimes a "default argument" appears in parentheses after the
+colon; it, too, is part of the prompt.  The default is used as the
+argument value if you enter an empty argument (e.g., by just typing
+<RET>).  For example, commands that read buffer names always show a
+default, which is the name of the buffer that will be used if you type
+just <RET>.
+
+   The simplest way to enter a minibuffer argument is to type the text
+you want, terminated by <RET> which exits the minibuffer.  You can
+cancel the command that wants the argument, and get out of the
+minibuffer, by typing `C-g'.
+
+   Since the minibuffer uses the screen space of the echo area, it can
+conflict with other ways XEmacs customarily uses the echo area.  Here is
+how XEmacs handles such conflicts:
+
+   * If a command gets an error while you are in the minibuffer, this
+     does not cancel the minibuffer.  However, the echo area is needed
+     for the error message and therefore the minibuffer itself is
+     hidden for a while.  It comes back after a few seconds, or as soon
+     as you type anything.
+
+   * If in the minibuffer you use a command whose purpose is to print a
+     message in the echo area, such as `C-x =', the message is printed
+     normally, and the minibuffer is hidden for a while.  It comes back
+     after a few seconds, or as soon as you type anything.
+
+   * Echoing of keystrokes does not take place while the minibuffer is
+     in use.
+
+* Menu:
+
+* File: Minibuffer File.  Entering file names with the minibuffer.
+* Edit: Minibuffer Edit.  How to edit in the minibuffer.
+* Completion::           An abbreviation facility for minibuffer input.
+* Minibuffer History::    Reusing recent minibuffer arguments.
+* Repetition::           Re-executing commands that used the minibuffer.
+
+\1f
+File: xemacs.info,  Node: Minibuffer File,  Next: Minibuffer Edit,  Prev: Minibuffer,  Up: Minibuffer
+
+Minibuffers for File Names
+==========================
+
+Sometimes the minibuffer starts out with text in it.  For example, when
+you are supposed to give a file name, the minibuffer starts out
+containing the "default directory", which ends with a slash.  This is
+to inform you which directory the file will be found in if you do not
+specify a directory.
+
+   For example, the minibuffer might start out with these contents:
+
+     Find File: /u2/emacs/src/
+
+where `Find File: ' is the prompt.  Typing `buffer.c' specifies the
+file `/u2/emacs/src/buffer.c'.  To find files in nearby directories,
+use `..'; thus, if you type `../lisp/simple.el', you will get the file
+named `/u2/emacs/lisp/simple.el'.  Alternatively, you can kill with
+`M-<DEL>' the directory names you don't want (*note Words::).
+
+   If you don't want any of the default, you can kill it with `C-a
+C-k'.  But you don't need to kill the default; you can simply ignore it.
+Insert an absolute file name, one starting with a slash or a tilde,
+after the default directory.  For example, to specify the file
+`/etc/termcap', just insert that name, giving these minibuffer contents:
+
+     Find File: /u2/emacs/src//etc/termcap
+
+XEmacs gives a special meaning to a double slash (which is not normally
+a useful thing to write): it means, "ignore everything before the
+second slash in the pair."  Thus, `/u2/emacs/src/' is ignored in the
+example above, and you get the file `/etc/termcap'.
+
+   If you set `insert-default-directory' to `nil', the default
+directory is not inserted in the minibuffer.  This way, the minibuffer
+starts out empty.  But the name you type, if relative, is still
+interpreted with respect to the same default directory.
+
+\1f
+File: xemacs.info,  Node: Minibuffer Edit,  Next: Completion,  Prev: Minibuffer File,  Up: Minibuffer
+
+Editing in the Minibuffer
+=========================
+
+The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
+usual XEmacs commands are available for editing the text of an argument
+you are entering.
+
+   Since <RET> in the minibuffer is defined to exit the minibuffer, you
+can't use it to insert a newline in the minibuffer.  To do that, type
+`C-o' or `C-q C-j'.  (Recall that a newline is really the character
+control-J.)
+
+   The minibuffer has its own window which always has space on the
+screen but acts as if it were not there when the minibuffer is not in
+use.  When the minibuffer is in use, its window is just like the
+others; you can switch to another window with `C-x o', edit text in
+other windows and perhaps even visit more files, before returning to the
+minibuffer to submit the argument.  You can kill text in another window,
+return to the minibuffer window, and then yank the text to use it in the
+argument.  *Note Windows::.
+
+   There are some restrictions on the use of the minibuffer window,
+however.  You cannot switch buffers in it--the minibuffer and its
+window are permanently attached.  Also, you cannot split or kill the
+minibuffer window. But you can make it taller in the normal fashion with
+`C-x ^'.  If you enable Resize-Minibuffer mode, then the minibuffer
+window expands vertically as necessary to hold the text that you put in
+the minibuffer.  Use `M-x resize-minibuffer-mode' to enable or disable
+this minor mode (*note Minor Modes::).
+
+   If while in the minibuffer you issue a command that displays help
+text of any sort in another window, you can use the `C-M-v' command
+while in the minibuffer to scroll the help text.  This lasts until you
+exit the minibuffer.  This feature is especially useful if a completing
+minibuffer gives you a list of possible completions.  *Note Other
+Window::.
+
+   If the variable `minibuffer-confirm-incomplete' is `t', you are
+asked for confirmation if there is no known completion for the text you
+typed. For example, if you attempted to visit a non-existent file, the
+minibuffer might read:
+             Find File: chocolate_bar.c [no completions, confirm]
+   If you press `Return' again, that confirms the filename. Otherwise,
+you can continue editing it.
+
+   XEmacs supports recursive use of the minibuffer.  However, it is easy
+to do this by accident (because of autorepeating keyboards, for example)
+and get confused.  Therefore, most XEmacs commands that use the
+minibuffer refuse to operate if the minibuffer window is selected.  If
+the minibuffer is active but you have switched to a different window,
+recursive use of the minibuffer is allowed--if you know enough to try
+to do this, you probably will not get confused.
+
+   If you set the variable `enable-recursive-minibuffers' to a
+non-`nil', recursive use of the minibuffer is always allowed.
+
+\1f
+File: xemacs.info,  Node: Completion,  Next: Minibuffer History,  Prev: Minibuffer Edit,  Up: Minibuffer
+
+Completion
+==========
+
+For certain kinds of arguments, you can use "completion" to enter the
+argument value.  Completion means that you type part of the argument,
+then XEmacs visibly fills in the rest, or as much as can be determined
+from the part you have typed.
+
+   When completion is available, certain keys--<TAB>, <RET>, and
+<SPC>--are rebound to complete the text present in the minibuffer into
+a longer string that it stands for, by matching it against a set of
+"completion alternatives" provided by the command reading the argument.
+`?' is defined to display a list of possible completions of what you
+have inserted.
+
+   For example, when `M-x' uses the minibuffer to read the name of a
+command, it provides a list of all available XEmacs command names to
+complete against.  The completion keys match the text in the minibuffer
+against all the command names, find any additional name characters
+implied by the ones already present in the minibuffer, and add those
+characters to the ones you have given.  This is what makes it possible
+to type `M-x inse <SPC> b <RET>' instead of `M-x insert-buffer <RET>'
+(for example).
+
+   Case is normally significant in completion because it is significant
+in most of the names that you can complete (buffer names, file names and
+command names).  Thus, `fo' does not complete to `Foo'.  When you are
+completing a name in which case does not matter, case may be ignored
+for completion's sake if specified by program.
+
+   When a completion list is displayed, the completions will highlight
+as you move the mouse over them.  Clicking the middle mouse button on
+any highlighted completion will "select" it just as if you had typed it
+in and hit <RET>.
+
+* Menu:
+
+* Example: Completion Example.
+* Commands: Completion Commands.
+* Strict Completion::
+* Options: Completion Options.
+
+\1f
+File: xemacs.info,  Node: Completion Example,  Next: Completion Commands,  Prev: Completion,  Up: Completion
+
+Completion Example
+------------------
+
+A concrete example may help here.  If you type `M-x au <TAB>', the
+<TAB> looks for alternatives (in this case, command names) that start
+with `au'.  There are several, including `auto-fill-mode' and
+`auto-save-mode'--but they are all the same as far as `auto', so the
+`au' in the minibuffer changes to `auto'.
+
+   If you type <TAB> again immediately, there are multiple
+possibilities for the very next character--it could be any of `c-'--so
+no more characters are added; instead, <TAB> displays a list of all
+possible completions in another window.
+
+   If you go on to type `-f <TAB>', this <TAB> sees `auto-f'.  The only
+command name starting this way is `auto-fill-mode', so completion fills
+in the rest of that.  You now have `auto-fill-mode' in the minibuffer
+after typing just `au <TAB> f <TAB>'.  Note that <TAB> has this effect
+because in the minibuffer it is bound to the command
+`minibuffer-complete' when completion is available.
+
+\1f
+File: xemacs.info,  Node: Completion Commands,  Next: Strict Completion,  Prev: Completion Example,  Up: Completion
+
+Completion Commands
+-------------------
+
+Here is a list of the completion commands defined in the minibuffer
+when completion is available.
+
+`<TAB>'
+     Complete the text in the minibuffer as much as possible
+     (`minibuffer-complete').
+
+`<SPC>'
+     Complete the minibuffer text, but don't go beyond one word
+     (`minibuffer-complete-word').
+
+`<RET>'
+     Submit the text in the minibuffer as the argument, possibly
+     completing first as described below
+     (`minibuffer-complete-and-exit').
+
+`?'
+     Print a list of all possible completions of the text in the
+     minibuffer (`minibuffer-list-completions').
+
+`<button2>'
+     Select the highlighted text under the mouse as a minibuffer
+     response.  When the minibuffer is being used to prompt the user
+     for a completion, any valid completions which are visible on the
+     screen will be highlighted when the mouse moves over them.
+     Clicking <button2> will select the highlighted completion and exit
+     the minibuffer.  (`minibuf-select-highlighted-completion').
+
+   <SPC> completes much like <TAB>, but never goes beyond the next
+hyphen or space.  If you have `auto-f' in the minibuffer and type
+<SPC>, it finds that the completion is `auto-fill-mode', but it stops
+completing after `fill-'.  This gives `auto-fill-'.  Another <SPC> at
+this point completes all the way to `auto-fill-mode'.  <SPC> in the
+minibuffer when completion is available runs the command
+`minibuffer-complete-word'.
+
+   Here are some commands you can use to choose a completion from a
+window that displays a list of completions:
+
+`button2up'
+     Clicking mouse button 2 on a completion in the list of possible
+     completions chooses that completion (`mouse-choose-completion').
+     You normally use this command while point is in the minibuffer;
+     but you must click in the list of completions, not in the
+     minibuffer itself.
+
+`<PRIOR>'
+`M-v'
+     Typing <PRIOR> or `M-v', while in the minibuffer, selects the
+     window showing the completion list buffer
+     (`switch-to-completions').  This paves the way for using the
+     commands below.  (Selecting that window in the usual ways has the
+     same effect, but this way is more convenient.)
+
+`<RET>'
+     Typing <RET> _in the completion list buffer_ chooses the
+     completion that point is in or next to (`choose-completion').  To
+     use this command, you must first switch windows to the window that
+     shows the list of completions.
+
+`<RIGHT>'
+`<TAB>'
+`C-f'
+     Typing the right-arrow key <RIGHT>, <TAB> or `C-f' _in the
+     completion list buffer_ moves point to the following completion
+     (`next-list-mode-item').
+
+`<LEFT>'
+`C-b'
+     Typing the left-arrow key <LEFT> or `C-b' _in the completion list
+     buffer_ moves point toward the beginning of the buffer, to the
+     previous completion (`previous-list-mode-item').
+
+\1f
+File: xemacs.info,  Node: Strict Completion,  Next: Completion Options,  Prev: Completion Commands,  Up: Completion
+
+Strict Completion
+-----------------
+
+There are three different ways that <RET> can work in completing
+minibuffers, depending on how the argument will be used.
+
+   * "Strict" completion is used when it is meaningless to give any
+     argument except one of the known alternatives.  For example, when
+     `C-x k' reads the name of a buffer to kill, it is meaningless to
+     give anything but the name of an existing buffer.  In strict
+     completion, <RET> refuses to exit if the text in the minibuffer
+     does not complete to an exact match.
+
+   * "Cautious" completion is similar to strict completion, except that
+     <RET> exits only if the text was an exact match already, not
+     needing completion.  If the text is not an exact match, <RET> does
+     not exit, but it does complete the text.  If it completes to an
+     exact match, a second <RET> will exit.
+
+     Cautious completion is used for reading file names for files that
+     must already exist.
+
+   * "Permissive" completion is used when any string whatever is
+     meaningful, and the list of completion alternatives is just a
+     guide.  For example, when `C-x C-f' reads the name of a file to
+     visit, any file name is allowed, in case you want to create a
+     file.  In permissive completion, <RET> takes the text in the
+     minibuffer exactly as given, without completing it.
+
+   The completion commands display a list of all possible completions in
+a window whenever there is more than one possibility for the very next
+character.  Also, typing `?' explicitly requests such a list.  If the
+list of completions is long, you can scroll it with `C-M-v' (*note
+Other Window::).
+
+\1f
+File: xemacs.info,  Node: Completion Options,  Prev: Strict Completion,  Up: Completion
+
+Completion Options
+------------------
+
+When completion is done on file names, certain file names are usually
+ignored.  The variable `completion-ignored-extensions' contains a list
+of strings; a file whose name ends in any of those strings is ignored
+as a possible completion.  The standard value of this variable has
+several elements including `".o"', `".elc"', `".dvi"' and `"~"'.  The
+effect is that, for example, `foo' can complete to `foo.c' even though
+`foo.o' exists as well.  However, if _all_ the possible completions end
+in "ignored" strings, then they are not ignored.  Ignored extensions do
+not apply to lists of completions--those always mention all possible
+completions.
+
+   If a completion command finds the next character is undetermined, it
+automatically displays a list of all possible completions.  If the
+variable `completion-auto-help' is set to `nil', this does not happen,
+and you must type `?' to display the possible completions.
+
+   If the variable `minibuffer-confirm-incomplete' is set to `t', then
+in contexts where `completing-read' allows answers that are not valid
+completions, an extra <RET> must be typed to confirm the response.
+This is helpful for catching typos.
+
+   Icomplete mode presents a constantly-updated display that tells you
+what completions are available for the text you've entered so far.  The
+command to enable or disable this minor mode is `M-x icomplete-mode'.
+
+\1f
+File: xemacs.info,  Node: Minibuffer History,  Next: Repetition,  Prev: Completion,  Up: Minibuffer
+
+Minibuffer History
+==================
+
+Every argument that you enter with the minibuffer is saved on a
+"minibuffer history list" so that you can use it again later in another
+argument.  Special commands load the text of an earlier argument in the
+minibuffer.  They discard the old minibuffer contents, so you can think
+of them as moving through the history of previous arguments.
+
+`<UP>'
+`M-p'
+     Move to the next earlier argument string saved in the minibuffer
+     history (`previous-history-element').
+
+`<DOWN>'
+`M-n'
+     Move to the next later argument string saved in the minibuffer
+     history (`next-history-element').
+
+`M-r REGEXP <RET>'
+     Move to an earlier saved argument in the minibuffer history that
+     has a match for REGEXP (`previous-matching-history-element').
+
+`M-s REGEXP <RET>'
+     Move to a later saved argument in the minibuffer history that has a
+     match for REGEXP (`next-matching-history-element').
+
+   The simplest way to reuse the saved arguments in the history list is
+to move through the history list one element at a time.  While in the
+minibuffer, use `M-p' or up-arrow (`previous-history-element') to "move
+to" the next earlier minibuffer input, and use `M-n' or down-arrow
+(`next-history-element') to "move to" the next later input.
+
+   The previous input that you fetch from the history entirely replaces
+the contents of the minibuffer.  To use it as the argument, exit the
+minibuffer as usual with <RET>.  You can also edit the text before you
+reuse it; this does not change the history element that you "moved" to,
+but your new argument does go at the end of the history list in its own
+right.
+
+   For many minibuffer arguments there is a "default" value.  In some
+cases, the minibuffer history commands know the default value.  Then you
+can insert the default value into the minibuffer as text by using `M-n'
+to move "into the future" in the history.
+
+   There are also commands to search forward or backward through the
+history; they search for history elements that match a regular
+expression that you specify with the minibuffer.  `M-r'
+(`previous-matching-history-element') searches older elements in the
+history, while `M-s' (`next-matching-history-element') searches newer
+elements.  By special dispensation, these commands can use the
+minibuffer to read their arguments even though you are already in the
+minibuffer when you issue them.  As with incremental searching, an
+uppercase letter in the regular expression makes the search
+case-sensitive (*note Search Case::).
+
+   All uses of the minibuffer record your input on a history list, but
+there are separate history lists for different kinds of arguments.  For
+example, there is a list for file names, used by all the commands that
+read file names.
+
+   There are several other very specific history lists, including one
+for command names read by `M-x', one for buffer names, one for arguments
+of commands like `query-replace', and one for compilation commands read
+by `compile'.  Finally, there is one "miscellaneous" history list that
+most minibuffer arguments use.
+
+\1f
+File: xemacs.info,  Node: Repetition,  Prev: Minibuffer History,  Up: Minibuffer
+
+Repeating Minibuffer Commands
+=============================
+
+Every command that uses the minibuffer at least once is recorded on a
+special history list, together with the values of its arguments, so that
+you can repeat the entire command.  In particular, every use of `M-x'
+is recorded there, since `M-x' uses the minibuffer to read the command
+name.
+
+`C-x <ESC> <ESC>'
+     Re-execute a recent minibuffer command (`repeat-complex-command').
+
+`M-p'
+     Within `C-x <ESC> <ESC>', move to previous recorded command
+     (`previous-history-element').
+
+`M-n'
+     Within `C-x <ESC> <ESC>', move to the next (more recent) recorded
+     command (`next-history-element').
+
+`M-x list-command-history'
+     Display the entire command history, showing all the commands `C-x
+     <ESC> <ESC>' can repeat, most recent first.
+
+   `C-x <ESC> <ESC>' is used to re-execute a recent minibuffer-using
+command.  With no argument, it repeats the last such command.  A
+numeric argument specifies which command to repeat; one means the last
+one, and larger numbers specify earlier ones.
+
+   `C-x <ESC> <ESC>' works by turning the previous command into a Lisp
+expression and then entering a minibuffer initialized with the text for
+that expression.  If you type just <RET>, the command is repeated as
+before.  You can also change the command by editing the Lisp
+expression.  Whatever expression you finally submit is what will be
+executed.  The repeated command is added to the front of the command
+history unless it is identical to the most recently executed command
+already there.
+
+   Even if you don't understand Lisp syntax, it will probably be obvious
+which command is displayed for repetition.  If you do not change the
+text, you can be sure the command will repeat exactly as before.
+
+   If you are in the minibuffer for `C-x <ESC> <ESC>' and the command
+shown to you is not the one you want to repeat, you can move around the
+list of previous commands using `M-n' and `M-p'.  `M-p' replaces the
+contents of the minibuffer with the next earlier recorded command, and
+`M-n' replaces it with the next later command.  After finding the
+desired previous command, you can edit its expression and then resubmit
+it by typing <RET>.  Any editing you have done on the command to be
+repeated is lost if you use `M-n' or `M-p'.
+
+   `M-n' and `M-p' are specially defined within `C-x <ESC> <ESC>' to
+run the commands `previous-history-element' and `next-history-element'.
+
+   The list of previous commands using the minibuffer is stored as a
+Lisp list in the variable `command-history'.  Each element of the list
+is a Lisp expression which describes one command and its arguments.
+Lisp programs can reexecute a command by feeding the corresponding
+`command-history' element to `eval'.
+
+\1f
+File: xemacs.info,  Node: M-x,  Next: Help,  Prev: Minibuffer,  Up: Top
+
+Running Commands by Name
+************************
+
+The Emacs commands that are used often or that must be quick to type are
+bound to keys--short sequences of characters--for convenient use.  Other
+Emacs commands that are used more rarely are not bound to keys; to run
+them, you must refer to them by name.
+
+   A command name consists, by convention, of one or more words,
+separated by hyphens: for example, `auto-fill-mode' or `manual-entry'.
+The use of English words makes the command name easier to remember than
+a key made up of obscure characters, even though it results in more
+characters to type.  You can run any command by name, even if it can be
+run by keys as well.
+
+   To run a command by name, start with `M-x', then type the command
+name, and finish with <RET>.  `M-x' uses the minibuffer to read the
+command name.  <RET> exits the minibuffer and runs the command.
+
+   Emacs uses the minibuffer for reading input for many different
+purposes; on this occasion, the string `M-x' is displayed at the
+beginning of the minibuffer as a "prompt" to remind you that your input
+should be the name of a command to be run.  *Note Minibuffer::, for
+full information on the features of the minibuffer.
+
+   You can use completion to enter a command name.  For example, to
+invoke the command `forward-char', type:
+
+     M-x forward-char <RET>
+   or
+     M-x fo <TAB> c <RET>
+
+After you type in `M-x fo TAB' emacs will give you a possible list of
+completions from which you can choose. Note that `forward-char' is the
+same command that you invoke with the key `C-f'.  You can call any
+command (interactively callable function) defined in Emacs by its name
+using `M-x' regardless of whether or not any keys are bound to it.
+
+   If you type `C-g' while Emacs reads the command name, you cancel the
+`M-x' command and get out of the minibuffer, ending up at top level.
+
+   To pass a numeric argument to a command you are invoking with `M-x',
+specify the numeric argument before the `M-x'.  `M-x' passes the
+argument along to the function that it calls.  The argument value
+appears in the prompt while the command name is being read.
+
+   You can use the command `M-x interactive' to specify a way of
+parsing arguments for interactive use of a function.  For example,
+write:
+
+       (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
+
+   to make `arg' be the prefix argument when `foo' is called as a
+command.  The call to `interactive' is actually a declaration rather
+than a function; it tells `call-interactively' how to read arguments to
+pass to the function.  When actually called, `interactive' returns
+`nil'.
+
+   The argument of INTERACTIVE is usually a string containing a code
+letter followed by a prompt.  Some code letters do not use I/O to get
+the argument and do not need prompts.  To prompt for multiple arguments,
+you must provide a code letter, its prompt, a newline, and another code
+letter, and so forth.  If the argument is not a string, it is evaluated
+to get a list of arguments to pass to the function.  If you do not
+provide an argument to `interactive', no arguments are passed when
+calling interactively.
+
+   Available code letters are:
+
+`a'
+     Function name: symbol with a function definition
+
+`b'
+     Name of existing buffer
+
+`B'
+     Name of buffer, possibly nonexistent
+
+`c'
+     Character
+
+`C'
+     Command name: symbol with interactive function definition
+
+`d'
+     Value of point as number (does not do I/O)
+
+`D'
+     Directory name
+
+`e'
+     Last mouse event
+
+`f'
+     Existing file name
+
+`F'
+     Possibly nonexistent file name
+
+`k'
+     Key sequence (string)
+
+`m'
+     Value of mark as number (does not do I/O)
+
+`n'
+     Number read using minibuffer
+
+`N'
+     Prefix arg converted to number, or if none, do like code `n'
+
+`p'
+     Prefix arg converted to number (does not do I/O)
+
+`P'
+     Prefix arg in raw form (does not do I/O)
+
+`r'
+     Region: point and mark as two numeric arguments, smallest first
+     (does not do I/O)
+
+`s'
+     Any string
+
+`S'
+     Any symbol
+
+`v'
+     Variable name: symbol that is `user-variable-p'
+
+`x'
+     Lisp expression read but not evaluated
+
+`X'
+     Lisp expression read and evaluated
+
+   In addition, if the string begins with `*', an error is signaled if
+the buffer is read-only.  This happens before reading any arguments.
+If the string begins with `@', the window the mouse is over is selected
+before anything else is done.  You may use both `@' and `*'; they are
+processed in the order that they appear.
+
+   Normally, when describing a command that is run by name, we omit the
+<RET> that is needed to terminate the name.  Thus we may refer to `M-x
+auto-fill-mode' rather than `M-x auto-fill-mode' <RET>.  We mention the
+<RET> only when it is necessary to emphasize its presence, for example,
+when describing a sequence of input that contains a command name and
+arguments that follow it.
+
+   `M-x' is defined to run the command `execute-extended-command',
+which is responsible for reading the name of another command and
+invoking it.
+
+\1f
+File: xemacs.info,  Node: Help,  Next: Mark,  Prev: M-x,  Up: Top
+
+Help
+****
+
+XEmacs provides extensive help features accessible through a single
+character, `C-h'.  `C-h' is a prefix key that is used only for
+documentation-printing commands.  The characters that you can type after
+`C-h' are called "help options".  One help option is `C-h'; that is how
+you ask for help about using `C-h'.  To cancel, type `C-g'.  The
+function key <F1> is equivalent to `C-h'.
+
+   `C-h C-h' (`help-for-help') displays a list of the possible help
+options, and then asks you to type the desired option.  It prompts with
+the string:
+
+     A B C F I K L M N P S T V W C-c C-d C-f C-i C-k C-n C-w;  ? for more help:
+
+You should type one of those characters.
+
+   Typing a third `C-h' displays a description of what the options mean;
+Emacs still waits for you to type an option.  To cancel, type `C-g'.
+
+   Most help buffers use a special major mode, Help mode, which lets you
+scroll conveniently with <SPC> and <DEL> or <BS>.
+
+* Menu:
+
+* Help Summary::       Brief list of all Help commands.
+* Key Help::           Asking what a key does in XEmacs.
+* Name Help::          Asking about a command, variable or function name.
+* Apropos::            Asking what pertains to a given topic.
+* Library Keywords::   Finding Lisp libraries by keywords (topics).
+* Help Mode::           Special features of Help mode and Help buffers.
+* Misc Help::          Other help commands.
+
+\1f
+File: xemacs.info,  Node: Help Summary,  Next: Key Help,  Prev: Help,  Up: Help
+
+Help Summary
+============
+
+   Here is a summary of the defined help commands.
+
+`C-h a REGEXP <RET>'
+     Display a list of functions and variables whose names match REGEXP
+     (`hyper-apropos').
+
+`C-h A REGEXP'
+     Show all commands whose names contain matches for REGEXP
+     (`command-apropos').
+
+`C-h b'
+     Display a table of all key bindings currently in effect, with local
+     bindings of the current major mode first, followed by all global
+     bindings (`describe-bindings').
+
+`C-h c KEY'
+     Print the name of the command that KEY runs
+     (`describe-key-briefly').  Here `c' stands for `character'.  For
+     more extensive information on KEY, use `C-h k'.
+
+`C-h d FUNCTION <RET>'
+`C-h f FUNCTION <RET>'
+     Display documentation on the Lisp function named FUNCTION
+     (`describe-function').  Since commands are Lisp functions, a
+     command name may be used.
+
+`C-h i'
+     Run Info, the program for browsing documentation files (`info').
+     The complete XEmacs manual is available online in Info.
+
+`C-h k KEY'
+     Display the name and documentation of the command that KEY runs
+     (`describe-key').
+
+`C-h l'
+     Display a description of the last 100 characters you typed
+     (`view-lossage').
+
+`C-h m'
+     Display documentation of the current major mode (`describe-mode').
+
+`C-h n'
+`C-h C-n'
+     Display documentation of XEmacs changes, most recent first
+     (`view-emacs-news').
+
+`C-h p'
+     Find packages by topic keyword (`finder-by-keyword').
+
+`C-h C-p'
+     Display a table of all mouse bindings currently in effect now, with
+     local bindings of the current major mode first, followed by all
+     global bindings (`describe-pointer').
+
+`C-h s'
+     Display current contents of the syntax table, plus an explanation
+     of what they mean (`describe-syntax').  *Note Syntax::.
+
+`C-h t'
+     Enter the XEmacs interactive tutorial (`help-with-tutorial').
+
+`C-h v VAR <RET>'
+     Display the documentation of the Lisp variable VAR
+     (`describe-variable').
+
+`C-h w COMMAND <RET>'
+     Print which keys run the command named COMMAND (`where-is').
+
+`C-h B <RET>'
+     Display info on how to deal with Beta versions of XEmacs
+     (`describe-beta').
+
+`C-h C GROUP <RET>'
+     Select customization buffer for GROUP (`customize').
+
+`C-h F <RET>'
+     View the local copy of the XEmacs FAQ (`xemacs-local-faq').
+
+`C-h C-i FILE <RET>'
+     Read Info file FILE with Info browser (`Info-query').
+
+`C-h C-c COMMAND <RET>'
+     Look up an Emacs command COMMAND in the Emacs manual in the Info
+     system (`Info-goto-emacs-command-node').
+
+`C-h C-f FUNCTION <RET>'
+     Look up an Emacs Lisp function FUNCTION in the Elisp manual in the
+     Info system (`Info-elisp-ref').
+
+\1f
+File: xemacs.info,  Node: Key Help,  Next: Name Help,  Prev: Help Summary,  Up: Help
+
+Documentation for a Key
+=======================
+
+The most basic `C-h' options are `C-h c' (`describe-key-briefly') and
+`C-h k' (`describe-key').  `C-h c KEY' prints in the echo area the name
+of the command that KEY is bound to.  For example, `C-h c C-f' prints
+`forward-char'.  Since command names are chosen to describe what the
+commands do, this is a good way to get a very brief description of what
+KEY does.
+
+   `C-h k KEY' is similar to `C-h c' but gives more information.  It
+displays the documentation string of the function KEY is bound to as
+well as its name.  KEY is a string or vector of events.  When called
+interactively, KEY may also be a menu selection.  This information does
+not usually fit into the echo area, so a window is used for the display.
+
+   `C-h c' and `C-h k' work for any sort of key sequences, including
+function keys and mouse events.
+
+\1f
+File: xemacs.info,  Node: Name Help,  Next: Apropos,  Prev: Key Help,  Up: Help
+
+Help by Command or Variable Name
+================================
+
+`C-h f' (`describe-function') reads the name of a Lisp function using
+the minibuffer, then displays that function's documentation string in a
+window.  Since commands are Lisp functions, you can use the argument
+FUNCTION to get the documentation of a command that you know by name.
+For example,
+
+     C-h f auto-fill-mode <RET>
+
+displays the documentation for `auto-fill-mode'. Using `C-h f' is the
+only way to see the documentation of a command that is not bound to any
+key, that is, a command you would normally call using `M-x'.  If the
+variable `describe-function-show-arglist' is `t', `describe-function'
+shows its arglist if the FUNCTION is not an autoload function.
+
+   `C-h f' is also useful for Lisp functions that you are planning to
+use in a Lisp program.  For example, if you have just written the
+expression `(make-vector len)' and want to make sure you are using
+`make-vector' properly, type `C-h f make-vector <RET>'.  Because `C-h
+f' allows all function names, not just command names, you may find that
+some of your favorite abbreviations that work in `M-x' don't work in
+`C-h f'.  An abbreviation may be unique among command names, yet fail
+to be unique when other function names are allowed.
+
+   The function name for `C-h f' to describe has a default which is
+used if you type <RET> leaving the minibuffer empty.  The default is
+the function called by the innermost Lisp expression in the buffer
+around point, _provided_ that is a valid, defined Lisp function name.
+For example, if point is located following the text `(make-vector (car
+x)', the innermost list containing point is the one that starts with
+`(make-vector', so the default is to describe the function
+`make-vector'.
+
+   `C-h f' is often useful just to verify that you have the right
+spelling for the function name.  If `C-h f' mentions a name from the
+buffer as the default, that name must be defined as a Lisp function.  If
+that is all you want to know, just type `C-g' to cancel the `C-h f'
+command, then go on editing.
+
+   `C-h w COMMAND <RET>' (`where-is') tells you what keys are bound to
+COMMAND.  It prints a list of the keys in the echo area. Alternatively,
+it informs you that a command is not bound to any keys, which implies
+that you must use `M-x' to call the command.
+
+   `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
+variables instead of Lisp functions.  Its default is the Lisp symbol
+around or before point, if that is the name of a known Lisp variable.
+*Note Variables::.
+
+\1f
+File: xemacs.info,  Node: Apropos,  Next: Library Keywords,  Prev: Name Help,  Up: Help
+
+Apropos
+=======
+
+`C-h A'
+     Show only symbols that are names of commands (`command-apropos').
+
+`M-x apropos REGEXP'
+     Show all symbols whose names contain matches for REGEXP.
+
+   A more sophisticated sort of question to ask is, "What are the
+commands for working with files?"  To ask this question, type `C-h a
+file <RET>', which displays a list of all command names that contain
+`file', including `copy-file', `find-file', and so on.  With each
+command name appears a brief description of how to use the command, and
+what keys you can currently invoke it with.  For example, it would say
+that you can invoke `find-file' by typing `C-x C-f'.  The `A' in `C-h
+A' stands for `Apropos'; `C-h A' runs the command `command-apropos'.
+This command normally checks only commands (interactive functions); if
+you specify a prefix argument, it checks noninteractive functions as
+well.
+
+   Because `C-h A' looks only for functions whose names contain the
+string you specify, you must use ingenuity in choosing the string.  If
+you are looking for commands for killing backwards and `C-h a
+kill-backwards <RET>' doesn't reveal any, don't give up.  Try just
+`kill', or just `backwards', or just `back'.  Be persistent.  Pretend
+you are playing Adventure.  Also note that you can use a regular
+expression as the argument, for more flexibility (*note Regexps::).
+
+   Here is a set of arguments to give to `C-h a' that covers many
+classes of XEmacs commands, since there are strong conventions for
+naming the standard XEmacs commands.  By giving you a feel for the
+naming conventions, this set should also serve to aid you in developing
+a technique for picking `apropos' strings.
+
+     char, line, word, sentence, paragraph, region, page, sexp, list,
+     defun, rect, buffer, frame, window, face, file, dir, register,
+     mode, beginning, end, forward, backward, next, previous, up, down,
+     search, goto, kill, delete, mark, insert, yank, fill, indent,
+     case, change, set, what, list, find, view, describe, default.
+
+   To list all Lisp symbols that contain a match for a regexp, not just
+the ones that are defined as commands, use the command `M-x apropos'
+instead of `C-h A'.  This command does not check key bindings by
+default; specify a numeric argument if you want it to check them.
+
+   The `apropos-documentation' command is like `apropos' except that it
+searches documentation strings for matches for the specified regular
+expression.
+
+   The `apropos-value' command is like `apropos' except that it
+searches symbols' values for matches for the specified regular
+expression.  This command does not check function definitions or
+property lists by default; specify a numeric argument if you want it to
+check them.
+
+   If the variable `apropos-do-all' is non-`nil', the commands above
+all behave as if they had been given a prefix argument.
+
+   If you want more information about a function definition, variable or
+symbol property listed in the Apropos buffer, you can click on it with
+`Mouse-2' or move there and type <RET>.
+
+\1f
+File: xemacs.info,  Node: Library Keywords,  Next: Help Mode,  Prev: Apropos,  Up: Help
+
+Keyword Search for Lisp Libraries
+=================================
+
+The `C-h p' command lets you search the standard Emacs Lisp libraries
+by topic keywords.  Here is a partial list of keywords you can use:
+
+     abbrev        abbreviation handling, typing shortcuts, macros
+     bib           code related to the `bib' bibliography processor
+     c             C, C++, and Objective-C language support
+     calendar      calendar and time management support
+     comm          communications, networking, remote access to files
+     data          support for editing files of data
+     docs          support for Emacs documentation
+     dumped        files preloaded into Emacs
+     emulations    emulations of other editors
+     extensions    Emacs Lisp language extensions
+     faces         support for multiple fonts
+     frames        support for Emacs frames and window systems
+     games         games, jokes and amusements
+     hardware      support for interfacing with exotic hardware
+     help          support for on-line help systems
+     hypermedia    support for links between text or other media types
+     i18n          internationalization and alternate character-set support
+     internal      code for Emacs internals, build process, defaults
+     languages     specialized modes for editing programming languages
+     lisp          Lisp support, including Emacs Lisp
+     local         code local to your site
+     maint         maintenance aids for the Emacs development group
+     mail          modes for electronic-mail handling
+     matching      various sorts of searching and matching
+     mouse         mouse support
+     mule          multi-language extensions
+     news          support for netnews reading and posting
+     oop           support for object-oriented programming
+     outlines      support for hierarchical outlining
+     processes     process, subshell, compilation, and job control support
+     terminals     support for terminal types
+     tex           code related to the TeX formatter
+     tools         programming tools
+     unix          front-ends/assistants for, or emulators of, UNIX features
+     vms           support code for vms
+     wp            word processing
+
+\1f
+File: xemacs.info,  Node: Help Mode,  Next: Misc Help,  Prev: Library Keywords,  Up: Help
+
+Help Mode Commands
+==================
+
+Help buffers provide the commands of View mode (*note Misc File Ops::),
+plus a few special commands of their own.
+
+`<SPC>'
+     Scroll forward.
+
+`<DEL>'
+`<BS>'
+     Scroll backward.
+
+   When a command name (*note Running Commands by Name: M-x.) or
+variable name (*note Variables::) appears in the documentation, it
+normally appears inside paired single-quotes.
+
+\1f
+File: xemacs.info,  Node: Misc Help,  Prev: Help Mode,  Up: Help
+
+Other Help Commands
+===================
+
+`C-h i' (`info') runs the Info program, which is used for browsing
+through structured documentation files.  The entire XEmacs manual is
+available within Info.  Eventually all the documentation of the GNU
+system will be available.  Type `h' after entering Info to run a
+tutorial on using Info.
+
+   If you specify a numeric argument, `C-h i' prompts for the name of a
+documentation file.  This way, you can browse a file which doesn't have
+an entry in the top-level Info menu.  It is also handy when you need to
+get to the documentation quickly, and you know the exact name of the
+file.
+
+   There are two special help commands for accessing XEmacs
+documentation through Info.  `C-h C-f FUNCTION <RET>' enters Info and
+goes straight to the documentation of the XEmacs function FUNCTION.
+`C-h C-k KEY' enters Info and goes straight to the documentation of the
+key KEY.  These two keys run the commands `Info-elisp-ref' and
+`Info-goto-emacs-key-command-node'.
+
+   If something surprising happens, and you are not sure what commands
+you typed, use `C-h l' (`view-lossage').  `C-h l' prints the last 100
+command characters you typed in.  If you see commands that you don't
+know, you can use `C-h c' to find out what they do.
+
+   XEmacs has several major modes.  Each mode redefines a few keys and
+makes a few other changes in how editing works.  `C-h m'
+(`describe-mode') prints documentation on the current major mode, which
+normally describes all the commands that are changed in this mode.
+
+   `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax')
+present information about the current XEmacs mode that is not covered
+by `C-h m'.  `C-h b' displays a list of all the key bindings currently
+in effect, with the local bindings of the current major mode first,
+followed by the global bindings (*note Key Bindings::).  `C-h s'
+displays the contents of the syntax table with explanations of each
+character's syntax (*note Syntax::).
+
+   You can get a similar list for a particular prefix key by typing
+`C-h' after the prefix key.  (There are a few prefix keys for which
+this does not work--those that provide their own bindings for `C-h'.
+One of these is <ESC>, because `<ESC> C-h' is actually `C-M-h', which
+marks a defun.)
+
+   The other `C-h' options display various files of useful information.
+`C-h C-w' (`describe-no-warranty') displays the full details on the
+complete absence of warranty for XEmacs.  `C-h n' (`view-emacs-news')
+displays the file `xemacs/etc/NEWS', which contains documentation on
+XEmacs changes arranged chronologically.  `C-h F' (`xemacs-local-faq')
+displays local version of the XEmacs
+frequently-answered-questions-list.  `C-h t' (`help-with-tutorial')
+displays the learn-by-doing XEmacs tutorial. `C-h C-c'
+(`describe-copying') displays the file `xemacs/etc/COPYING', which
+tells you the conditions you must obey in distributing copies of
+XEmacs.  `C-h C-d' (`describe-distribution') displays another file named
+`xemacs/etc/DISTRIB', which tells you how you can order a copy of the
+latest version of XEmacs.
+
+\1f
+File: xemacs.info,  Node: Mark,  Next: Mouse Selection,  Prev: Help,  Up: Top
+
+Selecting Text
+**************
+
+Many Emacs commands operate on an arbitrary contiguous part of the
+current buffer. You can select text in two ways:
+
+   * You use special keys to select text by defining a region between
+     point and the mark.
+
+   * If you are running XEmacs under X, you can also select text with
+     the mouse.
+
+The Mark and the Region
+=======================
+
+To specify the text for a command to operate on, set "the mark" at one
+end of it, and move point to the other end.  The text between point and
+the mark is called "the region".  You can move point or the mark to
+adjust the boundaries of the region.  It doesn't matter which one is
+set first chronologically, or which one comes earlier in the text.
+
+   Once the mark has been set, it remains until it is set again at
+another place.  The mark remains fixed with respect to the preceding
+character if text is inserted or deleted in a buffer.  Each Emacs
+buffer has its own mark; when you return to a buffer that had been
+selected previously, it has the same mark it had before.
+
+   Many commands that insert text, such as `C-y' (`yank') and `M-x
+insert-buffer', position the mark at one end of the inserted text--the
+opposite end from where point is positioned, so that the region
+contains the text just inserted.
+
+   Aside from delimiting the region, the mark is useful for marking a
+spot that you may want to go back to.  To make this feature more useful,
+Emacs remembers 16 previous locations of the mark in the `mark ring'.
+
+* Menu:
+
+* Setting Mark::       Commands to set the mark.
+* Using Region::       Summary of ways to operate on contents of the region.
+* Marking Objects::    Commands to put region around textual units.
+* Mark Ring::          Previous mark positions saved so you can go back there.
+
+\1f
+File: xemacs.info,  Node: Setting Mark,  Next: Using Region,  Prev: Mark,  Up: Mark
+
+Setting the Mark
+----------------
+
+Here are some commands for setting the mark:
+
+`C-<SPC>'
+     Set the mark where point is (`set-mark-command').
+
+`C-@'
+     The same.
+
+`C-x C-x'
+     Interchange mark and point (`exchange-point-and-mark').
+
+`C-<'
+     Pushes a mark at the beginning of the buffer.
+
+`C->'
+     Pushes a mark at the end of the buffer.
+
+   For example, to convert part of the buffer to all upper-case, you
+can use the `C-x C-u' (`upcase-region') command, which operates on the
+text in the region.  First go to the beginning of the text you want to
+capitalize and type `C-<SPC>' to put the mark there, then move to the
+end, and then type `C-x C-u' to capitalize the selected region.  You
+can also set the mark at the end of the text, move to the beginning,
+and then type `C-x C-u'.  Most commands that operate on the text in the
+region have the word `region' in their names.
+
+   The most common way to set the mark is with the `C-<SPC>' command
+(`set-mark-command').  This command sets the mark where point is. You
+can then move point away, leaving the mark behind.  It is actually
+incorrect to speak of the character `C-<SPC>'; there is no such
+character.  When you type <SPC> while holding down <CTRL>, you get the
+character `C-@' on most terminals. This character is actually bound to
+`set-mark-command'.  But unless you are unlucky enough to have a
+terminal where typing `C-<SPC>' does not produce `C-@', you should
+think of this character as `C-<SPC>'.
+
+   Since terminals have only one cursor, Emacs cannot show you where the
+mark is located. Most people use the mark soon after they set it, before
+they forget where it is. But you can see where the mark is with the
+command `C-x C-x' (`exchange-point-and-mark') which puts the mark where
+point was and point where the mark was.  The extent of the region is
+unchanged, but the cursor and point are now at the previous location of
+the mark.
+
+   Another way to set the mark is to push the mark to the beginning of a
+buffer while leaving point at its original location. If you supply an
+argument to `C-<' (`mark-beginning-of-buffer'), the mark is pushed N/10
+of the way from the true beginning of the buffer. You can also set the
+mark at the end of a buffer with `C->' (`mark-end-of-buffer'). It
+pushes the mark to the end of the buffer, leaving point alone.
+Supplying an argument to the command pushes the mark N/10 of the way
+from the true end of the buffer.
+
+   If you are using XEmacs under the X window system, you can set the
+variable `zmacs-regions' to `t'. This makes the current region (defined
+by point and mark) highlight and makes it available as the X clipboard
+selection, which means you can use the menu bar items on it.  *Note
+Active Regions::, for more information.
+
+   `C-x C-x' is also useful when you are satisfied with the location of
+point but want to move the mark; do `C-x C-x' to put point there and
+then you can move it.  A second use of `C-x C-x', if necessary, puts
+the mark at the new location with point back at its original location.
+
+\1f
+File: xemacs.info,  Node: Using Region,  Next: Marking Objects,  Prev: Setting Mark,  Up: Mark
+
+Operating on the Region
+-----------------------
+
+Once you have created an active region, you can do many things to the
+text in it:
+   * Kill it with `C-w' (*note Killing::).
+
+   * Save it in a register with `C-x r s' (*note Registers::).
+
+   * Save it in a buffer or a file (*note Accumulating Text::).
+
+   * Convert case with `C-x C-l' or `C-x C-u'
+     (*note Case::).
+
+   * Evaluate it as Lisp code with `M-x eval-region' (*note Lisp
+     Eval::).
+
+   * Fill it as text with `M-q' (*note Filling::).
+
+   * Print hardcopy with `M-x print-region' (*note Hardcopy::).
+
+   * Indent it with `C-x <TAB>' or `C-M-\' (*note Indentation::).
+
+\1f
+File: xemacs.info,  Node: Marking Objects,  Next: Mark Ring,  Prev: Using Region,  Up: Mark
+
+Commands to Mark Textual Objects
+--------------------------------
+
+There are commands for placing point and the mark around a textual
+object such as a word, list, paragraph or page.
+
+`M-@'
+     Set mark after end of next word (`mark-word').  This command and
+     the following one do not move point.
+
+`C-M-@'
+     Set mark after end of next Lisp expression (`mark-sexp').
+
+`M-h'
+     Put region around current paragraph (`mark-paragraph').
+
+`C-M-h'
+     Put region around current Lisp defun (`mark-defun').
+
+`C-x h'
+     Put region around entire buffer (`mark-whole-buffer').
+
+`C-x C-p'
+     Put region around current page (`mark-page').
+
+   `M-@' (`mark-word') puts the mark at the end of the next word, while
+`C-M-@' (`mark-sexp') puts it at the end of the next Lisp expression.
+These characters sometimes save you some typing.
+
+   A number of commands are available that set both point and mark and
+thus delimit an object in the buffer.  `M-h' (`mark-paragraph') moves
+point to the beginning of the paragraph that surrounds or follows
+point, and puts the mark at the end of that paragraph (*note
+Paragraphs::).  You can then indent, case-convert, or kill the whole
+paragraph.  In the same fashion, `C-M-h' (`mark-defun') puts point
+before and the mark after the current or following defun (*note
+Defuns::).  `C-x C-p' (`mark-page') puts point before the current page
+(or the next or previous, depending on the argument), and mark at the
+end (*note Pages::).  The mark goes after the terminating page
+delimiter (to include it), while point goes after the preceding page
+delimiter (to exclude it).  Finally, `C-x h' (`mark-whole-buffer') sets
+up the entire buffer as the region by putting point at the beginning
+and the mark at the end.
+
+\1f
+File: xemacs.info,  Node: Mark Ring,  Prev: Marking Objects,  Up: Mark
+
+The Mark Ring
+-------------
+
+Aside from delimiting the region, the mark is also useful for marking a
+spot that you may want to go back to.  To make this feature more
+useful, Emacs remembers 16 previous locations of the mark in the "mark
+ring".  Most commands that set the mark push the old mark onto this
+ring.  To return to a marked location, use `C-u C-<SPC>' (or `C-u
+C-@'); this is the command `set-mark-command' given a numeric argument.
+The command moves point to where the mark was, and restores the mark
+from the ring of former marks. Repeated use of this command moves point
+to all the old marks on the ring, one by one.  The marks you have seen
+go to the end of the ring, so no marks are lost.
+
+   Each buffer has its own mark ring.  All editing commands use the
+current buffer's mark ring.  In particular, `C-u C-<SPC>' always stays
+in the same buffer.
+
+   Many commands that can move long distances, such as `M-<'
+(`beginning-of-buffer'), start by setting the mark and saving the old
+mark on the mark ring.  This makes it easier for you to move back
+later.  Searches set the mark, unless they do not actually move point.
+When a command sets the mark, `Mark Set' is printed in the echo area.
+
+   The variable `mark-ring-max' is the maximum number of entries to
+keep in the mark ring.  If that many entries exist and another entry is
+added, the last entry in the list is discarded.  Repeating `C-u
+C-<SPC>' circulates through the entries that are currently in the ring.
+
+   The variable `mark-ring' holds the mark ring itself, as a list of
+marker objects in the order most recent first.  This variable is local
+in every buffer.
+
+\1f
+File: xemacs.info,  Node: Mouse Selection,  Next: Additional Mouse Operations,  Prev: Mark,  Up: Top
+
+Selecting Text with the Mouse
+=============================
+
+If you are using XEmacs under X, you can use the mouse pointer to
+select text. (The normal mouse pointer is an I-beam, the same pointer
+that `xterm' uses.)
+
+   The glyph variable `text-pointer-glyph' controls the shape of the
+mouse pointer when over text.  You can also control the shape of the
+mouse pointer when over nontext using `nontext-pointer-glyph', and the
+shape of the mouse pointer when over the modeline using
+`modeline-pointer-glyph'. (Remember, you should use `set-glyph-image',
+not `setq', to set one of these variables.)
+
+   If you want to get fancy, you can set the foreground and background
+colors of the mouse pointer by setting the `pointer' face.
+
+   There are two ways to select a region of text with the mouse:
+
+   To select a word in text, double-click with the left mouse button
+while the mouse cursor is over the word.  The word is highlighted when
+selected. On monochrome monitors, a stippled background indicates that a
+region of text has been highlighted. On color monitors, a color
+background indicates highlighted text. You can triple-click to select
+whole lines.
+
+   To select an arbitrary region of text:
+
+  1. Move the mouse cursor over the character at the beginning of the
+     region of text you want to select.
+
+  2. Press and hold the left mouse button.
+
+  3. While holding the left mouse button down, drag the cursor to the
+     character at the end of the region of text you want to select.
+
+  4. Release the left mouse button.
+        The selected region of text is highlighted.
+
+   Once a region of text is selected, it becomes the primary X selection
+(*note Using X Selections::) as well as the Emacs selected region. You
+can paste it into other X applications and use the options from the
+Edit pull-down menu on it.  Since it is also the Emacs region, you can
+use Emacs region commands on it.
+
+\1f
+File: xemacs.info,  Node: Additional Mouse Operations,  Next: Killing,  Prev: Mouse Selection,  Up: Top
+
+Additional Mouse Operations
+===========================
+
+XEmacs also provides the following mouse functions.  Most of these are
+not bound to mouse gestures by default, but they are provided for your
+customization pleasure.  For example, if you wanted `shift-left' (that
+is, holding down the <Shift> key and clicking the left mouse button) to
+delete the character at which you are pointing, then you could do this:
+
+     (global-set-key '(shift button1) 'mouse-del-char)
+
+`mouse-del-char'
+     Delete the character pointed to by the mouse.
+
+`mouse-delete-window'
+     Delete the Emacs window that the mouse is on.
+
+`mouse-keep-one-window'
+     Select the Emacs window that the mouse is on, then delete all other
+     windows on this frame.
+
+`mouse-kill-line'
+     Kill the line pointed to by the mouse.
+
+`mouse-line-length'
+     Print the length of the line indicated by the pointer.
+
+`mouse-scroll'
+     Scroll point to the mouse position.
+
+`mouse-select'
+     Select the Emacs window the mouse is on.
+
+`mouse-select-and-split'
+     Select the Emacs window mouse is on, then split it vertically in
+     half.
+
+`mouse-set-mark'
+     Select the Emacs window the mouse is on and set the mark at the
+     mouse position.  Display the cursor at that position for a second.
+
+`mouse-set-point'
+     Select the Emacs window that the mouse is on and move point to the
+     mouse position.
+
+`mouse-track'
+     Make a selection with the mouse.   This is the default binding of
+     the left mouse button (<button1>).
+
+`mouse-track-adjust'
+     Extend the existing selection.  This is the default binding of
+     <Shift-button1>.
+
+`mouse-track-and-copy-to-cutbuffer'
+     Make a selection like `mouse-track', but also copy it to the cut
+     buffer.
+
+`mouse-track-delete-and-insert'
+     Make a selection with the mouse and insert it at point.  This is
+     the default binding of <control-shift-button1>.
+
+`mouse-track-insert'
+     Make a selection with the mouse and insert it at point.  This is
+     the default binding of <control-button1>.
+
+`mouse-window-to-region'
+     Narrow a window to the region between the cursor and the mouse
+     pointer.
+
+   The `M-x mouse-track' command should be bound to a mouse button.  If
+you click-and-drag, the selection is set to the region between the
+point of the initial click and the point at which you release the
+button.  These positions do not need to be ordered.
+
+   If you click-and-release without moving the mouse, the point is
+moved, and the selection is disowned (there will be no selection
+owner.)  The mark will be set to the previous position of point.
+
+   If you double-click, the selection will extend by symbols instead of
+by characters.  If you triple-click, the selection will extend by lines.
+
+   If you drag the mouse off the top or bottom of the window, you can
+select pieces of text that are larger than the visible part of the
+buffer; the buffer will scroll as necessary.
+
+   The selected text becomes the current X selection, and is also
+copied to the top of the kill ring.  Point will be left at the position
+at which you released the button and the mark will be left at the
+initial click position.  Bind a mouse click to
+`mouse-track-and-copy-to-cutbuffer' to copy selections to the cut
+buffer.  (See also the `mouse-track-adjust' command, on
+`Shift-button1'.)
+
+   The `M-x mouse-track-adjust' command should be bound to a mouse
+button.  The selection will be enlarged or shrunk so that the point of
+the mouse click is one of its endpoints.  This is only meaningful after
+the `mouse-track' command (<button1>) has been executed.
+
+   The `M-x mouse-track-delete-and-insert' command is exactly the same
+as the `mouse-track' command on <button1>, except that point is not
+moved; the selected text is immediately inserted after being selected;
+and the text of the selection is deleted.
+
+   The `M-x mouse-track-insert' command is exactly the same as the
+`mouse-track' command on <button1>, except that point is not moved; the
+selected text is immediately inserted after being selected; and the
+selection is immediately disowned afterwards.
+
+\1f
+File: xemacs.info,  Node: Killing,  Next: Yanking,  Prev: Additional Mouse Operations,  Up: Top
+
+Deletion and Killing
+====================
+
+Most commands that erase text from the buffer save it. You can get the
+text back if you change your mind, or you can move or copy it to other
+parts of the buffer.  Commands which erase text and save it in the kill
+ring are known as "kill" commands.  Some other commands erase text but
+do not save it; they are known as "delete" commands.  (This distinction
+is made only for erasing text in the buffer.)
+
+   The commands' names and individual descriptions use the words `kill'
+and `delete' to indicate what they do.  If you perform a kill or delete
+command by mistake, use the `C-x u' (`undo') command to undo it (*note
+Undo::). The delete commands include `C-d' (`delete-char') and <DEL>
+(`delete-backward-char'), which delete only one character at a time,
+and those commands that delete only spaces or newlines.  Commands that
+can destroy significant amounts of nontrivial data usually kill.
+
+Deletion
+--------
+
+`C-d'
+     Delete next character (`delete-char').
+
+`<DEL>'
+     Delete previous character (`delete-backward-char').
+
+`M-\'
+     Delete spaces and tabs around point (`delete-horizontal-space').
+
+`M-<SPC>'
+     Delete spaces and tabs around point, leaving one space
+     (`just-one-space').
+
+`C-x C-o'
+     Delete blank lines around the current line (`delete-blank-lines').
+
+`M-^'
+     Join two lines by deleting the intervening newline, and any
+     indentation following it (`delete-indentation').
+
+   The most basic delete commands are `C-d' (`delete-char') and <DEL>
+(`delete-backward-char').  `C-d' deletes the character after point, the
+one the cursor is "on top of".  Point doesn't move.  <DEL> deletes the
+character before the cursor, and moves point back.  You can delete
+newlines like any other characters in the buffer; deleting a newline
+joins two lines.  Actually, `C-d' and <DEL> aren't always delete
+commands; if you give them an argument, they kill instead, since they
+can erase more than one character this way.
+
+   The other delete commands delete only formatting characters: spaces,
+tabs and newlines.  `M-\' (`delete-horizontal-space') deletes all
+spaces and tab characters before and after point.  `M-<SPC>'
+(`just-one-space') does the same but leaves a single space after point,
+regardless of the number of spaces that existed previously (even zero).
+
+   `C-x C-o' (`delete-blank-lines') deletes all blank lines after the
+current line. If the current line is blank, it deletes all blank lines
+preceding the current line as well as leaving one blank line, the
+current line.  `M-^' (`delete-indentation') joins the current line and
+the previous line, or, if given an argument, joins the current line and
+the next line by deleting a newline and all surrounding spaces, possibly
+leaving a single space.  *Note M-^: Indentation.
+
+Killing by Lines
+----------------
+
+`C-k'
+     Kill rest of line or one or more lines (`kill-line').
+
+   The simplest kill command is `C-k'.  If given at the beginning of a
+line, it kills all the text on the line, leaving the line blank.  If
+given on a blank line, the blank line disappears.  As a consequence, a
+line disappears completely if you go to the front of a non-blank line
+and type `C-k' twice.
+
+   More generally, `C-k' kills from point up to the end of the line,
+unless it is at the end of a line.  In that case, it kills the newline
+following the line, thus merging the next line into the current one.
+Emacs ignores invisible spaces and tabs at the end of the line when
+deciding which case applies: if point appears to be at the end of the
+line, you can be sure the newline will be killed.
+
+   If you give `C-k' a positive argument, it kills that many lines and
+the newlines that follow them (however, text on the current line before
+point is not killed).  With a negative argument, `C-k' kills back to a
+number of line beginnings.  An argument of -2 means kill back to the
+second line beginning.  If point is at the beginning of a line, that
+line beginning doesn't count, so `C-u - 2 C-k' with point at the front
+of a line kills the two previous lines.
+
+   `C-k' with an argument of zero kills all the text before point on the
+current line.
+
+Other Kill Commands
+-------------------
+
+`C-w'
+     Kill region (from point to the mark) (`kill-region').  *Note
+     Words::.
+
+`M-d'
+     Kill word (`kill-word').
+
+`M-<DEL>'
+     Kill word backwards (`backward-kill-word').
+
+`C-x <DEL>'
+     Kill back to beginning of sentence (`backward-kill-sentence').
+     *Note Sentences::.
+
+`M-k'
+     Kill to end of sentence (`kill-sentence').
+
+`C-M-k'
+     Kill sexp (`kill-sexp').  *Note Lists::.
+
+`M-z CHAR'
+     Kill up to next occurrence of CHAR (`zap-to-char').
+
+   `C-w' (`kill-region') is a very general kill command; it kills
+everything between point and the mark. You can use this command to kill
+any contiguous sequence of characters by first setting the mark at one
+end of a sequence of characters, then going to the other end and typing
+`C-w'.
+
+   A convenient way of killing is combined with searching: `M-z'
+(`zap-to-char') reads a character and kills from point up to (but not
+including) the next occurrence of that character in the buffer.  If
+there is no next occurrence, killing goes to the end of the buffer.  A
+numeric argument acts as a repeat count.  A negative argument means to
+search backward and kill text before point.
+
+   Other syntactic units can be killed: words, with `M-<DEL>' and `M-d'
+(*note Words::); sexps, with `C-M-k' (*note Lists::); and sentences,
+with `C-x <DEL>' and `M-k' (*note Sentences::).
+
+\1f
+File: xemacs.info,  Node: Yanking,  Next: Using X Selections,  Prev: Killing,  Up: Top
+
+Yanking
+=======
+
+"Yanking" means getting back text which was killed. Some systems call
+this "pasting".  The usual way to move or copy text is to kill it and
+then yank it one or more times.
+
+`C-y'
+     Yank last killed text (`yank').
+
+`M-y'
+     Replace re-inserted killed text with the previously killed text
+     (`yank-pop').
+
+`M-w'
+     Save region as last killed text without actually killing it
+     (`copy-region-as-kill').
+
+`C-M-w'
+     Append next kill to last batch of killed text (`append-next-kill').
+
+* Menu:
+
+* Kill Ring::       Where killed text is stored.  Basic yanking.
+* Appending Kills:: Several kills in a row all yank together.
+* Earlier Kills::   Yanking something killed some time ago.
+
+\1f
+File: xemacs.info,  Node: Kill Ring,  Next: Appending Kills,  Prev: Yanking,  Up: Yanking
+
+The Kill Ring
+-------------
+
+All killed text is recorded in the "kill ring", a list of blocks of
+text that have been killed.  There is only one kill ring, used in all
+buffers, so you can kill text in one buffer and yank it in another
+buffer.  This is the usual way to move text from one file to another.
+(*Note Accumulating Text::, for some other ways.)
+
+   If you have two separate Emacs processes, you cannot use the kill
+ring to move text. If you are using XEmacs under X, however, you can
+use the X selection mechanism to move text from one to another.
+
+   If you are using XEmacs under X and have one Emacs process with
+multiple frames, they do share the same kill ring.  You can kill or
+copy text in one Emacs frame, then yank it in the other frame belonging
+to the same process.
+
+   The command `C-y' (`yank') reinserts the text of the most recent
+kill.  It leaves the cursor at the end of the text and sets the mark at
+the beginning of the text.  *Note Mark::.
+
+   `C-u C-y' yanks the text, leaves the cursor in front of the text,
+and sets the mark after it, if the argument is with just a `C-u'.  Any
+other argument, including `C-u' and digits, has different results,
+described below, under "Yanking Earlier Kills".
+
+   To copy a block of text, you can also use `M-w'
+(`copy-region-as-kill'), which copies the region into the kill ring
+without removing it from the buffer. `M-w' is similar to `C-w' followed
+by `C-y' but does not mark the buffer as "modified" and does not
+actually cut anything.
+
+\1f
+File: xemacs.info,  Node: Appending Kills,  Next: Earlier Kills,  Prev: Kill Ring,  Up: Yanking
+
+Appending Kills
+---------------
+
+Normally, each kill command pushes a new block onto the kill ring.
+However, two or more kill commands in a row combine their text into a
+single entry, so that a single `C-y' yanks it all back. This means you
+don't have to kill all the text you want to yank in one command; you
+can kill line after line, or word after word, until you have killed what
+you want, then get it all back at once using `C-y'. (Thus we join
+television in leading people to kill thoughtlessly.)
+
+   Commands that kill forward from point add onto the end of the
+previous killed text.  Commands that kill backward from point add onto
+the beginning.  This way, any sequence of mixed forward and backward
+kill commands puts all the killed text into one entry without
+rearrangement.  Numeric arguments do not break the sequence of
+appending kills.  For example, suppose the buffer contains:
+
+     This is the first
+     line of sample text
+     and here is the third.
+
+with point at the beginning of the second line.  If you type `C-k C-u 2
+M-<DEL> C-k', the first `C-k' kills the text `line of sample text',
+`C-u 2 M-<DEL>' kills `the first' with the newline that followed it,
+and the second `C-k' kills the newline after the second line.  The
+result is that the buffer contains `This is and here is the third.' and
+a single kill entry contains `the first<RET>line of sample
+text<RET>'--all the killed text, in its original order.
+
+   If a kill command is separated from the last kill command by other
+commands (not just numeric arguments), it starts a new entry on the kill
+ring.  To force a kill command to append, first type the command `C-M-w'
+(`append-next-kill'). `C-M-w' tells the following command, if it is a
+kill command, to append the text it kills to the last killed text,
+instead of starting a new entry.  With `C-M-w', you can kill several
+separated pieces of text and accumulate them to be yanked back in one
+place.
+
+\1f
+File: xemacs.info,  Node: Earlier Kills,  Prev: Appending Kills,  Up: Yanking
+
+Yanking Earlier Kills
+---------------------
+
+To recover killed text that is no longer the most recent kill, you need
+the `Meta-y' (`yank-pop') command.  You can use `M-y' only after a
+`C-y' or another `M-y'.  It takes the text previously yanked and
+replaces it with the text from an earlier kill.  To recover the text of
+the next-to-the-last kill, first use `C-y' to recover the last kill,
+then `M-y' to replace it with the previous kill.
+
+   You can think in terms of a "last yank" pointer which points at an
+item in the kill ring.  Each time you kill, the "last yank" pointer
+moves to the new item at the front of the ring.  `C-y' yanks the item
+which the "last yank" pointer points to.  `M-y' moves the "last yank"
+pointer to a different item, and the text in the buffer changes to
+match.  Enough `M-y' commands can move the pointer to any item in the
+ring, so you can get any item into the buffer.  Eventually the pointer
+reaches the end of the ring; the next `M-y' moves it to the first item
+again.
+
+   Yanking moves the "last yank" pointer around the ring, but does not
+change the order of the entries in the ring, which always runs from the
+most recent kill at the front to the oldest one still remembered.
+
+   Use `M-y' with a numeric argument to advance the "last yank" pointer
+by the specified number of items.  A negative argument moves the
+pointer toward the front of the ring; from the front of the ring, it
+moves to the last entry and starts moving forward from there.
+
+   Once the text you are looking for is brought into the buffer, you can
+stop doing `M-y' commands and the text will stay there. Since the text
+is just a copy of the kill ring item, editing it in the buffer does not
+change what's in the ring.  As long you don't kill additional text, the
+"last yank" pointer remains at the same place in the kill ring:
+repeating `C-y' will yank another copy of the same old kill.
+
+   If you know how many `M-y' commands it would take to find the text
+you want, you can yank that text in one step using `C-y' with a numeric
+argument.  `C-y' with an argument greater than one restores the text
+the specified number of entries back in the kill ring.  Thus, `C-u 2
+C-y' gets the next to the last block of killed text.  It is equivalent
+to `C-y M-y'.  `C-y' with a numeric argument starts counting from the
+"last yank" pointer, and sets the "last yank" pointer to the entry that
+it yanks.
+
+   The variable `kill-ring-max' controls the length of the kill ring;
+no more than that many blocks of killed text are saved.
+
+\1f
+File: xemacs.info,  Node: Using X Selections,  Next: Accumulating Text,  Prev: Yanking,  Up: Top
+
+Using X Selections
+==================
+
+In the X window system, mouse selections provide a simple mechanism for
+text transfer between different applications.  In a typical X
+application, you can select text by pressing the left mouse button and
+dragging the cursor over the text you want to copy.  The text becomes
+the primary X selection and is highlighted.  The highlighted region is
+also the Emacs selected region.
+
+   * Since the region is the primary X selection, you can go to a
+     different X application and click the middle mouse button: the
+     text that you selected in the previous application is pasted into
+     the current application.
+
+   * Since the region is the Emacs selected region, you can use all
+     region commands (`C-w, M-w' etc.) as well as the options of the
+     Edit menu to manipulate the selected text.
+
+* Menu:
+
+* X Clipboard Selection::      Pasting to the X clipboard.
+* X Selection Commands::       Other operations on the selection.
+* X Cut Buffers::              X cut buffers are available for compatibility.
+* Active Regions::             Using zmacs-style highlighting of the
+                                selected region.
+
+\1f
+File: xemacs.info,  Node: X Clipboard Selection,  Next: X Selection Commands,  Prev: Using X Selections,  Up: Using X Selections
+
+The Clipboard Selection
+-----------------------
+
+There are other kinds of X selections besides the Primary selection; one
+common one is the Clipboard selection.  Some applications prefer to
+transfer data using this selection in preference to the Primary.  One
+can transfer text from the Primary selection to the  Clipboard
+selection with the Copy command under the Edit menu in the menubar.
+
+   Usually, the clipboard selection is not visible.  However, if you
+run the `xclipboard' application, the text most recently copied to the
+clipboard (with the Copy command) is displayed in a window.  Any time
+new text is thus copied, the `xclipboard' application makes a copy of
+it and displays it in its window.  The value of the clipboard can
+survive the lifetime of the running Emacs process.  The `xclipboard'
+man page provides more details.
+
+   Warning: If you use the `xclipboard' application, remember that it
+maintains a list of all things that have been pasted to the clipboard
+(that is, copied with the Copy command).  If you don't manually delete
+elements from this list by clicking on the Delete button in the
+`xclipboard' window, the clipboard will eventually consume a lot of
+memory.
+
+   In summary, some X applications (such as `xterm') allow one to paste
+text in them from XEmacs in the following way:
+
+   * Drag out a region of text in Emacs with the left mouse button,
+     making that text be the Primary selection.
+
+   * Click the middle button in the other application, pasting the
+     Primary selection.
+
+   With some other applications (notably, the OpenWindows and Motif
+tools) you must use this method instead:
+
+   * Drag out a region of text in Emacs with the left mouse button,
+     making that text be the Primary selection.
+
+   * Copy the selected text to the Clipboard selection by selecting the
+     Copy menu item from the Edit menu, or by hitting the Copy key on
+     your keyboard.
+
+   * Paste the text in the other application by selecting Paste from its
+     menu, or by hitting the Paste key on your keyboard.
+
+\1f
+File: xemacs.info,  Node: X Selection Commands,  Next: X Cut Buffers,  Prev: X Clipboard Selection,  Up: Using X Selections
+
+Miscellaneous X Selection Commands
+----------------------------------
+
+`M-x x-copy-primary-selection'
+     Copy the primary selection to both the kill ring and the Clipboard.
+
+`M-x x-insert-selection'
+     Insert the current selection into the buffer at point.
+
+`M-x x-delete-primary-selection'
+     Deletes the text in the primary selection without copying it to
+     the kill ring or the Clipboard.
+
+`M-x x-kill-primary-selection'
+     Deletes the text in the primary selection and copies it to both
+     the kill ring and the Clipboard.
+
+`M-x x-mouse-kill'
+     Kill the text between point and the mouse and copy it to the
+     clipboard and to the cut buffer.
+
+`M-x x-own-secondary-selection'
+     Make a secondary X selection of the given argument.
+
+`M-x x-own-selection'
+     Make a primary X selection of the given argument.
+
+`M-x x-set-point-and-insert-selection'
+     Set point where clicked and insert the primary selection or the
+     cut buffer.
+
+\1f
+File: xemacs.info,  Node: X Cut Buffers,  Next: Active Regions,  Prev: X Selection Commands,  Up: Using X Selections
+
+X Cut Buffers
+-------------
+
+X cut buffers are a different, older way of transferring text between
+applications.  XEmacs supports cut buffers for compatibility with older
+programs, even though selections are now the preferred way of
+transferring text.
+
+   X has a concept of applications "owning" selections.  When you select
+text by clicking and dragging inside an application, the application
+tells the X server that it owns the selection.  When another
+application asks the X server for the value of the selection, the X
+server requests the information from the owner. When you use
+selections, the selection data is not actually transferred unless
+someone wants it; the act of making a selection doesn't transfer data.
+Cut buffers are different: when you "own" a cut buffer, the data is
+actually transferred to the X server immediately, and survives the
+lifetime of the application.
+
+   Any time a region of text becomes the primary selection in Emacs,
+Emacs also copies that text to the cut buffer.  This makes it possible
+to copy text from an XEmacs buffer and paste it into an older,
+non-selection-based application (such as Emacs 18).
+
+   Note: Older versions of Emacs could not access the X selections, only
+the X cut buffers.
+
+\1f
+File: xemacs.info,  Node: Active Regions,  Prev: X Cut Buffers,  Up: Using X Selections
+
+Active Regions
+--------------
+
+By default, both the text you select in an Emacs buffer using the
+click-and-drag mechanism and text you select by setting point and the
+mark is highlighted. You can use Emacs region commands as well as the
+Cut and Copy commands on the highlighted region you selected with the
+mouse.
+
+   If you prefer, you can make a distinction between text selected with
+the mouse and text selected with point and the mark by setting the
+variable `zmacs-regions' to `nil'.  In that case:
+
+   * The text selected with the mouse becomes both the X selection and
+     the Emacs selected region. You can use menu-bar commands as well
+     as Emacs region commands on it.
+
+   * The text selected with point and the mark is not highlighted. You
+     can only use Emacs region commands on it, not the menu-bar items.
+
+   Active regions originally come from Zmacs, the Lisp Machine editor.
+The idea behind them is that commands can only operate on a region when
+the region is in an "active" state.  Put simply, you can only operate on
+a region that is highlighted.
+
+   The variable `zmacs-regions' checks whether LISPM-style active
+regions should be used.  This means that commands that operate on the
+region (the area between point and the mark) only work while the region
+is in the active state, which is indicated by highlighting.  Most
+commands causes the region to not be in the active state; for example,
+`C-w' only works immediately after activating the region.
+
+   More specifically:
+   * Commands that operate on the region only work if the region is
+     active.
+
+   * Only a very small set of commands causes the region to become
+     active-- those commands whose semantics are to mark an area, such
+     as `mark-defun'.
+
+   * The region is deactivated after each command that is executed,
+     except that motion commands do not change whether the region is
+     active or not.
+
+   `set-mark-command' (`C-SPC') pushes a mark and activates the region.
+Moving the cursor with normal motion commands (`C-n', `C-p', etc.)
+will cause the region between point and the recently-pushed mark to be
+highlighted.  It will remain highlighted until some non-motion command
+is executed.
+
+   `exchange-point-and-mark' (`C-x C-x') activates the region.  So if
+you mark a region and execute a command that operates on it, you can
+reactivate the same region with `C-x C-x' (or perhaps `C-x C-x C-x
+C-x') to operate on it again.
+
+   Generally, commands that push marks as a means of navigation, such as
+`beginning-of-buffer' (`M-<') and `end-of-buffer' (`M->'), do not
+activate the region.  However, commands that push marks as a means of
+marking an area of text, such as `mark-defun' (`M-C-h'), `mark-word'
+(`M-@'), and `mark-whole-buffer' (`C-x h'), do activate the region.
+
+   When `zmacs-regions' is `t', there is no distinction between the
+primary X selection and the active region selected by point and the
+mark.  To see this, set the mark (<C-SPC>) and move the cursor with any
+cursor-motion command: the region between point and mark is
+highlighted, and you can watch it grow and shrink as you move the
+cursor.
+
+   Any other commands besides cursor-motion commands (such as inserting
+or deleting text) will cause the region to no longer be active; it will
+no longer be highlighted, and will no longer be the primary selection.
+Region can be explicitly deactivated with `C-g'.
+
+   Commands that require a region (such as `C-w') signal an error if
+the region is not active.  Certain commands cause the region to be in
+its active state.  The most common ones are `push-mark' (<C-SPC>) and
+`exchange-point-and-mark' (`C-x C-x').
+
+   When `zmacs-regions' is `t', programs can be non-intrusive on the
+state of the region by setting the variable `zmacs-region-stays' to a
+non-`nil' value.  If you are writing a new Emacs command that is
+conceptually a "motion" command and should not interfere with the
+current highlightedness of the region, then you may set this variable.
+It is reset to `nil' after each user command is executed.
+
+   When `zmacs-regions' is `t', programs can make the region between
+point and mark go into the active (highlighted) state by using the
+function `zmacs-activate-region'. Only a small number of commands
+should ever do this.
+
+   When `zmacs-regions' is `t', programs can deactivate the region
+between point and the mark by using `zmacs-deactivate-region'.  Note:
+you should not have to call this function; the command loop calls it
+when appropriate.
+
+\1f
+File: xemacs.info,  Node: Accumulating Text,  Next: Rectangles,  Prev: Using X Selections,  Up: Top
+
+Accumulating Text
+=================
+
+Usually you copy or move text by killing it and yanking it, but there
+are other ways that are useful for copying one block of text in many
+places, or for copying many scattered blocks of text into one place.
+
+   If you like, you can accumulate blocks of text from scattered
+locations either into a buffer or into a file.  The relevant commands
+are described here.  You can also use Emacs registers for storing and
+accumulating text.  *Note Registers::.
+
+`M-x append-to-buffer'
+     Append region to contents of specified buffer (`append-to-buffer').
+
+`M-x prepend-to-buffer'
+     Prepend region to contents of specified buffer.
+
+`M-x copy-to-buffer'
+     Copy region into specified buffer, deleting that buffer's old
+     contents.
+
+`M-x insert-buffer'
+     Insert contents of specified buffer into current buffer at point.
+
+`M-x append-to-file'
+     Append region to the end of the contents of specified file.
+
+   To accumulate text into a buffer, use the command `M-x
+append-to-buffer', which inserts a copy of the region into the buffer
+BUFFERNAME, at the location of point in that buffer.  If there is no
+buffer with the given name, one is created.
+
+   If you append text to a buffer that has been used for editing, the
+copied text goes to the place where point is.  Point in that buffer is
+left at the end of the copied text, so successive uses of
+`append-to-buffer' accumulate the text in the specified buffer in the
+same order as they were copied.  Strictly speaking, this command does
+not always append to the text already in the buffer; but if this command
+is the only command used to alter a buffer, it does always append to the
+existing text because point is always at the end.
+
+   `M-x prepend-to-buffer' is similar to `append-to-buffer', but point
+in the other buffer is left before the copied text, so successive
+prependings add text in reverse order.  `M-x copy-to-buffer' is
+similar, except that any existing text in the other buffer is deleted,
+so the buffer is left containing just the text newly copied into it.
+
+   You can retrieve the accumulated text from that buffer with `M-x
+insert-buffer', which takes BUFFERNAME as an argument.  It inserts a
+copy of the text in buffer BUFFERNAME into the selected buffer.  You
+could alternatively select the other buffer for editing, perhaps moving
+text from it by killing or with `append-to-buffer'.  *Note Buffers::,
+for background information on buffers.
+
+   Instead of accumulating text within Emacs in a buffer, you can append
+text directly into a file with `M-x append-to-file', which takes
+FILE-NAME as an argument.  It adds the text of the region to the end of
+the specified file.  The file is changed immediately on disk.  This
+command is normally used with files that are not being visited in
+Emacs.  Using it on a file that Emacs is visiting can produce confusing
+results, because the file's text inside Emacs does not change while the
+file itself changes.
+
+\1f
+File: xemacs.info,  Node: Rectangles,  Next: Registers,  Prev: Accumulating Text,  Up: Top
+
+Rectangles
+==========
+
+The rectangle commands affect rectangular areas of text: all characters
+between a certain pair of columns, in a certain range of lines.
+Commands are provided to kill rectangles, yank killed rectangles, clear
+them out, or delete them.  Rectangle commands are useful with text in
+multicolumnar formats, like code with comments at the right, or for
+changing text into or out of such formats.
+
+   To specify the rectangle a command should work on, put the mark at
+one corner and point at the opposite corner.  The specified rectangle is
+called the "region-rectangle" because it is controlled about the same
+way the region is controlled.  Remember that a given combination of
+point and mark values can be interpreted either as specifying a region
+or as specifying a rectangle; it is up to the command that uses them to
+choose the interpretation.
+
+`M-x delete-rectangle'
+     Delete the text of the region-rectangle, moving any following text
+     on each line leftward to the left edge of the region-rectangle.
+
+`M-x kill-rectangle'
+     Similar, but also save the contents of the region-rectangle as the
+     "last killed rectangle".
+
+`M-x yank-rectangle'
+     Yank the last killed rectangle with its upper left corner at point.
+
+`M-x open-rectangle'
+     Insert blank space to fill the space of the region-rectangle.  The
+     previous contents of the region-rectangle are pushed rightward.
+
+`M-x clear-rectangle'
+     Clear the region-rectangle by replacing its contents with spaces.
+
+   The rectangle operations fall into two classes: commands deleting and
+moving rectangles, and commands for blank rectangles.
+
+   There are two ways to get rid of the text in a rectangle: you can
+discard the text (delete it) or save it as the "last killed" rectangle.
+The commands for these two ways are `M-x delete-rectangle' and `M-x
+kill-rectangle'.  In either case, the portion of each line that falls
+inside the rectangle's boundaries is deleted, causing following text
+(if any) on the line to move left.
+
+   Note that "killing" a rectangle is not killing in the usual sense;
+the rectangle is not stored in the kill ring, but in a special place
+that only records the most recently killed rectangle (that is, does not
+append to a killed rectangle).  Different yank commands have to be used
+and only one rectangle is stored, because yanking a rectangle is quite
+different from yanking linear text and yank-popping commands are
+difficult to make sense of.
+
+   Inserting a rectangle is the opposite of deleting one.  You specify
+where to put the upper left corner by putting point there.  The
+rectangle's first line is inserted at point, the rectangle's second line
+is inserted at a point one line vertically down, and so on.  The number
+of lines affected is determined by the height of the saved rectangle.
+
+   To insert the last killed rectangle, type `M-x yank-rectangle'.
+This can be used to convert single-column lists into double-column
+lists; kill the second half of the list as a rectangle and then yank it
+beside the first line of the list.
+
+   There are two commands for working with blank rectangles: `M-x
+clear-rectangle' erases existing text, and `M-x open-rectangle' inserts
+a blank rectangle.  Clearing a rectangle is equivalent to deleting it
+and then inserting a blank rectangle of the same size.
+
+   Rectangles can also be copied into and out of registers.  *Note
+Rectangle Registers: RegRect.
+
+\1f
+File: xemacs.info,  Node: Registers,  Next: Display,  Prev: Rectangles,  Up: Top
+
+Registers
+*********
+
+XEmacs "registers" are places in which you can save text or positions
+for later use.  Once you save text or a rectangle in a register, you
+can copy it into the buffer once or many times; a position saved in a
+register is used by moving point to that position.  Rectangles can also
+be copied into and out of registers (*note Rectangles::).
+
+   Each register has a name which is a single character.  A register can
+store a piece of text, a rectangle, a position, a window configuration,
+or a file name, but only one thing at any given time.  Whatever you
+store in a register remains there until you store something else in that
+register.  To see what a register R contains, use `M-x view-register'.
+
+`M-x view-register <RET> R'
+     Display a description of what register R contains.
+
+   `M-x view-register' reads a register name as an argument and then
+displays the contents of the specified register.
+
+* Menu:
+
+* Position: RegPos.           Saving positions in registers.
+* Text: RegText.              Saving text in registers.
+* Rectangle: RegRect.         Saving rectangles in registers.
+* Configurations: RegConfig.  Saving window configurations in registers.
+* Files: RegFiles.            File names in registers.
+* Numbers: RegNumbers.        Numbers in registers.
+* Bookmarks::                 Bookmarks are like registers, but persistent.
+
+\1f
+File: xemacs.info,  Node: RegPos,  Next: RegText,  Prev: Registers,  Up: Registers
+
+Saving Positions in Registers
+=============================
+
+Saving a position records a place in a buffer so that you can move back
+there later.  Moving to a saved position switches to that buffer and
+moves point to that place in it.
+
+`C-x r <SPC> R'
+     Save position of point in register R (`point-to-register').
+
+`C-x r j R'
+     Jump to the position saved in register R (`jump-to-register').
+
+   To save the current position of point in a register, choose a name R
+and type `C-x r <SPC> R'.  The register R retains the position thus
+saved until you store something else in that register.
+
+   The command `C-x r j R' moves point to the position recorded in
+register R.  The register is not affected; it continues to record the
+same location.  You can jump to the same position using the same
+register as often as you want.
+
+   If you use `C-x r j' to go to a saved position, but the buffer it
+was saved from has been killed, `C-x r j' tries to create the buffer
+again by visiting the same file.  Of course, this works only for buffers
+that were visiting files.
+
+\1f
+File: xemacs.info,  Node: RegText,  Next: RegRect,  Prev: RegPos,  Up: Registers
+
+Saving Text in Registers
+========================
+
+When you want to insert a copy of the same piece of text many times, it
+can be impractical to use the kill ring, since each subsequent kill
+moves the piece of text further down on the ring.  It becomes hard to
+keep track of the argument needed to retrieve the same text with `C-y'.
+An alternative is to store the text in a register with `C-x r s'
+(`copy-to-register') and then retrieve it with `C-x r i'
+(`insert-register').
+
+`C-x r s R'
+     Copy region into register R (`copy-to-register').
+
+`C-x r g R'
+`C-x r i R'
+     Insert text contents of register R (`insert-register').
+
+   `C-x r s R' stores a copy of the text of the region into the
+register named R.  Given a numeric argument, `C-x r s R' deletes the
+text from the buffer as well.
+
+   `C-x r i R' inserts the text from register R in the buffer.  By
+default it leaves point before the text and places the mark after it.
+With a numeric argument (`C-u'), it puts point after the text and the
+mark before it.
+
+\1f
+File: xemacs.info,  Node: RegRect,  Next: RegConfig,  Prev: RegText,  Up: Registers
+
+Saving Rectangles in Registers
+==============================
+
+A register can contain a rectangle instead of lines of text.  The
+rectangle is represented as a list of strings.  *Note Rectangles::, for
+basic information on rectangles and how to specify rectangles in a
+buffer.
+
+`C-x r r R'
+     Copy the region-rectangle into register R
+     (`copy-rectangle-to-register').  With a numeric argument, delete it
+     as well.
+
+`C-x r g R'
+`C-x r i R'
+     Insert the rectangle stored in register R (if it contains a
+     rectangle) (`insert-register').
+
+   The `C-x r i R' command inserts linear text if the register
+contains that, or inserts a rectangle if the register contains one.
+
+   See also the command `sort-columns', which you can think of as
+sorting a rectangle.  *Note Sorting::.
+
+\1f
+File: xemacs.info,  Node: RegConfig,  Next: RegNumbers,  Prev: RegRect,  Up: Registers
+
+Saving Window Configurations in Registers
+=========================================
+
+You can save the window configuration of the selected frame in a
+register, or even the configuration of all windows in all frames, and
+restore the configuration later.
+
+`C-x r w R'
+     Save the state of the selected frame's windows in register R
+     (`window-configuration-to-register').
+
+`M-x frame-configuration-to-register <RET> R'
+     Save the state of all frames, including all their windows, in
+     register R (`frame-configuration-to-register').
+
+   Use `C-x r j R' to restore a window or frame configuration.  This is
+the same command used to restore a cursor position.  When you restore a
+frame configuration, any existing frames not included in the
+configuration become invisible.  If you wish to delete these frames
+instead, use `C-u C-x r j R'.
+
+\1f
+File: xemacs.info,  Node: RegNumbers,  Next: RegFiles,  Prev: RegConfig,  Up: Registers
+
+Keeping Numbers in Registers
+============================
+
+There are commands to store a number in a register, to insert the
+number in the buffer in decimal, and to increment it.  These commands
+can be useful in keyboard macros (*note Keyboard Macros::).
+
+`C-u NUMBER C-x r n REG'
+     Store NUMBER into register REG (`number-to-register').
+
+`C-u NUMBER C-x r + REG'
+     Increment the number in register REG by NUMBER
+     (`increment-register').
+
+`C-x r g REG'
+     Insert the number from register REG into the buffer.
+
+   `C-x r g' is the same command used to insert any other sort of
+register contents into the buffer.
+
+\1f
+File: xemacs.info,  Node: RegFiles,  Next: Bookmarks,  Prev: RegNumbers,  Up: Registers
+
+Keeping File Names in Registers
+===============================
+
+If you visit certain file names frequently, you can visit them more
+conveniently if you put their names in registers.  Here's the Lisp code
+used to put a file name in a register:
+
+     (set-register ?R '(file . NAME))
+
+For example,
+
+     (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog"))
+
+puts the file name shown in register `z'.
+
+   To visit the file whose name is in register R, type `C-x r j R'.
+(This is the same command used to jump to a position or restore a frame
+configuration.)
+
+\1f
+File: xemacs.info,  Node: Bookmarks,  Prev: RegFiles,  Up: Registers
+
+Bookmarks
+=========
+
+"Bookmarks" are somewhat like registers in that they record positions
+you can jump to.  Unlike registers, they have long names, and they
+persist automatically from one Emacs session to the next.  The
+prototypical use of bookmarks is to record "where you were reading" in
+various files.
+
+   Note: bookmark.el is distributed in edit-utils package.  You need to
+install that to use bookmark facility (*note Packages::).
+
+`C-x r m <RET>'
+     Set the bookmark for the visited file, at point.
+
+`C-x r m BOOKMARK <RET>'
+     Set the bookmark named BOOKMARK at point (`bookmark-set').
+
+`C-x r b BOOKMARK <RET>'
+     Jump to the bookmark named BOOKMARK (`bookmark-jump').
+
+`C-x r l'
+     List all bookmarks (`list-bookmarks').
+
+`M-x bookmark-save'
+     Save all the current bookmark values in the default bookmark file.
+
+   The prototypical use for bookmarks is to record one current position
+in each of several files.  So the command `C-x r m', which sets a
+bookmark, uses the visited file name as the default for the bookmark
+name.  If you name each bookmark after the file it points to, then you
+can conveniently revisit any of those files with `C-x r b', and move to
+the position of the bookmark at the same time.
+
+   To display a list of all your bookmarks in a separate buffer, type
+`C-x r l' (`list-bookmarks').  If you switch to that buffer, you can
+use it to edit your bookmark definitions or annotate the bookmarks.
+Type `C-h m' in that buffer for more information about its special
+editing commands.
+
+   When you kill XEmacs, XEmacs offers to save your bookmark values in
+your default bookmark file, `~/.emacs.bmk', if you have changed any
+bookmark values.  You can also save the bookmarks at any time with the
+`M-x bookmark-save' command.  The bookmark commands load your default
+bookmark file automatically.  This saving and loading is how bookmarks
+persist from one XEmacs session to the next.
+
+   If you set the variable `bookmark-save-flag' to 1, then each command
+that sets a bookmark will also save your bookmarks; this way, you don't
+lose any bookmark values even if XEmacs crashes.  (The value, if a
+number, says how many bookmark modifications should go by between
+saving.)
+
+   Bookmark position values are saved with surrounding context, so that
+`bookmark-jump' can find the proper position even if the file is
+modified slightly.  The variable `bookmark-search-size' says how many
+characters of context to record, on each side of the bookmark's
+position.
+
+   Here are some additional commands for working with bookmarks:
+
+`M-x bookmark-load <RET> FILENAME <RET>'
+     Load a file named FILENAME that contains a list of bookmark
+     values.  You can use this command, as well as `bookmark-write', to
+     work with other files of bookmark values in addition to your
+     default bookmark file.
+
+`M-x bookmark-write <RET> FILENAME <RET>'
+     Save all the current bookmark values in the file FILENAME.
+
+`M-x bookmark-delete <RET> BOOKMARK <RET>'
+     Delete the bookmark named BOOKMARK.
+
+`M-x bookmark-insert-location <RET> BOOKMARK <RET>'
+     Insert in the buffer the name of the file that bookmark BOOKMARK
+     points to.
+
+`M-x bookmark-insert <RET> BOOKMARK <RET>'
+     Insert in the buffer the _contents_ of the file that bookmark
+     BOOKMARK points to.
+
+\1f
+File: xemacs.info,  Node: Display,  Next: Search,  Prev: Registers,  Up: Top
+
+Controlling the Display
+***********************
+
+Since only part of a large buffer fits in the window, XEmacs tries to
+show the part that is likely to be interesting.  The display control
+commands allow you to specify which part of the text you want to see.
+
+`C-l'
+     Clear frame and redisplay, scrolling the selected window to center
+     point vertically within it (`recenter').
+
+`C-v'
+`pgdn'
+`next'
+     Scroll forward (a windowful or a specified number of lines)
+     (`scroll-up').  On most X keyboards, you can get this
+     functionality using the key labelled `Page Down', which generates
+     either `next' or `pgdn'.
+
+`M-v'
+`pgup'
+`prior'
+     Scroll backward (`scroll-down').  On most X keyboards, you can get
+     this functionality using the key labelled `Page Up', which
+     generates either `prior' or `pgup'.
+
+`ARG C-l'
+     Scroll so point is on line ARG (`recenter').
+
+`C-x <'
+`C-pgdn'
+`C-next'
+     Scroll text in current window to the left (`scroll-left').
+
+`C-x >'
+`C-pgup'
+`C-prior'
+     Scroll to the right (`scroll-right').
+
+`C-x $'
+     Make deeply indented lines invisible (`set-selective-display').
+
+* Menu:
+
+* Scrolling::             Moving text up and down in a window.
+* Horizontal Scrolling::   Moving text left and right in a window.
+* Selective Display::      Hiding lines with lots of indentation.
+* Display Vars::           Information on variables for customizing display.
+
+\1f
+File: xemacs.info,  Node: Scrolling,  Next: Horizontal Scrolling,  Prev: Display,  Up: Display
+
+Scrolling
+=========
+
+If a buffer contains text that is too large to fit entirely within the
+window that is displaying the buffer, XEmacs shows a contiguous section
+of the text.  The section shown always contains point.
+
+   "Scrolling" means moving text up or down in the window so that
+different parts of the text are visible.  Scrolling forward means that
+text moves up, and new text appears at the bottom.  Scrolling backward
+moves text down and new text appears at the top.
+
+   Scrolling happens automatically if you move point past the bottom or
+top of the window.  You can also explicitly request scrolling with the
+commands in this section.
+
+`C-l'
+     Clear frame and redisplay, scrolling the selected window to center
+     point vertically within it (`recenter').
+
+`C-v'
+`pgdn'
+`next'
+     Scroll forward (a windowful or a specified number of lines)
+     (`scroll-up').
+
+`M-v'
+`pgup'
+`prior'
+     Scroll backward (`scroll-down').
+
+`ARG C-l'
+     Scroll so point is on line ARG (`recenter').
+
+   The most basic scrolling command is `C-l' (`recenter') with no
+argument.  It clears the entire frame and redisplays all windows.  In
+addition, it scrolls the selected window so that point is halfway down
+from the top of the window.
+
+   The scrolling commands `C-v' and `M-v' let you move all the text in
+the window up or down a few lines.  `C-v' (`scroll-up') with an
+argument shows you that many more lines at the bottom of the window,
+moving the text and point up together as `C-l' might.  `C-v' with a
+negative argument shows you more lines at the top of the window.
+`Meta-v' (`scroll-down') is like `C-v', but moves in the opposite
+direction.
+
+   To read the buffer a windowful at a time, use `C-v' with no
+argument.  `C-v' takes the last two lines at the bottom of the window
+and puts them at the top, followed by nearly a whole windowful of lines
+not previously visible.  Point moves to the new top of the window if it
+was in the text scrolled off the top.  `M-v' with no argument moves
+backward with similar overlap.  The number of lines of overlap across a
+`C-v' or `M-v' is controlled by the variable
+`next-screen-context-lines'; by default, it is two.
+
+   Another way to scroll is using `C-l' with a numeric argument.  `C-l'
+does not clear the frame when given an argument; it only scrolls the
+selected window.  With a positive argument N, `C-l' repositions text to
+put point N lines down from the top.  An argument of zero puts point on
+the very top line.  Point does not move with respect to the text;
+rather, the text and point move rigidly on the frame.  `C-l' with a
+negative argument puts point that many lines from the bottom of the
+window.  For example, `C-u - 1 C-l' puts point on the bottom line, and
+`C-u - 5 C-l' puts it five lines from the bottom.  Just `C-u' as
+argument, as in `C-u C-l', scrolls point to the center of the frame.
+
+   Scrolling happens automatically if point has moved out of the visible
+portion of the text when it is time to display.  Usually scrolling is
+done  to put point vertically centered within the window.  However, if
+the variable `scroll-step' has a non-zero value, an attempt is made to
+scroll the buffer by that many lines; if that is enough to bring point
+back into visibility, that is what happens.
+
+   Scrolling happens automatically if point has moved out of the visible
+portion of the text when it is time to display.  Usually scrolling is
+done  to put point vertically centered within the window.  However, if
+the variable `scroll-step' has a non-zero value, an attempt is made to
+scroll the buffer by that many lines; if that is enough to bring point
+back into visibility, that is what happens.
+
+   If you set `scroll-step' to a small value because you want to use
+arrow keys to scroll the screen without recentering, the redisplay
+preemption will likely make XEmacs keep recentering the screen when
+scrolling fast, regardless of `scroll-step'.  To prevent this, set
+`scroll-conservatively' to a small value, which will have the result of
+overriding the redisplay preemption.
+
+\1f
+File: xemacs.info,  Node: Horizontal Scrolling,  Prev: Scrolling,  Up: Display
+
+Horizontal Scrolling
+====================
+
+`C-x <'
+     Scroll text in current window to the left (`scroll-left').
+
+`C-x >'
+     Scroll to the right (`scroll-right').
+
+The text in a window can also be scrolled horizontally.  This means that
+each line of text is shifted sideways in the window, and one or more
+characters at the beginning of each line are not displayed at all.
+When a window has been scrolled horizontally in this way, text lines
+are truncated rather than continued (*note Continuation Lines::), with
+a `$' appearing in the first column when there is text truncated to the
+left, and in the last column when there is text truncated to the right.
+
+   The command `C-x <' (`scroll-left') scrolls the selected window to
+the left by N columns with argument N.  With no argument, it scrolls by
+almost the full width of the window (two columns less, to be precise).
+`C-x >' (`scroll-right') scrolls similarly to the right.  The window
+cannot be scrolled any farther to the right once it is displaying
+normally (with each line starting at the window's left margin);
+attempting to do so has no effect.
+
+\1f
+File: xemacs.info,  Node: Selective Display,  Next: Display Vars,  Prev: Display,  Up: Display
+
+Selective Display
+=================
+
+XEmacs can hide lines indented more than a certain number of columns
+(you specify how many columns).  This allows you  to get an overview of
+a part of a program.
+
+   To hide lines, type `C-x $' (`set-selective-display') with a numeric
+argument N.  (*Note Arguments::, for information on giving the
+argument.)  Lines with at least N columns of indentation disappear from
+the screen.  The only indication of their presence are three dots
+(`...'), which appear at the end of each visible line that is followed
+by one or more invisible ones.
+
+   The invisible lines are still present in the buffer, and most editing
+commands see them as usual, so it is very easy to put point in the
+middle of invisible text.  When this happens, the cursor appears at the
+end of the previous line, after the three dots.  If point is at the end
+of the visible line, before the newline that ends it, the cursor
+appears before the three dots.
+
+   The commands `C-n' and `C-p' move across the invisible lines as if
+they were not there.
+
+   To make everything visible again, type `C-x $' with no argument.
+
+\1f
+File: xemacs.info,  Node: Display Vars,  Prev: Selective Display,  Up: Display
+
+Variables Controlling Display
+=============================
+
+This section contains information for customization only.  Beginning
+users should skip it.
+
+   When you reenter XEmacs after suspending, XEmacs normally clears the
+screen and redraws the entire display.  On some terminals with more than
+one page of memory, it is possible to arrange the termcap entry so that
+the `ti' and `te' strings (output to the terminal when XEmacs is
+entered and exited, respectively) switch between pages of memory so as
+to use one page for XEmacs and another page for other output.  In that
+case, you might want to set the variable `no-redraw-on-reenter' to
+non-`nil' so that XEmacs will assume, when resumed, that the screen
+page it is using still contains what XEmacs last wrote there.
+
+   The variable `echo-keystrokes' controls the echoing of
+multi-character keys; its value is the number of seconds of pause
+required to cause echoing to start, or zero, meaning don't echo at all.
+*Note Echo Area::.
+
+   If the variable `ctl-arrow' is `nil', control characters in the
+buffer are displayed with octal escape sequences, all except newline and
+tab.  If its value is `t', then control characters will be printed with
+an up-arrow, for example `^A'.
+
+   If its value is not `t' and not `nil', then characters whose code is
+greater than 160 (that is, the space character (32) with its high bit
+set) will be assumed to be printable, and will be displayed without
+alteration.  This is the default when running under X Windows, since
+XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
+The `ctl-arrow' variable may also be set to an integer, in which case
+all characters whose codes are greater than or equal to that value will
+be assumed to be printable.
+
+   Altering the value of `ctl-arrow' makes it local to the current
+buffer; until that time, the default value is in effect.  *Note
+Locals::.
+
+   Normally, a tab character in the buffer is displayed as whitespace
+which extends to the next display tab stop position, and display tab
+stops come at intervals equal to eight spaces.  The number of spaces
+per tab is controlled by the variable `tab-width', which is made local
+by changing it, just like `ctl-arrow'.  Note that how the tab character
+in the buffer is displayed has nothing to do with the definition of
+<TAB> as a command.
+
+   If you set the variable `selective-display-ellipses' to `nil', the
+three dots at the end of a line that precedes invisible lines do not
+appear.  There is no visible indication of the invisible lines.  This
+variable becomes local automatically when set.
+
+\1f
+File: xemacs.info,  Node: Search,  Next: Fixit,  Prev: Display,  Up: Top
+
+Searching and Replacement
+*************************
+
+Like other editors, Emacs has commands for searching for occurrences of
+a string.  The principal search command is unusual in that it is
+"incremental": it begins to search before you have finished typing the
+search string.  There are also non-incremental search commands more like
+those of other editors.
+
+   Besides the usual `replace-string' command that finds all
+occurrences of one string and replaces them with another, Emacs has a
+fancy replacement command called `query-replace' which asks
+interactively which occurrences to replace.
+
+* Menu:
+
+* Incremental Search::     Search happens as you type the string.
+* Non-Incremental Search:: Specify entire string and then search.
+* Word Search::            Search for sequence of words.
+* Regexp Search::          Search for match for a regexp.
+* Regexps::                Syntax of regular expressions.
+* Search Case::            To ignore case while searching, or not.
+* Replace::                Search, and replace some or all matches.
+* Other Repeating Search:: Operating on all matches for some regexp.
+
+\1f
+File: xemacs.info,  Node: Incremental Search,  Next: Non-Incremental Search,  Prev: Search,  Up: Search
+
+Incremental Search
+==================
+
+An incremental search begins searching as soon as you type the first
+character of the search string.  As you type in the search string, Emacs
+shows you where the string (as you have typed it so far) is found.
+When you have typed enough characters to identify the place you want,
+you can stop.  Depending on what you do next, you may or may not need to
+terminate the search explicitly with a <RET>.
+
+`C-s'
+     Incremental search forward (`isearch-forward').
+
+`C-r'
+     Incremental search backward (`isearch-backward').
+
+   `C-s' starts an incremental search.  `C-s' reads characters from the
+keyboard and positions the cursor at the first occurrence of the
+characters that you have typed.  If you type `C-s' and then `F', the
+cursor moves right after the first `F'.  Type an `O', and see the
+cursor move to after the first `FO'.  After another `O', the cursor is
+after the first `FOO' after the place where you started the search.
+Meanwhile, the search string `FOO' has been echoed in the echo area.
+
+   The echo area display ends with three dots when actual searching is
+going on.  When search is waiting for more input, the three dots are
+removed.  (On slow terminals, the three dots are not displayed.)
+
+   If you make a mistake in typing the search string, you can erase
+characters with <DEL>.  Each <DEL> cancels the last character of the
+search string.  This does not happen until Emacs is ready to read
+another input character; first it must either find, or fail to find,
+the character you want to erase.  If you do not want to wait for this
+to happen, use `C-g' as described below.
+
+   When you are satisfied with the place you have reached, you can type
+<RET> (or <C-m>), which stops searching, leaving the cursor where the
+search brought it.  Any command not specially meaningful in searches
+also stops the search and is then executed.  Thus, typing `C-a' exits
+the search and then moves to the beginning of the line.  <RET> is
+necessary only if the next command you want to type is a printing
+character, <DEL>, <ESC>, or another control character that is special
+within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
+
+   Sometimes you search for `FOO' and find it, but were actually
+looking for a different occurrence of it.  To move to the next
+occurrence of the search string, type another `C-s'.  Do this as often
+as necessary.  If you overshoot, you can cancel some `C-s' characters
+with <DEL>.
+
+   After you exit a search, you can search for the same string again by
+typing just `C-s C-s': the first `C-s' is the key that invokes
+incremental search, and the second `C-s' means "search again".
+
+   If the specified string is not found at all, the echo area displays
+the text `Failing I-Search'.  The cursor is after the place where Emacs
+found as much of your string as it could.  Thus, if you search for
+`FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
+`FOOL'.  At this point there are several things you can do.  If you
+mistyped the search string, correct it.  If you like the place you have
+found, you can type <RET> or some other Emacs command to "accept what
+the search offered".  Or you can type `C-g', which removes from the
+search string the characters that could not be found (the `T' in
+`FOOT'), leaving those that were found (the `FOO' in `FOOT').  A second
+`C-g' at that point cancels the search entirely, returning point to
+where it was when the search started.
+
+   If a search is failing and you ask to repeat it by typing another
+`C-s', it starts again from the beginning of the buffer.  Repeating a
+failing backward search with `C-r' starts again from the end.  This is
+called "wrapping around".  `Wrapped' appears in the search prompt once
+this has happened.
+
+   The `C-g' "quit" character does special things during searches; just
+what it does depends on the status of the search.  If the search has
+found what you specified and is waiting for input, `C-g' cancels the
+entire search.  The cursor moves back to where you started the search.
+If `C-g' is typed when there are characters in the search string that
+have not been found--because Emacs is still searching for them, or
+because it has failed to find them--then the search string characters
+which have not been found are discarded from the search string.  The
+search is now successful and waiting for more input, so a second `C-g'
+cancels the entire search.
+
+   To search for a control character such as `C-s' or <DEL> or <ESC>,
+you must quote it by typing `C-q' first.  This function of `C-q' is
+analogous to its meaning as an Emacs command: it causes the following
+character to be treated the way a graphic character would normally be
+treated in the same context.
+
+   To search backwards, you can use `C-r' instead of `C-s' to start the
+search; `C-r' is the key that runs the command (`isearch-backward') to
+search backward.  You can also use `C-r' to change from searching
+forward to searching backwards.  Do this if a search fails because the
+place you started was too far down in the file.  Repeated `C-r' keeps
+looking for more occurrences backwards.  `C-s' starts going forward
+again.  You can cancel `C-r' in a search with <DEL>.
+
+   The characters `C-y' and `C-w' can be used in incremental search to
+grab text from the buffer into the search string.  This makes it
+convenient to search for another occurrence of text at point.  `C-w'
+copies the word after point as part of the search string, advancing
+point over that word.  Another `C-s' to repeat the search will then
+search for a string including that word.  `C-y' is similar to `C-w' but
+copies the rest of the current line into the search string.
+
+   The characters `M-p' and `M-n' can be used in an incremental search
+to recall things which you have searched for in the past.  A list of
+the last 16 things you have searched for is retained, and `M-p' and
+`M-n' let you cycle through that ring.
+
+   The character `M-<TAB>' does completion on the elements in the
+search history ring.  For example, if you know that you have recently
+searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
+If you had searched for other strings beginning with `PO' then you
+would be shown a list of them, and would need to type more to select
+one.
+
+   You can change any of the special characters in incremental search
+via the normal keybinding mechanism: simply add a binding to the
+`isearch-mode-map'.  For example, to make the character `C-b' mean
+"search backwards" while in isearch-mode, do this:
+
+     (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
+
+   These are the default bindings of isearch-mode:
+
+`DEL'
+     Delete a character from the incremental search string
+     (`isearch-delete-char').
+
+`RET'
+     Exit incremental search (`isearch-exit').
+
+`C-q'
+     Quote special characters for incremental search
+     (`isearch-quote-char').
+
+`C-s'
+     Repeat incremental search forward (`isearch-repeat-forward').
+
+`C-r'
+     Repeat incremental search backward (`isearch-repeat-backward').
+
+`C-y'
+     Pull rest of line from buffer into search string
+     (`isearch-yank-line').
+
+`C-w'
+     Pull next word from buffer into search string
+     (`isearch-yank-word').
+
+`C-g'
+     Cancels input back to what has been found successfully, or aborts
+     the isearch (`isearch-abort').
+
+`M-p'
+     Recall the previous element in the isearch history ring
+     (`isearch-ring-retreat').
+
+`M-n'
+     Recall the next element in the isearch history ring
+     (`isearch-ring-advance').
+
+`M-<TAB>'
+     Do completion on the elements in the isearch history ring
+     (`isearch-complete').
+
+
+   Any other character which is normally inserted into a buffer when
+typed is automatically added to the search string in isearch-mode.
+
+Slow Terminal Incremental Search
+--------------------------------
+
+Incremental search on a slow terminal uses a modified style of display
+that is designed to take less time.  Instead of redisplaying the buffer
+at each place the search gets to, it creates a new single-line window
+and uses that to display the line the search has found.  The
+single-line window appears as soon as point gets outside of the text
+that is already on the screen.
+
+   When the search is terminated, the single-line window is removed.
+Only at this time the window in which the search was done is
+redisplayed to show its new value of point.
+
+   The three dots at the end of the search string, normally used to
+indicate that searching is going on, are not displayed in slow style
+display.
+
+   The slow terminal style of display is used when the terminal baud
+rate is less than or equal to the value of the variable
+`search-slow-speed', initially 1200.
+
+   The number of lines to use in slow terminal search display is
+controlled by the variable `search-slow-window-lines'.  Its normal
+value is 1.
+
+\1f
+File: xemacs.info,  Node: Non-Incremental Search,  Next: Word Search,  Prev: Incremental Search,  Up: Search
+
+Non-Incremental Search
+======================
+
+Emacs also has conventional non-incremental search commands, which
+require you type the entire search string before searching begins.
+
+`C-s <RET> STRING <RET>'
+     Search for STRING.
+
+`C-r <RET> STRING <RET>'
+     Search backward for STRING.
+
+   To do a non-incremental search, first type `C-s <RET>' (or `C-s
+C-m').  This enters the minibuffer to read the search string.
+Terminate the string with <RET> to start the search.  If the string is
+not found, the search command gets an error.
+
+   By default, `C-s' invokes incremental search, but if you give it an
+empty argument, which would otherwise be useless, it invokes
+non-incremental search.  Therefore, `C-s <RET>' invokes non-incremental
+search.  `C-r <RET>' also works this way.
+
+   Forward and backward non-incremental searches are implemented by the
+commands `search-forward' and `search-backward'.  You can bind these
+commands to keys.  The reason that incremental search is programmed to
+invoke them as well is that `C-s <RET>' is the traditional sequence of
+characters used in Emacs to invoke non-incremental search.
+
+   Non-incremental searches performed using `C-s <RET>' do not call
+`search-forward' right away.  They first check if the next character is
+`C-w', which requests a word search.  *Note Word Search::.
+
+\1f
+File: xemacs.info,  Node: Word Search,  Next: Regexp Search,  Prev: Non-Incremental Search,  Up: Search
+
+Word Search
+===========
+
+Word search looks for a sequence of words without regard to how the
+words are separated.  More precisely, you type a string of many words,
+using single spaces to separate them, and the string is found even if
+there are multiple spaces, newlines or other punctuation between the
+words.
+
+   Word search is useful in editing documents formatted by text
+formatters.  If you edit while looking at the printed, formatted
+version, you can't tell where the line breaks are in the source file.
+Word search, allows you to search  without having to know the line
+breaks.
+
+`C-s <RET> C-w WORDS <RET>'
+     Search for WORDS, ignoring differences in punctuation.
+
+`C-r <RET> C-w WORDS <RET>'
+     Search backward for WORDS, ignoring differences in punctuation.
+
+   Word search is a special case of non-incremental search.  It is
+invoked with `C-s <RET> C-w' followed by the search string, which must
+always be terminated with another <RET>.  Being non-incremental, this
+search does not start until the argument is terminated.  It works by
+constructing a regular expression and searching for that.  *Note Regexp
+Search::.
+
+   You can do a backward word search with `C-r <RET> C-w'.
+
+   Forward and backward word searches are implemented by the commands
+`word-search-forward' and `word-search-backward'.  You can bind these
+commands to keys.  The reason that incremental search is programmed to
+invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
+sequence of keys for word search.
+
+\1f
+File: xemacs.info,  Node: Regexp Search,  Next: Regexps,  Prev: Word Search,  Up: Search
+
+Regular Expression Search
+=========================
+
+A "regular expression" ("regexp", for short) is a pattern that denotes
+a (possibly infinite) set of strings.  Searching for matches for a
+regexp is a powerful operation that editors on Unix systems have
+traditionally offered.
+
+   To gain a thorough understanding of regular expressions and how to
+use them to best advantage, we recommend that you study `Mastering
+Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
+1997'. (It's known as the "Hip Owls" book, because of the picture on its
+cover.)  You might also read the manuals to *Note (gawk)Top::, *Note
+(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note
+(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of
+regular expressions.
+
+   The XEmacs regular expression syntax most closely resembles that of
+`ed', or `grep', the GNU versions of which all utilize the GNU `regex'
+library.  XEmacs' version of `regex' has recently been extended with
+some Perl-like capabilities, described in the next section.
+
+   In XEmacs, you can search for the next match for a regexp either
+incrementally or not.
+
+   Incremental search for a regexp is done by typing `M-C-s'
+(`isearch-forward-regexp').  This command reads a search string
+incrementally just like `C-s', but it treats the search string as a
+regexp rather than looking for an exact match against the text in the
+buffer.  Each time you add text to the search string, you make the
+regexp longer, and the new regexp is searched for.  A reverse regexp
+search command `isearch-backward-regexp' also exists, bound to `M-C-r'.
+
+   All of the control characters that do special things within an
+ordinary incremental search have the same functionality in incremental
+regexp search.  Typing `C-s' or `C-r' immediately after starting a
+search retrieves the last incremental search regexp used: incremental
+regexp and non-regexp searches have independent defaults.
+
+   Non-incremental search for a regexp is done by the functions
+`re-search-forward' and `re-search-backward'.  You can invoke them with
+`M-x' or bind them to keys.  You can also call `re-search-forward' by
+way of incremental regexp search with `M-C-s <RET>'; similarly for
+`re-search-backward' with `M-C-r <RET>'.
+
+\1f
+File: xemacs.info,  Node: Regexps,  Next: Search Case,  Prev: Regexp Search,  Up: Search
+
+Syntax of Regular Expressions
+=============================
+
+Regular expressions have a syntax in which a few characters are special
+constructs and the rest are "ordinary".  An ordinary character is a
+simple regular expression that matches that character and nothing else.
+The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and
+`\'; no new special characters will be defined in the future.  Any
+other character appearing in a regular expression is ordinary, unless a
+`\' precedes it.
+
+   For example, `f' is not a special character, so it is ordinary, and
+therefore `f' is a regular expression that matches the string `f' and
+no other string.  (It does _not_ match the string `ff'.)  Likewise, `o'
+is a regular expression that matches only `o'.
+
+   Any two regular expressions A and B can be concatenated.  The result
+is a regular expression that matches a string if A matches some amount
+of the beginning of that string and B matches the rest of the string.
+
+   As a simple example, we can concatenate the regular expressions `f'
+and `o' to get the regular expression `fo', which matches only the
+string `fo'.  Still trivial.  To do something more powerful, you need
+to use one of the special characters.  Here is a list of them:
+
+`. (Period)'
+     is a special character that matches any single character except a
+     newline.  Using concatenation, we can make regular expressions
+     like `a.b', which matches any three-character string that begins
+     with `a' and ends with `b'.
+
+`*'
+     is not a construct by itself; it is a quantifying suffix operator
+     that means to repeat the preceding regular expression as many
+     times as possible.  In `fo*', the `*' applies to the `o', so `fo*'
+     matches one `f' followed by any number of `o's.  The case of zero
+     `o's is allowed: `fo*' does match `f'.
+
+     `*' always applies to the _smallest_ possible preceding
+     expression.  Thus, `fo*' has a repeating `o', not a repeating `fo'.
+
+     The matcher processes a `*' construct by matching, immediately, as
+     many repetitions as can be found; it is "greedy".  Then it
+     continues with the rest of the pattern.  If that fails,
+     backtracking occurs, discarding some of the matches of the
+     `*'-modified construct in case that makes it possible to match the
+     rest of the pattern.  For example, in matching `ca*ar' against the
+     string `caaar', the `a*' first tries to match all three `a's; but
+     the rest of the pattern is `ar' and there is only `r' left to
+     match, so this try fails.  The next alternative is for `a*' to
+     match only two `a's.  With this choice, the rest of the regexp
+     matches successfully.
+
+     Nested repetition operators can be extremely slow if they specify
+     backtracking loops.  For example, it could take hours for the
+     regular expression `\(x+y*\)*a' to match the sequence
+     `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'.  The slowness is because
+     Emacs must try each imaginable way of grouping the 35 `x''s before
+     concluding that none of them can work.  To make sure your regular
+     expressions run fast, check nested repetitions carefully.
+
+`+'
+     is a quantifying suffix operator similar to `*' except that the
+     preceding expression must match at least once.  It is also
+     "greedy".  So, for example, `ca+r' matches the strings `car' and
+     `caaaar' but not the string `cr', whereas `ca*r' matches all three
+     strings.
+
+`?'
+     is a quantifying suffix operator similar to `*', except that the
+     preceding expression can match either once or not at all.  For
+     example, `ca?r' matches `car' or `cr', but does not match anything
+     else.
+
+`*?'
+     works just like `*', except that rather than matching the longest
+     match, it matches the shortest match.  `*?' is known as a
+     "non-greedy" quantifier, a regexp construct borrowed from Perl.
+
+     This construct is very useful for when you want to match the text
+     inside a pair of delimiters.  For instance, `/\*.*?\*/' will match
+     C comments in a string.  This could not easily be achieved without
+     the use of a non-greedy quantifier.
+
+     This construct has not been available prior to XEmacs 20.4.  It is
+     not available in FSF Emacs.
+
+`+?'
+     is the non-greedy version of `+'.
+
+`??'
+     is the non-greedy version of `?'.
+
+`\{n,m\}'
+     serves as an interval quantifier, analogous to `*' or `+', but
+     specifies that the expression must match at least N times, but no
+     more than M times.  This syntax is supported by most Unix regexp
+     utilities, and has been introduced to XEmacs for the version 20.3.
+
+     Unfortunately, the non-greedy version of this quantifier does not
+     exist currently, although it does in Perl.
+
+`[ ... ]'
+     `[' begins a "character set", which is terminated by a `]'.  In
+     the simplest case, the characters between the two brackets form
+     the set.  Thus, `[ad]' matches either one `a' or one `d', and
+     `[ad]*' matches any string composed of just `a's and `d's
+     (including the empty string), from which it follows that `c[ad]*r'
+     matches `cr', `car', `cdr', `caddaar', etc.
+
+     The usual regular expression special characters are not special
+     inside a character set.  A completely different set of special
+     characters exists inside character sets: `]', `-' and `^'.
+
+     `-' is used for ranges of characters.  To write a range, write two
+     characters with a `-' between them.  Thus, `[a-z]' matches any
+     lower case letter.  Ranges may be intermixed freely with individual
+     characters, as in `[a-z$%.]', which matches any lower case letter
+     or `$', `%', or a period.
+
+     To include a `]' in a character set, make it the first character.
+     For example, `[]a]' matches `]' or `a'.  To include a `-', write
+     `-' as the first character in the set, or put it immediately after
+     a range.  (You can replace one individual character C with the
+     range `C-C' to make a place to put the `-'.)  There is no way to
+     write a set containing just `-' and `]'.
+
+     To include `^' in a set, put it anywhere but at the beginning of
+     the set.
+
+`[^ ... ]'
+     `[^' begins a "complement character set", which matches any
+     character except the ones specified.  Thus, `[^a-z0-9A-Z]' matches
+     all characters _except_ letters and digits.
+
+     `^' is not special in a character set unless it is the first
+     character.  The character following the `^' is treated as if it
+     were first (thus, `-' and `]' are not special there).
+
+     Note that a complement character set can match a newline, unless
+     newline is mentioned as one of the characters not to match.
+
+`^'
+     is a special character that matches the empty string, but only at
+     the beginning of a line in the text being matched.  Otherwise it
+     fails to match anything.  Thus, `^foo' matches a `foo' that occurs
+     at the beginning of a line.
+
+     When matching a string instead of a buffer, `^' matches at the
+     beginning of the string or after a newline character `\n'.
+
+`$'
+     is similar to `^' but matches only at the end of a line.  Thus,
+     `x+$' matches a string of one `x' or more at the end of a line.
+
+     When matching a string instead of a buffer, `$' matches at the end
+     of the string or before a newline character `\n'.
+
+`\'
+     has two functions: it quotes the special characters (including
+     `\'), and it introduces additional special constructs.
+
+     Because `\' quotes special characters, `\$' is a regular
+     expression that matches only `$', and `\[' is a regular expression
+     that matches only `[', and so on.
+
+
+   *Please note:* For historical compatibility, special characters are
+treated as ordinary ones if they are in contexts where their special
+meanings make no sense.  For example, `*foo' treats `*' as ordinary
+since there is no preceding expression on which the `*' can act.  It is
+poor practice to depend on this behavior; quote the special character
+anyway, regardless of where it appears.
+
+   For the most part, `\' followed by any character matches only that
+character.  However, there are several exceptions: characters that,
+when preceded by `\', are special constructs.  Such characters are
+always ordinary when encountered on their own.  Here is a table of `\'
+constructs:
+
+`\|'
+     specifies an alternative.  Two regular expressions A and B with
+     `\|' in between form an expression that matches anything that
+     either A or B matches.
+
+     Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
+
+     `\|' applies to the largest possible surrounding expressions.
+     Only a surrounding `\( ... \)' grouping can limit the grouping
+     power of `\|'.
+
+     Full backtracking capability exists to handle multiple uses of
+     `\|'.
+
+`\( ... \)'
+     is a grouping construct that serves three purposes:
+
+       1. To enclose a set of `\|' alternatives for other operations.
+          Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
+
+       2. To enclose an expression for a suffix operator such as `*' to
+          act on.  Thus, `ba\(na\)*' matches `bananana', etc., with any
+          (zero or more) number of `na' strings.
+
+       3. To record a matched substring for future reference.
+
+     This last application is not a consequence of the idea of a
+     parenthetical grouping; it is a separate feature that happens to be
+     assigned as a second meaning to the same `\( ... \)' construct
+     because there is no conflict in practice between the two meanings.
+     Here is an explanation of this feature:
+
+`\DIGIT'
+     matches the same text that matched the DIGITth occurrence of a `\(
+     ... \)' construct.
+
+     In other words, after the end of a `\( ... \)' construct.  the
+     matcher remembers the beginning and end of the text matched by that
+     construct.  Then, later on in the regular expression, you can use
+     `\' followed by DIGIT to match that same text, whatever it may
+     have been.
+
+     The strings matching the first nine `\( ... \)' constructs
+     appearing in a regular expression are assigned numbers 1 through 9
+     in the order that the open parentheses appear in the regular
+     expression.  So you can use `\1' through `\9' to refer to the text
+     matched by the corresponding `\( ... \)' constructs.
+
+     For example, `\(.*\)\1' matches any newline-free string that is
+     composed of two identical halves.  The `\(.*\)' matches the first
+     half, which may be anything, but the `\1' that follows must match
+     the same exact text.
+
+`\(?: ... \)'
+     is called a "shy" grouping operator, and it is used just like `\(
+     ... \)', except that it does not cause the matched substring to be
+     recorded for future reference.
+
+     This is useful when you need a lot of grouping `\( ... \)'
+     constructs, but only want to remember one or two - or if you have
+     more than nine groupings and need to use backreferences to refer to
+     the groupings at the end.
+
+     Using `\(?: ... \)' rather than `\( ... \)' when you don't need
+     the captured substrings ought to speed up your programs some,
+     since it shortens the code path followed by the regular expression
+     engine, as well as the amount of memory allocation and string
+     copying it must do.  The actual performance gain to be observed
+     has not been measured or quantified as of this writing.
+
+     The shy grouping operator has been borrowed from Perl, and has not
+     been available prior to XEmacs 20.3, nor is it available in FSF
+     Emacs.
+
+`\w'
+     matches any word-constituent character.  The editor syntax table
+     determines which characters these are.  *Note Syntax::.
+
+`\W'
+     matches any character that is not a word constituent.
+
+`\sCODE'
+     matches any character whose syntax is CODE.  Here CODE is a
+     character that represents a syntax code: thus, `w' for word
+     constituent, `-' for whitespace, `(' for open parenthesis, etc.
+     *Note Syntax::, for a list of syntax codes and the characters that
+     stand for them.
+
+`\SCODE'
+     matches any character whose syntax is not CODE.
+
+   The following regular expression constructs match the empty
+string--that is, they don't use up any characters--but whether they
+match depends on the context.
+
+`\`'
+     matches the empty string, but only at the beginning of the buffer
+     or string being matched against.
+
+`\''
+     matches the empty string, but only at the end of the buffer or
+     string being matched against.
+
+`\='
+     matches the empty string, but only at point.  (This construct is
+     not defined when matching against a string.)
+
+`\b'
+     matches the empty string, but only at the beginning or end of a
+     word.  Thus, `\bfoo\b' matches any occurrence of `foo' as a
+     separate word.  `\bballs?\b' matches `ball' or `balls' as a
+     separate word.
+
+`\B'
+     matches the empty string, but _not_ at the beginning or end of a
+     word.
+
+`\<'
+     matches the empty string, but only at the beginning of a word.
+
+`\>'
+     matches the empty string, but only at the end of a word.
+
+   Here is a complicated regexp used by Emacs to recognize the end of a
+sentence together with any whitespace that follows.  It is given in Lisp
+syntax to enable you to distinguish the spaces from the tab characters.
+In Lisp syntax, the string constant begins and ends with a
+double-quote.  `\"' stands for a double-quote as part of the regexp,
+`\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
+a newline.
+
+     "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
+
+This regexp contains four parts: a character set matching period, `?'
+or `!'; a character set matching close-brackets, quotes or parentheses,
+repeated any number of times; an alternative in backslash-parentheses
+that matches end-of-line, a tab or two spaces; and a character set
+matching whitespace characters, repeated any number of times.
+
+\1f
+File: xemacs.info,  Node: Search Case,  Next: Replace,  Prev: Regexps,  Up: Search
+
+Searching and Case
+==================
+
+All searches in Emacs normally ignore the case of the text they are
+searching through; if you specify searching for `FOO', `Foo' and `foo'
+are also considered a match.  Regexps, and in particular character
+sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
+
+   If you want a case-sensitive search, set the variable
+`case-fold-search' to `nil'.  Then all letters must match exactly,
+including case. `case-fold-search' is a per-buffer variable; altering
+it affects only the current buffer, but there is a default value which
+you can change as well.  *Note Locals::.  You can also use Case
+Sensitive Search from the Options menu on your screen.
+
+\1f
+File: xemacs.info,  Node: Replace,  Next: Other Repeating Search,  Prev: Search Case,  Up: Search
+
+Replacement Commands
+====================
+
+Global search-and-replace operations are not needed as often in Emacs as
+they are in other editors, but they are available.  In addition to the
+simple `replace-string' command which is like that found in most
+editors, there is a `query-replace' command which asks you, for each
+occurrence of a pattern, whether to replace it.
+
+   The replace commands all replace one string (or regexp) with one
+replacement string.  It is possible to perform several replacements in
+parallel using the command `expand-region-abbrevs'.  *Note Expanding
+Abbrevs::.
+
+* Menu:
+
+* Unconditional Replace::  Replacing all matches for a string.
+* Regexp Replace::         Replacing all matches for a regexp.
+* Replacement and Case::   How replacements preserve case of letters.
+* Query Replace::          How to use querying.
+
+\1f
+File: xemacs.info,  Node: Unconditional Replace,  Next: Regexp Replace,  Prev: Replace,  Up: Replace
+
+Unconditional Replacement
+-------------------------
+
+`M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
+     Replace every occurrence of STRING with NEWSTRING.
+
+`M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
+     Replace every match for REGEXP with NEWSTRING.
+
+   To replace every instance of `foo' after point with `bar', use the
+command `M-x replace-string' with the two arguments `foo' and `bar'.
+Replacement occurs only after point: if you want to cover the whole
+buffer you must go to the beginning first.  By default, all occurrences
+up to the end of the buffer are replaced.  To limit replacement to part
+of the buffer, narrow to that part of the buffer before doing the
+replacement (*note Narrowing::).
+
+   When `replace-string' exits, point is left at the last occurrence
+replaced.  The value of point when the `replace-string' command was
+issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
+
+   A numeric argument restricts replacement to matches that are
+surrounded by word boundaries.
+
+\1f
+File: xemacs.info,  Node: Regexp Replace,  Next: Replacement and Case,  Prev: Unconditional Replace,  Up: Replace
+
+Regexp Replacement
+------------------
+
+`replace-string' replaces exact matches for a single string.  The
+similar command `replace-regexp' replaces any match for a specified
+pattern.
+
+   In `replace-regexp', the NEWSTRING need not be constant.  It can
+refer to all or part of what is matched by the REGEXP.  `\&' in
+NEWSTRING stands for the entire text being replaced.  `\D' in
+NEWSTRING, where D is a digit, stands for whatever matched the D'th
+parenthesized grouping in REGEXP.  For example,
+
+     M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
+
+would replace (for example) `cadr' with `cadr-safe' and `cddr' with
+`cddr-safe'.
+
+     M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
+
+would perform exactly the opposite replacements.  To include a `\' in
+the text to replace with, you must give `\\'.
+

diff --git a/info/xemacs.info-2 b/info/xemacs.info-2
index f2754c1..42f4f80 100644 (file)
--- a/info/xemacs.info-2
+++ b/info/xemacs.info-2
@@ -1,4 +1,4 @@
-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from

 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -30,1083 +30,6876 @@ versions, except that the sections entitled "The GNU Manifesto",
 translation approved by the author instead of in the original English.
 
 \1f
 translation approved by the author instead of in the original English.
 
 \1f

-File: xemacs.info,  Node: Mode Line,  Next: GUI Components,  Prev: Echo Area,  Up: Frame
+File: xemacs.info,  Node: Replacement and Case,  Next: Query Replace,  Prev: Regexp Replace,  Up: Replace

 
 

-The Mode Line
-=============
+Replace Commands and Case
+-------------------------
+
+If the arguments to a replace command are in lower case, the command
+preserves case when it makes a replacement.  Thus, the following
+command:
+
+     M-x replace-string <RET> foo <RET> bar <RET>
+
+replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
+and `Foo' with `Bar'.  If upper-case letters are used in the second
+argument, they remain upper-case every time that argument is inserted.
+If upper-case letters are used in the first argument, the second
+argument is always substituted exactly as given, with no case
+conversion.  Likewise, if the variable `case-replace' is set to `nil',
+replacement is done without case conversion.  If `case-fold-search' is
+set to `nil', case is significant in matching occurrences of `foo' to
+replace; also, case conversion of the replacement string is not done.
+
+\1f
+File: xemacs.info,  Node: Query Replace,  Prev: Replacement and Case,  Up: Replace
+
+Query Replace
+-------------
+
+`M-% STRING <RET> NEWSTRING <RET>'
+`M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
+     Replace some occurrences of STRING with NEWSTRING.
+
+`M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
+     Replace some matches for REGEXP with NEWSTRING.
+
+   If you want to change only some of the occurrences of `foo' to
+`bar', not all of them, you can use `query-replace' instead of `M-%'.
+This command finds occurrences of `foo' one by one, displays each
+occurrence, and asks you whether to replace it.  A numeric argument to
+`query-replace' tells it to consider only occurrences that are bounded
+by word-delimiter characters.
+
+   Aside from querying, `query-replace' works just like
+`replace-string', and `query-replace-regexp' works just like
+`replace-regexp'.
+
+   The things you can type when you are shown an occurrence of STRING
+or a match for REGEXP are:
+
+`<SPC>'
+     to replace the occurrence with NEWSTRING.  This preserves case,
+     just like `replace-string', provided `case-replace' is non-`nil',
+     as it normally is.
+
+`<DEL>'
+     to skip to the next occurrence without replacing this one.
+
+`, (Comma)'
+     to replace this occurrence and display the result.  You are then
+     prompted for another input character.  However, since the
+     replacement has already been made, <DEL> and <SPC> are equivalent.
+     At this point, you can type `C-r' (see below) to alter the
+     replaced text.  To undo the replacement, you can type `C-x u'.
+     This exits the `query-replace'.  If you want to do further
+     replacement you must use `C-x <ESC> <ESC>' to restart (*note
+     Repetition::).
+
+`<ESC>'
+     to exit without doing any more replacements.
+
+`. (Period)'
+     to replace this occurrence and then exit.
+
+`!'
+     to replace all remaining occurrences without asking again.
+
+`^'
+     to go back to the location of the previous occurrence (or what
+     used to be an occurrence), in case you changed it by mistake.
+     This works by popping the mark ring.  Only one `^' in a row is
+     allowed, because only one previous replacement location is kept
+     during `query-replace'.
+
+`C-r'
+     to enter a recursive editing level, in case the occurrence needs
+     to be edited rather than just replaced with NEWSTRING.  When you
+     are done, exit the recursive editing level with `C-M-c' and the
+     next occurrence will be displayed.  *Note Recursive Edit::.
+
+`C-w'
+     to delete the occurrence, and then enter a recursive editing level
+     as in `C-r'.  Use the recursive edit to insert text to replace the
+     deleted occurrence of STRING.  When done, exit the recursive
+     editing level with `C-M-c' and the next occurrence will be
+     displayed.
+
+`C-l'
+     to redisplay the screen and then give another answer.
+
+`C-h'
+     to display a message summarizing these options, then give another
+     answer.
+
+   If you type any other character, Emacs exits the `query-replace', and
+executes the character as a command.  To restart the `query-replace',
+use `C-x <ESC> <ESC>', which repeats the `query-replace' because it
+used the minibuffer to read its arguments.  *Note C-x ESC ESC:
+Repetition.
+
+\1f
+File: xemacs.info,  Node: Other Repeating Search,  Prev: Replace,  Up: Search
+
+Other Search-and-Loop Commands
+==============================
+
+Here are some other commands that find matches for a regular expression.
+They all operate from point to the end of the buffer.
+
+`M-x occur'
+     Print each line that follows point and contains a match for the
+     specified regexp.  A numeric argument specifies the number of
+     context lines to print before and after each matching line; the
+     default is none.
+
+     The buffer `*Occur*' containing the output serves as a menu for
+     finding occurrences in their original context.  Find an occurrence
+     as listed in `*Occur*', position point there, and type `C-c C-c';
+     this switches to the buffer that was searched and moves point to
+     the original of the same occurrence.
+
+`M-x list-matching-lines'
+     Synonym for `M-x occur'.
+
+`M-x count-matches'
+     Print the number of matches following point for the specified
+     regexp.
+
+`M-x delete-non-matching-lines'
+     Delete each line that follows point and does not contain a match
+     for the specified regexp.
+
+`M-x delete-matching-lines'
+     Delete each line that follows point and contains a match for the
+     specified regexp.
+
+\1f
+File: xemacs.info,  Node: Fixit,  Next: Files,  Prev: Search,  Up: Top
+
+Commands for Fixing Typos
+*************************
+
+This chapter describes commands that are especially useful when you
+catch a mistake in your text just after you have made it, or when you
+change your mind while composing text on line.
+
+* Menu:
+
+* Kill Errors:: Commands to kill a batch of recently entered text.
+* Transpose::   Exchanging two characters, words, lines, lists...
+* Fixing Case:: Correcting case of last word entered.
+* Spelling::    Apply spelling checker to a word, or a whole file.
+
+\1f
+File: xemacs.info,  Node: Kill Errors,  Next: Transpose,  Prev: Fixit,  Up: Fixit
+
+Killing Your Mistakes
+=====================
+
+`<DEL>'
+     Delete last character (`delete-backward-char').
+
+`M-<DEL>'
+     Kill last word (`backward-kill-word').
+
+`C-x <DEL>'
+     Kill to beginning of sentence (`backward-kill-sentence').
+
+   The <DEL> character (`delete-backward-char') is the most important
+correction command.  When used among graphic (self-inserting)
+characters, it can be thought of as canceling the last character typed.
+
+   When your mistake is longer than a couple of characters, it might be
+more convenient to use `M-<DEL>' or `C-x <DEL>'.  `M-<DEL>' kills back
+to the start of the last word, and `C-x <DEL>' kills back to the start
+of the last sentence.  `C-x <DEL>' is particularly useful when you are
+thinking of what to write as you type it, in case you change your mind
+about phrasing.  `M-<DEL>' and `C-x <DEL>' save the killed text for
+`C-y' and `M-y' to retrieve.  *Note Yanking::.
+
+   `M-<DEL>' is often useful even when you have typed only a few
+characters wrong, if you know you are confused in your typing and aren't
+sure exactly what you typed.  At such a time, you cannot correct with
+<DEL> except by looking at the screen to see what you did.  It requires
+less thought to kill the whole word and start over.
+
+\1f
+File: xemacs.info,  Node: Transpose,  Next: Fixing Case,  Prev: Kill Errors,  Up: Fixit
+
+Transposing Text
+================
+
+`C-t'
+     Transpose two characters (`transpose-chars').
+
+`M-t'
+     Transpose two words (`transpose-words').
+
+`C-M-t'
+     Transpose two balanced expressions (`transpose-sexps').
+
+`C-x C-t'
+     Transpose two lines (`transpose-lines').
+
+   The common error of transposing two adjacent characters can be fixed
+with the `C-t' command (`transpose-chars').  Normally, `C-t' transposes
+the two characters on either side of point.  When given at the end of a
+line, `C-t' transposes the last two characters on the line, rather than
+transposing the last character of the line with the newline, which
+would be useless.  If you catch a transposition error right away, you
+can fix it with just `C-t'.  If you catch the error later,  move the
+cursor back to between the two transposed characters.  If you
+transposed a space with the last character of the word before it, the
+word motion commands are a good way of getting there.  Otherwise, a
+reverse search (`C-r') is often the best way.  *Note Search::.
+
+   `Meta-t' (`transpose-words') transposes the word before point with
+the word after point.  It moves point forward over a word, dragging the
+word preceding or containing point forward as well.  The punctuation
+characters between the words do not move.  For example, `FOO, BAR'
+transposes into `BAR, FOO' rather than `BAR FOO,'.
+
+   `C-M-t' (`transpose-sexps') is a similar command for transposing two
+expressions (*note Lists::), and `C-x C-t' (`transpose-lines')
+exchanges lines.  It works like `M-t' but in determines the division of
+the text into syntactic units differently.
+
+   A numeric argument to a transpose command serves as a repeat count:
+it tells the transpose command to move the character (word, sexp, line)
+before or containing point across several other characters (words,
+sexps, lines).  For example, `C-u 3 C-t' moves the character before
+point forward across three other characters.  This is equivalent to
+repeating `C-t' three times.  `C-u - 4 M-t' moves the word before point
+backward across four words.  `C-u - C-M-t' would cancel the effect of
+plain `C-M-t'.
+
+   A numeric argument of zero transposes the character (word, sexp,
+line) ending after point with the one ending after the mark (otherwise a
+command with a repeat count of zero would do nothing).
+
+\1f
+File: xemacs.info,  Node: Fixing Case,  Next: Spelling,  Prev: Transpose,  Up: Fixit
+
+Case Conversion
+===============
+
+`M-- M-l'
+     Convert last word to lower case.  Note that `Meta--' is
+     "Meta-minus."
+
+`M-- M-u'
+     Convert last word to all upper case.
+
+`M-- M-c'
+     Convert last word to lower case with capital initial.
+
+   A  common error is to type words in the wrong case.  Because of this,
+the word case-conversion commands `M-l', `M-u', and `M-c' do not move
+the cursor when used with a negative argument.  As soon as you see you
+have mistyped the last word, you can simply case-convert it and
+continue typing.  *Note Case::.
+
+\1f
+File: xemacs.info,  Node: Spelling,  Prev: Fixing Case,  Up: Fixit
+
+Checking and Correcting Spelling
+================================
+
+`M-$'
+     Check and correct spelling of word (`spell-word').
+
+`M-x spell-buffer'
+     Check and correct spelling of each word in the buffer.
+
+`M-x spell-region'
+     Check and correct spelling of each word in the region.
+
+`M-x spell-string'
+     Check spelling of specified word.
+
+   To check the spelling of the word before point, and optionally
+correct it, use the command `M-$' (`spell-word').  This command runs an
+inferior process containing the `spell' program to see whether the word
+is correct English.  If it is not, it asks you to edit the word (in the
+minibuffer) into a corrected spelling, and then performs a
+`query-replace' to substitute the corrected spelling for the old one
+throughout the buffer.
+
+   If you exit the minibuffer without altering the original spelling, it
+means you do not want to do anything to that word.  In that case, the
+`query-replace' is not done.
+
+   `M-x spell-buffer' checks each word in the buffer the same way that
+`spell-word' does, doing a `query-replace' for every incorrect word if
+appropriate.
+
+   `M-x spell-region' is similar to `spell-buffer' but operates only on
+the region, not the entire buffer.
+
+   `M-x spell-string' reads a string as an argument and checks whether
+that is a correctly spelled English word.  It prints a message giving
+the answer in the echo area.
+
+\1f
+File: xemacs.info,  Node: Files,  Next: Buffers,  Prev: Fixit,  Up: Top
+
+File Handling
+*************
+
+The basic unit of stored data in Unix is the "file".  To edit a file,
+you must tell Emacs to examine the file and prepare a buffer containing
+a copy of the file's text.  This is called "visiting" the file.  Editing
+commands apply directly to text in the buffer; that is, to the copy
+inside Emacs.  Your changes appear in the file itself only when you
+"save" the buffer back into the file.
+
+   Emacs is also able to handle "remote files" which are stored on
+other hosts.  Not only is Emacs somewhat aware of the special issues
+involved with network file systems, but it can also use FTP and ssh (or
+rsh) to make local copies of the files, and refresh them on the remote
+host automatically when you save the buffer.  The FTP interface is
+provided by the standard `efs' package *Note EFS: (efs)Top.  The
+ssh/rsh interface is provided by the optional `tramp' package *Note
+TRAMP: (tramp)Top.  These packages attempt to implement all of the
+operations described below, making remote file use transparent (except
+for unavoidable network delays).
+
+   In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, and operate on file directories.
+
+* Menu:
+
+* File Names::       How to type and edit file name arguments.
+* Visiting::         Visiting a file prepares Emacs to edit the file.
+* Saving::           Saving makes your changes permanent.
+* Reverting::        Reverting cancels all the changes not saved.
+* Auto Save::        Auto Save periodically protects against loss of data.
+* Version Control::  Version control systems (RCS and SCCS).
+* ListDir::          Listing the contents of a file directory.
+* Comparing Files::  Finding where two files differ.
+* Dired::            ``Editing'' a directory to delete, rename, etc.
+                     the files in it.
+* Misc File Ops::    Other things you can do on files.
+
+\1f
+File: xemacs.info,  Node: File Names,  Next: Visiting,  Prev: Files,  Up: Files
+
+File Names
+==========
+
+Most Emacs commands that operate on a file require you to specify the
+file name.  (Saving and reverting are exceptions; the buffer knows which
+file name to use for them.)  File names are specified in the minibuffer
+(*note Minibuffer::).  "Completion" is available, to make it easier to
+specify long file names.  *Note Completion::.
+
+   There is always a "default file name" which is used if you enter an
+empty argument by typing just <RET>.  Normally the default file name is
+the name of the file visited in the current buffer; this makes it easy
+to operate on that file with any of the Emacs file commands.
+
+   The syntax for accessing remote files unfortunately varies depending
+on the method used.  The syntax for using FTP is
+`/USER@REMOTE-HOST:PATH-ON-REMOTE-HOST'.  The syntax for using ssh is
+`/[USER@REMOTE-HOST]PATH-ON-REMOTE-HOST'.
+
+   In both cases the `USER@' portion is optional (it defaults to your
+local user name).  PATH-ON-REMOTE-HOST may use the `~' notation to
+indicate USER's home directory on the remote host.  The default file
+name will reflect the remote host information.
+
+   Each buffer has a default directory, normally the same as the
+directory of the file visited in that buffer.  When Emacs reads a file
+name, the default directory is used if you do not specify a directory.
+If you specify a directory in a relative fashion, with a name that does
+not start with a slash, it is interpreted with respect to the default
+directory.  The default directory of the current buffer is kept in the
+variable `default-directory', which has a separate value in every
+buffer.  The value of the variable should end with a slash.
+
+   For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
+the default directory is `/u/rms/gnu/'.  If you type just `foo', which
+does not specify a directory, it is short for `/u/rms/gnu/foo'.
+`../.login' would stand for `/u/rms/.login'.  `new/foo' would stand for
+the filename `/u/rms/gnu/new/foo'.
+
+   When visiting a remote file via EFS or TRAMP, the remote directory
+becomes the default directory (*note Visiting::) for that buffer, just
+as a local directory would.
+
+   The variable `default-directory-alist' takes an alist of major modes
+and their opinions on `default-directory' as a Lisp expression to
+evaluate.  A resulting value of `nil' is ignored in favor of
+`default-directory'.
+
+   You can create a new directory with the function `make-directory',
+which takes as an argument a file name string. The current directory is
+displayed in the minibuffer when the function is called; you can delete
+the old directory name and supply a new directory name. For example, if
+the current directory is `/u/rms/gnu', you can delete `gnu' and type
+`oryx' and <RET> to create `/u/rms/oryx'.  Removing a directory is
+similar to creating one.  To remove a directory, use
+`remove-directory'; it takes one argument, a file name string.
+
+   The command `M-x pwd' prints the current buffer's default directory,
+and the command `M-x cd' sets it (to a value read using the
+minibuffer).  A buffer's default directory changes only when the `cd'
+command is used.  A file-visiting buffer's default directory is
+initialized to the directory of the file that is visited there.  If a
+buffer is created with `C-x b', its default directory is copied from
+that of the buffer that was current at the time.
+
+   The default directory name actually appears in the minibuffer when
+the minibuffer becomes active to read a file name.  This serves two
+purposes: it shows you what the default is, so that you can type a
+relative file name and know with certainty what it will mean, and it
+allows you to edit the default to specify a different directory.  To
+inhibit the insertion of the default directory, set the variable
+`insert-default-directory' to `nil'.
+
+   Note that it is legitimate to type an absolute file name after you
+enter the minibuffer, ignoring the presence of the default directory
+name.  The final minibuffer contents may look invalid, but that is not
+so.  *Note Minibuffer File::.
+
+   `$' in a file name is used to substitute environment variables.  For
+example, if you have used the shell command `setenv FOO rms/hacks' to
+set up an environment variable named `FOO', then you can use
+`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
+`/u/rms/hacks/test.c'.  The environment variable name consists of all
+the alphanumeric characters after the `$'; alternatively, it may be
+enclosed in braces after the `$'.  Note that the `setenv' command
+affects Emacs only if done before Emacs is started.
+
+   To access a file with `$' in its name, type `$$'.  This pair is
+converted to a single `$' at the same time variable substitution is
+performed for single `$'.  The Lisp function that performs the
+substitution is called `substitute-in-file-name'.  The substitution is
+performed only on filenames read as such using the minibuffer.

 
 

-   Each text window's last line is a "mode line" which describes what is
-going on in that window.  When there is only one text window, the mode
-line appears right above the echo area.  The mode line is in inverse
-video if the terminal supports that, starts and ends with dashes, and
-contains text like `XEmacs: SOMETHING'.
-
-   If a mode line has something else in place of `XEmacs: SOMETHING',
-the window above it is in a special subsystem such as Dired.  The mode
-line then indicates the status of the subsystem.
-
-   Normally, the mode line has the following appearance:
-
-     --CH-XEmacs: BUF      (MAJOR MINOR)----POS------
-
-This gives information about the buffer being displayed in the window:
-the buffer's name, what major and minor modes are in use, whether the
-buffer's text has been changed, and how far down the buffer you are
-currently looking.
-
-   CH contains two stars (`**') if the text in the buffer has been
-edited (the buffer is "modified"), or two dashes (`--') if the buffer
-has not been edited.  Exception: for a read-only buffer, it is `%%'.
-
-   BUF is the name of the window's chosen "buffer".  The chosen buffer
-in the selected window (the window that the cursor is in) is also
-XEmacs's selected buffer, the buffer in which editing takes place.  When
-we speak of what some command does to "the buffer", we mean the
-currently selected buffer.  *Note Buffers::.
-
-   POS tells you whether there is additional text above the top of the
-screen or below the bottom.  If your file is small and it is completely
-visible on the screen, POS is `All'.  Otherwise, POS is `Top' if you
-are looking at the beginning of the file, `Bot' if you are looking at
-the end of the file, or `NN%', where NN is the percentage of the file
-above the top of the screen.
-
-   MAJOR is the name of the "major mode" in effect in the buffer.  At
-any time, each buffer is in one and only one major mode.  The available
-major modes include Fundamental mode (the least specialized), Text
-mode, Lisp mode, and C mode.  *Note Major Modes::, for details on how
-the modes differ and how you select one.
-
-   MINOR is a list of some of the "minor modes" that are turned on in
-the window's chosen buffer.  For example, `Fill' means that Auto Fill
-mode is on.  `Abbrev' means that Word Abbrev mode is on.  `Ovwrt' means
-that Overwrite mode is on.  *Note Minor Modes::, for more information.
-`Narrow' means that the buffer being displayed has editing restricted
-to only a portion of its text.  This is not really a minor mode, but is
-like one.  *Note Narrowing::.  `Def' means that a keyboard macro is
-being defined.  *Note Keyboard Macros::.
-
-   Some buffers display additional information after the minor modes.
-For example, Rmail buffers display the current message number and the
-total number of messages.  Compilation buffers and Shell mode display
-the status of the subprocess.
-
-   If XEmacs is currently inside a recursive editing level, square
-brackets (`[...]') appear around the parentheses that surround the
-modes.  If XEmacs is in one recursive editing level within another,
-double square brackets appear, and so on.  Since information on
-recursive editing applies to XEmacs in general and not to any one
-buffer, the square brackets appear in every mode line on the screen or
-not in any of them.  *Note Recursive Edit::.
-
-   XEmacs can optionally display the time and system load in all mode
-lines.  To enable this feature, type `M-x display-time'.  The
-information added to the mode line usually appears after the file name,
-before the mode names and their parentheses.  It looks like this:
-
-     HH:MMpm L.LL [D]
-
-(Some fields may be missing if your operating system cannot support
-them.)  HH and MM are the hour and minute, followed always by `am' or
-`pm'.  L.LL is the average number of running processes in the whole
-system recently.  D is an approximate index of the ratio of disk
-activity to CPU activity for all users.
-
-   The word `Mail' appears after the load level if there is mail for
-you that you have not read yet.
-
-   Customization note: the variable `mode-line-inverse-video' controls
-whether the mode line is displayed in inverse video (assuming the
-terminal supports it); `nil' means no inverse video.  The default is
-`t'.  For X frames, simply set the foreground and background colors
-appropriately.
-
-\1f
-File: xemacs.info,  Node: GUI Components,  Next: XEmacs under X,  Prev: Mode Line,  Up: Frame
-
-GUI Components
+\1f
+File: xemacs.info,  Node: Visiting,  Next: Saving,  Prev: File Names,  Up: Files
+
+Visiting Files

 ==============
 
 ==============
 

-   When executed in a graphical windowing environment such as the X
-Window System or Microsoft Windows, XEmacs displays several graphical
-user interface components such as scrollbars, menubars, toolbars, and
-gutters.  By default there is a vertical scrollbar at the right of each
-frame, and at the top of the frame there is a menubar, a toolbar, and a
-gutter, in that order.  Gutters can contain any of several widgets, but
-the default configuration puts a set of "notebook tabs" which you can
-use as a shortcut for selecting any of several related buffers in a
-given frame.  Operating the GUI components is "obvious":  click on the
-menubar to pull down a menu, on a button in the toolbar to invoke a
-function, and on a tab in the gutter to switch buffers.
+`C-x C-f'
+     Visit a file (`find-file').
+
+`C-x C-v'
+     Visit a different file instead of the one visited last
+     (`find-alternate-file').
+
+`C-x 4 C-f'
+     Visit a file, in another window (`find-file-other-window').  Don't
+     change this window.
+
+`C-x 5 C-f'
+     Visit a file, in another frame (`find-file-other-frame').  Don't
+     change this window or frame.
+
+   "Visiting" a file means copying its contents into an Emacs buffer so
+you can edit it.  Emacs creates a new buffer for each file you visit.
+We say that the buffer is visiting the file that it was created to
+hold.  Emacs constructs the buffer name from the file name by throwing
+away the directory and keeping just the file name.  For example, a file
+named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'.
+If a buffer with that name exists, a unique name is constructed by
+appending `<2>', `<3>',and so on, using the lowest number that makes a
+name that is not already in use.
+
+   Each window's mode line shows the name of the buffer that is being
+displayed in that window, so you can always tell what buffer you are
+editing.
+
+   The changes you make with Emacs are made in the Emacs buffer.  They
+do not take effect in the file that you visit, or any other permanent
+place, until you "save" the buffer.  Saving the buffer means that Emacs
+writes the current contents of the buffer into its visited file.  *Note
+Saving::.
+
+   If a buffer contains changes that have not been saved, the buffer is
+said to be "modified".  This is important because it implies that some
+changes will be lost if the buffer is not saved.  The mode line displays
+two stars near the left margin if the buffer is modified.
+
+   To visit a file, use the command `C-x C-f' (`find-file').  Follow
+the command with the name of the file you wish to visit, terminated by a
+<RET>.  If you are using XEmacs under X, you can also use the Open...
+command from the File menu bar item.
+
+   The file name is read using the minibuffer (*note Minibuffer::), with
+defaulting and completion in the standard manner (*note File Names::).
+While in the minibuffer, you can abort `C-x C-f' by typing `C-g'.
+
+   `C-x C-f' has completed successfully when text appears on the screen
+and a new buffer name appears in the mode line.  If the specified file
+does not exist and could not be created or cannot be read, an error
+results.  The error message is printed in the echo area, and includes
+the name of the file that Emacs was trying to visit.
+
+   If you visit a file that is already in Emacs, `C-x C-f' does not make
+another copy.  It selects the existing buffer containing that file.
+However, before doing so, it checks that the file itself has not changed
+since you visited or saved it last.  If the file has changed, Emacs
+prints a warning message.  *Note Simultaneous Editing: Interlocking.
+
+   You can switch to a specific file called out in the current buffer by
+calling the function `find-this-file'. By providing a prefix argument,
+this function calls `filename-at-point' and switches to a buffer
+visiting the file FILENAME. It creates one if none already exists. You
+can use this function to edit the file mentioned in the buffer you are
+working in or to test if the file exists. You can do that by using the
+minibuffer completion after snatching the all or part of the filename.
+
+   If the variable `find-file-use-truenames''s value is non-`nil', a
+buffer's visited filename will always be traced back to the real file.
+The filename will never be a symbolic link, and there will never be a
+symbolic link anywhere in its directory path. In other words, the
+`buffer-file-name' and `buffer-file-truename' will be equal.
+
+   If the variable `find-file-compare-truenames' value is non-`nil',
+the `find-file' command will check the `buffer-file-truename' of all
+visited files when deciding whether a given file is already in a
+buffer, instead of just `buffer-file-name'.  If you attempt to visit
+another file which is a symbolic link to a file that is already in a
+buffer, the existing buffer will be found instead of a newly created
+one.  This works if any component of the pathname (including a
+non-terminal component) is a symbolic link as well, but doesn't work
+with hard links (nothing does).
+
+   If you want to create a file, just visit it.  Emacs prints `(New
+File)' in the echo area, but in other respects behaves as if you had
+visited an existing empty file.  If you make any changes and save them,
+the file is created.
+
+   If you visit a nonexistent file unintentionally (because you typed
+the wrong file name), use the `C-x C-v' (`find-alternate-file') command
+to visit the file you wanted.  `C-x C-v' is similar to `C-x C-f', but
+it kills the current buffer (after first offering to save it if it is
+modified).  `C-x C-v' is allowed even if the current buffer is not
+visiting a file.
+
+   If the file you specify is actually a directory, Dired is called on
+that directory (*note Dired::).  To inhibit this, set the variable
+`find-file-run-dired' to `nil'; then it is an error to try to visit a
+directory.
+
+   `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
+the buffer containing the specified file is selected in another window.
+The window that was selected before `C-x 4 f' continues to show the
+same buffer it was already showing.  If you use this command when only
+one window is being displayed, that window is split in two, with one
+window showing the same buffer as before, and the other one showing the
+newly requested file.  *Note Windows::.
+
+   `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that
+it creates a new frame in which the file is displayed.
+
+   Use the function `find-this-file-other-window' to edit a file
+mentioned in the buffer you are editing or to test if that file exists.
+To do this, use the minibuffer completion after snatching the part or
+all of the filename. By providing a prefix argument, the function calls
+`filename-at-point' and switches you to a buffer visiting the file
+FILENAME in another window. The function creates a buffer if none
+already exists. This function is similar to `find-file-other-window'.
+
+   There are two hook variables that allow extensions to modify the
+operation of visiting files.  Visiting a file that does not exist runs
+the functions in the list `find-file-not-found-hooks'; the value of this
+variable is expected to be a list of functions which are called one by
+one until one of them returns non-`nil'.  Any visiting of a file,
+whether extant or not, expects `find-file-hooks' to contain list of
+functions and calls them all, one by one.  In both cases the functions
+receive no arguments.  Visiting a nonexistent file runs the
+`find-file-not-found-hooks' first.
+
+\1f
+File: xemacs.info,  Node: Saving,  Next: Reverting,  Prev: Visiting,  Up: Files
+
+Saving Files
+============
+
+"Saving" a buffer in Emacs means writing its contents back into the file
+that was visited in the buffer.
+
+`C-x C-s'
+     Save the current buffer in its visited file (`save-buffer').
+
+`C-x s'
+     Save any or all buffers in their visited files
+     (`save-some-buffers').
+
+`M-~'
+     Forget that the current buffer has been changed (`not-modified').
+
+`C-x C-w'
+     Save the current buffer in a specified file, and record that file
+     as the one visited in the buffer (`write-file').
+
+`M-x set-visited-file-name'
+     Change file the name under which the current buffer will be saved.
+
+   To save a file and make your changes permanent, type `C-x C-s'
+(`save-buffer').  After saving is finished, `C-x C-s' prints a message
+such as:
+
+     Wrote /u/rms/gnu/gnu.tasks
+
+If the selected buffer is not modified (no changes have been made in it
+since the buffer was created or last saved), Emacs does not save it
+because it would have no effect.  Instead, `C-x C-s' prints a message
+in the echo area saying:
+
+     (No changes need to be saved)
+
+   The command `C-x s' (`save-some-buffers') can save any or all
+modified buffers.  First it asks, for each modified buffer, whether to
+save it.  The questions should be answered with `y' or `n'.  `C-x C-c',
+the key that kills Emacs, invokes `save-some-buffers' and therefore
+asks the same questions.
+
+   If you have changed a buffer and do not want the changes to be saved,
+you should take some action to prevent it.  Otherwise, you are liable to
+save it by mistake each time you use `save-some-buffers' or a related
+command.  One thing you can do is type `M-~' (`not-modified'), which
+removes the indication that the buffer is modified.  If you do this,
+none of the save commands will believe that the buffer needs to be
+saved.  (`~' is often used as a mathematical symbol for `not'; thus
+`Meta-~' is `not', metafied.)  You could also use
+`set-visited-file-name' (see below) to mark the buffer as visiting a
+different file name, not in use for anything important.
+
+   You can also undo all the changes made since the file was visited or
+saved, by reading the text from the file again.  This is called
+"reverting".  *Note Reverting::.  Alternatively, you can undo all the
+changes by repeating the undo command `C-x u'; but this only works if
+you have not made more changes than the undo mechanism can remember.
+
+   `M-x set-visited-file-name' alters the name of the file that the
+current buffer is visiting.  It prompts you for the new file name in the
+minibuffer.  You can also use `set-visited-file-name' on a buffer that
+is not visiting a file.  The buffer's name is changed to correspond to
+the file it is now visiting unless the new name is already used by a
+different buffer; in that case, the buffer name is not changed.
+`set-visited-file-name' does not save the buffer in the newly visited
+file; it just alters the records inside Emacs so that it will save the
+buffer in that file.  It also marks the buffer as "modified" so that
+`C-x C-s' will save.
+
+   If you wish to mark a buffer as visiting a different file and save it
+right away, use `C-x C-w' (`write-file').  It is precisely equivalent
+to `set-visited-file-name' followed by `C-x C-s'.  `C-x C-s' used on a
+buffer that is not visiting  a file has the same effect as `C-x C-w';
+that is, it reads a file name, marks the buffer as visiting that file,
+and saves it there.  The default file name in a buffer that is not
+visiting a file is made by combining the buffer name with the buffer's
+default directory.
+
+   If Emacs is about to save a file and sees that the date of the latest
+version on disk does not match what Emacs last read or wrote, Emacs
+notifies you of this fact, because it probably indicates a problem
+caused by simultaneous editing and requires your immediate attention.
+*Note Simultaneous Editing: Interlocking.
+
+   If the variable `require-final-newline' is non-`nil', Emacs puts a
+newline at the end of any file that doesn't already end in one, every
+time a file is saved or written.
+
+   Use the hook variable `write-file-hooks' to implement other ways to
+write files, and specify things to be done before files are written.
+The value of this variable should be a list of Lisp functions.  When a
+file is to be written, the functions in the list are called, one by
+one, with no arguments.  If one of them returns a non-`nil' value, Emacs
+takes this to mean that the file has been written in some suitable
+fashion; the rest of the functions are not called, and normal writing is
+not done. Use the hook variable `after-save-hook' to list all the
+functions to be called after writing out a buffer to a file.
+
+* Menu:
+
+* Backup::       How Emacs saves the old version of your file.
+* Interlocking:: How Emacs protects against simultaneous editing
+                  of one file by two users.
+
+\1f
+File: xemacs.info,  Node: Backup,  Next: Interlocking,  Prev: Saving,  Up: Saving
+
+Backup Files
+------------
+
+Because Unix does not provide version numbers in file names, rewriting a
+file in Unix automatically destroys all record of what the file used to
+contain.  Thus, saving a file from Emacs throws away the old contents of
+the file--or it would, except that Emacs carefully copies the old
+contents to another file, called the "backup" file, before actually
+saving.  (Make sure that the variable `make-backup-files' is non-`nil'.
+Backup files are not written if this variable is `nil').
+
+   At your option, Emacs can keep either a single backup file or a
+series of numbered backup files for each file you edit.
+
+   Emacs makes a backup for a file only the first time a file is saved
+from one buffer.  No matter how many times you save a file, its backup
+file continues to contain the contents from before the file was visited.
+Normally this means that the backup file contains the contents from
+before the current editing session; however, if you kill the buffer and
+then visit the file again, a new backup file is made by the next save.

 
 * Menu:
 
 
 * Menu:
 

-* Menubar Basics::      How XEmacs uses the menubar.
-* Scrollbar Basics::    How XEmacs uses scrollbars.
-* Mode Line Basics::    How XEmacs uses modelines.
-* Toolbar Basics::      How XEmacs uses toolbars.
-* Gutter Basics::       How XEmacs uses gutters.
-* Inhibiting::          What if you don't like GUI?
-* Customizing::         Position, orientation, and appearance of GUI objects.
+* Names: Backup Names.         How backup files are named;
+                               Choosing single or numbered backup files.
+* Deletion: Backup Deletion.   Emacs deletes excess numbered backups.
+* Copying: Backup Copying.     Backups can be made by copying or renaming.
+
+\1f
+File: xemacs.info,  Node: Backup Names,  Next: Backup Deletion,  Prev: Backup,  Up: Backup
+
+Single or Numbered Backups
+..........................
+
+If you choose to have a single backup file (the default), the backup
+file's name is constructed by appending `~' to the file name being
+edited; thus, the backup file for `eval.c' is `eval.c~'.
+
+   If you choose to have a series of numbered backup files, backup file
+names are made by appending `.~', the number, and another `~' to the
+original file name.  Thus, the backup files of `eval.c' would be called
+`eval.c.~1~', `eval.c.~2~', and so on, through names like
+`eval.c.~259~' and beyond.
+
+   If protection stops you from writing backup files under the usual
+names, the backup file is written as `%backup%~' in your home directory.
+Only one such file can exist, so only the most recently made backup is
+available.
+
+   The choice of single backup or numbered backups is controlled by the
+variable `version-control'.  Its possible values are:
+
+`t'
+     Make numbered backups.
+
+`nil'
+     Make numbered backups for files that have numbered backups already.
+     Otherwise, make single backups.
+
+`never'
+     Never make numbered backups; always make single backups.
+
+`version-control' may be set locally in an individual buffer to control
+the making of backups for that buffer's file.  For example, Rmail mode
+locally sets `version-control' to `never' to make sure that there is
+only one backup for an Rmail file.  *Note Locals::.
+
+\1f
+File: xemacs.info,  Node: Backup Deletion,  Next: Backup Copying,  Prev: Backup Names,  Up: Backup
+
+Automatic Deletion of Backups
+.............................
+
+To prevent unlimited consumption of disk space, Emacs can delete
+numbered backup versions automatically.  Generally Emacs keeps the
+first few backups and the latest few backups, deleting any in between.
+This happens every time a new backup is made.  The two variables that
+control the deletion are `kept-old-versions' and `kept-new-versions'.
+Their values are, respectively the number of oldest (lowest-numbered)
+backups to keep and the number of newest (highest-numbered) ones to
+keep, each time a new backup is made.  The values are used just after a
+new backup version is made; that newly made backup is included in the
+count in `kept-new-versions'.  By default, both variables are 2.
+
+   If `delete-old-versions' is non-`nil',  excess middle versions are
+deleted without notification.  If it is `nil', the default, you are
+asked whether the excess middle versions should really be deleted.
+
+   You can also use Dired's `.' (Period) command to delete old versions.
+*Note Dired::.
+
+\1f
+File: xemacs.info,  Node: Backup Copying,  Prev: Backup Deletion,  Up: Backup
+
+Copying vs. Renaming
+....................
+
+You can make backup files by copying the old file or by renaming it.
+This makes a difference when the old file has multiple names.  If you
+rename the old file into the backup file, the alternate names become
+names for the backup file.  If you copy the old file instead, the
+alternate names remain names for the file that you are editing, and the
+contents accessed by those names will be the new contents.
+
+   How you make a backup file may also affect the file's owner and
+group.  If you use copying, they do not change.  If renaming is used,
+you become the file's owner, and the file's group becomes the default
+(different operating systems have different defaults for the group).
+
+   Having the owner change is usually a good idea, because then the
+owner is always the person who last edited the file.  Occasionally
+there is a file whose owner should not change.  Since most files should
+change owners, it is a good idea to use local variable lists to set
+`backup-by-copying-when-mismatch' for the special cases where the owner
+should not change (*note File Variables::).
+
+   Three variables control the choice of renaming or copying.
+Normally, renaming is done.  If the variable `backup-by-copying' is
+non-`nil', copying is used.  Otherwise, if the variable
+`backup-by-copying-when-linked' is non-`nil', copying is done for files
+that have multiple names, but renaming may still be done when the file
+being edited has only one name.  If the variable
+`backup-by-copying-when-mismatch' is non-`nil', copying is done if
+renaming would cause the file's owner or group to change.
+
+\1f
+File: xemacs.info,  Node: Interlocking,  Prev: Backup,  Up: Saving
+
+Protection Against Simultaneous Editing
+---------------------------------------
+
+Simultaneous editing occurs when two users visit the same file, both
+make changes, and both save their changes.  If no one was informed that
+this was happening, and you saved first, you would later find that your
+changes were lost.  On some systems, Emacs notices immediately when the
+second user starts to change a file already being edited, and issues a
+warning.  When this is not possible, or if the second user has started
+to change the file despite the warning, Emacs checks when the file is
+saved, and issues a second warning when a user is about to overwrite a
+file containing another user's changes.  If you are the user editing the
+file, you can take corrective action at this point and prevent actual
+loss of work.
+
+   When you make the first modification in an Emacs buffer that is
+visiting a file, Emacs records that you have locked the file.  (It does
+this by writing another file in a directory reserved for this purpose.)
+The lock is removed when you save the changes.  The idea is that the
+file is locked whenever the buffer is modified.  If you begin to modify
+the buffer while the visited file is locked by someone else, this
+constitutes a collision, and Emacs asks you what to do.  It does this
+by calling the Lisp function `ask-user-about-lock', which you can
+redefine to customize what it does.  The standard definition of this
+function asks you a question and accepts three possible answers:
+
+`s'
+     Steal the lock.  Whoever was already changing the file loses the
+     lock, and you get the lock.
+
+`p'
+     Proceed.  Go ahead and edit the file despite its being locked by
+     someone else.
+
+`q'
+     Quit.  This causes an error (`file-locked') and the modification
+     you were trying to make in the buffer does not actually take place.
+
+   Note that locking works on the basis of a file name; if a file has
+multiple names, Emacs does not realize that the two names are the same
+file and cannot prevent two users from editing it simultaneously under
+different names.  However, basing locking on names means that Emacs can
+interlock the editing of new files that do not really exist until they
+are saved.
+
+   Some systems are not configured to allow Emacs to make locks.  On
+these systems, Emacs cannot detect trouble in advance, but it can still
+detect it in time to prevent you from overwriting someone else's
+changes.
+
+   Every time Emacs saves a buffer, it first checks the
+last-modification date of the existing file on disk to see that it has
+not changed since the file was last visited or saved.  If the date does
+not match, it implies that changes were made in the file in some other
+way, and these changes are about to be lost if Emacs actually does
+save.  To prevent this, Emacs prints a warning message and asks for
+confirmation before saving.  Occasionally you will know why the file
+was changed and know that it does not matter; then you can answer `yes'
+and proceed.  Otherwise, you should cancel the save with `C-g' and
+investigate the situation.
+
+   The first thing you should do when notified that simultaneous editing
+has already taken place is to list the directory with `C-u C-x C-d'
+(*note Directory Listing: ListDir.).  This will show the file's current
+author.  You should attempt to contact that person and ask him not to
+continue editing.  Often the next step is to save the contents of your
+Emacs buffer under a different name, and use `diff' to compare the two
+files.
+
+   Simultaneous editing checks are also made when you visit a file that
+is already visited with `C-x C-f' and when you start to modify a file.
+This is not strictly necessary, but it is useful to find out about such
+a problem as early as possible, when corrective action takes less work.
+
+   Another way to protect your file is to set the read, write, and
+executable permissions for the file. Use the function
+`set-default-file-modes' to set the UNIX `umask' value to the NMASK
+argument. The `umask' value is the default protection mode for new
+files.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Menubar Basics,  Next: Scrollbar Basics,  Up: GUI Components
+File: xemacs.info,  Node: Reverting,  Next: Auto Save,  Prev: Saving,  Up: Files

 
 

-The XEmacs Menubar
+Reverting a Buffer

 ==================
 
 ==================
 

-   The XEmacs menubar is intended to be conformant to the usual
-conventions for menubars, although conformance is not yet perfect.  The
-menu at the extreme right is the `Help' menu, which should always be
-available.  It provides access to all the XEmacs help facilities
-available through `C-h', as well as samples of various configuration
-files like `~/.Xdefaults' and `~/.emacs'.  At the extreme left is the
-`Files' menu, which provides the usual file reading, writing, and
-printing operations, as well as operations like revert buffer from most
-recent save.  The next menu from the left is the `Edit' menu, which
-provides the `Undo' operation as well as cutting and pasting,
-searching, and keyboard macro definition and execution.
-
-   XEmacs provides a very dynamic environment, and the Lisp language
-makes for highly flexible applications.  The menubar reflects this:
-many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
-determined by the current state of XEmacs, and most major modes and many
-minor modes add items to menus and even whole menus to the menubar.  In
-fact, some applications like w3.el and VM provide so many menus that
-they define a whole new menubar and add a button that allows convenient
-switching between the "XEmacs menubar" and the "application menubar".
-Such applications normally bind themselves to a particular frame, and
-this switching only takes place on frames where such an application is
-active (ie, the current window of the frame is displaying a buffer in
-the appropriate major mode).
-
-   Other menus which are typically available are the `Options',
-`Tools', `Buffers', `Apps', and `Mule' menus.  For detailed
-descriptions of these menus, *Note Pull-down Menus::.  (In 21.2
-XEmacsen, the `Mule' menu will be moved under `Options'.)
-
-\1f
-File: xemacs.info,  Node: Scrollbar Basics,  Next: Mode Line Basics,  Prev: Menubar Basics,  Up: GUI Components
-
-XEmacs Scrollbars
-=================
+If you have made extensive changes to a file and then change your mind
+about them, you can get rid of all changes by reading in the previous
+version of the file.  To do this, use `M-x revert-buffer', which
+operates on the current buffer.  Since reverting a buffer can result in
+very extensive changes, you must confirm it with `yes'.
+
+   You may request that `revert-buffer' check for an auto-save file
+that is more recent than the visited file by providing a prefix
+argument.  If a recent auto-save file exists, `revert-buffer' offers to
+read the auto-save file instead of the visited file (*note Auto
+Save::).  Emacs asks you about the auto-save file before the request
+for confirmation of the `revert-buffer' operation, and demands `y' or
+`n' as an answer.  If you have started to type `yes' to confirm the
+revert operation, the `y' will answer the question about using the
+auto-save file, but the `es' will not be valid confirmation for the
+reversion.  This gives you a chance to cancel the operation with `C-g'
+and try again with the answers you really intend.
+
+   `revert-buffer' preserves the value of point (in characters from the
+beginning of the file).  If the file was edited only slightly, you will
+be at approximately the same piece of text after reverting as before.
+If you have made more extensive changes, after reversion point may be
+in a totally different context than your last edits before reversion.
+
+   A buffer reverted from its visited file is marked "not modified"
+until you make a change.  The buffer's modes will also be recalculated,
+by `normal-mode'.
+
+   Some kinds of buffers whose contents reflect data bases other than
+files, such as Dired buffers, can also be reverted.  For them,
+reverting means refreshing their contents from the appropriate data.
+Buffers created randomly with `C-x b' cannot be reverted;
+`revert-buffer' reports an error when asked to do so.
+
+\1f
+File: xemacs.info,  Node: Auto Save,  Next: Version Control,  Prev: Reverting,  Up: Files
+
+Auto-Saving: Protection Against Disasters
+=========================================
+
+Emacs saves all the visited files from time to time (based on counting
+your keystrokes) without being asked.  This is called "auto-saving".
+It prevents you from losing more than a limited amount of work if the
+system crashes.
+
+   When Emacs determines it is time for auto-saving, each buffer is
+considered and is auto-saved if auto-saving is turned on for it and it
+has changed since the last time it was auto-saved.  If any auto-saving
+is done, the message `Auto-saving...' is displayed in the echo area
+until auto-saving is finished.  Errors occurring during auto-saving are
+caught so that they do not interfere with the execution of commands you
+have been typing.

 
 

-   XEmacs scrollbars provide the usual interface.  Arrow buttons at
-either end allow for line by line scrolling, including autorepeat.
-Clicking in the scrollbar itself provides scrolling by windowsfull,
-depending on which side of the slider is clicked.  The slider itself
-may be dragged for smooth scrolling.
+* Menu:

 
 

-   The position of the slider corresponds to the position of the window
-in the buffer.  In particular, the length of the slider is proportional
-to the fraction of the buffer which appears in the window.
+* Files: Auto Save Files.
+* Control: Auto Save Control.
+* Recover::            Recovering text from auto-save files.

 
 

-   The presence of the scrollbars is under control of the application or
-may be customized by the user.  By default a vertical scrollbar is
-present in all windows (except the minibuffer), and there is no
-horizontal scrollbar.
+\1f
+File: xemacs.info,  Node: Auto Save Files,  Next: Auto Save Control,  Prev: Auto Save,  Up: Auto Save
+
+Auto-Save Files
+---------------
+
+Auto-saving does not normally write to the files you visited, because
+it can be undesirable to save a program that is in an inconsistent
+state when you have made only half of a planned change.  Instead,
+auto-saving is done in a different file called the "auto-save file",
+and the visited file is changed only when you save explicitly, for
+example, with `C-x C-s'.
+
+   Normally, the name of the auto-save file is generated by appending
+`#' to the front and back of the visited file name.  Thus, a buffer
+visiting file `foo.c' would be auto-saved in a file `#foo.c#'.  Most
+buffers that are not visiting files are auto-saved only if you request
+it explicitly; when they are auto-saved, the auto-save file name is
+generated by appending `#%' to the front and `#' to the back of buffer
+name.  For example, the `*mail*' buffer in which you compose messages
+to be sent is auto-saved in a file named `#%*mail*#'.  Names of
+auto-save files are generated this way unless you customize the
+functions `make-auto-save-file-name' and `auto-save-file-name-p' to do
+something different.  The file name to be used for auto-saving a buffer
+is calculated at the time auto-saving is turned on in that buffer.
+
+   If you want auto-saving to be done in the visited file, set the
+variable `auto-save-visited-file-name' to be non-`nil'.  In this mode,
+there is really no difference between auto-saving and explicit saving.
+
+   Emacs deletes a buffer's auto-save file when you explicitly save the
+buffer.  To inhibit the deletion, set the variable
+`delete-auto-save-files' to `nil'.  Changing the visited file name with
+`C-x C-w' or `set-visited-file-name' renames any auto-save file to
+correspond to the new visited name.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Mode Line Basics,  Next: Toolbar Basics,  Prev: Scrollbar Basics,  Up: GUI Components
+File: xemacs.info,  Node: Auto Save Control,  Next: Recover,  Prev: Auto Save Files,  Up: Auto Save

 
 

-XEmacs Mode Lines
-=================
+Controlling Auto-Saving
+-----------------------
+
+Each time you visit a file, auto-saving is turned on for that file's
+buffer if the variable `auto-save-default' is non-`nil' (but not in
+batch mode; *note Entering Emacs::).  The default for this variable is
+`t', so Emacs auto-saves buffers that visit files by default.  You can
+use the command `M-x auto-save-mode' to turn auto-saving for a buffer
+on or off.  Like other minor mode commands, `M-x auto-save-mode' turns
+auto-saving on with a positive argument, off with a zero or negative
+argument; with no argument, it toggles.
+
+   Emacs performs auto-saving periodically based on counting how many
+characters you have typed since the last time auto-saving happened.  The
+variable `auto-save-interval' specifies the number of characters
+between auto-saves.  By default, it is 300.  Emacs also auto-saves
+whenever you call the function `do-auto-save'.
+
+   Emacs also does auto-saving whenever it gets a fatal error.  This
+includes killing the Emacs job with a shell command such as `kill
+-emacs', or disconnecting a phone line or network connection.
+
+   You can set the number of seconds of idle time before an auto-save is
+done. Setting the value of the variable `auto-save-timeout' to zero or
+`nil' will  disable auto-saving due to idleness.
+
+   The actual amount of idle time between auto-saves is logarithmically
+related to the size of the current buffer.  This variable is the number
+of seconds after which an auto-save will happen when the current buffer
+is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3
+3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k
+buffer.
+
+   For this variable to have any effect, you must do `(require 'timer)'.
+
+\1f
+File: xemacs.info,  Node: Recover,  Prev: Auto Save Control,  Up: Auto Save
+
+Recovering Data from Auto-Saves
+-------------------------------

 
 

-   When used in a windowing system, the XEmacs modelines can be dragged
-vertically. The effect is to resize the windows above and below the
-modeline (this includes the minibuffer window).
+If you want to use the contents of an auto-save file to recover from a
+loss of data, use the command `M-x recover-file <RET> FILE <RET>'.
+Emacs visits FILE and then (after your confirmation) restores the
+contents from the auto-save file `#FILE#'.  You can then save the file
+with `C-x C-s' to put the recovered text into FILE itself.  For
+example, to recover file `foo.c' from its auto-save file `#foo.c#', do:

 
 

-   Additionally, a modeline can be dragged horizontally, in which case
-it scrolls its own text. This behavior is not enabled by default
-because it could be considered as disturbing when dragging vertically.
-When this behavior is enabled, the modeline's text can be dragged
-either in the same direction as the mouse, or in the opposite sense,
-making the modeline act as a scrollbar for its own text.
+     M-x recover-file <RET> foo.c <RET>
+     C-x C-s

 
 

-   You can select the behavior you want from the `Display' submenu of
-the `Options' menu.
+   Before asking for confirmation, `M-x recover-file' displays a
+directory listing describing the specified file and the auto-save file,
+so you can compare their sizes and dates.  If the auto-save file is
+older, `M-x recover-file' does not offer to read it.
+
+   Auto-saving is disabled by `M-x recover-file' because using this
+command implies that the auto-save file contains valuable data from a
+past session.  If you save the data in the visited file and then go on
+to make new changes, turn auto-saving back on with `M-x auto-save-mode'.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Toolbar Basics,  Next: Gutter Basics,  Prev: Mode Line Basics,  Up: GUI Components
+File: xemacs.info,  Node: Version Control,  Next: ListDir,  Prev: Auto Save,  Up: Files

 
 

-XEmacs Toolbars
+Version Control

 ===============
 
 ===============
 

-   XEmacs has a default toolbar which provides shortcuts for some of the
-commonly used operations (such as opening files) and applications (such
-as the Info manual reader).  Operations which require arguments will pop
-up dialogs to get them.
+"Version control systems" are packages that can record multiple
+versions of a source file, usually storing the unchanged parts of the
+file just once.  Version control systems also record history information
+such as the creation time of each version, who created it, and a
+description of what was changed in that version.
+
+   The GNU project recommends the version control system known as RCS,
+which is free software and available from the Free Software Foundation.
+Emacs supports use of either RCS or SCCS (a proprietary, but widely
+used, version control system that is not quite as powerful as RCS)
+through a facility called VC.  The same Emacs commands work with either
+RCS or SCCS, so you hardly have to know which one of them you are using.
+
+* Menu:

 
 

-   The position of the default toolbar can be customized.  Also, several
-toolbars may be present simultaneously (in different positions).  VM,
-for example, provides an application toolbar which shortcuts for
-mail-specific operations like sending, saving, and deleting messages.
+* Concepts of VC::              Basic version control information;
+                                  checking files in and out.
+* Editing with VC::             Commands for editing a file maintained
+                                  with version control.
+* Variables for Check-in/out::  Variables that affect the commands used
+                                  to check files in or out.
+* Log Entries::                 Logging your changes.
+* Change Logs and VC::          Generating a change log file from log
+                                  entries.
+* Old Versions::                Examining and comparing old versions.
+* VC Status::                   Commands to view the VC status of files and
+                                  look at log entries.
+* Renaming and VC::             A command to rename both the source and
+                                  master file correctly.
+* Snapshots::                   How to make and use snapshots, a set of
+                                  file versions that can be treated as a unit.
+* Version Headers::             Inserting version control headers into
+                                  working files.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Gutter Basics,  Next: Inhibiting,  Prev: Toolbar Basics,  Up: GUI Components
+File: xemacs.info,  Node: Concepts of VC,  Next: Editing with VC,  Prev: Version Control,  Up: Version Control

 
 

-XEmacs Gutters
-==============
+Concepts of Version Control
+---------------------------

 
 

-   Gutters are the most flexible of the GUI components described in this
-section.  In theory, the other GUI components could be implemented by
-customizing a gutter, but in practice the other components were
-introduced earlier and have their own special implementations.  Gutters
-tend to be more transient than the other components.  Buffer tabs, for
-example, change every time the selected buffer in the frame changes.
-And for progress gauges a gutter to contain the gauge is typically
-created on the fly when needed, then destroyed when the operation whose
-staus is being displayed is completed.
-
-   Buffer tabs, having somewhat complex behavior, deserve a closer look.
-By default, a row of buffer tabs is displayed at the top of every frame.
-(The tabs could be placed in the bottom gutter, but would be oriented
-the same way and look rather odd.  The horizontal orientation makes
-putting them in a side gutter utterly impractical.)  The buffer
-displayed in the current window of a frame can be changed to a specific
-buffer by clicking [mouse-1] on the corresponding tab in the gutter.
-
-   Each tab contains the name of its buffer.  The tab for the current
-buffer in each frame is displayed in raised relief.  The list of buffers
-chosen for display in the buffer tab row is derived by filtering the
-buffer list (like the `Buffers' menu).  The list starts out with all
-existing buffers, with more recently selected buffers coming earlier in
-the list.
-
-   Then "uninteresting" buffers, like internal XEmacs buffers, the
-`*Message Log*' buffer, and so on are deleted from the list.  Next, the
-frame's selected buffer is determined.  Buffers with a different major
-mode from the selected buffer are removed from the list.  Finally, if
-the list is too long, the least recently used buffers are deleted from
-the list.  By default up to 6 most recently used buffers with the same
-mode are displayed on tabs in the gutter.
-
-\1f
-File: xemacs.info,  Node: Inhibiting,  Next: Customizing,  Prev: Gutter Basics,  Up: GUI Components
-
-Inhibiting Display of GUI Components
-====================================
-
-   Use of GUI facilities is a personal thing.  Almost everyone agrees
-that drawing via keyboard-based "turtle graphics" is acceptable to
-hardly anyone if a mouse is available, but conversely emulating a
-keyboard with a screenful of buttons is a painful experience.  But
-between those extremes the complete novice will require a fair amount
-of time before toolbars and menus become dispensable, but many an
-"Ancien Haquer" sees them as a complete waste of precious frame space
-that could be filled with text.
-
-   Display of all of the GUI components created by XEmacs can be
-inhibited through the use of Customize.  Customize can be accessed
-through `Options | Customize' in the menu bar, or via `M-x customize'.
-Then navigate through the Customize tree to `Emacs | Environment'.
-Scrollbar and toolbar visibility is controlled via the `Display' group,
-options `Scrollbars visible' and  `Toolbar visible' respectively.
-Gutter visibility is controlled by group `Gutter', option `Visible'.
-
-   Or they can be controlled directly by `M-x customize-variable', by
-changing the values of the variables `menubar-visible-p',
-`scrollbars-visible-p', `toolbar-visible-p', or
-`gutter-buffers-tab-visible-p' respectively.  (The strange form of the
-last variable is due to the fact that gutters are often used to display
-transient widgets like progress gauges, which you probably don't want
-to inhibit.  It is more likely that you want to inhibit the default
-display of the buffers tab widget, which is what that variable controls.
-This interface is subject to change depending on developer experience
-and user feedback.)
-
-   Control of frame configuration can controlled automatically
-according to various parameters such as buffer or frame because these
-are "specifiers" *Note Specifiers: (lispref)Specifiers.  Using these
-features requires programming in Lisp; Customize is not yet that
-sophisticated.  Also, components that appear in various positions and
-orientations can have display suppressed according to position.  `C-h a
-visible-p' gives a list of variables which can be customized.  E.g., to
-control the visibility of specifically the left-side toolbar only,
-customize `left-toolbar-visible-p'.
-
-\1f
-File: xemacs.info,  Node: Customizing,  Prev: Inhibiting,  Up: GUI Components
-
-Changing the Position, Orientation, and Appearance of GUI Components
-====================================================================
-
-   #### Not documented yet.
-
-\1f
-File: xemacs.info,  Node: XEmacs under X,  Next: XEmacs under MS Windows,  Prev: GUI Components,  Up: Frame
-
-Using XEmacs Under the X Window System
-======================================
+When a file is under version control, we also say that it is
+"registered" in the version control system.  Each registered file has a
+corresponding "master file" which represents the file's present state
+plus its change history, so that you can reconstruct from it either the
+current version or any specified earlier version.  Usually the master
+file also records a "log entry" for each version describing what was
+changed in that version.
+
+   The file that is maintained under version control is sometimes called
+the "work file" corresponding to its master file.
+
+   To examine a file, you "check it out".  This extracts a version of
+the source file (typically, the most recent) from the master file.  If
+you want to edit the file, you must check it out "locked".  Only one
+user can do this at a time for any given source file.  (This kind of
+locking is completely unrelated to the locking that Emacs uses to
+detect simultaneous editing of a file.)
+
+   When you are done with your editing, you must "check in" the new
+version.  This records the new version in the master file, and unlocks
+the source file so that other people can lock it and thus modify it.
+
+   Checkin and checkout are the basic operations of version control.
+You can do both of them with a single Emacs command: `C-x C-q'
+(`vc-toggle-read-only').
+
+   A "snapshot" is a coherent collection of versions of the various
+files that make up a program.  *Note Snapshots::.
+
+\1f
+File: xemacs.info,  Node: Editing with VC,  Next: Variables for Check-in/out,  Prev: Concepts of VC,  Up: Version Control
+
+Editing with Version Control
+----------------------------
+
+When you visit a file that is maintained using version control, the
+mode line displays `RCS' or `SCCS' to inform you that version control
+is in use, and also (in case you care) which low-level system the file
+is actually stored in.  Normally, such a source file is read-only, and
+the mode line indicates this with `%%'.  With RCS, the mode line also
+indicates the number of the head version, which is normally also the
+version you are looking at.
+
+   These are the commands for editing a file maintained with version
+control:
+
+`C-x C-q'
+     Check the visited file in or out.
+
+`C-x v u'
+     Revert the buffer and the file to the last checked in version.
+
+`C-x v c'
+     Remove the last-entered change from the master for the visited
+     file.  This undoes your last check-in.
+
+`C-x v i'
+     Register the visited file in version control.
+
+(`C-x v' is the prefix key for version control commands; all of these
+commands except for `C-x C-q' start with `C-x v'.)
+
+   When you want to modify a file maintained with version control, type
+`C-x C-q' (`vc-toggle-read-only').  This "checks out" the file, and
+tells RCS or SCCS to lock the file.  This means making the file
+writable for you (but not for anyone else).
+
+   When you are finished editing the file, type `C-x C-q' again.  When
+used on a file that is checked out, this command checks the file in.
+But check-in does not start immediately; first, you must enter the "log
+entry"--a description of the changes in the new version.  `C-x C-q'
+pops up a buffer for you to enter this in.  When you are finished
+typing in the log entry, type `C-c C-c' to terminate it; this is when
+actual check-in takes place.
+
+   Once you have checked in your changes, the file is unlocked, so that
+other users can lock it and modify it.
+
+   Emacs does not save backup files for source files that are maintained
+with version control.  If you want to make backup files despite version
+control, set the variable `vc-make-backup-files' to a non-`nil' value.
+
+   Normally the work file exists all the time, whether it is locked or
+not.  If you set `vc-keep-workfiles' to `nil', then checking in a new
+version with `C-x C-q' deletes the work file; but any attempt to visit
+the file with Emacs creates it again.
+
+   It is not impossible to lock a file that someone else has locked.  If
+you try to check out a file that is locked, `C-x C-q' asks you whether
+you want to "steal the lock."  If you say yes, the file becomes locked
+by you, but a message is sent to the person who had formerly locked the
+file, to inform him of what has happened.  The mode line indicates that
+a file is locked by someone else by displaying the login name of that
+person, before the version number.
+
+   If you want to discard your current set of changes and revert to the
+last version checked in, use `C-x v u' (`vc-revert-buffer').  This
+cancels your last check-out, leaving the file unlocked.  If you want to
+make a different set of changes, you must first check the file out
+again.  `C-x v u' requires confirmation, unless it sees that you
+haven't made any changes since the last checked-in version.
+
+   `C-x v u' is also the command to use if you lock a file and then
+don't actually change it.
+
+   You can cancel a change after checking it in, with `C-x v c'
+(`vc-cancel-version').  This command discards all record of the most
+recent checked in version, so be careful about using it.  It requires
+confirmation with `yes'.  By default, `C-x v c' reverts your workfile
+and buffer to the previous version (the one that precedes the version
+that is deleted), but you can prevent the reversion by giving the
+command a prefix argument.  Then the buffer does not change.
+
+   This command with a prefix argument is useful when you have checked
+in a change and then discover a trivial error in it; you can cancel the
+erroneous check-in, fix the error, and repeat the check-in.
+
+   Be careful when invoking `C-x v c', as it is easy to throw away a
+lot of work with it.  To help you be careful, this command always
+requires confirmation with `yes'.
+
+   You can register the visited file for version control using
+`C-x v i' (`vc-register').  If the variable `vc-default-back-end' is
+non-`nil', it specifies which version control system to use; otherwise,
+this uses RCS if it is installed on your system and SCCS if not.  After
+`C-x v i', the file is unlocked and read-only.  Type `C-x C-q' if you
+wish to edit it.
+
+   By default, the initial version number is 1.1.  If you want to use a
+different number, give `C-x v i' a prefix argument; then it reads the
+initial version number using the minibuffer.
+
+   If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
+comment (much like a log entry) to describe the purpose of this source
+file.
+
+   To specify the version number for a subsequent checkin, use the
+command `C-u C-x v v'.  `C-x v v' (`vc-next-action') is the command
+that `C-x C-q' uses to do the "real work" when the visited file uses
+version control.  When used for checkin, and given a prefix argument,
+it reads the version number with the minibuffer.

 
 

-   XEmacs can be used with the X Window System and a window manager like
-MWM or TWM.  In that case, the X window manager opens, closes, and
-resizes XEmacs frames.  You use the window manager's mouse gestures to
-perform the operations.  Consult your window manager guide or reference
-manual for information on manipulating X windows.
+\1f
+File: xemacs.info,  Node: Variables for Check-in/out,  Next: Log Entries,  Prev: Editing with VC,  Up: Version Control
+
+Variables Affecting Check-in and Check-out
+------------------------------------------
+
+If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i' can
+save the current buffer without asking, and `C-x v u' also operates
+without asking for confirmation.  (This variable does not affect `C-x v
+c'; that is so drastic that it should always ask for confirmation.)
+
+   VC mode does much of its work by running the shell commands for RCS
+and SCCS.  If `vc-command-messages' is non-`nil', VC displays messages
+to indicate which shell commands it runs, and additional messages when
+the commands finish.
+
+   Normally, VC assumes that it can deduce the locked/unlocked state of
+files by looking at the file permissions of the work file; this is
+fast.  However, if the `RCS' or `SCCS' subdirectory is actually a
+symbolic link, then VC does not trust the file permissions to reflect
+this status.
+
+   You can specify the criterion for whether to trust the file
+permissions by setting the variable `vc-mistrust-permissions'.  Its
+value may be `t' (always mistrust the file permissions and check the
+master file), `nil' (always trust the file permissions), or a function
+of one argument which makes the decision.  The argument is the directory
+name of the `RCS' or `SCCS' subdirectory.  A non-`nil' value from the
+function says to mistrust the file permissions.
+
+   If you find that the file permissions of work files are changed
+erroneously, set `vc-mistrust-permissions' to `t'.  Then VC always
+checks the master file to determine the file's status.
+
+   You can specify additional directories to search for version control
+programs by setting the variable `vc-path'.  These directories are
+searched before the usual search path.  The proper result usually
+happens automatically.
+
+\1f
+File: xemacs.info,  Node: Log Entries,  Next: Change Logs and VC,  Prev: Variables for Check-in/out,  Up: Version Control
+
+Log Entries
+-----------
+
+When you're editing an initial comment or log entry for inclusion in a
+master file, finish your entry by typing `C-c C-c'.

 
 

-   When you are working under X, each X window (that is, each XEmacs
-frame) has a menu bar for mouse-controlled operations (*note Pull-down
-Menus::).
+`C-c C-c'
+     Finish the comment edit normally (`vc-finish-logentry').  This
+     finishes check-in.

 
 

-   XEmacs under X is also a multi-frame XEmacs.  You can use the New
-Frame menu item from the File menu to create a new XEmacs frame in a
-new X window from the same process.  The different frames will share the
-same buffer list, but you can look at different buffers in the different
-frames.
+   To abort check-in, just don't type `C-c C-c' in that buffer.  You
+can switch buffers and do other editing.  As long as you don't try to
+check in another file, the entry you were editing remains in its
+buffer, and you can go back to that buffer at any time to complete the
+check-in.

 
 

-   The function `find-file-other-frame' is just like `find-file', but
-creates a new frame to display the buffer in first.  This is normally
-bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
-does.
+   If you change several source files for the same reason, it is often
+convenient to specify the same log entry for many of the files.  To do
+this, use the history of previous log entries.  The commands `M-n',
+`M-p', `M-s' and `M-r' for doing this work just like the minibuffer
+history commands (except that these versions are used outside the
+minibuffer).

 
 

-   The function `switch-to-buffer-other-frame' is just like
-`switch-to-buffer', but creates a new frame to display the buffer in
-first.  This is normally bound to `C-x 5 b'.
+   Each time you check in a file, the log entry buffer is put into VC
+Log mode, which involves running two hooks: `text-mode-hook' and
+`vc-log-mode-hook'.

 
 

-   You can specify a different default frame size other than the one
-provided.  Use the variable `default-frame-alist', which is an alist of
-default values for frame creation other than the first one.  These may
-be set in your init file, like this:
+\1f
+File: xemacs.info,  Node: Change Logs and VC,  Next: Old Versions,  Prev: Log Entries,  Up: Version Control
+
+Change Logs and VC
+------------------
+
+If you use RCS for a program and also maintain a change log file for it
+(*note Change Log::), you can generate change log entries automatically
+from the version control log entries:
+
+`C-x v a'
+     Visit the current directory's change log file and create new
+     entries for versions checked in since the most recent entry in the
+     change log file (`vc-update-change-log').
+
+     This command works with RCS only; it does not work with SCCS.
+
+   For example, suppose the first line of `ChangeLog' is dated 10 April
+1992, and that the only check-in since then was by Nathaniel Bowditch
+to `rcs2log' on 8 May 1992 with log text `Ignore log messages that
+start with `#'.'.  Then `C-x v a' visits `ChangeLog' and inserts text
+like this:
+
+     Fri May  8 21:45:00 1992  Nathaniel Bowditch  (nat@apn.org)
+     
+             * rcs2log: Ignore log messages that start with `#'.
+
+You can then edit the new change log entry further as you wish.
+
+   Normally, the log entry for file `foo' is displayed as `* foo: TEXT
+OF LOG ENTRY'.  The `:' after `foo' is omitted if the text of the log
+entry starts with `(FUNCTIONNAME): '.  For example, if the log entry
+for `vc.el' is `(vc-do-command): Check call-process status.', then the
+text in `ChangeLog' looks like this:
+
+     Wed May  6 10:53:00 1992  Nathaniel Bowditch  (nat@apn.org)
+     
+             * vc.el (vc-do-command): Check call-process status.
+
+   When `C-x v a' adds several change log entries at once, it groups
+related log entries together if they all are checked in by the same
+author at nearly the same time.  If the log entries for several such
+files all have the same text, it coalesces them into a single entry.
+For example, suppose the most recent checkins have the following log
+entries:
+
+For `vc.texinfo':
+     Fix expansion typos.
+For `vc.el':
+     Don't call expand-file-name.
+For `vc-hooks.el':
+     Don't call expand-file-name.
+
+   They appear like this in `ChangeLog':
+
+     Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  (nat@apn.org)
+     
+             * vc.texinfo: Fix expansion typos.
+     
+             * vc.el, vc-hooks.el: Don't call expand-file-name.
+
+   Normally, `C-x v a' separates log entries by a blank line, but you
+can mark several related log entries to be clumped together (without an
+intervening blank line) by starting the text of each related log entry
+with a label of the form `{CLUMPNAME} '.  The label itself is not
+copied to `ChangeLog'.  For example, suppose the log entries are:
+
+For `vc.texinfo':
+     {expand} Fix expansion typos.
+For `vc.el':
+     {expand} Don't call expand-file-name.
+For `vc-hooks.el':
+     {expand} Don't call expand-file-name.
+
+Then the text in `ChangeLog' looks like this:
+
+     Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  (nat@apn.org)
+     
+             * vc.texinfo: Fix expansion typos.
+             * vc.el, vc-hooks.el: Don't call expand-file-name.
+
+   A log entry whose text begins with `#' is not copied to `ChangeLog'.
+For example, if you merely fix some misspellings in comments, you can
+log the change with an entry beginning with `#' to avoid putting such
+trivia into `ChangeLog'.
+
+\1f
+File: xemacs.info,  Node: Old Versions,  Next: VC Status,  Prev: Change Logs and VC,  Up: Version Control
+
+Examining And Comparing Old Versions
+------------------------------------

 
 

-       (setq default-frame-alist '((width . 80) (height . 55)))
+`C-x v ~ VERSION <RET>'
+     Examine version VERSION of the visited file, in a buffer of its
+     own (`vc-version-other-window').

 
 

-   For values specific to the first XEmacs frame, you must use X
-resources.  The variable `x-frame-defaults' takes an alist of default
-frame creation parameters for X window frames.  These override what is
-specified in `~/.Xdefaults' but are overridden by the arguments to the
-particular call to `x-create-frame'.
+`C-x v ='
+     Compare the current buffer contents with the latest checked-in
+     version of the file.

 
 

-   When you create a new frame, the variable `create-frame-hook' is
-called with one argument, the frame just created.
+`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
+     Compare the specified two versions of FILE.

 
 

-   If you want to close one or more of the X windows you created using
-New Frame, use the Delete Frame menu item from the File menu.
+   You can examine any version of a file by first visiting it, and then
+using `C-x v ~ VERSION <RET>' (`vc-version-other-window').  This puts
+the text of version VERSION in a file named `FILENAME.~VERSION~', then
+visits it in a separate window.

 
 

-   If you are working with multiple frames, some special information
-applies:
-   * Two variables, `frame-title-format' and `frame-icon-title-format'
-     determine the title of the frame and the title of the icon that
-     results if you shrink the frame.
+   To compare two versions of a file, use the command `C-x v ='
+(`vc-diff').

 
 

-   * The variables `auto-lower-frame' and `auto-raise-frame' position a
-     frame. If true, `auto-lower-frame' lowers a frame to the bottom
-     when it is no longer selected. If true, `auto-raise-frame' raises
-     a frame to the top when it is selected. Under X, most
-     ICCCM-compliant window managers will have options to do this for
-     you, but these variables are provided in case you are using a
-     broken window manager.
+   Plain `C-x v =' compares the current buffer contents (saving them in
+the file if necessary) with the last checked-in version of the file.
+With a prefix argument, `C-x v =' reads a file name and two version
+numbers, then compares those versions of the specified file.

 
 

-   * There is a new frame/modeline format directive, %S, which expands
-     to the name of the current frame (a frame's name is distinct from
-     its title; the name is used for resource lookup, among other
-     things, and the title is simply what appears above the window.)
+   If you supply a directory name instead of the name of a work file,
+this command compares the two specified versions of all registered files
+in that directory and its subdirectories.  You can also specify a
+snapshot name (*note Snapshots::) instead of one or both version
+numbers.
+
+   You can specify a checked-in version by its number; you can specify
+the most recent checked-in version with an empty version number.
+
+   This command works by running the `vcdiff' utility, getting the
+options from the variable `diff-switches'.  It displays the output in a
+special buffer in another window.  Unlike the `M-x diff' command, `C-x
+v =' does not try to find the changes in the old and new versions.
+This is because one or both versions normally do not exist as files.
+They exist only in the records of the master file.  *Note Comparing
+Files::, for more information about `M-x diff'.
+
+\1f
+File: xemacs.info,  Node: VC Status,  Next: Renaming and VC,  Prev: Old Versions,  Up: Version Control
+
+VC Status Commands
+------------------
+
+To view the detailed version control status and history of a file, type
+`C-x v l' (`vc-print-log').  It displays the history of changes to the
+current file, including the text of the log entries.  The output
+appears in a separate window.
+
+   When you are working on a large program, it's often useful to find
+all the files that are currently locked, or all the files maintained in
+version control at all.  You can use `C-x v d' (`vc-directory') to show
+all the locked files in or beneath the current directory.  This
+includes all files that are locked by any user.  `C-u C-x v d' lists
+all files in or beneath the current directory that are maintained with
+version control.
+
+   The list of files is displayed as a buffer that uses an augmented
+Dired mode.  The names of the users locking various files are shown (in
+parentheses) in place of the owner and group.  All the normal Dired
+commands work in this buffer.  Most interactive VC commands work also,
+and apply to the file name on the current line.
+
+   The `C-x v v' command (`vc-next-action'), when used in the augmented
+Dired buffer, operates on all the marked files (or the file on the
+current line).  If it operates on more than one file, it handles each
+file according to its current state; thus, it may check out one file
+and check in another (because it is already checked out).  If it has to
+check in any files, it reads a single log entry, then uses that text
+for all the files being checked in.  This can be convenient for
+registering or checking in several files at once, as part of the same
+change.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: XEmacs under MS Windows,  Prev: XEmacs under X,  Up: Frame
+File: xemacs.info,  Node: Renaming and VC,  Next: Snapshots,  Prev: VC Status,  Up: Version Control

 
 

-Using XEmacs Under Microsoft Windows
-====================================
+Renaming VC Work Files and Master Files
+---------------------------------------

 
 

-   Use of XEmacs under MS Windows is not separately documented here, but
-most operations available under the X Window System are also available
-with MS Windows.
+When you rename a registered file, you must also rename its master file
+correspondingly to get proper results.  Use `vc-rename-file' to rename
+the source file as you specify, and rename its master file accordingly.
+It also updates any snapshots (*note Snapshots::) that mention the
+file, so that they use the new name; despite this, the snapshot thus
+modified may not completely work (*note Snapshot Caveats::).

 
 

-   Where possible, native MS Windows GUI components and capabilities are
-used in XEmacs.
+   You cannot use `vc-rename-file' on a file that is locked by someone
+else.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Keystrokes,  Next: Pull-down Menus,  Prev: Frame,  Up: Top
+File: xemacs.info,  Node: Snapshots,  Next: Version Headers,  Prev: Renaming and VC,  Up: Version Control

 
 

-Keystrokes, Key Sequences, and Key Bindings
-*******************************************
+Snapshots
+---------
+
+A "snapshot" is a named set of file versions (one for each registered
+file) that you can treat as a unit.  One important kind of snapshot is
+a "release", a (theoretically) stable version of the system that is
+ready for distribution to users.

 
 * Menu:
 
 
 * Menu:
 

-* Intro to Keystrokes::      Keystrokes as building blocks of key sequences.
-* Representing Keystrokes::  Using lists of modifiers and keysyms to
-                             represent keystrokes.
-* Key Sequences::            Combine key strokes into key sequences you can
-                             bind to commands.
-* String Key Sequences::     Available for upward compatibility.
-* Meta Key::                 Using <ESC> to represent <Meta>
-* Super and Hyper Keys::     Adding modifier keys on certain keyboards.
-* Character Representation:: How characters appear in Emacs buffers.
-* Commands::                 How commands are bound to key sequences.
+* Making Snapshots::           The snapshot facilities.
+* Snapshot Caveats::           Things to be careful of when using snapshots.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Intro to Keystrokes,  Next: Representing Keystrokes,  Prev: Keystrokes,  Up: Keystrokes
+File: xemacs.info,  Node: Making Snapshots,  Next: Snapshot Caveats,  Prev: Snapshots,  Up: Snapshots
+
+Making and Using Snapshots
+..........................

 
 

-Keystrokes as Building Blocks of Key Sequences
-==============================================
+There are two basic commands for snapshots; one makes a snapshot with a
+given name, the other retrieves a named snapshot.

 
 

-   Earlier versions of Emacs used only the ASCII character set, which
-defines 128 different character codes.  Some of these codes are
-assigned graphic symbols like `a' and `='; the rest are control
-characters, such as `Control-a' (also called `C-a').  `C-a' means you
-hold down the <CTRL> key and then press `a'.
+`C-x v s NAME <RET>'
+     Define the last saved versions of every registered file in or
+     under the current directory as a snapshot named NAME
+     (`vc-create-snapshot').

 
 

-   Keybindings in XEmacs are not restricted to the set of keystrokes
-that can be represented in ASCII.  XEmacs can tell the difference
-between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
+`C-x v r NAME <RET>'
+     Check out all registered files at or below the current directory
+     level using whatever versions correspond to the snapshot NAME
+     (`vc-retrieve-snapshot').

 
 

-   A keystroke is like a piano chord: you get it by simultaneously
-striking several keys.  To be more precise, a keystroke consists of a
-possibly empty set of modifiers followed by a single "keysym".  The set
-of modifiers is small; it consists of `Control', `Meta', `Super',
-`Hyper', and `Shift'.
+     This command reports an error if any files are locked at or below
+     the current directory, without changing anything; this is to avoid
+     overwriting work in progress.

 
 

-   The rest of the keys on your keyboard, along with the mouse buttons,
-make up the set of keysyms.  A keysym is usually what is printed on the
-keys on your keyboard.  Here is a table of some of the symbolic names
-for keysyms:
-`a,b,c...'
-     alphabetic keys
+   A snapshot uses a very small amount of resources--just enough to
+record the list of file names and which version belongs to the
+snapshot.  Thus, you need not hesitate to create snapshots whenever
+they are useful.

 
 

-`f1,f2...'
-     function keys
+   You can give a snapshot name as an argument to `C-x v =' or `C-x v
+~' (*note Old Versions::).  Thus, you can use it to compare a snapshot
+against the current files, or two snapshots against each other, or a
+snapshot against a named version.
+
+\1f
+File: xemacs.info,  Node: Snapshot Caveats,  Prev: Making Snapshots,  Up: Snapshots
+
+Snapshot Caveats
+................
+
+VC's snapshot facilities are modeled on RCS's named-configuration
+support.  They use RCS's native facilities for this, so under VC
+snapshots made using RCS are visible even when you bypass VC.
+
+   For SCCS, VC implements snapshots itself.  The files it uses contain
+name/file/version-number triples.  These snapshots are visible only
+through VC.
+
+   A snapshot is a set of checked-in versions.  So make sure that all
+the files are checked in and not locked when you make a snapshot.
+
+   File renaming and deletion can create some difficulties with
+snapshots.  This is not a VC-specific problem, but a general design
+issue in version control systems that no one has solved very well yet.
+
+   If you rename a registered file, you need to rename its master along
+with it (the command `vc-rename-file' does this automatically).  If you
+are using SCCS, you must also update the records of the snapshot, to
+mention the file by its new name (`vc-rename-file' does this, too).  An
+old snapshot that refers to a master file that no longer exists under
+the recorded name is invalid; VC can no longer retrieve it.  It would
+be beyond the scope of this manual to explain enough about RCS and SCCS
+to explain how to update the snapshots by hand.
+
+   Using `vc-rename-file' makes the snapshot remain valid for
+retrieval, but it does not solve all problems.  For example, some of the
+files in the program probably refer to others by name.  At the very
+least, the makefile probably mentions the file that you renamed.  If you
+retrieve an old snapshot, the renamed file is retrieved under its new
+name, which is not the name that the makefile expects.  So the program
+won't really work as retrieved.

 
 

-`button1'
-     left mouse button
+\1f
+File: xemacs.info,  Node: Version Headers,  Prev: Snapshots,  Up: Version Control
+
+Inserting Version Control Headers
+---------------------------------
+
+Sometimes it is convenient to put version identification strings
+directly into working files.  Certain special strings called "version
+headers" are replaced in each successive version by the number of that
+version.
+
+   You can use the `C-x v h' command (`vc-insert-headers') to insert a
+suitable header string.
+
+`C-x v h'
+     Insert headers in a file for use with your version-control system.
+
+   The default header string is `\$Id\$' for RCS and `\%W\%' for SCCS.
+(The actual strings inserted do not have the backslashes in them.  They
+were placed in the Info source file so that the strings don't get
+interpreted as version-control headers when the Info source files are
+maintained under version control.) You can specify other headers to
+insert by setting the variable `vc-header-alist'.  Its value is a list
+of elements of the form `(PROGRAM . STRING)' where PROGRAM is `RCS' or
+`SCCS' and STRING is the string to use.
+
+   Instead of a single string, you can specify a list of strings; then
+each string in the list is inserted as a separate header on a line of
+its own.
+
+   It is often necessary to use "superfluous" backslashes when writing
+the strings that you put in this variable.  This is to prevent the
+string in the constant from being interpreted as a header itself if the
+Emacs Lisp file containing it is maintained with version control.
+
+   Each header is inserted surrounded by tabs, inside comment
+delimiters, on a new line at the start of the buffer.  Normally the
+ordinary comment start and comment end strings of the current mode are
+used, but for certain modes, there are special comment delimiters for
+this purpose; the variable `vc-comment-alist' specifies them.  Each
+element of this list has the form `(MODE STARTER ENDER)'.
+
+   The variable `vc-static-header-alist' specifies further strings to
+add based on the name of the buffer.  Its value should be a list of
+elements of the form `(REGEXP . FORMAT)'.  Whenever REGEXP matches the
+buffer name, FORMAT is inserted as part of the header.  A header line
+is inserted for each element that matches the buffer name, and for each
+string specified by `vc-header-alist'.  The header line is made by
+processing the string from `vc-header-alist' with the format taken from
+the element.  The default value for `vc-static-header-alist' is:
+
+     (("\\.c$" .
+       "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+     #endif /* lint */\n"))
+
+which specifies insertion of a string of this form:
+
+
+     #ifndef lint
+     static char vcid[] = "STRING";
+     #endif /* lint */

 
 

-`button2'
-     middle mouse button
+\1f
+File: xemacs.info,  Node: ListDir,  Next: Comparing Files,  Prev: Version Control,  Up: Files

 
 

-`button3'
-     right mouse button
+Listing a File Directory
+========================

 
 

-`button1up'
-     upstroke on the left mouse button
+Files are organized by Unix into "directories".  A "directory listing"
+is a list of all the files in a directory.  Emacs provides directory
+listings in brief format (file names only) and verbose format (sizes,
+dates, and authors included).

 
 

-`button2up'
-     upstroke on the middle mouse button
+`C-x C-d DIR-OR-PATTERN'
+     Print a brief directory listing (`list-directory').

 
 

-`button3up'
-     upstroke on the right mouse button
+`C-u C-x C-d DIR-OR-PATTERN'
+     Print a verbose directory listing.

 
 

-`return'
-     Return key
+   To print a directory listing, use `C-x C-d' (`list-directory').
+This command prompts in the minibuffer for a file name which is either
+a  directory to be listed or pattern containing wildcards for the files
+to be listed.  For example,

 
 

-   Use the variable `keyboard-translate-table' only if you are on a
-dumb tty, as it cannot handle input that cannot be represented as ASCII.
-The value of this variable is a string used as a translate table for
-keyboard input or `nil'.  Each character is looked up in this string
-and the contents used instead.  If the string is of length `n',
-character codes `N' and up are untranslated.  If you are running Emacs
-under X, you should do the translations with the `xmodmap' program
-instead.
+     C-x C-d /u2/emacs/etc <RET>

 
 

-\1f
-File: xemacs.info,  Node: Representing Keystrokes,  Next: Key Sequences,  Prev: Intro to Keystrokes,  Up: Keystrokes
+lists all the files in directory `/u2/emacs/etc'.  An example of
+specifying a file name pattern is:

 
 

-Representing Keystrokes
------------------------
+     C-x C-d /u2/emacs/src/*.c <RET>

 
 

-   XEmacs represents keystrokes as lists. Each list consists of an
-arbitrary combination of modifiers followed by a single keysym at the
-end of the list.  If the keysym corresponds to an ASCII character, you
-can use its character code.  (A keystroke may also be represented by an
-event object, as returned by the `read-key-sequence' function;
-non-programmers need not worry about this.)
+   Normally, `C-x C-d' prints a brief directory listing containing just
+file names.  A numeric argument (regardless of value) tells it to print
+a verbose listing (like `ls -l').

 
 

-   The following table gives some examples of how to list
-representations for keystrokes.  Each list consists of sets of
-modifiers followed by keysyms:
+   Emacs obtains the text of a directory listing by running `ls' in an
+inferior process.  Two Emacs variables control the switches passed to
+`ls': `list-directory-brief-switches' is a string giving the switches
+to use in brief listings (`"-CF"' by default).
+`list-directory-verbose-switches' is a string giving the switches to
+use in a verbose listing (`"-l"' by default).

 
 

-`(control a)'
-     Pressing <CTRL> and `a' simultaneously.
+   The variable `directory-abbrev-alist' is an alist of abbreviations
+for file directories.  The list consists of elements of the form `(FROM
+.  TO)', each meaning to replace `FROM' with `TO' when it appears in a
+directory name.  This replacement is done when setting up the default
+directory of a newly visited file.  Every `FROM' string should start
+with ``^''.

 
 

-`(control ?a)'
-     Another way of writing the keystroke `C-a'.
+   Use this feature when you have directories which you normally refer
+to via absolute symbolic links.  Make `TO' the name of the link, and
+`FROM' the name it is linked to.

 
 

-`(control 65)'
-     Yet another way of writing the keystroke `C-a'.
+\1f
+File: xemacs.info,  Node: Comparing Files,  Next: Dired,  Prev: ListDir,  Up: Files

 
 

-`(break)'
-     Pressing the <BREAK> key.
+Comparing Files
+===============

 
 

-`(control meta button2up)'
-     Release the middle mouse button, while pressing <CTRL> and <META>.
- Note: As you define keystrokes, you can use the `shift' key only as a
-modifier with characters that do not have a second keysym on the same
-key, such as `backspace' and `tab'.  It is an error to define a
-keystroke using the <shift> modifier with keysyms such as `a' and `='.
-The correct forms are `A' and `+'.
+The command `M-x diff' compares two files, displaying the differences
+in an Emacs buffer named `*Diff*'.  It works by running the `diff'
+program, using options taken from the variable `diff-switches', whose
+value should be a string.
+
+   The buffer `*Diff*' has Compilation mode as its major mode, so you
+can use `C-x `' to visit successive changed locations in the two source
+files.  You can also move to a particular hunk of changes and type `C-c
+C-c' to find the corresponding source location.  You can also use the
+other special commands of Compilation mode: <SPC> and <DEL> for
+scrolling, and `M-p' and `M-n' for cursor motion.  *Note Compilation::.
+
+   The command `M-x diff-backup' compares a specified file with its most
+recent backup.  If you specify the name of a backup file, `diff-backup'
+compares it with the source file that it is a backup of.
+
+   The command `M-x compare-windows' compares the text in the current
+window with that in the next window.  Comparison starts at point in each
+window.  Point moves forward in each window, a character at a time in
+each window, until the next characters in the two windows are
+different.  Then the command is finished.  For more information about
+windows in Emacs, *Note Windows::.
+
+   With a numeric argument, `compare-windows' ignores changes in
+whitespace.  If the variable `compare-ignore-case' is non-`nil', it
+ignores differences in case as well.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Key Sequences,  Next: String Key Sequences,  Prev: Representing Keystrokes,  Up: Keystrokes
+File: xemacs.info,  Node: Dired,  Next: Misc File Ops,  Prev: Comparing Files,  Up: Files

 
 

-Representing Key Sequences
---------------------------
+Dired, the Directory Editor
+===========================
+
+Dired makes it easy to delete or visit many of the files in a single
+directory at once.  It creates an Emacs buffer containing a listing of
+the directory.  You can use the normal Emacs commands to move around in
+this buffer and special Dired commands to operate on the files.
+
+* Menu:
+
+* Enter: Dired Enter.         How to invoke Dired.
+* Edit: Dired Edit.           Editing the Dired buffer.
+* Deletion: Dired Deletion.   Deleting files with Dired.
+* Immed: Dired Immed.         Other file operations through Dired.
+
+\1f
+File: xemacs.info,  Node: Dired Enter,  Next: Dired Edit,  Prev: Dired,  Up: Dired

 
 

-   A "complete key sequence" is a sequence of keystrokes that Emacs
-understands as a unit.  Key sequences are significant because you can
-bind them to commands.  Note that not all sequences of keystrokes are
-possible key sequences.  In particular, the initial keystrokes in a key
-sequence must make up a "prefix key sequence".
+Entering Dired
+--------------

 
 

-   Emacs represents a key sequence as a vector of keystrokes.  Thus, the
-schematic representation of a complete key sequence is as follows:
+To invoke dired, type `C-x d' or `M-x dired'.  The command reads a
+directory name or wildcard file name pattern as a minibuffer argument
+just like the `list-directory' command, `C-x C-d'.  Where `dired'
+differs from `list-directory' is in naming the buffer after the
+directory name or the wildcard pattern used for the listing, and putting
+the buffer into Dired mode so that the special commands of Dired are
+available in it.  The variable `dired-listing-switches' is a string
+used as an argument to `ls' in making the directory; this string must
+contain `-l'.

 
 

-       [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
+   To display the Dired buffer in another window rather than in the
+selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x
+d'.

 
 

-   Here are some examples of complete key sequences:
+\1f
+File: xemacs.info,  Node: Dired Edit,  Next: Dired Deletion,  Prev: Dired Enter,  Up: Dired
+
+Editing in Dired
+----------------
+
+Once the Dired buffer exists, you can switch freely between it and other
+Emacs buffers.  Whenever the Dired buffer is selected, certain special
+commands are provided that operate on files that are listed.  The Dired
+buffer is "read-only", and inserting text in it is not useful, so
+ordinary printing characters such as `d' and `x' are used for Dired
+commands.  Most Dired commands operate on the file described by the line
+that point is on.  Some commands perform operations immediately; others
+"flag" a file to be operated on later.
+
+   Most Dired commands that operate on the current line's file also
+treat a numeric argument as a repeat count, meaning to act on the files
+of the next few lines.  A negative argument means to operate on the
+files of the preceding lines, and leave point on the first of those
+lines.
+
+   All the usual Emacs cursor motion commands are available in Dired
+buffers.  Some special purpose commands are also provided.  The keys
+`C-n' and `C-p' are redefined so that they try to position the cursor
+at the beginning of the filename on the line, rather than at the
+beginning of the line.
+
+   For extra convenience, <SPC> and `n' in Dired are equivalent to
+`C-n'.  `p' is equivalent to `C-p'.  Moving by lines is done so often
+in Dired that it deserves to be easy to type.  <DEL> (move up and
+unflag) is often useful simply for moving up.
+
+   The `g' command in Dired runs `revert-buffer' to reinitialize the
+buffer from the actual disk directory and show any changes made in the
+directory by programs other than Dired.  All deletion flags in the Dired
+buffer are lost when this is done.

 
 

-`[(control c) (control a)]'
-     Typing `C-c' followed by `C-a'
+\1f
+File: xemacs.info,  Node: Dired Deletion,  Next: Dired Immed,  Prev: Dired Edit,  Up: Dired
+
+Deleting Files With Dired
+-------------------------
+
+The primary use of Dired is to flag files for deletion and then delete
+them.
+
+`d'
+     Flag this file for deletion.
+
+`u'
+     Remove deletion-flag on this line.
+
+`<DEL>'
+     Remove deletion-flag on previous line, moving point to that line.
+
+`x'
+     Delete the files that are flagged for deletion.
+
+`#'
+     Flag all auto-save files (files whose names start and end with `#')
+     for deletion (*note Auto Save::).
+
+`~'
+     Flag all backup files (files whose names end with `~') for deletion
+     (*note Backup::).
+
+`. (Period)'
+     Flag excess numeric backup files for deletion.  The oldest and
+     newest few backup files of any one file are exempt; the middle
+     ones are flagged.
+
+   You can flag a file for deletion by moving to the line describing the
+file and typing `d' or `C-d'.  The deletion flag is visible as a `D' at
+the beginning of the line.  Point is moved to the beginning of the next
+line, so that repeated `d' commands flag successive files.
+
+   The files are flagged for deletion rather than deleted immediately to
+avoid the danger of deleting a file accidentally.  Until you direct
+Dired to delete the flagged files, you can remove deletion flags using
+the commands `u' and <DEL>.  `u' works just like `d', but removes flags
+rather than making flags.  <DEL> moves upward, removing flags; it is
+like `u' with numeric argument automatically negated.
+
+   To delete the flagged files, type `x'.  This command first displays a
+list of all the file names flagged for deletion, and requests
+confirmation with `yes'.  Once you confirm, all the flagged files are
+deleted, and their lines are deleted from the text of the Dired buffer.
+The shortened Dired buffer remains selected.  If you answer `no' or
+quit with `C-g', you return immediately to Dired, with the deletion
+flags still present and no files actually deleted.
+
+   The `#', `~', and `.' commands flag many files for deletion, based
+on their names.  These commands are useful precisely because they do
+not actually delete any files; you can remove the deletion flags from
+any flagged files that you really wish to keep.
+
+   `#' flags for deletion all files that appear to have been made by
+auto-saving (that is, files whose names begin and end with `#').  `~'
+flags for deletion all files that appear to have been made as backups
+for files that were edited (that is, files whose names end with `~').
+
+   `.' (Period) flags just some of the backup files for deletion: only
+numeric backups that are not among the oldest few nor the newest few
+backups of any one file.  Normally `dired-kept-versions' (not
+`kept-new-versions'; that applies only when saving) specifies the
+number of newest versions of each file to keep, and `kept-old-versions'
+specifies the number of oldest versions to keep.  Period with a
+positive numeric argument, as in `C-u 3 .', specifies the number of
+newest versions to keep, overriding `dired-kept-versions'.  A negative
+numeric argument overrides `kept-old-versions', using minus the value
+of the argument to specify the number of oldest versions of each file
+to keep.

 
 

-`[(control c) (control 65)]'
-     Typing `C-c' followed by `C-a'. (Using the ASCII code for the
-     character `a')
+\1f
+File: xemacs.info,  Node: Dired Immed,  Prev: Dired Deletion,  Up: Dired

 
 

-`[(control c) (break)]'
-     Typing `C-c' followed by the `break' character.
+Immediate File Operations in Dired
+----------------------------------

 
 

-   A "prefix key sequence" is the beginning of a series of longer
-sequences that are valid key sequences; adding any single keystroke to
-the end of a prefix results in a valid key sequence.  For example,
-`control-x' is standardly defined as a prefix.  Thus there is a
-two-character key sequence starting with `C-x' for each valid
-keystroke, giving numerous possibilities.  Here are some samples:
+Some file operations in Dired take place immediately when they are
+requested.

 
 

-   * `[(control x) (c)]'
+`C'
+     Copies the file described on the current line.  You must supply a
+     file name to copy to, using the minibuffer.

 
 

-   * `[(control x) (control c)]'
+`f'
+     Visits the file described on the current line.  It is just like
+     typing `C-x C-f' and supplying that file name.  If the file on
+     this line is a subdirectory, `f' actually causes Dired to be
+     invoked on that subdirectory.  *Note Visiting::.

 
 

-   Adding one character to a prefix key does not have to form a complete
-key.  It could make another, longer prefix.  For example, `[(control x)
-(\4)]' is itself a prefix that leads to any number of different
-three-character keys, including `[(control x) (\4) (f)]', `[(control x)
-(\4) (b)]' and so on.  It would be possible to define one of those
-three-character sequences as a prefix, creating a series of
-four-character keys, but we did not define any of them this way.
+`o'
+     Like `f', but uses another window to display the file's buffer.
+     The Dired buffer remains visible in the first window.  This is
+     like using `C-x 4 C-f' to visit the file.  *Note Windows::.

 
 

-   By contrast, the two-character sequence `[(control f) (control k)]'
-is not a key, because the `(control f)' is a complete key sequence in
-itself.  You cannot give `[(control f (control k)]' an independent
-meaning as a command while `(control f)' is a complete sequence,
-because Emacs would understand <C-f C-k> as two commands.
+`R'
+     Renames the file described on the current line.  You must supply a
+     file name to rename to, using the minibuffer.

 
 

-   The predefined prefix key sequences in Emacs are `(control c)',
-`(control x)', `(control h)', `[(control x) (\4)]', and `escape'.  You
-can customize Emacs and could make new prefix keys or eliminate the
-default key sequences.  *Note Key Bindings::.  For example, if you
-redefine `(control f)' as a prefix, `[(control f) (control k)]'
-automatically becomes a valid key sequence (complete, unless you define
-it as a prefix as well).  Conversely, if you remove the prefix
-definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
-`[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
+`v'
+     Views the file described on this line using `M-x view-file'.
+     Viewing a file is like visiting it, but is slanted toward moving
+     around in the file conveniently and does not allow changing the
+     file.  *Note View File: Misc File Ops.  Viewing a file that is a
+     directory runs Dired on that directory.

 
 

-   Note that the above paragraphs uses \4 instead of simply 4, because
-\4 is the symbol whose name is "4", and plain 4 is the integer 4, which
-would have been interpreted as the ASCII value.  Another way of
-representing the symbol whose name is "4" is to write ?4, which would be
-interpreted as the number 52, which is the ASCII code for the character
-"4".  We could therefore actually have written 52 directly, but that is
-far less clear.
+\1f
+File: xemacs.info,  Node: Misc File Ops,  Prev: Dired,  Up: Files
+
+Miscellaneous File Operations
+=============================
+
+Emacs has commands for performing many other operations on files.  All
+operate on one file; they do not accept wildcard file names.
+
+   You can use the command `M-x add-name-to-file' to add a name to an
+existing file without removing the old name.  The new name must belong
+on the file system that the file is on.
+
+   `M-x append-to-file' adds the text of the region to the end of the
+specified file.
+
+   `M-x copy-file' reads the file OLD and writes a new file named NEW
+with the same contents.  Confirmation is required if a file named NEW
+already exists, because copying overwrites the old contents of the file
+NEW.
+
+   `M-x delete-file' deletes a specified file, like the `rm' command in
+the shell.  If you are deleting many files in one directory, it may be
+more convenient to use Dired (*note Dired::).
+
+   `M-x insert-file' inserts a copy of the contents of a specified file
+into the current buffer at point, leaving point unchanged before the
+contents and the mark after them.  *Note Mark::.
+
+   `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and
+then creates a symbolic link named LINKNAME and pointing at OLD.
+Future attempts to open file LINKNAME will then refer to the file named
+OLD at the time the opening is done, or will result in an error if the
+name OLD is not in use at that time.  Confirmation is required if you
+create the link while LINKNAME is in use.  Note that not all systems
+support symbolic links.
+
+   `M-x rename-file' reads two file names OLD and NEW using the
+minibuffer, then renames file OLD as NEW.  If a file named NEW already
+exists, you must confirm with `yes' or renaming is not done; this is
+because renaming causes the previous meaning of the name NEW to be
+lost.  If OLD and NEW are on different file systems, the file OLD is
+copied and deleted.
+
+   `M-x view-file' allows you to scan or read a file by sequential
+screenfuls.  It reads a file name argument using the minibuffer.  After
+reading the file into an Emacs buffer, `view-file' reads and displays
+one windowful.  You can then type <SPC> to scroll forward one window,
+or <DEL> to scroll backward.  Various other commands are provided for
+moving around in the file, but none for changing it; type `C-h' while
+viewing a file for a list of them.  Most commands are the default Emacs
+cursor motion commands.  To exit from viewing, type `C-c'.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: String Key Sequences,  Next: Meta Key,  Prev: Key Sequences,  Up: Keystrokes
+File: xemacs.info,  Node: Buffers,  Next: Windows,  Prev: Files,  Up: Top
+
+Using Multiple Buffers
+**********************
+
+Text you are editing in Emacs resides in an object called a "buffer".
+Each time you visit a file, Emacs creates a buffer to hold the file's
+text.  Each time you invoke Dired, Emacs creates a buffer to hold the
+directory listing.  If you send a message with `C-x m', a buffer named
+`*mail*' is used to hold the text of the message.  When you ask for a
+command's documentation, it appears in a buffer called `*Help*'.
+
+   At any time, one and only one buffer is "selected".  It is also
+called the "current buffer".  Saying a command operates on "the buffer"
+really means that the command operates on the selected buffer, as most
+commands do.
+
+   When Emacs creates multiple windows, each window has a chosen buffer
+which is displayed there, but at any time only one of the windows is
+selected and its chosen buffer is the selected buffer.  Each window's
+mode line displays the name of the buffer the window is displaying
+(*note Windows::).
+
+   Each buffer has a name which can be of any length but is
+case-sensitive.  You can select a buffer using its name.  Most buffers
+are created when you visit files; their names are derived from the
+files' names.  You can also create an empty buffer with any name you
+want.  A newly started Emacs has a buffer named `*scratch*' which you
+can use for evaluating Lisp expressions in Emacs.
+
+   Each buffer records what file it is visiting, whether it is
+modified, and what major mode and minor modes are in effect in it
+(*note Major Modes::).  Any Emacs variable can be made "local to" a
+particular buffer, meaning its value in that buffer can be different
+from the value in other buffers.  *Note Locals::.

 
 

-String Key Sequences
---------------------
+* Menu:
+
+* Select Buffer::   Creating a new buffer or reselecting an old one.
+* List Buffers::    Getting a list of buffers that exist.
+* Misc Buffer::     Renaming; changing read-onliness; copying text.
+* Kill Buffer::     Killing buffers you no longer need.
+* Several Buffers:: How to go through the list of all buffers
+                     and operate variously on several of them.
+
+\1f
+File: xemacs.info,  Node: Select Buffer,  Next: List Buffers,  Prev: Buffers,  Up: Buffers
+
+Creating and Selecting Buffers
+==============================
+
+`C-x b BUFFER <RET>'
+     Select or create a buffer named BUFFER (`switch-to-buffer').
+
+`C-x 4 b BUFFER <RET>'
+     Similar, but select a buffer named BUFFER in another window
+     (`switch-to-buffer-other-window').
+
+`M-x switch-to-other-buffer N'
+     Switch to the previous buffer.
+
+   To select a buffer named BUFNAME, type `C-x b BUFNAME <RET>'.  This
+is the command `switch-to-buffer' with argument BUFNAME.  You can use
+completion on an abbreviation for the buffer name you want (*note
+Completion::).  An empty argument to `C-x b' specifies the most
+recently selected buffer that is not displayed in any window.
+
+   Most buffers are created when you visit files, or use Emacs commands
+that display text.  You can also create a buffer explicitly by typing
+`C-x b BUFNAME <RET>', which creates a new, empty buffer that is not
+visiting any file, and selects it for editing.  The new buffer's major
+mode is determined by the value of `default-major-mode' (*note Major
+Modes::).  Buffers not visiting files are usually used for making notes
+to yourself.  If you try to save one, you are asked for the file name
+to use.

 
 

-   For backward compatibility, you may also represent a key sequence
-using strings.  For example, we have the following equivalent
-representations:
+   The function `switch-to-buffer-other-frame' is similar to
+`switch-to-buffer' except that it creates a new frame in which to
+display the selected buffer.

 
 

-`"\C-c\C-c"'
-     `[(control c) (control c)]'
+   Use `M-x switch-to-other-buffer' to visit the previous buffer. If
+you supply a positive integer N, the Nth most recent buffer is
+displayed. If you supply an argument of 0, the current buffer is moved
+to the bottom of the buffer stack.

 
 

-`"\e\C-c"'
-     `[(meta control c)]'
+   Note that you can also use `C-x C-f' and any other command for
+visiting a file to switch buffers.  *Note Visiting::.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Meta Key,  Next: Super and Hyper Keys,  Prev: String Key Sequences,  Up: Keystrokes
+File: xemacs.info,  Node: List Buffers,  Next: Misc Buffer,  Prev: Select Buffer,  Up: Buffers
+
+Listing Existing Buffers
+========================
+
+`C-x C-b'
+     List the existing buffers (`list-buffers').
+
+   To print a list of all existing buffers, type `C-x C-b'.  Each line
+in the list shows one buffer's name, major mode, and visited file.  A
+`*' at the beginning of a line indicates the buffer has been
+"modified".  If several buffers are modified, it may be time to save
+some with `C-x s' (*note Saving::).  A `%' indicates a read-only
+buffer.  A `.' marks the selected buffer.  Here is an example of a
+buffer list:
+
+      MR Buffer         Size  Mode           File
+      -- ------         ----  ----           ----
+     .*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
+         *Help*         1287  Fundamental
+         files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
+       % RMAIL          64042 RMAIL          /u/rms/RMAIL
+      *% man            747   Dired          /u2/emacs/man/
+         net.emacs      343885 Fundamental   /u/rms/net.emacs
+         fileio.c       27691 C              /u2/emacs/src/fileio.c
+         NEWS           67340 Text           /u2/emacs/etc/NEWS
+         *scratch*      0     Lisp Interaction
+
+Note that the buffer `*Help*' was made by a help request; it is not
+visiting any file.  The buffer `man' was made by Dired on the directory
+`/u2/emacs/man/'.
+
+   As you move the mouse over the `*Buffer List*' buffer, the lines are
+highlighted.  This visual cue indicates that clicking the right mouse
+button (`button3') will pop up a menu of commands on the buffer
+represented by this line.  This menu duplicates most of those commands
+which are bound to keys in the `*Buffer List*' buffer.

 
 

-Assignment of the <META> Key
-----------------------------
+\1f
+File: xemacs.info,  Node: Misc Buffer,  Next: Kill Buffer,  Prev: List Buffers,  Up: Buffers
+
+Miscellaneous Buffer Operations
+===============================
+
+`C-x C-q'
+     Toggle read-only status of buffer (`toggle-read-only').

 
 

-   Not all terminals have the complete set of modifiers.  Terminals
-that have a <Meta> key allow you to type Meta characters by just
-holding that key down.  To type `Meta-a', hold down <META> and press
-`a'.  On those terminals, the <META> key works like the <SHIFT> key.
-Such a key is not always labeled <META>, however, as this function is
-often a special option for a key with some other primary purpose.
+`M-x rename-buffer'
+     Change the name of the current buffer.

 
 

-   If there is no <META> key, you can still type Meta characters using
-two-character sequences starting with <ESC>.  To enter `M-a', you could
-type `<ESC> a'.  To enter `C-M-a', you would type `ESC C-a'.  <ESC> is
-allowed on terminals with Meta keys, too, in case you have formed a
-habit of using it.
+`M-x view-buffer'
+     Scroll through a buffer.

 
 

-   If you are running under X and do not have a <META> key, it is
-possible to reconfigure some other key to be a <META> key.  *Note Super
-and Hyper Keys::.
+   A buffer can be "read-only", which means that commands to change its
+text are not allowed.  Normally, read-only buffers are created by
+subsystems such as Dired and Rmail that have special commands to operate
+on the text.  Emacs also creates a read-only buffer if you visit a file
+that is protected.  To make changes in a read-only buffer, use the
+command `C-x C-q' (`toggle-read-only').  It makes a read-only buffer
+writable, and makes a writable buffer read-only.  This works by setting
+the variable `buffer-read-only', which has a local value in each buffer
+and makes a buffer read-only if its value is non-`nil'.

 
 

-   Emacs believes the terminal has a <META> key if the variable
-`meta-flag' is non-`nil'.  Normally this is set automatically according
-to the termcap entry for your terminal type.  However, sometimes the
-termcap entry is wrong, and then it is useful to set this variable
-yourself.  *Note Variables::, for how to do this.
+   `M-x rename-buffer' changes the name of the current buffer,
+prompting for the new name in the minibuffer.  There is no default.  If
+you specify a name that is used by a different buffer, an error is
+signalled and renaming is not done.

 
 

-   Note: If you are running under the X window system, the setting of
-the `meta-flag' variable is irrelevant.
+   `M-x view-buffer' is similar to `M-x view-file' (*note Misc File
+Ops::), but it examines an already existing Emacs buffer.  View mode
+provides convenient commands for scrolling through the buffer but not
+for changing it.  When you exit View mode, the resulting value of point
+remains in effect.
+
+   To copy text from one buffer to another, use the commands `M-x
+append-to-buffer' and `M-x insert-buffer'.  *Note Accumulating Text::.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Super and Hyper Keys,  Next: Character Representation,  Prev: Meta Key,  Up: Keystrokes
+File: xemacs.info,  Node: Kill Buffer,  Next: Several Buffers,  Prev: Misc Buffer,  Up: Buffers

 
 

-Assignment of the <SUPER> and <HYPER> Keys
-------------------------------------------
+Killing Buffers
+===============
+
+After using Emacs for a while, you may accumulate a large number of
+buffers and may want to eliminate the ones you no longer need.  There
+are several commands for doing this.

 
 

-   Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
-keys.  Under X, you can simulate the <SUPER> or <HYPER> key if you want
-to bind keys to sequences using `super' and `hyper'.  You can use the
-`xmodmap' program to do this.
-
-   For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
-following:
-
-   Create a file called `~/.xmodmap'.  In this file, place the lines
-
-             remove Lock = Caps_Lock
-             keysym Caps_Lock = Super_L
-             add Mod2 = Super_L
-
-   The first line says that the key that is currently called `Caps_Lock'
-should no longer behave as a "lock" key.  The second line says that
-this should now be called `Super_L' instead.  The third line says that
-the key called `Super_L' should be a modifier key, which produces the
-`Mod2' modifier.
-
-   To create a <META> or <HYPER> key instead of a <SUPER> key, replace
-the word `Super' above with `Meta' or `Hyper'.
-
-   Just after you start up X, execute the command `xmodmap /.xmodmap'.
-You can add this command to the appropriate initialization file to have
-the command executed automatically.
-
-   If you have problems, see the documentation for the `xmodmap'
-program.  The X keyboard model is quite complicated, and explaining it
-is beyond the scope of this manual.  However, we reprint the following
-description from the X Protocol document for your convenience:
-
-   A list of keysyms is associated with each keycode. If that list
-(ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
-list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
-the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
-`K1 K2', then the list is treated as if it were the list ```K1 K2 K1
-K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
-of keysyms `K1 K2 K3', then the list is treated as if it were the list
-```K1 K2 K3 NoSymbol'''.
-
-   The first four elements of the list are split into two groups of
-keysyms. Group 1 contains the first and second keysyms; Group 2 contains
-third and fourth keysyms. Within each group, if the second element of
-the group is NoSymbol, then the group should be treated as if the second
-element were the same as the first element, except when the first
-element is an alphabetic keysym `K' for which both lowercase and
-uppercase forms are defined. In that case, the group should be treated
-as if the first element were the lowercase form of `K' and the second
-element were the uppercase form of `K'.
-
-   The standard rules for obtaining a keysym from a KeyPress event make
-use of only the Group 1 and Group 2 keysyms; no interpretation of other
-keysyms in the list is given here. (That is, the last four keysyms are
-unused.)
-
-   Which group to use is determined by modifier state. Switching between
-groups is controlled by the keysym named `Mode_switch'. Attach that
-keysym to some keycode and attach that keycode to any one of the
-modifiers Mod1 through Mod5. This modifier is called the "group
-modifier". For any keycode, Group 1 is used when the group modifier is
-off, and Group 2 is used when the group modifier is on.
-
-   Within a group, which keysym to use is also determined by modifier
-state. The first keysym is used when the `Shift' and `Lock' modifiers
-are off. The second keysym is used when the `Shift' modifier is on, or
-when the `Lock' modifier is on and the second keysym is uppercase
-alphabetic, or when the `Lock' modifier is on and is interpreted as
-`ShiftLock'. Otherwise, when the `Lock' modifier is on and is
-interpreted as `CapsLock', the state of the `Shift' modifier is applied
-first to select a keysym, but if that keysym is lower-case alphabetic,
-then the corresponding upper-case keysym is used instead.
-
-   In addition to the above information on keysyms, we also provide the
-following description of modifier mapping from the InterClient
-Communications Conventions Manual:
-
-   X11 supports 8 modifier bits, of which 3 are pre-assigned to
-`Shift', `Lock', and `Control'. Each modifier bit is controlled by the
-state of a set of keys, and these sets are specified in a table
-accessed by `GetModifierMapping()' and `SetModifierMapping()'.
-
-   A client needing to use one of the pre-assigned modifiers should
-assume that the modifier table has been set up correctly to control
-these modifiers. The `Lock' modifier should be interpreted as `Caps
-Lock' or `Shift Lock' according to whether the keycodes in its
-controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
-
-   Clients should determine the meaning of a modifier bit from the
-keysyms being used to control it.
-
-   A client needing to use an extra modifier, for example `Meta',
-should:
-
-  1. Scan the existing modifier mappings.
-
-       1. If it finds a modifier that contains a keycode whose set of
-          keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
-          that modifier bit.
-
-       2. If there is no existing modifier controlled by `XK_Meta_L' or
-          `XK_Meta_R', it should select an unused modifier bit (one with
-          an empty controlling set) and:
-
-  2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
-     that keycode to the set for the chosen modifier, and then:
-
-       1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
-          add that keycode to the set for the chosen modifier, and then:
-
-       2. If the controlling set is still empty, interact with the user
-          to select one or more keys to be `Meta'.
-
-  3. If there are no unused modifier bits, ask the user to take
-     corrective action.
-
-   This means that the `Mod1' modifier does not necessarily mean
-`Meta', although some applications (such as twm and emacs 18) assume
-that. Any of the five unassigned modifier bits could mean `Meta'; what
-matters is that a modifier bit is generated by a keycode which is bound
-to the keysym `Meta_L' or `Meta_R'.
-
-   Therefore, if you want to make a <META> key, the right way is to
-make the keycode in question generate both a `Meta' keysym and some
-previously-unassigned modifier bit.
-
-\1f
-File: xemacs.info,  Node: Character Representation,  Next: Commands,  Prev: Super and Hyper Keys,  Up: Keystrokes
-
-Representation of Characters
+`C-x k'
+     Kill a buffer, specified by name (`kill-buffer').
+
+`M-x kill-some-buffers'
+     Offer to kill each buffer, one by one.
+
+   `C-x k' (`kill-buffer') kills one buffer, whose name you specify in
+the minibuffer.  If you type just <RET> in the minibuffer, the default,
+killing the current buffer, is used.  If the current buffer is killed,
+the buffer that has been selected recently but does not appear in any
+window now is selected.  If the buffer being killed contains unsaved
+changes, you are asked to confirm with `yes' before the buffer is
+killed.
+
+   The command `M-x kill-some-buffers' asks about each buffer, one by
+one.  An answer of `y' means to kill the buffer.  Killing the current
+buffer or a buffer containing unsaved changes selects a new buffer or
+asks for confirmation just like `kill-buffer'.
+
+\1f
+File: xemacs.info,  Node: Several Buffers,  Prev: Kill Buffer,  Up: Buffers
+
+Operating on Several Buffers

 ============================
 
 ============================
 

-   This section briefly discusses how characters are represented in
-Emacs buffers.  *Note Key Sequences::, for information on representing
-key sequences to create key bindings.
+The "buffer-menu" facility is like a "Dired for buffers"; it allows you
+to request operations on various Emacs buffers by editing a buffer
+containing a list of them.  You can save buffers, kill them (here
+called "deleting" them, for consistency with Dired), or display them.
+
+`M-x buffer-menu'
+     Begin editing a buffer listing all Emacs buffers.
+
+   The command `buffer-menu' writes a list of all Emacs buffers into
+the buffer `*Buffer List*', and selects that buffer in Buffer Menu
+mode.  The buffer is read-only.  You can only change it using the
+special commands described in this section.  Most of the commands are
+graphic characters.  You can use  Emacs cursor motion commands in the
+`*Buffer List*' buffer.  If the cursor is on a line describing a
+buffer, the following  special commands apply to that buffer:
+
+`d'
+     Request to delete (kill) the buffer, then move down.  A `D' before
+     the buffer name on a line indicates a deletion request.  Requested
+     deletions actually take place when you use the `x' command.
+
+`k'
+     Synonym for `d'.
+
+`C-d'
+     Like `d' but move up afterwards instead of down.
+
+`s'
+     Request to save the buffer.  An `S' before the buffer name on a
+     line indicates the request.  Requested saves actually take place
+     when you use the `x' command.  You can request both saving and
+     deletion for the same buffer.
+
+`~'
+     Mark buffer "unmodified".  The command `~' does this immediately
+     when typed.
+
+`x'
+     Perform previously requested deletions and saves.
+
+`u'
+     Remove any request made for the current line, and move down.
+
+`<DEL>'
+     Move to previous line and remove any request made for that line.
+
+   All commands that add or remove flags to request later operations
+also move down a line.  They accept a numeric argument as a repeat
+count, unless otherwise specified.
+
+   There are also special commands to use the buffer list to select
+another buffer, and to specify one or more other buffers for display in
+additional windows.
+
+`1'
+     Select the buffer in a full-frame window.  This command takes
+     effect immediately.
+
+`2'
+     Immediately set up two windows, with this buffer in one and the
+     buffer selected before `*Buffer List*' in the other.
+
+`f'
+     Immediately select the buffer in place of the `*Buffer List*'
+     buffer.
+
+`o'
+     Immediately select the buffer in another window as if by `C-x 4 b',
+     leaving `*Buffer List*' visible.
+
+`q'
+     Immediately select this buffer, and display any buffers previously
+     flagged with the `m' command in other windows.  If there are no
+     buffers flagged with `m', this command is equivalent to `1'.
+
+`m'
+     Flag this buffer to be displayed in another window if the `q'
+     command is used.  The request shows as a `>' at the beginning of
+     the line.  The same buffer may not have both a delete request and a
+     display request.
+
+   Going back between a `buffer-menu' buffer and other Emacs buffers is
+easy.  You can, for example, switch from the `*Buffer List*' buffer to
+another Emacs buffer, and edit there.  You can then reselect the
+`buffer-menu' buffer and perform operations already requested, or you
+can kill that buffer or pay no further attention to it.   All that
+`buffer-menu' does directly is create and select a suitable buffer, and
+turn on Buffer Menu mode.  All the other capabilities of the buffer
+menu are implemented by special commands provided in Buffer Menu mode.
+
+   The only difference between `buffer-menu' and `list-buffers' is that
+`buffer-menu' selects the `*Buffer List*' buffer and `list-buffers'
+does not.  If you run `list-buffers' (that is, type `C-x C-b') and
+select the buffer list manually, you can use all the commands described
+here.
+
+\1f
+File: xemacs.info,  Node: Windows,  Next: Mule,  Prev: Buffers,  Up: Top
+
+Multiple Windows
+****************
+
+Emacs can split the frame into two or many windows, which can display
+parts of different buffers or different parts of one buffer.  If you are
+running XEmacs under X, that means you can have the X window that
+contains the Emacs frame have multiple subwindows.
+
+* Menu:

 
 

-   ASCII graphic characters in Emacs buffers are displayed with their
-graphics.  <LFD> is the same as a newline character; it is displayed by
-starting a new line.  <TAB> is displayed by moving to the next tab stop
-column (usually every 8 spaces).  Other control characters are
-displayed as a caret (`^') followed by the non-control version of the
-character; thus, `C-a' is displayed as `^A'.  Non-ASCII characters 128
-and up are displayed with octal escape sequences; thus, character code
-243 (octal), also called `M-#' when used as an input character, is
-displayed as `\243'.
+* Basic Window::     Introduction to Emacs windows.
+* Split Window::     New windows are made by splitting existing windows.
+* Other Window::     Moving to another window or doing something to it.
+* Pop Up Window::    Finding a file or buffer in another window.
+* Change Window::    Deleting windows and changing their sizes.

 
 

-   The variable `ctl-arrow' may be used to alter this behavior.  *Note
-Display Vars::.
+\1f
+File: xemacs.info,  Node: Basic Window,  Next: Split Window,  Prev: Windows,  Up: Windows
+
+Concepts of Emacs Windows
+=========================
+
+When Emacs displays multiple windows, each window has one Emacs buffer
+designated for display.  The same buffer may appear in more than one
+window; if it does, any changes in its text are displayed in all the
+windows that display it.  Windows showing the same buffer can show
+different parts of it, because each window has its own value of point.
+
+   At any time, one  window is the "selected window"; the buffer
+displayed by that window is the current buffer.  The cursor shows the
+location of point in that window.  Each other window has a location of
+point as well, but since the terminal has only one cursor, it cannot
+show the location of point in the other windows.
+
+   Commands to move point affect the value of point for the selected
+Emacs window only.  They do not change the value of point in any other
+Emacs window, including those showing the same buffer.  The same is
+true for commands such as `C-x b' to change the selected buffer in the
+selected window; they do not affect other windows at all.  However,
+there are other commands such as `C-x 4 b' that select a different
+window and switch buffers in it.  Also, all commands that display
+information in a window, including (for example) `C-h f'
+(`describe-function') and `C-x C-b' (`list-buffers'), work by switching
+buffers in a non-selected window without affecting the selected window.
+
+   Each window has its own mode line, which displays the buffer name,
+modification status, and major and minor modes of the buffer that is
+displayed in the window.  *Note Mode Line::, for details on the mode
+line.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Commands,  Prev: Character Representation,  Up: Keystrokes
+File: xemacs.info,  Node: Split Window,  Next: Other Window,  Prev: Basic Window,  Up: Windows

 
 

-Keys and Commands
+Splitting Windows

 =================
 
 =================
 

-   This manual is full of passages that tell you what particular keys
-do.  But Emacs does not assign meanings to keys directly.  Instead,
-Emacs assigns meanings to "functions", and then gives keys their
-meanings by "binding" them to functions.
-
-   A function is a Lisp object that can be executed as a program.
-Usually it is a Lisp symbol that has been given a function definition;
-every symbol has a name, usually made of a few English words separated
-by dashes, such as `next-line' or `forward-word'.  It also has a
-"definition", which is a Lisp program.  Only some functions can be the
-bindings of keys; these are functions whose definitions use
-`interactive' to specify how to call them interactively.  Such
-functions are called "commands", and their names are "command names".
-More information on this subject will appear in the XEmacs Lisp
-Reference Manual.
-
-   The bindings between keys and functions are recorded in various
-tables called "keymaps".  *Note Key Bindings::, for more information on
-key sequences you can bind commands to.  *Note Keymaps::, for
-information on creating keymaps.
-
-   When we say  "`C-n' moves down vertically one line" we are glossing
-over a distinction that is irrelevant in ordinary use but is vital in
-understanding how to customize Emacs.  The function `next-line' is
-programmed to move down vertically.  `C-n' has this effect because it
-is bound to that function.  If you rebind `C-n' to the function
-`forward-word' then `C-n' will move forward by words instead.
-Rebinding keys is a common method of customization.
-
-   The rest of this manual usually ignores this subtlety to keep things
-simple.  To give the customizer the information needed, we often state
-the name of the command that really does the work in parentheses after
-mentioning the key that runs it.  For example, we will say that "The
-command `C-n' (`next-line') moves point vertically down," meaning that
-`next-line' is a command that moves vertically down and `C-n' is a key
-that is standardly bound to it.
-
-   While we are on the subject of information for customization only,
-it's a good time to tell you about "variables".  Often the description
-of a command will say, "To change this, set the variable `mumble-foo'."
-A variable is a name used to remember a value.  Most of the variables
-documented in this manual exist just to facilitate customization: some
-command or other part of Emacs uses the variable and behaves
-differently depending on its setting.  Until you are interested in
-customizing, you can ignore the information about variables.  When you
-are ready to be interested, read the basic information on variables, and
-then the information on individual variables will make sense.  *Note
-Variables::.
-
-\1f
-File: xemacs.info,  Node: Pull-down Menus,  Next: Entering Emacs,  Prev: Keystrokes,  Up: Top
-
-XEmacs Pull-down Menus
-======================
+`C-x 2'
+     Split the selected window into two windows, one above the other
+     (`split-window-vertically').
+
+`C-x 3'
+     Split the selected window into two windows positioned side by side
+     (`split-window-horizontally').
+
+`C-x 6'
+     Save the current window configuration in register REG (a letter).
+
+`C-x 7'
+     Restore (make current) the window configuration in register REG (a
+     letter).  Use with a register previously set with `C-x 6'.
+
+   The command `C-x 2' (`split-window-vertically') breaks the selected
+window into two windows, one above the other.  Both windows start out
+displaying the same buffer, with the same value of point.  By default
+each of the two windows gets half the height of the window that was
+split.  A numeric argument specifies how many lines to give to the top
+window.
+
+   `C-x 3' (`split-window-horizontally') breaks the selected window
+into two side-by-side windows.  A numeric argument specifies how many
+columns to give the one on the left.  A line of vertical bars separates
+the two windows.  Windows that are not the full width of the frame have
+truncated mode lines which do not always appear in inverse video,
+because Emacs display routines cannot display a region of inverse video
+that is only part of a line on the screen.
+
+   When a window is less than the full width, many text lines are too
+long to fit.  Continuing all those lines might be confusing.  Set the
+variable `truncate-partial-width-windows' to non-`nil' to force
+truncation in all windows less than the full width of the frame,
+independent of the buffer and its value for `truncate-lines'.  *Note
+Continuation Lines::.
+
+   Horizontal scrolling is often used in side-by-side windows.  *Note
+Display::.
+
+   You can resize a window and store that configuration in a register by
+supplying a REGISTER argument to `window-configuration-to-register'
+(`C-x 6'). To return to the window configuration established with
+`window-configuration-to-register', use `jump-to-register' (`C-x j').
+
+\1f
+File: xemacs.info,  Node: Other Window,  Next: Pop Up Window,  Prev: Split Window,  Up: Windows
+
+Using Other Windows
+===================
+
+`C-x o'
+     Select another window (`other-window').  That is the letter `o',
+     not zero.
+
+`M-C-v'
+     Scroll the next window (`scroll-other-window').
+
+`M-x compare-windows'
+     Find the next place where the text in the selected window does not
+     match the text in the next window.
+
+`M-x other-window-any-frame N'
+     Select the Nth different window on any frame.
+
+   To select a different window, use `C-x o' (`other-window').  That is
+an `o', for `other', not a zero.  When there are more than two windows,
+the command moves through all the windows in a cyclic order, generally
+top to bottom and left to right.  From the rightmost and bottommost
+window, it goes back to the one at the upper left corner.  A numeric
+argument, N, moves several steps in the cyclic order of windows. A
+negative numeric argument moves around the cycle in the opposite order.
+If the optional second argument WHICH-FRAMES is non-`nil', the
+function cycles through all frames.  When the minibuffer is active, the
+minibuffer is the last window in the cycle; you can switch from the
+minibuffer window to one of the other windows, and later switch back
+and finish supplying the minibuffer argument that is requested.  *Note
+Minibuffer Edit::.
+
+   The command `M-x other-window-any-frame' also selects the window N
+steps away in the cyclic order.  However, unlike `other-window', this
+command selects a window on the next or previous frame instead of
+wrapping around to the top or bottom of the current frame, when there
+are no more windows.
+
+   The usual scrolling commands (*note Display::) apply to the selected
+window only.  `M-C-v' (`scroll-other-window') scrolls the window that
+`C-x o' would select.  Like `C-v', it takes positive and negative
+arguments.
+
+   The command `M-x compare-windows' compares the text in the current
+window with the text in the next window.  Comparison starts at point in
+each window.  Point moves forward in each window, a character at a time,
+until the next set of characters in the two windows are different.
+Then the command is finished.
+
+   A prefix argument IGNORE-WHITESPACE means ignore changes in
+whitespace.  The variable `compare-windows-whitespace' controls how
+whitespace is skipped.
+
+   If `compare-ignore-case' is non-`nil', changes in case are also
+ignored.

 
 

-   If you are running XEmacs under X, a menu bar on top of the Emacs
-frame provides access to pull-down menus of file, edit, and
-help-related commands. The menus provide convenient shortcuts and an
-easy interface for novice users.  They do not provide additions to the
-functionality available via key commands; you can still invoke commands
-from the keyboard as in previous versions of Emacs.
+\1f
+File: xemacs.info,  Node: Pop Up Window,  Next: Change Window,  Prev: Other Window,  Up: Windows

 
 

-File
-     Perform file and buffer-related operations, such as opening and
-     closing files, saving and printing buffers, as well as exiting
-     Emacs.
+Displaying in Another Window
+============================

 
 

-Edit
-     Perform standard editing operations, such as cutting, copying,
-     pasting, and killing selected text.
+`C-x 4' is a prefix key for commands that select another window
+(splitting the window if there is only one) and select a buffer in that
+window.  Different `C-x 4' commands have different ways of finding the
+buffer to select.

 
 

-Apps
-     Access to sub-applications implemented within XEmacs, such as the
-     mail reader, the World Wide Web browser, the spell-checker, and
-     the calendar program.
+`C-x 4 b BUFNAME <RET>'
+     Select buffer BUFNAME in another window.  This runs
+     `switch-to-buffer-other-window'.

 
 

-Options
-     Control various options regarding the way XEmacs works, such as
-     controlling which elements of the frame are visible, selecting the
-     fonts to be used for text, specifying whether searches are
-     case-sensitive, etc.
+`C-x 4 f FILENAME <RET>'
+     Visit file FILENAME and select its buffer in another window.  This
+     runs `find-file-other-window'.  *Note Visiting::.

 
 

-Buffers
-     Present a menu of buffers for selection as well as the option to
-     display a buffer list.
+`C-x 4 d DIRECTORY <RET>'
+     Select a Dired buffer for directory DIRECTORY in another window.
+     This runs `dired-other-window'.  *Note Dired::.

 
 

-Tools
-     Perform various actions designed to automate software development
-     and similar technical work, such as searching through many files,
-     compiling a program, and comparing or merging two or three files.
+`C-x 4 m'
+     Start composing a mail message in another window.  This runs
+     `mail-other-window', and its same-window version is `C-x m' (*note
+     Sending Mail::).

 
 

-Help
-     Access to Emacs Info.
+`C-x 4 .'
+     Find a tag in the current tag table in another window.  This runs
+     `find-tag-other-window', the multiple-window variant of `M-.'
+     (*note Tags::).

 
 

-   There are two ways of selecting an item from a pull-down menu:
+   If the variable `display-buffer-function' is non-`nil', its value is
+the function to call to handle `display-buffer'. It receives two
+arguments, the buffer and a flag that if non-`nil' means that the
+currently selected window is not acceptable. Commands such as
+`switch-to-buffer-other-window' and `find-file-other-window' work using
+this function.

 
 

-   * Select an item in the menu bar by moving the cursor over it and
-     click the left mouse-button.  Then move the cursor over the menu
-     item you want to choose and click left again.
+\1f
+File: xemacs.info,  Node: Change Window,  Prev: Pop Up Window,  Up: Windows
+
+Deleting and Rearranging Windows
+================================
+
+`C-x 0'
+     Get rid of the selected window (`delete-window').  That is a zero.
+     If there is more than one Emacs frame, deleting the sole remaining
+     window on that frame deletes the frame as well. If the current
+     frame is the only frame, it is not deleted.
+
+`C-x 1'
+     Get rid of all windows except the selected one
+     (`delete-other-windows').
+
+`C-x ^'
+     Make the selected window taller, at the expense of the other(s)
+     (`enlarge-window').
+
+`C-x }'
+     Make the selected window wider (`enlarge-window-horizontally').
+
+   To delete a window, type `C-x 0' (`delete-window').  (That is a
+zero.)  The space occupied by the deleted window is distributed among
+the other active windows (but not the minibuffer window, even if that
+is active at the time).  Once a window is deleted, its attributes are
+forgotten; there is no automatic way to make another window of the same
+shape or showing the same buffer.  The buffer continues to exist, and
+you can select it in any window with `C-x b'.
+
+   `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it
+deletes all the windows except the selected one (and the minibuffer).
+The selected window expands to use the whole frame except for the echo
+area.
+
+   To readjust the division of space among existing windows, use `C-x
+^' (`enlarge-window').  It makes the currently selected window longer
+by one line or as many lines as a numeric argument specifies.  With a
+negative argument, it makes the selected window smaller.  `C-x }'
+(`enlarge-window-horizontally') makes the selected window wider by the
+specified number of columns.  The extra screen space given to a window
+comes from one of its neighbors, if that is possible; otherwise, all
+the competing windows are shrunk in the same proportion.  If this makes
+some windows too small, those windows are deleted and their space is
+divided up.   Minimum window size is specified by the variables
+`window-min-height' and `window-min-width'.
+
+   You can also resize windows within a frame by clicking the left mouse
+button on a modeline, and dragging.
+
+   Clicking the right button on a mode line pops up a menu of common
+window manager operations.  This menu contains the following options:
+
+Delete Window
+     Remove the window above this modeline from the frame.
+
+Delete Other Windows
+     Delete all windows on the frame except for the one above this
+     modeline.
+
+Split Window
+     Split the window above the mode line in half, creating another
+     window.
+
+Split Window Horizontally
+     Split the window above the mode line in half horizontally, so that
+     there will be two windows side-by-side.
+
+Balance Windows
+     Readjust the sizes of all windows on the frame until all windows
+     have roughly the same number of lines.

 
 

-   * Select an item in the menu bar by moving the cursor over it and
-     click and hold the left mouse-button.  With the mouse-button
-     depressed, move the cursor over the menu item you want, then
-     release it to make your selection.
+\1f
+File: xemacs.info,  Node: Mule,  Next: Major Modes,  Prev: Windows,  Up: Top

 
 

-   If a command in the pull-down menu is not applicable in a given
-situation, the command is disabled and its name appears faded.  You
-cannot invoke items that are faded.  For example, many commands on the
-Edit menu appear faded until you select text on which they are to
-operate; after you select a block of text, edit commands are enabled.
-*Note Mouse Selection::, for information on using the mouse to select
-text.  *Note Using X Selections::, for related information.
+World Scripts Support
+*********************

 
 

-   There are also `M-x' equivalents for each menu item.  To find the
-equivalent for any left-button menu item, do the following:
+If you compile XEmacs with Mule option, it supports a wide variety of
+world scripts, including Latin script, as well as Arabic script,
+Simplified Chinese script (for mainland of China), Traditional Chinese
+script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA
+symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts
+(Hangul and Hanja) and Cyrillic script (for Byelorussian, Bulgarian,
+Russian, Serbian and Ukrainian).  These features have been merged from
+the modified version of Emacs known as MULE (for "MULti-lingual
+Enhancement to GNU Emacs").

 
 

-  1. Type `C-h k' to get the `Describe Key' prompt.
+* Menu:

 
 

-  2. Select the menu item and click.
+* Mule Intro::              Basic concepts of Mule.
+* Language Environments::   Setting things up for the language you use.
+* Input Methods::           Entering text characters not on your keyboard.
+* Select Input Method::     Specifying your choice of input methods.
+* Mule and Fonts::          Additional font-related issues
+* Coding Systems::          Character set conversion when you read and
+                              write files, and so on.
+* Recognize Coding::        How XEmacs figures out which conversion to use.
+* Specify Coding::          Various ways to choose which conversion to use.

 
 

-   Emacs displays the function associated with the menu item in a
-separate window, usually together with some documentation.
+\1f
+File: xemacs.info,  Node: Mule Intro,  Next: Language Environments,  Prev: Mule,  Up: Mule

 
 

-* Menu:
+What is Mule?
+=============

 
 

-* File Menu::           Items on the File menu.
-* Edit Menu::           Items on the Edit menu.
-* Apps Menu::          Items on the Apps menu.
-* Options Menu::        Items on the Options menu.
-* Buffers Menu::        Information about the Buffers menu.
-* Tools Menu::         Items on the Tools menu.
-* Help Menu::           Items on the Help menu.
-* Menu Customization::  Adding and removing menu items and related
-                        operations.
+Mule is the MUltiLingual Extension to XEmacs.  It provides facilities
+not only for handling text written in many different languages, but in
+fact multilingual texts containing several languages in the same buffer.
+This goes beyond the simple facilities offered by Unicode for
+representation of multilingual text.  Mule also supports input methods,
+composing display using fonts in various different encodings, changing
+character syntax and other editing facilities to correspond to local
+language usage, and more.
+
+   The most obvious problem is that of the different character coding
+systems used by different languages.  ASCII supplies all the characters
+needed for most computer programming languages and US English (it lacks
+the currency symbol for British English), but other Western European
+languages (French, Spanish, German) require more than 96 code positions
+for accented characters.  In fact, even with 8 bits to represent 96 more
+character (including accented characters and symbols such as currency
+symbols), some languages' alphabets remain incomplete (Croatian,
+Polish).  (The 64 "missing characters" are reserved for control
+characters.)  Furthermore, many European languages have their own
+alphabets, which must conflict with the accented characters since the
+ASCII characters are needed for computer interaction (error and log
+messages are typically in ASCII).
+
+   For economy of space, historical practice has been for each language
+to establish its own encoding for the characters it needs.  This allows
+most European languages to represented with one octet (byte) per
+character.  However, many Asian languages have thousands of characters
+and require two or more octets per character.  For multilingual
+purposes, the ISO 2022 standard establishes escape codes that allow
+switching encodings in midstream.  (It's also ISO 2022 that establishes
+the standard that code points 0-31 and 128-159 are control codes.)
+
+   However, this is error-prone and complex for internal processing.
+For this reason XEmacs uses an internal coding system which can encode
+all of the world's scripts.  Unfortunately, for historical reasons, this
+code is not Unicode, although we are moving in that direction.
+
+   XEmacs translates between the internal character encoding and various
+other coding systems when reading and writing files, when exchanging
+data with subprocesses, and (in some cases) in the `C-q' command (see
+below).  The internal encoding is never visible to the user in a
+production XEmacs, but unfortunately the process cannot be completely
+transparent to the user.  This is because the same ranges of octets may
+represent 1-octet ISO-8859-1 (which is satisfactory for most Western
+European use prior to the introduction of the Euro currency), 1-octet
+ISO-8859-15 (which substitutes the Euro for the rarely used "generic
+currency" symbol), 1-octet ISO-8859-5 (Cyrillic), or multioctet EUC-JP
+(Japanese).  There's no way to tell without being able to read!
+
+   A number of heuristics are incorporated in Mule for automatic
+recognition, there are facilities for the user to set defaults, and
+where necessary (rarely, we hope) to set coding systems directly.
+
+   The command `C-h h' (`view-hello-file') displays the file
+`etc/HELLO', which shows how to say "hello" in many languages.  This
+illustrates various scripts.
+
+   Keyboards, even in the countries where these character sets are used,
+generally don't have keys for all the characters in them.  So XEmacs
+supports various "input methods", typically one for each script or
+language, to make it convenient to type them.
+
+   The prefix key `C-x <RET>' is used for commands that pertain to
+world scripts, coding systems, and input methods.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: File Menu,  Next: Edit Menu,  Up: Pull-down Menus
+File: xemacs.info,  Node: Language Environments,  Next: Input Methods,  Prev: Mule Intro,  Up: Mule
+
+Language Environments
+=====================
+
+All supported character sets are supported in XEmacs buffers if it is
+compiled with Mule; there is no need to select a particular language in
+order to display its characters in an XEmacs buffer.  However, it is
+important to select a "language environment" in order to set various
+defaults.  The language environment really represents a choice of
+preferred script (more or less) rather that a choice of language.
+
+   The language environment controls which coding systems to recognize
+when reading text (*note Recognize Coding::).  This applies to files,
+incoming mail, netnews, and any other text you read into XEmacs.  It may
+also specify the default coding system to use when you create a file.
+Each language environment also specifies a default input method.
+
+   The command to select a language environment is `M-x
+set-language-environment'.  It makes no difference which buffer is
+current when you use this command, because the effects apply globally to
+the XEmacs session.  The supported language environments include:
+
+     ASCII, Chinese-BIG5, Chinese-GB, Croatian, Cyrillic-ALT,
+     Cyrillic-ISO, Cyrillic-KOI8, Cyrillic-Win, Czech, English,
+     Ethiopic, French, German, Greek, Hebrew, IPA, Japanese, Korean,
+     Latin-1, Latin-2, Latin-3, Latin-4, Latin-5, Norwegian, Polish,
+     Romanian, Slovenian, Thai-XTIS, Vietnamese.
+
+   Some operating systems let you specify the language you are using by
+setting locale environment variables.  XEmacs handles one common special
+case of this: if your locale name for character types contains the
+string `8859-N', XEmacs automatically selects the corresponding
+language environment.
+
+   To display information about the effects of a certain language
+environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
+(`describe-language-environment').  This tells you which languages this
+language environment is useful for, and lists the character sets,
+coding systems, and input methods that go with it.  It also shows some
+sample text to illustrate scripts used in this language environment.
+By default, this command describes the chosen language environment.

 
 

-The File Menu
--------------
+\1f
+File: xemacs.info,  Node: Input Methods,  Next: Select Input Method,  Prev: Language Environments,  Up: Mule

 
 

-   The File menu bar item contains the items New Frame, Open File...,
-Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
-Frame, Kill Buffer and Exit Emacs on the pull-down menu.  If you select
-a menu item, Emacs executes the equivalent command.
-
-Open File, New Frame...
-     Prompts you for a filename and loads that file into a new buffer
-     in a new Emacs frame, that is, a new X window running under the
-     same Emacs process.  You can remove the frame using the Delete
-     Frame menu item.  When you remove the last frame, you exit Emacs
-     and are prompted for confirmation.
-
-Open File...
-     Prompts you for a filename and loads that file into a new buffer.
-     Open File... is equivalent to the Emacs command `find-file' (`C-x
-     C-f').
-
-Insert File...
-     Prompts you for a filename and inserts the contents of that file
-     into the current buffer.  The file associated with the current
-     buffer is not changed by this command.  This is equivalent to the
-     Emacs command `insert-file' (`C-x i').
-
-Save Buffer
-     Writes and saves the current Emacs buffer as the latest version of
-     the current visited file.  Save Buffer is equivalent to the Emacs
-     command `save-buffer' (`C-x C-s').
-
-Save Buffer As...
-     Writes and saves the current Emacs buffer to the filename you
-     specify.  Save Buffer As... is equivalent to the Emacs command
-     `write-file' (`C-x C-w').
-
-Revert Buffer
-     Restores the last saved version of the file to the current buffer.
-     When you edit a buffer containing a text file, you must save the
-     buffer before your changes become effective.  Use Revert Buffer if
-     you do not want to keep the changes you have made in the buffer.
-     Revert Buffer is equivalent to the Emacs command `revert-file'
-     (`M-x revert-buffer').
-
-Kill Buffer
-     Kills the current buffer, prompting you first if there are unsaved
-     changes.  This is roughly equivalent to the Emacs command
-     `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
-     name of a buffer to kill.
-
-Print Buffer
-     Prints a hardcopy of the current buffer.  Equivalent to the Emacs
-     command `print-buffer' (`M-x print-buffer').
-
-New Frame
-     Creates a new Emacs frame displaying the `*scratch*' buffer.  This
-     is like the Open File, New Frame... menu item, except that it does
-     not prompt for or load a file.
-
-Delete Frame
-     Allows you to close all but one of the frames created by New Frame.
-     If you created several Emacs frames belonging to the same Emacs
-     process, you can close all but one of them.  When you attempt to
-     close the last frame, Emacs informs you that you are attempting to
-     delete the last frame.  You have to choose Exit Emacs for that.
-
-Split Frame
-     Divides the current window on the current frame into two
-     equal-sized windows, both displaying the same buffer.  Equivalent
-     to the Emacs command `split-window-vertically' (`C-x 2').
-
-Un-split (Keep This)
-     If the frame is divided into multiple windows, this removes all
-     windows other than the selected one.  Equivalent to the Emacs
-     command `delete-other-windows' (`C-x 1').
-
-Un-split (Keep Others)
-     If the frame is divided into multiple windows, this removes the
-     selected window from the frame, giving the space back to one of the
-     other windows.  Equivalent to the Emacs command `delete-window'
-     (`C-x 0').
-
-Exit Emacs
-     Shuts down (kills) the Emacs process.  Equivalent to the Emacs
-     command `save-buffers-kill-emacs' (`C-x C-c').  Before killing the
-     Emacs process, the system asks which unsaved buffers to save by
-     going through the list of all buffers in that Emacs process.
-
-\1f
-File: xemacs.info,  Node: Edit Menu,  Next: Apps Menu,  Prev: File Menu,  Up: Pull-down Menus
-
-The Edit Menu
--------------
+Input Methods
+=============

 
 

-   The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
-Clear menu items.  When you select a menu item, Emacs executes the
-equivalent command.  Most commands on the Edit menu work on a block of
-text, the X selection.  They appear faded until you select a block of
-text (activate a region) with the mouse.  *Note Using X Selections::,
-*note Killing::, and *note Yanking:: for more information.
-
-Undo
-     Undoes the previous command.  Undo is equivalent to the Emacs
-     command `undo' (`C-x u').
-
-Cut
-     Removes the selected text block from the current buffer, makes it
-     the X clipboard selection, and places it in the kill ring.  Before
-     executing this command, you have to select a region using Emacs
-     region selection commands or with the mouse.
-
-Copy
-     Makes a selected text block the X clipboard selection, and places
-     it in the kill ring.  You can select text using one of the Emacs
-     region selection commands or by selecting a text region with the
-     mouse.
-
-Paste
-     Inserts the current value of the X clipboard selection in the
-     current buffer.  Note that this is not necessarily the same as the
-     Emacs `yank' command, because the Emacs kill ring and the X
-     clipboard selection are not the same thing.  You can paste in text
-     you have placed in the clipboard using Copy or Cut.  You can also
-     use Paste to insert text that was pasted into the clipboard from
-     other applications.
-
-Clear
-     Removes the selected text block from the current buffer but does
-     not place it in the kill ring or the X clipboard selection.
-
-Start Macro Recording
-     After selecting this, Emacs will remember every keystroke you type
-     until End Macro Recording is selected.  This is the same as the
-     Emacs command `start-kbd-macro' (`C-x (').
-
-End Macro Recording
-     Selecting this tells emacs to stop remembering your keystrokes.
-     This is the same as the Emacs command `end-kbd-macro' (`C-x )').
-
-Execute Last Macro
-     Selecting this item will cause emacs to re-interpret all of the
-     keystrokes which were saved between selections of the Start Macro
-     Recording and End Macro Recording menu items.  This is the same as
-     the Emacs command `call-last-kbd-macro' (`C-x e').
-
-\1f
-File: xemacs.info,  Node: Apps Menu,  Next: Options Menu,  Prev: Edit Menu,  Up: Pull-down Menus
-
-The Apps Menu
--------------
+An "input method" is a kind of character conversion designed
+specifically for interactive input.  In XEmacs, typically each language
+has its own input method; sometimes several languages which use the same
+characters can share one input method.  A few languages support several
+input methods.
+
+   The simplest kind of input method works by mapping ASCII letters into
+another alphabet.  This is how the Greek and Russian input methods work.
+
+   A more powerful technique is composition: converting sequences of
+characters into one letter.  Many European input methods use composition
+to produce a single non-ASCII letter from a sequence that consists of a
+letter followed by accent characters.  For example, some methods convert
+the sequence `'a' into a single accented letter.
+
+   The input methods for syllabic scripts typically use mapping followed
+by composition.  The input methods for Thai and Korean work this way.
+First, letters are mapped into symbols for particular sounds or tone
+marks; then, sequences of these which make up a whole syllable are
+mapped into one syllable sign.
+
+   Chinese and Japanese require more complex methods.  In Chinese input
+methods, first you enter the phonetic spelling of a Chinese word (in
+input method `chinese-py', among others), or a sequence of portions of
+the character (input methods `chinese-4corner' and `chinese-sw', and
+others).  Since one phonetic spelling typically corresponds to many
+different Chinese characters, you must select one of the alternatives
+using special XEmacs commands.  Keys such as `C-f', `C-b', `C-n',
+`C-p', and digits have special definitions in this situation, used for
+selecting among the alternatives.  <TAB> displays a buffer showing all
+the possibilities.
+
+   In Japanese input methods, first you input a whole word using
+phonetic spelling; then, after the word is in the buffer, XEmacs
+converts it into one or more characters using a large dictionary.  One
+phonetic spelling corresponds to many differently written Japanese
+words, so you must select one of them; use `C-n' and `C-p' to cycle
+through the alternatives.
+
+   Sometimes it is useful to cut off input method processing so that the
+characters you have just entered will not combine with subsequent
+characters.  For example, in input method `latin-1-postfix', the
+sequence `e '' combines to form an `e' with an accent.  What if you
+want to enter them as separate characters?
+
+   One way is to type the accent twice; that is a special feature for
+entering the separate letter and accent.  For example, `e ' '' gives
+you the two characters `e''.  Another way is to type another letter
+after the `e'--something that won't combine with that--and immediately
+delete it.  For example, you could type `e e <DEL> '' to get separate
+`e' and `''.
+
+   Another method, more general but not quite as easy to type, is to use
+`C-\ C-\' between two characters to stop them from combining.  This is
+the command `C-\' (`toggle-input-method') used twice.  *Note Select
+Input Method::.
+
+   `C-\ C-\' is especially useful inside an incremental search, because
+stops waiting for more characters to combine, and starts searching for
+what you have already entered.
+
+   The variables `input-method-highlight-flag' and
+`input-method-verbose-flag' control how input methods explain what is
+happening.  If `input-method-highlight-flag' is non-`nil', the partial
+sequence is highlighted in the buffer.  If `input-method-verbose-flag'
+is non-`nil', the list of possible characters to type next is displayed
+in the echo area (but not when you are in the minibuffer).
+
+\1f
+File: xemacs.info,  Node: Select Input Method,  Next: Mule and Fonts,  Prev: Input Methods,  Up: Mule
+
+Selecting an Input Method
+=========================
+
+`C-\'
+     Enable or disable use of the selected input method.
+
+`C-x <RET> C-\ METHOD <RET>'
+     Select a new input method for the current buffer.
+
+`C-h I METHOD <RET>'
+`C-h C-\ METHOD <RET>'
+     Describe the input method METHOD (`describe-input-method').  By
+     default, it describes the current input method (if any).
+
+`M-x list-input-methods'
+     Display a list of all the supported input methods.
+
+   To choose an input method for the current buffer, use `C-x <RET>
+C-\' (`select-input-method').  This command reads the input method name
+with the minibuffer; the name normally starts with the language
+environment that it is meant to be used with.  The variable
+`current-input-method' records which input method is selected.
+
+   Input methods use various sequences of ASCII characters to stand for
+non-ASCII characters.  Sometimes it is useful to turn off the input
+method temporarily.  To do this, type `C-\' (`toggle-input-method').
+To reenable the input method, type `C-\' again.
+
+   If you type `C-\' and you have not yet selected an input method, it
+prompts for you to specify one.  This has the same effect as using `C-x
+<RET> C-\' to specify an input method.
+
+   Selecting a language environment specifies a default input method for
+use in various buffers.  When you have a default input method, you can
+select it in the current buffer by typing `C-\'.  The variable
+`default-input-method' specifies the default input method (`nil' means
+there is none).
+
+   Some input methods for alphabetic scripts work by (in effect)
+remapping the keyboard to emulate various keyboard layouts commonly used
+for those scripts.  How to do this remapping properly depends on your
+actual keyboard layout.  To specify which layout your keyboard has, use
+the command `M-x quail-set-keyboard-layout'.
+
+   To display a list of all the supported input methods, type `M-x
+list-input-methods'.  The list gives information about each input
+method, including the string that stands for it in the mode line.
+
+\1f
+File: xemacs.info,  Node: Mule and Fonts,  Next: Coding Systems,  Prev: Select Input Method,  Up: Mule
+
+Mule and Fonts
+==============
+
+(This section is X11-specific.)
+
+   Text in XEmacs buffers is displayed using various faces.  In
+addition to specifying properties of a face, such as font and color,
+there are some additional properties of Mule charsets that are used in
+text.
+
+   There is currently two properties of a charset that could be
+adjusted by user: font registry and so called "ccl-program".
+
+   Font registry is a regular expression matching the font registry
+field for this character set.  For example, both the `ascii' and
+`latin-iso8859-1' charsets use the registry `"ISO8859-1"'.  This field
+is used to choose an appropriate font when the user gives a general
+font specification such as `-*-courier-medium-r-*-140-*', i.e. a
+14-point upright medium-weight Courier font.
+
+   You can set font registry for a charset using `set-charset-registry'
+function in one of your startup files.  This function takes two
+arguments: character set (as a symbol) and font registry (as a string).
+
+   E. g., for Cyrillic texts Mule uses `cyrillic-iso8859-5' charset
+with `"ISO8859-5"' as a default registry, and we want to use `"koi8-r"'
+instead, because fonts in that encoding are installed on our system.
+Use:
+
+     (set-charset-registry 'cyrillic-iso8859-5 "koi8-r")
+
+   (Please note that you probably also want to set font registry for
+`ascii' charset so that mixed English/Cyrillic texts be displayed using
+the same font.)
+
+   "CCL-programs" are a little special-purpose scripts defined within
+XEmacs or in some package.  Those scripts allow XEmacs to use fonts that
+are in different encoding from the encoding that is used by Mule for
+text in buffer.  Returning to the above example, we need to somehow tell
+XEmacs that we have different encodings of fonts and text and so it
+needs to convert characters between those encodings when displaying.
+That's what `set-charset-ccl-program' function is used for.  There are
+quite a few various CCL programs defined within XEmacs, and there is no
+comprehensive list of them, so you currently have to consult sources.
+
+   We know that there is a CCL program called `ccl-encode-koi8-r-font'
+that is used exactly for needed purpose: to convert characters between
+`ISO8859-5' encoding and `koi8-r'.  Use:
+
+     (set-charset-ccl-program 'cyrillic-iso8859-5 'ccl-encode-koi8-r-font)
+
+   There are several more uses for CCL programs, not related to fonts,
+but those uses are not described here.
+
+\1f
+File: xemacs.info,  Node: Coding Systems,  Next: Recognize Coding,  Prev: Mule and Fonts,  Up: Mule
+
+Coding Systems
+==============
+
+Users of various languages have established many more-or-less standard
+coding systems for representing them.  XEmacs does not use these coding
+systems internally; instead, it converts from various coding systems to
+its own system when reading data, and converts the internal coding
+system to other coding systems when writing data.  Conversion is
+possible in reading or writing files, in sending or receiving from the
+terminal, and in exchanging data with subprocesses.
+
+   XEmacs assigns a name to each coding system.  Most coding systems are
+used for one language, and the name of the coding system starts with the
+language name.  Some coding systems are used for several languages;
+their names usually start with `iso'.  There are also special coding
+systems `binary' and `no-conversion' which do not convert printing
+characters at all.
+
+   In addition to converting various representations of non-ASCII
+characters, a coding system can perform end-of-line conversion.  XEmacs
+handles three different conventions for how to separate lines in a file:
+newline, carriage-return linefeed, and just carriage-return.
+
+`C-h C CODING <RET>'
+     Describe coding system CODING.
+
+`C-h C <RET>'
+     Describe the coding systems currently in use.
+
+`M-x list-coding-systems'
+     Display a list of all the supported coding systems.
+
+`C-u M-x list-coding-systems'
+     Display comprehensive list of specific details of all supported
+     coding systems.
+
+   The command `C-x RET C' (`describe-coding-system') displays
+information about particular coding systems.  You can specify a coding
+system name as argument; alternatively, with an empty argument, it
+describes the coding systems currently selected for various purposes,
+both in the current buffer and as the defaults, and the priority list
+for recognizing coding systems (*note Recognize Coding::).
+
+   To display a list of all the supported coding systems, type `M-x
+list-coding-systems'.  The list gives information about each coding
+system, including the letter that stands for it in the mode line (*note
+Mode Line::).
+
+   Each of the coding systems that appear in this list--except for
+`binary', which means no conversion of any kind--specifies how and
+whether to convert printing characters, but leaves the choice of
+end-of-line conversion to be decided based on the contents of each file.
+For example, if the file appears to use carriage-return linefeed between
+lines, that end-of-line conversion will be used.
+
+   Each of the listed coding systems has three variants which specify
+exactly what to do for end-of-line conversion:
+
+`...-unix'
+     Don't do any end-of-line conversion; assume the file uses newline
+     to separate lines.  (This is the convention normally used on Unix
+     and GNU systems.)
+
+`...-dos'
+     Assume the file uses carriage-return linefeed to separate lines,
+     and do the appropriate conversion.  (This is the convention
+     normally used on Microsoft systems.)
+
+`...-mac'
+     Assume the file uses carriage-return to separate lines, and do the
+     appropriate conversion.  (This is the convention normally used on
+     the Macintosh system.)
+
+   These variant coding systems are omitted from the
+`list-coding-systems' display for brevity, since they are entirely
+predictable.  For example, the coding system `iso-8859-1' has variants
+`iso-8859-1-unix', `iso-8859-1-dos' and `iso-8859-1-mac'.
+
+   In contrast, the coding system `binary' specifies no character code
+conversion at all--none for non-Latin-1 byte values and none for end of
+line.  This is useful for reading or writing binary files, tar files,
+and other files that must be examined verbatim.
+
+   The easiest way to edit a file with no conversion of any kind is with
+the `M-x find-file-literally' command.  This uses `binary', and also
+suppresses other XEmacs features that might convert the file contents
+before you see them.  *Note Visiting::.
+
+   The coding system `no-conversion' means that the file contains
+non-Latin-1 characters stored with the internal XEmacs encoding.  It
+handles end-of-line conversion based on the data encountered, and has
+the usual three variants to specify the kind of end-of-line conversion.
+
+\1f
+File: xemacs.info,  Node: Recognize Coding,  Next: Specify Coding,  Prev: Coding Systems,  Up: Mule
+
+Recognizing Coding Systems
+==========================
+
+Most of the time, XEmacs can recognize which coding system to use for
+any given file-once you have specified your preferences.
+
+   Some coding systems can be recognized or distinguished by which byte
+sequences appear in the data.  However, there are coding systems that
+cannot be distinguished, not even potentially.  For example, there is no
+way to distinguish between Latin-1 and Latin-2; they use the same byte
+values with different meanings.
+
+   XEmacs handles this situation by means of a priority list of coding
+systems.  Whenever XEmacs reads a file, if you do not specify the coding
+system to use, XEmacs checks the data against each coding system,
+starting with the first in priority and working down the list, until it
+finds a coding system that fits the data.  Then it converts the file
+contents assuming that they are represented in this coding system.
+
+   The priority list of coding systems depends on the selected language
+environment (*note Language Environments::).  For example, if you use
+French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you
+use Czech, you probably want Latin-2 to be preferred.  This is one of
+the reasons to specify a language environment.
+
+   However, you can alter the priority list in detail with the command
+`M-x prefer-coding-system'.  This command reads the name of a coding
+system from the minibuffer, and adds it to the front of the priority
+list, so that it is preferred to all others.  If you use this command
+several times, each use adds one element to the front of the priority
+list.
+
+   Sometimes a file name indicates which coding system to use for the
+file.  The variable `file-coding-system-alist' specifies this
+correspondence.  There is a special function
+`modify-coding-system-alist' for adding elements to this list.  For
+example, to read and write all `.txt' using the coding system
+`china-iso-8bit', you can execute this Lisp expression:
+
+     (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
+
+The first argument should be `file', the second argument should be a
+regular expression that determines which files this applies to, and the
+third argument says which coding system to use for these files.
+
+   You can specify the coding system for a particular file using the
+`-*-...-*-' construct at the beginning of a file, or a local variables
+list at the end (*note File Variables::).  You do this by defining a
+value for the "variable" named `coding'.  XEmacs does not really have a
+variable `coding'; instead of setting a variable, it uses the specified
+coding system for the file.  For example, `-*-mode: C; coding:
+iso-8859-1;-*-' specifies use of the iso-8859-1 coding system, as well
+as C mode.
+
+   Once XEmacs has chosen a coding system for a buffer, it stores that
+coding system in `buffer-file-coding-system' and uses that coding
+system, by default, for operations that write from this buffer into a
+file.  This includes the commands `save-buffer' and `write-region'.  If
+you want to write files from this buffer using a different coding
+system, you can specify a different coding system for the buffer using
+`set-buffer-file-coding-system' (*note Specify Coding::).
+
+\1f
+File: xemacs.info,  Node: Specify Coding,  Prev: Recognize Coding,  Up: Mule
+
+Specifying a Coding System
+==========================
+
+In cases where XEmacs does not automatically choose the right coding
+system, you can use these commands to specify one:
+
+`C-x <RET> f CODING <RET>'
+     Use coding system CODING for the visited file in the current
+     buffer.
+
+`C-x <RET> c CODING <RET>'
+     Specify coding system CODING for the immediately following command.
+
+`C-x <RET> k CODING <RET>'
+     Use coding system CODING for keyboard input.  (This feature is
+     non-functional and is temporarily disabled.)
+
+`C-x <RET> t CODING <RET>'
+     Use coding system CODING for terminal output.
+
+`C-x <RET> p CODING <RET>'
+     Use coding system CODING for subprocess input and output in the
+     current buffer.
+
+   The command `C-x RET f' (`set-buffer-file-coding-system') specifies
+the file coding system for the current buffer--in other words, which
+coding system to use when saving or rereading the visited file.  You
+specify which coding system using the minibuffer.  Since this command
+applies to a file you have already visited, it affects only the way the
+file is saved.
+
+   Another way to specify the coding system for a file is when you visit
+the file.  First use the command `C-x <RET> c'
+(`universal-coding-system-argument'); this command uses the minibuffer
+to read a coding system name.  After you exit the minibuffer, the
+specified coding system is used for _the immediately following command_.
+
+   So if the immediately following command is `C-x C-f', for example,
+it reads the file using that coding system (and records the coding
+system for when the file is saved).  Or if the immediately following
+command is `C-x C-w', it writes the file using that coding system.
+Other file commands affected by a specified coding system include `C-x
+C-i' and `C-x C-v', as well as the other-window variants of `C-x C-f'.
+
+   In addition, if you run some file input commands with the precedent
+`C-u', you can specify coding system to read from minibuffer.  So if
+the immediately following command is `C-x C-f', for example, it reads
+the file using that coding system (and records the coding system for
+when the file is saved).  Other file commands affected by a specified
+coding system include `C-x C-i' and `C-x C-v', as well as the
+other-window variants of `C-x C-f'.
+
+   The variable `default-buffer-file-coding-system' specifies the
+choice of coding system to use when you create a new file.  It applies
+when you find a new file, and when you create a buffer and then save it
+in a file.  Selecting a language environment typically sets this
+variable to a good choice of default coding system for that language
+environment.
+
+   The command `C-x <RET> t' (`set-terminal-coding-system') specifies
+the coding system for terminal output.  If you specify a character code
+for terminal output, all characters output to the terminal are
+translated into that coding system.
+
+   This feature is useful for certain character-only terminals built to
+support specific languages or character sets--for example, European
+terminals that support one of the ISO Latin character sets.
+
+   By default, output to the terminal is not translated at all.
+
+   The command `C-x <RET> k' (`set-keyboard-coding-system') specifies
+the coding system for keyboard input.  Character-code translation of
+keyboard input is useful for terminals with keys that send non-ASCII
+graphic characters--for example, some terminals designed for ISO
+Latin-1 or subsets of it.
+
+   By default, keyboard input is not translated at all.
+
+   There is a similarity between using a coding system translation for
+keyboard input, and using an input method: both define sequences of
+keyboard input that translate into single characters.  However, input
+methods are designed to be convenient for interactive use by humans, and
+the sequences that are translated are typically sequences of ASCII
+printing characters.  Coding systems typically translate sequences of
+non-graphic characters.
+
+   (This feature is non-functional and is temporarily disabled.)
+
+   The command `C-x <RET> p' (`set-buffer-process-coding-system')
+specifies the coding system for input and output to a subprocess.  This
+command applies to the current buffer; normally, each subprocess has its
+own buffer, and thus you can use this command to specify translation to
+and from a particular subprocess by giving the command in the
+corresponding buffer.
+
+   By default, process input and output are not translated at all.
+
+   The variable `file-name-coding-system' specifies a coding system to
+use for encoding file names.  If you set the variable to a coding
+system name (as a Lisp symbol or a string), XEmacs encodes file names
+using that coding system for all file operations.  This makes it
+possible to use non-Latin-1 characters in file names--or, at least,
+those non-Latin-1 characters which the specified coding system can
+encode.  By default, this variable is `nil', which implies that you
+cannot use non-Latin-1 characters in file names.
+
+\1f
+File: xemacs.info,  Node: Major Modes,  Next: Indentation,  Prev: Mule,  Up: Top
+
+Major Modes
+***********
+
+Emacs has many different "major modes", each of which customizes Emacs
+for editing text of a particular sort.  The major modes are mutually
+exclusive;  at any time, each buffer has one major mode.  The mode line
+normally contains the name of the current major mode in parentheses.
+*Note Mode Line::.
+
+   The least specialized major mode is called "Fundamental mode".  This
+mode has no mode-specific redefinitions or variable settings.  Each
+Emacs command behaves in its most general manner, and each option is in
+its default state.  For editing any specific type of text, such as Lisp
+code or English text, you should switch to the appropriate major mode,
+such as Lisp mode or Text mode.
+
+   Selecting a major mode changes the meanings of a few keys to become
+more specifically adapted to the language being edited.  <TAB>, <DEL>,
+and <LFD> are changed frequently.  In addition, commands which handle
+comments use the mode to determine how to delimit comments.  Many major
+modes redefine the syntactical properties of characters appearing in
+the buffer.  *Note Syntax::.
+
+   The major modes fall into three major groups.  Lisp mode (which has
+several variants), C mode, and Muddle mode are for specific programming
+languages.  Text mode, Nroff mode, TeX mode, and Outline mode are for
+editing English text.  The remaining major modes are not intended for
+use on users' files; they are used in buffers created by Emacs for
+specific purposes and include Dired mode for buffers made by Dired
+(*note Dired::), Mail mode for buffers made by `C-x m' (*note Sending
+Mail::), and Shell mode for buffers used for communicating with an
+inferior shell process (*note Interactive Shell::).
+
+   Most programming language major modes specify that only blank lines
+separate paragraphs.  This is so that the paragraph commands remain
+useful.  *Note Paragraphs::.  They also cause Auto Fill mode to use the
+definition of <TAB> to indent the new lines it creates.  This is
+because most lines in a program are usually indented.  *Note
+Indentation::.
+
+* Menu:
+
+* Choosing Modes::     How major modes are specified or chosen.

 
 

-   The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
-(MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
-Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
-When you select a menu item, Emacs executes the equivalent command.
-For some of the menu items, there are sub-menus which you will need to
-select.
+\1f
+File: xemacs.info,  Node: Choosing Modes,  Prev: Major Modes,  Up: Major Modes
+
+Choosing Major Modes
+====================
+
+You can select a major mode explicitly for the current buffer, but most
+of the time Emacs determines which mode to use based on the file name
+or some text in the file.
+
+   Use a `M-x' command to explicitly select a new major mode.  Add
+`-mode' to the name of a major mode to get the name of a command to
+select that mode.  For example, to enter Lisp mode, execute `M-x
+lisp-mode'.
+
+   When you visit a file, Emacs usually chooses the right major mode
+based on the file's name.  For example, files whose names end in `.c'
+are edited in C mode.  The variable `auto-mode-alist' controls the
+correspondence between file names and major mode.  Its value is a list
+in which each element has the form:
+
+     (REGEXP . MODE-FUNCTION)
+
+For example, one element normally found in the list has the form
+`("\\.c$" . c-mode)'. It is responsible for selecting C mode for files
+whose names end in `.c'.  (Note that `\\' is needed in Lisp syntax to
+include a `\' in the string, which is needed to suppress the special
+meaning of `.' in regexps.)  The only practical way to change this
+variable is with Lisp code.
+
+   You can specify which major mode should be used for editing a certain
+file by a special sort of text in the first non-blank line of the file.
+The mode name should appear in this line both preceded and followed by
+`-*-'.  Other text may appear on the line as well.  For example,
+
+     ;-*-Lisp-*-
+
+tells Emacs to use Lisp mode.  Note how the semicolon is used to make
+Lisp treat this line as a comment.  Such an explicit specification
+overrides any default mode based on the file name.
+
+   Another format of mode specification is:
+
+     -*-Mode: MODENAME;-*-
+
+which allows other things besides the major mode name to be specified.
+However, Emacs does not look for anything except the mode name.
+
+   The major mode can also be specified in a local variables list.
+*Note File Variables::.
+
+   When you visit a file that does not specify a major mode to use, or
+when you create a new buffer with `C-x b', Emacs uses the major mode
+specified by the variable `default-major-mode'.  Normally this value is
+the symbol `fundamental-mode', which specifies Fundamental mode.  If
+`default-major-mode' is `nil', the major mode is taken from the
+previously selected buffer.
+
+\1f
+File: xemacs.info,  Node: Indentation,  Next: Text,  Prev: Major Modes,  Up: Top
+
+Indentation
+***********
+
+`<TAB>'
+     Indent current line "appropriately" in a mode-dependent fashion.
+
+`<LFD>'
+     Perform <RET> followed by <TAB> (`newline-and-indent').
+
+`M-^'
+     Merge two lines (`delete-indentation').  This would cancel out the
+     effect of <LFD>.
+
+`C-M-o'
+     Split line at point; text on the line after point becomes a new
+     line indented to the same column that it now starts in
+     (`split-line').
+
+`M-m'
+     Move (forward or back) to the first non-blank character on the
+     current line (`back-to-indentation').
+
+`C-M-\'
+     Indent several lines to same column (`indent-region').
+
+`C-x <TAB>'
+     Shift block of lines rigidly right or left (`indent-rigidly').
+
+`M-i'
+     Indent from point to the next prespecified tab stop column
+     (`tab-to-tab-stop').
+
+`M-x indent-relative'
+     Indent from point to under an indentation point in the previous
+     line.
+
+   Most programming languages have some indentation convention.  For
+Lisp code, lines are indented according to their nesting in
+parentheses.  The same general idea is used for C code, though details
+differ.
+
+   Use the <TAB> command to indent a line whatever the language.  Each
+major mode defines this command to perform indentation appropriate for
+the particular language.  In Lisp mode, <TAB> aligns a line according
+to its depth in parentheses.  No matter where in the line you are when
+you type <TAB>, it aligns the line as a whole.  In C mode, <TAB>
+implements a subtle and sophisticated indentation style that knows
+about many aspects of C syntax.
+
+   In Text mode, <TAB> runs the command `tab-to-tab-stop', which
+indents to the next tab stop column.  You can set the tab stops with
+`M-x edit-tab-stops'.
+
+* Menu:
+
+* Indentation Commands:: Various commands and techniques for indentation.
+* Tab Stops::            You can set arbitrary "tab stops" and then
+                         indent to the next tab stop when you want to.
+* Just Spaces::          You can request indentation using just spaces.
+
+\1f
+File: xemacs.info,  Node: Indentation Commands,  Next: Tab Stops,  Prev: Indentation,  Up: Indentation
+
+Indentation Commands and Techniques
+===================================
+
+If you just want to insert a tab character in the buffer, you can type
+`C-q <TAB>'.
+
+   To move over the indentation on a line, type `Meta-m'
+(`back-to-indentation').  This command, given anywhere on a line,
+positions point at the first non-blank character on the line.
+
+   To insert an indented line before the current line, type `C-a C-o
+<TAB>'.  To make an indented line after the current line, use `C-e
+<LFD>'.
+
+   `C-M-o' (`split-line') moves the text from point to the end of the
+line vertically down, so that the current line becomes two lines.
+`C-M-o' first moves point forward over any spaces and tabs.  Then it
+inserts after point a newline and enough indentation to reach the same
+column point is on.  Point remains before the inserted newline; in this
+regard, `C-M-o' resembles `C-o'.
+
+   To join two lines cleanly, use the `Meta-^' (`delete-indentation')
+command to delete the indentation at the front of the current line, and
+the line boundary as well.  Empty spaces are replaced by a single
+space, or by no space if at the beginning of a line, before a close
+parenthesis, or after an open parenthesis.  To delete just the
+indentation of a line, go to the beginning of the line and use `Meta-\'
+(`delete-horizontal-space'), which deletes all spaces and tabs around
+the cursor.
+
+   There are also commands for changing the indentation of several
+lines at once.  `Control-Meta-\' (`indent-region') gives each line which
+begins in the region the "usual" indentation by invoking <TAB> at the
+beginning of the line.  A numeric argument specifies the column to
+indent to.  Each line is shifted left or right so that its first
+non-blank character appears in that column.  `C-x <TAB>'
+(`indent-rigidly') moves all the lines in the region right by its
+argument (left, for negative arguments).  The whole group of lines moves
+rigidly sideways, which is how the command gets its name.
+
+   `M-x indent-relative' indents at point based on the previous line
+(actually, the last non-empty line.)  It inserts whitespace at point,
+moving point, until it is underneath an indentation point in the
+previous line.  An indentation point is the end of a sequence of
+whitespace or the end of the line.  If point is farther right than any
+indentation point in the previous line, the whitespace before point is
+deleted and the first indentation point then applicable is used.  If no
+indentation point is applicable even then, `tab-to-tab-stop' is run
+(see next section).
+
+   `indent-relative' is the definition of <TAB> in Indented Text mode.
+*Note Text::.
+
+\1f
+File: xemacs.info,  Node: Tab Stops,  Next: Just Spaces,  Prev: Indentation Commands,  Up: Indentation
+
+Tab Stops
+=========
+
+For typing in tables, you can use Text mode's definition of <TAB>,
+`tab-to-tab-stop'.  This command inserts indentation before point,
+enough to reach the next tab stop column.  Even if you are not in Text
+mode, this function is associated with `M-i' anyway.
+
+   You can arbitrarily set the tab stops used by `M-i'.  They are
+stored as a list of column-numbers in increasing order in the variable
+`tab-stop-list'.
+
+   The convenient way to set the tab stops is using `M-x
+edit-tab-stops', which creates and selects a buffer containing a
+description of the tab stop settings.  You can edit this buffer to
+specify different tab stops, and then type `C-c C-c' to make those new
+tab stops take effect.  In the tab stop buffer, `C-c C-c' runs the
+function `edit-tab-stops-note-changes' rather than the default
+`save-buffer'.  `edit-tab-stops' records which buffer was current when
+you invoked it, and stores the tab stops in that buffer.  Normally all
+buffers share the same tab stops and changing them in one buffer
+affects all.  If you make `tab-stop-list' local in one buffer
+`edit-tab-stops' in that buffer edits only the local settings.
+
+   Below is the text representing ordinary tab stops every eight
+columns:
+
+             :       :       :       :       :       :
+     0         1         2         3         4
+     0123456789012345678901234567890123456789012345678
+     To install changes, type C-c C-c
+
+   The first line contains a colon at each tab stop.  The remaining
+lines help you see where the colons are and tell you what to do.
+
+   Note that the tab stops that control `tab-to-tab-stop' have nothing
+to do with displaying tab characters in the buffer.  *Note Display
+Vars::, for more information on that.
+
+\1f
+File: xemacs.info,  Node: Just Spaces,  Prev: Tab Stops,  Up: Indentation
+
+Tabs vs. Spaces
+===============
+
+Emacs normally uses both tabs and spaces to indent lines.  If you
+prefer, all indentation can be made from spaces only.  To request this,
+set `indent-tabs-mode' to `nil'.  This is a per-buffer variable;
+altering the variable affects only the current buffer, but there is a
+default value which you can change as well.  *Note Locals::.
+
+   There are also commands to convert tabs to spaces or vice versa,
+always preserving the columns of all non-blank text.  `M-x tabify'
+scans the region for sequences of spaces, and converts sequences of at
+least three spaces to tabs if that is possible without changing
+indentation.  `M-x untabify' changes all tabs in the region to
+corresponding numbers of spaces.
+
+\1f
+File: xemacs.info,  Node: Text,  Next: Programs,  Prev: Indentation,  Up: Top
+
+Commands for Human Languages
+****************************
+
+The term "text" has two widespread meanings in our area of the computer
+field.  One is data that is a sequence of characters.  In this sense of
+the word any file that you edit with Emacs is text.  The other meaning
+is more restrictive: a sequence of characters in a human language for
+humans to read (possibly after processing by a text formatter), as
+opposed to a program or commands for a program.
+
+   Human languages have syntactic and stylistic conventions that editor
+commands should support or use to advantage: conventions involving
+words, sentences, paragraphs, and capital letters.  This chapter
+describes Emacs commands for all these things.  There are also commands
+for "filling", or rearranging paragraphs into lines of approximately
+equal length.  The commands for moving over and killing words,
+sentences, and paragraphs, while intended primarily for editing text,
+are also often useful for editing programs.
+
+   Emacs has several major modes for editing human language text.  If a
+file contains plain text, use Text mode, which customizes Emacs in
+small ways for the syntactic conventions of text.  For text which
+contains embedded commands for text formatters, Emacs has other major
+modes, each for a particular text formatter.  Thus, for input to TeX,
+you can use TeX mode; for input to nroff, Nroff mode.
+
+* Menu:
+
+* Text Mode::   The major modes for editing text files.
+* Nroff Mode::  The major mode for editing input to the formatter nroff.
+* TeX Mode::    The major modes for editing input to the formatter TeX.
+* Outline Mode:: The major mode for editing outlines.
+* Words::       Moving over and killing words.
+* Sentences::   Moving over and killing sentences.
+* Paragraphs:: Moving over paragraphs.
+* Pages::      Moving over pages.
+* Filling::     Filling or justifying text
+* Case::        Changing the case of text
+
+\1f
+File: xemacs.info,  Node: Text Mode,  Next: Words,  Prev: Text,  Up: Text
+
+Text Mode
+=========
+
+You should use Text mode--rather than Fundamental or Lisp mode--to edit
+files of text in a human language.  Invoke `M-x text-mode' to enter
+Text mode.  In Text mode, <TAB> runs the function `tab-to-tab-stop',
+which allows you to use arbitrary tab stops set with `M-x
+edit-tab-stops' (*note Tab Stops::).  Features concerned with comments
+in programs are turned off unless they are explicitly invoked.  The
+syntax table is changed so that periods are not considered part of a
+word, while apostrophes, backspaces and underlines are.
+
+   A similar variant mode is Indented Text mode, intended for editing
+text in which most lines are indented.  This mode defines <TAB> to run
+`indent-relative' (*note Indentation::), and makes Auto Fill indent the
+lines it creates.  As a result, a line made by Auto Filling, or by
+<LFD>, is normally indented just like the previous line.  Use `M-x
+indented-text-mode' to select this mode.
+
+   Entering Text mode or Indented Text mode calls the value of the
+variable `text-mode-hook' with no arguments, if that value exists and
+is not `nil'.  This value is also called when modes related to Text
+mode are entered; this includes Nroff mode, TeX mode, Outline mode, and
+Mail mode.  Your hook can look at the value of `major-mode' to see
+which of these modes is actually being entered.
+
+   Two modes similar to Text mode are of use for editing text that is to
+be passed through a text formatter before achieving its final readable
+form.
+
+* Menu:
+
+* Nroff Mode::  The major mode for editing input to the formatter nroff.
+* TeX Mode::    The major modes for editing input to the formatter TeX.
+
+
+  Another similar mode is used for editing outlines.  It allows you
+to view the text at various levels of detail.  You can view either
+the outline headings alone or both headings and text; you can also
+hide some of the headings at lower levels from view to make the high
+level structure more visible.
+
+
+* Outline Mode:: The major mode for editing outlines.
+
+\1f
+File: xemacs.info,  Node: Nroff Mode,  Next: TeX Mode,  Prev: Text Mode,  Up: Text Mode
+
+Nroff Mode
+----------
+
+Nroff mode is a mode like Text mode but modified to handle nroff
+commands present in the text.  Invoke `M-x nroff-mode' to enter this
+mode.  Nroff mode differs from Text mode in only a few ways.  All nroff
+command lines are considered paragraph separators, so that filling never
+garbles the nroff commands.  Pages are separated by `.bp' commands.
+Comments start with backslash-doublequote.  There are also three special
+commands that are not available in Text mode:
+
+`M-n'
+     Move to the beginning of the next line that isn't an nroff command
+     (`forward-text-line').  An argument is a repeat count.
+
+`M-p'
+     Like `M-n' but move up (`backward-text-line').
+
+`M-?'
+     Prints in the echo area the number of text lines (lines that are
+     not nroff commands) in the region (`count-text-lines').
+
+   The other feature of Nroff mode is Electric Nroff newline mode.
+This is a minor mode that you can turn on or off with `M-x
+electric-nroff-mode' (*note Minor Modes::).  When the mode is on and
+you use <RET> to end a line containing an nroff command that opens a
+kind of grouping, Emacs automatically inserts the matching nroff
+command to close that grouping on the following line.  For example, if
+you are at the beginning of a line and type `.(b <RET>', the matching
+command `.)b' will be inserted on a new line following point.
+
+   Entering Nroff mode calls the value of the variable `text-mode-hook'
+with no arguments, if that value exists and is not `nil'; then it does
+the same with the variable `nroff-mode-hook'.
+
+\1f
+File: xemacs.info,  Node: TeX Mode,  Next: Outline Mode,  Prev: Nroff Mode,  Up: Text Mode
+
+TeX Mode
+--------
+
+TeX is a powerful text formatter written by Donald Knuth; like GNU
+Emacs, it is free.  LaTeX is a simplified input format for TeX,
+implemented by TeX macros.  It is part of TeX.
+
+   Emacs has a special TeX mode for editing TeX input files.  It
+provides facilities for checking the balance of delimiters and for
+invoking TeX on all or part of the file.
+
+   TeX mode has two variants, Plain TeX mode and LaTeX mode, which are
+two distinct major modes that differ only slightly.  These modes are
+designed for editing the two different input formats.  The command `M-x
+tex-mode' looks at the contents of a buffer to determine whether it
+appears to be LaTeX input or not; it then selects the appropriate mode.
+If it can't tell which is right (e.g., the buffer is empty), the
+variable `tex-default-mode' controls which mode is used.
+
+   The commands `M-x plain-tex-mode' and `M-x latex-mode' explicitly
+select one of the variants of TeX mode.  Use these commands when `M-x
+tex-mode' does not guess right.
+
+* Menu:
+
+* Editing: TeX Editing.   Special commands for editing in TeX mode.
+* Printing: TeX Print.    Commands for printing part of a file with TeX.
+
+   TeX for Unix systems can be obtained from the University of
+Washington for a distribution fee.
+
+   To order a full distribution, send $140.00 for a 1/2 inch 9-track
+tape, $165.00 for two 4-track 1/4 inch cartridge tapes (foreign sites
+$150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover the extra
+postage) payable to the University of Washington to:
+
+     The Director
+     Northwest Computer Support Group,  DW-10
+     University of Washington
+     Seattle, Washington 98195
+
+Purchase orders are acceptable, but there is an extra charge of $10.00
+to pay for processing charges. (The total cost comes to $150 for
+domestic sites, $175 for foreign sites).
+
+   The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
+industry standard 2400 foot half-inch reel.  The physical format for
+the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track
+serpentine recording for the SUN.  Also, SystemV tapes can be written
+in cpio format, blocked 5120 bytes, ASCII headers.
+
+\1f
+File: xemacs.info,  Node: TeX Editing,  Next: TeX Print,  Prev: TeX Mode,  Up: TeX Mode
+
+TeX Editing Commands
+....................
+
+Here are the special commands provided in TeX mode for editing the text
+of the file.
+
+`"'
+     Insert, according to context, either ```' or `"' or `'''
+     (`TeX-insert-quote').
+
+`<LFD>'
+     Insert a paragraph break (two newlines) and check the previous
+     paragraph for unbalanced braces or dollar signs (`tex-terminate-
+     paragraph').
+
+`M-x validate-tex-buffer'
+     Check each paragraph in the buffer for unbalanced braces or dollar
+     signs.
+
+`C-c {'
+     Insert `{}' and position point between them (`tex-insert-braces').
+
+`C-c }'
+     Move forward past the next unmatched close brace (`up-list').
+
+`C-c C-e'
+     Close a block for LaTeX (`tex-close-latex-block').
+
+   In TeX, the character `"' is not normally used; you use ```' to
+start a quotation and `''' to end one.  TeX mode defines the key `"' to
+insert ```' after whitespace or an open brace, `"' after a backslash,
+or `''' otherwise.  This is done by the command `tex-insert-quote'.  If
+you need the character `"' itself in unusual contexts, use `C-q' to
+insert it.  Also, `"' with a numeric argument always inserts that
+number of `"' characters.
+
+   In TeX mode, `$' has a special syntax code which attempts to
+understand the way TeX math mode delimiters match.  When you insert a
+`$' that is meant to exit math mode, the position of the matching `$'
+that entered math mode is displayed for a second.  This is the same
+feature that displays the open brace that matches a close brace that is
+inserted.  However, there is no way to tell whether a `$' enters math
+mode or leaves it; so when you insert a `$' that enters math mode, the
+previous `$' position is shown as if it were a match, even though they
+are actually unrelated.
+
+   If you prefer to keep braces balanced at all times, you can use `C-c
+{' (`tex-insert-braces') to insert a pair of braces.  It leaves point
+between the two braces so you can insert the text that belongs inside.
+Afterward, use the command `C-c }' (`up-list') to move forward past the
+close brace.
+
+   There are two commands for checking the matching of braces.  <LFD>
+(`tex-terminate-paragraph') checks the paragraph before point, and
+inserts two newlines to start a new paragraph.  It prints a message in
+the echo area if any mismatch is found.  `M-x validate-tex-buffer'
+checks the entire buffer, paragraph by paragraph.  When it finds a
+paragraph that contains a mismatch, it displays point at the beginning
+of the paragraph for a few seconds and pushes a mark at that spot.
+Scanning continues until the whole buffer has been checked or until you
+type another key.  The positions of the last several paragraphs with
+mismatches can be found in the mark ring (*note Mark Ring::).
+
+   Note that square brackets and parentheses, not just braces, are
+matched in TeX mode.  This is wrong if you want to  check TeX syntax.
+However, parentheses and square brackets are likely to be used in text
+as matching delimiters and it is useful for the various motion commands
+and automatic match display to work with them.
+
+   In LaTeX input, `\begin' and `\end' commands must balance.  After
+you insert a `\begin', use `C-c C-f' (`tex-close-latex-block') to
+insert automatically a matching `\end' (on a new line following the
+`\begin').  A blank line is inserted between the two, and point is left
+there.
+
+\1f
+File: xemacs.info,  Node: TeX Print,  Prev: TeX Editing,  Up: TeX Mode
+
+TeX Printing Commands
+.....................
+
+You can invoke TeX as an inferior of Emacs on either the entire
+contents of the buffer or just a region at a time.  Running TeX in this
+way on just one chapter is a good way to see what your changes look
+like without taking the time to format the entire file.
+
+`C-c C-r'
+     Invoke TeX on the current region, plus the buffer's header
+     (`tex-region').
+
+`C-c C-b'
+     Invoke TeX on the entire current buffer (`tex-buffer').
+
+`C-c C-l'
+     Recenter the window showing output from the inferior TeX so that
+     the last line can be seen (`tex-recenter-output-buffer').
+
+`C-c C-k'
+     Kill the inferior TeX (`tex-kill-job').
+
+`C-c C-p'
+     Print the output from the last `C-c C-r' or `C-c C-b' command
+     (`tex-print').
+
+`C-c C-q'
+     Show the printer queue (`tex-show-print-queue').
+
+   You can pass the current buffer through an inferior TeX using `C-c
+C-b' (`tex-buffer').  The formatted output appears in a file in `/tmp';
+to print it, type `C-c C-p' (`tex-print').  Afterward use `C-c C-q'
+(`tex-show-print-queue') to view the progress of your output towards
+being printed.
+
+   The console output from TeX, including any error messages, appears
+in a buffer called `*TeX-shell*'.  If TeX gets an error, you can switch
+to this buffer and feed it input (this works as in Shell mode; *note
+Interactive Shell::).  Without switching to this buffer, you can scroll
+it so that its last line is visible by typing `C-c C-l'.
+
+   Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
+that its output is no longer useful.  Using `C-c C-b' or `C-c C-r' also
+kills any TeX process still running.
+
+   You can pass an arbitrary region through an inferior TeX by typing
+`C-c C-r' (`tex-region').  This is tricky, however, because most files
+of TeX input contain commands at the beginning to set parameters and
+define macros.  Without them, no later part of the file will format
+correctly.  To solve this problem, `C-c C-r' allows you to designate a
+part of the file as containing essential commands; it is included
+before the specified region as part of the input to TeX.  The
+designated part of the file is called the "header".
+
+   To indicate the bounds of the header in Plain TeX mode, insert two
+special strings in the file: `%**start of header' before the header,
+and `%**end of header' after it.  Each string must appear entirely on
+one line, but there may be other text on the line before or after.  The
+lines containing the two strings are included in the header.  If
+`%**start of header' does not appear within the first 100 lines of the
+buffer, `C-c C-r' assumes there is no header.
+
+   In LaTeX mode, the header begins with `\documentstyle' and ends with
+`\begin{document}'.  These are commands that LaTeX requires you to use,
+so you don't need to do anything special to identify the header.
+
+   When you enter either kind of TeX mode, Emacs calls with no
+arguments the value of the variable `text-mode-hook', if that value
+exists and is not `nil'.  Emacs then calls the variable `TeX-mode-hook'
+and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same
+conditions.
+
+\1f
+File: xemacs.info,  Node: Outline Mode,  Prev: TeX Mode,  Up: Text Mode
+
+Outline Mode
+------------
+
+Outline mode is a major mode similar to Text mode but intended for
+editing outlines.  It allows you to make parts of the text temporarily
+invisible so that you can see just the overall structure of the
+outline.  Type `M-x outline-mode' to turn on Outline mode in the
+current buffer.
+
+   When you enter Outline mode, Emacs calls with no arguments the value
+of the variable `text-mode-hook', if that value exists and is not
+`nil'; then it does the same with the variable `outline-mode-hook'.
+
+   When a line is invisible in outline mode, it does not appear on the
+screen.  The screen appears exactly as if the invisible line were
+deleted, except that an ellipsis (three periods in a row) appears at
+the end of the previous visible line (only one ellipsis no matter how
+many invisible lines follow).
+
+   All editing commands treat the text of the invisible line as part of
+the previous visible line.  For example, `C-n' moves onto the next
+visible line.  Killing an entire visible line, including its
+terminating newline, really kills all the following invisible lines as
+well; yanking everything back yanks the invisible lines and they remain
+invisible.
+
+* Menu:
+
+* Format: Outline Format.        What the text of an outline looks like.
+* Motion: Outline Motion.        Special commands for moving through outlines.
+* Visibility: Outline Visibility. Commands to control what is visible.
+
+\1f
+File: xemacs.info,  Node: Outline Format,  Next: Outline Motion,  Prev: Outline Mode,  Up: Outline Mode
+
+Format of Outlines
+..................
+
+Outline mode assumes that the lines in the buffer are of two types:
+"heading lines" and "body lines".  A heading line represents a topic in
+the outline.  Heading lines start with one or more stars; the number of
+stars determines the depth of the heading in the outline structure.
+Thus, a heading line with one star is a major topic; all the heading
+lines with two stars between it and the next one-star heading are its
+subtopics; and so on.  Any line that is not a heading line is a body
+line.  Body lines belong to the preceding heading line.  Here is an
+example:
+
+     * Food
+     
+     This is the body,
+     which says something about the topic of food.
+     
+     ** Delicious Food
+     
+     This is the body of the second-level header.
+     
+     ** Distasteful Food
+     
+     This could have
+     a body too, with
+     several lines.
+     
+     *** Dormitory Food
+     
+     * Shelter
+     
+     A second first-level topic with its header line.
+
+   A heading line together with all following body lines is called
+collectively an "entry".  A heading line together with all following
+deeper heading lines and their body lines is called a "subtree".
+
+   You can customize the criterion for distinguishing heading lines by
+setting the variable `outline-regexp'.  Any line whose beginning has a
+match for this regexp is considered a heading line.  Matches that start
+within a line (not at the beginning) do not count.  The length of the
+matching text determines the level of the heading; longer matches make
+a more deeply nested level.  Thus, for example, if a text formatter has
+commands `@chapter', `@section' and `@subsection' to divide the
+document into chapters and sections, you can make those lines count as
+heading lines by setting `outline-regexp' to
+`"@chap\\|@\\(sub\\)*section"'.  Note the trick: the two words
+`chapter' and `section' are the same length, but by defining the regexp
+to match only `chap' we ensure that the length of the text matched on a
+chapter heading is shorter, so that Outline mode will know that
+sections are contained in chapters.  This works as long as no other
+command starts with `@chap'.
+
+   Outline mode makes a line invisible by changing the newline before it
+into an ASCII Control-M (code 015).  Most editing commands that work on
+lines treat an invisible line as part of the previous line because,
+strictly speaking, it is part of that line, since there is no longer a
+newline in between.  When you save the file in Outline mode, Control-M
+characters are saved as newlines, so the invisible lines become ordinary
+lines in the file.  Saving does not change the visibility status of a
+line inside Emacs.
+
+\1f
+File: xemacs.info,  Node: Outline Motion,  Next: Outline Visibility,  Prev: Outline Format,  Up: Outline Mode
+
+Outline Motion Commands
+.......................
+
+Some special commands in Outline mode move backward and forward to
+heading lines.
+
+`C-c C-n'
+     Move point to the next visible heading line
+     (`outline-next-visible-heading').
+
+`C-c C-p'
+     Move point to the previous visible heading line
+     (`outline-previous-visible-heading').
+
+`C-c C-f'
+     Move point to the next visible heading line at the same level as
+     the one point is on (`outline-forward-same-level').
+
+`C-c C-b'
+     Move point to the previous visible heading line at the same level
+     (`outline-backward-same-level').
+
+`C-c C-u'
+     Move point up to a lower-level (more inclusive) visible heading
+     line (`outline-up-heading').
+
+   `C-c C-n' (`next-visible-heading') moves down to the next heading
+line.  `C-c C-p' (`previous-visible-heading') moves similarly backward.
+Both accept numeric arguments as repeat counts.  The names emphasize
+that invisible headings are skipped, but this is not really a special
+feature.  All editing commands that look for lines ignore the invisible
+lines automatically.
+
+   More advanced motion commands understand the levels of headings.
+The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
+(`outline-backward-same-level') move from one heading line to another
+visible heading at the same depth in the outline.  `C-c C-u'
+(`outline-up-heading') moves backward to another heading that is less
+deeply nested.
+
+\1f
+File: xemacs.info,  Node: Outline Visibility,  Prev: Outline Motion,  Up: Outline Mode
+
+Outline Visibility Commands
+...........................
+
+The other special commands of outline mode are used to make lines
+visible or invisible.  Their names all start with `hide' or `show'.
+Most of them exist as pairs of opposites.  They are not undoable;
+instead, you can undo right past them.  Making lines visible or
+invisible is simply not recorded by the undo mechanism.
+
+`M-x hide-body'
+     Make all body lines in the buffer invisible.
+
+`M-x show-all'
+     Make all lines in the buffer visible.
+
+`C-c C-d'
+     Make everything under this heading invisible, not including this
+     heading itself (`hide-subtree').
+
+`C-c C-s'
+     Make everything under this heading visible, including body,
+     subheadings, and their bodies (`show-subtree').
+
+`M-x hide-leaves'
+     Make the body of this heading line, and of all its subheadings,
+     invisible.
+
+`M-x show-branches'
+     Make all subheadings of this heading line, at all levels, visible.
+
+`C-c C-i'
+     Make immediate subheadings (one level down) of this heading line
+     visible (`show-children').
+
+`M-x hide-entry'
+     Make this heading line's body invisible.
+
+`M-x show-entry'
+     Make this heading line's body visible.
+
+   Two commands that are exact opposites are `M-x hide-entry' and `M-x
+show-entry'.  They are used with point on a heading line, and apply
+only to the body lines of that heading.  The subtopics and their bodies
+are not affected.
+
+   Two more powerful opposites are `C-c C-d' (`hide-subtree') and `C-c
+C-s' (`show-subtree').  Both should be used when point is on a heading
+line, and both apply to all the lines of that heading's "subtree": its
+body, all its subheadings, both direct and indirect, and all of their
+bodies.  In other words, the subtree contains everything following this
+heading line, up to and not including the next heading of the same or
+higher rank.
+
+   Intermediate between a visible subtree and an invisible one is having
+all the subheadings visible but none of the body.  There are two
+commands for doing this, one that hides the bodies and one that makes
+the subheadings visible.  They are `M-x hide-leaves' and `M-x
+show-branches'.
+
+   A little weaker than `show-branches' is `C-c C-i' (`show-children').
+It makes just the direct subheadings visible--those one level down.
+Deeper subheadings remain invisible.
+
+   Two commands have a blanket effect on the whole file.  `M-x
+hide-body' makes all body lines invisible, so that you see just the
+outline structure.  `M-x show-all' makes all lines visible.  You can
+think of these commands as a pair of opposites even though `M-x
+show-all' applies to more than just body lines.
+
+   You can turn off the use of ellipses at the ends of visible lines by
+setting `selective-display-ellipses' to `nil'.  The result is no
+visible indication of the presence of invisible lines.
+
+\1f
+File: xemacs.info,  Node: Words,  Next: Sentences,  Prev: Text Mode,  Up: Text
+
+Words
+=====
+
+Emacs has commands for moving over or operating on words.  By
+convention, the keys for them are all `Meta-' characters.
+
+`M-f'
+     Move forward over a word (`forward-word').
+
+`M-b'
+     Move backward over a word (`backward-word').
+
+`M-d'
+     Kill up to the end of a word (`kill-word').
+
+`M-<DEL>'
+     Kill back to the beginning of a word (`backward-kill-word').
+
+`M-@'
+     Mark the end of the next word (`mark-word').
+
+`M-t'
+     Transpose two words;  drag a word forward or backward across other
+     words (`transpose-words').
+
+   Notice how these keys form a series that parallels the
+character-based `C-f', `C-b', `C-d', `C-t' and <DEL>.  `M-@' is related
+to `C-@', which is an alias for `C-<SPC>'.
+
+   The commands `Meta-f' (`forward-word') and `Meta-b'
+(`backward-word') move forward and backward over words.  They are
+analogous to `Control-f' and `Control-b', which move over single
+characters.  Like their `Control-' analogues, `Meta-f' and `Meta-b'
+move several words if given an argument.  `Meta-f' with a negative
+argument moves backward, and `Meta-b' with a negative argument moves
+forward.  Forward motion stops after the last letter of the word, while
+backward motion stops before the first letter.
+
+   `Meta-d' (`kill-word') kills the word after point.  To be precise,
+it kills everything from point to the place `Meta-f' would move to.
+Thus, if point is in the middle of a word, `Meta-d' kills just the part
+after point.  If some punctuation comes between point and the next
+word, it is killed along with the word.  (To kill only the next word
+but not the punctuation before it, simply type `Meta-f' to get to the
+end and kill the word backwards with `Meta-<DEL>'.)  `Meta-d' takes
+arguments just like `Meta-f'.
+
+   `Meta-<DEL>' (`backward-kill-word') kills the word before point.  It
+kills everything from point back to where `Meta-b' would move to.  If
+point is after the space in `FOO, BAR', then `FOO, ' is killed.   To
+kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
+
+   `Meta-t' (`transpose-words') exchanges the word before or containing
+point with the following word.  The delimiter characters between the
+words do not move.  For example, transposing `FOO, BAR' results in
+`BAR, FOO' rather than `BAR FOO,'.  *Note Transpose::, for more on
+transposition and on arguments to transposition commands.
+
+   To operate on the next N words with an operation which applies
+between point and mark, you can either set the mark at point and then
+move over the words, or you can use the command `Meta-@' (`mark-word')
+which does not move point but sets the mark where `Meta-f' would move
+to.  It can be given arguments just like `Meta-f'.
+
+   The word commands' understanding of syntax is completely controlled
+by the syntax table.  For example, any character can be declared to be
+a word delimiter.  *Note Syntax::.
+
+\1f
+File: xemacs.info,  Node: Sentences,  Next: Paragraphs,  Prev: Words,  Up: Text
+
+Sentences
+=========
+
+The Emacs commands for manipulating sentences and paragraphs are mostly
+on `Meta-' keys, and therefore are like the word-handling commands.
+
+`M-a'
+     Move back to the beginning of the sentence (`backward-sentence').
+
+`M-e'
+     Move forward to the end of the sentence (`forward-sentence').
+
+`M-k'
+     Kill forward to the end of the sentence (`kill-sentence').
+
+`C-x <DEL>'
+     Kill back to the beginning of the sentence
+     (`backward-kill-sentence').
+
+   The commands `Meta-a' and `Meta-e' (`backward-sentence' and
+`forward-sentence') move to the beginning and end of the current
+sentence, respectively.  They resemble `Control-a' and `Control-e',
+which move to the beginning and end of a line.  Unlike their
+counterparts, `Meta-a' and `Meta-e' move over successive sentences if
+repeated or given numeric arguments.  Emacs assumes the typist's
+convention is followed, and thus considers a sentence to end wherever
+there is a `.', `?', or `!' followed by the end of a line or two
+spaces, with any number of `)', `]', `'', or `"' characters allowed in
+between.  A sentence also begins or ends wherever a paragraph begins or
+ends.
+
+   Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
+sentence edge at which it is stopping.
+
+   `M-a' and `M-e' have a corresponding kill command, just like `C-a'
+and `C-e' have `C-k'.  The command is  `M-k' (`kill-sentence') which
+kills from point to the end of the sentence.  With minus one as an
+argument it kills back to the beginning of the sentence.  Larger
+arguments serve as repeat counts.
+
+   There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
+for killing back to the beginning of a sentence, which is useful when
+you change your mind in the middle of composing text.
+
+   The variable `sentence-end' controls recognition of the end of a
+sentence.  It is a regexp that matches the last few characters of a
+sentence, together with the whitespace following the sentence.  Its
+normal value is:
+
+     "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
+
+This example is explained in the section on regexps.  *Note Regexps::.
+
+\1f
+File: xemacs.info,  Node: Paragraphs,  Next: Pages,  Prev: Sentences,  Up: Text
+
+Paragraphs
+==========
+
+The Emacs commands for manipulating paragraphs are also `Meta-' keys.
+
+`M-{'
+     Move back to previous paragraph beginning
+     (`backward-paragraph').
+
+`M-}'
+     Move forward to next paragraph end (`forward-paragraph').
+
+`M-h'
+     Put point and mark around this or next paragraph
+     (`mark-paragraph').
+
+   `Meta-{' moves to the beginning of the current or previous paragraph,
+while `Meta-}' moves to the end of the current or next paragraph.
+Blank lines and text formatter command lines separate paragraphs and are
+not part of any paragraph.  An indented line starts a new paragraph.
+
+   In major modes for programs (as opposed to Text mode), paragraphs
+begin and end only at blank lines.  As a result, the paragraph commands
+continue to be useful even though there are no paragraphs per se.
+
+   When there is a fill prefix, paragraphs are delimited by all lines
+which don't start with the fill prefix.  *Note Filling::.
+
+   To operate on a paragraph, you can use the command `Meta-h'
+(`mark-paragraph') to set the region around it.  This command puts
+point at the beginning and mark at the end of the paragraph point was
+in.  If point is between paragraphs (in a run of blank lines or at a
+boundary), the paragraph following point is surrounded by point and
+mark.  If there are blank lines preceding the first line of the
+paragraph, one of the blank lines is included in the region.  Thus, for
+example, `M-h C-w' kills the paragraph around or after point.
+
+   The precise definition of a paragraph boundary is controlled by the
+variables `paragraph-separate' and `paragraph-start'.  The value of
+`paragraph-start' is a regexp that matches any line that either starts
+or separates paragraphs.  The value of `paragraph-separate' is another
+regexp that  matches only lines that separate paragraphs without being
+part of any paragraph.  Lines that start a new paragraph and are
+contained in it must match both regexps.  For example, normally
+`paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
+\t\f]*$"'.
+
+   Normally it is desirable for page boundaries to separate paragraphs.
+The default values of these variables recognize the usual separator for
+pages.
+
+\1f
+File: xemacs.info,  Node: Pages,  Next: Filling,  Prev: Paragraphs,  Up: Text
+
+Pages
+=====
+
+Files are often thought of as divided into "pages" by the "formfeed"
+character (ASCII Control-L, octal code 014).  For example, if a file is
+printed on a line printer, each "page" of the file starts on a new page
+of paper.  Emacs treats a page-separator character just like any other
+character.  It can be inserted with `C-q C-l' or deleted with <DEL>.
+You are free to paginate your file or not.  However, since pages are
+often meaningful divisions of the file, commands are provided to move
+over them and operate on them.
+
+`C-x ['
+     Move point to previous page boundary (`backward-page').
+
+`C-x ]'
+     Move point to next page boundary (`forward-page').
+
+`C-x C-p'
+     Put point and mark around this page (or another page)
+     (`mark-page').
+
+`C-x l'
+     Count the lines in this page (`count-lines-page').
+
+   The `C-x [' (`backward-page') command moves point to immediately
+after the previous page delimiter.  If point is already right after a
+page delimiter, the command skips that one and stops at the previous
+one.  A numeric argument serves as a repeat count.  The `C-x ]'
+(`forward-page') command moves forward past the next page delimiter.
+
+   The `C-x C-p' command (`mark-page') puts point at the beginning of
+the current page and the mark at the end.  The page delimiter at the end
+is included (the mark follows it).  The page delimiter at the front is
+excluded (point follows it).  You can follow this command  by `C-w' to
+kill a page you want to move elsewhere.  If you insert the page after a
+page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
+page will be properly delimited before and after once again.
+
+   A numeric argument to `C-x C-p' is used to specify which page to go
+to, relative to the current one.  Zero means the current page.  One
+means the next page, and -1 means the previous one.
+
+   The `C-x l' command (`count-lines-page') can help you decide where
+to break a page in two.  It prints the total number of lines in the
+current page in the echo area, then divides the lines into those
+preceding the current line and those following it, for example
+
+     Page has 96 (72+25) lines
+
+Notice that the sum is off by one; this is correct if point is not at
+the beginning of a line.
+
+   The variable `page-delimiter' should have as its value a regexp that
+matches the beginning of a line that separates pages.  This defines
+where pages begin.  The normal value of this variable is `"^\f"', which
+matches a formfeed character at the beginning of a line.
+
+\1f
+File: xemacs.info,  Node: Filling,  Next: Case,  Prev: Pages,  Up: Text
+
+Filling Text
+============
+
+If you use Auto Fill mode, Emacs "fills" text (breaks it up into lines
+that fit in a specified width) as you insert it.  When you alter
+existing text it is often no longer be properly filled afterwards and
+you can use explicit commands for filling.
+
+* Menu:
+
+* Auto Fill::    Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix::   Filling when every line is indented or in a comment, etc.
+
+\1f
+File: xemacs.info,  Node: Auto Fill,  Next: Fill Commands,  Prev: Filling,  Up: Filling
+
+Auto Fill Mode
+--------------
+
+"Auto Fill" mode is a minor mode in which lines are broken
+automatically when they become too wide.  Breaking happens only when
+you type a <SPC> or <RET>.
+
+`M-x auto-fill-mode'
+     Enable or disable Auto Fill mode.
+
+`<SPC>'
+`<RET>'
+     In Auto Fill mode, break lines when appropriate.
+
+   `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
+if it was on.  With a positive numeric argument the command always turns
+Auto Fill mode on, and with a negative argument it always turns it off.
+The presence of the word `Fill' in the mode line, inside the
+parentheses, indicates that Auto Fill mode is in effect.  Auto Fill mode
+is a minor mode; you can turn it on or off for each buffer individually.
+*Note Minor Modes::.
+
+   In Auto Fill mode, lines are broken automatically at spaces when
+they get longer than desired.  Line breaking and rearrangement takes
+place only when you type <SPC> or <RET>.  To insert a space or newline
+without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
+(recall that a newline is really a linefeed).  `C-o' inserts a newline
+without line breaking.
+
+   Auto Fill mode works well with Lisp mode: when it makes a new line in
+Lisp mode, it indents that line with <TAB>.  If a line ending in a Lisp
+comment gets too long, the text of the comment is split into two
+comment lines.  Optionally, new comment delimiters are inserted at the
+end of the first line and the beginning of the second, so that each line
+is a separate comment.  The variable `comment-multi-line' controls the
+choice (*note Comments::).
+
+   Auto Fill mode does not refill entire paragraphs.  It can break
+lines but cannot merge lines.  Editing in the middle of a paragraph can
+result in a paragraph that is not correctly filled.  The easiest way to
+make the paragraph properly filled again is using an explicit fill
+commands.
+
+   Many users like Auto Fill mode and want to use it in all text files.
+The section on init files explains how you can arrange this permanently
+for yourself.  *Note Init File::.
+
+\1f
+File: xemacs.info,  Node: Fill Commands,  Next: Fill Prefix,  Prev: Auto Fill,  Up: Filling
+
+Explicit Fill Commands
+----------------------
+
+`M-q'
+     Fill current paragraph (`fill-paragraph').
+
+`M-g'
+     Fill each paragraph in the region (`fill-region').
+
+`C-x f'
+     Set the fill column (`set-fill-column').
+
+`M-x fill-region-as-paragraph'
+     Fill the region, considering it as one paragraph.
+
+`M-s'
+     Center a line.
+
+   To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
+It causes the paragraph containing point, or the one after point if
+point is between paragraphs, to be refilled.  All line breaks are
+removed, and new ones are inserted where necessary.  `M-q' can be
+undone with `C-_'.  *Note Undo::.
+
+   To refill many paragraphs, use `M-g' (`fill-region'), which divides
+the region into paragraphs and fills each of them.
+
+   `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
+paragraph boundaries (*note Paragraphs::).  For more control, you can
+use `M-x fill-region-as-paragraph', which refills everything between
+point and mark.  This command recognizes only blank lines as paragraph
+separators.
+
+   A numeric argument to `M-g' or `M-q' causes it to "justify" the text
+as well as filling it.  Extra spaces are inserted to make the right
+margin line up exactly at the fill column.  To remove the extra spaces,
+use `M-q' or `M-g' with no argument.
+
+   The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
+match lines that should not be auto-filled.
+
+   The command `Meta-s' (`center-line') centers the current line within
+the current fill column.  With an argument, it centers several lines
+individually and moves past them.
+
+   The maximum line width for filling is in the variable `fill-column'.
+Altering the value of `fill-column' makes it local to the current
+buffer; until then, the default value--initially 70--is in effect.
+*Note Locals::.
+
+   The easiest way to set `fill-column' is to use the command `C-x f'
+(`set-fill-column').  With no argument, it sets `fill-column' to the
+current horizontal position of point.  With a numeric argument, it uses
+that number as the new fill column.
+
+\1f
+File: xemacs.info,  Node: Fill Prefix,  Prev: Fill Commands,  Up: Filling
+
+The Fill Prefix
+---------------
+
+To fill a paragraph in which each line starts with a special marker
+(which might be a few spaces, giving an indented paragraph), use the
+"fill prefix" feature.  The fill prefix is a string which is not
+included in filling.  Emacs expects every line to start with a fill
+prefix.
+
+`C-x .'
+     Set the fill prefix (`set-fill-prefix').
+
+`M-q'
+     Fill a paragraph using current fill prefix (`fill-paragraph').
+
+`M-x fill-individual-paragraphs'
+     Fill the region, considering each change of indentation as
+     starting a new paragraph.
+
+   To specify a fill prefix, move to a line that starts with the desired
+prefix, put point at the end of the prefix, and give the command
+`C-x .' (`set-fill-prefix').  That's a period after the `C-x'.  To turn
+off the fill prefix, specify an empty prefix: type `C-x .' with point
+at the beginning of a line.
+
+   When a fill prefix is in effect, the fill commands remove the fill
+prefix from each line before filling and insert it on each line after
+filling.  Auto Fill mode also inserts the fill prefix inserted on new
+lines it creates.  Lines that do not start with the fill prefix are
+considered to start paragraphs, both in `M-q' and the paragraph
+commands; this is just right if you are using paragraphs with hanging
+indentation (every line indented except the first one).  Lines which are
+blank or indented once the prefix is removed also separate or start
+paragraphs; this is what you want if you are writing multi-paragraph
+comments with a comment delimiter on each line.
+
+   The fill prefix is stored in the variable `fill-prefix'.  Its value
+is a string, or `nil' when there is no fill prefix.  This is a
+per-buffer variable; altering the variable affects only the current
+buffer, but there is a default value which you can change as well.
+*Note Locals::.
+
+   Another way to use fill prefixes is through `M-x
+fill-individual-paragraphs'.  This function divides the region into
+groups of consecutive lines with the same amount and kind of
+indentation and fills each group as a paragraph, using its indentation
+as a fill prefix.
+
+\1f
+File: xemacs.info,  Node: Case,  Prev: Filling,  Up: Text
+
+Case Conversion Commands
+========================
+
+Emacs has commands for converting either a single word or any arbitrary
+range of text to upper case or to lower case.
+
+`M-l'
+     Convert following word to lower case (`downcase-word').
+
+`M-u'
+     Convert following word to upper case (`upcase-word').
+
+`M-c'
+     Capitalize the following word (`capitalize-word').
+
+`C-x C-l'
+     Convert region to lower case (`downcase-region').
+
+`C-x C-u'
+     Convert region to upper case (`upcase-region').
+
+   The word conversion commands are used most frequently.  `Meta-l'
+(`downcase-word') converts the word after point to lower case, moving
+past it.  Thus, repeating `Meta-l' converts successive words.  `Meta-u'
+(`upcase-word') converts to all capitals instead, while `Meta-c'
+(`capitalize-word') puts the first letter of the word into upper case
+and the rest into lower case.  The word conversion commands convert
+several words at once if given an argument.  They are especially
+convenient for converting a large amount of text from all upper case to
+mixed case: you can move through the text using `M-l', `M-u', or `M-c'
+on each word as appropriate, occasionally using `M-f' instead to skip a
+word.
+
+   When given a negative argument, the word case conversion commands
+apply to the appropriate number of words before point, but do not move
+point.  This is convenient when you have just typed a word in the wrong
+case: you can give the case conversion command and continue typing.
+
+   If a word case conversion command is given in the middle of a word,
+it applies only to the part of the word which follows point.  This is
+just like what `Meta-d' (`kill-word') does.  With a negative argument,
+case conversion applies only to the part of the word before point.
+
+   The other case conversion commands are `C-x C-u' (`upcase-region')
+and `C-x C-l' (`downcase-region'), which convert everything between
+point and mark to the specified case.  Point and mark do not move.
+
+\1f
+File: xemacs.info,  Node: Programs,  Next: Running,  Prev: Text,  Up: Top
+
+Editing Programs
+****************
+
+Emacs has many commands designed to understand the syntax of programming
+languages such as Lisp and C.  These commands can:
+
+   * Move over or kill balanced expressions or "sexps" (*note Lists::).
+
+   * Move over or mark top-level balanced expressions ("defuns", in
+     Lisp; functions, in C).
+
+   * Show how parentheses balance (*note Matching::).
+
+   * Insert, kill, or align comments (*note Comments::).
+
+   * Follow the usual indentation conventions of the language (*note
+     Grinding::).
+
+   The commands available for words, sentences, and paragraphs are
+useful in editing code even though their canonical application is for
+editing human language text.  Most symbols contain words (*note
+Words::); sentences can be found in strings and comments (*note
+Sentences::).  Paragraphs per se are not present in code, but the
+paragraph commands are useful anyway, because Lisp mode and C mode
+define paragraphs to begin and end at blank lines (*note Paragraphs::).
+Judicious use of blank lines to make the program clearer also provides
+interesting chunks of text for the paragraph commands to work on.
+
+   The selective display feature is useful for looking at the overall
+structure of a function (*note Selective Display::).  This feature
+causes only the lines that are indented less than a specified amount to
+appear on the screen.
+
+* Menu:
+
+* Program Modes::       Major modes for editing programs.
+* Lists::               Expressions with balanced parentheses.
+                         There are editing commands to operate on them.
+* Defuns::              Each program is made up of separate functions.
+                         There are editing commands to operate on them.
+* Grinding::            Adjusting indentation to show the nesting.
+* Matching::            Insertion of a close-delimiter flashes matching open.
+* Comments::            Inserting, filling and aligning comments.
+* Balanced Editing::    Inserting two matching parentheses at once, etc.
+* Lisp Completion::     Completion on symbol names in Lisp code.
+* Documentation::       Getting documentation of functions you plan to call.
+* Change Log::          Maintaining a change history for your program.
+* Tags::                Go direct to any function in your program in one
+                         command.  Tags remembers which file it is in.
+* Fortran::            Fortran mode and its special features.
+* Asm Mode::            Asm mode and its special features.
+
+\1f
+File: xemacs.info,  Node: Program Modes,  Next: Lists,  Prev: Programs,  Up: Programs
+
+Major Modes for Programming Languages
+=====================================
+
+Emacs has several major modes for the programming languages Lisp,
+Scheme (a variant of Lisp), C, Fortran, and Muddle.  Ideally, a major
+mode should be implemented for each programming language you might want
+to edit with Emacs; but often the mode for one language can serve for
+other syntactically similar languages.  The language modes that exist
+are those that someone decided to take the trouble to write.
+
+   There are several variants of Lisp mode, which differ in the way they
+interface to Lisp execution.  *Note Lisp Modes::.
+
+   Each of the programming language modes defines the <TAB> key to run
+an indentation function that knows the indentation conventions of that
+language and updates the current line's indentation accordingly.  For
+example, in C mode <TAB> is bound to `c-indent-line'.  <LFD> is
+normally defined to do <RET> followed by <TAB>; thus it, too, indents
+in a mode-specific fashion.
+
+   In most programming languages, indentation is likely to vary from
+line to line.  So the major modes for those languages rebind <DEL> to
+treat a tab as if it were the equivalent number of spaces (using the
+command `backward-delete-char-untabify').  This makes it possible to
+rub out indentation one column at a time without worrying whether it is
+made up of spaces or tabs.  In these modes, use `C-b C-d' to delete a
+tab character before point.
+
+   Programming language modes define paragraphs to be separated only by
+blank lines, so that the paragraph commands remain useful.  Auto Fill
+mode, if enabled in a programming language major mode, indents the new
+lines which it creates.
+
+   Turning on a major mode calls a user-supplied function called the
+"mode hook", which is the value of a Lisp variable.  For example,
+turning on C mode calls the value of the variable `c-mode-hook' if that
+value exists and is non-`nil'.  Mode hook variables for other
+programming language modes include `lisp-mode-hook',
+`emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
+`scheme-mode-hook', and `muddle-mode-hook'.  The mode hook function
+receives no arguments.
+
+\1f
+File: xemacs.info,  Node: Lists,  Next: Defuns,  Prev: Program Modes,  Up: Programs
+
+Lists and Sexps
+===============
+
+By convention, Emacs keys for dealing with balanced expressions are
+usually `Control-Meta-' characters.  They tend to be analogous in
+function to their `Control-' and `Meta-' equivalents.  These commands
+are usually thought of as pertaining to expressions in programming
+languages, but can be useful with any language in which some sort of
+parentheses exist (including English).
+
+   The commands fall into two classes.  Some commands deal only with
+"lists" (parenthetical groupings).  They see nothing except
+parentheses, brackets, braces (depending on what must balance in the
+language you are working with), and escape characters that might be used
+to quote those.
+
+   The other commands deal with expressions or "sexps".  The word `sexp'
+is derived from "s-expression", the term for a symbolic expression in
+Lisp.  In Emacs, the notion of `sexp' is not limited to Lisp.  It
+refers to an expression in the language  your program is written in.
+Each programming language has its own major mode, which customizes the
+syntax tables so that expressions in that language count as sexps.
+
+   Sexps typically include symbols, numbers, and string constants, as
+well as anything contained in parentheses, brackets, or braces.
+
+   In languages that use prefix and infix operators, such as C, it is
+not possible for all expressions to be sexps.  For example, C mode does
+not recognize `foo + bar' as an sexp, even though it is a C expression;
+it recognizes `foo' as one sexp and `bar' as another, with the `+' as
+punctuation between them.  This is a fundamental ambiguity: both `foo +
+bar' and `foo' are legitimate choices for the sexp to move over if
+point is at the `f'.  Note that `(foo + bar)' is a sexp in C mode.
+
+   Some languages have obscure forms of syntax for expressions that
+nobody has bothered to make Emacs understand properly.
+
+`C-M-f'
+     Move forward over an sexp (`forward-sexp').
+
+`C-M-b'
+     Move backward over an sexp (`backward-sexp').
+
+`C-M-k'
+     Kill sexp forward (`kill-sexp').
+
+`C-M-u'
+     Move up and backward in list structure (`backward-up-list').
+
+`C-M-d'
+     Move down and forward in list structure (`down-list').
+
+`C-M-n'
+     Move forward over a list (`forward-list').
+
+`C-M-p'
+     Move backward over a list (`backward-list').
+
+`C-M-t'
+     Transpose expressions (`transpose-sexps').
+
+`C-M-@'
+     Put mark after following expression (`mark-sexp').
+
+   To move forward over an sexp, use `C-M-f' (`forward-sexp').  If the
+first significant character after point is an opening delimiter (`(' in
+Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
+delimiter.  If the character begins a symbol, string, or number,
+`C-M-f' moves over that.  If the character after point is a closing
+delimiter, `C-M-f' just moves past it.  (This last is not really moving
+across an sexp; it is an exception which is included in the definition
+of `C-M-f' because it is as useful a behavior as anyone can think of
+for that situation.)
+
+   The command `C-M-b' (`backward-sexp') moves backward over a sexp.
+The detailed rules are like those above for `C-M-f', but with
+directions reversed.  If there are any prefix characters (single quote,
+back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
+over them as well.
+
+   `C-M-f' or `C-M-b' with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
+
+   In languages such as C where the comment-terminator can be
+recognized, the sexp commands move across comments as if they were
+whitespace.  In Lisp and other languages where comments run until the
+end of a line, it is very difficult to ignore comments when parsing
+backwards; therefore, in such languages the sexp commands treat the
+text of comments as if it were code.
+
+   Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
+`C-M-k' kills the characters that `C-M-f' would move over.
+
+   The "list commands", `C-M-n' (`forward-list') and `C-M-p'
+(`backward-list'), move over lists like the sexp commands but skip over
+any number of other kinds of sexps (symbols, strings, etc).  In some
+situations, these commands are useful because they usually ignore
+comments, since the comments usually do not contain any lists.
+
+   `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
+is possible.  To move up one (or N) levels, use `C-M-u'
+(`backward-up-list').  `C-M-u' moves backward up past one unmatched
+opening delimiter.  A positive argument serves as a repeat count; a
+negative argument reverses direction of motion and also requests
+repetition, so it moves forward and up one or more levels.
+
+   To move down in list structure, use `C-M-d' (`down-list').  In Lisp
+mode, where `(' is the only opening delimiter, this is nearly the same
+as searching for a `('.  An argument specifies the number of levels of
+parentheses to go down.
+
+   `C-M-t' (`transpose-sexps') drags the previous sexp across the next
+one.  An argument serves as a repeat count, and a negative argument
+drags backwards (thus canceling out the effect of `C-M-t' with a
+positive argument).  An argument of zero, rather than doing nothing,
+transposes the sexps ending after point and the mark.
+
+   To make the region be the next sexp in the buffer, use `C-M-@'
+(`mark-sexp') which sets the mark at the same place that `C-M-f' would
+move to.  `C-M-@' takes arguments like `C-M-f'.  In particular, a
+negative argument is useful for putting the mark at the beginning of
+the previous sexp.
+
+   The list and sexp commands' understanding of syntax is completely
+controlled by the syntax table.  Any character can, for example, be
+declared to be an opening delimiter and act like an open parenthesis.
+*Note Syntax::.
+
+\1f
+File: xemacs.info,  Node: Defuns,  Next: Grinding,  Prev: Lists,  Up: Programs
+
+Defuns
+======
+
+In Emacs, a parenthetical grouping at the top level in the buffer is
+called a "defun".  The name derives from the fact that most top-level
+lists in Lisp are instances of the special form `defun', but Emacs
+calls any top-level parenthetical grouping counts a defun regardless of
+its contents or the programming language.  For example, in C, the body
+of a function definition is a defun.
+
+`C-M-a'
+     Move to beginning of current or preceding defun
+     (`beginning-of-defun').
+
+`C-M-e'
+     Move to end of current or following defun (`end-of-defun').
+
+`C-M-h'
+     Put region around whole current or following defun (`mark-defun').
+
+   The commands to move to the beginning and end of the current defun
+are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
+
+   To operate on the current defun, use `C-M-h' (`mark-defun') which
+puts point at the beginning and the mark at the end of the current or
+next defun.  This is the easiest way to prepare for moving the defun to
+a different place.  In C mode, `C-M-h' runs the function
+`mark-c-function', which is almost the same as `mark-defun', but which
+backs up over the argument declarations, function name, and returned
+data type so that the entire C function is inside the region.
+
+   To compile and evaluate the current defun, use `M-x compile-defun'.
+This function prints the results in the minibuffer. If you include an
+argument, it inserts the value in the current buffer after the defun.
+
+   Emacs assumes that any open-parenthesis found in the leftmost column
+is the start of a defun.  Therefore, never put an open-parenthesis at
+the left margin in a Lisp file unless it is the start of a top level
+list.  Never put an open-brace or other opening delimiter at the
+beginning of a line of C code unless it starts the body of a function.
+The most likely problem case is when you want an opening delimiter at
+the start of a line inside a string.  To avoid trouble, put an escape
+character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
+before the opening delimiter.  It will not affect the contents of the
+string.
+
+   The original Emacs found defuns by moving upward a level of
+parentheses until there were no more levels to go up.  This required
+scanning back to the beginning of the buffer for every function.  To
+speed this up, Emacs was changed to assume that any `(' (or other
+character assigned the syntactic class of opening-delimiter) at the
+left margin is the start of a defun.  This heuristic is nearly always
+right; however, it mandates the convention described above.
+
+\1f
+File: xemacs.info,  Node: Grinding,  Next: Matching,  Prev: Defuns,  Up: Programs
+
+Indentation for Programs
+========================
+
+The best way to keep a program properly indented ("ground") is to use
+Emacs to re-indent it as you change the program.  Emacs has commands to
+indent properly either a single line, a specified number of lines, or
+all of the lines inside a single parenthetical grouping.
+
+* Menu:
+
+* Basic Indent::
+* Multi-line Indent::   Commands to reindent many lines at once.
+* Lisp Indent::                Specifying how each Lisp function should be indented.
+* C Indent::           Choosing an indentation style for C code.
+
+\1f
+File: xemacs.info,  Node: Basic Indent,  Next: Multi-line Indent,  Prev: Grinding,  Up: Grinding
+
+Basic Program Indentation Commands
+----------------------------------
+
+`<TAB>'
+     Adjust indentation of current line.
+
+`<LFD>'
+     Equivalent to <RET> followed by <TAB> (`newline-and-indent').
+
+   The basic indentation command is <TAB>, which gives the current line
+the correct indentation as determined from the previous lines.  The
+function that <TAB> runs depends on the major mode; it is
+`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc.  These
+functions understand different syntaxes for different languages, but
+they all do about the same thing.  <TAB> in any programming language
+major mode inserts or deletes whitespace at the beginning of the
+current line, independent of where point is in the line.  If point is
+inside the whitespace at the beginning of the line, <TAB> leaves it at
+the end of that whitespace; otherwise, <TAB> leaves point fixed with
+respect to the characters around it.
+
+   Use `C-q <TAB>' to insert a tab at point.
+
+   When entering a large amount of new code, use <LFD>
+(`newline-and-indent'), which is equivalent to a <RET> followed by a
+<TAB>.  <LFD> creates a blank line, then gives it the appropriate
+indentation.
+
+   <TAB> indents the second and following lines of the body of a
+parenthetical grouping each under the preceding one; therefore, if you
+alter one line's indentation to be nonstandard, the lines below tend to
+follow it.  This is the right behavior in cases where the standard
+result of <TAB> does not look good.
+
+   Remember that Emacs assumes that an open-parenthesis, open-brace, or
+other opening delimiter at the left margin (including the indentation
+routines) is the start of a function.  You should therefore never have
+an opening delimiter in column zero that is not the beginning of a
+function, not even inside a string.  This restriction is vital for
+making the indentation commands fast. *Note Defuns::, for more
+information on this behavior.
+
+\1f
+File: xemacs.info,  Node: Multi-line Indent,  Next: Lisp Indent,  Prev: Basic Indent,  Up: Grinding
+
+Indenting Several Lines
+-----------------------
+
+Several commands are available to re-indent several lines of code which
+have been altered or moved to a different level in a list structure.
+
+`C-M-q'
+     Re-indent all the lines within one list (`indent-sexp').
+
+`C-u <TAB>'
+     Shift an entire list rigidly sideways so that its first line is
+     properly indented.
+
+`C-M-\'
+     Re-indent all lines in the region (`indent-region').
+
+   To re-indent the contents of a single list, position point before the
+beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
+Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
+functions in other modes.  The indentation of the line the sexp starts
+on is not changed; therefore, only the relative indentation within the
+list, and not its position, is changed.  To correct the position as
+well, type a <TAB> before `C-M-q'.
+
+   If the relative indentation within a list is correct but the
+indentation of its beginning is not, go to the line on which the list
+begins and type `C-u <TAB>'.  When you give <TAB> a numeric argument,
+it moves all the lines in the group, starting on the current line,
+sideways the same amount that the current line moves.  The command does
+not move lines that start inside strings, or C preprocessor lines when
+in C mode.
+
+   Another way to specify a range to be re-indented is with point and
+mark.  The command `C-M-\' (`indent-region') applies <TAB> to every
+line whose first character is between point and mark.
+
+\1f
+File: xemacs.info,  Node: Lisp Indent,  Next: C Indent,  Prev: Multi-line Indent,  Up: Grinding
+
+Customizing Lisp Indentation
+----------------------------
+
+The indentation pattern for a Lisp expression can depend on the function
+called by the expression.  For each Lisp function, you can choose among
+several predefined patterns of indentation, or define an arbitrary one
+with a Lisp program.
+
+   The standard pattern of indentation is as follows: the second line
+of the expression is indented under the first argument, if that is on
+the same line as the beginning of the expression; otherwise, the second
+line is indented underneath the function name.  Each following line is
+indented under the previous line whose nesting depth is the same.
+
+   If the variable `lisp-indent-offset' is non-`nil', it overrides the
+usual indentation pattern for the second line of an expression, so that
+such lines are always indented `lisp-indent-offset' more columns than
+the containing list.
+
+   Certain functions override the standard pattern.  Functions whose
+names start with `def' always indent the second line by
+`lisp-body-indention' extra columns beyond the open-parenthesis
+starting the expression.
+
+   Individual functions can override the standard pattern in various
+ways, according to the `lisp-indent-function' property of the function
+name.  (Note: `lisp-indent-function' was formerly called
+`lisp-indent-hook').  There are four possibilities for this property:
+
+`nil'
+     This is the same as no property; the standard indentation pattern
+     is used.
+
+`defun'
+     The pattern used for function names that start with `def' is used
+     for this function also.
+
+a number, NUMBER
+     The first NUMBER arguments of the function are "distinguished"
+     arguments; the rest are considered the "body" of the expression.
+     A line in the expression is indented according to whether the
+     first argument on it is distinguished or not.  If the argument is
+     part of the body, the line is indented `lisp-body-indent' more
+     columns than the open-parenthesis starting the containing
+     expression.  If the argument is distinguished and is either the
+     first or second argument, it is indented twice that many extra
+     columns.  If the argument is distinguished and not the first or
+     second argument, the standard pattern is followed for that line.
+
+a symbol, SYMBOL
+     SYMBOL should be a function name; that function is called to
+     calculate the indentation of a line within this expression.  The
+     function receives two arguments:
+    STATE
+          The value returned by `parse-partial-sexp' (a Lisp primitive
+          for indentation and nesting computation) when it parses up to
+          the beginning of this line.
+
+    POS
+          The position at which the line being indented begins.
+
+     It should return either a number, which is the number of columns of
+     indentation for that line, or a list whose first element is such a
+     number.  The difference between returning a number and returning a
+     list is that a number says that all following lines at the same
+     nesting level should be indented just like this one; a list says
+     that following lines might call for different indentations.  This
+     makes a difference when the indentation is computed by `C-M-q'; if
+     the value is a number, `C-M-q' need not recalculate indentation
+     for the following lines until the end of the list.
+
+\1f
+File: xemacs.info,  Node: C Indent,  Prev: Lisp Indent,  Up: Grinding
+
+Customizing C Indentation
+-------------------------
+
+Two variables control which commands perform C indentation and when.
+
+   If `c-auto-newline' is non-`nil', newlines are inserted both before
+and after braces that you insert and after colons and semicolons.
+Correct C indentation is done on all the lines that are made this way.
+
+   If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
+does indentation only if point is at the left margin or within the
+line's indentation.  If there is non-whitespace to the left of point,
+<TAB> just inserts a tab character in the buffer.  Normally, this
+variable is `nil', and <TAB> always reindents the current line.
+
+   C does not have anything analogous to particular function names for
+which special forms of indentation are desirable.  However, it has a
+different need for customization facilities: many different styles of C
+indentation are in common use.
+
+   There are six variables you can set to control the style that Emacs C
+mode will use.
+
+`c-indent-level'
+     Indentation of C statements within surrounding block.  The
+     surrounding block's indentation is the indentation of the line on
+     which the open-brace appears.
+
+`c-continued-statement-offset'
+     Extra indentation given to a substatement, such as the then-clause
+     of an `if' or body of a `while'.
+
+`c-brace-offset'
+     Extra indentation for lines that start with an open brace.
+
+`c-brace-imaginary-offset'
+     An open brace following other text is treated as if it were this
+     far to the right of the start of its line.
+
+`c-argdecl-indent'
+     Indentation level of declarations of C function arguments.
+
+`c-label-offset'
+     Extra indentation for a line that is a label, case, or default.
+
+   The variable `c-indent-level' controls the indentation for C
+statements with respect to the surrounding block.  In the example:
+
+         {
+           foo ();
+
+the difference in indentation between the lines is `c-indent-level'.
+Its standard value is 2.
+
+   If the open-brace beginning the compound statement is not at the
+beginning of its line, the `c-indent-level' is added to the indentation
+of the line, not the column of the open-brace.  For example,
+
+     if (losing) {
+       do_this ();
+
+One popular indentation style is that which results from setting
+`c-indent-level' to 8 and putting open-braces at the end of a line in
+this way.  Another popular style prefers to put the open-brace on a
+separate line.
+
+   In fact, the value of the variable `c-brace-imaginary-offset' is
+also added to the indentation of such a statement.  Normally this
+variable is zero.  Think of this variable as the imaginary position of
+the open brace, relative to the first non-blank character on the line.
+By setting the variable to 4 and `c-indent-level' to 0, you can get
+this style:
+
+     if (x == y) {
+         do_it ();
+         }
+
+   When `c-indent-level' is zero, the statements inside most braces
+line up exactly under the open brace.  An exception are braces in column
+zero, like those surrounding a function's body.  The statements inside
+those braces are not placed at column zero.  Instead, `c-brace-offset'
+and `c-continued-statement-offset' (see below) are added to produce a
+typical offset between brace levels, and the statements are indented
+that far.
+
+   `c-continued-statement-offset' controls the extra indentation for a
+line that starts within a statement (but not within parentheses or
+brackets).  These lines are usually statements inside other statements,
+like the then-clauses of `if' statements and the bodies of `while'
+statements.  The `c-continued-statement-offset' parameter determines
+the difference in indentation between the two lines in:
+
+     if (x == y)
+       do_it ();
+
+The default value for `c-continued-statement-offset' is 2.  Some
+popular indentation styles correspond to a value of zero for
+`c-continued-statement-offset'.
+
+   `c-brace-offset' is the extra indentation given to a line that
+starts with an open-brace.  Its standard value is zero; compare:
+
+     if (x == y)
+       {
+
+with:
+
+     if (x == y)
+       do_it ();
+
+If you set `c-brace-offset' to 4, the first example becomes:
+
+     if (x == y)
+           {
+
+   `c-argdecl-indent' controls the indentation of declarations of the
+arguments of a C function.  It is absolute: argument declarations
+receive exactly `c-argdecl-indent' spaces.  The standard value is 5 and
+results in code like this:
+
+     char *
+     index (string, char)
+          char *string;
+          int char;
+
+   `c-label-offset' is the extra indentation given to a line that
+contains a label, a case statement, or a `default:' statement.  Its
+standard value is -2 and results in code like this:
+
+     switch (c)
+       {
+       case 'x':
+
+If `c-label-offset' were zero, the same code would be indented as:
+
+     switch (c)
+       {
+         case 'x':
+
+This example assumes that the other variables above also have their
+default values.
+
+   Using the indentation style produced by the default settings of the
+variables just discussed and putting open braces on separate lines
+produces clear and readable files.  For an example, look at any of the C
+source files of XEmacs.
+
+\1f
+File: xemacs.info,  Node: Matching,  Next: Comments,  Prev: Grinding,  Up: Programs
+
+Automatic Display of Matching Parentheses
+=========================================
+
+The Emacs parenthesis-matching feature shows you automatically how
+parentheses match in the text.  Whenever a self-inserting character that
+is a closing delimiter is typed, the cursor moves momentarily to the
+location of the matching opening delimiter, provided that is visible on
+the screen.  If it is not on the screen, some text starting with that
+opening delimiter is displayed in the echo area.  Either way, you see
+the grouping you are closing off.
+
+   In Lisp, automatic matching applies only to parentheses.  In C, it
+also applies to braces and brackets.  Emacs knows which characters to
+regard as matching delimiters based on the syntax table set by the major
+mode.  *Note Syntax::.
+
+   If the opening delimiter and closing delimiter are mismatched--as in
+`[x)'--the echo area displays a warning message.  The correct matches
+are specified in the syntax table.
+
+   Two variables control parenthesis matching displays.
+`blink-matching-paren' turns the feature on or off. The default is `t'
+(match display is on); `nil' turns it off.
+`blink-matching-paren-distance' specifies how many characters back
+Emacs searches to find a matching opening delimiter.  If the match is
+not found in the specified region, scanning stops, and nothing is
+displayed.  This prevents wasting lots of time scanning when there is no
+match.  The default is 4000.
+
+\1f
+File: xemacs.info,  Node: Comments,  Next: Balanced Editing,  Prev: Matching,  Up: Programs
+
+Manipulating Comments
+=====================
+
+The comment commands insert, kill and align comments.
+
+`M-;'
+     Insert or align comment (`indent-for-comment').
+
+`C-x ;'
+     Set comment column (`set-comment-column').
+
+`C-u - C-x ;'
+     Kill comment on current line (`kill-comment').
+
+`M-<LFD>'
+     Like <RET> followed by inserting and aligning a comment
+     (`indent-new-comment-line').
+
+   The command that creates a comment is `Meta-;'
+(`indent-for-comment').  If there is no comment already on the line, a
+new comment is created and aligned at a specific column called the
+"comment column".  Emacs creates the comment by inserting the string at
+the value of `comment-start'; see below.  Point is left after that
+string.  If the text of the line extends past the comment column,
+indentation is done to a suitable boundary (usually, at least one space
+is inserted).  If the major mode has specified a string to terminate
+comments, that string is inserted after point, to keep the syntax valid.
+
+   You can also use `Meta-;' to align an existing comment.  If a line
+already contains the string that starts comments, `M-;' just moves
+point after it and re-indents it to the conventional place.  Exception:
+comments starting in column 0 are not moved.
+
+   Some major modes have special rules for indenting certain kinds of
+comments in certain contexts.  For example, in Lisp code, comments which
+start with two semicolons are indented as if they were lines of code,
+instead of at the comment column.  Comments which start with three
+semicolons are supposed to start at the left margin.  Emacs understands
+these conventions by indenting a double-semicolon comment using <TAB>
+and by not changing the indentation of a triple-semicolon comment at
+all.
+
+     ;; This function is just an example.
+     ;;; Here either two or three semicolons are appropriate.
+     (defun foo (x)
+     ;;; And now, the first part of the function:
+       ;; The following line adds one.
+       (1+ x))           ; This line adds one.
+
+   In C code, a comment preceded on its line by nothing but whitespace
+is indented like a line of code.
+
+   Even when an existing comment is properly aligned, `M-;' is still
+useful for moving directly to the start of the comment.
+
+   `C-u - C-x ;' (`kill-comment') kills the comment on the current
+line, if there is one.  The indentation before the start of the comment
+is killed as well.  If there does not appear to be a comment in the
+line, nothing happens.  To reinsert the comment on another line, move
+to the end of that line, type first `C-y', and then `M-;' to realign
+the comment.  Note that `C-u - C-x ;' is not a distinct key; it is `C-x
+;' (`set-comment-column') with a negative argument.  That command is
+programmed to call `kill-comment' when called with a negative argument.
+However, `kill-comment' is a valid command which you could bind
+directly to a key if you wanted to.
+
+Multiple Lines of Comments
+--------------------------
+
+If you are typing a comment and want to continue it on another line,
+use the command `Meta-<LFD>' (`indent-new-comment-line'), which
+terminates the comment you are typing, creates a new blank line
+afterward, and begins a new comment indented under the old one.  If
+Auto Fill mode is on and you go past the fill column while typing, the
+comment is continued in just this fashion.  If point is not at the end
+of the line when you type `M-<LFD>', the text on the rest of the line
+becomes part of the new comment line.
+
+Options Controlling Comments
+----------------------------
+
+The comment column is stored in the variable `comment-column'.  You can
+explicitly set it to a number.  Alternatively, the command `C-x ;'
+(`set-comment-column') sets the comment column to the column point is
+at.  `C-u C-x ;' sets the comment column to match the last comment
+before point in the buffer, and then calls `Meta-;' to align the
+current line's comment under the previous one.  Note that `C-u - C-x ;'
+runs the function `kill-comment' as described above.
+
+   `comment-column' is a per-buffer variable; altering the variable
+affects only the current buffer.  You can also change the default value.
+*Note Locals::.  Many major modes initialize this variable for the
+current buffer.
+
+   The comment commands recognize comments based on the regular
+expression that is the value of the variable `comment-start-skip'.
+This regexp should not match the null string.  It may match more than
+the comment starting delimiter in the strictest sense of the word; for
+example, in C mode the value of the variable is `"/\\*+ *"', which
+matches extra stars and spaces after the `/*' itself.  (Note that `\\'
+is needed in Lisp syntax to include a `\' in the string, which is needed
+to deny the first star its special meaning in regexp syntax.  *Note
+Regexps::.)
+
+   When a comment command makes a new comment, it inserts the value of
+`comment-start' to begin it.  The value of `comment-end' is inserted
+after point and will follow the text you will insert into the comment.
+In C mode, `comment-start' has the value `"/* "' and `comment-end' has
+the value `" */"'.
+
+   `comment-multi-line' controls how `M-<LFD>'
+(`indent-new-comment-line') behaves when used inside a comment.  If
+`comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
+terminates the comment on the starting line and starts a new comment on
+the new following line.  If `comment-multi-line' is not `nil', then
+`M-<LFD>' sets up the new following line as part of the same comment
+that was found on the starting line.  This is done by not inserting a
+terminator on the old line and not inserting a starter on the new line.
+In languages where multi-line comments are legal, the value you choose
+for this variable is a matter of taste.
+
+   The variable `comment-indent-hook' should contain a function that is
+called to compute the indentation for a newly inserted comment or for
+aligning an existing comment.  Major modes set this variable
+differently.  The function is called with no arguments, but with point
+at the beginning of the comment, or at the end of a line if a new
+comment is to be inserted.  The function should return the column in
+which the comment ought to start.  For example, in Lisp mode, the
+indent hook function bases its decision on the number of semicolons
+that begin an existing comment and on the code in the preceding lines.
+
+\1f
+File: xemacs.info,  Node: Balanced Editing,  Next: Lisp Completion,  Prev: Comments,  Up: Programs
+
+Editing Without Unbalanced Parentheses
+======================================
+
+`M-('
+     Put parentheses around next sexp(s) (`insert-parentheses').
+
+`M-)'
+     Move past next close parenthesis and re-indent
+     (`move-over-close-and-reindent').
+
+   The commands `M-(' (`insert-parentheses') and `M-)'
+(`move-over-close-and-reindent') are designed to facilitate a style of
+editing which keeps parentheses balanced at all times.  `M-(' inserts a
+pair of parentheses, either together as in `()', or, if given an
+argument, around the next several sexps, and leaves point after the open
+parenthesis.  Instead of typing `( F O O )', you can type `M-( F O O',
+which has the same effect except for leaving the cursor before the
+close parenthesis.  You can then type `M-)', which moves past the close
+parenthesis, deletes any indentation preceding it (in this example
+there is none), and indents with <LFD> after it.
+
+\1f
+File: xemacs.info,  Node: Lisp Completion,  Next: Documentation,  Prev: Balanced Editing,  Up: Programs
+
+Completion for Lisp Symbols
+===========================
+
+Completion usually happens in the minibuffer.  An exception is
+completion for Lisp symbol names, which is available in all buffers.
+
+   The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
+Lisp symbol before point to be an abbreviation, and compares it against
+all non-trivial Lisp symbols currently known to Emacs.  Any additional
+characters that they all have in common are inserted at point.
+Non-trivial symbols are those that have function definitions, values, or
+properties.
+
+   If there is an open-parenthesis immediately before the beginning of
+the partial symbol, only symbols with function definitions are
+considered as completions.
+
+   If the partial name in the buffer has more than one possible
+completion and they have no additional characters in common, a list of
+all possible completions is displayed in another window.
+
+\1f
+File: xemacs.info,  Node: Documentation,  Next: Change Log,  Prev: Lisp Completion,  Up: Programs
+
+Documentation Commands
+======================
+
+As you edit Lisp code to be run in Emacs, you can use the commands `C-h
+f' (`describe-function') and `C-h v' (`describe-variable') to print
+documentation of functions and variables you want to call.  These
+commands use the minibuffer to read the name of a function or variable
+to document, and display the documentation in a window.
+
+   For extra convenience, these commands provide default arguments
+based on the code in the neighborhood of point.  `C-h f' sets the
+default to the function called in the innermost list containing point.
+`C-h v' uses the symbol name around or adjacent to point as its default.
+
+   The `M-x manual-entry' command gives you access to documentation on
+Unix commands, system calls, and libraries.  The command reads a topic
+as an argument, and displays the Unix manual page for that topic.
+`manual-entry' always searches all 8 sections of the manual and
+concatenates all the entries it finds.  For example, the topic
+`termcap' finds the description of the termcap library from section 3,
+followed by the description of the termcap data base from section 5.
+
+\1f
+File: xemacs.info,  Node: Change Log,  Next: Tags,  Prev: Documentation,  Up: Programs
+
+Change Logs
+===========
+
+The Emacs command `M-x add-change-log-entry' helps you keep a record of
+when and why you have changed a program.  It assumes that you have a
+file in which you write a chronological sequence of entries describing
+individual changes.  The default is to store the change entries in a
+file called `ChangeLog' in the same directory as the file you are
+editing.  The same `ChangeLog' file therefore records changes for all
+the files in a directory.
+
+   A change log entry starts with a header line that contains your name
+and the current date.  Except for these header lines, every line in the
+change log starts with a tab.  One entry can describe several changes;
+each change starts with a line starting with a tab and a star.  `M-x
+add-change-log-entry' visits the change log file and creates a new entry
+unless the most recent entry is for today's date and your name.  In
+either case, it adds a new line to start the description of another
+change just after the header line of the entry.  When `M-x
+add-change-log-entry' is finished, all is prepared for you to edit in
+the description of what you changed and how.  You must then save the
+change log file yourself.
+
+   The change log file is always visited in Indented Text mode, which
+means that <LFD> and auto-filling indent each new line like the previous
+line.  This is convenient for entering the contents of an entry, which
+must be indented.  *Note Text Mode::.
+
+   Here is an example of the formatting conventions used in the change
+log for Emacs:
+
+     Wed Jun 26 19:29:32 1985  Richard M. Stallman  (rms at mit-prep)
+     
+             * xdisp.c (try_window_id):
+             If C-k is done at end of next-to-last line,
+             this fn updates window_end_vpos and cannot leave
+             window_end_pos nonnegative (it is zero, in fact).
+             If display is preempted before lines are output,
+             this is inconsistent.  Fix by setting
+             blank_end_of_window to nonzero.
+     
+     Tue Jun 25 05:25:33 1985  Richard M. Stallman  (rms at mit-prep)
+     
+             * cmds.c (Fnewline):
+             Call the auto fill hook if appropriate.
+     
+             * xdisp.c (try_window_id):
+             If point is found by compute_motion after xp, record that
+             permanently.  If display_text_line sets point position wrong
+             (case where line is killed, point is at eob and that line is
+             not displayed), set it again in final compute_motion.
+
+\1f
+File: xemacs.info,  Node: Tags,  Next: Fortran,  Prev: Change Log,  Up: Programs
+
+Tags Tables
+===========
+
+A "tags table" is a description of how a multi-file program is broken
+up into files.  It lists the names of the component files and the names
+and positions of the functions (or other named subunits) in each file.
+Grouping the related files makes it possible to search or replace
+through all the files with one command.  Recording the function names
+and positions makes possible the `M-.' command which finds the
+definition of a function by looking up which of the files it is in.
+
+   Tags tables are stored in files called "tags table files".  The
+conventional name for a tags table file is `TAGS'.
+
+   Each entry in the tags table records the name of one tag, the name
+of the file that the tag is defined in (implicitly), and the position
+in that file of the tag's definition.
+
+   Just what names from the described files are recorded in the tags
+table depends on the programming language of the described file.  They
+normally include all functions and subroutines, and may also include
+global variables, data types, and anything else convenient.  Each name
+recorded is called a "tag".
+
+   The Ebrowse is a separate facility tailored for C++, with tags and a
+class browser.  *Note Top: (ebrowse)Top.
+
+* Menu:
+
+* Tag Syntax::         Tag syntax for various types of code and text files.
+* Create Tags Table::  Creating a tags table with `etags'.
+* Etags Regexps::       Create arbitrary tags using regular expressions.
+* Select Tags Table::  How to visit a tags table.
+* Find Tag::           Commands to find the definition of a specific tag.
+* Tags Search::                Using a tags table for searching and replacing.
+* List Tags::          Listing and finding tags defined in a file.
+
+\1f
+File: xemacs.info,  Node: Tag Syntax,  Next: Create Tags Table,  Up: Tags
+
+Source File Tag Syntax
+----------------------
+
+Here is how tag syntax is defined for the most popular languages:
+
+   * In C code, any C function or typedef is a tag, and so are
+     definitions of `struct', `union' and `enum'.  You can tag function
+     declarations and external variables in addition to function
+     definitions by giving the `--declarations' option to `etags'.
+     `#define' macro definitions and `enum' constants are also tags,
+     unless you specify `--no-defines' when making the tags table.
+     Similarly, global variables are tags, unless you specify
+     `--no-globals'.  Use of `--no-globals' and `--no-defines' can make
+     the tags table file much smaller.
+
+   * In C++ code, in addition to all the tag constructs of C code,
+     member functions are also recognized, and optionally member
+     variables if you use the `--members' option.  Tags for variables
+     and functions in classes are named `CLASS::VARIABLE' and
+     `CLASS::FUNCTION'.  `operator' functions tags are named, for
+     example `operator+'.
+
+   * In Java code, tags include all the constructs recognized in C++,
+     plus the `interface', `extends' and `implements' constructs.  Tags
+     for variables and functions in classes are named `CLASS.VARIABLE'
+     and `CLASS.FUNCTION'.
+
+   * In LaTeX text, the argument of any of the commands `\chapter',
+     `\section', `\subsection', `\subsubsection', `\eqno', `\label',
+     `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
+     `\index', is a tag.
+
+     Other commands can make tags as well, if you specify them in the
+     environment variable `TEXTAGS' before invoking `etags'.  The value
+     of this environment variable should be a colon-separated list of
+     command names.  For example,
+
+          TEXTAGS="def:newcommand:newenvironment"
+          export TEXTAGS
+
+     specifies (using Bourne shell syntax) that the commands `\def',
+     `\newcommand' and `\newenvironment' also define tags.
+
+   * In Lisp code, any function defined with `defun', any variable
+     defined with `defvar' or `defconst', and in general the first
+     argument of any expression that starts with `(def' in column zero,
+     is a tag.
+
+   * In Scheme code, tags include anything defined with `def' or with a
+     construct whose name starts with `def'.  They also include
+     variables set with `set!' at top level in the file.
+
+   Several other languages are also supported:
+
+   * In Ada code, functions, procedures, packages, tasks, and types are
+     tags.  Use the `--packages-only' option to create tags for
+     packages only.
+
+     With Ada, it is possible to have the same name used for different
+     entity kinds (e.g. the same name for a procedure and a function).
+     Also, for things like packages, procedures and functions, there is
+     the spec (i.e. the interface) and the body (i.e. the
+     implementation).  To facilitate the choice to the user, a tag
+     value is appended with a qualifier:
+
+    function
+          `/f'
+
+    procedure
+          `/p'
+
+    package spec
+          `/s'
+
+    package body
+          `/b'
+
+    type
+          `/t'
+
+    task
+          `/k'
+
+     So, as an example, `M-x find-tag bidule/b' will go directly to the
+     body of the package BIDULE while `M-x find-tag bidule' will just
+     search for any tag BIDULE.
+
+   * In assembler code, labels appearing at the beginning of a line,
+     followed by a colon, are tags.
+
+   * In Bison or Yacc input files, each rule defines as a tag the
+     nonterminal it constructs.  The portions of the file that contain
+     C code are parsed as C code.
+
+   * In Cobol code, tags are paragraph names; that is, any word
+     starting in column 8 and followed by a period.
+
+   * In Erlang code, the tags are the functions, records, and macros
+     defined in the file.
+
+   * In Fortran code, functions, subroutines and blockdata are tags.
+
+   * In makefiles, targets are tags.
+
+   * In Objective C code, tags include Objective C definitions for
+     classes, class categories, methods, and protocols.
+
+   * In Pascal code, the tags are the functions and procedures defined
+     in the file.
+
+   * In Perl code, the tags are the procedures defined by the `sub',
+     `my' and `local' keywords.  Use `--globals' if you want to tag
+     global variables.
+
+   * In PostScript code, the tags are the functions.
+
+   * In Prolog code, a tag name appears at the left margin.
+
+   * In Python code, `def' or `class' at the beginning of a line
+     generate a tag.
+
+   You can also generate tags based on regexp matching (*note Etags
+Regexps::) to handle other formats and languages.
+
+\1f
+File: xemacs.info,  Node: Create Tags Table,  Next: Etags Regexps,  Prev: Tag Syntax,  Up: Tags
+
+Creating Tags Tables
+--------------------
+
+The `etags' program is used to create a tags table file.  It knows the
+syntax of several languages, as described in *Note Tag Syntax::.  Here
+is how to run `etags':
+
+     etags INPUTFILES...
+
+The `etags' program reads the specified files, and writes a tags table
+named `TAGS' in the current working directory.  You can intermix
+compressed and plain text source file names.  `etags' knows about the
+most common compression formats, and does the right thing.  So you can
+compress all your source files and have `etags' look for compressed
+versions of its file name arguments, if it does not find uncompressed
+versions.  Under MS-DOS, `etags' also looks for file names like
+`mycode.cgz' if it is given `mycode.c' on the command line and
+`mycode.c' does not exist.
+
+   `etags' recognizes the language used in an input file based on its
+file name and contents.  You can specify the language with the
+`--language=NAME' option, described below.
+
+   If the tags table data become outdated due to changes in the files
+described in the table, the way to update the tags table is the same
+way it was made in the first place.  It is not necessary to do this
+often.
+
+   If the tags table fails to record a tag, or records it for the wrong
+file, then Emacs cannot possibly find its definition.  However, if the
+position recorded in the tags table becomes a little bit wrong (due to
+some editing in the file that the tag definition is in), the only
+consequence is a slight delay in finding the tag.  Even if the stored
+position is very wrong, Emacs will still find the tag, but it must
+search the entire file for it.
+
+   So you should update a tags table when you define new tags that you
+want to have listed, or when you move tag definitions from one file to
+another, or when changes become substantial.  Normally there is no need
+to update the tags table after each edit, or even every day.
+
+   One tags table can effectively include another.  Specify the included
+tags file name with the `--include=FILE' option when creating the file
+that is to include it.  The latter file then acts as if it contained
+all the files specified in the included file, as well as the files it
+directly contains.
+
+   If you specify the source files with relative file names when you run
+`etags', the tags file will contain file names relative to the
+directory where the tags file was initially written.  This way, you can
+move an entire directory tree containing both the tags file and the
+source files, and the tags file will still refer correctly to the source
+files.
+
+   If you specify absolute file names as arguments to `etags', then the
+tags file will contain absolute file names.  This way, the tags file
+will still refer to the same files even if you move it, as long as the
+source files remain in the same place.  Absolute file names start with
+`/', or with `DEVICE:/' on MS-DOS and MS-Windows.
+
+   When you want to make a tags table from a great number of files, you
+may have problems listing them on the command line, because some systems
+have a limit on its length.  The simplest way to circumvent this limit
+is to tell `etags' to read the file names from its standard input, by
+typing a dash in place of the file names, like this:
+
+     find . -name "*.[chCH]" -print | etags -
+
+   Use the option `--language=NAME' to specify the language explicitly.
+You can intermix these options with file names; each one applies to
+the file names that follow it.  Specify `--language=auto' to tell
+`etags' to resume guessing the language from the file names and file
+contents.  Specify `--language=none' to turn off language-specific
+processing entirely; then `etags' recognizes tags by regexp matching
+alone (*note Etags Regexps::).
+
+   `etags --help' prints the list of the languages `etags' knows, and
+the file name rules for guessing the language. It also prints a list of
+all the available `etags' options, together with a short explanation.
+
+\1f
+File: xemacs.info,  Node: Etags Regexps,  Next: Select Tags Table,  Prev: Create Tags Table,  Up: Tags
+
+Etags Regexps
+-------------
+
+The `--regex' option provides a general way of recognizing tags based
+on regexp matching.  You can freely intermix it with file names.  Each
+`--regex' option adds to the preceding ones, and applies only to the
+following files.  The syntax is:
+
+     --regex=/TAGREGEXP[/NAMEREGEXP]/
+
+where TAGREGEXP is used to match the lines to tag.  It is always
+anchored, that is, it behaves as if preceded by `^'.  If you want to
+account for indentation, just match any initial number of blanks by
+beginning your regular expression with `[ \t]*'.  In the regular
+expressions, `\' quotes the next character, and `\t' stands for the tab
+character.  Note that `etags' does not handle the other C escape
+sequences for special characters.
+
+   The syntax of regular expressions in `etags' is the same as in
+Emacs, augmented with the "interval operator", which works as in `grep'
+and `ed'.  The syntax of an interval operator is `\{M,N\}', and its
+meaning is to match the preceding expression at least M times and up to
+N times.
+
+   You should not match more characters with TAGREGEXP than that needed
+to recognize what you want to tag.  If the match is such that more
+characters than needed are unavoidably matched by TAGREGEXP (as will
+usually be the case), you should add a NAMEREGEXP, to pick out just the
+tag.  This will enable Emacs to find tags more accurately and to do
+completion on tag names more reliably.  You can find some examples
+below.
+
+   The option `--ignore-case-regex' (or `-c') is like `--regex', except
+that the regular expression provided will be matched without regard to
+case, which is appropriate for various programming languages.
+
+   The `-R' option deletes all the regexps defined with `--regex'
+options.  It applies to the file names following it, as you can see
+from the following example:
+
+     etags --regex=/REG1/ voo.doo --regex=/REG2/ \
+         bar.ber -R --lang=lisp los.er
+
+Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
+according to their contents.  `etags' also uses REG1 to recognize
+additional tags in `voo.doo', and both REG1 and REG2 to recognize
+additional tags in `bar.ber'.  `etags' uses the Lisp tags rules, and no
+regexp matching, to recognize tags in `los.er'.
+
+   A regular expression can be bound to a given language, by prepending
+it with `{lang}'.  When you do this, `etags' will use the regular
+expression only for files of that language.  `etags --help' prints the
+list of languages recognised by `etags'.  The following example tags
+the `DEFVAR' macros in the Emacs source files.  `etags' applies this
+regular expression to C files only:
+
+     --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+
+This feature is particularly useful when storing a list of regular
+expressions in a file.  The following option syntax instructs `etags'
+to read two files of regular expressions.  The regular expressions
+contained in the second file are matched without regard to case.
+
+     --regex=@first-file --ignore-case-regex=@second-file
+
+A regex file contains one regular expressions per line.  Empty lines,
+and lines beginning with space or tab are ignored.  When the first
+character in a line is `@', `etags' assumes that the rest of the line
+is the name of a file of regular expressions.  This means that such
+files can be nested.  All the other lines are taken to be regular
+expressions.  For example, one can create a file called `emacs.tags'
+with the following contents (the first line in the file is a comment):
+
+             -- This is for GNU Emacs source files
+     {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+
+and then use it like this:
+
+     etags --regex=@emacs.tags *.[ch] */*.[ch]
+
+   Here are some more examples.  The regexps are quoted to protect them
+from shell interpretation.
+
+   * Tag Octave files:
+
+          etags --language=none \
+                --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+                --regex='/###key \(.*\)/\1/' \
+                --regex='/[ \t]*global[ \t].*/' \
+                *.m
+
+     Note that tags are not generated for scripts so that you have to
+     add a line by yourself of the form `###key <script-name>' if you
+     want to jump to it.
+
+   * Tag Tcl files:
+
+          etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+
+   * Tag VHDL files:
+
+          --language=none \
+          --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+          --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+          \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+
+\1f
+File: xemacs.info,  Node: Select Tags Table,  Next: Find Tag,  Prev: Etags Regexps,  Up: Tags
+
+Selecting a Tags Table
+----------------------
+
+At any time Emacs has one "selected" tags table, and all the commands
+for working with tags tables use the selected one.  To select a tags
+table, use the variable `tag-table-alist'.
+
+   The value of `tag-table-alist' is a list that determines which
+`TAGS' files should be active for a given buffer.  This is not really
+an association list, in that all elements are checked.  The car of each
+element of this list is a pattern against which the buffers file name
+is compared; if it matches, then the cdr of the list should be the name
+of the tags table to use.  If more than one element of this list
+matches the buffers file name, all of the associated tags tables are
+used.  Earlier ones are searched first.
+
+   If the car of elements of this list are strings, they are treated as
+regular-expressions against which the file is compared (like the
+`auto-mode-alist').  If they are not strings, they are evaluated.  If
+they evaluate to non-`nil', the current buffer is considered to match.
+
+   If the cdr of the elements of this list are strings, they are
+assumed to name a tags file.  If they name a directory, the string
+`tags' is appended to them to get the file name.  If they are not
+strings, they are evaluated and must return an appropriate string.
+
+   For example:
+
+       (setq tag-table-alist
+             '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
+               ("\\.el$" . "/usr/local/emacs/src/")
+               ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
+               ("" . "/usr/local/emacs/src/")
+               ))
+
+   The example defines the tags table alist in the following way:
+
+   * Anything in the directory `/usr/src/public/perl/' should use the
+     `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'.
+
+   * Files ending in `.el' should use the `TAGS' file
+     `/usr/local/emacs/src/TAGS'.
+
+   * Anything in or below the directory `/jbw/gnu/' should use the
+     `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'.
+
+   If you had a file called `/usr/jbw/foo.el', it would use both `TAGS'
+files,
+`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in
+that order), because it matches both patterns.
+
+   If the buffer-local variable `buffer-tag-table' is set, it names a
+tags table that is searched before all others when `find-tag' is
+executed from this buffer.
+
+   If there is a file called `TAGS' in the same directory as the file
+in question, then that tags file will always be used as well (after the
+`buffer-tag-table' but before the tables specified by this list).
+
+   If the variable `tags-file-name' is set, the `TAGS' file it names
+will apply to all buffers (for backwards compatibility.)  It is searched
+first.
+
+   If the value of the variable `tags-always-build-completion-table' is
+`t', the tags file will always be added to the completion table without
+asking first, regardless of the size of the tags file.
+
+   The function `M-x visit-tags-table', is largely made obsolete by the
+variable `tag-table-alist', tells tags commands to use the tags table
+file FILE first.  The FILE should be the name of a file created with
+the `etags' program.  A directory name is also acceptable; it means the
+file `TAGS' in that directory.  The function only stores the file name
+you provide in the variable `tags-file-name'.  Emacs does not actually
+read in the tags table contents until you try to use them.  You can set
+the variable explicitly instead of using `visit-tags-table'.  The value
+of the variable `tags-file-name' is the name of the tags table used by
+all buffers.  This is for backward compatibility, and is largely
+supplanted by the variable `tag-table-alist'.
+
+\1f
+File: xemacs.info,  Node: Find Tag,  Next: Tags Search,  Prev: Select Tags Table,  Up: Tags
+
+Finding a Tag
+-------------
+
+The most important thing that a tags table enables you to do is to find
+the definition of a specific tag.
+
+`M-. TAG &OPTIONAL OTHER-WINDOW'
+     Find first definition of TAG (`find-tag').
+
+`C-u M-.'
+     Find next alternate definition of last tag specified.
+
+`C-x 4 . TAG'
+     Find first definition of TAG, but display it in another window
+     (`find-tag-other-window').
+
+   `M-.' (`find-tag') is the command to find the definition of a
+specified tag.  It searches through the tags table for that tag, as a
+string, then uses the tags table information to determine the file in
+which the definition is used and the approximate character position of
+the definition in the file.  Then `find-tag' visits the file, moves
+point to the approximate character position, and starts searching
+ever-increasing distances away for the text that should appear at the
+beginning of the definition.
+
+   If an empty argument is given (by typing <RET>), the sexp in the
+buffer before or around point is used as the name of the tag to find.
+*Note Lists::, for information on sexps.
+
+   The argument to `find-tag' need not be the whole tag name; it can be
+a substring of a tag name.  However, there can be many tag names
+containing the substring you specify.  Since `find-tag' works by
+searching the text of the tags table, it finds the first tag in the
+table that the specified substring appears in.  To find other tags that
+match the substring, give `find-tag' a numeric argument, as in `C-u
+M-.'.  This does not read a tag name, but continues searching the tag
+table's text for another tag containing the same substring last used.
+If your keyboard has a real <META> key, `M-0 M-.' is an easier
+alternative to `C-u M-.'.
+
+   If the optional second argument OTHER-WINDOW is non-`nil', it uses
+another window to display the tag.  Multiple active tags tables and
+completion are supported.
+
+   Variables of note include the following:
+
+`tag-table-alist'
+     Controls which tables apply to which buffers.
+
+`tags-file-name'
+     Stores a default tags table.
+
+`tags-build-completion-table'
+     Controls completion behavior.
+
+`buffer-tag-table'
+     Specifies a buffer-local table.
+
+`make-tags-files-invisible'
+     Sets whether tags tables should be very hidden.
+
+`tag-mark-stack-max'
+     Specifies how many tags-based hops to remember.
+
+   Like most commands that can switch buffers, `find-tag' has another
+similar command that displays the new buffer in another window.  `C-x 4
+.' invokes the function `find-tag-other-window'.  (This key sequence
+ends with a period.)
+
+   Emacs comes with a tags table file `TAGS' (in the directory
+containing Lisp libraries) that includes all the Lisp libraries and all
+the C sources of Emacs.  By specifying this file with `visit-tags-table'
+and then using `M-.' you can quickly look at the source of any Emacs
+function.
+
+\1f
+File: xemacs.info,  Node: Tags Search,  Next: List Tags,  Prev: Find Tag,  Up: Tags
+
+Searching and Replacing with Tags Tables
+----------------------------------------
+
+The commands in this section visit and search all the files listed in
+the selected tags table, one by one.  For these commands, the tags
+table serves only to specify a sequence of files to search.  A related
+command is `M-x grep' (*note Compilation::).
+
+`M-x tags-search <RET> REGEXP <RET>'
+     Search for REGEXP through the files in the selected tags table.
+
+`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
+     Perform a `query-replace-regexp' on each file in the selected tags
+     table.
+
+`M-,'
+     Restart one of the commands above, from the current location of
+     point (`tags-loop-continue').
+
+   `M-x tags-search' reads a regexp using the minibuffer, then searches
+for matches in all the files in the selected tags table, one file at a
+time.  It displays the name of the file being searched so you can
+follow its progress.  As soon as it finds an occurrence, `tags-search'
+returns.
+
+   Having found one match, you probably want to find all the rest.  To
+find one more match, type `M-,' (`tags-loop-continue') to resume the
+`tags-search'.  This searches the rest of the current buffer, followed
+by the remaining files of the tags table.
+
+   `M-x tags-query-replace' performs a single `query-replace-regexp'
+through all the files in the tags table.  It reads a regexp to search
+for and a string to replace with, just like ordinary `M-x
+query-replace-regexp'.  It searches much like `M-x tags-search', but
+repeatedly, processing matches according to your input.  *Note
+Replace::, for more information on query replace.
+
+   It is possible to get through all the files in the tags table with a
+single invocation of `M-x tags-query-replace'.  But often it is useful
+to exit temporarily, which you can do with any input event that has no
+special query replace meaning.  You can resume the query replace
+subsequently by typing `M-,'; this command resumes the last tags search
+or replace command that you did.
+
+   The commands in this section carry out much broader searches than the
+`find-tag' family.  The `find-tag' commands search only for definitions
+of tags that match your substring or regexp.  The commands
+`tags-search' and `tags-query-replace' find every occurrence of the
+regexp, as ordinary search commands and replace commands do in the
+current buffer.
+
+   These commands create buffers only temporarily for the files that
+they have to search (those which are not already visited in Emacs
+buffers).  Buffers in which no match is found are quickly killed; the
+others continue to exist.
+
+   It may have struck you that `tags-search' is a lot like `grep'.  You
+can also run `grep' itself as an inferior of Emacs and have Emacs show
+you the matching lines one by one.  This works much like running a
+compilation; finding the source locations of the `grep' matches works
+like finding the compilation errors.  *Note Compilation::.
+
+   If you wish to process all the files in a selected tags table, but
+`M-x tags-search' and `M-x tags-query-replace' are not giving you the
+desired result, you can use `M-x next-file'.
+
+`C-u M-x next-file'
+     With a numeric argument, regardless of its value, visit the first
+     file in the tags table and prepare to advance sequentially by
+     files.
+
+`M-x next-file'
+     Visit the next file in the selected tags table.
+
+\1f
+File: xemacs.info,  Node: List Tags,  Prev: Tags Search,  Up: Tags
+
+Tags Table Inquiries
+--------------------
+
+`M-x list-tags'
+     Display a list of the tags defined in a specific program file.
+
+`M-x tags-apropos'
+     Display a list of all tags matching a specified regexp.
+
+   `M-x list-tags' reads the name of one of the files described by the
+selected tags table, and displays a list of all the tags defined in that
+file.  The "file name" argument is really just a string to compare
+against the names recorded in the tags table; it is read as a string
+rather than a file name.  Therefore, completion and defaulting are not
+available, and you must enter the string the same way it appears in the
+tag table.  Do not include a directory as part of the file name unless
+the file name recorded in the tags table contains that directory.
+
+   `M-x tags-apropos' is like `apropos' for tags.  It reads a regexp,
+then finds all the tags in the selected tags table whose entries match
+that regexp, and displays the tag names found.
+
+\1f
+File: xemacs.info,  Node: Fortran,  Next: Asm Mode,  Prev: Tags,  Up: Programs
+
+Fortran Mode
+============
+
+Fortran mode provides special motion commands for Fortran statements and
+subprograms, and indentation commands that understand Fortran
+conventions of nesting, line numbers, and continuation statements.
+
+   Special commands for comments are provided because Fortran comments
+are unlike those of other languages.
+
+   Built-in abbrevs optionally save typing when you insert Fortran
+keywords.
+
+   Use `M-x fortran-mode' to switch to this major mode.  Doing so calls
+the value of `fortran-mode-hook' as a function of no arguments if that
+variable has a non-`nil' value.
+
+* Menu:
+
+* Motion: Fortran Motion.     Moving point by statements or subprograms.
+* Indent: Fortran Indent.     Indentation commands for Fortran.
+* Comments: Fortran Comments. Inserting and aligning comments.
+* Columns: Fortran Columns.   Measuring columns for valid Fortran.
+* Abbrev: Fortran Abbrev.     Built-in abbrevs for Fortran keywords.
+
+   Fortran mode was contributed by Michael Prange.
+
+\1f
+File: xemacs.info,  Node: Fortran Motion,  Next: Fortran Indent,  Prev: Fortran,  Up: Fortran
+
+Motion Commands
+---------------
+
+Fortran mode provides special commands to move by subprograms (functions
+and subroutines) and by statements.  There is also a command to put the
+region around one subprogram, which is convenient for killing it or
+moving it.
+
+`C-M-a'
+     Move to beginning of subprogram
+     (`beginning-of-fortran-subprogram').
+
+`C-M-e'
+     Move to end of subprogram (`end-of-fortran-subprogram').
+
+`C-M-h'
+     Put point at beginning of subprogram and mark at end
+     (`mark-fortran-subprogram').
+
+`C-c C-n'
+     Move to beginning of current or next statement (`fortran-next-
+     statement').
+
+`C-c C-p'
+     Move to beginning of current or previous statement (`fortran-
+     previous-statement').
+
+\1f
+File: xemacs.info,  Node: Fortran Indent,  Next: Fortran Comments,  Prev: Fortran Motion,  Up: Fortran
+
+Fortran Indentation
+-------------------
+
+Special commands and features are available for indenting Fortran code.
+They make sure various syntactic entities (line numbers, comment line
+indicators, and continuation line flags) appear in the columns that are
+required for standard Fortran.
+
+* Menu:
+
+* Commands: ForIndent Commands. Commands for indenting Fortran.
+* Numbers:  ForIndent Num.      How line numbers auto-indent.
+* Conv:     ForIndent Conv.     Conventions you must obey to avoid trouble.
+* Vars:     ForIndent Vars.     Variables controlling Fortran indent style.
+
+\1f
+File: xemacs.info,  Node: ForIndent Commands,  Next: ForIndent Num,  Prev: Fortran Indent,  Up: Fortran Indent
+
+Fortran Indentation Commands
+............................
+
+`<TAB>'
+     Indent the current line (`fortran-indent-line').
+
+`M-<LFD>'
+     Break the current line and set up a continuation line.
+
+`C-M-q'
+     Indent all the lines of the subprogram point is in
+     (`fortran-indent-subprogram').
+
+   <TAB> is redefined by Fortran mode to reindent the current line for
+Fortran (`fortran-indent-line').  Line numbers and continuation markers
+are indented to their required columns, and the body of the statement
+is independently indented, based on its nesting in the program.
+
+   The key `C-M-q' is redefined as `fortran-indent-subprogram', a
+command that reindents all the lines of the Fortran subprogram
+(function or subroutine) containing point.
+
+   The key `M-<LFD>' is redefined as `fortran-split-line', a command to
+split a line in the appropriate fashion for Fortran.  In a non-comment
+line, the second half becomes a continuation line and is indented
+accordingly.  In a comment line, both halves become separate comment
+lines.
+
+\1f
+File: xemacs.info,  Node: ForIndent Num,  Next: ForIndent Conv,  Prev: ForIndent Commands,  Up: Fortran Indent
+
+Line Numbers and Continuation
+.............................
+
+If a number is the first non-whitespace in the line, it is assumed to be
+a line number and is moved to columns 0 through 4.  (Columns are always
+counted from 0 in XEmacs.)  If the text on the line starts with the
+conventional Fortran continuation marker `$', it is moved to column 5.
+If the text begins with any non whitespace character in column 5, it is
+assumed to be an unconventional continuation marker and remains in
+column 5.
+
+   Line numbers of four digits or less are normally indented one space.
+This amount is controlled by the variable `fortran-line-number-indent',
+which is the maximum indentation a line number can have.  Line numbers
+are indented to right-justify them to end in column 4 unless that would
+require more than the maximum indentation.  The default value of the
+variable is 1.
+
+   Simply inserting a line number is enough to indent it according to
+these rules.  As each digit is inserted, the indentation is recomputed.
+To turn off this feature, set the variable
+`fortran-electric-line-number' to `nil'.  Then inserting line numbers
+is like inserting anything else.
+
+\1f
+File: xemacs.info,  Node: ForIndent Conv,  Next: ForIndent Vars,  Prev: ForIndent Num,  Up: Fortran Indent
+
+Syntactic Conventions
+.....................
+
+Fortran mode assumes that you follow certain conventions that simplify
+the task of understanding a Fortran program well enough to indent it
+properly:
+
+   * Two nested `do' loops never share a `continue' statement.
+
+   * The same character appears in column 5 of all continuation lines.
+     It is the value of the variable `fortran-continuation-char'.  By
+     default, this character is `$'.
+
+If you fail to follow these conventions, the indentation commands may
+indent some lines unaesthetically.  However, a correct Fortran program
+will retain its meaning when reindented even if the conventions are not
+followed.
+
+\1f
+File: xemacs.info,  Node: ForIndent Vars,  Prev: ForIndent Conv,  Up: Fortran Indent
+
+Variables for Fortran Indentation
+.................................
+
+Several additional variables control how Fortran indentation works.
+
+`fortran-do-indent'
+     Extra indentation within each level of `do' statement (the default
+     is 3).
+
+`fortran-if-indent'
+     Extra indentation within each level of `if' statement (the default
+     is 3).
+
+`fortran-continuation-indent'
+     Extra indentation for bodies of continuation lines (the default is
+     5).
+
+`fortran-check-all-num-for-matching-do'
+     If this is `nil', indentation assumes that each `do' statement
+     ends on a `continue' statement.  Therefore, when computing
+     indentation for a statement other than `continue', it can save
+     time by not checking for a `do' statement ending there.  If this
+     is non-`nil', indenting any numbered statement must check for a
+     `do' that ends there.  The default is `nil'.
+
+`fortran-minimum-statement-indent'
+     Minimum indentation for Fortran statements.  For standard Fortran,
+     this is 6.  Statement bodies are always indented at least this
+     much.
+
+\1f
+File: xemacs.info,  Node: Fortran Comments,  Next: Fortran Columns,  Prev: Fortran Indent,  Up: Fortran
+
+Comments
+--------
+
+The usual Emacs comment commands assume that a comment can follow a line
+of code.  In Fortran, the standard comment syntax requires an entire
+line to be just a comment.  Therefore, Fortran mode replaces the
+standard Emacs comment commands and defines some new variables.
+
+   Fortran mode can also handle a non-standard comment syntax where
+comments start with `!' and can follow other text.  Because only some
+Fortran compilers accept this syntax, Fortran mode will not insert such
+comments unless you have specified to do so in advance by setting the
+variable `comment-start' to `"!"' (*note Variables::).
+
+`M-;'
+     Align comment or insert new comment (`fortran-comment-indent').
+
+`C-x ;'
+     Applies to nonstandard `!' comments only.
+
+`C-c ;'
+     Turn all lines of the region into comments, or (with arg) turn
+     them back into real code (`fortran-comment-region').
+
+   `M-;' in Fortran mode is redefined as the command
+`fortran-comment-indent'.  Like the usual `M-;' command, it recognizes
+an existing comment and aligns its text appropriately.  If there is no
+existing comment, a comment is inserted and aligned.
+
+   Inserting and aligning comments is not the same in Fortran mode as in
+other modes.  When a new comment must be inserted, a full-line comment
+is inserted if the current line is blank.  On a non-blank line, a
+non-standard `!' comment is inserted if you previously specified you
+wanted to use them.  Otherwise a full-line comment is inserted on a new
+line before the current line.
+
+   Non-standard `!' comments are aligned like comments in other
+languages, but full-line comments are aligned differently.  In a
+standard full-line comment, the comment delimiter itself must always
+appear in column zero.  What can be aligned is the text within the
+comment.  You can choose from three styles of alignment by setting the
+variable `fortran-comment-indent-style' to one of these values:
+
+`fixed'
+     The text is aligned at a fixed column, which is the value of
+     `fortran-comment-line-column'.  This is the default.
+
+`relative'
+     The text is aligned as if it were a line of code, but with an
+     additional `fortran-comment-line-column' columns of indentation.
+
+`nil'
+     Text in full-line columns is not moved automatically.
+
+   You can also specify the character to be used to indent within
+full-line comments by setting the variable `fortran-comment-indent-char'
+to the character you want to use.
+
+   Fortran mode introduces two variables `comment-line-start' and
+`comment-line-start-skip', which do for full-line comments what
+`comment-start' and `comment-start-skip' do for ordinary text-following
+comments.  Normally these are set properly by Fortran mode, so you do
+not need to change them.
+
+   The normal Emacs comment command `C-x ;' has not been redefined.  It
+can therefore be used if you use `!' comments, but is useless in
+Fortran mode otherwise.
+
+   The command `C-c ;' (`fortran-comment-region') turns all the lines
+of the region into comments by inserting the string `C$$$' at the front
+of each one.  With a numeric arg, the region is turned back into live
+code by deleting `C$$$' from the front of each line.  You can control
+the string used for the comments by setting the variable
+`fortran-comment-region'.  Note that here we have an example of a
+command and a variable with the same name; the two uses of the name
+never conflict because in Lisp and in Emacs it is always clear from the
+context which one is referred to.
+
+\1f
+File: xemacs.info,  Node: Fortran Columns,  Next: Fortran Abbrev,  Prev: Fortran Comments,  Up: Fortran
+
+Columns
+-------
+
+`C-c C-r'
+     Displays a "column ruler" momentarily above the current line
+     (`fortran-column-ruler').
+
+`C-c C-w'
+     Splits the current window horizontally so that it is 72 columns
+     wide.  This may help you avoid going over that limit
+     (`fortran-window-create').
+
+   The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
+above the current line.  The comment ruler consists of two lines of
+text that show you the locations of columns with special significance
+in Fortran programs.  Square brackets show the limits of the columns for
+line numbers, and curly brackets show the limits of the columns for the
+statement body.  Column numbers appear above them.
+
+   Note that the column numbers count from zero, as always in XEmacs.
+As a result, the numbers may not be those you are familiar with; but the
+actual positions in the line are standard Fortran.
+
+   The text used to display the column ruler is the value of the
+variable `fortran-comment-ruler'.  By changing this variable, you can
+change the display.
+
+   For even more help, use `C-c C-w' (`fortran-window-create'), a
+command which splits the current window horizontally, resulting in a
+window 72 columns wide.  When you edit in this window, you can
+immediately see when a line gets too wide to be correct Fortran.
+
+\1f
+File: xemacs.info,  Node: Fortran Abbrev,  Prev: Fortran Columns,  Up: Fortran
+
+Fortran Keyword Abbrevs
+-----------------------
+
+Fortran mode provides many built-in abbrevs for common keywords and
+declarations.  These are the same sort of abbrevs that you can define
+yourself.  To use them, you must turn on Abbrev mode.  *note Abbrevs::.
+
+   The built-in abbrevs are unusual in one way: they all start with a
+semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
+mode makes this possible by changing the syntax of semicolon to "word
+constituent".
+
+   For example, one built-in Fortran abbrev is `;c' for `continue'.  If
+you insert `;c' and then insert a punctuation character such as a space
+or a newline, the `;c' changes automatically to `continue', provided
+Abbrev mode is enabled.
+
+   Type `;?' or `;C-h' to display a list of all built-in Fortran
+abbrevs and what they stand for.
+
+\1f
+File: xemacs.info,  Node: Asm Mode,  Prev: Fortran,  Up: Programs
+
+Asm Mode
+========
+
+Asm mode is a major mode for editing files of assembler code.  It
+defines these commands:
+
+`<TAB>'
+     `tab-to-tab-stop'.
+
+`<LFD>'
+     Insert a newline and then indent using `tab-to-tab-stop'.
+
+`:'
+     Insert a colon and then remove the indentation from before the
+     label preceding colon.  Then do `tab-to-tab-stop'.
+
+`;'
+     Insert or align a comment.
+
+   The variable `asm-comment-char' specifies which character starts
+comments in assembler syntax.
+
+\1f
+File: xemacs.info,  Node: Running,  Next: Abbrevs,  Prev: Programs,  Up: Top
+
+Compiling and Testing Programs
+******************************
+
+The previous chapter discusses the Emacs commands that are useful for
+making changes in programs.  This chapter deals with commands that
+assist in the larger process of developing and maintaining programs.
+
+* Menu:
+
+* Compilation::        Compiling programs in languages other than Lisp
+                        (C, Pascal, etc.)
+* Modes: Lisp Modes.   Various modes for editing Lisp programs, with
+                       different facilities for running the Lisp programs.
+* Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
+* Eval: Lisp Eval.     Executing a single Lisp expression in Emacs.
+* Debug: Lisp Debug.   Debugging Lisp programs running in Emacs.
+* Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
+* External Lisp::      Communicating through Emacs with a separate Lisp.
+
+\1f
+File: xemacs.info,  Node: Compilation,  Next: Lisp Modes,  Prev: Running,  Up: Running
+
+Running "make", or Compilers Generally
+======================================
+
+Emacs can run compilers for non-interactive languages like C and
+Fortran as inferior processes, feeding the error log into an Emacs
+buffer.  It can also parse the error messages and visit the files in
+which errors are found, moving point to the line where the error
+occurred.
+
+`M-x compile'
+     Run a compiler asynchronously under Emacs, with error messages to
+     `*compilation*' buffer.
+
+`M-x grep'
+     Run `grep' asynchronously under Emacs, with matching lines listed
+     in the buffer named `*compilation*'.
+
+`M-x kill-compilation'
+     Kill the process made by the `M-x compile' command.
+
+`M-x kill-grep'
+     Kill the running compilation or `grep' subprocess.
+
+`C-x `'
+     Visit the next compiler error message or `grep' match.
+
+   To run `make' or another compiler, type `M-x compile'.  This command
+reads a shell command line using the minibuffer, then executes the
+specified command line in an inferior shell with output going to the
+buffer named `*compilation*'.  By default, the current buffer's default
+directory is used as the working directory for the execution of the
+command; therefore, the makefile comes from this directory.
+
+   When the shell command line is read, the minibuffer appears
+containing a default command line (the command you used the last time
+you typed `M-x compile').  If you type just <RET>, the same command
+line is used again.  The first `M-x compile' provides `make -k' as the
+default.  The default is taken from the variable `compile-command'; if
+the appropriate compilation command for a file is something other than
+`make -k', it can be useful to have the file specify a local value for
+`compile-command' (*note File Variables::).
+
+   When you start a compilation, the buffer `*compilation*' is
+displayed in another window but not selected.  Its mode line displays
+the word `run' or `exit' in the parentheses to tell you whether
+compilation is finished.  You do not have to keep this buffer visible;
+compilation continues in any case.
+
+   To kill the compilation process, type `M-x kill-compilation'.  The
+mode line of the `*compilation*' buffer changes to say `signal' instead
+of `run'.  Starting a new compilation also kills any running
+compilation, as only one can occur at any time.  Starting a new
+compilation prompts for confirmation before actually killing a
+compilation that is running.
+
+   To parse the compiler error messages, type `C-x `' (`next-error').
+The character following `C-x' is the grave accent, not the single
+quote.  The command displays the buffer `*compilation*' in one window
+and the buffer in which the next error occurred in another window.
+Point in that buffer is moved to the line where the error was found.
+The corresponding error message is scrolled to the top of the window in
+which `*compilation*' is displayed.
+
+   The first time you use `C-x `' after the start of a compilation, it
+parses all the error messages, visits all the files that have error
+messages, and creates markers pointing at the lines the error messages
+refer to.  It then moves to the first error message location.
+Subsequent uses of `C-x `' advance down the data set up by the first
+use.  When the preparsed error messages are exhausted, the next `C-x `'
+checks for any more error messages that have come in; this is useful if
+you start editing compiler errors while compilation is still going on.
+If no additional error messages have come in, `C-x `' reports an error.
+
+   `C-u C-x `' discards the preparsed error message data and parses the
+`*compilation*' buffer again, then displays the first error.  This way,
+you can process the same set of errors again.
+
+   Instead of running a compiler, you can run `grep' and see the lines
+on which matches were found.  To do this, type `M-x grep' with an
+argument line that contains the same arguments you would give to
+`grep': a `grep'-style regexp (usually in single quotes to quote the
+shell's special characters) followed by filenames, which may use
+wildcard characters.  The output from `grep' goes in the
+`*compilation*' buffer.  You can use `C-x `' to find the lines that
+match as if they were compilation errors.
+
+   Note: a shell is used to run the compile command, but the shell is
+not run in interactive mode.  In particular, this means that the shell
+starts up with no prompt.  If you find your usual shell prompt making an
+unsightly appearance in the `*compilation*' buffer, it means you have
+made a mistake in your shell's initialization file (`.cshrc' or `.shrc'
+or ...) by setting the prompt unconditionally.  The shell
+initialization file should set the prompt only if there already is a
+prompt.  Here's how to do it in `csh':
+
+     if ($?prompt) set prompt = ...
+
+\1f
+File: xemacs.info,  Node: Lisp Modes,  Next: Lisp Libraries,  Prev: Compilation,  Up: Running
+
+Major Modes for Lisp
+====================
+
+Emacs has four different major modes for Lisp.  They are the same in
+terms of editing commands, but differ in the commands for executing Lisp
+expressions.
+
+Emacs-Lisp mode
+     The mode for editing source files of programs to run in Emacs Lisp.
+     This mode defines `C-M-x' to evaluate the current defun.  *Note
+     Lisp Libraries::.
+
+Lisp Interaction mode
+     The mode for an interactive session with Emacs Lisp.  It defines
+     <LFD> to evaluate the sexp before point and insert its value in the
+     buffer.  *Note Lisp Interaction::.
+
+Lisp mode
+     The mode for editing source files of programs that run in other
+     dialects of Lisp than Emacs Lisp.  This mode defines `C-M-x' to
+     send the current defun to an inferior Lisp process.  *Note
+     External Lisp::.
+
+Inferior Lisp mode
+     The mode for an interactive session with an inferior Lisp process.
+     This mode combines the special features of Lisp mode and Shell mode
+     (*note Shell Mode::).
+
+Scheme mode
+     Like Lisp mode but for Scheme programs.
+
+Inferior Scheme mode
+     The mode for an interactive session with an inferior Scheme
+     process.
+
+\1f
+File: xemacs.info,  Node: Lisp Libraries,  Next: Lisp Eval,  Prev: Lisp Modes,  Up: Running
+
+Libraries of Lisp Code for Emacs
+================================
+
+Lisp code for Emacs editing commands is stored in files whose names
+conventionally end in `.el'.  This ending tells Emacs to edit them in
+Emacs-Lisp mode (*note Lisp Modes::).
+
+* Menu:
+
+* Loading::            Loading libraries of Lisp code into Emacs for use.
+* Compiling Libraries:: Compiling a library makes it load and run faster.
+* Mocklisp::           Converting Mocklisp to Lisp so XEmacs can run it.
+
+\1f
+File: xemacs.info,  Node: Loading,  Next: Compiling Libraries,  Prev: Lisp Libraries,  Up: Lisp Libraries
+
+Loading Libraries
+-----------------
+
+`M-x load-file FILE'
+     Load the file FILE of Lisp code.
+
+`M-x load-library LIBRARY'
+     Load the library named LIBRARY.
+
+`M-x locate-library LIBRARY &optional NOSUFFIX'
+     Show the full path name of Emacs library LIBRARY.
+
+   To execute a file of Emacs Lisp, use `M-x load-file'.  This command
+reads the file name you provide in the minibuffer, then executes the
+contents of that file as Lisp code.  It is not necessary to visit the
+file first; in fact, this command reads the file as found on disk, not
+the text in an Emacs buffer.
+
+   Once a file of Lisp code is installed in the Emacs Lisp library
+directories, users can load it using `M-x load-library'.  Programs can
+load it by calling `load-library', or with `load', a more primitive
+function that is similar but accepts some additional arguments.
+
+   `M-x load-library' differs from `M-x load-file' in that it searches
+a sequence of directories and tries three file names in each directory.
+The three names are: first, the specified name with `.elc' appended;
+second, the name with `.el' appended; third, the specified name alone.
+A `.elc' file would be the result of compiling the Lisp file into byte
+code;  if possible, it is loaded in preference to the Lisp file itself
+because the compiled file loads and runs faster.
+
+   Because the argument to `load-library' is usually not in itself a
+valid file name, file name completion is not available.  In fact, when
+using this command, you usually do not know exactly what file name will
+be used.
+
+   The sequence of directories searched by `M-x load-library' is
+specified by the variable `load-path', a list of strings that are
+directory names.  The elements of this list may not begin with "`~'",
+so you must call `expand-file-name' on them before adding them to the
+list.  The default value of the list contains the directory where the
+Lisp code for Emacs itself is stored.  If you have libraries of your
+own, put them in a single directory and add that directory to
+`load-path'.  `nil' in this list stands for the current default
+directory, but it is probably not a good idea to put `nil' in the list.
+If you start wishing that `nil' were in the list, you should probably
+use `M-x load-file' for this case.
+
+   The variable is initialized by the EMACSLOADPATH environment
+variable. If no value is specified, the variable takes the default value
+specified in the file `paths.h' when Emacs was built. If a path isn't
+specified in `paths.h', a default value is obtained from the file
+system, near the directory in which the Emacs executable resides.
+
+   Like `M-x load-library', `M-x locate-library' searches the
+directories in `load-path' to find the file that `M-x load-library'
+would load.  If the optional second argument NOSUFFIX is non-`nil', the
+suffixes `.elc' or `.el' are not added to the specified name LIBRARY
+(like calling `load' instead of `load-library').
+
+   You often do not have to give any command to load a library, because
+the commands defined in the library are set up to "autoload" that
+library.  Running any of those commands causes `load' to be called to
+load the library; this replaces the autoload definitions with the real
+ones from the library.
+
+   If autoloading a file does not finish, either because of an error or
+because of a `C-g' quit, all function definitions made by the file are
+undone automatically.  So are any calls to `provide'.  As a
+consequence, the entire file is loaded a second time if you use one of
+the autoloadable commands again.  This prevents problems when the
+command is no longer autoloading but is working incorrectly because the
+file was only partially loaded.  Function definitions are undone only
+for autoloading; explicit calls to `load' do not undo anything if
+loading is not completed.
+
+   The variable `after-load-alist' takes an alist of expressions to be
+evaluated when particular files are loaded.  Each element has the form
+`(FILENAME forms...)'.  When `load' is run and the filename 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 it
+does prevent execution of the rest of the `forms'.
+
+\1f
+File: xemacs.info,  Node: Compiling Libraries,  Next: Mocklisp,  Prev: Loading,  Up: Lisp Libraries
+
+Compiling Libraries
+-------------------
+
+Emacs Lisp code can be compiled into byte-code which loads faster,
+takes up less space when loaded, and executes faster.
+
+`M-x batch-byte-compile'
+     Run byte-compile-file on the files remaining on the command line.
+
+`M-x byte-compile-buffer &optional BUFFER'
+     Byte-compile and evaluate contents of BUFFER (default is current
+     buffer).
+
+`M-x byte-compile-file'
+     Compile a file of Lisp code named FILENAME into a file of byte
+     code.
+
+`M-x byte-compile-and-load-file FILENAME'
+     Compile a file of Lisp code named FILENAME into a file of byte
+     code and load it.
+
+`M-x byte-recompile-directory DIRECTORY'
+     Recompile every `.el' file in DIRECTORY that needs recompilation.
+
+`M-x disassemble'
+     Print disassembled code for OBJECT on (optional) STREAM.
+
+`M-x make-obsolete FUNCTION NEW'
+     Make the byte-compiler warn that FUNCTION is obsolete and NEW
+     should be used instead.
+
+   `byte-compile-file' creates a byte-code compiled file from an
+Emacs-Lisp source file.  The default argument for this function is the
+file visited in the current buffer.  The function reads the specified
+file, compiles it into byte code, and writes an output file whose name
+is made by appending `c' to the input file name.  Thus, the file
+`rmail.el' would be compiled into `rmail.elc'. To compile a file of
+Lisp code named FILENAME into a file of byte code and then load it, use
+`byte-compile-and-load-file'. To compile and evaluate Lisp code in a
+given buffer, use `byte-compile-buffer'.
+
+   To recompile all changed Lisp files in a directory, use `M-x
+byte-recompile-directory'.  Specify just the directory name as an
+argument.  Each `.el' file that has been byte-compiled before is
+byte-compiled again if it has changed since the previous compilation.
+A numeric argument to this command tells it to offer to compile each
+`.el' file that has not been compiled yet.  You must answer `y' or `n'
+to each offer.
+
+   You can use the function `batch-byte-compile' to invoke Emacs
+non-interactively from the shell to do byte compilation.  When you use
+this function, the files to be compiled are specified with command-line
+arguments.  Use a shell command of the form:
+
+     emacs -batch -f batch-byte-compile FILES...
+
+   Directory names may also be given as arguments; in that case,
+`byte-recompile-directory' is invoked on each such directory.
+`batch-byte-compile' uses all remaining command-line arguments as file
+or directory names, then kills the Emacs process.
+
+   `M-x disassemble' explains the result of byte compilation.  Its
+argument is a function name.  It displays the byte-compiled code in a
+help window in symbolic form, one instruction per line.  If the
+instruction refers to a variable or constant, that is shown, too.
+
+\1f
+File: xemacs.info,  Node: Mocklisp,  Prev: Compiling Libraries,  Up: Lisp Libraries
+
+Converting Mocklisp to Lisp
+---------------------------
+
+XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
+To convert a Mocklisp file, visit it and then type `M-x
+convert-mocklisp-buffer'.  Then save the resulting buffer of Lisp file
+in a file whose name ends in `.el' and use the new file as a Lisp
+library.
+
+   You cannot currently byte-compile converted Mocklisp code.  The
+reason is that converted Mocklisp code uses some special Lisp features
+to deal with Mocklisp's incompatible ideas of how arguments are
+evaluated and which values signify "true" or "false".
+
+\1f
+File: xemacs.info,  Node: Lisp Eval,  Next: Lisp Debug,  Prev: Lisp Libraries,  Up: Running
+
+Evaluating Emacs-Lisp Expressions
+=================================
+
+Lisp programs intended to be run in Emacs should be edited in
+Emacs-Lisp mode; this will happen automatically for file names ending in
+`.el'.  By contrast, Lisp mode itself should be used for editing Lisp
+programs intended for other Lisp systems.  Emacs-Lisp mode can be
+selected with the command `M-x emacs-lisp-mode'.
+
+   For testing of Lisp programs to run in Emacs, it is useful to be able
+to evaluate part of the program as it is found in the Emacs buffer.  For
+example, if you change the text of a Lisp function definition and then
+evaluate the definition, Emacs installs the change for future calls to
+the function.  Evaluation of Lisp expressions is also useful in any
+kind of editing task for invoking non-interactive functions (functions
+that are not commands).
+
+`M-:'
+     Read a Lisp expression in the minibuffer, evaluate it, and print
+     the value in the minibuffer (`eval-expression').
+
+`C-x C-e'
+     Evaluate the Lisp expression before point, and print the value in
+     the minibuffer (`eval-last-sexp').
+
+`C-M-x'
+     Evaluate the defun containing point or after point, and print the
+     value in the minibuffer (`eval-defun').
+
+`M-x eval-region'
+     Evaluate all the Lisp expressions in the region.
+
+`M-x eval-current-buffer'
+     Evaluate all the Lisp expressions in the buffer.
+
+   `M-:' (`eval-expression') is the most basic command for evaluating a
+Lisp expression interactively.  It reads the expression using the
+minibuffer, so you can execute any expression on a buffer regardless of
+what the buffer contains.  When evaluation is complete, the current
+buffer is once again the buffer that was current when `M-:' was typed.
+
+   In Emacs-Lisp mode, the key `C-M-x' is bound to the function
+`eval-defun', which parses the defun containing point or following point
+as a Lisp expression and evaluates it.  The value is printed in the echo
+area.  This command is convenient for installing in the Lisp environment
+changes that you have just made in the text of a function definition.
+
+   The command `C-x C-e' (`eval-last-sexp') performs a similar job but
+is available in all major modes, not just Emacs-Lisp mode.  It finds
+the sexp before point, reads it as a Lisp expression, evaluates it, and
+prints the value in the echo area.  It is sometimes useful to type in an
+expression and then, with point still after it, type `C-x C-e'.
+
+   If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
+value by inserting it into the current buffer at point, rather than in
+the echo area.  The argument value does not matter.
+
+   The most general command for evaluating Lisp expressions from a
+buffer is `eval-region'.  `M-x eval-region' parses the text of the
+region as one or more Lisp expressions, evaluating them one by one.
+`M-x eval-current-buffer' is similar, but it evaluates the entire
+buffer.  This is a reasonable way to install the contents of a file of
+Lisp code that you are just ready to test.  After finding and fixing a
+bug, use `C-M-x' on each function that you change, to keep the Lisp
+world in step with the source file.
+
+\1f
+File: xemacs.info,  Node: Lisp Debug,  Next: Lisp Interaction,  Prev: Lisp Eval,  Up: Running
+
+The Emacs-Lisp Debugger
+=======================
+
+XEmacs contains a debugger for Lisp programs executing inside it.  This
+debugger is normally not used; many commands frequently get Lisp errors
+when invoked in inappropriate contexts (such as `C-f' at the end of the
+buffer) and it would be unpleasant to enter a special debugging mode in
+this case.  When you want to make Lisp errors invoke the debugger, you
+must set the variable `debug-on-error' 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'.  However, if you set `debug-on-quit' to be
+non-`nil', `C-g' will invoke the debugger.  This can be useful for
+debugging an infinite loop; type `C-g' once the loop has had time to
+reach its steady state.  `debug-on-quit' has no effect on errors.
+
+   You can make Emacs enter the debugger when a specified function is
+called or at a particular place in Lisp code.  Use `M-x debug-on-entry'
+with argument FUN-NAME to have Emacs enter the debugger as soon as
+FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
+function stop entering the debugger when called.  (Redefining the
+function also does this.)  To enter the debugger from some other place
+in Lisp code, you must insert the expression `(debug)' there and
+install the changed code with `C-M-x'.  *Note Lisp Eval::.
+
+   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 the buffer
+is a message describing the reason that the debugger was invoked, for
+example, an error message if it was invoked due to an error.
+
+   The backtrace buffer is read-only and is in Backtrace mode, a special
+major mode in which letters are defined as debugger commands.  The
+usual Emacs editing commands are available; you can switch windows to
+examine the buffer that was being edited at the time of the error, and
+you can switch buffers, visit files, and perform any other editing
+operations.  However, the debugger is a recursive editing level (*note
+Recursive Edit::); it is a good idea to return to the backtrace buffer
+and explicitly exit the debugger when you don't want to use it any
+more.  Exiting the debugger kills the backtrace buffer.
+
+   The contents of the backtrace buffer show you the functions that are
+executing and the arguments that were given to them.  It also allows you
+to specify a stack frame by moving point to the line describing that
+frame.  The frame whose line point is on is considered the "current
+frame".  Some of the debugger commands operate on the current frame.
+Debugger commands are mainly used for stepping through code one
+expression at a time.  Here is a list of them:
+
+`c'
+     Exit the debugger and continue execution.  In most cases,
+     execution of the program continues 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).  This
+     includes entry to the debugger due to function entry or exit,
+     explicit invocation, and quitting or certain errors.  Most errors
+     cannot be continued; trying to continue an error usually causes
+     the same error to occur again.
+
+`d'
+     Continue execution, but enter the debugger the next time a Lisp
+     function is called.  This allows you to step through the
+     subexpressions of an expression, and see what the subexpressions
+     do and what values they compute.
+
+     When you enter the debugger this way, Emacs flags the stack frame
+     for the function call from which you entered.  The same function
+     is then called when you exit the frame.  To cancel this flag, use
+     `u'.
+
+`b'
+     Set up to enter the debugger when the current frame is exited.
+     Frames that invoke the debugger on exit are flagged with stars.
+
+`u'
+     Don't enter the debugger when the current frame is exited.  This
+     cancels a `b' command on a frame.
+
+`e'
+     Read a Lisp expression in the minibuffer, evaluate it, and print
+     the value in the echo area.  This is equivalent to the command
+     `M-:'.
+
+`q'
+     Terminate the program being debugged; return to top-level Emacs
+     command execution.
+
+     If the debugger was entered due to a `C-g' but you really want to
+     quit, not to 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 value returned by the debugger makes a difference 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.
+
+     The debugger's return value also matters with many errors.  For
+     example, `wrong-type-argument' errors will use the debugger's
+     return value instead of the invalid argument; `no-catch' errors
+     will use the debugger value as a throw tag instead of the tag that
+     was not found.  If an error was signaled by calling the Lisp
+     function `signal', the debugger's return value is returned as the
+     value of `signal'.

 
 

diff --git a/info/xemacs.info-3 b/info/xemacs.info-3
index f3f6e3a..a55d70b 100644 (file)
--- a/info/xemacs.info-3
+++ b/info/xemacs.info-3
@@ -1,4 +1,4 @@
-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from

 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -30,1217 +30,7274 @@ versions, except that the sections entitled "The GNU Manifesto",
 translation approved by the author instead of in the original English.
 
 \1f
 translation approved by the author instead of in the original English.
 
 \1f

-File: xemacs.info,  Node: Options Menu,  Next: Buffers Menu,  Prev: Apps Menu,  Up: Pull-down Menus
+File: xemacs.info,  Node: Lisp Interaction,  Next: External Lisp,  Prev: Lisp Debug,  Up: Running
+
+Lisp Interaction Buffers
+========================
+
+The buffer `*scratch*', which is selected when Emacs starts up, is
+provided for evaluating Lisp expressions interactively inside Emacs.
+Both the expressions you evaluate and their output goes in the buffer.
+
+   The `*scratch*' buffer's major mode is Lisp Interaction mode, which
+is the same as Emacs-Lisp mode except for one command, <LFD>.  In
+Emacs-Lisp mode, <LFD> is an indentation command.  In Lisp Interaction
+mode, <LFD> is bound to `eval-print-last-sexp'.  This function reads
+the Lisp expression before point, evaluates it, and inserts the value
+in printed representation before point.
+
+   The way to use the `*scratch*' buffer is to insert Lisp expressions
+at the end, ending each one with <LFD> so that it will be evaluated.
+The result is a complete typescript of the expressions you have
+evaluated and their values.
+
+   The rationale for this feature is that Emacs must have a buffer when
+it starts up, but that buffer is not useful for editing files since a
+new buffer is made for every file that you visit.  The Lisp interpreter
+typescript is the most useful thing I can think of for the initial
+buffer to do.  `M-x lisp-interaction-mode' will put any buffer in Lisp
+Interaction mode.

 
 

-The Options Menu
-----------------
+\1f
+File: xemacs.info,  Node: External Lisp,  Prev: Lisp Interaction,  Up: Running
+
+Running an External Lisp
+========================
+
+Emacs has facilities for running programs in other Lisp systems.  You
+can run a Lisp process as an inferior of Emacs, and pass expressions to
+it to be evaluated.  You can also pass changed function definitions
+directly from the Emacs buffers in which you edit the Lisp programs to
+the inferior Lisp process.
+
+   To run an inferior Lisp process, type `M-x run-lisp'.  This runs the
+program named `lisp', the same program you would run by typing `lisp'
+as a shell command, with both input and output going through an Emacs
+buffer named `*lisp*'.  In other words, any "terminal output" from Lisp
+will go into the buffer, advancing point, and any "terminal input" for
+Lisp comes from text in the buffer.  To give input to Lisp, go to the
+end of the buffer and type the input, terminated by <RET>.  The
+`*lisp*' buffer is in Inferior Lisp mode, which has all the special
+characteristics of Lisp mode and Shell mode (*note Shell Mode::).
+
+   Use Lisp mode to run the source files of programs in external Lisps.
+You can select this mode with `M-x lisp-mode'.  It is used automatically
+for files whose names end in `.l' or `.lisp', as most Lisp systems
+usually expect.
+
+   When you edit a function in a Lisp program you are running, the
+easiest way to send the changed definition to the inferior Lisp process
+is the key `C-M-x'.  In Lisp mode, this key runs the function
+`lisp-send-defun', which finds the defun around or following point and
+sends it as input to the Lisp process.  (Emacs can send input to any
+inferior process regardless of what buffer is current.)
+
+   Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
+to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
+programs to be run in Emacs): in both modes it has the effect of
+installing the function definition that point is in, but the way of
+doing so is different according to where the relevant Lisp environment
+is found.  *Note Lisp Modes::.

 
 

-   The Options pull-down menu contains the Read Only, Case Sensitive
-Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
-Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
-Menu Length..., Buffers Sub-Menus and Save Options menu items.  When
-you select a menu item, Emacs executes the equivalent command.  For
-some of the menu items, there are sub-menus which you will need to
-select.
-
-Read Only
-     Selecting this item will cause the buffer to visit the file in a
-     read-only mode. Changes to the file will not be allowed. This is
-     equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
-
-Case Sensitive Search
-     Selecting this item will cause searches to be case-sensitive. If
-     its not selected then searches will ignore case. This option is
-     local to the buffer.
-
-Overstrike
-     After selecting this item, when you type letters they will replace
-     existing text on a one-to-one basis, rather than pushing it to the
-     right. At the end of a line, such characters extend the line.
-     Before a tab, such characters insert until the tab is filled in.
-     This is the same as Emacs command `quoted-insert' (`C-q').
-
-Auto Delete Selection
-     Selecting this item will cause automatic deletion of the selected
-     region. The typed text will replace the selection if the selection
-     is active (i.e. if its highlighted). If the option is not selected
-     then the typed text is just inserted at the point.
-
-Teach Extended Commands
-     After you  select this item, any time you execute a command with
-     `M-x'which has a shorter keybinding, you will be shown the
-     alternate binding before the command executes.
-
-Syntax Highlighting
-     You can customize your init file to include the font-lock mode so
-     that when you select this item, the comments will be displayed in
-     one face, strings in another, reserved words in another, and so
-     on. *Note Init File::.  When Fonts is selected, different parts of
-     the program will appear in different Fonts. When Colors is
-     selected, then the program will be displayed in different colors.
-     Selecting None causes the program to appear in just one Font and
-     Color. Selecting Less resets the Fonts and Colors to a fast,
-     minimal set of decorations. Selecting More resets the Fonts and
-     Colors to a larger set of decorations. For example, if Less is
-     selected (which is the default setting) then you might have all
-     comments in green color.  Whereas, if More is selected then a
-     function name in the comments themselves might appear in a
-     different Color or Font.
-
-Paren Highlighting
-     After selecting Blink from this item, if you place the cursor on a
-     parenthesis, the matching parenthesis will blink. If you select
-     Highlight and place the cursor on a parenthesis, the whole
-     expression of the parenthesis under the cursor will be highlighted.
-     Selecting None will turn off the options (regarding Paren
-     Highlighting) which you had selected earlier.
-
-Font
-     You can select any Font for your program by choosing from one of
-     the available Fonts.
-
-Size
-     You can select any size ranging from 2 to 24 by selecting the
-     appropriate option.
-
-Weight
-     You can choose either Bold or Medium for the weight.
-
-Buffers Menu Length...
-     Prompts you for the number of buffers to display. Then it will
-     display that number of most recently selected buffers.
-
-Buffers Sub-Menus
-     After selection of this item the Buffers menu will contain several
-     commands, as submenus of each buffer line. If this item is
-     unselected, then there are no submenus for each buffer line, the
-     only command available will be selecting that buffer.
-
-Save Options
-     Selecting this item will save the current settings of your Options
-     menu to your init file.  *Note Init File::.
-
-\1f
-File: xemacs.info,  Node: Buffers Menu,  Next: Tools Menu,  Prev: Options Menu,  Up: Pull-down Menus
-
-The Buffers Menu
-----------------
+\1f
+File: xemacs.info,  Node: Packages,  Next: Basic,  Prev: Startup Paths,  Up: Top
+
+Packages
+========
+
+The XEmacs 21 distribution comes only with a very basic set of built-in
+modes and packages.  Most of the packages that were part of the
+distribution of earlier versions of XEmacs are now available
+separately.  The installer as well as the user can choose which
+packages to install; the actual installation process is easy.  This
+gives an installer the ability to tailor an XEmacs installation for
+local needs with safe removal of unnecessary code.
+
+* Menu:

 
 

-   The Buffers menu provides a selection of up to ten buffers and the
-item List All Buffers, which provides a Buffer List. *Note List
-Buffers::, for more information.
+* Package Terminology:: Understanding different kinds of packages.
+* Installing Packages:: How to install packages.
+* Building Packages::   Building packages from CVS sources.
+* Local.rules File::    This is an important file that you must create.
+* Available Packages::  A brief directory of packaged LISP.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Tools Menu,  Next: Help Menu,  Prev: Buffers Menu,  Up: Pull-down Menus
+File: xemacs.info,  Node: Package Terminology,  Next: Installing Packages,  Up: Packages

 
 

-The Tools Menu
---------------
+Package Terminology:
+====================
+
+Package Flavors
+---------------
+
+There are two main flavors of packages.
+
+   * Regular Packages A regular package is one in which multiple files
+     are involved and one may not in general safely remove any of them.
+
+   * Single-File Packages A single-file package is an aggregate
+     collection of thematically related but otherwise independent lisp
+     files.  These files are bundled together for download convenience
+     and individual files may be deleted at will without any loss of
+     functionality.  However, we would recommend that you follow this
+     rule of thumb: "When in doubt, don't delete".
+
+Package Distributions
+---------------------
+
+XEmacs Lisp packages are distributed in two ways, depending on the
+intended use.  Binary Packages are for installers and end-users that can
+be installed directly into an XEmacs package directory.  Source Packages
+are for developers and include all files necessary for rebuilding
+bytecompiled lisp and creating tarballs for distribution.

 
 

-   The Tools pull-down menu contains the Grep..., Compile..., Shell
-Command..., Shell Command on Region..., Debug(GDB)...  and
-Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
-sub-menus.  When you select a menu item, Emacs executes the equivalent
-command.  For some of the menu items, there are sub-menus which you
-will need to select.
+Binary Packages
+---------------
+
+Binary packages may be installed directly into an XEmacs package
+hierarchy.
+
+Source Packages
+---------------
+
+Source packages contain all of the Package author's (where appropriate
+in regular packages) source code plus all of the files necessary to
+build distribution tarballs (Unix Tar format files, gzipped for space
+savings).
+
+   Currently, source packages are only available via CVS.  See
+<http://cvs.xemacs.org/> for details.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Help Menu,  Next: Menu Customization,  Prev: Tools Menu,  Up: Pull-down Menus
+File: xemacs.info,  Node: Installing Packages,  Next: Building Packages,  Prev: Package Terminology,  Up: Packages

 
 

-The Help Menu
--------------
+Installing Packages:
+====================
+
+Getting Started
+---------------
+
+When you first download XEmacs 21, you will usually first grab the
+"core distribution", a file called `xemacs-21.x.x.tar.gz'. (Replace the
+21.x.x by the current version number.)  The core distribution contains
+the sources of XEmacs and a minimal set of Emacs Lisp files, which are
+in the subdirectory named `lisp'.  This subdirectory used to contain
+all Emacs Lisp files distributed with XEmacs.  Now, to conserve disk
+space, most non-essential packages were made optional.
+
+Choosing the Packages You Need
+------------------------------
+
+The *Note Available Packages:: can currently be found in the same ftp
+directory where you grabbed the core distribution from, and are located
+in the subdirectory `packages'.  Package file names follow the naming
+convention `<package-name>-<version>-pkg.tar.gz'.
+
+   If you have EFS *Note (EFS)::, packages can be installed over the
+network.  Alternatively, if you have copies of the packages locally,
+you can install packages from a local disk or CDROM.
+
+   The file `etc/PACKAGES' in the core distribution contains a list of
+the *Note Available Packages:: at the time of the XEmacs release.
+
+   You can also get a list of available packages, and whether or not
+they are installed, using the visual package browser and installer.
+You can access it via the menus:
+
+     Tools -> Packages -> List and Install
+
+   Or, you can get to it via the keyboard:
+
+     `M-x pui-list-packages'

 
 

-   The Help Menu gives you access to Emacs Info and provides a menu
-equivalent for each of the choices you have when using `C-h'.  *Note
-Help::, for more information.
+   Hint to system administrators of multi-user systems: it might be a
+good idea to install all packages and not interfere with the wishes of
+your users.

 
 

-   The Help menu also gives access to UNIX online manual pages via the
-UNIX Manual Page option.
+   If you can't find which package provides the feature you require, try
+using the `package-get-package-provider' function. Eg., if you know
+that you need `thingatpt', type:
+
+     `M-x package-get-package-provider RET thingatpt'
+
+   which will return something like `(fsf-compat "1.08")'. You can the
+use one of the methods above for installing the package you want.
+
+XEmacs and Installing Packages
+------------------------------
+
+There are three main ways to install packages:
+
+* Menu:
+
+* Automatically::     Using the package tools from XEmacs.
+* Manually::          Using individual package tarballs.
+* Sumo::              All at once, using the 'Sumo Tarball'.
+* Which Packages::    Which packages to install.
+* Removing Packages:: Removing packages.
+
+   But regardless of the method you use to install packages, they can
+only be used by XEmacs after a restart unless the package in question
+has not been previously installed.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Menu Customization,  Prev: Help Menu,  Up: Pull-down Menus
+File: xemacs.info,  Node: Automatically,  Next: Manually,  Up: Installing Packages

 
 

-Customizing XEmacs Menus
-------------------------
+Automatic Package Installation:
+===============================
+
+XEmacs comes with some tools to make the periodic updating and
+installing easier. It will notice if new packages or versions are
+available and will fetch them from the FTP site.
+
+   Unfortunately this requires that a few packages are already in place.
+You will have to install them by hand as above or use a SUMO tarball.
+This requirement will hopefully go away in the future. The packages you
+need are:
+
+        efs          - To fetch the files from the FTP site or mirrors.
+        xemacs-base  - Needed by efs.
+     
+     and optionally:
+     
+        mailcrypt    - To do PGP verification of the `package-index'
+                       file.

 
 

-   You can customize any of the pull-down menus by adding or removing
-menu items and disabling or enabling existing menu items.
+   After installing these by hand, fire up XEmacs and follow these
+steps.

 
 

-   The following functions are available:
-`add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
-     Add a menu to the menu bar or one of its submenus.
+  1. Choose a download site.  via menu: Tools -> Packages -> Set
+     Download Site via keyb: `M-x customize-variable RET
+     package-get-remote RET' (put in the details of remote host and
+     directory)

 
 

-`add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
-     ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
-     the menu first if necessary.
+     If the package tarballs _AND_ the package-index file are in a
+     local directory, you can: `M-x pui-set-local-package-get-directory
+     RET'

 
 

-`delete-menu-item: (PATH)'
-     Remove the menu item defined by PATH from the menu hierarchy.
+  2. Obtain a list of packages and display the list in a buffer named
+     `*Packages*'.  menu: Tools -> Packages -> List & Install keyb:
+     `M-x pui-list-packages RET'

 
 

-`disable-menu-item: (PATH)'
-     Disable the specified menu item.
+     XEmacs will now connect to the remote site and download the latest
+     package-index file.

 
 

-`enable-menu-item: (PATH)'
-     Enable the specified previously disabled menu item.
+     The visual package browser will then display a list of all
+     packages.  Help information will be displayed at the very bottom
+     of the buffer; you may have to scroll down to see it.  You can
+     also press `?' to get the same help.  From this buffer, you can
+     tell the package status by the character in the first column:

 
 

-`relabel-menu-item: (PATH NEW-NAME)'
-     Change the string of the menu item specified by PATH to NEW-NAME.
+    `-'
+          The package has not been installed.

 
 

-   Use the function `add-menu' to add a new menu or submenu.  If a menu
-or submenu of the given name exists already, it is changed.
+    `*'
+          The package has been installed, but a newer version is
+          available.  The current version is out-of-date.

 
 

-   MENU-PATH identifies the menu under which the new menu should be
-inserted.  It is a list of strings; for example, `("File")' names the
-top-level File menu.  `("File" "Foo")' names a hypothetical submenu of
-File.  If MENU-PATH is `nil', the menu is added to the menu bar itself.
+    `+'
+          The package has been marked for installation/update.

 
 

-   MENU-NAME is the string naming the menu to be added.
+     If there is no character in the first column, the package has been
+     installed and is up to date.

 
 

-   MENU-ITEMS is a list of menu item descriptions.  Each menu item
-should be a vector of three elements:
+     From here, you can select or unselect packages for installation
+     using the <RET> key, the `Mouse-2' button or selecting "Select"
+     from the Popup `Mouse-3' Menu.  Once you've finished selecting the
+     packages, you can press the `x' key (or use the menu) to actually
+     install the packages. Note that you will have to restart XEmacs
+     for XEmacs to recognize any new packages.

 
 

-   * A string, which is the name of the menu item
+     Key summary:

 
 

-   * A symbol naming a command, or a form to evaluate
+    `?'
+          Display simple help.

 
 

-   * `t' or `nil' to indicate whether the item is selectable
+    `<RET>'
+    `<Mouse-2>'
+          Toggle between selecting and unselecting a package for
+          installation.

 
 

-   The optional argument BEFORE is the name of the menu before which
-the new menu or submenu should be added.  If the menu is already
-present, it is not moved.
+    `x'
+          Install selected packages.

 
 

-   The function `add-menu-item' adds a menu item to the specified menu,
-creating the menu first if necessary.  If the named item already
-exists, the menu remains unchanged.
+    `<SPC>'
+          View, in the minibuffer, additional information about the
+          package, such as the package date (not the build date) and
+          the package author.  Moving the mouse over a package name
+          will also do the same thing.

 
 

-   MENU-PATH identifies the menu into which the new menu item should be
-inserted.  It is a list of strings; for example, `("File")' names the
-top-level File menu.  `("File" "Foo")' names a hypothetical submenu of
-File.
+    `v'
+          Toggle between verbose and non-verbose package display.

 
 

-   ITEM-NAME is the string naming the menu item to add.
+    `g'
+          Refresh the package display.

 
 

-   FUNCTION is the command to invoke when this menu item is selected.
-If it is a symbol, it is invoked with `call-interactively', in the same
-way that functions bound to keys are invoked.  If it is a list, the
-list is simply evaluated.
+    `q'
+          Kill the package buffer.

 
 

-   ENABLED-P controls whether the item is selectable or not.  It should
-be `t', `nil', or a form to evaluate to decide.  This form will be
-evaluated just before the menu is displayed, and the menu item will be
-selectable if that form returns non-`nil'.
+     Moving the mouse over a package will also cause additional
+     information about the package to be displayed in the minibuffer.
+     If you have balloon-help enabled a balloon-help frame will pop up
+     and display additional package information also.

 
 

-   For example, to make the `rename-file' command available from the
-File menu, use the following code:
+  3. Choose the packages you wish to install.  mouse: Click button 2 on
+     the package name.   keyb: `RET' on the package name

 
 

-     (add-menu-item '("File") "Rename File" 'rename-file t)
+  4. Make sure you have everything you need.  menu: Packages -> Add
+     Required keyb: `r'

 
 

-   To add a submenu of file management commands using a File Management
-item, use the following code:
+     XEmacs will now search for packages that are required by the ones
+     that you have chosen to install and offer to select those packages
+     also.

 
 

-     (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
-     (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
-     (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
+     For novices and gurus alike, this step can save your bacon.  It's
+     easy to forget to install a critical package.

 
 

-   The optional BEFORE argument is the name of a menu item before which
-the new item should be added.  If the item is already present, it is
-not moved.
+  5. Download and install the packages.  menu: Packages ->
+     Install/Remove Selected keyb: `x'

 
 

-   To remove a specified menu item from the menu hierarchy, use
-`delete-menu-item'.
+   You can also install packages using a semi-manual interface:

 
 

-   PATH is a list of strings that identify the position of the menu
-item in the menu hierarchy.  `("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.
+     M-x package-get-all <return>

 
 

-   To disable a menu item, use `disable-menu-item'.  The disabled menu
-item is grayed and can no longer be selected.  To make the item
-selectable again, use `enable-menu-item'.  `disable-menu-item' and
-`enable-menu-item' both have the argument PATH.
+   Enter the name of the package (e.g., `prog-modes'), and XEmacs will
+search for the latest version and install it and any packages that it
+depends upon.

 
 

-   To change the string of the specified menu item, use
-`relabel-menu-item'. This function also takes the argument PATH.
+Keeping Packages Up To Date:
+============================

 
 

-   NEW-NAME is the string to which the menu item will be changed.
+Once you have the packages you want installed (using any of the above
+methods) you'll want to keep them up to date.  You can do this easily
+from the menubar:
+
+     Tools -> Packages -> Set Download Site
+     Tools -> Packages -> Update Installed Packages

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Entering Emacs,  Next: Exiting,  Prev: Pull-down Menus,  Up: Top
+File: xemacs.info,  Node: Manually,  Next: Sumo,  Prev: Automatically,  Up: Installing Packages

 
 

-Entering and Exiting Emacs
-**************************
+Manual Package Installation:
+============================

 
 

-   The usual way to invoke XEmacs is to type `xemacs <RET>' at the
-shell.  XEmacs clears the screen and then displays an initial advisory
-message and copyright notice.  You can begin typing XEmacs commands
-immediately afterward.
+Fetch the packages from the FTP site, CD-ROM whatever. The filenames
+have the form `name-<version>-pkg.tar.gz' and are gzipped tar files. For
+a fresh install it is sufficient to untar the file at the top of the
+package hierarchy.

 
 

-   Some operating systems insist on discarding all type-ahead when
-XEmacs starts up; they give XEmacs no way to prevent this.  Therefore,
-it is advisable to wait until XEmacs clears the screen before typing
-your first editing command.
+   Note: If you are upgrading packages already installed, it's best to
+remove the old package first *Note Removing Packages::.

 
 

-   If you run XEmacs from a shell window under the X Window System, run
-it in the background with `xemacs&'.  This way, XEmacs does not tie up
-the shell window, so you can use that to run other shell commands while
-XEmacs operates its own X windows.  You can begin typing XEmacs commands
-as soon as you direct your keyboard input to the XEmacs frame.
+   For example if we are installing the `xemacs-base' package (version
+1.48):

 
 

-   Before Emacs reads the first command, you have not had a chance to
-give a command to specify a file to edit.  Since Emacs must always have
-a current buffer for editing, it presents a buffer, by default, a buffer
-named `*scratch*'.  The buffer is in Lisp Interaction mode; you can use
-it to type Lisp expressions and evaluate them, or you can ignore that
-capability and simply doodle.  (You can specify a different major mode
-for this buffer by setting the variable `initial-major-mode' in your
-init file.  *Note Init File::.)
+        mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
+        cd $prefix/lib/xemacs/xemacs-packages RET
+        gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
+     
+     Or if you have GNU tar, the last step can be:
+     
+        tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET

 
 

-   It is possible to specify files to be visited, Lisp files to be
-loaded, and functions to be called, by giving Emacs arguments in the
-shell command line.  *Note Command Switches::.  But we don't recommend
-doing this.  The feature exists mainly for compatibility with other
-editors.
+   For MULE related packages, it is best to untar into the mule-packages
+hierarchy, i.e. for the `mule-base' package, version 1.37:

 
 

-   Many other editors are designed to be started afresh each time you
-want to edit.  You edit one file and then exit the editor.  The next
-time you want to edit either another file or the same one, you must run
-the editor again.  With these editors, it makes sense to use a
-command-line argument to say which file to edit.
-
-   But starting a new Emacs each time you want to edit a different file
-does not make sense.  For one thing, this would be annoyingly slow.  For
-another, this would fail to take advantage of Emacs's ability to visit
-more than one file in a single editing session.  And it would lose the
-other accumulated context, such as registers, undo history, and the mark
-ring.
-
-   The recommended way to use XEmacs is to start it only once, just
-after you log in, and do all your editing in the same Emacs session.
-Each time you want to edit a different file, you visit it with the
-existing Emacs, which eventually comes to have many files in it ready
-for editing.  Usually you do not kill the Emacs until you are about to
-log out.  *Note Files::, for more information on visiting more than one
-file.
-
-\1f
-File: xemacs.info,  Node: Exiting,  Next: Command Switches,  Prev: Entering Emacs,  Up: Top
+        mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
+        cd $prefix/lib/xemacs/mule-packages RET
+        gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
+     
+     Or if you have GNU tar, the last step can be:
+     
+        tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET

 
 

-Exiting Emacs
-=============
+\1f
+File: xemacs.info,  Node: Sumo,  Next: Which Packages,  Prev: Manually,  Up: Installing Packages

 
 

-   There are two commands for exiting Emacs because there are two kinds
-of exiting: "suspending" Emacs and "killing" Emacs.
-
-   "Suspending" means stopping Emacs temporarily and returning control
-to its parent process (usually a shell), allowing you to resume editing
-later in the same Emacs job, with the same buffers, same kill ring,
-same undo history, and so on.  This is the usual way to exit.
-
-   "Killing" Emacs means destroying the Emacs job.  You can run Emacs
-again later, but you will get a fresh Emacs; there is no way to resume
-the same editing session after it has been killed.
-
-`C-z'
-     Suspend Emacs or iconify a frame
-     (`suspend-emacs-or-iconify-frame').  If used under the X window
-     system, shrink the X window containing the Emacs frame to an icon
-     (see below).
-
-`C-x C-c'
-     Kill Emacs (`save-buffers-kill-emacs').
-
-   If you use XEmacs under the X window system, `C-z' shrinks the X
-window containing the Emacs frame to an icon.  The Emacs process is
-stopped temporarily, and control is returned to the window manager.  If
-more than one frame is associated with the Emacs process, only the
-frame from which you used `C-z' is iconified.
-
-   To activate the "suspended" Emacs, use the appropriate window manager
-mouse gestures.  Usually left-clicking on the icon reactivates and
-reopens the X window containing the Emacs frame, but the window manager
-you use determines what exactly happens.  To actually kill the Emacs
-process, use `C-x C-c' or the Exit XEmacs item on the File menu.
-
-   To suspend Emacs, type `C-z' (`suspend-emacs').  This takes you back
-to the shell from which you invoked Emacs.  You can resume Emacs with
-the shell command `%xemacs' in most common shells.
-
-   On systems that do not support suspending programs, `C-z' starts an
-inferior shell that communicates directly with the terminal.  Emacs
-waits until you exit the subshell.  (The way to do that is probably
-with `C-d' or `exit', but it depends on which shell you use.)  The only
-way on these systems to get back to the shell from which Emacs was run
-(to log out, for example) is to kill Emacs.
-
-   Suspending also fails if you run Emacs under a shell that doesn't
-support suspending programs, even if the system itself does support it.
-In such a case, you can set the variable `cannot-suspend' to a
-non-`nil' value to force `C-z' to start an inferior shell.  (One might
-also describe Emacs's parent shell as "inferior" for failing to support
-job control properly, but that is a matter of taste.)
-
-   When Emacs communicates directly with an X server and creates its own
-dedicated X windows, `C-z' has a different meaning.  Suspending an
-applications that uses its own X windows is not meaningful or useful.
-Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
-temporarily closes up the selected Emacs frame.  The way to get back to
-a shell window is with the window manager.
-
-   To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs').  A
-two-character key is used for this to make it harder to type.  Selecting
-the Exit XEmacs option of the File menu is an alternate way of issuing
-the command.
-
-   Unless a numeric argument is used, this command first offers to save
-any modified file-visiting buffers.  If you do not save all buffers,
-you are asked for reconfirmation with `yes' before killing Emacs, since
-any changes not saved will be lost forever.  If any subprocesses are
-still running, `C-x C-c' asks you to confirm killing them, since killing
-Emacs will kill the subprocesses immediately.
-
-   There is no way to restart an Emacs session once you have killed it.
-You can, however, arrange for Emacs to record certain session
-information, such as which files are visited, when you kill it, so that
-the next time you restart Emacs it will try to visit the same files and
-so on.
-
-   The operating system usually listens for certain special characters
-whose meaning is to kill or suspend the program you are running.  This
-operating system feature is turned off while you are in Emacs.  The
-meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
-use of `C-z' and `C-c' on several operating systems as the characters
-for stopping or killing a program, but that is their only relationship
-with the operating system.  You can customize these keys to run any
-commands of your choice (*note Keymaps::).
-
-\1f
-File: xemacs.info,  Node: Command Switches,  Next: Startup Paths,  Prev: Exiting,  Up: Top
-
-Command Line Switches and Arguments
-===================================
-
-   XEmacs supports command line arguments you can use to request
-various actions when invoking Emacs.  The commands are for compatibility
-with other editors and for sophisticated activities.  If you are using
-XEmacs under the X window system, you can also use a number of standard
-Xt command line arguments. Command line arguments are not usually
-needed for editing with Emacs; new users can skip this section.
-
-   Many editors are designed to be started afresh each time you want to
-edit.  You start the editor to edit one file; then exit the editor.  The
-next time you want to edit either another file or the same one, you
-start the editor again.  Under these circumstances, it makes sense to
-use a command line argument to say which file to edit.
-
-   The recommended way to use XEmacs is to start it only once, just
-after you log in, and do all your editing in the same Emacs process.
-Each time you want to edit a file, you visit it using the existing
-Emacs.  Emacs creates a new buffer for each file, and (unless you kill
-some of the buffers) Emacs eventually has many files in it ready for
-editing.  Usually you do not kill the Emacs process until you are about
-to log out.  Since you usually read files by typing commands to Emacs,
-command line arguments for specifying a file when Emacs is started are
-seldom needed.
-
-   Emacs accepts command-line arguments that specify files to visit,
-functions to call, and other activities and operating modes.  If you
-are running XEmacs under the X window system, a number of standard Xt
-command line arguments are available, as well as a few X parameters
-that are XEmacs-specific.
-
-   Options with long names with a single initial hyphen are also
-recognized with the GNU double initial hyphen syntax.  (The reverse is
-not true.)
-
-   The following subsections list:
-   * Command line arguments that you can always use
-
-   * Command line arguments that have to appear at the beginning of the
-     argument list
-
-   * Command line arguments that are only relevant if you are running
-     XEmacs under X
-
-Command Line Arguments for Any Position
----------------------------------------
+Installing the Sumo Packages:
+=============================

 
 

-   Command line arguments are processed in the order they appear on the
-command line; however, certain arguments (the ones in the second table)
-must be at the front of the list if they are used.
-
-   Here are the arguments allowed:
-
-`FILE'
-     Visit FILE using `find-file'.  *Note Visiting::.
-
-`+LINENUM FILE'
-     Visit FILE using `find-file', then go to line number LINENUM in it.
-
-`-load FILE'
-`-l FILE'
-     Load a file FILE of Lisp code with the function `load'.  *Note
-     Lisp Libraries::.
-
-`-funcall FUNCTION'
-`-f FUNCTION'
-     Call Lisp function FUNCTION with no arguments.
+Those with little time, cheap connections and plenty of disk space can
+install all the packages at once using the sumo tarballs.  Download the
+file: `xemacs-sumo.tar.gz'

 
 

-`-eval FUNCTION'
-     Interpret the next argument as a Lisp expression, and evaluate it.
-     You must be very careful of the shell quoting here.
+   For an XEmacs compiled with Mule you also need:
+`xemacs-mule-sumo.tar.gz'

 
 

-`-insert FILE'
-`-i FILE'
-     Insert the contents of FILE into the current buffer.  This is like
-     what `M-x insert-buffer' does; *Note Misc File Ops::.
+   N.B. They are called 'Sumo Tarballs' for good reason. They are
+currently about 19MB and 4.5MB (gzipped) respectively.

 
 

-`-kill'
-     Exit from Emacs without asking for confirmation.  Always the last
-     argument processed, no matter where it appears in the command line.
-
-`-version'
-`-V'
-     Prints version information.  This implies `-batch'.
-
-          % xemacs -version
-          XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
-
-`-help'
-     Prints a summary of command-line options and then exits.
-
-Command Line Arguments (Beginning of Line Only)
------------------------------------------------
-
-   The following arguments are recognized only at the beginning of the
-command line.  If more than one of them appears, they must appear in the
-order in which they appear in this table.
-
-`--show-dump-id'
-`-sd'
-     Print the ID for the new portable dumper's dump file on the
-     terminal and exit.  (Prints an error message and exits if XEmacs
-     was not configured `--pdump'.)
+   Install them by:

 
 

-`--no-dump-file'
-`-nd'
-     Don't load the dump file.  Roughly equivalent to old temacs.
-     (Ignored if XEmacs was not configured `--pdump'.)
-
-`--terminal FILE'
-`-t FILE'
-     Use FILE instead of the terminal for input and output.  This
-     implies the `-nw' option, documented below.
-
-`-batch'
-     Run Emacs in "batch mode", which means that the text being edited
-     is not displayed and the standard Unix interrupt characters such as
-     `C-z' and `C-c' continue to have their normal effect.  Emacs in
-     batch mode outputs to `stderr' only what would normally be printed
-     in the echo area under program control.
-
-     Batch mode is used for running programs written in Emacs Lisp from
-     shell scripts, makefiles, and so on.  Normally the `-l' switch or
-     `-f' switch will be used as well, to invoke a Lisp program to do
-     the batch processing.
-
-     `-batch' implies `-q' (do not load an init file).  It also causes
-     Emacs to kill itself after all command switches have been
-     processed.  In addition, auto-saving is not done except in buffers
-     for which it has been explicitly requested.
-
-`--no-windows'
-`-nw'
-     Start up XEmacs in TTY mode (using the TTY XEmacs was started
-     from), rather than trying to connect to an X display.  Note that
-     this happens automatically if the `DISPLAY' environment variable
-     is not set.
-
-`-debug-init'
-     Enter the debugger if an error in the init file occurs.
-
-`-debug-paths'
-     Displays information on how XEmacs constructs the various paths
-     into its hierarchy on startup.  (See also *note Startup Paths::.)
-
-`-unmapped'
-     Do not map the initial frame.  This is useful if you want to start
-     up XEmacs as a server (e.g. for gnuserv screens or external client
-     widgets).
-
-`-no-init-file'
-`-q'
-     Do not load your Emacs init file.  *Note Init File::.
-
-`-no-site-file'
-     Do not load the site-specific init file `lisp/site-start.el'.
-
-`-no-autoloads'
-     Do not load global symbol files (`auto-autoloads') at startup.
-     This implies `-vanilla'.
-
-`-no-early-packages'
-     Do not process early packages.  (For more information on startup
-     issues concerning the package system, *Note Startup Paths::.)
-
-`-vanilla'
-     This is equivalent to `-q -no-site-file -no-early-packages'.
-
-`-user-init-file FILE'
-     Load FILE as your Emacs init file instead of
-     `~/.xemacs/init.el'/`~/.emacs'.
-
-`-user-init-directory DIRECTORY'
-     Use DIRECTORY as the location of your early package hierarchies
-     and the various user-specific initialization files.
-
-`-user USER'
-`-u USER'
-     Equivalent to `-user-init-file ~USER/.xemacs/init.el
-     -user-init-directory ~USER/.xemacs', or `-user-init-file
-     ~USER/.emacs -user-init-directory ~USER/.xemacs', whichever init
-     file comes first.  *Note Init File::.
-
-   Note that the init file can get access to the command line argument
-values as the elements of a list in the variable `command-line-args'.
-(The arguments in the second table above will already have been
-processed and will not be in the list.)  The init file can override the
-normal processing of the other arguments by setting this variable.
-
-   One way to use command switches is to visit many files automatically:
-
-     xemacs *.c
-
-passes each `.c' file as a separate argument to Emacs, so that Emacs
-visits each file (*note Visiting::).
-
-   Here is an advanced example that assumes you have a Lisp program file
-called `hack-c-program.el' which, when loaded, performs some useful
-operation on the current buffer, expected to be a C program.
-
-     xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
-
-Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
-makes changes in the visited file), save `foo.c' (note that
-`save-buffer' is the function that `C-x C-s' is bound to), and then
-exit to the shell from which the command was executed.  `-batch'
-guarantees there will be no problem redirecting output to `log',
-because Emacs will not assume that it has a display terminal to work
-with.
-
-Command Line Arguments (for XEmacs Under X)
--------------------------------------------
-
-   If you are running XEmacs under X, a number of options are available
-to control color, border, and window title and icon name:
-
-`-title TITLE'
-`-wn TITLE'
-`-T TITLE'
-     Use TITLE as the window title. This sets the `frame-title-format'
-     variable, which controls the title of the X window corresponding
-     to the selected frame.  This is the same format as
-     `mode-line-format'.
+   `cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET'

 
 

-`-iconname TITLE'
-`-in TITLE'
-     Use TITLE as the icon name. This sets the
-     `frame-icon-title-format' variable, which controls the title of
-     the icon corresponding to the selected frame.
+   Or, if you have GNU tar:

 
 

-`-mc COLOR'
-     Use COLOR as the mouse color.
+   `cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET'

 
 

-`-cr COLOR'
-     Use COLOR as the text-cursor foreground color.
+   As the Sumo tarballs are not regenerated as often as the individual
+packages, it is recommended that you use the automatic package tools
+afterwards to pick up any recent updates.

 
 

-`-private'
-     Install a private colormap for XEmacs.
+\1f
+File: xemacs.info,  Node: Which Packages,  Next: Removing Packages,  Prev: Sumo,  Up: Installing Packages

 
 

-   In addition, XEmacs allows you to use a number of standard Xt
-command line arguments.
+Which Packages to Install:
+==========================

 
 

-`-background COLOR'
-`-bg COLOR'
-     Use COLOR as the background color.
+This is difficult to say. When in doubt install a package. If you
+administrate a big site it might be a good idea to just install
+everything. A good minimal set of packages for XEmacs-latin1 would be

 
 

-`-bordercolor COLOR'
-`-bd COLOR'
-     Use COLOR as the border color.
+   xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
+edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
+text-modes, time, mailcrypt

 
 

-`-borderwidth WIDTH'
-`-bw WIDTH'
-     Use WIDTH as the border width.
+   If you are using the XEmacs package tools, don't forget to do:

 
 

-`-display DISPLAY'
-`-d DISPLAY'
-     When running under the X window system, create the window
-     containing the Emacs frame on the display named DISPLAY.
+       Packages -> Add Required

 
 

-`-foreground COLOR'
-`-fg COLOR'
-     Use COLOR as the foreground color.
+   To make sure you have everything that the packages you have chosen to
+install need.

 
 

-`-font NAME'
-`-fn NAME'
-     Use NAME as the default font.
+   See also *Note Available Packages:: for further descriptions of the
+individual packages.

 
 

-`-geometry SPEC'
-`-geom SPEC'
-`-g SPEC'
-     Use the geometry (window size and/or position) specified by SPEC.
+\1f
+File: xemacs.info,  Node: Removing Packages,  Prev: Which Packages,  Up: Installing Packages

 
 

-`-iconic'
-     Start up iconified.
+Removing Packages:
+==================

 
 

-`-rv'
-     Bring up Emacs in reverse video.
+Because the exact files and their locations contained in a package may
+change it is recommended to remove a package first before installing a
+new version. In order to facilitate removal each package contains an
+`pgkinfo/MANIFEST.pkgname' file which list all the files belonging to
+the package.

 
 

-`-name NAME'
-     Use the resource manager resources specified by NAME.  The default
-     is to use the name of the program (`argv[0]') as the resource
-     manager name.
+   No need to panic, you don't have to go through the
+`pkinfo/MANIFEST.pkgname' and manually delete the files.  Instead, use
+`M-x package-get-delete-package RET'.

 
 

-`-xrm'
-     Read something into the resource database for this invocation of
-     Emacs only.
+   Note that the interactive package tools included with XEmacs already
+do this for you.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Startup Paths,  Next: Packages,  Prev: Command Switches,  Up: Top
+File: xemacs.info,  Node: Building Packages,  Next: Local.rules File,  Prev: Installing Packages,  Up: Packages
+
+Building Packages:
+==================

 
 

-How XEmacs finds Directories and Files
-======================================
+Currently, source packages are only available via anonymous CVS.  See
+<http://cvs.xemacs.org/> for details of checking out the
+`xemacs-packages' module.

 
 

-   XEmacs deals with a multitude of files during operation.  These files
-are spread over many directories, and XEmacs determines the location of
-most of these directories at startup and organizes them into various
-paths.  (A "path", for the purposes of this section, is simply a list
-of directories which XEmacs searches successively in order to locate a
-file.)
+Prerequisites for Building Source Packages
+------------------------------------------

 
 

-XEmacs Directory Hierarchies
-----------------------------
+`GNU cp'
+
+`GNU install'
+     (or a BSD compatible install program).
+
+`GNU make'
+     (3.75 or later preferred).
+
+`makeinfo'
+     (4.2 from GNU texinfo 4.2 or later required).
+
+`GNU tar'
+     (or equivalent).
+
+`GNU gzip'
+     (or equivalent).
+
+`A properly configured `Local.rules' file.'
+     *Note Local.rules File::.
+And of course, XEmacs 21.0 or higher.
+
+What You Can Do With Source Packages
+------------------------------------
+
+The packages CVS sources are most useful for creating XEmacs package
+tarballs for installation into your own XEmacs installations or for
+distributing to others.
+
+   For a list and description of the different `Makefile' targets,
+*Note Makefile Targets: (lispref)Makefile Targets.
+
+\1f
+File: xemacs.info,  Node: Local.rules File,  Next: Available Packages,  Prev: Building Packages,  Up: Packages
+
+The Local.rules File:
+=====================
+
+This file is used when building and installing packages from source.  In
+the top level of the CVS module, `packages', contains the file,
+`Local.rules.template'.  Simply copy that to `Local.rules' and edit it
+to suit your needs.
+
+   For a complete discussion of the `Local.rules' file, *Note
+Local.rules File: (lispref)Local.rules File.
+
+\1f
+File: xemacs.info,  Node: Available Packages,  Prev: Local.rules File,  Up: Packages
+
+Available Packages:
+===================
+
+This section lists the Lisp packages that are currently available from
+xemacs.org and it's mirrors.  If a particular package that you are
+looking for isn't here, please send a message to the XEmacs Beta list
+<xemacs-beta@xemacs.org>.
+
+   This data is up to date as of June 27, 2003.
+
+Normal Packages
+---------------
+
+A very broad selection of elisp packages.
+
+`Sun'
+     Support for Sparcworks.
+
+`ada'
+     Ada language support.
+
+`apel'
+     A Portable Emacs Library.  Used by XEmacs MIME support.
+
+`auctex'
+     Basic TeX/LaTeX support.
+
+`bbdb'
+     The Big Brother Data Base: a rolodex-like database program.
+
+`build'
+     Build XEmacs using custom widgets.
+
+`c-support'
+     Basic single-file add-ons for editing C code.
+
+`calc'
+     Emacs calculator.
+
+`calendar'
+     Calendar and diary support.
+
+`cc-mode'
+     C, C++ and Java language support.
+
+`clearcase'
+     Support for the Clearcase version control system.
+
+`cookie'
+     "Fortune cookie"-style messages. Includes Spook (suspicious
+     phrases) and Yow (Zippy quotes).
+
+`crisp'
+     Crisp/Brief emulation.
+
+`debug'
+     GUD, gdb, dbx debugging support.
+
+`dictionary'
+     Interface to RFC2229 dictionary servers.
+
+`dired'
+     The DIRectory EDitor is for manipulating, and running commands on
+     files in a directory.
+
+`docbookide'
+     DocBook editing support.
+
+`ecrypto'
+     Crypto functionality in Emacs Lisp.
+
+`edebug'
+     A Lisp debugger.
+
+`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.
+
+`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.
+
+`ess'
+     ESS: Emacs Speaks Statistics.
+
+`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).
+
+`fortran-modes'
+     Fortran language support.
+
+`frame-icon'
+     Provide a WM icon based on major mode.
+
+`fsf-compat'
+     GNU Emacs compatibility files.
+
+`games'
+     Tetris, Sokoban, and Snake.
+
+`general-docs'
+     General documentation.  Presently, empty.
+
+`gnats'
+     XEmacs bug reports.
+
+`gnus'
+     The Gnus Newsreader and Mailreader.
+
+`haskell-mode'
+     Haskell language support.
+
+`hm--html-menus'
+     HTML editing.
+
+`ibuffer'
+     Advanced replacement for buffer-menu.
+
+`idlwave'
+     Editing and Shell mode for the Interactive Data Language.
+
+`igrep'
+     Enhanced front-end for Grep.
+
+`ilisp'
+     Front-end for interacting with Inferior Lisp (external lisps).
+
+`ispell'
+     Spell-checking with ispell.
+
+`jde'
+     Java language and development support.
+
+`liece'
+     IRC (Internet Relay Chat) client for Emacs.
+
+`mail-lib'
+     Fundamental lisp files for providing email support.
+
+`mailcrypt'
+     Support for messaging encryption with PGP.
+
+`mew'
+     Messaging in an Emacs World; a MIME-based email program.
+
+`mh-e'
+     Front end support for MH.
+
+`mine'
+     Elisp implementation of the game 'Minehunt'.

 
 

-   Many of the files XEmacs looks for are located within the XEmacs
-installation itself.  However, there are several views of what actually
-constitutes the "XEmacs installation": XEmacs may be run from the
-compilation directory, it may be installed into arbitrary directories,
-spread over several directories unrelated to each other.  Moreover, it
-may subsequently be moved to a different place.  (This last case is not
-as uncommon as it sounds.  Binary kits work this way.)  Consequently,
-XEmacs has quite complex procedures in place to find directories, no
-matter where they may be hidden.
-
-   XEmacs will always respect directory options passed to `configure'.
-However, if it cannot locate a directory at the configured place, it
-will initiate a search for the directory in any of a number of
-"hierarchies" rooted under a directory which XEmacs assumes contain
-parts of the XEmacs installation; it may locate several such hierarchies
-and search across them.  (Typically, there are just one or two
-hierarchies: the hierarchy where XEmacs was or will be installed, and
-the one where it is being built.)  Such a directory containing a
-hierarchy is called a "root".  Whenever this section refers to a
-directory using the shorthand `<root>', it means that XEmacs searches
-for it under all hierarchies XEmacs was able to scrounge up.  In a
-running XEmacs, the hierarchy roots are stored in the variable
-`emacs-roots'.
-
-Package Hierarchies
+`misc-games'
+     Other amusements and diversions.
+
+`mmm-mode'
+     Support for Multiple Major Modes within a single buffer.
+
+`net-utils'
+     Miscellaneous Networking Utilities.  This is a single-file package
+     and files may be deleted at will.
+
+`ocaml'
+     Objective Caml editing support.
+
+`os-utils'
+     Miscellaneous single-file O/S utilities, for printing, archiving,
+     compression, remote shells, etc.
+
+`pc'
+     PC style interface emulation.
+
+`pcl-cvs'
+     CVS frontend.
+
+`pcomplete'
+     Provides programmatic completion.
+
+`perl-modes'
+     Perl language support.
+
+`pgg'
+     Emacs interface to various PGP implementations.
+
+`prog-modes'
+     Miscellaneous single-file lisp files for various programming
+     languages.
+
+`ps-print'
+     Print buffers to PostScript printers.
+
+`psgml'
+     Validated HTML/SGML editing.
+
+`psgml-dtds'
+     A collection of DTDs for psgml.  Note that this package is
+     deprecated and will be removed in the future, most likely Q2/2003.
+     Instead of using this, you should install needed DTDs yourself.
+
+`python-modes'
+     Python language support.
+
+`reftex'
+     Emacs support for LaTeX cross-references, citations.
+
+`rmail'
+     An obsolete Emacs mailer.  If you do not already use it don't
+     start.
+
+`ruby-modes'
+     Ruby language support.
+
+`sasl'
+     Simple Authentication and Security Layer (SASL) library.
+
+`scheme'
+     Front-end support for Inferior Scheme.
+
+`semantic'
+     Semantic bovinator.
+
+`sgml'
+     SGML/Linuxdoc-SGML editing.
+
+`sh-script'
+     Support for editing shell scripts.
+
+`sieve'
+     Manage Sieve email filtering scripts.
+
+`slider'
+     User interface tool.
+
+`sml-mode'
+     Standard ML editing support.
+
+`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.
+
+`tm'
+     Emacs MIME support. Not needed for Gnus >= 5.8.0
+
+`tooltalk'
+     Support for building with Tooltalk.
+
+`tpu'
+     DEC EDIT/TPU support.
+
+`tramp'
+     Remote shell-based file editing.  This is similar to EFS or
+     Ange-FTP, but works with rsh/ssh and rcp/scp.
+
+`vc'
+     Version Control for Free systems.
+
+`vc-cc'
+     Version Control for ClearCase.  This package will shortly be
+     replaced with clearcase.el
+
+`vhdl'
+     Support for VHDL.
+
+`view-process'
+     A Unix process browsing tool.
+
+`viper'
+     VI emulation support.
+
+`vm'
+     An Emacs mailer.
+
+`w3'
+     A Web browser.
+
+`x-symbol'
+     Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts.
+
+`xemacs-base'
+     Fundamental XEmacs support.  Install this unless you wish a totally
+     naked XEmacs.
+
+`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.
+
+`xslide'
+     XSL editing support.
+
+`xslt-process'
+     A minor mode for (X)Emacs which allows running an XSLT processor
+     on a buffer.
+
+`zenirc'
+     ZENIRC IRC Client.
+
+Mule Support (mule)

 -------------------
 
 -------------------
 

-   Many relevant directories and files XEmacs uses are actually not
-part of the core installation.  They are part of any of the many
-packages usually installed on top of an XEmacs installation.  (*Note
-Packages::.)  Hence, they play a prominent role in the various paths
-XEmacs sets up.
-
-   XEmacs locates packages in any of a number of package hierarchies.
-Package hierarchies fall into three groups: "early", "late", and "last",
-according to the relative location at which they show up in the various
-XEmacs paths.  Early package hierarchies are at the very front, late
-ones somewhere in the middle, and last hierarchies are (you guessed it)
-last.
-
-   By default, XEmacs expects an early package hierarchy in the
-subdirectory `.xemacs/xemacs-packages' of the user's home directory.
-
-   Moreover, XEmacs expects late hierarchies in the subdirectories
-`site-packages', `mule-packages', and `xemacs-packages' (in that order)
-of the `<root>/lib/xemacs' subdirectory of one of the installation
-hierarchies.  (If you run in-place, these are direct subdirectories of
-the build directory.)  Furthermore, XEmacs will also search these
-subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
-prefer directories found there.
-
-   By default, XEmacs does not have a pre-configured last package
-hierarchy.  Last hierarchies are primarily for using package hierarchies
-of outdated versions of XEmacs as a fallback option.  For example, it is
-possible to run XEmacs 21 with the 20.4 package hierarchy as a last
-hierarchy.
+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.

 
 

-   It is possible to specify at configure-time the location of the
-various package hierarchies with the `--package-path' option to
-configure.  The early, late, and last components of the package path
-are separated by double instead of single colons.  If all three
-components are present, they locate the early, late, and last package
-hierarchies respectively.  If two components are present, they locate
-the early and late hierarchies.  If only one component is present, it
-locates the late hierarchy.  At run time, the package path may also be
-specified via the `EMACSPACKAGEPATH' environment variable.
+`edict'
+     Lisp Interface to EDICT, Kanji Dictionary.

 
 

-   An XEmacs package is laid out just like a normal installed XEmacs
-lisp directory.  It may have `lisp', `etc', `info', and `lib-src'
-subdirectories.  XEmacs adds these at appropriate places within the
-various system-wide paths.
+`egg-its'
+     Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to
+     XEmacs build.

 
 

-   There may be any number of package hierarchy directories.
+`latin-unity'
+     Unify character sets in a buffer. When characters belong to
+     disjoint character sets, this attempts to translate the characters
+     so that they belong to one character set. If the buffer coding
+     system is not sufficient, this suggests different coding systems.

 
 

-Directories and Paths
----------------------
+`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. (This isn't an English dictionary program)

 
 

-   Here is a list of the various directories and paths XEmacs tries to
-locate during startup.  XEmacs distinguishes between directories and
-paths specific to "version", "site", and "architecture" when looking
-for them.
-
-`version-specific'
-     directories are specific to the version of XEmacs they belong to
-     and typically reside under `<root>/lib/xemacs-<VERSION>'.
-
-`site-specific'
-     directories are independent of the version of XEmacs they belong
-     to and typically reside under `<root>/lib/xemacs'
-
-`architecture-specific'
-     directories are specific both to the version of XEmacs and the
-     architecture it runs on and typically reside under
-     `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
-
-   During installation, all of these directories may also reside
-directly under `<root>', because that is where they are in the XEmacs
-tarball.
-
-   If XEmacs runs with the `-debug-paths' option (*note Command
-Switches::), it will print the values of these variables, hopefully
-aiding in debugging any problems which come up.
-
-`lisp-directory'
-     Contains the version-specific location of the Lisp files that come
-     with the core distribution of XEmacs.  XEmacs will search it
-     recursively to a depth of 1 when setting up `load-path'.
-
-`load-path'
-     Is where XEmacs searches for XEmacs Lisp files with commands like
-     `load-library'.  It contains the package lisp directories (see
-     further down) and the version-specific core Lisp directories.  If
-     the environment variable `EMACSLOADPATH' is set at startup, its
-     directories are prepended to `load-path'.
-
-`Info-directory-list'
-     Contains the location of info files.  (See *Note (info)::.)  It
-     contains the package info directories and the version-specific core
-     documentation.  Moreover, XEmacs will add `/usr/info',
-     `/usr/local/info' as well as the directories of the environment
-     variable `INFOPATH' to `Info-directory-list'.
-
-`exec-directory'
-     Is the directory of architecture-dependent files that come with
-     XEmacs, especially executable programs intended for XEmacs to
-     invoke.
-
-`exec-path'
-     Is the path for executables which XEmacs may want to start.  It
-     contains the package executable paths as well as `exec-directory',
-     and the directories of the environment variables `PATH' and
-     `EMACSPATH'.
-
-`doc-directory'
-     Is the directory containing the architecture-specific `DOC' file
-     that contains documentation for XEmacs' commands.
-
-`data-directory'
-     Is the version-specific directory that contains core data files
-     XEmacs uses.  It may be initialized from the `EMACSDATA'
-     environment variable.
-
-`data-directory-list'
-     Is the path where XEmacs looks for data files.  It contains
-     package data directories as well as `data-directory'.
-
-\1f
-File: xemacs.info,  Node: Basic,  Next: Undo,  Prev: Packages,  Up: Top
-
-Basic Editing Commands
-**********************
-
-   We now give the basics of how to enter text, make corrections, and
-save the text in a file.  If this material is new to you, you might
-learn it more easily by running the Emacs learn-by-doing tutorial.  To
-use the tutorial, run Emacs and type `Control-h t'
-(`help-with-tutorial').  You can also use Tutorials item from the Help
-menu.
-
-   XEmacs comes with many translations of tutorial.  If your XEmacs is
-with MULE and you set up language environment correctly, XEmacs chooses
-right tutorial when available (*note Language Environments::).  If you
-want specific translation, give `C-h t' a prefix argument, like `C-u
-C-h t'.
-
-   To clear the screen and redisplay, type `C-l' (`recenter').
+`mule-base'
+     Basic Mule support.  Must be installed prior to building with Mule.
+
+`mule-ucs'
+     Extended coding systems (including Unicode) for XEmacs.
+
+`skk'
+     Another Japanese Language Input Method.  Can be used without a
+     separate process running as a dictionary server.
+
+\1f
+File: xemacs.info,  Node: Abbrevs,  Next: Picture,  Prev: Running,  Up: Top
+
+Abbrevs
+*******
+
+An "abbrev" is a word which "expands" into some different text.
+Abbrevs are defined by the user to expand in specific ways.  For
+example, you might define `foo' as an abbrev expanding to `find outer
+otter'.  With this abbrev defined, you would be able to get `find outer
+otter ' into the buffer by typing `f o o <SPC>'.
+
+   Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
+Disabling Abbrev mode does not cause abbrev definitions to be discarded,
+but they do not expand until Abbrev mode is enabled again.  The command
+`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
+turns Abbrev mode on if the argument is positive, off otherwise.  *Note
+Minor Modes::.  `abbrev-mode' is also a variable; Abbrev mode is on
+when the variable is non-`nil'.  The variable `abbrev-mode'
+automatically becomes local to the current buffer when it is set.
+
+   Abbrev definitions can be "mode-specific"--active only in one major
+mode.  Abbrevs can also have "global" definitions that are active in
+all major modes.  The same abbrev can have a global definition and
+various mode-specific definitions for different major modes.  A
+mode-specific definition for the current major mode overrides a global
+definition.
+
+   You can define Abbrevs interactively during an editing session.  You
+can also save lists of abbrev definitions in files and reload them in
+later sessions.  Some users keep extensive lists of abbrevs that they
+load in every session.
+
+   A second kind of abbreviation facility is called the "dynamic
+expansion".  Dynamic abbrev expansion happens only when you give an
+explicit command and the result of the expansion depends only on the
+current contents of the buffer.  *Note Dynamic Abbrevs::.

 
 * Menu:
 
 
 * Menu:
 

+* Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
+* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
+* Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
+* Saving Abbrevs::    Saving the entire list of abbrevs for another session.
+* Dynamic Abbrevs::   Abbreviations for words already in the buffer.

 
 

-* Inserting Text::      Inserting text by simply typing it.
-* Moving Point::        How to move the cursor to the place where you want to
-                         change something.
-* Erasing::            Deleting and killing text.
-* Files: Basic Files.   Visiting, creating, and saving files.
-* Help: Basic Help.     Asking what a character does.
-* Blank Lines::                Commands to make or delete blank lines.
-* Continuation Lines::  Lines too wide for the screen.
-* Position Info::       What page, line, row, or column is point on?
-* Arguments::          Numeric arguments for repeating a command.
+\1f
+File: xemacs.info,  Node: Defining Abbrevs,  Next: Expanding Abbrevs,  Prev: Abbrevs,  Up: Abbrevs
+
+Defining Abbrevs
+================
+
+`C-x a g'
+     Define an abbrev to expand into some text before point
+     (`add-global-abbrev').
+
+`C-x a l'
+     Similar, but define an abbrev available only in the current major
+     mode (`add-mode-abbrev').
+
+`C-x a i g'
+     Define a word in the buffer as an abbrev
+     (`inverse-add-global-abbrev').
+
+`C-x a i l'
+     Define a word in the buffer as a mode-specific abbrev
+     (`inverse-add-mode-abbrev').
+
+`M-x kill-all-abbrevs'
+     After this command, no abbrev definitions remain in effect.
+
+   The usual way to define an abbrev is to enter the text you want the
+abbrev to expand to, position point after it, and type `C-x a g'
+(`add-global-abbrev').  This reads the abbrev itself using the
+minibuffer, and then defines it as an abbrev for one or more words
+before point.  Use a numeric argument to say how many words before point
+should be taken as the expansion.  For example, to define the abbrev
+`foo' as in the example above, insert the text `find outer otter', then
+type
+`C-u 3 C-x a g f o o <RET>'.
+
+   An argument of zero to `C-x a g' means to use the contents of the
+region as the expansion of the abbrev being defined.
+
+   The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
+mode-specific abbrev.  Mode-specific abbrevs are active only in a
+particular major mode.  `C-x a l' defines an abbrev for the major mode
+in effect at the time `C-x a l' is typed.  The arguments work the same
+way they do for `C-x a g'.
+
+   If the text of an abbrev you want is already in the buffer instead of
+the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
+instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
+instead of `C-x a l'.  These commands are called "inverse" because they
+invert the meaning of the argument found in the buffer and the argument
+read using the minibuffer.
+
+   To change the definition of an abbrev, just add the new definition.
+You will be asked to confirm if the abbrev has a prior definition.  To
+remove an abbrev definition, give a negative argument to `C-x a g' or
+`C-x a l'.  You must choose the command to specify whether to kill a
+global definition or a mode-specific definition for the current mode,
+since those two definitions are independent for one abbrev.
+
+   `M-x kill-all-abbrevs' removes all existing abbrev definitions.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Inserting Text,  Next: Moving Point,  Up: Basic
+File: xemacs.info,  Node: Expanding Abbrevs,  Next: Editing Abbrevs,  Prev: Defining Abbrevs,  Up: Abbrevs
+
+Controlling Abbrev Expansion
+============================
+
+An abbrev expands whenever it is in a buffer just before point and you
+type a self-inserting punctuation character (<SPC>, comma, etc.).  Most
+often an abbrev is used by inserting the abbrev followed by punctuation.
+
+   Abbrev expansion preserves case; thus, `foo' expands into `find
+outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
+OTTER' or `Find Outer Otter' according to the variable
+`abbrev-all-caps' (a non-`nil' value chooses the first of the two
+expansions).
+
+   Two commands are available to control abbrev expansion:
+
+`M-''
+     Separate a prefix from a following abbrev to be expanded
+     (`abbrev-prefix-mark').
+
+`C-x a e'
+     Expand the abbrev before point (`expand-abbrev').  This is
+     effective even when Abbrev mode is not enabled.
+
+`M-x unexpand-abbrev'
+     Undo last abbrev expansion.
+
+`M-x expand-region-abbrevs'
+     Expand some or all abbrevs found in the region.
+
+   You may wish to expand an abbrev with a prefix attached.  For
+example, if `cnst' expands into `construction', you may want to use it
+to enter `reconstruction'.  It does not work to type `recnst', because
+that is not necessarily a defined abbrev.  Instead, you can use the
+command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the
+abbrev `cnst'.  First, insert `re'.  Then type `M-''; this inserts a
+minus sign in the buffer to indicate that it has done its work.  Then
+insert the abbrev `cnst'.  The buffer now contains `re-cnst'.  Now
+insert a punctuation character to expand the abbrev `cnst' into
+`construction'.  The minus sign is deleted at this point by `M-''.  The
+resulting text is the desired `reconstruction'.
+
+   If you actually want the text of the abbrev in the buffer, rather
+than its expansion, insert the following punctuation with `C-q'.  Thus,
+`foo C-q -' leaves `foo-' in the buffer.
+
+   If you expand an abbrev by mistake, you can undo the expansion
+(replace the expansion by the original abbrev text) with `M-x
+unexpand-abbrev'.  You can also use `C-_' (`undo') to undo the
+expansion; but that will first undo the insertion of the punctuation
+character.
+
+   `M-x expand-region-abbrevs' searches through the region for defined
+abbrevs, and  offers to replace each one it finds with its expansion.
+This command is useful if you have typed text using abbrevs but forgot
+to turn on Abbrev mode first.  It may also be useful together with a
+special set of abbrev definitions for making several global
+replacements at once.  The command is effective even if Abbrev mode is
+not enabled.

 
 

-Inserting Text
-==============
+\1f
+File: xemacs.info,  Node: Editing Abbrevs,  Next: Saving Abbrevs,  Prev: Expanding Abbrevs,  Up: Abbrevs

 
 

-   To insert printing characters into the text you are editing, just
-type them.  This inserts the characters you type into the buffer at the
-cursor (that is, at "point"; *note Point::).  The cursor moves forward,
-and any text after the cursor moves forward too.  If the text in the
-buffer is `FOOBAR', with the cursor before the `B', then if you type
-`XX', you get `FOOXXBAR', with the cursor still before the `B'.
-
-   To "delete" text you have just inserted, use <BS>.  <BS> deletes the
-character _before_ the cursor (not the one that the cursor is on top of
-or under; that is the character AFTER the cursor).  The cursor and all
-characters after it move backwards.  Therefore, if you type a printing
-character and then type <BS>, they cancel out.
-
-   To end a line and start typing a new one, type <RET>.  This inserts
-a newline character in the buffer.  If point is in the middle of a
-line, <RET> splits the line.  Typing <DEL> when the cursor is at the
-beginning of a line deletes the preceding newline, thus joining the
-line with the preceding line.
-
-   Emacs can split lines automatically when they become too long, if you
-turn on a special minor mode called "Auto Fill" mode.  *Note Filling::,
-for how to use Auto Fill mode.
-
-   If you prefer to have text characters replace (overwrite) existing
-text rather than shove it to the right, you can enable Overwrite mode,
-a minor mode.  *Note Minor Modes::.
-
-   Direct insertion works for printing characters and <SPC>, but other
-characters act as editing commands and do not insert themselves.  If you
-need to insert a control character or a character whose code is above
-200 octal, you must "quote" it by typing the character `Control-q'
-(`quoted-insert') first.  (This character's name is normally written
-`C-q' for short.)  There are two ways to use `C-q':
-
-   * `C-q' followed by any non-graphic character (even `C-g') inserts
-     that character.
-
-   * `C-q' followed by a sequence of octal digits inserts the character
-     with the specified octal character code.  You can use any number of
-     octal digits; any non-digit terminates the sequence.  If the
-     terminating character is <RET>, it serves only to terminate the
-     sequence; any other non-digit is itself used as input after
-     terminating the sequence.  (The use of octal sequences is disabled
-     in ordinary non-binary Overwrite mode, to give you a convenient
-     way to insert a digit instead of overwriting with it.)
-
-A numeric argument to `C-q' specifies how many copies of the quoted
-character should be inserted (*note Arguments::).
-
-   Customization information: <DEL>, in most modes, runs the command
-`backward-or-forward-delete-char'; <RET> runs the command `newline',
-and self-inserting printing characters run the command `self-insert',
-which inserts whatever character was typed to invoke it.  Some major
-modes rebind <DEL> to other commands.
-
-\1f
-File: xemacs.info,  Node: Moving Point,  Next: Erasing,  Prev: Inserting Text,  Up: Basic
-
-Changing the Location of Point
-==============================
-
-   To do more than insert characters, you have to know how to move point
-(*note Point::).  The simplest way to do this is with arrow keys, or by
-clicking the left mouse button where you want to move to.
-
-   NOTE: Many of the following commands have two versions, one that uses
-the function keys (e.g. <LEFT> or <END>) and one that doesn't.  The
-former versions may only be available on X terminals (i.e. not on
-TTY's), but the latter are available on all terminals.
+Examining and Editing Abbrevs
+=============================

 
 

-`C-a'
-`HOME'
-     Move to the beginning of the line (`beginning-of-line').
+`M-x list-abbrevs'
+     Print a list of all abbrev definitions.

 
 

-`C-e'
-`END'
-     Move to the end of the line (`end-of-line').
+`M-x edit-abbrevs'
+     Edit a list of abbrevs; you can add, alter, or remove definitions.

 
 

-`C-f'
-`RIGHT'
-     Move forward one character (`forward-char').
+   The output from `M-x list-abbrevs' looks like this:

 
 

-`C-b'
-`LEFT'
-     Move backward one character (`backward-char').
+     (lisp-mode-abbrev-table)
+     "dk"           0    "define-key"
+     (global-abbrev-table)
+     "dfn"          0    "definition"

 
 

-`M-f'
-`C-RIGHT'
-     Move forward one word (`forward-word').
+(Some blank lines of no semantic significance, and some other abbrev
+tables, have been omitted.)

 
 

-`M-b'
-`C-LEFT'
-     Move backward one word (`backward-word').
+   A line containing a name in parentheses is the header for abbrevs in
+a particular abbrev table; `global-abbrev-table' contains all the global
+abbrevs, and the other abbrev tables that are named after major modes
+contain the mode-specific abbrevs.

 
 

-`C-n'
-`DOWN'
-     Move down one line, vertically (`next-line').  This command
-     attempts to keep the horizontal position unchanged, so if you
-     start in the middle of one line, you end in the middle of the
-     next.  When on the last line of text, `C-n' creates a new line and
-     moves onto it.
+   Within each abbrev table, each non-blank line defines one abbrev.
+The word at the beginning is the abbrev.  The number that appears is
+the number of times the abbrev has been expanded.  Emacs keeps track of
+this to help you see which abbrevs you actually use, in case you want
+to eliminate those that you don't use often.  The string at the end of
+the line is the expansion.

 
 

-`C-p'
-`UP'
-     Move up one line, vertically (`previous-line').
+   `M-x edit-abbrevs' allows you to add, change or kill abbrev
+definitions by editing a list of them in an Emacs buffer.  The list has
+the format described above.  The buffer of abbrevs is called
+`*Abbrevs*', and is in Edit-Abbrevs mode.  This mode redefines the key
+`C-c C-c' to install the abbrev definitions as specified in the buffer.
+The  `edit-abbrevs-redefine' command does this.  Any abbrevs not
+described in the buffer are eliminated when this is done.

 
 

-`C-v'
-`PGDN'
-     Move down one page, vertically (`scroll-up').
+   `edit-abbrevs' is actually the same as `list-abbrevs', except that
+it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely
+displays it in another window.

 
 

-`M-v'
-`PGUP'
-     Move up one page, vertically (`scroll-down').
+\1f
+File: xemacs.info,  Node: Saving Abbrevs,  Next: Dynamic Abbrevs,  Prev: Editing Abbrevs,  Up: Abbrevs

 
 

-`C-l'
-     Clear the frame and reprint everything (`recenter').  Text moves
-     on the frame to bring point to the center of the window.
+Saving Abbrevs
+==============

 
 

-`M-r'
-     Move point to left margin, vertically centered in the window
-     (`move-to-window-line').  Text does not move on the screen.
+These commands allow you to keep abbrev definitions between editing
+sessions.

 
 

-     A numeric argument says which screen line to place point on.  It
-     counts screen lines down from the top of the window (zero for the
-     top line).  A negative argument counts lines from the bottom (-1
-     for the bottom line).
+`M-x write-abbrev-file'
+     Write a file describing all defined abbrevs.

 
 

-`C-t'
-     Transpose two characters, the ones before and after the cursor
-     (`transpose-chars').
+`M-x read-abbrev-file'
+     Read such an abbrev file and define abbrevs as specified there.

 
 

-`M-<'
-`C-HOME'
-     Move to the top of the buffer (`beginning-of-buffer').  With
-     numeric argument N, move to N/10 of the way from the top.  *Note
-     Arguments::, for more information on numeric arguments.
+`M-x quietly-read-abbrev-file'
+     Similar, but do not display a message about what is going on.

 
 

-`M->'
-`C-END'
-     Move to the end of the buffer (`end-of-buffer').
+`M-x define-abbrevs'
+     Define abbrevs from buffer.

 
 

-`M-x goto-char'
-     Read a number N and move point to buffer position N.  Position 1
-     is the beginning of the buffer.
+`M-x insert-abbrevs'
+     Insert all abbrevs and their expansions into the buffer.

 
 

-`M-g'
-     Read a number N and move point to line number N (`goto-line').
-     Line 1 is the beginning of the buffer.
+   Use `M-x write-abbrev-file' to save abbrev definitions for use in a
+later session.  The command reads a file name using the minibuffer and
+writes a description of all current abbrev definitions into the
+specified file.  The text stored in the file looks like the output of
+`M-x list-abbrevs'.

 
 

-`M-x set-goal-column'
-     Use the current column of point as the "semi-permanent goal
-     column" for `C-n' and `C-p' (`set-goal-column').  Henceforth, those
-     commands always move to this column in each line moved into, or as
-     close as possible given the contents of the line.  This goal
-     column remains in effect until canceled.
+   `M-x read-abbrev-file' prompts for a file name using the minibuffer
+and reads the specified file, defining abbrevs according to its
+contents.  `M-x quietly-read-abbrev-file' is the same but does not
+display a message in the echo area; it is actually useful primarily in
+the init file.  *Note Init File::. If you give an empty argument to
+either of these functions, the file name Emacs uses is the value of the
+variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'.

 
 

-`C-u M-x set-goal-column'
-     Cancel the goal column.  Henceforth, `C-n' and `C-p' once again
-     try to avoid changing the horizontal position, as usual.
+   Emacs offers to save abbrevs automatically if you have changed any of
+them, whenever it offers to save all files (for `C-x s' or `C-x C-c').
+Set the variable `save-abbrevs' to `nil' to inhibit this feature.

 
 

-   If you set the variable `track-eol' to a non-`nil' value, then `C-n'
-and `C-p' when at the end of the starting line move to the end of
-another line.  Normally, `track-eol' is `nil'.  *Note Variables::, for
-how to set variables such as `track-eol'.
+   The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
+similar to the previous commands but work on text in an Emacs buffer.
+`M-x insert-abbrevs' inserts text into the current buffer before point,
+describing all current abbrev definitions; `M-x define-abbrevs' parses
+the entire current buffer and defines abbrevs accordingly.

 
 

-   Normally, `C-n' on the last line of a buffer appends a newline to
-it.  If the variable `next-line-add-newlines' is `nil', then `C-n' gets
-an error instead (like `C-p' on the first line).
+\1f
+File: xemacs.info,  Node: Dynamic Abbrevs,  Prev: Saving Abbrevs,  Up: Abbrevs
+
+Dynamic Abbrev Expansion
+========================
+
+The abbrev facility described above operates automatically as you insert
+text, but all abbrevs must be defined explicitly.  By contrast,
+"dynamic abbrevs" allow the meanings of abbrevs to be determined
+automatically from the contents of the buffer, but dynamic abbrev
+expansion happens only when you request it explicitly.
+
+`M-/'
+     Expand the word in the buffer before point as a "dynamic abbrev",
+     by searching in the buffer for words starting with that
+     abbreviation (`dabbrev-expand').
+
+   For example, if the buffer contains `does this follow ' and you type
+`f o M-/', the effect is to insert `follow' because that is the last
+word in the buffer that starts with `fo'.  A numeric argument to `M-/'
+says to take the second, third, etc. distinct expansion found looking
+backward from point.  Repeating `M-/' searches for an alternative
+expansion by looking farther back.  After the entire buffer before
+point has been considered, the buffer after point is searched.
+
+   Dynamic abbrev expansion is completely independent of Abbrev mode;
+the expansion of a word with `M-/' is completely independent of whether
+it has a definition as an ordinary abbrev.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Erasing,  Next: Basic Files,  Prev: Moving Point,  Up: Basic
+File: xemacs.info,  Node: Picture,  Next: Sending Mail,  Prev: Abbrevs,  Up: Top
+
+Editing Pictures
+****************
+
+If you want to create a picture made out of text characters (for
+example, a picture of the division of a register into fields, as a
+comment in a program), use the command `edit-picture' to enter Picture
+mode.
+
+   In Picture mode, editing is based on the "quarter-plane" model of
+text.  In this model, the text characters lie studded on an area that
+stretches infinitely far to the right and downward.  The concept of the
+end of a line does not exist in this model; the most you can say is
+where the last non-blank character on the line is found.
+
+   Of course, Emacs really always considers text as a sequence of
+characters, and lines really do have ends.  But in Picture mode most
+frequently-used keys are rebound to commands that simulate the
+quarter-plane model of text.  They do this by inserting spaces or by
+converting tabs to spaces.
+
+   Most of the basic editing commands of Emacs are redefined by Picture
+mode to do essentially the same thing but in a quarter-plane way.  In
+addition, Picture mode defines various keys starting with the `C-c'
+prefix to run special picture editing commands.
+
+   One of these keys, `C-c C-c', is pretty important.  Often a picture
+is part of a larger file that is usually edited in some other major
+mode.  `M-x edit-picture' records the name of the previous major mode.
+You can then use the `C-c C-c' command (`picture-mode-exit') to restore
+that mode.  `C-c C-c' also deletes spaces from the ends of lines,
+unless you give it a numeric argument.
+
+   The commands used in Picture mode all work in other modes (provided
+the `picture' library is loaded), but are only  bound to keys in
+Picture mode.  Note that the descriptions below talk of moving "one
+column" and so on, but all the picture mode commands handle numeric
+arguments as their normal equivalents do.
+
+   Turning on Picture mode calls the value of the variable
+`picture-mode-hook' as a function, with no arguments, if that value
+exists and is non-`nil'.

 
 

-Erasing Text
-============
+* Menu:

 
 

-`<DEL>'
-     Delete the character before or after point
-     (`backward-or-forward-delete-char').  You can customize this
-     behavior by setting the variable `delete-key-deletes-forward'.
+* Basic Picture::         Basic concepts and simple commands of Picture Mode.
+* Insert in Picture::     Controlling direction of cursor motion
+                           after "self-inserting" characters.
+* Tabs in Picture::       Various features for tab stops and indentation.
+* Rectangles in Picture:: Clearing and superimposing rectangles.

 
 

-`C-d'
-     Delete the character after point (`delete-char').
+\1f
+File: xemacs.info,  Node: Basic Picture,  Next: Insert in Picture,  Prev: Picture,  Up: Picture
+
+Basic Editing in Picture Mode
+=============================
+
+Most keys do the same thing in Picture mode that they usually do, but do
+it in a quarter-plane style.  For example, `C-f' is rebound to run
+`picture-forward-column', which moves point one column to the right, by
+inserting a space if necessary, so that the actual end of the line
+makes no difference.  `C-b' is rebound to run
+`picture-backward-column', which always moves point left one column,
+converting a tab to multiple spaces if necessary.  `C-n' and `C-p' are
+rebound to run `picture-move-down' and `picture-move-up', which can
+either insert spaces or convert tabs as necessary to make sure that
+point stays in exactly the same column.  `C-e' runs
+`picture-end-of-line', which moves to after the last non-blank
+character on the line.  There was no need to change `C-a', as the choice
+of screen model does not affect beginnings of lines.
+
+   Insertion of text is adapted to the quarter-plane screen model
+through the use of Overwrite mode (*note Minor Modes::).
+Self-inserting characters replace existing text, column by column,
+rather than pushing existing text to the right.  <RET> runs
+`picture-newline', which just moves to the beginning of the following
+line so that new text will replace that line.
+
+   Text is erased instead of deleted and killed.  <DEL>
+(`picture-backward-clear-column') replaces the preceding character with
+a space rather than removing it.  `C-d' (`picture-clear-column') does
+the same in a forward direction.  `C-k' (`picture-clear-line') really
+kills the contents of lines, but never removes the newlines from a
+buffer.
+
+   To do actual insertion, you must use special commands.  `C-o'
+(`picture-open-line') creates a blank line, but does so after the
+current line; it never splits a line.  `C-M-o', `split-line', makes
+sense in Picture mode, so it remains unchanged.  <LFD>
+(`picture-duplicate-line') inserts another line with the same contents
+below the current line.
+
+   To actually delete parts of the picture, use `C-w', or with `C-c
+C-d' (which is defined as `delete-char', as `C-d' is in other modes),
+or with one of the picture rectangle commands (*note Rectangles in
+Picture::).

 
 

-`C-k'
-     Kill to the end of the line (`kill-line').
+\1f
+File: xemacs.info,  Node: Insert in Picture,  Next: Tabs in Picture,  Prev: Basic Picture,  Up: Picture
+
+Controlling Motion After Insert
+===============================
+
+Since "self-inserting" characters just overwrite and move point in
+Picture mode, there is no essential restriction on how point should be
+moved.  Normally point moves right, but you can specify any of the eight
+orthogonal or diagonal directions for motion after a "self-inserting"
+character.  This is useful for drawing lines in the buffer.
+
+`C-c <'
+     Move left after insertion (`picture-movement-left').

 
 

-`M-d'
-     Kill forward to the end of the next word (`kill-word').
+`C-c >'
+     Move right after insertion (`picture-movement-right').

 
 

-`M-<DEL>'
-     Kill back to the beginning of the previous word
-     (`backward-kill-word').
+`C-c ^'
+     Move up after insertion (`picture-movement-up').

 
 

-   You already know about the <DEL> key which deletes the character
-before point (that is, before the cursor).  Another key, `Control-d'
-(`C-d' for short), deletes the character after point (that is, the
-character that the cursor is on).  This shifts the rest of the text on
-the line to the left.  If you type `C-d' at the end of a line, it joins
-together that line and the next line.
+`C-c .'
+     Move down after insertion (`picture-movement-down').

 
 

-   To erase a larger amount of text, use the `C-k' key, which kills a
-line at a time.  If you type `C-k' at the beginning or middle of a
-line, it kills all the text up to the end of the line.  If you type
-`C-k' at the end of a line, it joins that line and the next line.
+`C-c `'
+     Move up and left ("northwest") after insertion
+     (`picture-movement-nw').

 
 

-   *Note Killing::, for more flexible ways of killing text.
+`C-c ''
+     Move up and right ("northeast") after insertion
+     (`picture-movement-ne').
+
+`C-c /'
+     Move down and left ("southwest") after insertion
+     (`picture-movement-sw').
+
+`C-c \'
+     Move down and right ("southeast") after insertion
+     (`picture-movement-se').
+
+   Two motion commands move based on the current Picture insertion
+direction.  The command `C-c C-f' (`picture-motion') moves in the same
+direction as motion after "insertion" currently does, while `C-c C-b'
+(`picture-motion-reverse') moves in the opposite direction.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Basic Files,  Next: Basic Help,  Prev: Erasing,  Up: Basic
+File: xemacs.info,  Node: Tabs in Picture,  Next: Rectangles in Picture,  Prev: Insert in Picture,  Up: Picture
+
+Picture Mode Tabs
+=================
+
+Two kinds of tab-like action are provided in Picture mode.
+Context-based tabbing is done with `M-<TAB>' (`picture-tab-search').
+With no argument, it moves to a point underneath the next "interesting"
+character that follows whitespace in the previous non-blank line.
+"Next" here means "appearing at a horizontal position greater than the
+one point starts out at".  With an argument, as in `C-u M-<TAB>', the
+command moves to the next such interesting character in the current
+line.  `M-<TAB>' does not change the text; it only moves point.
+"Interesting" characters are defined by the variable
+`picture-tab-chars', which contains a string of characters considered
+interesting.  Its default value is `"!-~"'.
+
+   <TAB> itself runs `picture-tab', which operates based on the current
+tab stop settings; it is the Picture mode equivalent of
+`tab-to-tab-stop'.  Without arguments it just moves point, but with a
+numeric argument it clears the text that it moves over.
+
+   The context-based and tab-stop-based forms of tabbing are brought
+together by the command `C-c <TAB>' (`picture-set-tab-stops'.)  This
+command sets the tab stops to the positions which `M-<TAB>' would
+consider significant in the current line.  If you use this command with
+<TAB>, you can get the effect of context-based tabbing.  But `M-<TAB>'
+is more convenient in the cases where it is sufficient.

 
 

-Files
-=====
+\1f
+File: xemacs.info,  Node: Rectangles in Picture,  Prev: Tabs in Picture,  Up: Picture
+
+Picture Mode Rectangle Commands
+===============================

 
 

-   The commands described above are sufficient for creating and altering
-text in an Emacs buffer; the more advanced Emacs commands just make
-things easier.  But to keep any text permanently you must put it in a
-"file".  Files are named units of text which are stored by the
-operating system for you to retrieve later by name.  To look at or use
-the contents of a file in any way, including editing the file with
-Emacs, you must specify the file name.
+Picture mode defines commands for working on rectangular pieces of the
+text in ways that fit with the quarter-plane model.  The standard
+rectangle commands may also be useful (*note Rectangles::).

 
 

-   Consider a file named `/usr/rms/foo.c'.  To begin editing this file
-from Emacs, type:
+`C-c C-k'
+     Clear out the region-rectangle (`picture-clear-rectangle').  With
+     argument, kill it.

 
 

-     C-x C-f /usr/rms/foo.c <RET>
+`C-c C-w R'
+     Similar but save rectangle contents in register R first
+     (`picture-clear-rectangle-to-register').

 
 

-Here the file name is given as an "argument" to the command `C-x C-f'
-(`find-file').  That command uses the "minibuffer" to read the
-argument, and you type <RET> to terminate the argument (*note
-Minibuffer::).
+`C-c C-y'
+     Copy last killed rectangle into the buffer by overwriting, with
+     upper left corner at point (`picture-yank-rectangle').  With
+     argument, insert instead.

 
 

-   You can also use the Open... menu item from the File menu, then type
-the name of the file to the prompt.
+`C-c C-x R'
+     Similar, but use the rectangle in register R
+     (`picture-yank-rectangle-from-register').

 
 

-   Emacs obeys the command by "visiting" the file: creating a buffer,
-copying the contents of the file into the buffer, and then displaying
-the buffer for you to edit.  If you alter the text, you can "save" the
-new text in the file by typing `C-x C-s' (`save-buffer') or choosing
-Save Buffer from the File menu.  This makes the changes permanent by
-copying the altered buffer contents back into the file
-`/usr/rms/foo.c'.  Until you save, the changes exist only inside Emacs,
-and the file `foo.c' is unaltered.
+   The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
+and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
+standard rectangle commands in that they normally clear the rectangle
+instead of deleting it; this is analogous with the way `C-d' is changed
+in Picture mode.

 
 

-   To create a file, visit the file with `C-x C-f' as if it already
-existed or choose Open... from the File menu and provide the name for
-the new file.  Emacs will create an empty buffer in which you can
-insert the text you want to put in the file.  When you save the buffer
-with `C-x C-s', or by choosing Save Buffer from the File menu, the file
-is created.
+   However, deletion of rectangles can be useful in Picture mode, so
+these commands delete the rectangle if given a numeric argument.

 
 

-   To learn more about using files, *Note Files::.
+   The Picture mode commands for yanking rectangles differ from the
+standard ones in overwriting instead of inserting.  This is the same
+way that Picture mode insertion of other text is different from other
+modes.  `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
+the rectangle that was most recently killed, while `C-c C-x'
+(`picture-yank-rectangle-from-register') does for the rectangle found
+in a specified register.
+
+   Since most region commands in Picture mode operate on rectangles,
+when you select a region of text with the mouse in Picture mode, it is
+highlighted as a rectangle.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Basic Help,  Next: Blank Lines,  Prev: Basic Files,  Up: Basic
+File: xemacs.info,  Node: Sending Mail,  Next: Reading Mail,  Prev: Picture,  Up: Top

 
 

-Help
-====
+Sending Mail
+************
+
+To send a message in Emacs, start by typing the command (`C-x m') to
+select and initialize the `*mail*' buffer.  You can then edit the text
+and headers of the message in the mail buffer, and type the command
+(`C-c C-c') to send the message.
+
+`C-x m'
+     Begin composing a message to send (`mail').
+
+`C-x 4 m'
+     Likewise, but display the message in another window
+     (`mail-other-window').
+
+`C-c C-c'
+     In Mail mode, send the message and switch to another buffer
+     (`mail-send-and-exit').

 
 

-   If you forget what a key does, you can find out with the Help
-character, which is `C-h' (or <F1>, which is an alias for `C-h').  Type
-`C-h k' followed by the key you want to know about; for example, `C-h k
-C-n' tells you all about what `C-n' does.  `C-h' is a prefix key; `C-h
-k' is just one of its subcommands (the command `describe-key').  The
-other subcommands of `C-h' provide different kinds of help.  Type `C-h'
-twice to get a description of all the help facilities.  *Note Help::.
+   The command `C-x m' (`mail') selects a buffer named `*mail*' and
+initializes it with the skeleton of an outgoing message.  `C-x 4 m'
+(`mail-other-window') selects the `*mail*' buffer in a different
+window, leaving the previous current buffer visible.
+
+   Because the buffer for mail composition is an ordinary Emacs buffer,
+you can switch to other buffers while in the middle of composing mail,
+and switch back later (or never).  If you use the `C-x m' command again
+when you have been composing another message but have not sent it, a
+new mail buffer will be created; in this way, you can compose multiple
+messages at once.  You can switch back to and complete an unsent
+message by using the normal buffer selection mechanisms.
+
+   `C-u C-x m' is another way to switch back to a message in progress:
+it will search for an existing, unsent mail message buffer and select
+it.
+
+* Menu:
+
+* Format: Mail Format.    Format of the mail being composed.
+* Headers: Mail Headers.  Details of allowed mail header fields.
+* Mode: Mail Mode.        Special commands for editing mail being composed.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Blank Lines,  Next: Continuation Lines,  Prev: Basic Help,  Up: Basic
+File: xemacs.info,  Node: Mail Format,  Next: Mail Headers,  Prev: Sending Mail,  Up: Sending Mail

 
 

-Blank Lines
-===========
+The Format of the Mail Buffer
+=============================

 
 

-   Here are special commands and techniques for putting in and taking
-out blank lines.
+In addition to the "text" or contents, a message has "header fields",
+which say who sent it, when, to whom, why, and so on.  Some header
+fields, such as the date and sender, are created automatically after the
+message is sent.  Others, such as the recipient names, must be
+specified by you in order to send the message properly.

 
 

-`C-o'
-     Insert one or more blank lines after the cursor (`open-line').
+   Mail mode provides a few commands to help you edit some header
+fields, and some are preinitialized in the buffer automatically at
+times.  You can insert or edit any header fields using ordinary editing
+commands.

 
 

-`C-x C-o'
-     Delete all but one of many consecutive blank lines
-     (`delete-blank-lines').
+   The line in the buffer that says:

 
 

-   When you want to insert a new line of text before an existing line,
-you can do it by typing the new line of text, followed by <RET>.
-However, it may be easier to see what you are doing if you first make a
-blank line and then insert the desired text into it.  This is easy to do
-using the key `C-o' (`open-line'), which inserts a newline after point
-but leaves point in front of the newline.  After `C-o', type the text
-for the new line.  `C-o F O O' has the same effect as `F O O <RET>',
-except for the final location of point.
+     --text follows this line--

 
 

-   You can make several blank lines by typing `C-o' several times, or
-by giving it a numeric argument to tell it how many blank lines to make.
-*Note Arguments::, for how.  If you have a fill prefix, then `C-o'
-command inserts the fill prefix on the new line, when you use it at the
-beginning of a line.  *Note Fill Prefix::.
+is a special delimiter that separates the headers you have specified
+from the text.  Whatever follows this line is the text of the message;
+the headers precede it.  The delimiter line itself does not appear in
+the message actually sent.  The text used for the delimiter line is
+controlled by the variable `mail-header-separator'.

 
 

-   The easy way to get rid of extra blank lines is with the command
-`C-x C-o' (`delete-blank-lines').  `C-x C-o' in a run of several blank
-lines deletes all but one of them.  `C-x C-o' on a solitary blank line
-deletes that blank line.  When point is on a nonblank line, `C-x C-o'
-deletes any blank lines following that nonblank line.
+   Here is an example of what the headers and text in the `*mail*'
+buffer might look like.
+
+     To: rms@mc
+     CC: mly@mc, rg@oz
+     Subject: The XEmacs User's Manual
+     --Text follows this line--
+     Please ignore this message.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Continuation Lines,  Next: Position Info,  Prev: Blank Lines,  Up: Basic
+File: xemacs.info,  Node: Mail Headers,  Next: Mail Mode,  Prev: Mail Format,  Up: Sending Mail

 
 

-Continuation Lines
+Mail Header Fields

 ==================
 
 ==================
 

-   If you add too many characters to one line without breaking it with
-<RET>, the line will grow to occupy two (or more) lines on the screen,
-with a curved arrow at the extreme right margin of all but the last of
-them.  The curved arrow says that the following screen line is not
-really a distinct line in the text, but just the "continuation" of a
-line too long to fit the screen.  Continuation is also called "line
-wrapping".
-
-   Sometimes it is nice to have Emacs insert newlines automatically when
-a line gets too long.  Continuation on the screen does not do that.  Use
-Auto Fill mode (*note Filling::) if that's what you want.
-
-   Instead of continuation, long lines can be displayed by "truncation".
-This means that all the characters that do not fit in the width of the
-frame or window do not appear at all.  They remain in the buffer,
-temporarily invisible.  Right arrow in the last column (instead of the
-curved arrow) inform you that truncation is in effect.
-
-   Truncation instead of continuation happens whenever horizontal
-scrolling is in use, and optionally in all side-by-side windows (*note
-Windows::).  You can enable truncation for a particular buffer by
-setting the variable `truncate-lines' to non-`nil' in that buffer.
-(*Note Variables::.)  Altering the value of `truncate-lines' makes it
-local to the current buffer; until that time, the default value is in
-effect.  The default is initially `nil'.  *Note Locals::.
-
-   *Note Display Vars::, for additional variables that affect how text
-is displayed.
+There are several header fields you can use in the `*mail*' buffer.
+Each header field starts with a field name at the beginning of a line,
+terminated by a colon.  It does not matter whether you use upper or
+lower case in the field name.  After the colon and optional whitespace
+comes the contents of the field.
+
+`To'
+     This field contains the mailing addresses of the message.
+
+`Subject'
+     The contents of the `Subject' field should be a piece of text that
+     says what the message is about.  Subject fields are useful because
+     most mail-reading programs can provide a summary of messages,
+     listing the subject of each message but not its text.
+
+`CC'
+     This field contains additional mailing addresses to send the
+     message to, but whose readers should not regard the message as
+     addressed to them.
+
+`BCC'
+     This field contains additional mailing addresses to send the
+     message to, but which should not appear in the header of the
+     message actually sent.
+
+`FCC'
+     This field contains the name of one file (in Unix mail file
+     format) to which a copy of the message should be appended when the
+     message is sent.
+
+`From'
+     Use the `From' field to say who you are, when the account you are
+     using to send the mail is not your own.  The contents of the
+     `From' field should be a valid mailing address, since replies will
+     normally go there.
+
+`Reply-To'
+     Use the `Reply-To' field to direct replies to a different address,
+     not your own. `From' and `Reply-To' have the same effect on where
+     replies go, but they convey a different meaning to the person who
+     reads the message.
+
+`In-Reply-To'
+     This field contains a piece of text describing a message you are
+     replying to.  Some mail systems can use the information to
+     correlate related pieces of mail.  This field is normally filled
+     in by your mail handling package when you are replying to a
+     message and you never need to think about it.
+
+The `To', `CC', `BCC' and `FCC' fields can appear any number of times,
+to specify many places to send the message.
+
+The `To', `CC', and `BCC', fields can have continuation lines.  All the
+lines starting with whitespace, following the line on which the field
+starts, are considered part of the field.  For example,
+
+     To: foo@here, this@there,
+       me@gnu.cambridge.mass.usa.earth.spiral3281
+
+If you have a `~/.mailrc' file, Emacs scans it for mail aliases the
+first time you try to send mail in an Emacs session.  Emacs expands
+aliases found in the `To', `CC', and `BCC' fields where appropriate.
+You can set the variable `mail-abbrev-mailrc-file' to the name of the
+file with mail aliases.  If `nil', `~/.mailrc' is used.
+
+   Your `.mailrc' file ensures that word-abbrevs are defined for each
+of your mail aliases when point is in a `To', `CC', `BCC', or `From'
+field.  The aliases are defined in your `.mailrc' file or in a file
+specified by the MAILRC environment variable if it exists.  Your mail
+aliases expand any time you type a word-delimiter at the end of an
+abbreviation.
+
+   In this version of Emacs, what you see is what you get: in contrast
+to some other versions, no abbreviations are expanded after you have
+sent the mail.  This means you don't suffer the annoyance of having the
+system do things behind your back--if the system rewrites an address
+you typed, you know it immediately, instead of after the mail has been
+sent and it's too late to do anything about it.  For example, you will
+never again be in trouble because you forgot to delete an old alias
+from your `.mailrc' and a new local user is given a userid which
+conflicts with one of your aliases.
+
+   Your mail alias abbrevs are in effect only when point is in an
+appropriate header field. The mail aliases will not expand in the body
+of the message, or in other header fields.  The default mode-specific
+abbrev table `mail-mode-abbrev-table' is used instead if defined.  That
+means if you have been using mail-mode specific abbrevs, this code will
+not adversely affect you.  You can control which header fields the
+abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'.
+
+   If auto-fill mode is on, abbrevs wrap at commas instead of at word
+boundaries, and header continuation lines will be properly indented.
+
+   You can also insert a mail alias with
+`mail-interactive-insert-alias'.  This function, which is bound to `C-c
+C-a', prompts you for an alias (with completion) and inserts its
+expansion at point.
+
+   In this version of Emacs, it is possible to have lines like the
+following in your `.mailrc' file:
+
+          alias someone "John Doe <doe@quux.com>"
+
+   That is, if you want an address to have embedded spaces, simply
+surround it with double-quotes.  The quotes are necessary because the
+format of the `.mailrc' file uses spaces as address delimiters.
+
+   Aliases in the `.mailrc' file may be nested. For example, assume you
+define aliases like:
+          alias group1 fred ethel
+          alias group2 larry curly moe
+          alias everybody group1 group2
+
+   When you now type `everybody' on the `To' line, it will expand to:
+          fred, ethyl, larry, curly, moe
+
+   Aliases may contain forward references; the alias of `everybody' in
+the example above can precede the aliases of `group1' and `group2'.
+
+   In this version of Emacs, you can use the `source' `.mailrc' command
+for reading aliases from some other file as well.
+
+   Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even
+though word-abbrevs normally cannot contain hyphens.
+
+   To read in the contents of another `.mailrc'-type file from Emacs,
+use the command `M-x merge-mail-aliases'.  The `rebuild-mail-aliases'
+command is similar, but deletes existing aliases first.
+
+   If you want multiple addresses separated by a string other than `,'
+(a comma), then set the variable `mail-alias-separator-string' to it.
+This has to be a comma bracketed by whitespace if you want any kind  of
+reasonable behavior.
+
+   If the variable `mail-archive-file-name' is non-`nil', it should be
+a string naming a file.  Each time you start to edit a message to send,
+an `FCC' field is entered for that file.  Unless you remove the `FCC'
+field, every message is written into that file when it is sent.
+
+\1f
+File: xemacs.info,  Node: Mail Mode,  Prev: Mail Headers,  Up: Sending Mail
+
+Mail Mode
+=========
+
+The major mode used in the `*mail*' buffer is Mail mode.  Mail mode is
+similar to Text mode, but several commands are provided on the `C-c'
+prefix.  These commands all deal specifically with editing or sending
+the message.
+
+`C-c C-s'
+     Send the message, and leave the `*mail*' buffer selected
+     (`mail-send').
+
+`C-c C-c'
+     Send the message, and select some other buffer
+     (`mail-send-and-exit').
+
+`C-c C-f C-t'
+     Move to the `To' header field, creating one if there is none
+     (`mail-to').
+
+`C-c C-f C-s'
+     Move to the `Subject' header field, creating one if there is none
+     (`mail-subject').
+
+`C-c C-f C-c'
+     Move to the `CC' header field, creating one if there is none
+     (`mail-cc').
+
+`C-c C-w'
+     Insert the file `~/.signature' at the end of the message text
+     (`mail-signature').
+
+`C-c C-y'
+     Yank the selected message (`mail-yank-original').
+
+`C-c C-q'
+     Fill all paragraphs of yanked old messages, each individually
+     (`mail-fill-yanked-message').
+
+`<button3>'
+     Pops up a menu of useful mail-mode commands.
+
+   There are two ways to send a message.  `C-c C-c'
+(`mail-send-and-exit') is the usual way to send the message.  It sends
+the message and then deletes the window (if there is another window) or
+switches to another buffer.  It puts the `*mail*' buffer at the lowest
+priority for automatic reselection, since you are finished with using
+it.  `C-c C-s' (`mail-send') sends the message and marks the `*mail*'
+buffer unmodified, but leaves that buffer selected so that you can
+modify the message (perhaps with new recipients) and send it again.
+
+   Mail mode provides some other special commands that are useful for
+editing the headers and text of the message before you send it.  There
+are three commands defined to move point to particular header fields,
+all based on the prefix `C-c C-f' (`C-f' is for "field").  They are
+`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s'
+(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc')
+for the `CC' field.  These fields have special motion commands because
+they are edited most frequently.
+
+   `C-c C-w' (`mail-signature') adds a standard piece of text at the
+end of the message to say more about who you are.  The text comes from
+the file `.signature' in your home directory.
+
+   When you use an Rmail command to send mail from the Rmail mail
+reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*'
+buffer to insert the text of the message you are replying to.  Normally
+Rmail indents each line of that message four spaces and eliminates most
+header fields.  A numeric argument specifies the number of spaces to
+indent.  An argument of just `C-u' says not to indent at all and not to
+eliminate anything.  `C-c C-y' always uses the current message from the
+`RMAIL' buffer, so you can insert several old messages by selecting one
+in `RMAIL', switching to `*mail*' and yanking it, then switching back
+to `RMAIL' to select another.
+
+   After using `C-c C-y', you can use the command `C-c C-q'
+(`mail-fill-yanked-message') to fill the paragraphs of the yanked old
+message or messages.  One use of `C-c C-q' fills all such paragraphs,
+each one separately.
+
+   Clicking the right mouse button in a mail buffer pops up a menu of
+the above commands, for easy access.
+
+   Turning on Mail mode (which `C-x m' does automatically) calls the
+value of `text-mode-hook', if it is not void or `nil', and then calls
+the value of `mail-mode-hook' if that is not void or `nil'.
+
+\1f
+File: xemacs.info,  Node: Reading Mail,  Next: Calendar/Diary,  Prev: Sending Mail,  Up: Top
+
+Reading Mail
+************
+
+XEmacs provides several mail-reading packages.  Each one comes with its
+own manual, which is included in each package.
+
+   The recommended mail-reading package for new users is VM.  VM works
+with standard Unix-mail-format folders and was designed as a replacement
+for the older Rmail.
+
+   XEmacs also provides a sophisticated and comfortable front-end to the
+MH mail-processing system, called `MH-E'.  Unlike in other mail
+programs, folders in MH are stored as file-system directories, with
+each message occupying one (numbered) file.  This facilitates working
+with mail using shell commands, and many other features of MH are also
+designed to integrate well with the shell and with shell scripts.  Keep
+in mind, however, that in order to use MH-E you must have the MH
+mail-processing system installed on your computer.
+
+   The "Everything including the kitchen sink" package `Gnus' is also
+available as an XEmacs package.  Gnus also handles Usenet articles as
+well as mail.
+
+   `MEW' (Messaging in the Emacs World) is another mail-reading package
+available for XEmacs.
+
+   Finally, XEmacs provides the Rmail package.  Rmail is (currently)
+the only mail reading package distributed with FSF GNU Emacs, and is
+powerful in its own right.  However, it stores mail folders in a
+special format called `Babyl', that is incompatible with all other
+frequently-used mail programs.  A utility program is provided for
+converting Babyl folders to standard Unix-mail format; however, unless
+you already have mail in Babyl-format folders, you should consider
+using Gnus, VM, or MH-E instead.
+
+\1f
+File: xemacs.info,  Node: Calendar/Diary,  Next: Sorting,  Prev: Reading Mail,  Up: Top
+
+Calendar Mode and the Diary
+===========================
+
+Emacs provides the functions of a desk calendar, with a diary of
+planned or past events.  To enter the calendar, type `M-x calendar';
+this displays a three-month calendar centered on the current month, with
+point on the current date.  With a numeric argument, as in `C-u M-x
+calendar', it prompts you for the month and year to be the center of the
+three-month calendar.  The calendar uses its own buffer, whose major
+mode is Calendar mode.
+
+   `Button2' in the calendar brings up a menu of operations on a
+particular date; `Buttons3' brings up a menu of commonly used calendar
+features that are independent of any particular date.  To exit the
+calendar, type `q'.  *Note Customizing the Calendar and Diary:
+(lispref)Calendar, for customization information about the calendar and
+diary.
+
+* Menu:
+
+* Calendar Motion::        Moving through the calendar; selecting a date.
+* Scroll Calendar::        Bringing earlier or later months onto the screen.
+* Mark and Region::        Remembering dates, the mark ring.
+* General Calendar::       Exiting or recomputing the calendar.
+* LaTeX Calendar::         Print a calendar using LaTeX.
+* Holidays::               Displaying dates of holidays.
+* Sunrise/Sunset::         Displaying local times of sunrise and sunset.
+* Lunar Phases::           Displaying phases of the moon.
+* Other Calendars::        Converting dates to other calendar systems.
+* Diary::                  Displaying events from your diary.
+* Calendar Customization:: Altering the behavior of the features above.
+
+\1f
+File: xemacs.info,  Node: Calendar Motion,  Next: Scroll Calendar,  Prev: Calendar/Diary,  Up: Calendar/Diary
+
+Movement in the Calendar
+------------------------
+
+Calendar mode lets you move through the calendar in logical units of
+time such as days, weeks, months, and years.  If you move outside the
+three months originally displayed, the calendar display "scrolls"
+automatically through time to make the selected date visible.  Moving to
+a date lets you view its holidays or diary entries, or convert it to
+other calendars; moving longer time periods is also useful simply to
+scroll the calendar.
+
+* Menu:
+
+* Calendar Unit Motion::       Moving by days, weeks, months, and years.
+* Move to Beginning or End::   Moving to start/end of weeks, months, and years.
+* Specified Dates::            Moving to the current date or another
+                               specific date.
+
+\1f
+File: xemacs.info,  Node: Calendar Unit Motion,  Next: Move to Beginning or End,  Prev: Calendar Motion,  Up: Calendar Motion
+
+Motion by Integral Days, Weeks, Months, Years
+.............................................
+
+The commands for movement in the calendar buffer parallel the commands
+for movement in text.  You can move forward and backward by days,
+weeks, months, and years.
+
+`C-f'
+     Move point one day forward (`calendar-forward-day').
+
+`C-b'
+     Move point one day backward (`calendar-backward-day').
+
+`C-n'
+     Move point one week forward (`calendar-forward-week').
+
+`C-p'
+     Move point one week backward (`calendar-backward-week').
+
+`M-}'
+     Move point one month forward (`calendar-forward-month').
+
+`M-{'
+     Move point one month backward (`calendar-backward-month').
+
+`C-x ]'
+     Move point one year forward (`calendar-forward-year').
+
+`C-x ['
+     Move point one year backward (`calendar-backward-year').
+
+   The day and week commands are natural analogues of the usual Emacs
+commands for moving by characters and by lines.  Just as `C-n' usually
+moves to the same column in the following line, in Calendar mode it
+moves to the same day in the following week.  And `C-p' moves to the
+same day in the previous week.
+
+   The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just
+as they normally are in other modes.
+
+   The commands for motion by months and years work like those for
+weeks, but move a larger distance.  The month commands `M-}' and `M-{'
+move forward or backward by an entire month's time.  The year commands
+`C-x ]' and `C-x [' move forward or backward a whole year.
+
+   The easiest way to remember these commands is to consider months and
+years analogous to paragraphs and pages of text, respectively.  But the
+commands themselves are not quite analogous.  The ordinary Emacs
+paragraph commands move to the beginning or end of a paragraph, whereas
+these month and year commands move by an entire month or an entire
+year, which usually involves skipping across the end of a month or year.
+
+   All these commands accept a numeric argument as a repeat count.  For
+convenience, the digit keys and the minus sign specify numeric
+arguments in Calendar mode even without the Meta modifier.  For example,
+`100 C-f' moves point 100 days forward from its present location.
+
+\1f
+File: xemacs.info,  Node: Move to Beginning or End,  Next: Specified Dates,  Prev: Calendar Unit Motion,  Up: Calendar Motion
+
+Beginning or End of Week, Month or Year
+.......................................
+
+A week (or month, or year) is not just a quantity of days; we think of
+weeks (months, years) as starting on particular dates.  So Calendar mode
+provides commands to move to the beginning or end of a week, month or
+year:
+
+`C-a'
+     Move point to start of week (`calendar-beginning-of-week').
+
+`C-e'
+     Move point to end of week (`calendar-end-of-week').
+
+`M-a'
+     Move point to start of month (`calendar-beginning-of-month').
+
+`M-e'
+     Move point to end of month (`calendar-end-of-month').
+
+`M-<'
+     Move point to start of year (`calendar-beginning-of-year').
+
+`M->'
+     Move point to end of year (`calendar-end-of-year').
+
+   These commands also take numeric arguments as repeat counts, with the
+repeat count indicating how many weeks, months, or years to move
+backward or forward.
+
+   By default, weeks begin on Sunday.  To make them begin on Monday
+instead, set the variable `calendar-week-start-day' to 1.
+
+\1f
+File: xemacs.info,  Node: Specified Dates,  Prev: Move to Beginning or End,  Up: Calendar Motion
+
+Particular Dates
+................
+
+Calendar mode provides commands for moving to a particular date
+specified in various ways.
+
+`g d'
+     Move point to specified date (`calendar-goto-date').
+
+`o'
+     Center calendar around specified month (`calendar-other-month').
+
+`.'
+     Move point to today's date (`calendar-goto-today').
+
+   `g d' (`calendar-goto-date') prompts for a year, a month, and a day
+of the month, and then moves to that date.  Because the calendar
+includes all dates from the beginning of the current era, you must type
+the year in its entirety; that is, type `1990', not `90'.
+
+   `o' (`calendar-other-month') prompts for a month and year, then
+centers the three-month calendar around that month.
+
+   You can return to today's date with `.' (`calendar-goto-today').
+
+\1f
+File: xemacs.info,  Node: Scroll Calendar,  Next: Mark and Region,  Prev: Calendar Motion,  Up: Calendar/Diary
+
+Scrolling the Calendar through Time
+-----------------------------------
+
+The calendar display scrolls automatically through time when you move
+out of the visible portion.  You can also scroll it manually.  Imagine
+that the calendar window contains a long strip of paper with the months
+on it.  Scrolling it means moving the strip so that new months become
+visible in the window.
+
+`C-x <'
+     Scroll calendar one month forward (`scroll-calendar-left').
+
+`C-x >'
+     Scroll calendar one month backward (`scroll-calendar-right').
+
+`C-v'
+`<NEXT>'
+     Scroll calendar three months forward
+     (`scroll-calendar-left-three-months').
+
+`M-v'
+`<PRIOR>'
+     Scroll calendar three months backward
+     (`scroll-calendar-right-three-months').
+
+   The most basic calendar scroll commands scroll by one month at a
+time.  This means that there are two months of overlap between the
+display before the command and the display after.  `C-x <' scrolls the
+calendar contents one month to the left; that is, it moves the display
+forward in time.  `C-x >' scrolls the contents to the right, which
+moves backwards in time.
+
+   The commands `C-v' and `M-v' scroll the calendar by an entire
+"screenful"--three months--in analogy with the usual meaning of these
+commands.  `C-v' makes later dates visible and `M-v' makes earlier
+dates visible.  These commands take a numeric argument as a repeat
+count; in particular, since `C-u' multiplies the next command by four,
+typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u
+M-v' scrolls the calendar backward by a year.
+
+   The function keys <NEXT> and <PRIOR> are equivalent to `C-v' and
+`M-v', just as they are in other modes.
+
+\1f
+File: xemacs.info,  Node: Mark and Region,  Next: General Calendar,  Prev: Scroll Calendar,  Up: Calendar/Diary
+
+The Mark and the Region
+-----------------------
+
+The concept of the mark applies to the calendar just as to any other
+buffer, but it marks a _date_, not a _position_ in the buffer.  The
+region consists of the days between the mark and point (including the
+starting and stopping dates).
+
+`C-SPC'
+     Set the mark to today's date (`calendar-set-mark').
+
+`C-@'
+     The same.
+
+`C-x C-x'
+     Interchange mark and point (`calendar-exchange-point-and-mark').
+
+`M-='
+     Display the number of days in the current region
+     (`calendar-count-days-region').
+
+   You set the mark in the calendar, as in any other buffer, by using
+`C-@' or `C-SPC' (`calendar-set-mark').  You return to the marked date
+with the command `C-x C-x' (`calendar-exchange-point-and-mark') which
+puts the mark where point was and point where mark was.  The calendar
+is scrolled as necessary, if the marked date was not visible on the
+screen.  This does not change the extent of the region.
+
+   To determine the number of days in the region, type `M-='
+(`calendar-count-days-region').  The numbers of days printed is
+_inclusive_; that is, it includes the days specified by mark and point.
+
+   The main use of the mark in the calendar is to remember dates that
+you may want to go back to.  To make this feature more useful, the mark
+ring (*note Mark Ring::) operates exactly as in other buffers:  Emacs
+remembers 16 previous locations of the mark.  To return to a marked
+date, type `C-u C-SPC' (or `C-u C-@'); this is the command
+`calendar-set-mark' given a numeric argument.  It moves point to where
+the mark was, restores the mark from the ring of former marks, and
+stores the previous point at the end of the mark ring.  So, repeated
+use of this command moves point through all the old marks on the ring,
+one by one.
+
+\1f
+File: xemacs.info,  Node: General Calendar,  Next: LaTeX Calendar,  Prev: Mark and Region,  Up: Calendar/Diary
+
+Miscellaneous Calendar Commands
+-------------------------------
+
+`p d'
+     Display day-in-year (`calendar-print-day-of-year').
+
+`?'
+     Briefly describe calendar commands (`describe-calendar-mode').
+
+`C-c C-l'
+     Regenerate the calendar window (`redraw-calendar').
+
+`SPC'
+     Scroll the next window (`scroll-other-window').
+
+`q'
+     Exit from calendar (`exit-calendar').
+
+   If you want to know how many days have elapsed since the start of
+the year, or the number of days remaining in the year, type the `p d'
+command (`calendar-print-day-of-year').  This displays both of those
+numbers in the echo area.
+
+   To display a brief description of the calendar commands, type `?'
+(`describe-calendar-mode').  For a fuller description, type `C-h m'.
+
+   You can use `SPC' (`scroll-other-window') to scroll the other
+window.  This is handy when you display a list of holidays or diary
+entries in another window.
+
+   If the calendar window text gets corrupted, type `C-c C-l'
+(`redraw-calendar') to redraw it.  (This can only happen if you use
+non-Calendar-mode editing commands.)
+
+   In Calendar mode, you can use `SPC' (`scroll-other-window') to
+scroll the other window.  This is handy when you display a list of
+holidays or diary entries in another window.
+
+   To exit from the calendar, type `q' (`exit-calendar').  This buries
+all buffers related to the calendar, selecting other buffers.  (If a
+frame contains a dedicated calendar window, exiting from the calendar
+iconifies that frame.)
+
+\1f
+File: xemacs.info,  Node: LaTeX Calendar,  Next: Holidays,  Prev: General Calendar,  Up: Calendar/Diary
+
+LaTeX Calendar
+==============
+
+The Calendar LaTeX commands produce a buffer of LaTeX code that prints
+as a calendar.  Depending on the command you use, the printed calendar
+covers the day, week, month or year that point is in.
+
+`t m'
+     Generate a one-month calendar (`cal-tex-cursor-month').
+
+`t M'
+     Generate a sideways-printing one-month calendar
+     (`cal-tex-cursor-month-landscape').
+
+`t d'
+     Generate a one-day calendar (`cal-tex-cursor-day').
+
+`t w 1'
+     Generate a one-page calendar for one week (`cal-tex-cursor-week').
+
+`t w 2'
+     Generate a two-page calendar for one week (`cal-tex-cursor-week2').
+
+`t w 3'
+     Generate an ISO-style calendar for one week
+     (`cal-tex-cursor-week-iso').
+
+`t w 4'
+     Generate a calendar for one Monday-starting week
+     (`cal-tex-cursor-week-monday').
+
+`t f w'
+     Generate a Filofax-style two-weeks-at-a-glance calendar
+     (`cal-tex-cursor-filofax-2week').
+
+`t f W'
+     Generate a Filofax-style one-week-at-a-glance calendar
+     (`cal-tex-cursor-filofax-week').
+
+`t y'
+     Generate a calendar for one year (`cal-tex-cursor-year').
+
+`t Y'
+     Generate a sideways-printing calendar for one year
+     (`cal-tex-cursor-year-landscape').
+
+`t f y'
+     Generate a Filofax-style calendar for one year
+     (`cal-tex-cursor-filofax-year').
+
+   Some of these commands print the calendar sideways (in "landscape
+mode"), so it can be wider than it is long.  Some of them use Filofax
+paper size (3.75in x 6.75in).  All of these commands accept a prefix
+argument which specifies how many days, weeks, months or years to print
+(starting always with the selected one).
+
+   If the variable `cal-tex-holidays' is non-`nil' (the default), then
+the printed calendars show the holidays in `calendar-holidays'.  If the
+variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
+entries are included also (in weekly and monthly calendars only).
+
+\1f
+File: xemacs.info,  Node: Holidays,  Next: Sunrise/Sunset,  Prev: LaTeX Calendar,  Up: Calendar/Diary
+
+Holidays
+--------
+
+The Emacs calendar knows about all major and many minor holidays, and
+can display them.
+
+`h'
+     Display holidays for the selected date
+     (`calendar-cursor-holidays').
+
+`Button2 Holidays'
+     Display any holidays for the date you click on.
+
+`x'
+     Mark holidays in the calendar window (`mark-calendar-holidays').
+
+`u'
+     Unmark calendar window (`calendar-unmark').
+
+`a'
+     List all holidays for the displayed three months in another window
+     (`list-calendar-holidays').
+
+`M-x holidays'
+     List all holidays for three months around today's date in another
+     window.
+
+`M-x list-holidays'
+     List holidays in another window for a specified range of years.
+
+   To see if any holidays fall on a given date, position point on that
+date in the calendar window and use the `h' command.  Alternatively,
+click on that date with `Button2' and then choose `Holidays' from the
+menu that appears.  Either way, this displays the holidays for that
+date, in the echo area if they fit there, otherwise in a separate
+window.
+
+   To view the distribution of holidays for all the dates shown in the
+calendar, use the `x' command.  This displays the dates that are
+holidays in a different face (or places a `*' after these dates, if
+display with multiple faces is not available). The command applies both
+to the currently visible months and to other months that subsequently
+become visible by scrolling.  To turn marking off and erase the current
+marks, type `u', which also erases any diary marks (*note Diary::).
+
+   To get even more detailed information, use the `a' command, which
+displays a separate buffer containing a list of all holidays in the
+current three-month range.  You can use <SPC> in the calendar window to
+scroll that list.
+
+   The command `M-x holidays' displays the list of holidays for the
+current month and the preceding and succeeding months; this works even
+if you don't have a calendar window.  If you want the list of holidays
+centered around a different month, use `C-u M-x holidays', which
+prompts for the month and year.
+
+   The holidays known to Emacs include United States holidays and the
+major Christian, Jewish, and Islamic holidays; also the solstices and
+equinoxes.
+
+   The command `M-x list-holidays' displays the list of holidays for a
+range of years.  This function asks you for the starting and stopping
+years, and allows you to choose all the holidays or one of several
+categories of holidays.  You can use this command even if you don't have
+a calendar window.
+
+   The dates used by Emacs for holidays are based on _current
+practice_, not historical fact.  Historically, for instance, the start
+of daylight savings time and even its existence have varied from year to
+year, but present United States law mandates that daylight savings time
+begins on the first Sunday in April.  When the daylight savings rules
+are set up for the United States, Emacs always uses the present
+definition, even though it is wrong for some prior years.
+
+\1f
+File: xemacs.info,  Node: Sunrise/Sunset,  Next: Lunar Phases,  Prev: Holidays,  Up: Calendar/Diary
+
+Times of Sunrise and Sunset
+---------------------------
+
+Special calendar commands can tell you, to within a minute or two, the
+times of sunrise and sunset for any date.
+
+`S'
+     Display times of sunrise and sunset for the selected date
+     (`calendar-sunrise-sunset').
+
+`Button2 Sunrise/Sunset'
+     Display times of sunrise and sunset for the date you click on.
+
+`M-x sunrise-sunset'
+     Display times of sunrise and sunset for today's date.
+
+`C-u M-x sunrise-sunset'
+     Display times of sunrise and sunset for a specified date.
+
+   Within the calendar, to display the _local times_ of sunrise and
+sunset in the echo area, move point to the date you want, and type `S'.
+Alternatively, click `Button2' on the date, then choose
+`Sunrise/Sunset' from the menu that appears.  The command `M-x
+sunrise-sunset' is available outside the calendar to display this
+information for today's date or a specified date.  To specify a date
+other than today, use `C-u M-x sunrise-sunset', which prompts for the
+year, month, and day.
+
+   You can display the times of sunrise and sunset for any location and
+any date with `C-u C-u M-x sunrise-sunset'.  This asks you for a
+longitude, latitude, number of minutes difference from Coordinated
+Universal Time, and date, and then tells you the times of sunrise and
+sunset for that location on that date.
+
+   Because the times of sunrise and sunset depend on the location on
+earth, you need to tell Emacs your latitude, longitude, and location
+name before using these commands.  Here is an example of what to set:
+
+     (setq calendar-latitude 40.1)
+     (setq calendar-longitude -88.2)
+     (setq calendar-location-name "Urbana, IL")
+
+Use one decimal place in the values of `calendar-latitude' and
+`calendar-longitude'.
+
+   Your time zone also affects the local time of sunrise and sunset.
+Emacs usually gets time zone information from the operating system, but
+if these values are not what you want (or if the operating system does
+not supply them), you must set them yourself.  Here is an example:
+
+     (setq calendar-time-zone -360)
+     (setq calendar-standard-time-zone-name "CST")
+     (setq calendar-daylight-time-zone-name "CDT")
+
+The value of `calendar-time-zone' is the number of minutes difference
+between your local standard time and Coordinated Universal Time
+(Greenwich time).  The values of `calendar-standard-time-zone-name' and
+`calendar-daylight-time-zone-name' are the abbreviations used in your
+time zone.  Emacs displays the times of sunrise and sunset _corrected
+for daylight savings time_.  *Note Daylight Savings::, for how daylight
+savings time is determined.
+
+   As a user, you might find it convenient to set the calendar location
+variables for your usual physical location in your init file.  And when
+you install Emacs on a machine, you can create a `default.el' file
+which sets them properly for the typical location of most users of that
+machine.  *Note Init File::.
+
+\1f
+File: xemacs.info,  Node: Lunar Phases,  Next: Other Calendars,  Prev: Sunrise/Sunset,  Up: Calendar/Diary
+
+Phases of the Moon
+------------------
+
+These calendar commands display the dates and times of the phases of
+the moon (new moon, first quarter, full moon, last quarter).  This
+feature is useful for debugging problems that "depend on the phase of
+the moon."
+
+`M'
+     Display the dates and times for all the quarters of the moon for
+     the three-month period shown (`calendar-phases-of-moon').
+
+`M-x phases-of-moon'
+     Display dates and times of the quarters of the moon for three
+     months around today's date.
+
+   Within the calendar, use the `M' command to display a separate
+buffer of the phases of the moon for the current three-month range.  The
+dates and times listed are accurate to within a few minutes.
+
+   Outside the calendar, use the command `M-x phases-of-moon' to
+display the list of the phases of the moon for the current month and the
+preceding and succeeding months.  For information about a different
+month, use `C-u M-x phases-of-moon', which prompts for the month and
+year.
+
+   The dates and times given for the phases of the moon are given in
+local time (corrected for daylight savings, when appropriate); but if
+the variable `calendar-time-zone' is void, Coordinated Universal Time
+(the Greenwich time zone) is used.  *Note Daylight Savings::.
+
+\1f
+File: xemacs.info,  Node: Other Calendars,  Next: Calendar Systems,  Prev: Lunar Phases,  Up: Calendar/Diary
+
+Conversion To and From Other Calendars
+--------------------------------------
+
+The Emacs calendar displayed is _always_ the Gregorian calendar,
+sometimes called the "new style" calendar, which is used in most of the
+world today.  However, this calendar did not exist before the sixteenth
+century and was not widely used before the eighteenth century; it did
+not fully displace the Julian calendar and gain universal acceptance
+until the early twentieth century.  The Emacs calendar can display any
+month since January, year 1 of the current era, but the calendar
+displayed is the Gregorian, even for a date at which the Gregorian
+calendar did not exist.
+
+   While Emacs cannot display other calendars, it can convert dates to
+and from several other calendars.
+
+* Menu:
+
+* Calendar Systems::      The calendars Emacs understands
+                            (aside from Gregorian).
+* To Other Calendar::     Converting the selected date to various calendars.
+* From Other Calendar::   Moving to a date specified in another calendar.
+* Mayan Calendar::        Moving to a date specified in a Mayan calendar.
+
+   If you are interested in these calendars, you can convert dates one
+at a time.  Put point on the desired date of the Gregorian calendar and
+press the appropriate keys.  The `p' is a mnemonic for "print" since
+Emacs "prints' the equivalent date in the echo area.
+
+\1f
+File: xemacs.info,  Node: Calendar Systems,  Next: To Other Calendar,  Prev: Other Calendars,  Up: Other Calendars
+
+Supported Calendar Systems
+==========================
+
+The ISO commercial calendar is used largely in Europe.
+
+   The Julian calendar, named after Julius Caesar, was the one used in
+Europe throughout medieval times, and in many countries up until the
+nineteenth century.
+
+   Astronomers use a simple counting of days elapsed since noon, Monday,
+January 1, 4713 B.C. on the Julian calendar.  The number of days elapsed
+is called the _Julian day number_ or the _Astronomical day number_.
+
+   The Hebrew calendar is used by tradition in the Jewish religion.  The
+Emacs calendar program uses the Hebrew calendar to determine the dates
+of Jewish holidays.  Hebrew calendar dates begin and end at sunset.
+
+   The Islamic calendar is used in many predominantly Islamic countries.
+Emacs uses it to determine the dates of Islamic holidays.  There is no
+universal agreement in the Islamic world about the calendar; Emacs uses
+a widely accepted version, but the precise dates of Islamic holidays
+often depend on proclamation by religious authorities, not on
+calculations.  As a consequence, the actual dates of observance can vary
+slightly from the dates computed by Emacs.  Islamic calendar dates begin
+and end at sunset.
+
+   The French Revolutionary calendar was created by the Jacobins after
+the 1789 revolution, to represent a more secular and nature-based view
+of the annual cycle, and to install a 10-day week in a rationalization
+measure similar to the metric system.  The French government officially
+abandoned this calendar at the end of 1805.
+
+   The Maya of Central America used three separate, overlapping calendar
+systems, the _long count_, the _tzolkin_, and the _haab_.  Emacs knows
+about all three of these calendars.  Experts dispute the exact
+correlation between the Mayan calendar and our calendar; Emacs uses the
+Goodman-Martinez-Thompson correlation in its calculations.
+
+   The Copts use a calendar based on the ancient Egyptian solar
+calendar.  Their calendar consists of twelve 30-day months followed by
+an extra five-day period.  Once every fourth year they add a leap day
+to this extra period to make it six days.  The Ethiopic calendar is
+identical in structure, but has different year numbers and month names.
+
+   The Persians use a solar calendar based on a design of Omar Khayyam.
+Their calendar consists of twelve months of which the first six have 31
+days, the next five have 30 days, and the last has 29 in ordinary years
+and 30 in leap years.  Leap years occur in a complicated pattern every
+four or five years.
+
+   The Chinese calendar is a complicated system of lunar months arranged
+into solar years.  The years go in cycles of sixty, each year containing
+either twelve months in an ordinary year or thirteen months in a leap
+year; each month has either 29 or 30 days.  Years, ordinary months, and
+days are named by combining one of ten "celestial stems" with one of
+twelve "terrestrial branches" for a total of sixty names that are
+repeated in a cycle of sixty.
+
+\1f
+File: xemacs.info,  Node: To Other Calendar,  Next: From Other Calendar,  Prev: Calendar Systems,  Up: Other Calendars
+
+Converting To Other Calendars
+=============================
+
+The following commands describe the selected date (the date at point)
+in various other calendar systems:
+
+`Button2  Other Calendars'
+     Display the date that you click on, expressed in various other
+     calendars.
+
+`p c'
+     Display ISO commercial calendar equivalent for selected day
+     (`calendar-print-iso-date').
+
+`p j'
+     Display Julian date for selected day
+     (`calendar-print-julian-date').
+
+`p a'
+     Display astronomical (Julian) day number for selected day
+     (`calendar-print-astro-day-number').
+
+`p h'
+     Display Hebrew date for selected day
+     (`calendar-print-hebrew-date').
+
+`p i'
+     Display Islamic date for selected day
+     (`calendar-print-islamic-date').
+
+`p f'
+     Display French Revolutionary date for selected day
+     (`calendar-print-french-date').
+
+`p C'
+     Display Chinese date for selected day
+     (`calendar-print-chinese-date').
+
+`p k'
+     Display Coptic date for selected day
+     (`calendar-print-coptic-date').
+
+`p e'
+     Display Ethiopic date for selected day
+     (`calendar-print-ethiopic-date').
+
+`p p'
+     Display Persian date for selected day
+     (`calendar-print-persian-date').
+
+`p m'
+     Display Mayan date for selected day (`calendar-print-mayan-date').
+
+   If you are using X, the easiest way to translate a date into other
+calendars is to click on it with `Button2', then choose `Other
+Calendars' from the menu that appears.  This displays the equivalent
+forms of the date in all the calendars Emacs understands, in the form of
+a menu.  (Choosing an alternative from this menu doesn't actually do
+anything--the menu is used only for display.)
+
+   Put point on the desired date of the Gregorian calendar, then type
+the appropriate keys.  The `p' is a mnemonic for "print" since Emacs
+"prints" the equivalent date in the echo area.
+
+\1f
+File: xemacs.info,  Node: From Other Calendar,  Next: Mayan Calendar,  Prev: To Other Calendar,  Up: Other Calendars
+
+Converting From Other Calendars
+===============================
+
+You can use the other supported calendars to specify a date to move to.
+This section describes the commands for doing this using calendars
+other than Mayan; for the Mayan calendar, see the following section.
+
+`g c'
+     Move to a date specified in the ISO commercial calendar
+     (`calendar-goto-iso-date').
+
+`g j'
+     Move to a date specified in the Julian calendar
+     (`calendar-goto-julian-date').
+
+`g a'
+     Move to a date specified in astronomical (Julian) day number
+     (`calendar-goto-astro-day-number').
+
+`g h'
+     Move to a date specified in the Hebrew calendar
+     (`calendar-goto-hebrew-date').
+
+`g i'
+     Move to a date specified in the Islamic calendar
+     (`calendar-goto-islamic-date').
+
+`g f'
+     Move to a date specified in the French Revolutionary calendar
+     (`calendar-goto-french-date').
+
+`g C'
+     Move to a date specified in the Chinese calendar
+     (`calendar-goto-chinese-date').
+
+`g p'
+     Move to a date specified in the Persian calendar
+     (`calendar-goto-persian-date').
+
+`g k'
+     Move to a date specified in the Coptic calendar
+     (`calendar-goto-coptic-date').
+
+`g e'
+     Move to a date specified in the Ethiopic calendar
+     (`calendar-goto-ethiopic-date').
+
+   These commands ask you for a date on the other calendar, move point
+to the Gregorian calendar date equivalent to that date, and display the
+other calendar's date in the echo area.  Emacs uses strict completion
+(*note Completion::) whenever it asks you to type a month name, so you
+don't have to worry about the spelling of Hebrew, Islamic, or French
+names.
+
+   One common question concerning the Hebrew calendar is the computation
+of the anniversary of a date of death, called a "yahrzeit."  The Emacs
+calendar includes a facility for such calculations.  If you are in the
+calendar, the command `M-x list-yahrzeit-dates' asks you for a range of
+years and then displays a list of the yahrzeit dates for those years
+for the date given by point.  If you are not in the calendar, this
+command first asks you for the date of death and the range of years,
+and then displays the list of yahrzeit dates.
+
+\1f
+File: xemacs.info,  Node: Mayan Calendar,  Next: Diary,  Prev: From Other Calendar,  Up: Other Calendars
+
+Converting from the Mayan Calendar
+----------------------------------
+
+Here are the commands to select dates based on the Mayan calendar:
+
+`g m l'
+     Move to a date specified by the long count calendar
+     (`calendar-goto-mayan-long-count-date').
+
+`g m n t'
+     Move to the next occurrence of a place in the tzolkin calendar
+     (`calendar-next-tzolkin-date').
+
+`g m p t'
+     Move to the previous occurrence of a place in the tzolkin calendar
+     (`calendar-previous-tzolkin-date').
+
+`g m n h'
+     Move to the next occurrence of a place in the haab calendar
+     (`calendar-next-haab-date').
+
+`g m p h'
+     Move to the previous occurrence of a place in the haab calendar
+     (`calendar-previous-haab-date').
+
+`g m n c'
+     Move to the next occurrence of a place in the calendar round
+     (`calendar-next-calendar-round-date').
+
+`g m p c'
+     Move to the previous occurrence of a place in the calendar round
+     (`calendar-previous-calendar-round-date').
+
+   To understand these commands, you need to understand the Mayan
+calendars.  The "long count" is a counting of days with these units:
+
+     1 kin = 1 day   1 uinal = 20 kin   1 tun = 18 uinal
+     1 katun = 20 tun   1 baktun = 20 katun
+
+Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
+tun, 16 uinal, and 6 kin.  The Emacs calendar can handle Mayan long
+count dates as early as 7.17.18.13.1, but no earlier.  When you use the
+`g m l' command, type the Mayan long count date with the baktun, katun,
+tun, uinal, and kin separated by periods.
+
+   The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
+independent cycles of 13 and 20 days.  Since this cycle repeats
+endlessly, Emacs provides commands to move backward and forward to the
+previous or next point in the cycle.  Type `g m p t' to go to the
+previous tzolkin date; Emacs asks you for a tzolkin date and moves point
+to the previous occurrence of that date.  Similarly, type `g m n t' to
+go to the next occurrence of a tzolkin date.
+
+   The Mayan haab calendar is a cycle of 365 days arranged as 18 months
+of 20 days each, followed a 5-day monthless period.  Like the tzolkin
+cycle, this cycle repeats endlessly, and there are commands to move
+backward and forward to the previous or next point in the cycle.  Type
+`g m p h' to go to the previous haab date; Emacs asks you for a haab
+date and moves point to the previous occurrence of that date.
+Similarly, type `g m n h' to go to the next occurrence of a haab date.
+
+   The Maya also used the combination of the tzolkin date and the haab
+date.  This combination is a cycle of about 52 years called a _calendar
+round_.  If you type `g m p c', Emacs asks you for both a haab and a
+tzolkin date and then moves point to the previous occurrence of that
+combination.  Use `g m n c' to move point to the next occurrence of a
+combination.  These commands signal an error if the haab/tzolkin date
+combination you have typed is impossible.
+
+   Emacs uses strict completion (*note Completion::) whenever it asks
+you to type a Mayan name, so you don't have to worry about spelling.
+
+\1f
+File: xemacs.info,  Node: Diary,  Next: Calendar Customization,  Prev: Mayan Calendar,  Up: Calendar/Diary
+
+The Diary
+---------
+
+The Emacs diary keeps track of appointments or other events on a daily
+basis, in conjunction with the calendar.  To use the diary feature, you
+must first create a "diary file" containing a list of events and their
+dates.  Then Emacs can automatically pick out and display the events
+for today, for the immediate future, or for any specified date.
+
+   By default, Emacs uses `~/diary' as the diary file.  This is the
+same file that the `calendar' utility uses.  A sample `~/diary' file is:
+
+     12/22/1988 Twentieth wedding anniversary!!
+     &1/1. Happy New Year!
+     10/22 Ruth's birthday.
+     * 21, *: Payday
+     Tuesday--weekly meeting with grad students at 10am
+              Supowit, Shen, Bitner, and Kapoor to attend.
+     1/13/89 Friday the thirteenth!!
+     &thu 4pm squash game with Lloyd.
+     mar 16 Dad's birthday
+     April 15, 1989 Income tax due.
+     &* 15 time cards due.
+
+This example uses extra spaces to align the event descriptions of most
+of the entries.  Such formatting is purely a matter of taste.
+
+   Although you probably will start by creating a diary manually, Emacs
+provides a number of commands to let you view, add, and change diary
+entries.  You can also share diary entries with other users (*note
+Included Diary Files::).
+
+* Menu:
+
+* Diary Commands::         Viewing diary entries and associated calendar dates.
+* Format of Diary File::   Entering events in your diary.
+* Date Formats::           Various ways you can specify dates.
+* Adding to Diary::        Commands to create diary entries.
+* Special Diary Entries::  Anniversaries, blocks of dates, cyclic entries, etc.
+
+\1f
+File: xemacs.info,  Node: Diary Commands,  Next: Format of Diary File,  Prev: Diary,  Up: Diary
+
+Commands Displaying Diary Entries
+---------------------------------
+
+Once you have created a `~/diary' file, you can use the calendar to
+view it.  You can also view today's events outside of Calendar mode.
+
+`d'
+     Display all diary entries for the selected date
+     (`view-diary-entries').
+
+`Button2 Diary'
+     Display all diary entries for the date you click on.
+
+`s'
+     Display the entire diary file (`show-all-diary-entries').
+
+`m'
+     Mark all visible dates that have diary entries
+     (`mark-diary-entries').
+
+`u'
+     Unmark the calendar window (`calendar-unmark').
+
+`M-x print-diary-entries'
+     Print hard copy of the diary display as it appears.
+
+`M-x diary'
+     Display all diary entries for today's date.
+
+`M-x diary-mail-entries'
+     Mail yourself email reminders about upcoming diary entries.
+
+   Displaying the diary entries with `d' shows in a separate window the
+diary entries for the selected date in the calendar.  The mode line of
+the new window shows the date of the diary entries and any holidays
+that fall on that date.  If you specify a numeric argument with `d', it
+shows all the diary entries for that many successive days.  Thus, `2 d'
+displays all the entries for the selected date and for the following
+day.
+
+   Another way to display the diary entries for a date is to click
+`Button2' on the date, and then choose `Diary' from the menu that
+appears.
+
+   To get a broader view of which days are mentioned in the diary, use
+the `m' command.  This displays the dates that have diary entries in a
+different face (or places a `+' after these dates, if display with
+multiple faces is not available).  The command applies both to the
+currently visible months and to other months that subsequently become
+visible by scrolling.  To turn marking off and erase the current marks,
+type `u', which also turns off holiday marks (*note Holidays::).
+
+   To see the full diary file, rather than just some of the entries, use
+the `s' command.
+
+   Display of selected diary entries uses the selective display feature
+to hide entries that don't apply.
+
+   The diary buffer as you see it is an illusion, so simply printing the
+buffer does not print what you see on your screen.  There is a special
+command to print hard copy of the diary buffer _as it appears_; this
+command is `M-x print-diary-entries'.  It sends the data directly to
+the printer.  You can customize it like `lpr-region' (*note Hardcopy::).
+
+   The command `M-x diary' displays the diary entries for the current
+date, independently of the calendar display, and optionally for the next
+few days as well; the variable `number-of-diary-entries' specifies how
+many days to include (*note Customization::).
+
+   If you put `(diary)' in your init file, this automatically displays
+a window with the day's diary entries, when you enter Emacs.  *Note
+Init File::.  The mode line of the displayed window shows the date and
+any holidays that fall on that date.
+
+   Many users like to receive notice of events in their diary as email.
+To send such mail to yourself, use the command `M-x
+diary-mail-entries'.  A prefix argument specifies how many days
+(starting with today) to check; otherwise, the variable
+`diary-mail-days' says how many days.
+
+\1f
+File: xemacs.info,  Node: Format of Diary File,  Next: Date Formats,  Prev: Diary Commands,  Up: Diary
+
+The Diary File
+--------------
+
+Your "diary file" is a file that records events associated with
+particular dates.  The name of the diary file is specified by the
+variable `diary-file'; `~/diary' is the default.  The `calendar'
+utility program supports a subset of the format allowed by the Emacs
+diary facilities, so you can use that utility to view the diary file,
+with reasonable results aside from the entries it cannot understand.
+
+   Each entry in the diary file describes one event and consists of one
+or more lines.  An entry always begins with a date specification at the
+left margin.  The rest of the entry is simply text to describe the
+event.  If the entry has more than one line, then the lines after the
+first must begin with whitespace to indicate they continue a previous
+entry.  Lines that do not begin with valid dates and do not continue a
+preceding entry are ignored.
+
+   You can inhibit the marking of certain diary entries in the calendar
+window; to do this, insert an ampersand (`&') at the beginning of the
+entry, before the date.  This has no effect on display of the entry in
+the diary window; it affects only marks on dates in the calendar
+window.  Nonmarking entries are especially useful for generic entries
+that would otherwise mark many different dates.
+
+   If the first line of a diary entry consists only of the date or day
+name with no following blanks or punctuation, then the diary window
+display doesn't include that line; only the continuation lines appear.
+For example, this entry:
+
+     02/11/1989
+           Bill B. visits Princeton today
+           2pm Cognitive Studies Committee meeting
+           2:30-5:30 Liz at Lawrenceville
+           4:00pm Dentist appt
+           7:30pm Dinner at George's
+           8:00-10:00pm concert
+
+appears in the diary window without the date line at the beginning.
+This style of entry looks neater when you display just a single day's
+entries, but can cause confusion if you ask for more than one day's
+entries.
+
+   You can edit the diary entries as they appear in the window, but it
+is important to remember that the buffer displayed contains the _entire_
+diary file, with portions of it concealed from view.  This means, for
+instance, that the `C-f' (`forward-char') command can put point at what
+appears to be the end of the line, but what is in reality the middle of
+some concealed line.
+
+   _Be careful when editing the diary entries!_  Inserting additional
+lines or adding/deleting characters in the middle of a visible line
+cannot cause problems, but editing at the end of a line may not do what
+you expect.  Deleting a line may delete other invisible entries that
+follow it.  Before editing the diary, it is best to display the entire
+file with `s' (`show-all-diary-entries').
+
+\1f
+File: xemacs.info,  Node: Date Formats,  Next: Adding to Diary,  Prev: Format of Diary File,  Up: Diary
+
+Date Formats
+------------
+
+Here are some sample diary entries, illustrating different ways of
+formatting a date.  The examples all show dates in American order
+(month, day, year), but Calendar mode supports European order (day,
+month, year) as an option.
+
+     4/20/93  Switch-over to new tabulation system
+     apr. 25  Start tabulating annual results
+     4/30  Results for April are due
+     */25  Monthly cycle finishes
+     Friday  Don't leave without backing up files
+
+   The first entry appears only once, on April 20, 1993.  The second and
+third appear every year on the specified dates, and the fourth uses a
+wildcard (asterisk) for the month, so it appears on the 25th of every
+month.  The final entry appears every week on Friday.
+
+   You can use just numbers to express a date, as in `MONTH/DAY' or
+`MONTH/DAY/YEAR'.  This must be followed by a nondigit.  In the date
+itself, MONTH and DAY are numbers of one or two digits.  The optional
+YEAR is also a number, and may be abbreviated to the last two digits;
+that is, you can use `11/12/1989' or `11/12/89'.
+
+   Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY,
+YEAR', where the month's name can be spelled in full or abbreviated to
+three characters (with or without a period).  Case is not significant.
+
+   A date may be "generic"; that is, partially unspecified.  Then the
+entry applies to all dates that match the specification.  If the date
+does not contain a year, it is generic and applies to any year.
+Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any
+month, day, or year, respectively.  Thus, a diary entry `3/*/*' matches
+any day in March of any year; so does `march *'.
+
+   If you prefer the European style of writing dates--in which the day
+comes before the month--type `M-x european-calendar' while in the
+calendar, or set the variable `european-calendar-style' to `t' _before_
+using any calendar or diary command.  This mode interprets all dates in
+the diary in the European manner, and also uses European style for
+displaying diary dates.  (Note that there is no comma after the
+MONTHNAME in the European style.)  To go back to the (default) American
+style of writing dates, type `M-x american-calendar'.
+
+   You can use the name of a day of the week as a generic date which
+applies to any date falling on that day of the week.  You can abbreviate
+the day of the week to three letters (with or without a period) or spell
+it in full; case is not significant.
+
+\1f
+File: xemacs.info,  Node: Adding to Diary,  Next: Special Diary Entries,  Prev: Date Formats,  Up: Diary
+
+Commands to Add to the Diary
+----------------------------
+
+While in the calendar, there are several commands to create diary
+entries:
+
+`i d'
+     Add a diary entry for the selected date (`insert-diary-entry').
+
+`i w'
+     Add a diary entry for the selected day of the week
+     (`insert-weekly-diary-entry').
+
+`i m'
+     Add a diary entry for the selected day of the month
+     (`insert-monthly-diary-entry').
+
+`i y'
+     Add a diary entry for the selected day of the year
+     (`insert-yearly-diary-entry').
+
+   You can make a diary entry for a specific date by selecting that date
+in the calendar window and typing the `i d' command.  This command
+displays the end of your diary file in another window and inserts the
+date; you can then type the rest of the diary entry.
+
+   If you want to make a diary entry that applies to a specific day of
+the week, select that day of the week (any occurrence will do) and type
+`i w'.  This inserts the day-of-week as a generic date; you can then
+type the rest of the diary entry.  You can make a monthly diary entry in
+the same fashion.  Select the day of the month, use the `i m' command,
+and type rest of the entry.  Similarly, you can insert a yearly diary
+entry with the `i y' command.
+
+   All of the above commands make marking diary entries by default.  To
+make a nonmarking diary entry, give a numeric argument to the command.
+For example, `C-u i w' makes a nonmarking weekly diary entry.
+
+   When you modify the diary file, be sure to save the file before
+exiting Emacs.
+
+\1f
+File: xemacs.info,  Node: Special Diary Entries,  Prev: Adding to Diary,  Up: Diary
+
+Special Diary Entries
+---------------------
+
+In addition to entries based on calendar dates, the diary file can
+contain "sexp entries" for regular events such as anniversaries.  These
+entries are based on Lisp expressions (sexps) that Emacs evaluates as
+it scans the diary file.  Instead of a date, a sexp entry contains `%%'
+followed by a Lisp expression which must begin and end with
+parentheses.  The Lisp expression determines which dates the entry
+applies to.
+
+   Calendar mode provides commands to insert certain commonly used sexp
+entries:
+
+`i a'
+     Add an anniversary diary entry for the selected date
+     (`insert-anniversary-diary-entry').
+
+`i b'
+     Add a block diary entry for the current region
+     (`insert-block-diary-entry').
+
+`i c'
+     Add a cyclic diary entry starting at the date
+     (`insert-cyclic-diary-entry').
+
+   If you want to make a diary entry that applies to the anniversary of
+a specific date, move point to that date and use the `i a' command.
+This displays the end of your diary file in another window and inserts
+the anniversary description; you can then type the rest of the diary
+entry. The entry looks like this:
+
+   The effect of `i a' is to add a `diary-anniversary' sexp to your
+diary file.  You can also add one manually, for instance:
+
+     %%(diary-anniversary 10 31 1948) Arthur's birthday
+
+This entry applies to October 31 in any year after 1948; `10 31 1948'
+specifies the date.  (If you are using the European calendar style, the
+month and day are interchanged.)  The reason this expression requires a
+beginning year is that advanced diary functions can use it to calculate
+the number of elapsed years.
+
+   A "block" diary entry applies to a specified range of consecutive
+dates.  Here is a block diary entry that applies to all dates from June
+24, 1990 through July 10, 1990:
+
+     %%(diary-block 6 24 1990 7 10 1990) Vacation
+
+The `6 24 1990' indicates the starting date and the `7 10 1990'
+indicates the stopping date.  (Again, if you are using the European
+calendar style, the month and day are interchanged.)
+
+   To insert a block entry, place point and the mark on the two dates
+that begin and end the range, and type `i b'.  This command displays
+the end of your diary file in another window and inserts the block
+description; you can then type the diary entry.
+
+   "Cyclic" diary entries repeat after a fixed interval of days.  To
+create one, select the starting date and use the `i c' command.  The
+command prompts for the length of interval, then inserts the entry,
+which looks like this:
+
+     %%(diary-cyclic 50 3 1 1990) Renew medication
+
+This entry applies to March 1, 1990 and every 50th day following; `3 1
+1990' specifies the starting date.  (If you are using the European
+calendar style, the month and day are interchanged.)
+
+   All three of these commands make marking diary entries.  To insert a
+nonmarking entry, give a numeric argument to the command.  For example,
+`C-u i a' makes a nonmarking anniversary diary entry.
+
+   Marking sexp diary entries in the calendar is _extremely_
+time-consuming, since every date visible in the calendar window must be
+individually checked.  So it's a good idea to make sexp diary entries
+nonmarking (with `&') when possible.
+
+   Another sophisticated kind of sexp entry, a "floating" diary entry,
+specifies a regularly occurring event by offsets specified in days,
+weeks, and months.  It is comparable to a crontab entry interpreted by
+the `cron' utility.  Here is a nonmarking, floating diary entry that
+applies to the last Thursday in November:
+
+     &%%(diary-float 11 4 -1) American Thanksgiving
+
+The 11 specifies November (the eleventh month), the 4 specifies Thursday
+(the fourth day of the week, where Sunday is numbered zero), and the -1
+specifies "last" (1 would mean "first", 2 would mean "second", -2 would
+mean "second-to-last", and so on).  The month can be a single month or
+a list of months.  Thus you could change the 11 above to `'(1 2 3)' and
+have the entry apply to the last Thursday of January, February, and
+March.  If the month is `t', the entry applies to all months of the
+year.
+
+   The sexp feature of the diary allows you to specify diary entries
+based on any Emacs Lisp expression.  You can use the library of built-in
+functions or you can write your own functions.  The built-in functions
+include the ones shown in this section, plus a few others (*note Sexp
+Diary Entries::).
+
+   The generality of sexps lets you specify any diary entry that you can
+describe algorithmically.  Suppose you get paid on the 21st of the month
+if it is a weekday, and to the Friday before if the 21st is on a
+weekend.  The diary entry
+
+     &%%(let ((dayname (calendar-day-of-week date))
+              (day (car (cdr date))))
+           (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
+               (and (memq day '(19 20)) (= dayname 5)))
+              ) Pay check deposited
+
+to just those dates.  This example illustrates how the sexp can depend
+on the variable `date'; this variable is a list (MONTH DAY YEAR) that
+gives the Gregorian date for which the diary entries are being found.
+If the value of the sexp is `t', the entry applies to that date.  If
+the sexp evaluates to `nil', the entry does _not_ apply to that date.
+
+\1f
+File: xemacs.info,  Node: Calendar Customization,  Prev: Diary,  Up: Calendar/Diary
+
+Customizing the Calendar and Diary
+----------------------------------
+
+There are many customizations that you can use to make the calendar and
+diary suit your personal tastes.
+
+* Menu:
+
+* Calendar Customizing::   Defaults you can set.
+* Holiday Customizing::    Defining your own holidays.
+* Date Display Format::    Changing the format.
+* Time Display Format::    Changing the format.
+* Daylight Savings::       Changing the default.
+* Diary Customizing::      Defaults you can set.
+* Hebrew/Islamic Entries:: How to obtain them.
+* Fancy Diary Display::    Enhancing the diary display, sorting entries.
+* Included Diary Files::   Sharing a common diary file.
+* Sexp Diary Entries::     Fancy things you can do.
+* Appt Customizing::      Customizing appointment reminders.
+
+\1f
+File: xemacs.info,  Node: Calendar Customizing,  Next: Holiday Customizing,  Up: Calendar Customization
+
+Customizing the Calendar
+........................
+
+If you set the variable `view-diary-entries-initially' to `t', calling
+up the calendar automatically displays the diary entries for the
+current date as well.  The diary dates appear only if the current date
+is visible.  If you add both of the following lines to your init file:
+
+     (setq view-diary-entries-initially t)
+     (calendar)
+
+this displays both the calendar and diary windows whenever you start
+Emacs.  *Note Init File::.
+
+   Similarly, if you set the variable
+`view-calendar-holidays-initially' to `t', entering the calendar
+automatically displays a list of holidays for the current three-month
+period.  The holiday list appears in a separate window.
+
+   You can set the variable `mark-diary-entries-in-calendar' to `t' in
+order to mark any dates with diary entries.  This takes effect whenever
+the calendar window contents are recomputed.  There are two ways of
+marking these dates: by changing the face (*note Faces::), if the
+display supports that, or by placing a plus sign (`+') beside the date
+otherwise.
+
+   Similarly, setting the variable `mark-holidays-in-calendar' to `t'
+marks holiday dates, either with a change of face or with an asterisk
+(`*').
+
+   The variable `calendar-holiday-marker' specifies how to mark a date
+as being a holiday.  Its value may be a character to insert next to the
+date, or a face name to use for displaying the date.  Likewise, the
+variable `diary-entry-marker' specifies how to mark a date that has
+diary entries.  The calendar creates faces named `holiday-face' and
+`diary-face' for these purposes; those symbols are the default values
+of these variables, when Emacs supports multiple faces on your terminal.
+
+   The variable `calendar-load-hook' is a normal hook run when the
+calendar package is first loaded (before actually starting to display
+the calendar).
+
+   Starting the calendar runs the normal hook
+`initial-calendar-window-hook'.  Recomputation of the calendar display
+does not run this hook.  But if you leave the calendar with the `q'
+command and reenter it, the hook runs again.
+
+   The variable `today-visible-calendar-hook' is a normal hook run
+after the calendar buffer has been prepared with the calendar when the
+current date is visible in the window.  One use of this hook is to
+replace today's date with asterisks; to do that, use the hook function
+`calendar-star-date'.
+
+     (add-hook 'today-visible-calendar-hook 'calendar-star-date)
+
+Another standard hook function marks the current date, either by
+changing its face or by adding an asterisk.  Here's how to use it:
+
+     (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
+
+The variable `calendar-today-marker' specifies how to mark today's
+date.  Its value should be a character to insert next to the date or a
+face name to use for displaying the date.  A face named
+`calendar-today-face' is provided for this purpose; that symbol is the
+default for this variable when Emacs supports multiple faces on your
+terminal.
+
+A similar normal hook, `today-invisible-calendar-hook' is run if the
+current date is _not_ visible in the window.
+
+\1f
+File: xemacs.info,  Node: Holiday Customizing,  Next: Date Display Format,  Prev: Calendar Customizing,  Up: Calendar Customization
+
+Customizing the Holidays
+........................
+
+Emacs knows about holidays defined by entries on one of several lists.
+You can customize these lists of holidays to your own needs, adding or
+deleting holidays.  The lists of holidays that Emacs uses are for
+general holidays (`general-holidays'), local holidays
+(`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
+(Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
+(`islamic-holidays'), and other holidays (`other-holidays').
+
+   The general holidays are, by default, holidays common throughout the
+United States.  To eliminate these holidays, set `general-holidays' to
+`nil'.
+
+   There are no default local holidays (but sites may supply some).  You
+can set the variable `local-holidays' to any list of holidays, as
+described below.
+
+   By default, Emacs does not include all the holidays of the religions
+that it knows, only those commonly found in secular calendars.  For a
+more extensive collection of religious holidays, you can set any (or
+all) of the variables `all-christian-calendar-holidays',
+`all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
+`t'.  If you want to eliminate the religious holidays, set any or all
+of the corresponding variables `christian-holidays', `hebrew-holidays',
+and `islamic-holidays' to `nil'.
+
+   You can set the variable `other-holidays' to any list of holidays.
+This list, normally empty, is intended for individual use.
+
+   Each of the lists (`general-holidays', `local-holidays',
+`christian-holidays', `hebrew-holidays', `islamic-holidays', and
+`other-holidays') is a list of "holiday forms", each holiday form
+describing a holiday (or sometimes a list of holidays).
+
+   Here is a table of the possible kinds of holiday form.  Day numbers
+and month numbers count starting from 1, but "dayname" numbers count
+Sunday as 0.  The element STRING is always the name of the holiday, as
+a string.
+
+`(holiday-fixed MONTH DAY STRING)'
+     A fixed date on the Gregorian calendar.  MONTH and DAY are
+     numbers, STRING is the name of the holiday.
+
+`(holiday-float MONTH DAYNAME K STRING)'
+     The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
+     Sunday, and so on); negative K means count back from the end of
+     the month.  STRING is the name of the holiday.
+
+`(holiday-hebrew MONTH DAY STRING)'
+     A fixed date on the Hebrew calendar.  MONTH and DAY are numbers,
+     STRING is the name of the holiday.
+
+`(holiday-islamic MONTH DAY STRING)'
+     A fixed date on the Islamic calendar.  MONTH and DAY are numbers,
+     STRING is the name of the holiday.
+
+`(holiday-julian MONTH DAY STRING)'
+     A fixed date on the Julian calendar.  MONTH and DAY are numbers,
+     STRING is the name of the holiday.
+
+`(holiday-sexp SEXP STRING)'
+     A date calculated by the Lisp expression SEXP.  The expression
+     should use the variable `year' to compute and return the date of a
+     holiday, or `nil' if the holiday doesn't happen this year.  The
+     value of SEXP must represent the date as a list of the form
+     `(MONTH DAY YEAR)'.  STRING is the name of the holiday.
+
+`(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
+     A holiday that happens only if CONDITION is true.
+
+`(FUNCTION [ARGS])'
+     A list of dates calculated by the function FUNCTION, called with
+     arguments ARGS.
+
+   For example, suppose you want to add Bastille Day, celebrated in
+France on July 14.  You can do this by adding the following line to
+your init file:
+
+     (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
+
+   *Note Init File::.
+
+The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
+fourteenth day of the seventh month (July).
+
+   Many holidays occur on a specific day of the week, at a specific time
+of month.  Here is a holiday form describing Hurricane Supplication Day,
+celebrated in the Virgin Islands on the fourth Monday in August:
+
+     (holiday-float 8 1 4 "Hurricane Supplication Day")
+
+Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
+Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
+the month (1 specifies the first occurrence, 2 the second occurrence,
+-1 the last occurrence, -2 the second-to-last occurrence, and so on).
+
+   You can specify holidays that occur on fixed days of the Hebrew,
+Islamic, and Julian calendars too.  For example,
+
+     (setq other-holidays
+           '((holiday-hebrew 10 2 "Last day of Hanukkah")
+             (holiday-islamic 3 12 "Mohammed's Birthday")
+             (holiday-julian 4 2 "Jefferson's Birthday")))
+
+adds the last day of Hanukkah (since the Hebrew months are numbered with
+1 starting from Nisan), the Islamic feast celebrating Mohammed's
+birthday (since the Islamic months are numbered from 1 starting with
+Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
+Julian calendar.
+
+   To include a holiday conditionally, use either Emacs Lisp's `if' or
+the `holiday-sexp' form.  For example, American presidential elections
+occur on the first Tuesday after the first Monday in November of years
+divisible by 4:
+
+     (holiday-sexp (if (= 0 (% year 4))
+                        (calendar-gregorian-from-absolute
+                      (1+ (calendar-dayname-on-or-before
+                            1 (+ 6 (calendar-absolute-from-gregorian
+                                     (list 11 1 year))))))
+                   "US Presidential Election"))
+
+or
+
+     (if (= 0 (% displayed-year 4))
+         (fixed 11
+                (extract-calendar-day
+                  (calendar-gregorian-from-absolute
+                    (1+ (calendar-dayname-on-or-before
+                          1 (+ 6 (calendar-absolute-from-gregorian
+                                   (list 11 1 displayed-year)))))))
+                "US Presidential Election"))
+
+   Some holidays just don't fit into any of these forms because special
+calculations are involved in their determination.  In such cases you
+must write a Lisp function to do the calculation.  To include eclipses,
+for example, add `(eclipses)' to `other-holidays' and write an Emacs
+Lisp function `eclipses' that returns a (possibly empty) list of the
+relevant Gregorian dates among the range visible in the calendar
+window, with descriptive strings, like this:
+
+     (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+
+\1f
+File: xemacs.info,  Node: Date Display Format,  Next: Time Display Format,  Prev: Holiday Customizing,  Up: Calendar Customization
+
+Date Display Format
+...................
+
+You can customize the manner of displaying dates in the diary, in mode
+lines, and in messages by setting `calendar-date-display-form'.  This
+variable holds a list of expressions that can involve the variables
+`month', `day', and `year', which are all numbers in string form, and
+`monthname' and `dayname', which are both alphabetic strings.  In the
+American style, the default value of this list is as follows:
+
+     ((if dayname (concat dayname ", ")) monthname " " day ", " year)
+
+while in the European style this value is the default:
+
+     ((if dayname (concat dayname ", ")) day " " monthname " " year)
+
+   + The ISO standard date representation is this:
+
+     (year "-" month "-" day)
+
+This specifies a typical American format:
+
+     (month "/" day "/" (substring year -2))
+
+\1f
+File: xemacs.info,  Node: Time Display Format,  Next: Daylight Savings,  Prev: Date Display Format,  Up: Calendar Customization
+
+Time Display Format
+...................
+
+The calendar and diary by default display times of day in the
+conventional American style with the hours from 1 through 12, minutes,
+and either `am' or `pm'.  If you prefer the European style, also known
+in the US as military, in which the hours go from 00 to 23, you can
+alter the variable `calendar-time-display-form'.  This variable is a
+list of expressions that can involve the variables `12-hours',
+`24-hours', and `minutes', which are all numbers in string form, and
+`am-pm' and `time-zone', which are both alphabetic strings.  The
+default value of `calendar-time-display-form' is as follows:
+
+     (12-hours ":" minutes am-pm
+               (if time-zone " (") time-zone (if time-zone ")"))
+
+Here is a value that provides European style times:
+
+     (24-hours ":" minutes
+               (if time-zone " (") time-zone (if time-zone ")"))
+
+gives military-style times like `21:07 (UT)' if time zone names are
+defined, and times like `21:07' if they are not.
+
+\1f
+File: xemacs.info,  Node: Daylight Savings,  Next: Diary Customizing,  Prev: Time Display Format,  Up: Calendar Customization
+
+Daylight Savings Time
+.....................
+
+Emacs understands the difference between standard time and daylight
+savings time--the times given for sunrise, sunset, solstices,
+equinoxes, and the phases of the moon take that into account.  The rules
+for daylight savings time vary from place to place and have also varied
+historically from year to year.  To do the job properly, Emacs needs to
+know which rules to use.
+
+   Some operating systems keep track of the rules that apply to the
+place where you are; on these systems, Emacs gets the information it
+needs from the system automatically.  If some or all of this
+information is missing, Emacs fills in the gaps with the rules
+currently used in Cambridge, Massachusetts.  If the resulting rules are
+not what you want, you can tell Emacs the rules to use by setting
+certain variables.
+
+   If the default choice of rules is not appropriate for your location,
+you can tell Emacs the rules to use by setting the variables
+`calendar-daylight-savings-starts' and
+`calendar-daylight-savings-ends'.  Their values should be Lisp
+expressions that refer to the variable `year', and evaluate to the
+Gregorian date on which daylight savings time starts or (respectively)
+ends, in the form of a list `(MONTH DAY YEAR)'.  The values should be
+`nil' if your area does not use daylight savings time.
+
+   Emacs uses these expressions to determine the starting date of
+daylight savings time for the holiday list  and for correcting times of
+day in the solar and lunar calculations.
+
+   The values for Cambridge, Massachusetts are as follows:
+
+     (calendar-nth-named-day 1 0 4 year)
+     (calendar-nth-named-day -1 0 10 year)
+
+That is, the first 0th day (Sunday) of the fourth month (April) in the
+year specified by `year', and the last Sunday of the tenth month
+(October) of that year.  If daylight savings time were changed to start
+on October 1, you would set `calendar-daylight-savings-starts' to this:
+
+     (list 10 1 year)
+
+   For a more complex example, suppose daylight savings time begins on
+the first of Nisan on the Hebrew calendar.  You should set
+`calendar-daylight-savings-starts' to this value:
+
+     (calendar-gregorian-from-absolute
+       (calendar-absolute-from-hebrew
+         (list 1 1 (+ year 3760))))
+
+because Nisan is the first month in the Hebrew calendar and the Hebrew
+year differs from the Gregorian year by 3760 at Nisan.
+
+   If there is no daylight savings time at your location, or if you want
+all times in standard time, set `calendar-daylight-savings-starts' and
+`calendar-daylight-savings-ends' to `nil'.
+
+   The variable `calendar-daylight-time-offset' specifies the
+difference between daylight savings time and standard time, measured in
+minutes.  The value for Cambridge, Massachusetts is 60.
+
+   The two variables `calendar-daylight-savings-starts-time' and
+`calendar-daylight-savings-ends-time' specify the number of minutes
+after midnight local time when the transition to and from daylight
+savings time should occur.  For Cambridge, Massachusetts both variables'
+values are 120.
+
+\1f
+File: xemacs.info,  Node: Diary Customizing,  Next: Hebrew/Islamic Entries,  Prev: Daylight Savings,  Up: Calendar Customization
+
+Customizing the Diary
+.....................
+
+Ordinarily, the mode line of the diary buffer window indicates any
+holidays that fall on the date of the diary entries.  The process of
+checking for holidays can take several seconds, so including holiday
+information delays the display of the diary buffer noticeably.  If you'd
+prefer to have a faster display of the diary buffer but without the
+holiday information, set the variable `holidays-in-diary-buffer' to
+`nil'.
+
+   The variable `number-of-diary-entries' controls the number of days
+of diary entries to be displayed at one time.  It affects the initial
+display when `view-diary-entries-initially' is `t', as well as the
+command `M-x diary'.  For example, the default value is 1, which says
+to display only the current day's diary entries.  If the value is 2,
+both the current day's and the next day's entries are displayed.  The
+value can also be a vector of seven elements: for example, if the value
+is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the
+current date's and the next day's diary entries appear Monday through
+Thursday, Friday through Monday's entries appear on Friday, while on
+Saturday only that day's entries appear.
+
+   The variable `print-diary-entries-hook' is a normal hook run after
+preparation of a temporary buffer containing just the diary entries
+currently visible in the diary buffer.  (The other, irrelevant diary
+entries are really absent from the temporary buffer; in the diary
+buffer, they are merely hidden.)  The default value of this hook does
+the printing with the command `lpr-buffer'.  If you want to use a
+different command to do the printing, just change the value of this
+hook.  Other uses might include, for example, rearranging the lines into
+order by day and time.
+
+   You can customize the form of dates in your diary file, if neither
+the standard American nor European styles suits your needs, by setting
+the variable `diary-date-forms'.  This variable is a list of patterns
+for recognizing a date.  Each date pattern is a list whose elements may
+be regular expressions (*note Regexps::) or the symbols `month', `day',
+`year', `monthname', and `dayname'.  All these elements serve as
+patterns that match certain kinds of text in the diary file.  In order
+for the date pattern, as a whole, to match, all of its elements must
+match consecutively.
+
+   A regular expression in a date pattern matches in its usual fashion,
+using the standard syntax table altered so that `*' is a word
+constituent.
+
+   The symbols `month', `day', `year', `monthname', and `dayname' match
+the month number, day number, year number, month name, and day name of
+the date being considered.  The symbols that match numbers allow
+leading zeros; those that match names allow three-letter abbreviations
+and capitalization.  All the symbols can match `*'; since `*' in a
+diary entry means "any day", "any month", and so on, it should match
+regardless of the date being considered.
+
+   The default value of `diary-date-forms' in the American style is
+this:
+
+     ((month "/" day "[^/0-9]")
+      (month "/" day "/" year "[^0-9]")
+      (monthname " *" day "[^,0-9]")
+      (monthname " *" day ", *" year "[^0-9]")
+      (dayname "\\W"))
+
+Emacs matches of the diary entries with the date forms is done with the
+standard syntax table from Fundamental mode (*note Syntax Tables:
+(lispref)Syntax Tables.), but with the `*' changed so that it is a word
+constituent.
+
+   The date patterns in the list must be _mutually exclusive_ and must
+not match any portion of the diary entry itself, just the date and one
+character of whitespace.  If, to be mutually exclusive, the pattern
+must match a portion of the diary entry text--beyond the whitespace
+that ends the date--then the first element of the date pattern _must_
+be `backup'.  This causes the date recognizer to back up to the
+beginning of the current word of the diary entry, after finishing the
+match.  Even if you use `backup', the date pattern must absolutely not
+match more than a portion of the first word of the diary entry.  The
+default value of `diary-date-forms' in the European style is this list:
+
+     ((day "/" month "[^/0-9]")
+      (day "/" month "/" year "[^0-9]")
+      (backup day " *" monthname "\\W+\\<[^*0-9]")
+      (day " *" monthname " *" year "[^0-9]")
+      (dayname "\\W"))
+
+Notice the use of `backup' in the third pattern, because it needs to
+match part of a word beyond the date itself to distinguish it from the
+fourth pattern.
+
+\1f
+File: xemacs.info,  Node: Hebrew/Islamic Entries,  Next: Fancy Diary Display,  Prev: Diary Customizing,  Up: Calendar Customization
+
+Hebrew- and Islamic-Date Diary Entries
+......................................
+
+Your diary file can have entries based on Hebrew or Islamic dates, as
+well as entries based on the world-standard Gregorian calendar.
+However, because recognition of such entries is time-consuming and most
+people don't use them, you must explicitly enable their use.  If you
+want the diary to recognize Hebrew-date diary entries, for example, you
+must do this:
+
+     (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+     (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+
+If you want Islamic-date entries, do this:
+
+     (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+     (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+
+   Hebrew- and Islamic-date diary entries have the same formats as
+Gregorian-date diary entries, except that `H' precedes a Hebrew date
+and `I' precedes an Islamic date.  Moreover, because the Hebrew and
+Islamic month names are not uniquely specified by the first three
+letters, you may not abbreviate them.  For example, a diary entry for
+the Hebrew date Heshvan 25 could look like this:
+
+     HHeshvan 25 Happy Hebrew birthday!
+
+and would appear in the diary for any date that corresponds to Heshvan
+25 on the Hebrew calendar.  And here is  Islamic-date diary entry  that
+matches Dhu al-Qada 25:
+
+     IDhu al-Qada 25 Happy Islamic birthday!
+
+and would appear in the diary for any date that corresponds to Dhu
+al-Qada 25 on the Islamic calendar.
+
+   As with Gregorian-date diary entries, Hebrew- and Islamic-date
+entries are nonmarking if they are preceded with an ampersand (`&').
+
+   Here is a table of commands used in the calendar to create diary
+entries that match the selected date and other dates that are similar
+in the Hebrew or Islamic calendar:
+
+`i h d'
+     Add a diary entry for the Hebrew date corresponding to the
+     selected date (`insert-hebrew-diary-entry').
+
+`i h m'
+     Add a diary entry for the day of the Hebrew month corresponding to
+     the selected date (`insert-monthly-hebrew-diary-entry').  This
+     diary entry matches any date that has the same Hebrew
+     day-within-month as the selected date.
+
+`i h y'
+     Add a diary entry for the day of the Hebrew year corresponding to
+     the selected date (`insert-yearly-hebrew-diary-entry').  This diary
+     entry matches any date which has the same Hebrew month and
+     day-within-month as the selected date.
+
+`i i d'
+     Add a diary entry for the Islamic date corresponding to the
+     selected date (`insert-islamic-diary-entry').
+
+`i i m'
+     Add a diary entry for the day of the Islamic month corresponding
+     to the selected date (`insert-monthly-islamic-diary-entry').
+
+`i i y'
+     Add a diary entry for the day of the Islamic year corresponding to
+     the selected date (`insert-yearly-islamic-diary-entry').
+
+   These commands work much like the corresponding commands for ordinary
+diary entries: they apply to the date that point is on in the calendar
+window, and what they do is insert just the date portion of a diary
+entry at the end of your diary file.  You must then insert the rest of
+the diary entry.
+
+\1f
+File: xemacs.info,  Node: Fancy Diary Display,  Next: Included Diary Files,  Prev: Hebrew/Islamic Entries,  Up: Calendar Customization
+
+Fancy Diary Display
+...................
+
+Diary display works by preparing the diary buffer and then running the
+hook `diary-display-hook'.  The default value of this hook
+(`simple-diary-display') hides the irrelevant diary entries and then
+displays the buffer.  However, if you specify the hook as follows,
+
+     (add-hook 'diary-display-hook 'fancy-diary-display)
+
+this enables fancy diary display.  It displays diary entries and
+holidays by copying them into a special buffer that exists only for the
+sake of display.  Copying to a separate buffer provides an opportunity
+to change the displayed text to make it prettier--for example, to sort
+the entries by the dates they apply to.
+
+   As with simple diary display, you can print a hard copy of the buffer
+with `print-diary-entries'.  To print a hard copy of a day-by-day diary
+for a week by positioning point on Sunday of that week, type `7 d' and
+then do `M-x print-diary-entries'.  As usual, the inclusion of the
+holidays slows down the display slightly; you can speed things up by
+setting the variable `holidays-in-diary-buffer' to `nil'.
+
+   Ordinarily, the fancy diary buffer does not show days for which
+there are no diary entries, even if that day is a holiday.  If you want
+such days to be shown in the fancy diary buffer, set the variable
+`diary-list-include-blanks' to `t'.
+
+   If you use the fancy diary display, you can use the normal hook
+`list-diary-entries-hook' to sort each day's diary entries by their
+time of day.  Add this line to your init file:
+
+     (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
+
+   *Note Init File::.
+
+For each day, this sorts diary entries that begin with a recognizable
+time of day according to their times.  Diary entries without times come
+first within each day.
+
+\1f
+File: xemacs.info,  Node: Included Diary Files,  Next: Sexp Diary Entries,  Prev: Fancy Diary Display,  Up: Calendar Customization
+
+Included Diary Files
+....................
+
+Fancy diary display also has the ability to process included diary
+files.  This permits a group of people to share a diary file for events
+that apply to all of them.  Lines in the diary file of this form:
+
+     #include "FILENAME"
+
+includes the diary entries from the file FILENAME in the fancy diary
+buffer.  The include mechanism is recursive, so that included files can
+include other files, and so on; you must be careful not to have a cycle
+of inclusions, of course.  Here is how to enable the include facility:
+
+     (add-hook 'list-diary-entries-hook 'include-other-diary-files)
+     (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
+
+   The include mechanism works only with the fancy diary display,
+because ordinary diary display shows the entries directly from your
+diary file.
+
+\1f
+File: xemacs.info,  Node: Sexp Diary Entries,  Next: Appt Customizing,  Prev: Included Diary Files,  Up: Calendar Customization
+
+Sexp Entries and the Fancy Diary Display
+........................................
+
+Sexp diary entries allow you to do more than just have complicated
+conditions under which a diary entry applies.  If you use the fancy
+diary display, sexp entries can generate the text of the entry depending
+on the date itself.  For example, an anniversary diary entry can insert
+the number of years since the anniversary date into the text of the
+diary entry.  Thus the `%d' in this dairy entry:
+
+     %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
+
+gets replaced by the age, so on October 31, 1990 the entry appears in
+the fancy diary buffer like this:
+
+     Arthur's birthday (42 years old)
+
+If the diary file instead contains this entry:
+
+     %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
+
+the entry in the fancy diary buffer for October 31, 1990 appears like
+this:
+
+     Arthur's 42nd birthday
+
+   Similarly, cyclic diary entries can interpolate the number of
+repetitions that have occurred:
+
+     %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+
+looks like this:
+
+     Renew medication (5th time)
+
+in the fancy diary display on September 8, 1990.
+
+   The generality of sexp diary entries lets you specify any diary entry
+that you can describe algorithmically.  A sexp diary entry contains an
+expression that computes whether the entry applies to any given date.
+If its value is non-`nil', the entry applies to that date; otherwise,
+it does not.  The expression can use the variable  `date' to find the
+date being considered; its value is a list (MONTH DAY YEAR) that refers
+to the Gregorian calendar.
+
+   Suppose you get paid on the 21st of the month if it is a weekday, and
+on the Friday before if the 21st is on a weekend.  Here is how to write
+a sexp diary entry that matches those dates:
+
+     &%%(let ((dayname (calendar-day-of-week date))
+              (day (car (cdr date))))
+           (or (and (= day 21) (memq dayname '(1 2 3 4 5)))
+               (and (memq day '(19 20)) (= dayname 5)))
+              ) Pay check deposited
+
+applies to just those dates.  This example illustrates how the sexp can
+depend on the variable `date'; this variable is a list (MONTH DAY YEAR)
+that gives the Gregorian date for which the diary entries are being
+found.  If the value of the expression is `t', the entry applies to
+that date.  If the expression evaluates to `nil', the entry does _not_
+apply to that date.
+
+   The following sexp diary entries take advantage of the ability (in
+the fancy diary display) to concoct diary entries whose text varies
+based on the date:
+
+`%%(diary-sunrise-sunset)'
+     Make a diary entry for the local times of today's sunrise and
+     sunset.
+
+`%%(diary-phases-of-moon)'
+     Make a diary entry for the phases (quarters) of the moon.
+
+`%%(diary-day-of-year)'
+     Make a diary entry with today's day number in the current year and
+     the number of days remaining in the current year.
+
+`%%(diary-iso-date)'
+     Make a diary entry with today's equivalent ISO commercial date.
+
+`%%(diary-julian-date)'
+     Make a diary entry with today's equivalent date on the Julian
+     calendar.
+
+`%%(diary-astro-day-number)'
+     Make a diary entry with today's equivalent astronomical (Julian)
+     day number.
+
+`%%(diary-hebrew-date)'
+     Make a diary entry with today's equivalent date on the Hebrew
+     calendar.
+
+`%%(diary-islamic-date)'
+     Make a diary entry with today's equivalent date on the Islamic
+     calendar.
+
+`%%(diary-french-date)'
+     Make a diary entry with today's equivalent date on the French
+     Revolutionary calendar.
+
+`%%(diary-mayan-date)'
+     Make a diary entry with today's equivalent date on the Mayan
+     calendar.
+
+Thus including the diary entry
+
+     &%%(diary-hebrew-date)
+
+causes every day's diary display to contain the equivalent date on the
+Hebrew calendar, if you are using the fancy diary display.  (With simple
+diary display, the line `&%%(diary-hebrew-date)' appears in the diary
+for any date, but does nothing particularly useful.)
+
+   These functions can be used to construct sexp diary entries based on
+the Hebrew calendar in certain standard ways:
+
+`%%(diary-rosh-hodesh)'
+     Make a diary entry that tells the occurrence and ritual
+     announcement of each new Hebrew month.
+
+`%%(diary-parasha)'
+     Make a Saturday diary entry that tells the weekly synagogue
+     scripture reading.
+
+`%%(diary-sabbath-candles)'
+     Make a Friday diary entry that tells the _local time_ of Sabbath
+     candle lighting.
+
+`%%(diary-omer)'
+     Make a diary entry that gives the omer count, when appropriate.
+
+`%%(diary-yahrzeit MONTH DAY YEAR) NAME'
+     Make a diary entry marking the anniversary of a date of death.
+     The date is the _Gregorian_ (civil) date of death.  The diary
+     entry appears on the proper Hebrew calendar anniversary and on the
+     day before.  (In the European style, the order of the parameters
+     is changed to DAY, MONTH, YEAR.)
+
+\1f
+File: xemacs.info,  Node: Appt Customizing,  Prev: Sexp Diary Entries,  Up: Calendar Customization
+
+Customizing Appointment Reminders
+.................................
+
+You can specify exactly how Emacs reminds you of an appointment, and
+how far in advance it begins doing so, by setting these variables:
+
+`appt-message-warning-time'
+     The time in minutes before an appointment that the reminder
+     begins.  The default is 10 minutes.
+
+`appt-audible'
+     If this is `t' (the default), Emacs rings the terminal bell for
+     appointment reminders.
+
+`appt-visible'
+     If this is `t' (the default), Emacs displays the appointment
+     message in echo area.
+
+`appt-display-mode-line'
+     If this is `t' (the default), Emacs displays the number of minutes
+     to the appointment on the mode line.
+
+`appt-msg-window'
+     If this is `t' (the default), Emacs displays the appointment
+     message in another window.
+
+`appt-display-duration'
+     The number of seconds an appointment message is displayed.  The
+     default is 5 seconds.
+
+\1f
+File: xemacs.info,  Node: Sorting,  Next: Shell,  Prev: Calendar/Diary,  Up: Top
+
+Sorting Text
+============
+
+XEmacs provides several commands for sorting text in a buffer.  All
+operate on the contents of the region (the text between point and the
+mark).  They divide the text of the region into many "sort records",
+identify a "sort key" for each record, and then reorder the records
+using the order determined by the sort keys.  The records are ordered so
+that their keys are in alphabetical order, or, for numerical sorting, in
+numerical order.  In alphabetical sorting, all upper-case letters `A'
+through `Z' come before lower-case `a', in accordance with the ASCII
+character sequence.
+
+   The sort commands differ in how they divide the text into sort
+records and in which part of each record they use as the sort key.
+Most of the commands make each line a separate sort record, but some
+commands use paragraphs or pages as sort records.  Most of the sort
+commands use each entire sort record as its own sort key, but some use
+only a portion of the record as the sort key.
+
+`M-x sort-lines'
+     Divide the region into lines and sort by comparing the entire text
+     of a line.  A prefix argument means sort in descending order.
+
+`M-x sort-paragraphs'
+     Divide the region into paragraphs and sort by comparing the entire
+     text of a paragraph (except for leading blank lines).  A prefix
+     argument means sort in descending order.
+
+`M-x sort-pages'
+     Divide the region into pages and sort by comparing the entire text
+     of a page (except for leading blank lines).  A prefix argument
+     means sort in descending order.
+
+`M-x sort-fields'
+     Divide the region into lines and sort by comparing the contents of
+     one field in each line.  Fields are defined as separated by
+     whitespace, so the first run of consecutive non-whitespace
+     characters in a line constitutes field 1, the second such run
+     constitutes field 2, etc.
+
+     You specify which field to sort by with a numeric argument: 1 to
+     sort by field 1, etc.  A negative argument means sort in descending
+     order.  Thus, minus 2 means sort by field 2 in reverse-alphabetical
+     order.
+
+`M-x sort-numeric-fields'
+     Like `M-x sort-fields', except the specified field is converted to
+     a number for each line and the numbers are compared.  `10' comes
+     before `2' when considered as text, but after it when considered
+     as a number.
+
+`M-x sort-columns'
+     Like `M-x sort-fields', except that the text within each line used
+     for comparison comes from a fixed range of columns.  An explanation
+     is given below.
+
+   For example, if the buffer contains:
+
+     On systems where clash detection (locking of files being edited) is
+     implemented, XEmacs also checks the first time you modify a buffer
+     whether the file has changed on disk since it was last visited or
+     saved.  If it has, you are asked to confirm that you want to change
+     the buffer.
+
+then if you apply `M-x sort-lines' to the entire buffer you get:
+
+     On systems where clash detection (locking of files being edited) is
+     implemented, XEmacs also checks the first time you modify a buffer
+     saved.  If it has, you are asked to confirm that you want to change
+     the buffer.
+     whether the file has changed on disk since it was last visited or
+
+where the upper case `O' comes before all lower case letters.  If you
+apply instead `C-u 2 M-x sort-fields' you get:
+
+     saved.  If it has, you are asked to confirm that you want to change
+     implemented, XEmacs also checks the first time you modify a buffer
+     the buffer.
+     On systems where clash detection (locking of files being edited) is
+     whether the file has changed on disk since it was last visited or
+
+where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'.
+
+   `M-x sort-columns' requires more explanation.  You specify the
+columns by putting point at one of the columns and the mark at the other
+column.  Because this means you cannot put point or the mark at the
+beginning of the first line to sort, this command uses an unusual
+definition of `region': all of the line point is in is considered part
+of the region, and so is all of the line the mark is in.
+
+   For example, to sort a table by information found in columns 10 to
+15, you could put the mark on column 10 in the first line of the table,
+and point on column 15 in the last line of the table, and then use this
+command.  Or you could put the mark on column 15 in the first line and
+point on column 10 in the last line.
+
+   This can be thought of as sorting the rectangle specified by point
+and the mark, except that the text on each line to the left or right of
+the rectangle moves along with the text inside the rectangle.  *Note
+Rectangles::.
+
+\1f
+File: xemacs.info,  Node: Shell,  Next: Narrowing,  Prev: Sorting,  Up: Top
+
+Running Shell Commands from XEmacs
+==================================
+
+XEmacs has commands for passing single command lines to inferior shell
+processes; it can also run a shell interactively with input and output
+to an XEmacs buffer `*shell*'.
+
+`M-!'
+     Run a specified shell command line and display the output
+     (`shell-command').
+
+`M-|'
+     Run a specified shell command line with region contents as input;
+     optionally replace the region with the output
+     (`shell-command-on-region').
+
+`M-x shell'
+     Run a subshell with input and output through an XEmacs buffer.
+     You can then give commands interactively.
+
+`M-x term'
+     Run a subshell with input and output through an XEmacs buffer.
+     You can then give commands interactively.  Full terminal emulation
+     is available.
+
+* Menu:
+
+* Single Shell::         How to run one shell command and return.
+* Interactive Shell::    Permanent shell taking input via XEmacs.
+* Shell Mode::           Special XEmacs commands used with permanent shell.
+* Terminal emulator::    An XEmacs window as a terminal emulator.
+* Term Mode::            Special XEmacs commands used in Term mode.
+* Paging in Term::       Paging in the terminal emulator.
+
+\1f
+File: xemacs.info,  Node: Single Shell,  Next: Interactive Shell,  Prev: Shell,  Up: Shell
+
+Single Shell Commands
+---------------------
+
+`M-!' (`shell-command') reads a line of text using the minibuffer and
+creates an inferior shell to execute the line as a command.  Standard
+input from the command comes from the null device.  If the shell
+command produces any output, the output goes to an XEmacs buffer named
+`*Shell Command Output*', which is displayed in another window but not
+selected.  A numeric argument, as in `M-1 M-!', directs this command to
+insert any output into the current buffer.  In that case, point is left
+before the output and the mark is set after the output.
+
+   `M-|' (`shell-command-on-region') is like `M-!' but passes the
+contents of the region as input to the shell command, instead of no
+input.  If a numeric argument is used to direct  output to the current
+buffer, then the old region is deleted first and the output replaces it
+as the contents of the region.
+
+   Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
+use.  This variable is initialized based on your `SHELL' environment
+variable when you start XEmacs.  If the file name does not specify a
+directory, the directories in the list `exec-path' are searched; this
+list is initialized based on the `PATH' environment variable when you
+start XEmacs.  You can override either or both of these default
+initializations in your init file. *Note Init File::.
+
+   When you use `M-!' and `M-|', XEmacs has to wait until the shell
+command completes.  You can quit with `C-g'; that terminates the shell
+command.
+
+\1f
+File: xemacs.info,  Node: Interactive Shell,  Next: Shell Mode,  Prev: Single Shell,  Up: Shell
+
+Interactive Inferior Shell
+--------------------------
+
+To run a subshell interactively with its typescript in an XEmacs
+buffer, use `M-x shell'.  This creates (or reuses) a buffer named
+`*shell*' and runs a subshell with input coming from and output going
+to that buffer.  That is to say, any "terminal output" from the subshell
+will go into the buffer, advancing point, and any "terminal input" for
+the subshell comes from text in the buffer.  To give input to the
+subshell, go to the end of the buffer and type the input, terminated by
+<RET>.
+
+   XEmacs does not wait for the subshell to do anything.  You can switch
+windows or buffers and edit them while the shell is waiting, or while
+it is running a command.  Output from the subshell waits until XEmacs
+has time to process it; this happens whenever XEmacs is waiting for
+keyboard input or for time to elapse.
+
+   To get multiple subshells, change the name of buffer `*shell*' to
+something different by using `M-x rename-buffer'.  The next use of `M-x
+shell' creates a new buffer `*shell*' with its own subshell.  By
+renaming this buffer as well you can create a third one, and so on.
+All the subshells run independently and in parallel.
+
+   The file name used to load the subshell is the value of the variable
+`explicit-shell-file-name', if that is non-`nil'.  Otherwise, the
+environment variable `ESHELL' is used, or the environment variable
+`SHELL' if there is no `ESHELL'.  If the file name specified is
+relative, the directories in the list `exec-path' are searched (*note
+Single Shell Commands: Single Shell.).
+
+   As soon as the subshell is started, it is sent as input the contents
+of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME
+is the name of the file that the shell was loaded from.  For example,
+if you use `csh', the file sent to it is `~/.emacs_csh'.
+
+   `cd', `pushd', and `popd' commands given to the inferior shell are
+watched by XEmacs so it can keep the `*shell*' buffer's default
+directory the same as the shell's working directory.  These commands
+are recognized syntactically by examining lines of input that are sent.
+If you use aliases for these commands, you can tell XEmacs to
+recognize them also.  For example, if the value of the variable
+`shell-pushd-regexp' matches the beginning of a shell command line,
+that line is regarded as a `pushd' command.  Change this variable when
+you add aliases for `pushd'.  Likewise, `shell-popd-regexp' and
+`shell-cd-regexp' are used to recognize commands with the meaning of
+`popd' and `cd'.
+
+   `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs'
+idea of what the current directory stack is.  `M-x
+shell-dirtrack-toggle' turns directory tracking on and off.
+
+   XEmacs keeps a history of the most recent commands you have typed in
+the `*shell*' buffer.  If you are at the beginning of a shell command
+line and type <M-p>, the previous shell input is inserted into the
+buffer before point.  Immediately typing <M-p> again deletes that input
+and inserts the one before it.  By repeating <M-p> you can move
+backward through your commands until you find one you want to repeat.
+You may then edit the command before typing <RET> if you wish. <M-n>
+moves forward through the command history, in case you moved backward
+past the one you wanted while using <M-p>.  If you type the first few
+characters of a previous command and then type <M-p>, the most recent
+shell input starting with those characters is inserted.  This can be
+very convenient when you are repeating a sequence of shell commands.
+The variable `input-ring-size' controls how many commands are saved in
+your input history.  The default is 30.
+
+\1f
+File: xemacs.info,  Node: Shell Mode,  Next: Terminal emulator,  Prev: Interactive Shell,  Up: Shell
+
+Shell Mode
+----------
+
+The shell buffer uses Shell mode, which defines several special keys
+attached to the `C-c' prefix.  They are chosen to resemble the usual
+editing and job control characters present in shells that are not under
+XEmacs, except that you must type `C-c' first.  Here is a list of the
+special key bindings of Shell mode:
+
+`<RET>'
+     At end of buffer send line as input; otherwise, copy current line
+     to end of buffer and send it (`send-shell-input').  When a line is
+     copied, any text at the beginning of the line that matches the
+     variable `shell-prompt-pattern' is left out; this variable's value
+     should be a regexp string that matches the prompts that you use in
+     your subshell.
+
+`C-c C-d'
+     Send end-of-file as input, probably causing the shell or its
+     current subjob to finish (`shell-send-eof').
+
+`C-d'
+     If point is not at the end of the buffer, delete the next
+     character just like most other modes.  If point is at the end of
+     the buffer, send end-of-file as input, instead of generating an
+     error as in other modes (`comint-delchar-or-maybe-eof').
+
+`C-c C-u'
+     Kill all text that has yet to be sent as input
+     (`kill-shell-input').
+
+`C-c C-w'
+     Kill a word before point (`backward-kill-word').
+
+`C-c C-c'
+     Interrupt the shell or its current subjob if any
+     (`interrupt-shell-subjob').
+
+`C-c C-z'
+     Stop the shell or its current subjob if any (`stop-shell-subjob').
+
+`C-c C-\'
+     Send quit signal to the shell or its current subjob if any
+     (`quit-shell-subjob').
+
+`C-c C-o'
+     Delete last batch of output from shell (`kill-output-from-shell').
+
+`C-c C-r'
+     Scroll top of last batch of output to top of window
+     (`show-output-from-shell').
+
+`C-c C-y'
+     Copy the previous bunch of shell input and insert it into the
+     buffer before point (`copy-last-shell-input').  No final newline
+     is inserted, and the input copied is not resubmitted until you type
+     <RET>.
+
+`M-p'
+     Move backward through the input history.  Search for a matching
+     command if you have typed the beginning of a command
+     (`comint-previous-input').
+
+`M-n'
+     Move forward through the input history.  Useful when you are using
+     <M-p> quickly and go past the desired command
+     (`comint-next-input').
+
+`<TAB>'
+     Complete the file name preceding point (`comint-dynamic-complete').
+
+\1f
+File: xemacs.info,  Node: Terminal emulator,  Next: Term Mode,  Prev: Shell Mode,  Up: Shell
+
+Interactive Inferior Shell with Terminal Emulator
+-------------------------------------------------
+
+To run a subshell in a terminal emulator, putting its typescript in an
+XEmacs buffer, use `M-x term'.  This creates (or reuses) a buffer named
+`*term*' and runs a subshell with input coming from your keyboard and
+output going to that buffer.
+
+   All the normal keys that you type are sent without any interpretation
+by XEmacs directly to the subshell, as "terminal input."  Any "echo" of
+your input is the responsibility of the subshell.  (The exception is
+the terminal escape character, which by default is `C-c'. *note Term
+Mode::.)  Any "terminal output" from the subshell goes into the buffer,
+advancing point.
+
+   Some programs (such as XEmacs itself) need to control the appearance
+on the terminal screen in detail.  They do this by sending special
+control codes.  The exact control codes needed vary from terminal to
+terminal, but nowadays most terminals and terminal emulators (including
+xterm) understand the so-called "ANSI escape sequences" (first
+popularized by the Digital's VT100 family of terminal).  The term mode
+also understands these escape sequences, and for each control code does
+the appropriate thing to change the buffer so that the appearance of
+the window will match what it would be on a real terminal.  Thus you
+can actually run XEmacs inside an XEmacs Term window!
+
+   XEmacs does not wait for the subshell to do anything.  You can switch
+windows or buffers and edit them while the shell is waiting, or while
+it is running a command.  Output from the subshell waits until XEmacs
+has time to process it; this happens whenever XEmacs is waiting for
+keyboard input or for time to elapse.
+
+   To make multiple terminal emulators, rename the buffer `*term*' to
+something different using `M-x rename-uniquely', just as with Shell
+mode.
+
+   The file name used to load the subshell is determined the same way
+as for Shell mode.
+
+   Unlike Shell mode, Term mode does not track the current directory by
+examining your input.  Instead, if you use a programmable shell, you
+can have it tell Term what the current directory is.  This is done
+automatically by bash for version 1.15 and later.
+
+\1f
+File: xemacs.info,  Node: Term Mode,  Next: Paging in Term,  Prev: Terminal emulator,  Up: Shell
+
+Term Mode
+---------
+
+Term uses Term mode, which has two input modes: In line mode, Term
+basically acts like Shell mode.  *Note Shell Mode::.  In Char mode,
+each character is sent directly to the inferior subshell, except for
+the Term escape character, normally `C-c'.
+
+   To switch between line and char mode, use these commands:
+     findex term-char-mode
+
+`C-c C-j'
+     Switch to line mode.  Do nothing if already in line mode.
+
+`C-c C-k'
+     Switch to char mode.  Do nothing if already in char mode.
+
+   The following commands are only available in Char mode:
+`C-c C-c'
+     Send a literal <C-c> to the sub-shell.
+
+`C-c C-x'
+     A prefix command to conveniently access the global <C-x> commands.
+     For example, `C-c C-x o' invokes the global binding of `C-x o',
+     which is normally `other-window'.
+
+\1f
+File: xemacs.info,  Node: Paging in Term,  Prev: Term Mode,  Up: Shell
+
+Paging in the terminal emulator
+-------------------------------
+
+Term mode has a pager feature.  When the pager is enabled, term mode
+will pause at the end of each screenful.
+
+`C-c C-q'
+     Toggles the pager feature:  Disables the pager if it is enabled,
+     and vice versa.  This works in both line and char modes.  If the
+     pager enabled, the mode-line contains the word `page'.
+
+   If the pager is enabled, and Term receives more than a screenful of
+output since your last input, Term will enter More break mode.  This is
+indicated by `**MORE**' in the mode-line.  Type a `Space' to display
+the next screenful of output.  Type `?' to see your other options.  The
+interface is similar to the Unix `more' program.
+
+\1f
+File: xemacs.info,  Node: Narrowing,  Next: Hardcopy,  Prev: Shell,  Up: Top
+
+Narrowing
+=========
+
+"Narrowing" means focusing in on some portion of the buffer, making the
+rest temporarily invisible and inaccessible.  Cancelling the narrowing
+and making the entire buffer once again visible is called "widening".
+The amount of narrowing in effect in a buffer at any time is called the
+buffer's "restriction".
+
+`C-x n n'
+     Narrow down to between point and mark (`narrow-to-region').
+
+`C-x n w'
+     Widen to make the entire buffer visible again (`widen').
+
+   Narrowing sometimes makes it easier to concentrate on a single
+subroutine or paragraph by eliminating clutter.  It can also be used to
+restrict the range of operation of a replace command or repeating
+keyboard macro.  The word `Narrow' appears in the mode line whenever
+narrowing is in effect.  When you have narrowed to a part of the
+buffer, that part appears to be all there is.  You can't see the rest,
+can't move into it (motion commands won't go outside the visible part),
+and can't change it in any way.  However, the invisible text is not
+gone; if you save the file, it will be saved.
+
+   The primary narrowing command is `C-x n n' (`narrow-to-region').  It
+sets the current buffer's restrictions so that the text in the current
+region remains visible but all text before the region or after the
+region is invisible.  Point and mark do not change.
+
+   Because narrowing can easily confuse users who do not understand it,
+`narrow-to-region' is normally a disabled command.  Attempting to use
+this command asks for confirmation and gives you the option of enabling
+it; once you enable the command, confirmation will no longer be
+required.  *Note Disabling::.
+
+   To undo narrowing, use `C-x n w' (`widen').  This makes all text in
+the buffer accessible again.
+
+   Use the `C-x =' command to get information on what part of the
+buffer you narrowed down.  *Note Position Info::.
+
+\1f
+File: xemacs.info,  Node: Hardcopy,  Next: Recursive Edit,  Prev: Narrowing,  Up: Top
+
+Hardcopy Output
+===============
+
+The XEmacs commands for making hardcopy derive their names from the
+Unix commands `print' and `lpr'.
+
+`M-x print-buffer'
+     Print hardcopy of current buffer using Unix command `print'
+     (`lpr -p').  This command adds page headings containing the file
+     name and page number.
+
+`M-x lpr-buffer'
+     Print hardcopy of current buffer using Unix command `lpr'.  This
+     command does not add page headings.
+
+`M-x print-region'
+     Like `print-buffer', but prints only the current region.
+
+`M-x lpr-region'
+     Like `lpr-buffer', but prints only the current region.
+
+   All the hardcopy commands pass extra switches to the `lpr' program
+based on the value of the variable `lpr-switches'.  Its value should be
+a list of strings, each string a switch starting with `-'.  For
+example, the value could be `("-Pfoo")' to print on printer `foo'.
+
+\1f
+File: xemacs.info,  Node: Recursive Edit,  Next: Dissociated Press,  Prev: Hardcopy,  Up: Top
+
+Recursive Editing Levels
+========================
+
+A "recursive edit" is a situation in which you are using XEmacs
+commands to perform arbitrary editing while in the middle of another
+XEmacs command.  For example, when you type `C-r' inside a
+`query-replace', you enter a recursive edit in which you can change the
+current buffer.  When you exit from the recursive edit, you go back to
+the `query-replace'.
+
+   "Exiting" a recursive edit means returning to the unfinished
+command, which continues execution.  For example, exiting the recursive
+edit requested by `C-r' in `query-replace' causes query replacing to
+resume.  Exiting is done with `C-M-c' (`exit-recursive-edit').
+
+   You can also "abort" a recursive edit.  This is like exiting, but
+also quits the unfinished command immediately.  Use the command `C-]'
+(`abort-recursive-edit') for this.  *Note Quitting::.
+
+   The mode line shows you when you are in a recursive edit by
+displaying square brackets around the parentheses that always surround
+the major and minor mode names.  Every window's mode line shows the
+square brackets, since XEmacs as a whole, rather than any particular
+buffer, is in a recursive edit.
+
+   It is possible to be in recursive edits within recursive edits.  For
+example, after typing `C-r' in a `query-replace', you might type a
+command that entered the debugger.  In such a case, two or more sets of
+square brackets appear in the mode line(s).  Exiting the inner
+recursive edit (here with the debugger `c' command) resumes the
+query-replace command where it called the debugger.  After the end of
+the query-replace command, you would be able to exit the first
+recursive edit.  Aborting exits only one level of recursive edit; it
+returns to the command level of the previous recursive edit.  You can
+then abort that one as well.
+
+   The command `M-x top-level' aborts all levels of recursive edits,
+returning immediately to the top level command reader.
+
+   The text you edit inside the recursive edit need not be the same text
+that you were editing at top level.  If the command that invokes the
+recursive edit selects a different buffer first, that is the buffer you
+will edit recursively.  You can switch buffers within the recursive edit
+in the normal manner (as long as the buffer-switching keys have not been
+rebound).  While you could theoretically do the rest of your editing
+inside the recursive edit, including visiting files, this could have
+surprising effects (such as stack overflow) from time to time.  It is
+best if you always exit or abort a recursive edit when you no longer
+need it.
+
+   In general, XEmacs tries to avoid using recursive edits.  It is
+usually preferable to allow users to switch among the possible editing
+modes in any order they like.  With recursive edits, the only way to get
+to another state is to go "back" to the state that the recursive edit
+was invoked from.
+
+\1f
+File: xemacs.info,  Node: Dissociated Press,  Next: CONX,  Prev: Recursive Edit,  Up: Top
+
+Dissociated Press
+=================
+
+`M-x dissociated-press' is a command for scrambling a file of text
+either word by word or character by character.  Starting from a buffer
+of straight English, it produces extremely amusing output.  The input
+comes from the current XEmacs buffer.  Dissociated Press writes its
+output in a buffer named `*Dissociation*', and redisplays that buffer
+after every couple of lines (approximately) to facilitate reading it.
+
+   `dissociated-press' asks every so often whether to continue
+operating.  Answer `n' to stop it.  You can also stop at any time by
+typing `C-g'.  The dissociation output remains in the `*Dissociation*'
+buffer for you to copy elsewhere if you wish.
+
+   Dissociated Press operates by jumping at random from one point in the
+buffer to another.  In order to produce plausible output rather than
+gibberish, it insists on a certain amount of overlap between the end of
+one run of consecutive words or characters and the start of the next.
+That is, if it has just printed out `president' and then decides to
+jump to a different point in the file, it might spot the `ent' in
+`pentagon' and continue from there, producing `presidentagon'.  Long
+sample texts produce the best results.
+
+   A positive argument to `M-x dissociated-press' tells it to operate
+character by character, and specifies the number of overlap characters.
+A negative argument tells it to operate word by word and specifies the
+number of overlap words.  In this mode, whole words are treated as the
+elements to be permuted, rather than characters.  No argument is
+equivalent to an argument of two.  For your againformation, the output
+goes only into the buffer `*Dissociation*'.  The buffer you start with
+is not changed.
+
+   Dissociated Press produces nearly the same results as a Markov chain
+based on a frequency table constructed from the sample text.  It is,
+however, an independent, ignoriginal invention.  Dissociated Press
+techniquitously copies several consecutive characters from the sample
+between random choices, whereas a Markov chain would choose randomly for
+each word or character.  This makes for more plausible sounding results
+and runs faster.
+
+   It is a mustatement that too much use of Dissociated Press can be a
+developediment to your real work.  Sometimes to the point of outragedy.
+And keep dissociwords out of your documentation, if you want it to be
+well userenced and properbose.  Have fun.  Your buggestions are welcome.
+
+\1f
+File: xemacs.info,  Node: CONX,  Next: Amusements,  Prev: Dissociated Press,  Up: Top
+
+CONX
+====
+
+Besides producing a file of scrambled text with Dissociated Press, you
+can generate random sentences by using CONX.
+
+`M-x conx'
+     Generate random sentences in the `*conx*' buffer.
+
+`M-x conx-buffer'
+     Absorb the text in the current buffer into the `conx' database.
+
+`M-x conx-init'
+     Forget the current word-frequency tree.
+
+`M-x conx-load'
+     Load a `conx' database that has been previously saved with `M-x
+     conx-save'.
+
+`M-x conx-region'
+     Absorb the text in the current buffer into the `conx' database.
+
+`M-x conx-save'
+     Save the current `conx' database to a file for future retrieval.
+
+   Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
+and then type `M-x conx'.  Output is continuously generated until you
+type <^G>. You can save the `conx' database to a file with `M-x
+conx-save', which you can retrieve with `M-x conx-load'.  To clear the
+database, use `M-x conx-init'.
+
+\1f
+File: xemacs.info,  Node: Amusements,  Next: Emulation,  Prev: CONX,  Up: Top
+
+Other Amusements
+================
+
+If you are a little bit bored, you can try `M-x hanoi'.  If you are
+considerably bored, give it a numeric argument.  If you are very, very
+bored, try an argument of 9.  Sit back and watch.
+
+   When you are frustrated, try the famous Eliza program.  Just do `M-x
+doctor'.  End each input by typing `RET' twice.
+
+   When you are feeling strange, type `M-x yow'.
+
+\1f
+File: xemacs.info,  Node: Emulation,  Next: Customization,  Prev: Amusements,  Up: Top
+
+Emulation
+=========
+
+XEmacs can be programmed to emulate (more or less) most other editors.
+Standard facilities can emulate these:
+
+Viper (a vi emulator)
+     In XEmacs, Viper is the preferred emulation of vi within XEmacs.
+     Viper is designed to allow you to take advantage of the best
+     features of XEmacs while still doing your basic editing in a
+     familiar, vi-like fashion.  Viper provides various different
+     levels of vi emulation, from a quite complete emulation that
+     allows almost no access to native XEmacs commands, to an "expert"
+     mode that combines the most useful vi commands with the most
+     useful XEmacs commands.
+
+     To start Viper, put the command
+
+          (viper-mode)
+
+     in your init file.  *Note Init File::.
+
+     Viper comes with a separate manual that is provided standard with
+     the XEmacs distribution.
+
+EDT (DEC VMS editor)
+     Turn on EDT emulation with `M-x edt-emulation-on'.  `M-x
+     edt-emulation-off' restores normal Emacs command bindings.
+
+     Most of the EDT emulation commands are keypad keys, and most
+     standard Emacs key bindings are still available.  The EDT
+     emulation rebindings are done in the global keymap, so there is no
+     problem switching buffers or major modes while in EDT emulation.
+
+Gosling Emacs
+     Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
+     set-gosmacs-bindings'.  This redefines many keys, mostly on the
+     `C-x' and `ESC' prefixes, to work as they do in Gosmacs.  `M-x
+     set-gnu-bindings' returns to normal XEmacs by rebinding the same
+     keys to the definitions they had at the time `M-x
+     set-gosmacs-bindings' was done.
+
+     It is also possible to run Mocklisp code written for Gosling Emacs.
+     *Note Mocklisp::.
+
+\1f
+File: xemacs.info,  Node: Customization,  Next: Quitting,  Prev: Emulation,  Up: Top
+
+Customization
+*************
+
+This chapter talks about various topics relevant to adapting the
+behavior of Emacs in minor ways.
+
+   All kinds of customization affect only the particular Emacs job that
+you do them in.  They are completely lost when you kill the Emacs job,
+and have no effect on other Emacs jobs you may run at the same time or
+later.  The only way an Emacs job can affect anything outside of it is
+by writing a file; in particular, the only way to make a customization
+`permanent' is to put something in your init file or other appropriate
+file to do the customization in each session.  *Note Init File::.
+
+* Menu:
+
+* Minor Modes::     Each minor mode is one feature you can turn on
+                     independently of any others.
+* Variables::       Many Emacs commands examine Emacs variables
+                     to decide what to do; by setting variables,
+                     you can control their functioning.
+* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
+                     to be replayed with a single command.
+* Key Bindings::    The keymaps say what command each key runs.
+                     By changing them, you can "redefine keys".
+* Syntax::          The syntax table controls how words and expressions
+                     are parsed.
+* Init File::       How to write common customizations in the init file.
+* Audible Bell::    Changing how Emacs sounds the bell.
+* Faces::           Changing the fonts and colors of a region of text.
+* Frame Components::  Controlling the presence and positions of the
+                     menubar, toolbars, and gutters.
+* X Resources::     X resources controlling various aspects of the
+                     behavior of XEmacs.
+
+\1f
+File: xemacs.info,  Node: Minor Modes,  Next: Variables,  Up: Customization
+
+Minor Modes
+===========
+
+Minor modes are options which you can use or not.  For example, Auto
+Fill mode is a minor mode in which <SPC> breaks lines between words as
+you type.  All the minor modes are independent of each other and of the
+selected major mode.  Most minor modes inform you in the mode line when
+they are on; for example, `Fill' in the mode line means that Auto Fill
+mode is on.
+
+   Append `-mode' to the name of a minor mode to get the name of a
+command function that turns the mode on or off.  Thus, the command to
+enable or disable Auto Fill mode is called `M-x auto-fill-mode'.  These
+commands are usually invoked with `M-x', but you can bind keys to them
+if you wish.  With no argument, the function turns the mode on if it was
+off and off if it was on.  This is known as "toggling".  A positive
+argument always turns the mode on, and an explicit zero argument or a
+negative argument always turns it off.
+
+   Auto Fill mode allows you to enter filled text without breaking lines
+explicitly.  Emacs inserts newlines as necessary to prevent lines from
+becoming too long.  *Note Filling::.
+
+   Overwrite mode causes ordinary printing characters to replace
+existing text instead of moving it to the right.  For example, if point
+is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
+mode, it changes to `FOOGAR', instead of `FOOGBAR'.
+
+   Abbrev mode allows you to define abbreviations that automatically
+expand as you type them.  For example, `amd' might expand to `abbrev
+mode'.  *Note Abbrevs::, for full information.
+
+\1f
+File: xemacs.info,  Node: Variables,  Next: Keyboard Macros,  Prev: Minor Modes,  Up: Customization
+
+Variables
+=========
+
+A "variable" is a Lisp symbol which has a value.  Variable names can
+contain any characters, but by convention they are words separated by
+hyphens.  A variable can also have a documentation string, which
+describes what kind of value it should have and how the value will be
+used.
+
+   Lisp allows any variable to have any kind of value, but most
+variables that Emacs uses require a value of a certain type.  Often the
+value has to be a string or a number.  Sometimes we say that a certain
+feature is turned on if a variable is "non-`nil'," meaning that if the
+variable's value is `nil', the feature is off, but the feature is on
+for any other value.  The conventional value to turn on the
+feature--since you have to pick one particular value when you set the
+variable--is `t'.
+
+   Emacs uses many Lisp variables for internal recordkeeping, as any
+Lisp program must, but the most interesting variables for you are the
+ones that exist for the sake of customization.  Emacs does not
+(usually) change the values of these variables; instead, you set the
+values, and thereby alter and control the behavior of certain Emacs
+commands.  These variables are called "options".  Most options are
+documented in this manual and appear in the Variable Index (*note
+Variable Index::).
+
+   One example of a variable which is an option is `fill-column', which
+specifies the position of the right margin (as a number of characters
+from the left margin) to be used by the fill commands (*note Filling::).
+
+* Menu:
+
+* Examining::           Examining or setting one variable's value.
+* Easy Customization::  Convenient and easy customization of variables.
+* Edit Options::        Examining or editing list of all variables' values.
+* Locals::              Per-buffer values of variables.
+* File Variables::      How files can specify variable values.
+
+\1f
+File: xemacs.info,  Node: Examining,  Next: Easy Customization,  Up: Variables
+
+Examining and Setting Variables
+-------------------------------
+
+`C-h v'
+`M-x describe-variable'
+     Print the value and documentation of a variable.
+
+`M-x set-variable'
+     Change the value of a variable.
+
+   To examine the value of a single variable, use `C-h v'
+(`describe-variable'), which reads a variable name using the
+minibuffer, with completion.  It prints both the value and the
+documentation of the variable.
+
+     C-h v fill-column <RET>
+
+prints something like:
+
+     fill-column's value is 75
+     
+     Documentation:
+     *Column beyond which automatic line-wrapping should happen.
+     Automatically becomes local when set in any fashion.
+
+The star at the beginning of the documentation indicates that this
+variable is an option.  `C-h v' is not restricted to options; it allows
+any variable name.
+
+   If you know which option you want to set, you can use `M-x
+set-variable' to set it.  This prompts for the variable name in the
+minibuffer (with completion), and then prompts for a Lisp expression
+for the new value using the minibuffer a second time.  For example,
+
+     M-x set-variable <RET> fill-column <RET> 75 <RET>
+
+sets `fill-column' to 75, as if you had executed the Lisp expression
+`(setq fill-column 75)'.
+
+   Setting variables in this way, like all means of customizing Emacs
+except where explicitly stated, affects only the current Emacs session.
+
+\1f
+File: xemacs.info,  Node: Easy Customization,  Next: Edit Options,  Prev: Examining,  Up: Variables
+
+Easy Customization Interface
+----------------------------
+
+A convenient way to find the user option variables that you want to
+change, and then change them, is with `M-x customize' (or use a
+keyboard shortcut, `C-h C'.  This command creates a "customization
+buffer" with which you can browse through the Emacs user options in a
+logically organized structure, then edit and set their values.  You can
+also use the customization buffer to save settings permanently.  (Not
+all Emacs user options are included in this structure as of yet, but we
+are adding the rest.)
+
+* Menu:
+
+* Groups: Customization Groups.
+                             How options are classified in a structure.
+* Changing an Option::       How to edit a value and set an option.
+* Face Customization::       How to edit the attributes of a face.
+* Specific Customization::   Making a customization buffer for specific
+                                options, faces, or groups.
+
+\1f
+File: xemacs.info,  Node: Customization Groups,  Next: Changing an Option,  Up: Easy Customization
+
+Customization Groups
+....................
+
+For customization purposes, user options are organized into "groups" to
+help you find them.  Groups are collected into bigger groups, all the
+way up to a master group called `Emacs'.
+
+   `M-x customize' (or `C-h C') creates a customization buffer that
+shows the top-level `Emacs' group and the second-level groups
+immediately under it.  It looks like this, in part:
+
+     /- Emacs group: ---------------------------------------------------\
+           [State]: visible group members are all at standard settings.
+        Customization of the One True Editor.
+        See also [Manual].
+     
+      [Open] Editing group
+     Basic text editing facilities.
+     
+      [Open] External group
+     Interfacing to external utilities.
+     
+     MORE SECOND-LEVEL GROUPS
+     
+     \- Emacs group end ------------------------------------------------/
+
+This says that the buffer displays the contents of the `Emacs' group.
+The other groups are listed because they are its contents.  But they
+are listed differently, without indentation and dashes, because _their_
+contents are not included.  Each group has a single-line documentation
+string; the `Emacs' group also has a `[State]' line.
+
+   Most of the text in the customization buffer is read-only, but it
+typically includes some "editable fields" that you can edit.  There are
+also "active fields"; this means a field that does something when you
+"invoke" it.  To invoke an active field, either click on it with
+`Mouse-1', or move point to it and type <RET>.
+
+   For example, the phrase `[Open]' that appears in a second-level
+group is an active field.  Invoking the `[Open]' field for a group
+opens up a new customization buffer, which shows that group and its
+contents.  This field is a kind of hypertext link to another group.
+
+   The `Emacs' group does not include any user options itself, but
+other groups do.  By examining various groups, you will eventually find
+the options and faces that belong to the feature you are interested in
+customizing.  Then you can use the customization buffer to set them.
+
+   You can view the structure of customization groups on a larger scale
+with `M-x customize-browse'.  This command creates a special kind of
+customization buffer which shows only the names of the groups (and
+options and faces), and their structure.
+
+   In this buffer, you can show the contents of a group by invoking
+`[+]'.  When the group contents are visible, this button changes to
+`[-]'; invoking that hides the group contents.
+
+   Each group, option or face name in this buffer has an active field
+which says `[Group]', `[Option]' or `[Face]'.  Invoking that active
+field creates an ordinary customization buffer showing just that group
+and its contents, just that option, or just that face.  This is the way
+to set values in it.
+
+\1f
+File: xemacs.info,  Node: Changing an Option,  Next: Face Customization,  Prev: Customization Groups,  Up: Easy Customization
+
+Changing an Option
+..................
+
+Here is an example of what a user option looks like in the
+customization buffer:
+
+     Kill Ring Max: [Hide] 30
+        [State]: this option is unchanged from its standard setting.
+     Maximum length of kill ring before oldest elements are thrown away.
+
+   The text following `[Hide]', `30' in this case, indicates the
+current value of the option.  If you see `[Show]' instead of `[Hide]',
+it means that the value is hidden; the customization buffer initially
+hides values that take up several lines.  Invoke `[Show]' to show the
+value.
+
+   The line after the option name indicates the "customization state"
+of the option: in the example above, it says you have not changed the
+option yet.  The word `[State]' at the beginning of this line is
+active; you can get a menu of various operations by invoking it with
+`Mouse-1' or <RET>.  These operations are essential for customizing the
+variable.
+
+   The line after the `[State]' line displays the beginning of the
+option's documentation string.  If there are more lines of
+documentation, this line ends with `[More]'; invoke this to show the
+full documentation string.
+
+   To enter a new value for `Kill Ring Max', move point to the value
+and edit it textually.  For example, you can type `M-d', then insert
+another number.
+
+   When you begin to alter the text, you will see the `[State]' line
+change to say that you have edited the value:
+
+     [State]: you have edited the value as text, but not set the option.
+
+   Editing the value does not actually set the option variable.  To do
+that, you must "set" the option.  To do this, invoke the word `[State]'
+and choose `Set for Current Session'.
+
+   The state of the option changes visibly when you set it:
+
+     [State]: you have set this option, but not saved it for future sessions.
+
+   You don't have to worry about specifying a value that is not valid;
+setting the option checks for validity and will not really install an
+unacceptable value.
+
+   While editing a value or field that is a file name, directory name,
+command name, or anything else for which completion is defined, you can
+type `M-<TAB>' (`widget-complete') to do completion.
+
+   Some options have a small fixed set of possible legitimate values.
+These options don't let you edit the value textually.  Instead, an
+active field `[Value Menu]' appears before the value; invoke this field
+to edit the value.  For a boolean "on or off" value, the active field
+says `[Toggle]', and it changes to the other value.  `[Value Menu]' and
+`[Toggle]' edit the buffer; the changes take effect when you use the
+`Set for Current Session' operation.
+
+   Some options have values with complex structure.  For example, the
+value of `load-path' is a list of directories.  Here is how it appears
+in the customization buffer:
+
+     Load Path:
+     [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
+     [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
+     [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
+     [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
+     [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
+     [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
+     [INS]
+        [State]: this item has been changed outside the customization buffer.
+     List of directories to search for files to load....
+
+Each directory in the list appears on a separate line, and each line has
+several editable or active fields.
+
+   You can edit any of the directory names.  To delete a directory from
+the list, invoke `[DEL]' on that line.  To insert a new directory in
+the list, invoke `[INS]' at the point where you want to insert it.
+
+   You can also invoke `[Current dir?]' to switch between including a
+specific named directory in the path, and including `nil' in the path.
+(`nil' in a search path means "try the current directory.")
+
+   Two special commands, <TAB> and `S-<TAB>', are useful for moving
+through the customization buffer.  <TAB> (`widget-forward') moves
+forward to the next active or editable field; `S-<TAB>'
+(`widget-backward') moves backward to the previous active or editable
+field.
+
+   Typing <RET> on an editable field also moves forward, just like
+<TAB>.  The reason for this is that people have a tendency to type
+<RET> when they are finished editing a field.  If you have occasion to
+insert a newline in an editable field, use `C-o' or `C-q C-j',
+
+   Setting the option changes its value in the current Emacs session;
+"saving" the value changes it for future sessions as well.  This works
+by writing code into your init file so as to set the option variable
+again each time you start Emacs.  *Note Init File::.  To save the
+option, invoke `[State]' and select the `Save for Future Sessions'
+operation.
+
+   You can also restore the option to its standard value by invoking
+`[State]' and selecting the `Reset' operation.  There are actually
+three reset operations:
+
+`Reset to Current'
+     If you have made some modifications and not yet set the option,
+     this restores the text in the customization buffer to match the
+     actual value.
+
+`Reset to Saved'
+     This restores the value of the option to the last saved value, and
+     updates the text accordingly.
+
+`Reset to Standard Settings'
+     This sets the option to its standard value, and updates the text
+     accordingly.  This also eliminates any saved value for the option,
+     so that you will get the standard value in future Emacs sessions.
+
+   The state of a group indicates whether anything in that group has
+been edited, set or saved.  You can select `Set for Current Session',
+`Save for Future Sessions' and the various kinds of `Reset' operation
+for the group; these operations on the group apply to all options in
+the group and its subgroups.
+
+   Near the top of the customization buffer there are two lines
+containing several active fields:
+
+      [Set] [Save] [Reset]  [Done]
+
+Invoking `[Done]' buries this customization buffer.  Each of the other
+fields performs an operation--set, save or reset--on each of the items
+in the buffer that could meaningfully be set, saved or reset.
+
+\1f
+File: xemacs.info,  Node: Face Customization,  Next: Specific Customization,  Prev: Changing an Option,  Up: Easy Customization
+
+Customizing Faces
+.................
+
+In addition to user options, some customization groups also include
+faces.  When you show the contents of a group, both the user options and
+the faces in the group appear in the customization buffer.  Here is an
+example of how a face looks:
+
+     Custom Changed Face: (sample)
+        [State]: this face is unchanged from its standard setting.
+     Face used when the customize item has been changed.
+     Parent groups: [Custom Magic Faces]
+     Attributes: [ ] Bold: [Toggle]  off (nil)
+                 [ ] Italic: [Toggle]  off (nil)
+                 [ ] Underline: [Toggle]  off (nil)
+                 [ ] Foreground: white       (sample)
+                 [ ] Background: blue        (sample)
+                 [ ] Inverse: [Toggle]  off (nil)
+                 [ ] Stipple:
+                 [ ] Font Family:
+                 [ ] Size:
+                 [ ] Strikethru: off
+
+   Each face attribute has its own line.  The `[X]' field before the
+attribute name indicates whether the attribute is "enabled"; `X' means
+that it is.  You can enable or disable the attribute by invoking that
+field.  When the attribute is enabled, you can change the attribute
+value in the usual ways.
+
+   *Note Faces::, for description of how `face-frob-from-locale-first'
+variable affects changing `Bold' and `Italic' attributes.
+
+   Setting, saving and resetting a face work like the same operations
+for options (*note Changing an Option::).
+
+   A face can specify different appearances for different types of
+display.  For example, a face can make text red on a color display, but
+use a bold font on a monochrome display.  To specify multiple
+appearances for a face, select `Show Display Types' in the menu you get
+from invoking `[State]'.
+
+\1f
+File: xemacs.info,  Node: Specific Customization,  Prev: Face Customization,  Up: Easy Customization
+
+Customizing Specific Items
+..........................
+
+Instead of finding the options you want to change by moving down
+through the structure of groups, you can specify the particular option,
+face or group that you want to customize.
+
+`M-x customize-option <RET> OPTION <RET>'
+     Set up a customization buffer with just one option, OPTION.
+
+`M-x customize-face <RET> FACE <RET>'
+     Set up a customization buffer with just one face, FACE.
+
+`M-x customize-group <RET> GROUP <RET>'
+     Set up a customization buffer with just one group, GROUP.
+
+`M-x customize-apropos <RET> REGEXP <RET>'
+     Set up a customization buffer with all the options, faces and
+     groups that match REGEXP.
+
+`M-x customize-saved'
+     Set up a customization buffer containing all options and faces
+     that you have saved with customization buffers.
+
+`M-x customize-customized'
+     Set up a customization buffer containing all options and faces
+     that you have customized but not saved.
+
+   If you want to alter a particular user option variable with the
+customization buffer, and you know its name, you can use the command
+`M-x customize-option' and specify the option name.  This sets up the
+customization buffer with just one option--the one that you asked for.
+Editing, setting and saving the value work as described above, but only
+for the specified option.
+
+   Likewise, you can modify a specific face, chosen by name, using `M-x
+customize-face'.
+
+   You can also set up the customization buffer with a specific group,
+using `M-x customize-group'.  The immediate contents of the chosen
+group, including option variables, faces, and other groups, all appear
+as well.  However, these subgroups' own contents start out hidden.  You
+can show their contents in the usual way, by invoking `[Show]'.
+
+   To control more precisely what to customize, you can use `M-x
+customize-apropos'.  You specify a regular expression as argument; then
+all options, faces and groups whose names match this regular expression
+are set up in the customization buffer.  If you specify an empty regular
+expression, this includes _all_ groups, options and faces in the
+customization buffer (but that takes a long time).
+
+   If you change option values and then decide the change was a mistake,
+you can use two special commands to revisit your previous changes.  Use
+`customize-saved' to look at the options and faces that you have saved.
+Use `M-x customize-customized' to look at the options and faces that
+you have set but not saved.
+
+\1f
+File: xemacs.info,  Node: Edit Options,  Next: Locals,  Prev: Easy Customization,  Up: Variables
+
+Editing Variable Values
+-----------------------
+
+`M-x list-options'
+     Display a buffer listing names, values, and documentation of all
+     options.
+
+`M-x edit-options'
+     Change option values by editing a list of options.
+
+   `M-x list-options' displays a list of all Emacs option variables in
+an Emacs buffer named `*List Options*'.  Each option is shown with its
+documentation and its current value.  Here is what a portion of it might
+look like:
+
+     ;; exec-path:
+     ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
+     *List of directories to search programs to run in subprocesses.
+     Each element is a string (directory name)
+     or nil (try the default directory).
+     ;;
+     ;; fill-column:
+     75
+     *Column beyond which automatic line-wrapping should happen.
+     Automatically becomes local when set in any fashion.
+     ;;
+
+   `M-x edit-options' goes one step further and immediately selects the
+`*List Options*' buffer; this buffer uses the major mode Options mode,
+which provides commands that allow you to point at an option and change
+its value:
+
+`s'
+     Set the variable point is in or near to a new value read using the
+     minibuffer.
+
+`x'
+     Toggle the variable point is in or near: if the value was `nil',
+     it becomes `t'; otherwise it becomes `nil'.
+
+`1'
+     Set the variable point is in or near to `t'.
+
+`0'
+     Set the variable point is in or near to `nil'.
+
+`n'
+`p'
+     Move to the next or previous variable.
+
+\1f
+File: xemacs.info,  Node: Locals,  Next: File Variables,  Prev: Edit Options,  Up: Variables
+
+Local Variables
+---------------
+
+`M-x make-local-variable'
+     Make a variable have a local value in the current buffer.
+
+`M-x kill-local-variable'
+     Make a variable use its global value in the current buffer.
+
+`M-x make-variable-buffer-local'
+     Mark a variable so that setting it will make it local to the
+     buffer that is current at that time.
+
+   You can make any variable "local" to a specific Emacs buffer.  This
+means that the variable's value in that buffer is independent of its
+value in other buffers.  A few variables are always local in every
+buffer.  All other Emacs variables have a "global" value which is in
+effect in all buffers that have not made the variable local.
+
+   Major modes always make the variables they set local to the buffer.
+This is why changing major modes in one buffer has no effect on other
+buffers.
+
+   `M-x make-local-variable' reads the name of a variable and makes it
+local to the current buffer.  Further changes in this buffer will not
+affect others, and changes in the global value will not affect this
+buffer.
+
+   `M-x make-variable-buffer-local' reads the name of a variable and
+changes the future behavior of the variable so that it automatically
+becomes local when it is set.  More precisely, once you have marked a
+variable in this way, the usual ways of setting the variable will
+automatically invoke `make-local-variable' first.  We call such
+variables "per-buffer" variables.
+
+   Some important variables have been marked per-buffer already.  They
+include `abbrev-mode', `auto-fill-function', `case-fold-search',
+`comment-column', `ctl-arrow', `fill-column', `fill-prefix',
+`indent-tabs-mode', `left-margin',
+`mode-line-format', `overwrite-mode', `selective-display-ellipses',
+`selective-display', `tab-width', and `truncate-lines'.  Some other
+variables are always local in every buffer, but they are used for
+internal purposes.
+
+   Note: the variable `auto-fill-function' was formerly named
+`auto-fill-hook'.
+
+   If you want a variable to cease to be local to the current buffer,
+call `M-x kill-local-variable' and provide the name of a variable to
+the prompt.  The global value of the variable is again in effect in
+this buffer.  Setting the major mode kills all the local variables of
+the buffer.
+
+   To set the global value of a variable, regardless of whether the
+variable has a local value in the current buffer, you can use the Lisp
+function `setq-default'.  It works like `setq'.  If there is a local
+value in the current buffer, the local value is not affected by
+`setq-default'; thus, the new global value may not be visible until you
+switch to another buffer, as in the case of:
+
+     (setq-default fill-column 75)
+
+`setq-default' is the only way to set the global value of a variable
+that has been marked with `make-variable-buffer-local'.
+
+   Programs can look at a variable's default value with `default-value'.
+This function takes a symbol as an argument and returns its default
+value.  The argument is evaluated; usually you must quote it
+explicitly, as in the case of:
+
+     (default-value 'fill-column)
+
+\1f
+File: xemacs.info,  Node: File Variables,  Prev: Locals,  Up: Variables
+
+Local Variables in Files
+------------------------
+
+A file can contain a "local variables list", which specifies the values
+to use for certain Emacs variables when that file is edited.  Visiting
+the file checks for a local variables list and makes each variable in
+the list local to the buffer in which the file is visited, with the
+value specified in the file.
+
+   A local variables list goes near the end of the file, in the last
+page.  (It is often best to put it on a page by itself.)  The local
+variables list starts with a line containing the string `Local
+Variables:', and ends with a line containing the string `End:'.  In
+between come the variable names and values, one set per line, as
+`VARIABLE: VALUE'.  The VALUEs are not evaluated; they are used
+literally.
+
+   The line which starts the local variables list does not have to say
+just `Local Variables:'.  If there is other text before `Local
+Variables:', that text is called the "prefix", and if there is other
+text after, that is called the "suffix".  If a prefix or suffix are
+present, each entry in the local variables list should have the prefix
+before it and the suffix after it.  This includes the `End:' line.  The
+prefix and suffix are included to disguise the local variables list as
+a comment so the compiler or text formatter  will ignore it.  If you do
+not need to disguise the local variables list as a comment in this way,
+there is no need to include a prefix or a suffix.
+
+   Two "variable" names are special in a local variables list: a value
+for the variable `mode' sets the major mode, and a value for the
+variable `eval' is simply evaluated as an expression and the value is
+ignored.  These are not real variables; setting them in any other
+context does not have the same effect.  If `mode' is used in a local
+variables list, it should be the first entry in the list.
+
+   Here is an example of a local variables list:
+     ;;; Local Variables: ***
+     ;;; mode:lisp ***
+     ;;; comment-column:0 ***
+     ;;; comment-start: ";;; "  ***
+     ;;; comment-end:"***" ***
+     ;;; End: ***
+
+   Note that the prefix is `;;; ' and the suffix is ` ***'.  Note also
+that comments in the file begin with and end with the same strings.
+Presumably the file contains code in a language which is enough like
+Lisp for Lisp mode to be useful but in which comments start and end
+differently.  The prefix and suffix are used in the local variables
+list to make the list look like several lines of comments when the
+compiler or interpreter for that language reads the file.
+
+   The start of the local variables list must be no more than 3000
+characters from the end of the file, and must be in the last page if the
+file is divided into pages.  Otherwise, Emacs will not notice it is
+there.  The purpose is twofold: a stray `Local Variables:' not in the
+last page does not confuse Emacs, and Emacs never needs to search a
+long file that contains no page markers and has no local variables list.
+
+   You may be tempted to turn on Auto Fill mode with a local variable
+list.  That is inappropriate.  Whether you use Auto Fill mode or not is
+a matter of personal taste, not a matter of the contents of particular
+files.  If you want to use Auto Fill, set up major mode hooks with your
+init file to turn it on (when appropriate) for you alone (*note Init
+File::).  Don't try to use a local variable list that would impose your
+taste on everyone working with the file.
+
+   XEmacs allows you to specify local variables in the first line of a
+file, in addition to specifying them in the `Local Variables' section
+at the end of a file.
+
+   If the first line of a file contains two occurrences of ``-*-'',
+XEmacs uses the information between them to determine what the major
+mode and variable settings should be.  For example, these are all legal:
+
+             ;;; -*- mode: emacs-lisp -*-
+             ;;; -*- mode: postscript; version-control: never -*-
+             ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
+
+   For historical reasons, the syntax ``-*- modename -*-'' is allowed
+as well; for example, you can use:
+
+             ;;; -*- emacs-lisp -*-
+
+   The variable `enable-local-variables' controls the use of local
+variables lists in files you visit.  The value can be `t', `nil', or
+something else.  A value of `t' means local variables lists are obeyed;
+`nil' means they are ignored; anything else means query.
+
+   The command `M-x normal-mode' always obeys local variables lists and
+ignores this variable.
+
+\1f
+File: xemacs.info,  Node: Keyboard Macros,  Next: Key Bindings,  Prev: Variables,  Up: Customization
+
+Keyboard Macros
+===============
+
+A "keyboard macro" is a command defined by the user to abbreviate a
+sequence of keys.  For example, if you discover that you are about to
+type `C-n C-d' forty times, you can speed your work by defining a
+keyboard macro to invoke `C-n C-d' and calling it with a repeat count
+of forty.
+
+`C-x ('
+     Start defining a keyboard macro (`start-kbd-macro').
+
+`C-x )'
+     End the definition of a keyboard macro (`end-kbd-macro').
+
+`C-x e'
+     Execute the most recent keyboard macro (`call-last-kbd-macro').
+
+`C-u C-x ('
+     Re-execute last keyboard macro, then add more keys to its
+     definition.
+
+`C-x q'
+     When this point is reached during macro execution, ask for
+     confirmation (`kbd-macro-query').
+
+`M-x name-last-kbd-macro'
+     Give a command name (for the duration of the session) to the most
+     recently defined keyboard macro.
+
+`M-x insert-kbd-macro'
+     Insert in the buffer a keyboard macro's definition, as Lisp code.
+
+   Keyboard macros differ from other Emacs commands in that they are
+written in the Emacs command language rather than in Lisp.  This makes
+it easier for the novice to write them and makes them more convenient as
+temporary hacks.  However, the Emacs command language is not powerful
+enough as a programming language to be useful for writing anything
+general or complex.  For such things, Lisp must be used.
+
+   You define a keyboard macro by executing the commands which are its
+definition.  Put differently, as you are defining a keyboard macro, the
+definition is being executed for the first time.  This way, you see
+what the effects of your commands are, and don't have to figure them
+out in your head.  When you are finished, the keyboard macro is defined
+and also has been executed once.  You can then execute the same set of
+commands again by invoking the macro.
+
+* Menu:
+
+* Basic Kbd Macro::     Defining and running keyboard macros.
+* Save Kbd Macro::      Giving keyboard macros names; saving them in files.
+* Kbd Macro Query::     Keyboard macros that do different things each use.
+
+\1f
+File: xemacs.info,  Node: Basic Kbd Macro,  Next: Save Kbd Macro,  Up: Keyboard Macros
+
+Basic Use
+---------
+
+To start defining a keyboard macro, type `C-x (' (`start-kbd-macro').
+From then on, anything you type continues to be executed, but also
+becomes part of the definition of the macro.  `Def' appears in the mode
+line to remind you of what is going on.  When you are finished, the
+`C-x )' command (`end-kbd-macro') terminates the definition, without
+becoming part of it.
+
+   For example,
+
+     C-x ( M-f foo C-x )
+
+defines a macro to move forward a word and then insert `foo'.
+
+   You can give `C-x )' a repeat count as an argument, in which case it
+repeats the macro that many times right after defining it, but defining
+the macro counts as the first repetition (since it is executed as you
+define it).  If you give `C-x )' an argument of 4, it executes the
+macro immediately 3 additional times.  An argument of zero to `C-x e'
+or `C-x )' means repeat the macro indefinitely (until it gets an error
+or you type `C-g').
+
+   Once you have defined a macro, you can invoke it again with the `C-x
+e' command (`call-last-kbd-macro').  You can give the command a repeat
+count numeric argument to execute the macro many times.
+
+   To repeat an operation at regularly spaced places in the text,
+define a macro and include as part of the macro the commands to move to
+the next place you want to use it.  For example, if you want to change
+each line, you should position point at the start of a line, and define
+a macro to change that line and leave point at the start of the next
+line.  Repeating the macro will then operate on successive lines.
+
+   After you have terminated the definition of a keyboard macro, you
+can add to the end of its definition by typing `C-u C-x ('.  This is
+equivalent to plain `C-x (' followed by retyping the whole definition
+so far.  As a consequence it re-executes the macro as previously
+defined.
+
+\1f
+File: xemacs.info,  Node: Save Kbd Macro,  Next: Kbd Macro Query,  Prev: Basic Kbd Macro,  Up: Keyboard Macros
+
+Naming and Saving Keyboard Macros
+---------------------------------
+
+To save a keyboard macro for longer than until you define the next one,
+you must give it a name using `M-x name-last-kbd-macro'.  This reads a
+name as an argument using the minibuffer and defines that name to
+execute the macro.  The macro name is a Lisp symbol, and defining it in
+this way makes it a valid command name for calling with `M-x' or for
+binding a key to with `global-set-key' (*note Keymaps::).  If you
+specify a name that has a prior definition other than another keyboard
+macro, Emacs prints an error message and nothing is changed.
+
+   Once a macro has a command name, you can save its definition in a
+file.  You can then use it in another editing session.  First visit the
+file you want to save the definition in.  Then use the command:
+
+     M-x insert-kbd-macro <RET> MACRONAME <RET>
+
+This inserts some Lisp code that, when executed later, will define the
+same macro with the same definition it has now.  You need not
+understand Lisp code to do this, because `insert-kbd-macro' writes the
+Lisp code for you.  Then save the file.  You can load the file with
+`load-file' (*note Lisp Libraries::).  If the file you save in is your
+initialization file (*note Init File::), then the macro will be defined
+each time you run Emacs.
+
+   If you give `insert-kbd-macro' a prefix argument, it creates
+additional Lisp code to record the keys (if any) that you have bound to
+the keyboard macro, so that the macro is reassigned the same keys when
+you load the file.
+
+\1f
+File: xemacs.info,  Node: Kbd Macro Query,  Prev: Save Kbd Macro,  Up: Keyboard Macros
+
+Executing Macros With Variations
+--------------------------------
+
+You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
+that of `query-replace'.  The macro asks you  each time whether to make
+a change.  When you are defining the macro, type `C-x q' at the point
+where you want the query to occur.  During macro definition, the `C-x
+q' does nothing, but when you invoke the macro, `C-x q' reads a
+character from the terminal to decide whether to continue.
+
+   The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
+`C-l', and `C-r'.  Any other character terminates execution of the
+keyboard macro and is then read as a command.  <SPC> means to continue.
+<DEL> means to skip the remainder of this repetition of the macro,
+starting again from the beginning in the next repetition.  `C-d' means
+to skip the remainder of this repetition and cancel further repetition.
+`C-l' redraws the frame and asks you again for a character to specify
+what to do.  `C-r' enters a recursive editing level, in which you can
+perform editing that is not part of the macro.  When you exit the
+recursive edit using `C-M-c', you are asked again how to continue with
+the keyboard macro.  If you type a <SPC> at this time, the rest of the
+macro definition is executed.  It is up to you to leave point and the
+text in a state such that the rest of the macro will do what you want.
+
+   `C-u C-x q', which is `C-x q' with a numeric argument, performs a
+different function.  It enters a recursive edit reading input from the
+keyboard, both when you type it during the definition of the macro and
+when it is executed from the macro.  During definition, the editing you
+do inside the recursive edit does not become part of the macro.  During
+macro execution, the recursive edit gives you a chance to do some
+particularized editing.  *Note Recursive Edit::.
+
+\1f
+File: xemacs.info,  Node: Key Bindings,  Next: Syntax,  Prev: Keyboard Macros,  Up: Customization
+
+Customizing Key Bindings
+========================
+
+This section deals with the "keymaps" that define the bindings between
+keys and functions, and shows how you can customize these bindings.
+
+   A command is a Lisp function whose definition provides for
+interactive use.  Like every Lisp function, a command has a function
+name, which is a Lisp symbol whose name usually consists of lower case
+letters and hyphens.
+
+* Menu:
+
+* Keymaps::    Definition of the keymap data structure.
+               Names of Emacs's standard keymaps.
+* Rebinding::  How to redefine one key's meaning conveniently.
+* Disabling::  Disabling a command means confirmation is required
+                before it can be executed.  This is done to protect
+                beginners from surprises.
+
+\1f
+File: xemacs.info,  Node: Keymaps,  Next: Rebinding,  Up: Key Bindings
+
+Keymaps
+-------
+
+The bindings between characters and command functions are recorded in
+data structures called "keymaps".  Emacs has many of these.  One, the
+"global" keymap, defines the meanings of the single-character keys that
+are defined regardless of major mode.  It is the value of the variable
+`global-map'.
+
+   Each major mode has another keymap, its "local keymap", which
+contains overriding definitions for the single-character keys that are
+redefined in that mode.  Each buffer records which local keymap is
+installed for it at any time, and the current buffer's local keymap is
+the only one that directly affects command execution.  The local keymaps
+for Lisp mode, C mode, and many other major modes always exist even when
+not in use.  They are the values of the variables `lisp-mode-map',
+`c-mode-map', and so on.  For less frequently used major modes, the
+local keymap is sometimes constructed only when the mode is used for the
+first time in a session, to save space.
+
+   There are local keymaps for the minibuffer, too; they contain various
+completion and exit commands.
+
+   * `minibuffer-local-map' is used for ordinary input (no completion).
+
+   * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
+     like <RET>.  This is used mainly for Mocklisp compatibility.
+
+   * `minibuffer-local-completion-map' is for permissive completion.
+
+   * `minibuffer-local-must-match-map' is for strict completion and for
+     cautious completion.
+
+   * `repeat-complex-command-map' is for use in `C-x <ESC> <ESC>'.
+
+   * `isearch-mode-map' contains the bindings of the special keys which
+     are bound in the pseudo-mode entered with `C-s' and `C-r'.
+
+   Finally, each prefix key has a keymap which defines the key sequences
+that start with it.  For example, `ctl-x-map' is the keymap used for
+characters following a `C-x'.
+
+   * `ctl-x-map' is the variable name for the map used for characters
+     that follow `C-x'.
+
+   * `help-map' is used for characters that follow `C-h'.
+
+   * `esc-map' is for characters that follow <ESC>. All Meta characters
+     are actually defined by this map.
+
+   * `ctl-x-4-map' is for characters that follow `C-x 4'.
+
+   * `mode-specific-map' is for characters that follow `C-c'.
+
+   The definition of a prefix key is the keymap to use for looking up
+the following character.  Sometimes the definition is actually a Lisp
+symbol whose function definition is the following character keymap.  The
+effect is the same, but it provides a command name for the prefix key
+that you can use as a description of what the prefix key is for.  Thus
+the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
+definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
+
+   Prefix key definitions can appear in either the global map or a
+local map.  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 modes can locally redefine a key as a prefix by
+putting a prefix key definition for it in the local map.
+
+   A mode can also put a prefix definition of a global prefix character
+such as `C-x' into its local map.  This is how major modes override the
+definitions of certain keys that start with `C-x'.  This case is
+special, because the local definition does not entirely replace the
+global one.  When both the global and local definitions of a key are
+other keymaps, the next character is looked up in both keymaps, with
+the local definition overriding the global one.  The character after the
+`C-x' is looked up in both the major mode's own keymap for redefined
+`C-x' commands and in `ctl-x-map'.  If the major mode's own keymap for
+`C-x' commands contains `nil', the definition from the global keymap
+for `C-x' commands is used.
+
+\1f
+File: xemacs.info,  Node: Rebinding,  Next: Disabling,  Prev: Keymaps,  Up: Key Bindings
+
+Changing Key Bindings
+---------------------
+
+You can redefine an Emacs key by changing its entry in a keymap.  You
+can change the global keymap, in which case the change is effective in
+all major modes except those that have their own overriding local
+definitions for the same key.  Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+
+* Menu:
+
+* Interactive Rebinding::      Changing Key Bindings Interactively
+* Programmatic Rebinding::     Changing Key Bindings Programmatically
+* Key Bindings Using Strings:: Using Strings for Changing Key Bindings
+
+\1f
+File: xemacs.info,  Node: Interactive Rebinding,  Next: Programmatic Rebinding,  Up: Rebinding
+
+Changing Key Bindings Interactively
+...................................
+
+`M-x global-set-key <RET> KEY CMD <RET>'
+     Defines KEY globally to run CMD.
+
+`M-x local-set-key <RET> KEYS CMD <RET>'
+     Defines KEY locally (in the major mode now in effect) to run CMD.
+
+`M-x local-unset-key <RET> KEYS <RET>'
+     Removes the local binding of KEY.
+
+   CMD is a symbol naming an interactively-callable function.
+
+   When called interactively, KEY is the next complete key sequence
+that you type.  When called as a function, KEY is a string, a vector of
+events, or a vector of key-description lists as described in the
+`define-key' function description.  The binding goes in the current
+buffer's local map, which is shared with other buffers in the same
+major mode.
+
+   The following example:
+
+     M-x global-set-key <RET> C-f next-line <RET>
+
+redefines `C-f' to move down a line.  The fact that CMD is read second
+makes it serve as a kind of confirmation for KEY.
+
+   These functions offer no way to specify a particular prefix keymap as
+the one to redefine in, but that is not necessary, as you can include
+prefixes in KEY.  KEY is read by reading characters one by one until
+they amount to a complete key (that is, not a prefix key).  Thus, if
+you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
+CMD.  But if you type `C-x', another character is read; if that
+character is `4', another character is read, and so on.  For example,
+
+     M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
+
+redefines `C-x 4 $' to run the (fictitious) command
+`spell-other-window'.
+
+   The most general way to modify a keymap is the function
+`define-key', used in Lisp code (such as your init file).  `define-key'
+takes three arguments: the keymap, the key to modify in it, and the new
+definition.  *Note Init File::, for an example.
+`substitute-key-definition' is used similarly; it takes three
+arguments, an old definition, a new definition, and a keymap, and
+redefines in that keymap all keys that were previously defined with the
+old definition to have the new definition instead.
+
+\1f
+File: xemacs.info,  Node: Programmatic Rebinding,  Next: Key Bindings Using Strings,  Prev: Interactive Rebinding,  Up: Rebinding
+
+Changing Key Bindings Programmatically
+......................................
+
+You can use the functions `global-set-key' and `define-key' to rebind
+keys under program control.
+
+``(global-set-key KEYS CMD)''
+     Defines KEYS globally to run CMD.
+
+``(define-key KEYMAP KEYS DEF)''
+     Defines KEYS to run DEF in the keymap KEYMAP.
+
+   KEYMAP is a keymap object.
+
+   KEYS is the sequence of keystrokes to bind.
+
+   DEF is anything that can be a key's definition:
+
+   * `nil', meaning key is undefined in this keymap
+
+   * A command, that is, a Lisp function suitable for interactive
+     calling
+
+   * A string or key sequence vector, which is treated as a keyboard
+     macro
+
+   * A keymap to define a prefix key
+
+   * A symbol so that when the key is looked up, the symbol stands for
+     its function definition, which should at that time be one of the
+     above, or another symbol whose function definition is used, and so
+     on
+
+   * A cons, `(string . defn)', meaning that DEFN is the definition
+     (DEFN should be a valid definition in its own right)
+
+   * A cons, `(keymap . char)', meaning use the definition of CHAR in
+     map KEYMAP
+
+   For backward compatibility, XEmacs allows you to specify key
+sequences as strings.  However, the preferred method is to use the
+representations of key sequences as vectors of keystrokes.  *Note
+Keystrokes::, for more information about the rules for constructing key
+sequences.
+
+   Emacs allows you to abbreviate representations for key sequences in
+most places where there is no ambiguity.  Here are some rules for
+abbreviation:
+
+   * The keysym by itself is equivalent to a list of just that keysym,
+     i.e., `f1' is equivalent to `(f1)'.
+
+   * A keystroke by itself is equivalent to a vector containing just
+     that keystroke, i.e.,  `(control a)' is equivalent to `[(control
+     a)]'.
+
+   * You can use ASCII codes for keysyms that have them. i.e., `65' is
+     equivalent to `A'. (This is not so much an abbreviation as an
+     alternate representation.)
+
+   Here are some examples of programmatically binding keys:
+
+
+     ;;;  Bind `my-command' to <f1>
+     (global-set-key 'f1 'my-command)
+     
+     ;;;  Bind `my-command' to Shift-f1
+     (global-set-key '(shift f1) 'my-command)
+     
+     ;;; Bind `my-command' to C-c Shift-f1
+     (global-set-key '[(control c) (shift f1)] 'my-command)
+     
+     ;;; Bind `my-command' to the middle mouse button.
+     (global-set-key 'button2 'my-command)
+     
+     ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
+     ;;; in the keymap that is in force when you are running `dired'.
+     (define-key dired-mode-map '(meta control button3) 'my-command)
+
+\1f
+File: xemacs.info,  Node: Key Bindings Using Strings,  Prev: Programmatic Rebinding,  Up: Rebinding
+
+Using Strings for Changing Key Bindings
+.......................................
+
+For backward compatibility, you can still use strings to represent key
+sequences.  Thus you can use commands like the following:
+
+     ;;; Bind `end-of-line' to C-f
+     (global-set-key "\C-f" 'end-of-line)
+
+   Note, however, that in some cases you may be binding more than one
+key sequence by using a single command.  This situation can arise
+because in ASCII, `C-i' and <TAB> have the same representation.
+Therefore, when Emacs sees:
+
+     (global-set-key "\C-i" 'end-of-line)
+
+   it is unclear whether the user intended to bind `C-i' or <TAB>.  The
+solution XEmacs adopts is to bind both of these key sequences.
+
+   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)
+
+   This applies only when running under a window system.  If you are
+talking to Emacs through an ASCII-only channel, you do not get any of
+these features.
+
+   Here is a table of pairs of key sequences that behave in a similar
+fashion:
+
+             control h      backspace
+             control l      clear
+             control i      tab
+             control m      return
+             control j      linefeed
+             control [      escape
+             control @      control space
+
+\1f
+File: xemacs.info,  Node: Disabling,  Prev: Rebinding,  Up: Key Bindings
+
+Disabling Commands
+------------------
+
+Disabling a command marks it as requiring confirmation before it can be
+executed.  The purpose of disabling a command is to prevent beginning
+users from executing it by accident and being confused.
+
+   The direct mechanism for disabling a command is to have a non-`nil'
+`disabled' property on the Lisp symbol for the command.  These
+properties are normally set by the user's init file with Lisp
+expressions such as:
+
+     (put 'delete-region 'disabled t)
+
+   *Note Init File::.
+
+   If the value of the `disabled' property is a string, that string is
+included in the message printed when the command is used:
+
+     (put 'delete-region 'disabled
+          "Text deleted this way cannot be yanked back!\n")
+
+   You can disable a command either by editing the init file directly
+or with the command `M-x disable-command', which edits the init file
+for you.  *Note Init File::.
+
+   When you attempt to invoke a disabled command interactively in Emacs,
+a window is displayed containing the command's name, its documentation,
+and some instructions on what to do next; then Emacs asks for input
+saying whether to execute the command as requested, enable it and
+execute, or cancel it.  If you decide to enable the command, you are
+asked whether to do this permanently or just for the current session.
+Enabling permanently works by automatically editing your init file.
+You can use `M-x enable-command' at any time to enable any command
+permanently.
+
+   Whether a command is disabled is independent of what key is used to
+invoke it; it also applies if the command is invoked using `M-x'.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+
+\1f
+File: xemacs.info,  Node: Syntax,  Next: Init File,  Prev: Key Bindings,  Up: Customization
+
+The Syntax Table
+================
+
+All the Emacs commands which parse words or balance parentheses are
+controlled by the "syntax table".  The syntax table specifies which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on.  Actually, each major mode has its own syntax
+table (though sometimes related major modes use the same one) which it
+installs in each buffer that uses that major mode.  The syntax table
+installed in the current buffer is the one that all commands use, so we
+call it "the" syntax table.  A syntax table is a Lisp object, a vector
+of length 256 whose elements are numbers.
+
+* Menu:
+
+* Entry: Syntax Entry.    What the syntax table records for each character.
+* Change: Syntax Change.  How to change the information.
+
+\1f
+File: xemacs.info,  Node: Syntax Entry,  Next: Syntax Change,  Up: Syntax
+
+Information About Each Character
+--------------------------------
+
+The syntax table entry for a character is a number that encodes six
+pieces of information:
+
+   * The syntactic class of the character, represented as a small
+     integer
+
+   * The matching delimiter, for delimiter characters only (the
+     matching delimiter of `(' is `)', and vice versa)
+
+   * A flag saying whether the character is the first character of a
+     two-character comment starting sequence
+
+   * A flag saying whether the character is the second character of a
+     two-character comment starting sequence
+
+   * A flag saying whether the character is the first character of a
+     two-character comment ending sequence
+
+   * A flag saying whether the character is the second character of a
+     two-character comment ending sequence
+
+   The syntactic classes are stored internally as small integers, but
+are usually described to or by the user with characters.  For example,
+`(' is used to specify the syntactic class of opening delimiters.  Here
+is a table of syntactic classes, with the characters that specify them.
+
+`-'
+     The class of whitespace characters.  Please don't use the formerly
+     advertised  , which is not supported by GNU Emacs.
+
+`w'
+     The class of word-constituent characters.
+
+`_'
+     The class of characters that are part of symbol names but not
+     words.  This class is represented by `_' because the character `_'
+     has this class in both C and Lisp.
+
+`.'
+     The class of punctuation characters that do not fit into any other
+     special class.
+
+`('
+     The class of opening delimiters.
+
+`)'
+     The class of closing delimiters.
+
+`''
+     The class of expression-adhering characters.  These characters are
+     part of a symbol if found within or adjacent to one, and are part
+     of a following expression if immediately preceding one, but are
+     like whitespace if surrounded by whitespace.
+
+`"'
+     The class of string-quote characters.  They match each other in
+     pairs, and the characters within the pair all lose their syntactic
+     significance except for the `\' and `/' classes of escape
+     characters, which can be used to include a string-quote inside the
+     string.
+
+`$'
+     The class of self-matching delimiters.  This is intended for TeX's
+     `$', which is used both to enter and leave math mode.  Thus, a
+     pair of matching `$' characters surround each piece of math mode
+     TeX input.  A pair of adjacent `$' characters act like a single
+     one for purposes of matching.
+
+`/'
+     The class of escape characters that always just deny the following
+     character its special syntactic significance.  The character after
+     one of these escapes is always treated as alphabetic.
+
+`\'
+     The class of C-style escape characters.  In practice, these are
+     treated just like `/'-class characters, because the extra
+     possibilities for C escapes (such as being followed by digits)
+     have no effect on where the containing expression ends.
+
+`<'
+     The class of comment-starting characters.  Only single-character
+     comment starters (such as `;' in Lisp mode) are represented this
+     way.
+
+`>'
+     The class of comment-ending characters.  Newline has this syntax in
+     Lisp mode.
+
+   The characters flagged as part of two-character comment delimiters
+can have other syntactic functions most of the time.  For example, `/'
+and `*' in C code, when found separately, have nothing to do with
+comments.  The comment-delimiter significance overrides when the pair of
+characters occur together in the proper order.  Only the list and sexp
+commands use the syntax table to find comments; the commands
+specifically for comments have other variables that tell them where to
+find comments.  Moreover, the list and sexp commands notice comments
+only if `parse-sexp-ignore-comments' is non-`nil'.  This variable is set
+to `nil' in modes where comment-terminator sequences are liable to
+appear where there is no comment, for example, in Lisp mode where the
+comment terminator is a newline but not every newline ends a comment.
+
+\1f
+File: xemacs.info,  Node: Syntax Change,  Prev: Syntax Entry,  Up: Syntax
+
+Altering Syntax Information
+---------------------------
+
+It is possible to alter a character's syntax table entry by storing a
+new number in the appropriate element of the syntax table, but it would
+be hard to determine what number to use.  Emacs therefore provides a
+command that allows you to specify the syntactic properties of a
+character in a convenient way.
+
+   `M-x modify-syntax-entry' is the command to change a character's
+syntax.  It can be used interactively and is also used by major modes
+to initialize their own syntax tables.  Its first argument is the
+character to change.  The second argument is a string that specifies the
+new syntax.  When called from Lisp code, there is a third, optional
+argument, which specifies the syntax table in which to make the change.
+If not supplied, or if this command is called interactively, the third
+argument defaults to the current buffer's syntax table.
+
+  1. The first character in the string specifies the syntactic class.
+     It is one of the characters in the previous table (*note Syntax
+     Entry::).
+
+  2. The second character is the matching delimiter.  For a character
+     that is not an opening or closing delimiter, this should be a
+     space, and may be omitted if no following characters are needed.
+
+  3. The remaining characters are flags.  The flag characters allowed
+     are:
+
+    `1'
+          Flag this character as the first of a two-character comment
+          starting sequence.
+
+    `2'
+          Flag this character as the second of a two-character comment
+          starting sequence.
+
+    `3'
+          Flag this character as the first of a two-character comment
+          ending sequence.
+
+    `4'
+          Flag this character as the second of a two-character comment
+          ending sequence.
+
+   Use `C-h s' (`describe-syntax') to display a description of the
+contents of the current syntax table.  The description of each
+character includes both the string you have to pass to
+`modify-syntax-entry' to set up that character's current syntax, and
+some English to explain that string if necessary.
+
+\1f
+File: xemacs.info,  Node: Init File,  Next: Audible Bell,  Prev: Syntax,  Up: Customization
+
+The Init File
+=============
+
+When you start Emacs, it normally loads either `.xemacs/init.el' or the
+file `.emacs' (whichever comes first) in your home directory.  This
+file, if it exists, should contain Lisp code.  It is called your
+initialization file or "init file".  Use the command line switch `-q'
+to tell Emacs whether to load an init file (*note Entering Emacs::).
+Use the command line switch `-user-init-file' (*note Command
+Switches::) to tell Emacs to load a different file instead of
+`~/.xemacs/init.el'/`~/.emacs'.
+
+   When the init file is read, the variable `user-init-file' says which
+init file was loaded.
+
+   At some sites there is a "default init file", which is the library
+named `default.el', found via the standard search path for libraries.
+The Emacs distribution contains no such library; your site may create
+one for local customizations.  If this library exists, it is loaded
+whenever you start Emacs.  But your init file, if any, is loaded first;
+if it sets `inhibit-default-init' non-`nil', then `default' is not
+loaded.
+
+   If you have a large amount of code in your init file, you should
+byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'.
+
+* Menu:
+
+* Init Syntax::     Syntax of constants in Emacs Lisp.
+* Init Examples::   How to do some things with an init file.
+* Terminal Init::   Each terminal type can have an init file.
+
+\1f
+File: xemacs.info,  Node: Init Syntax,  Next: Init Examples,  Up: Init File
+
+Init File Syntax
+----------------
+
+The init file contains one or more Lisp function call expressions.
+Each consists of a function name followed by arguments, all surrounded
+by parentheses.  For example, `(setq fill-column 60)' represents a call
+to the function `setq' which is used to set the variable `fill-column'
+(*note Filling::) to 60.
+
+   The second argument to `setq' is an expression for the new value of
+the variable.  This can be a constant, a variable, or a function call
+expression.  In the init file, constants are used most of the time.
+They can be:
+
+Numbers
+     Integers are written in decimal, with an optional initial minus
+     sign.
+
+     If a sequence of digits is followed by a period and another
+     sequence of digits, it is interpreted as a floating point number.
+
+     The number prefixes `#b', `#o', and `#x' are supported to
+     represent numbers in binary, octal, and hexadecimal notation (or
+     radix).
+
+Strings
+     Lisp string syntax is the same as C string syntax with a few extra
+     features.  Use a double-quote character to begin and end a string
+     constant.
+
+     Newlines and special characters may be present literally in
+     strings.  They can also be represented as backslash sequences:
+     `\n' for newline, `\b' for backspace, `\r' for return, `\t' for
+     tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a
+     backslash, `\"' for a double-quote, or `\OOO' for the character
+     whose octal code is OOO.  Backslash and double-quote are the only
+     characters for which backslash sequences are mandatory.
+
+     You can use `\C-' as a prefix for a control character, as in
+     `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta
+     character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.
+
+Characters
+     Lisp character constant syntax consists of a `?' followed by
+     either a character or an escape sequence starting with `\'.
+     Examples: `?x', `?\n', `?\"', `?\)'.  Note that strings and
+     characters are not interchangeable in Lisp; some contexts require
+     one and some contexts require the other.
+
+True
+     `t' stands for `true'.
+
+False
+     `nil' stands for `false'.
+
+Other Lisp objects
+     Write a single-quote (') followed by the Lisp object you want.
+
+\1f
+File: xemacs.info,  Node: Init Examples,  Next: Terminal Init,  Prev: Init Syntax,  Up: Init File
+
+Init File Examples
+------------------
+
+Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+
+   * Make <TAB> in C mode just insert a tab if point is in the middle
+     of a line.
+
+          (setq c-tab-always-indent nil)
+
+     Here we have a variable whose value is normally `t' for `true' and
+     the alternative is `nil' for `false'.
+
+   * Make searches case sensitive by default (in all buffers that do not
+     override this).
+
+          (setq-default case-fold-search nil)
+
+     This sets the default value, which is effective in all buffers
+     that do not have local values for the variable.  Setting
+     `case-fold-search' with `setq' affects only the current buffer's
+     local value, which is probably not what you want to do in an init
+     file.
+
+   * Make Text mode the default mode for new buffers.
+
+          (setq default-major-mode 'text-mode)
+
+     Note that `text-mode' is used because it is the command for
+     entering the mode we want.  A single-quote is written before it to
+     make a symbol constant; otherwise, `text-mode' would be treated as
+     a variable name.
+
+   * Turn on Auto Fill mode automatically in Text mode and related
+     modes.
+
+          (setq text-mode-hook
+            '(lambda () (auto-fill-mode 1)))
+
+     Here we have a variable whose value should be a Lisp function.  The
+     function we supply is a list starting with `lambda', and a single
+     quote is written in front of it to make it (for the purpose of this
+     `setq') a list constant rather than an expression.  Lisp functions
+     are not explained here; for mode hooks it is enough to know that
+     `(auto-fill-mode 1)' is an expression that will be executed when
+     Text mode is entered.  You could replace it with any other
+     expression that you like, or with several expressions in a row.
+
+          (setq text-mode-hook 'turn-on-auto-fill)
+
+     This is another way to accomplish the same result.
+     `turn-on-auto-fill' is a symbol whose function definition is
+     `(lambda () (auto-fill-mode 1))'.
+
+   * Load the installed Lisp library named `foo' (actually a file
+     `foo.elc' or `foo.el' in a standard Emacs directory).
+
+          (load "foo")
+
+     When the argument to `load' is a relative pathname, not starting
+     with `/' or `~', `load' searches the directories in `load-path'
+     (*note Loading::).
+
+   * Load the compiled Lisp file `foo.elc' from your home directory.
+
+          (load "~/foo.elc")
+
+     Here an absolute file name is used, so no searching is done.
+
+   * Rebind the key `C-x l' to run the function `make-symbolic-link'.
+
+          (global-set-key "\C-xl" 'make-symbolic-link)
+
+     or
+
+          (define-key global-map "\C-xl" 'make-symbolic-link)
+
+     Note once again the single-quote used to refer to the symbol
+     `make-symbolic-link' instead of its value as a variable.
+
+   * Do the same thing for C mode only.
+
+          (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+
+   * Bind the function key <F1> to a command in C mode.  Note that the
+     names of function keys must be lower case.
+
+          (define-key c-mode-map 'f1 'make-symbolic-link)
+
+   * Bind the shifted version of <F1> to a command.
+
+          (define-key c-mode-map '(shift f1) 'make-symbolic-link)
+
+   * Redefine all keys which now run `next-line' in Fundamental mode to
+     run `forward-line' instead.
+
+          (substitute-key-definition 'next-line 'forward-line
+                                     global-map)
+
+   * Make `C-x C-v' undefined.
+
+          (global-unset-key "\C-x\C-v")
+
+     One reason to undefine a key is so that you can make it a prefix.
+     Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix,
+     but `C-x C-v' must be freed of any non-prefix definition first.
+
+   * Make `$' have the syntax of punctuation in Text mode.  Note the
+     use of a character constant for `$'.
+
+          (modify-syntax-entry ?\$ "." text-mode-syntax-table)
+
+   * Enable the use of the command `eval-expression' without
+     confirmation.
+
+          (put 'eval-expression 'disabled nil)
+
+\1f
+File: xemacs.info,  Node: Terminal Init,  Prev: Init Examples,  Up: Init File
+
+Terminal-Specific Initialization
+--------------------------------
+
+Each terminal type can have a Lisp library to be loaded into Emacs when
+it is run on that type of terminal.  For a terminal type named
+TERMTYPE, the library is called `term/TERMTYPE' and it is found by
+searching the directories `load-path' as usual and trying the suffixes
+`.elc' and `.el'.  Normally it appears in the subdirectory `term' of
+the directory where most Emacs libraries are kept.
+
+   The usual purpose of the terminal-specific library is to define the
+escape sequences used by the terminal's function keys using the library
+`keypad.el'.  See the file `term/vt100.el' for an example of how this
+is done.
+
+   When the terminal type contains a hyphen, only the part of the name
+before the first hyphen is significant in choosing the library name.
+Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library
+`term/aaa'.  The code in the library can use `(getenv "TERM")' to find
+the full terminal type name.
+
+   The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type.  Your init file can
+prevent the loading of the terminal-specific library by setting
+`term-file-prefix' to `nil'.  *Note Init File::.
+
+   The value of the variable `term-setup-hook', if not `nil', is called
+as a function of no arguments at the end of Emacs initialization, after
+both your init file and any terminal-specific library have been read.
+*Note Init File::.  You can set the value in the init file to override
+part of any of the terminal-specific libraries and to define
+initializations for terminals that do not have a library.
+
+\1f
+File: xemacs.info,  Node: Audible Bell,  Next: Faces,  Prev: Init File,  Up: Customization
+
+Changing the Bell Sound
+=======================
+
+You can now change how the audible bell sounds using the variable
+`sound-alist'.
+
+   `sound-alist''s value is an list associating symbols with, among
+other things, strings of audio-data.  When `ding' is called with one of
+the symbols, the associated sound data is played instead of the
+standard beep.  This only works if you are logged in on the console of a
+machine with audio hardware. To listen to a sound of the provided type,
+call the function `play-sound' with the argument SOUND. You can also
+set the volume of the sound with the optional argument VOLUME.
+
+   Each element of `sound-alist' is a list describing a sound.  The
+first element of the list is the name of the sound being defined.
+Subsequent elements of the list are alternating keyword/value pairs:
+
+`sound'
+     A string of raw sound data, or the name of another sound to play.
+     The symbol `t' here means use the default X beep.
+
+`volume'
+     An integer from 0-100, defaulting to `bell-volume'.
+
+`pitch'
+     If using the default X beep, the pitch (Hz) to generate.
+
+`duration'
+     If using the default X beep, the duration (milliseconds).
+
+   For compatibility, elements of `sound-alist' may also be of the form:
+
+     ( SOUND-NAME . <SOUND> )
+     ( SOUND-NAME <VOLUME> <SOUND> )
+
+   You should probably add things to this list by calling the function
+`load-sound-file'.
+
+   Note that you can only play audio data if running on the console
+screen of a machine with audio hardware which emacs understands, which
+at this time means a Sun SparcStation, SGI, or HP9000s700.
+
+   Also note that the pitch, duration, and volume options are available
+everywhere, but most X servers ignore the `pitch' option.
+
+   The variable `bell-volume' should be an integer from 0 to 100, with
+100 being loudest, which controls how loud the sounds emacs makes
+should be.  Elements of the `sound-alist' may override this value.
+This variable applies to the standard X bell sound as well as sound
+files.
+
+   If the symbol `t' is in place of a sound-string, Emacs uses the
+default X beep.  This allows you to define beep-types of different
+volumes even when not running on the console.
+
+   You can add things to this list by calling the function
+`load-sound-file', which reads in an audio-file and adds its data to
+the sound-alist. You can specify the sound with the SOUND-NAME argument
+and the file into which the sounds are loaded with the FILENAME
+argument. The optional VOLUME argument sets the volume.
+
+   `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)'
+
+   To load and install some sound files as beep-types, use the function
+`load-default-sounds' (note that this only works if you are on display
+0 of a machine with audio hardware).
+
+   The following beep-types are used by Emacs itself. Other Lisp
+packages may use other beep types, but these are the ones that the C
+kernel of Emacs uses.
+
+`auto-save-error'
+     An auto-save does not succeed
+
+`command-error'
+     The Emacs command loop catches an error
+
+`undefined-key'
+     You type a key that is undefined
+
+`undefined-click'
+     You use an undefined mouse-click combination
+
+`no-completion'
+     Completion was not possible
+
+`y-or-n-p'
+     You type something other than the required `y' or `n'
+
+`yes-or-no-p'
+     You type something other than `yes' or `no'
+
+\1f
+File: xemacs.info,  Node: Faces,  Next: Frame Components,  Prev: Audible Bell,  Up: Customization
+
+Faces
+=====
+
+XEmacs has objects called extents and faces.  An "extent" is a region
+of text and a "face" is a collection of textual attributes, such as
+fonts and colors.  Every extent is displayed in some face; therefore,
+changing the properties of a face immediately updates the display of
+all associated extents.  Faces can be frame-local: you can have a
+region of text that displays with completely different attributes when
+its buffer is viewed from a different X window.
+
+   The display attributes of faces may be specified either in Lisp or
+through the X resource manager.
+
+Customizing Faces
+-----------------
+
+You can change the face of an extent with the functions in this
+section.  All the functions prompt for a FACE as an argument; use
+completion for a list of possible values.
+
+`M-x invert-face'
+     Swap the foreground and background colors of the given FACE.
+
+`M-x make-face-bold'
+     Make the font of the given FACE bold.  When called from a program,
+     returns `nil' if this is not possible.
+
+`M-x make-face-bold-italic'
+     Make the font of the given FACE bold italic.  When called from a
+     program, returns `nil' if not possible.
+
+`M-x make-face-italic'
+     Make the font of the given FACE italic.  When called from a
+     program, returns `nil' if not possible.
+
+`M-x make-face-unbold'
+     Make the font of the given FACE non-bold.  When called from a
+     program, returns `nil' if not possible.
+
+`M-x make-face-unitalic'
+     Make the font of the given FACE non-italic.  When called from a
+     program, returns `nil' if not possible.
+
+`M-x make-face-larger'
+     Make the font of the given FACE a little larger.  When called from
+     a program, returns `nil' if not possible.
+
+`M-x make-face-smaller'
+     Make the font of the given FACE a little smaller.  When called
+     from a program, returns `nil' if not possible.
+
+`M-x set-face-background'
+     Change the background color of the given FACE.
+
+`M-x set-face-background-pixmap'
+     Change the background pixmap of the given FACE.
+
+`M-x set-face-font'
+     Change the font of the given FACE.
+
+`M-x set-face-foreground'
+     Change the foreground color of the given FACE.
+
+`M-x set-face-underline-p'
+     Change whether the given FACE is underlined.
+
+   You can exchange the foreground and background color of the selected
+FACE with the function `invert-face'. If the face does not specify both
+foreground and background, then its foreground and background are set
+to the background and foreground of the default face.  When calling
+this from a program, you can supply the optional argument FRAME to
+specify which frame is affected; otherwise, all frames are affected.
+
+   The work of `make-face-bold', `make-face-bold-italic',
+`make-face-italic', `make-face-unbold', `make-face-unitalic' functions
+is affected by `face-frob-from-locale-first' variable.  If it is `nil',
+those functions first try to manipulate device specific data like X
+font names to obtain the desired font face specification.  This may be
+unsuitable in environments using different font face specifications for
+different frames, non-Mule environments in particular.
+
+   If the variable is non-`nil', those functions first try to figure
+out whether the face font is the same as one of predefined faces:
+`default', `bold', `italic', `bold-italic'.  If it is the same, then
+the new face font specification is set to be the same as that of a
+corresponding predefined face.  Thus if the predefined face is set up
+properly for different frames, the same will hold for the face being
+changed by the functions.  This is the behavior one might desire in
+non-Mule environments mentioned above: face being changed still looks
+right in all frames.
+
+   How predefined faces might be set up for different frames in such an
+environments is described in *Note Face Resources::.
+
+   You can set the background color of the specified FACE with the
+function `set-face-background'.  The argument `color' should be a
+string, the name of a color.  When called from a program, if the
+optional FRAME argument is provided, the face is changed only in that
+frame; otherwise, it is changed in all frames.
+
+   You can set the background pixmap of the specified FACE with the
+function `set-face-background-pixmap'.  The pixmap argument NAME should
+be a string, the name of a file of pixmap data.  The directories listed
+in the `x-bitmap-file-path' variable are searched.  The bitmap may also
+be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are
+the size in pixels, and DATA is a string containing the raw bits of the
+bitmap.  If the optional FRAME argument is provided, the face is
+changed only in that frame; otherwise, it is changed in all frames.
+
+   The variable `x-bitmap-file-path' takes as a value a list of the
+directories in which X bitmap files may be found.  If the value is
+`nil', the list is initialized from the `*bitmapFilePath' resource.
+
+   If the environment variable XBMLANGPATH is set, then it is consulted
+before the `x-bitmap-file-path' variable.
+
+   You can set the font of the specified FACE with the function
+`set-face-font'.  The FONT argument should be a string, the name of a
+font.  When called from a program, if the optional FRAME argument is
+provided, the face is changed only in that frame; otherwise, it is
+changed in all frames.
+
+   You can set the foreground color of the specified FACE with the
+function `set-face-foreground'.  The argument COLOR should be a string,
+the name of a color.  If the optional FRAME argument is provided, the
+face is changed only in that frame; otherwise, it is changed in all
+frames.
+
+   You can set underline the specified FACE with the function
+`set-face-underline-p'. The argument UNDERLINE-P can be used to make
+underlining an attribute of the face or not. If the optional FRAME
+argument is provided, the face is changed only in that frame;
+otherwise, it is changed in all frames.
+
+\1f
+File: xemacs.info,  Node: Frame Components,  Next: X Resources,  Prev: Faces,  Up: Customization
+
+Frame Components
+================
+
+You can control the presence and position of most frame components, such
+as the menubar, toolbars, and gutters.
+
+   This section is not written yet.  Try the Lisp Reference Manual:
+*Note Menubar: (lispref)Menubar, *Note Toolbar Intro: (lispref)Toolbar
+Intro, and *Note Gutter Intro: (lispref)Gutter Intro.
+
+\1f
+File: xemacs.info,  Node: X Resources,  Prev: Frame Components,  Up: Customization
+
+X Resources
+===========
+
+Historically, XEmacs has used the X resource application class `Emacs'
+for its resources.  Unfortunately, GNU Emacs uses the same application
+class, and resources are not compatible between the two Emacsen.  This
+sharing of the application class often leads to trouble if you want to
+run both variants.
+
+   Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds
+any XEmacs resources in the resource database when the X connection is
+initialized.  Otherwise, it will use the class `Emacs' for backwards
+compatibility.  The variable `x-emacs-application-class' may be
+consulted to determine the application class being used.
+
+   The examples in this section assume the application class is `Emacs'.
+
+   The Emacs resources are generally set per-frame. Each Emacs frame
+can have its own name or the same name as another, depending on the
+name passed to the `make-frame' function.
+
+   You can specify resources for all frames with the syntax:
+
+     Emacs*parameter: value
+
+or
+
+     Emacs*EmacsFrame.parameter:value
+
+You can specify resources for a particular frame with the syntax:
+
+     Emacs*FRAME-NAME.parameter: value
+
+* Menu:
+
+* Geometry Resources::     Controlling the size and position of frames.
+* Iconic Resources::       Controlling whether frames come up iconic.
+* Resource List::          List of resources settable on a frame or device.
+* Face Resources::         Controlling faces using resources.
+* Widgets::                The widget hierarchy for XEmacs.
+* Menubar Resources::      Specifying resources for the menubar.
+
+\1f
+File: xemacs.info,  Node: Geometry Resources,  Next: Iconic Resources,  Up: X Resources
+
+Geometry Resources
+------------------
+
+To make the default size of all Emacs frames be 80 columns by 55 lines,
+do this:
+
+     Emacs*EmacsFrame.geometry: 80x55
+
+To set the geometry of a particular frame named `fred', do this:
+
+     Emacs*fred.geometry: 80x55
+
+Important! Do not use the following syntax:
+
+     Emacs*geometry: 80x55
+
+You should never use `*geometry' with any X application. It does not
+say "make the geometry of Emacs be 80 columns by 55 lines."  It really
+says, "make Emacs and all subwindows thereof be 80x55 in whatever units
+they care to measure in."  In particular, that is both telling the
+Emacs text pane to be 80x55 in characters, and telling the menubar pane
+to be 80x55 pixels, which is surely not what you want.
+
+   As a special case, this geometry specification also works (and sets
+the default size of all Emacs frames to 80 columns by 55 lines):
+
+     Emacs.geometry: 80x55
+
+since that is the syntax used with most other applications (since most
+other applications have only one top-level window, unlike Emacs).  In
+general, however, the top-level shell (the unmapped ApplicationShell
+widget named `Emacs' that is the parent of the shell widgets that
+actually manage the individual frames) does not have any interesting
+resources on it, and you should set the resources on the frames instead.
+
+   The `-geometry' command-line argument sets only the geometry of the
+initial frame created by Emacs.
+
+   A more complete explanation of geometry-handling is
+
+   * The `-geometry' command-line option sets the `Emacs.geometry'
+     resource, that is, the geometry of the ApplicationShell.
+
+   * For the first frame created, the size of the frame is taken from
+     the ApplicationShell if it is specified, otherwise from the
+     geometry of the frame.
+
+   * For subsequent frames, the order is reversed: First the frame, and
+     then the ApplicationShell.
+
+   * For the first frame created, the position of the frame is taken
+     from the ApplicationShell (`Emacs.geometry') if it is specified,
+     otherwise from the geometry of the frame.
+
+   * For subsequent frames, the position is taken only from the frame,
+     and never from the ApplicationShell.
+
+   This is rather complicated, but it does seem to provide the most
+intuitive behavior with respect to the default sizes and positions of
+frames created in various ways.
+
+\1f
+File: xemacs.info,  Node: Iconic Resources,  Next: Resource List,  Prev: Geometry Resources,  Up: X Resources
+
+Iconic Resources
+----------------
+
+Analogous to `-geometry', the `-iconic' command-line option sets the
+iconic flag of the ApplicationShell (`Emacs.iconic') and always applies
+to the first frame created regardless of its name.  However, it is
+possible to set the iconic flag on particular frames (by name) by using
+the `Emacs*FRAME-NAME.iconic' resource.
+
+\1f
+File: xemacs.info,  Node: Resource List,  Next: Face Resources,  Prev: Iconic Resources,  Up: X Resources
+
+Resource List
+-------------
+
+Emacs frames accept the following resources:
+
+`geometry' (class `Geometry'): string
+     Initial geometry for the frame.  *Note Geometry Resources::, for a
+     complete discussion of how this works.
+
+`iconic' (class `Iconic'): boolean
+     Whether this frame should appear in the iconified state.
+
+`internalBorderWidth' (class `InternalBorderWidth'): int
+     How many blank pixels to leave between the text and the edge of the
+     window.
+
+`interline' (class `Interline'): int
+     How many pixels to leave between each line (may not be
+     implemented).
+
+`menubar' (class `Menubar'): boolean
+     Whether newly-created frames should initially have a menubar.  Set
+     to true by default.
+
+`initiallyUnmapped' (class `InitiallyUnmapped'): boolean
+     Whether XEmacs should leave the initial frame unmapped when it
+     starts up.  This is useful if you are starting XEmacs as a server
+     (e.g. in conjunction with gnuserv or the external client widget).
+     You can also control this with the `-unmapped' command-line option.
+
+`barCursor' (class `BarColor'): boolean
+     Whether the cursor should be displayed as a bar, or the
+     traditional box.
+
+`cursorColor' (class `CursorColor'): color-name
+     The color of the text cursor.
+
+`scrollBarWidth' (class `ScrollBarWidth'): integer
+     How wide the vertical scrollbars should be, in pixels; 0 means no
+     vertical scrollbars.  You can also use a resource specification of
+     the form `*scrollbar.width', or the usual toolkit scrollbar
+     resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
+     (Lucid), or `*Scrollbar.thickness' (Athena).  We don't recommend
+     that you use the toolkit resources, though, because they're
+     dependent on how exactly your particular build of XEmacs was
+     configured.
+
+`scrollBarHeight' (class `ScrollBarHeight'): integer
+     How high the horizontal scrollbars should be, in pixels; 0 means no
+     horizontal scrollbars.  You can also use a resource specification
+     of the form `*scrollbar.height', or the usual toolkit scrollbar
+     resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
+     (Lucid), or `*Scrollbar.thickness' (Athena).  We don't recommend
+     that you use the toolkit resources, though, because they're
+     dependent on how exactly your particular build of XEmacs was
+     configured.
+
+`scrollBarPlacement' (class `ScrollBarPlacement'): string
+     Where the horizontal and vertical scrollbars should be positioned.
+     This should be one of the four strings `BOTTOM_LEFT',
+     `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'.  Default is
+     `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
+     `BOTTOM_LEFT' for the Athena scrollbars.
+
+`topToolBarHeight' (class `TopToolBarHeight'): integer
+`bottomToolBarHeight' (class `BottomToolBarHeight'): integer
+`leftToolBarWidth' (class `LeftToolBarWidth'): integer
+`rightToolBarWidth' (class `RightToolBarWidth'): integer
+     Height and width of the four possible toolbars.
+
+`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
+`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
+     Color of the top and bottom shadows for the toolbars.  NOTE: These
+     resources do _not_ have anything to do with the top and bottom
+     toolbars (i.e. the toolbars at the top and bottom of the frame)!
+     Rather, they affect the top and bottom shadows around the edges of
+     all four kinds of toolbars.
+
+`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
+`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
+     Pixmap of the top and bottom shadows for the toolbars.  If set,
+     these resources override the corresponding color resources. NOTE:
+     These resources do _not_ have anything to do with the top and
+     bottom toolbars (i.e. the toolbars at the top and bottom of the
+     frame)!  Rather, they affect the top and bottom shadows around the
+     edges of all four kinds of toolbars.
+
+`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
+     Thickness of the shadows around the toolbars, in pixels.
+
+`visualBell' (class `VisualBell'): boolean
+     Whether XEmacs should flash the screen rather than making an
+     audible beep.
+
+`bellVolume' (class `BellVolume'): integer
+     Volume of the audible beep.
+
+`useBackingStore' (class `UseBackingStore'): boolean
+     Whether XEmacs should set the backing-store attribute of the X
+     windows it creates.  This increases the memory usage of the X
+     server but decreases the amount of X traffic necessary to update
+     the screen, and is useful when the connection to the X server goes
+     over a low-bandwidth line such as a modem connection.
+
+   Emacs devices accept the following resources:
+
+`textPointer' (class `Cursor'): cursor-name
+     The cursor to use when the mouse is over text.  This resource is
+     used to initialize the variable `x-pointer-shape'.
+
+`selectionPointer' (class `Cursor'): cursor-name
+     The cursor to use when the mouse is over a selectable text region
+     (an extent with the `highlight' property; for example, an Info
+     cross-reference).  This resource is used to initialize the variable
+     `x-selection-pointer-shape'.
+
+`spacePointer' (class `Cursor'): cursor-name
+     The cursor to use when the mouse is over a blank space in a buffer
+     (that is, after the end of a line or after the end-of-file).  This
+     resource is used to initialize the variable
+     `x-nontext-pointer-shape'.
+
+`modeLinePointer' (class `Cursor'): cursor-name
+     The cursor to use when the mouse is over a modeline.  This
+     resource is used to initialize the variable `x-mode-pointer-shape'.
+
+`gcPointer' (class `Cursor'): cursor-name
+     The cursor to display when a garbage-collection is in progress.
+     This resource is used to initialize the variable
+     `x-gc-pointer-shape'.
+
+`scrollbarPointer' (class `Cursor'): cursor-name
+     The cursor to use when the mouse is over the scrollbar.  This
+     resource is used to initialize the variable
+     `x-scrollbar-pointer-shape'.
+
+`pointerColor' (class `Foreground'): color-name
+`pointerBackground' (class `Background'): color-name
+     The foreground and background colors of the mouse cursor.  These
+     resources are used to initialize the variables
+     `x-pointer-foreground-color' and `x-pointer-background-color'.
+
+\1f
+File: xemacs.info,  Node: Face Resources,  Next: Widgets,  Prev: Resource List,  Up: X Resources
+
+Face Resources
+--------------
+
+The attributes of faces are also per-frame. They can be specified as:
+
+     Emacs.FACE_NAME.parameter: value
+
+or
+
+     Emacs*FRAME_NAME.FACE_NAME.parameter: value
+
+Faces accept the following resources:
+
+`attributeFont' (class `AttributeFont'): font-name
+     The font of this face.
+
+`attributeForeground' (class `AttributeForeground'): color-name
+`attributeBackground' (class `AttributeBackground'): color-name
+     The foreground and background colors of this face.
+
+`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
+     The name of an XBM file (or XPM file, if your version of Emacs
+     supports XPM), to use as a background stipple.
+
+`attributeUnderline' (class `AttributeUnderline'): boolean
+     Whether text in this face should be underlined.
+
+   All text is displayed in some face, defaulting to the face named
+`default'.  To set the font of normal text, use
+`Emacs*default.attributeFont'. To set it in the frame named `fred', use
+`Emacs*fred.default.attributeFont'.
+
+   These are the names of the predefined faces:
+
+`default'
+     Everything inherits from this.
+
+`bold'
+     If this is not specified in the resource database, Emacs tries to
+     find a bold version of the font of the default face.
+
+`italic'
+     If this is not specified in the resource database, Emacs tries to
+     find an italic version of the font of the default face.
+
+`bold-italic'
+     If this is not specified in the resource database, Emacs tries to
+     find a bold-italic version of the font of the default face.
+
+`modeline'
+     This is the face that the modeline is displayed in.  If not
+     specified in the resource database, it is determined from the
+     default face by reversing the foreground and background colors.
+
+`highlight'
+     This is the face that highlighted extents (for example, Info
+     cross-references and possible completions, when the mouse passes
+     over them) are displayed in.
+
+`left-margin'
+`right-margin'
+     These are the faces that the left and right annotation margins are
+     displayed in.
+
+`zmacs-region'
+     This is the face that mouse selections are displayed in.
+
+`isearch'
+     This is the face that the matched text being searched for is
+     displayed in.
+
+`info-node'
+     This is the face of info menu items.  If unspecified, it is copied
+     from `bold-italic'.
+
+`info-xref'
+     This is the face of info cross-references.  If unspecified, it is
+     copied from `bold'. (Note that, when the mouse passes over a
+     cross-reference, the cross-reference's face is determined from a
+     combination of the `info-xref' and `highlight' faces.)
+
+   Other packages might define their own faces; to see a list of all
+faces, use any of the interactive face-manipulation commands such as
+`set-face-font' and type `?' when you are prompted for the name of a
+face.
+
+   If the `bold', `italic', and `bold-italic' faces are not specified
+in the resource database, then XEmacs attempts to derive them from the
+font of the default face.  It can only succeed at this if you have
+specified the default font using the XLFD (X Logical Font Description)
+format, which looks like
+
+     *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+If you use any of the other, less strict font name formats, some of
+which look like
+
+     lucidasanstypewriter-12
+     fixed
+     9x13
+
+   then XEmacs won't be able to guess the names of the bold and italic
+versions.  All X fonts can be referred to via XLFD-style names, so you
+should use those forms.  See the man pages for `X(1)', `xlsfonts(1)',
+and `xfontsel(1)'.
+
+\1f
+File: xemacs.info,  Node: Widgets,  Next: Menubar Resources,  Prev: Face Resources,  Up: X Resources
+
+Widgets
+-------
+
+There are several structural widgets between the terminal EmacsFrame
+widget and the top level ApplicationShell; the exact names and types of
+these widgets change from release to release (for example, they changed
+between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
+subject to further change in the future, so you should avoid mentioning
+them in your resource database.  The above-mentioned syntaxes should be
+forward- compatible.  As of 19.13, the exact widget hierarchy is as
+follows:
+
+     INVOCATION-NAME            "shell"       "container"     FRAME-NAME
+     x-emacs-application-class  "EmacsShell"  "EmacsManager"  "EmacsFrame"
+
+   where INVOCATION-NAME is the terminal component of the name of the
+XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
+is generally `Emacs'.
+
+\1f
+File: xemacs.info,  Node: Menubar Resources,  Prev: Widgets,  Up: X Resources
+
+Menubar Resources
+-----------------
+
+As the menubar is implemented as a widget which is not a part of XEmacs
+proper, it does not use the face mechanism for specifying fonts and
+colors: It uses whatever resources are appropriate to the type of widget
+which is used to implement it.
+
+   If Emacs was compiled to use only the Lucid Motif-lookalike menu
+widgets, then one way to specify the font of the menubar would be
+
+     Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+   If both the Lucid Motif-lookalike menu widgets and X Font Sets are
+configured to allow multilingual menubars, then one uses
+
+     *menubar*FontSet:       -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
+                             -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
+
+   That would specify fonts for a Japanese menubar.  Specifying only one
+XLFD is acceptable; specifying more than one for a given registry
+(language) is also allowed.  When X Font Sets are configured, some .font
+resources (eg, menubars) are ignored in favor of the corresponding
+.fontSet resources.
+
+   If the Motif library is being used, then one would have to use
+
+     Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+   because the Motif library uses the `fontList' resource name instead
+of `font', which has subtly different semantics.
+
+   The same is true of the scrollbars: They accept whichever resources
+are appropriate for the toolkit in use.
+
+\1f
+File: xemacs.info,  Node: Quitting,  Next: Lossage,  Prev: Customization,  Up: Top
+
+Quitting and Aborting
+=====================
+
+`C-g'
+     Quit.  Cancel running or partially typed command.
+
+`C-]'
+     Abort innermost recursive editing level and cancel the command
+     which invoked it (`abort-recursive-edit').
+
+`M-x top-level'
+     Abort all recursive editing levels that are currently executing.
+
+`C-x u'
+     Cancel an already-executed command, usually (`undo').
+
+   There are two ways of cancelling commands which are not finished
+executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
+top-level'.  Quitting is cancelling a partially typed command or one
+which is already running.  Aborting is getting out of a recursive
+editing level and cancelling the command that invoked the recursive
+edit.
+
+   Quitting with `C-g' is used for getting rid of a partially typed
+command or a numeric argument that you don't want.  It also stops a
+running command in the middle in a relatively safe way, so you can use
+it if you accidentally start executing a command that takes a long
+time.  In particular, it is safe to quit out of killing; either your
+text will ALL still be there, or it will ALL be in the kill ring (or
+maybe both).  Quitting an incremental search does special things
+documented under searching; in general, it may take two successive
+`C-g' characters to get out of a search.  `C-g' works by setting the
+variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
+checks this variable frequently and quits if it is non-`nil'.  `C-g' is
+only actually executed as a command if it is typed while Emacs is
+waiting for input.
+
+   If you quit twice in a row before the first `C-g' is recognized, you
+activate the "emergency escape" feature and return to the shell.  *Note
+Emergency Escape::.
+
+   You can use `C-]' (`abort-recursive-edit') to get out of a recursive
+editing level and cancel the command which invoked it.  Quitting with
+`C-g' does not do this, and could not do this because it is used to
+cancel a partially typed command within the recursive editing level.
+Both operations are useful.  For example, if you are in the Emacs
+debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
+argument, you can cancel that argument with `C-g' and remain in the
+debugger.
+
+   The command `M-x top-level' is equivalent to "enough" `C-]' commands
+to get you out of all the levels of recursive edits that you are in.
+`C-]' only gets you out one level at a time, but `M-x top-level' goes
+out all levels at once.  Both `C-]' and `M-x top-level' are like all
+other commands and unlike `C-g' in that they are effective only when
+Emacs is ready for a command.  `C-]' is an ordinary key and has its
+meaning only because of its binding in the keymap.  *Note Recursive
+Edit::.
+
+   `C-x u' (`undo') is not strictly speaking a way of cancelling a
+command, but you can think of it as cancelling a command already
+finished executing.  *Note Undo::.
+
+\1f
+File: xemacs.info,  Node: Lossage,  Next: Bugs,  Prev: Quitting,  Up: Top
+
+Dealing With Emacs Trouble
+==========================
+
+This section describes various conditions in which Emacs fails to work,
+and how to recognize them and correct them.
+
+* Menu:
+
+* Stuck Recursive::    `[...]' in mode line around the parentheses.
+* Screen Garbled::     Garbage on the screen.
+* Text Garbled::       Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Emergency Escape::   Emergency escape---
+                        What to do if Emacs stops responding.
+* Total Frustration::  When you are at your wits' end.
+
+\1f
+File: xemacs.info,  Node: Stuck Recursive,  Next: Screen Garbled,  Prev: Lossage,  Up: Lossage
+
+Recursive Editing Levels
+------------------------
+
+Recursive editing levels are important and useful features of Emacs, but
+they can seem like malfunctions to the user who does not understand
+them.
+
+   If the mode line has square brackets `[...]' around the parentheses
+that contain the names of the major and minor modes, you have entered a
+recursive editing level.  If you did not do this on purpose, or if you
+don't understand what that means, you should just get out of the
+recursive editing level.  To do so, type `M-x top-level'.  This is
+called getting back to top level.  *Note Recursive Edit::.
+
+\1f
+File: xemacs.info,  Node: Screen Garbled,  Next: Text Garbled,  Prev: Stuck Recursive,  Up: Lossage
+
+Garbage on the Screen
+---------------------
+
+If the data on the screen looks wrong, the first thing to do is see
+whether the text is actually wrong.  Type `C-l', to redisplay the
+entire screen.  If the text appears correct after this, the problem was
+entirely in the previous screen update.
+
+   Display updating problems often result from an incorrect termcap
+entry for the terminal you are using.  The file `etc/TERMS' in the Emacs
+distribution gives the fixes for known problems of this sort.
+`INSTALL' contains general advice for these problems in one of its
+sections.  Very likely there is simply insufficient padding for certain
+display operations.  To investigate the possibility that you have this
+sort of problem, try Emacs on another terminal made by a different
+manufacturer.  If problems happen frequently on one kind of terminal but
+not another kind, the real problem is likely to be a bad termcap entry,
+though it could also be due to a bug in Emacs that appears for terminals
+that have or lack specific features.
+
+\1f
+File: xemacs.info,  Node: Text Garbled,  Next: Unasked-for Search,  Prev: Screen Garbled,  Up: Lossage
+
+Garbage in the Text
+-------------------
+
+If `C-l' shows that the text is wrong, try undoing the changes to it
+using `C-x u' until it gets back to a state you consider correct.  Also
+try `C-h l' to find out what command you typed to produce the observed
+results.
+
+   If a large portion of text appears to be missing at the beginning or
+end of the buffer, check for the word `Narrow' in the mode line.  If it
+appears, the text is still present, but marked off-limits.  To make it
+visible again, type `C-x n w'.  *Note Narrowing::.
+
+\1f
+File: xemacs.info,  Node: Unasked-for Search,  Next: Emergency Escape,  Prev: Text Garbled,  Up: Lossage
+
+Spontaneous Entry to Incremental Search
+---------------------------------------
+
+If Emacs spontaneously displays `I-search:' at the bottom of the
+screen, it means that the terminal is sending `C-s' and `C-q' according
+to the poorly designed xon/xoff "flow control" protocol.  You should
+try to prevent this by putting the terminal in a mode where it will not
+use flow control, or by giving it enough padding that it will never
+send a `C-s'.  If that cannot be done, you must tell Emacs to expect
+flow control to be used, until you can get a properly designed terminal.
+
+   Information on how to do these things can be found in the file
+`INSTALL' in the Emacs distribution.
+
+\1f
+File: xemacs.info,  Node: Emergency Escape,  Next: Total Frustration,  Prev: Unasked-for Search,  Up: Lossage
+
+Emergency Escape
+----------------
+
+Because at times there have been bugs causing Emacs to loop without
+checking `quit-flag', a special feature causes Emacs to be suspended
+immediately if you type a second `C-g' while the flag is already set,
+so you can always get out of XEmacs.  Normally Emacs recognizes and
+clears `quit-flag' (and quits!) quickly enough to prevent this from
+happening.
+
+   When you resume Emacs after a suspension caused by multiple `C-g', it
+asks two questions before going back to what it had been doing:
+
+     Auto-save? (y or n)
+     Abort (and dump core)? (y or n)
+
+Answer each one with `y' or `n' followed by <RET>.
+
+   Saying `y' to `Auto-save?' causes immediate auto-saving of all
+modified buffers in which auto-saving is enabled.
+
+   Saying `y' to `Abort (and dump core)?' causes an illegal instruction
+to be executed, dumping core.  This is to enable a wizard to figure out
+why Emacs was failing to quit in the first place.  Execution does not
+continue after a core dump.  If you answer `n', execution does
+continue.  With luck, Emacs will ultimately check `quit-flag' and quit
+normally.  If not, and you type another `C-g', it is suspended again.
+
+   If Emacs is not really hung, but is just being slow, you may invoke
+the double `C-g' feature without really meaning to.  In that case,
+simply resume and answer `n' to both questions, and you will arrive at
+your former state.  Presumably the quit you requested will happen soon.
+
+   The double-`C-g' feature may be turned off when Emacs is running
+under a window system, since the window system always enables you to
+kill Emacs or to create another window and run another program.
+
+\1f
+File: xemacs.info,  Node: Total Frustration,  Prev: Emergency Escape,  Up: Lossage
+
+Help for Total Frustration
+--------------------------
+
+If using Emacs (or something else) becomes terribly frustrating and none
+of the techniques described above solve the problem, Emacs can still
+help you.
+
+   First, if the Emacs you are using is not responding to commands, type
+`C-g C-g' to get out of it and then start a new one.
+
+   Second, type `M-x doctor <RET>'.
+
+   The doctor will make you feel better.  Each time you say something to
+the doctor, you must end it by typing <RET> <RET>.  This lets the
+doctor know you are finished.
+
+\1f
+File: xemacs.info,  Node: Bugs,  Prev: Lossage,  Up: Top
+
+Reporting Bugs
+==============
+
+Sometimes you will encounter a bug in Emacs.  Although we cannot promise
+we can or will fix the bug, and we might not even agree that it is a
+bug, we want to hear about bugs you encounter in case we do want to fix
+them.
+
+   To make it possible for us to fix a bug, you must report it.  In
+order to do so effectively, you must know when and how to do it.
+
+When Is There a Bug
+-------------------
+
+If Emacs executes an illegal instruction, or dies with an operating
+system error message that indicates a problem in the program (as
+opposed to something like "disk full"), then it is certainly a bug.
+
+   If Emacs updates the display in a way that does not correspond to
+what is in the buffer, then it is certainly a bug.  If a command seems
+to do the wrong thing but the problem corrects itself if you type
+`C-l', it is a case of incorrect display updating.
+
+   Taking forever to complete a command can be a bug, but you must make
+certain that it was really Emacs's fault.  Some commands simply take a
+long time.  Type `C-g' and then `C-h l' to see whether the input Emacs
+received was what you intended to type; if the input was such that you
+KNOW it should have been processed quickly, report a bug.  If you don't
+know whether the command should take a long time, find out by looking
+in the manual or by asking for assistance.
+
+   If a command you are familiar with causes an Emacs error message in a
+case where its usual definition ought to be reasonable, it is probably a
+bug.
+
+   If a command does the wrong thing, that is a bug.  But be sure you
+know for certain what it ought to have done.  If you aren't familiar
+with the command, or don't know for certain how the command is supposed
+to work, then it might actually be working right.  Rather than jumping
+to conclusions, show the problem to someone who knows for certain.
+
+   Finally, a command's intended definition may not be best for editing
+with.  This is a very important sort of problem, but it is also a
+matter of judgment.  Also, it is easy to come to such a conclusion out
+of ignorance of some of the existing features.  It is probably best not
+to complain about such a problem until you have checked the
+documentation in the usual ways, feel confident that you understand it,
+and know for certain that what you want is not available.  If you are
+not sure what the command is supposed to do after a careful reading of
+the manual, check the index and glossary for any terms that may be
+unclear.  If you still do not understand, this indicates a bug in the
+manual.  The manual's job is to make everything clear.  It is just as
+important to report documentation bugs as program bugs.
+
+   If the online documentation string of a function or variable
+disagrees with the manual, one of them must be wrong, so report the bug.
+
+How to Report a Bug
+-------------------
+
+When you decide that there is a bug, it is important to report it and to
+report it in a way which is useful.  What is most useful is an exact
+description of what commands you type, starting with the shell command
+to run Emacs, until the problem happens.  Always include the version
+number of Emacs that you are using; type `M-x emacs-version' to print
+this.
+
+   The most important principle in reporting a bug is to report FACTS,
+not hypotheses or categorizations.  It is always easier to report the
+facts, but people seem to prefer to strain to posit explanations and
+report them instead.  If the explanations are based on guesses about
+how Emacs is implemented, they will be useless; we will have to try to
+figure out what the facts must have been to lead to such speculations.
+Sometimes this is impossible.  But in any case, it is unnecessary work
+for us.
+
+   For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
+visiting a file which (you know) happens to be rather large, and Emacs
+prints out `I feel pretty today'.  The best way to report the bug is
+with a sentence like the preceding one, because it gives all the facts
+and nothing but the facts.
+
+   Do not assume that the problem is due to the size of the file and
+say, "When I visit a large file, Emacs prints out `I feel pretty
+today'."  This is what we mean by "guessing explanations".  The problem
+is just as likely to be due to the fact that there is a `z' in the file
+name.  If this is so, then when we got your report, we would try out
+the problem with some "large file", probably with no `z' in its name,
+and not find anything wrong.  There is no way in the world that we
+could guess that we should try visiting a file with a `z' in its name.
+
+   Alternatively, the problem might be due to the fact that the file
+starts with exactly 25 spaces.  For this reason, you should make sure
+that you inform us of the exact contents of any file that is needed to
+reproduce the bug.  What if the problem only occurs when you have typed
+the `C-x a l' command previously?  This is why we ask you to give the
+exact sequence of characters you typed since starting to use Emacs.
+
+   You should not even say "visit a file" instead of `C-x C-f' unless
+you know that it makes no difference which visiting command is used.
+Similarly, rather than saying "if I have three characters on the line,"
+say "after I type `<RET> A B C <RET> C-p'," if that is the way you
+entered the text.
+
+   If you are not in Fundamental mode when the problem occurs, you
+should say what mode you are in.
+
+   If the manifestation of the bug is an Emacs error message, it is
+important to report not just the text of the error message but a
+backtrace showing how the Lisp program in Emacs arrived at the error.
+To make the backtrace, you must execute the Lisp expression `(setq
+debug-on-error t)' before the error happens (that is to say, you must
+execute that expression and then make the bug happen).  This causes the
+Lisp debugger to run (*note Lisp Debug::).  The debugger's backtrace
+can be copied as text into the bug report.  This use of the debugger is
+possible only if you know how to make the bug happen again.  Do note
+the error message the first time the bug happens, so if you can't make
+it happen again, you can report at least that.
+
+   Check whether any programs you have loaded into the Lisp world,
+including your init file, set any variables that may affect the
+functioning of Emacs.  *Note Init File::.  Also, see whether the
+problem happens in a freshly started Emacs without loading your init
+file (start Emacs with the `-q' switch to prevent loading the init
+file).  If the problem does NOT occur then, it is essential that we
+know the contents of any programs that you must load into the Lisp
+world in order to cause the problem to occur.
+
+   If the problem does depend on an init file or other Lisp programs
+that are not part of the standard Emacs system, then you should make
+sure it is not a bug in those programs by complaining to their
+maintainers first.  After they verify that they are using Emacs in a
+way that is supposed to work, they should report the bug.
+
+   If you can tell us a way to cause the problem without visiting any
+files, please do so.  This makes it much easier to debug.  If you do
+need files, make sure you arrange for us to see their exact contents.
+For example, it can often matter whether there are spaces at the ends
+of lines, or a newline after the last line in the buffer (nothing ought
+to care whether the last line is terminated, but tell that to the bugs).
+
+   The easy way to record the input to Emacs precisely is to write a
+dribble file; execute the Lisp expression:
+
+     (open-dribble-file "~/dribble")
+
+using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
+Emacs.  From then on, all Emacs input will be written in the specified
+dribble file until the Emacs process is killed.
+
+   For possible display bugs, it is important to report the terminal
+type (the value of environment variable `TERM'), the complete termcap
+entry for the terminal from `/etc/termcap' (since that file is not
+identical on all machines), and the output that Emacs actually sent to
+the terminal.  The way to collect this output is to execute the Lisp
+expression:
+
+     (open-termscript "~/termscript")
+
+using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
+Emacs.  From then on, all output from Emacs to the terminal will be
+written in the specified termscript file as well, until the Emacs
+process is killed.  If the problem happens when Emacs starts up, put
+this expression into your init file so that the termscript file will be
+open when Emacs displays the screen for the first time.  *Note Init
+File::. Be warned: it is often difficult, and sometimes impossible, to
+fix a terminal-dependent bug without access to a terminal of the type
+that stimulates the bug.
+
+   The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
+discussions and requests for assistance.
+
+   If you don't have access to this newgroup, you can subscribe to the
+mailing list version: the newsgroup is bidirectionally gatewayed into
+the mailing list `xemacs@xemacs.org'.
+
+   To be added or removed from this mailing list, send mail to
+`xemacs-request@xemacs.org'.  Do not send requests for addition to the
+mailing list itself.
+
+   The mailing lists and newsgroups are archived on our anonymous FTP
+server, `ftp.xemacs.org', and at various other archive sites around the
+net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
+FTP server. It provides some introductory information and help for
+initial configuration problems.

 
 

diff --git a/info/xemacs.info-4 b/info/xemacs.info-4
index 53fc1cd..af09a71 100644 (file)
--- a/info/xemacs.info-4
+++ b/info/xemacs.info-4
@@ -1,4 +1,4 @@
-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.6 from

 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 xemacs/xemacs.texi.
 
 INFO-DIR-SECTION XEmacs Editor

@@ -30,1166 +30,3340 @@ versions, except that the sections entitled "The GNU Manifesto",
 translation approved by the author instead of in the original English.
 
 \1f
 translation approved by the author instead of in the original English.
 
 \1f

-File: xemacs.info,  Node: Position Info,  Next: Arguments,  Prev: Continuation Lines,  Up: Basic
-
-Cursor Position Information
-===========================
-
-   If you are accustomed to other display editors, you may be surprised
-that Emacs does not always display the page number or line number of
-point in the mode line.  In Emacs, this information is only rarely
-needed, and a number of commands are available to compute and print it.
-Since text is stored in a way that makes it difficult to compute the
-information, it is not displayed all the time.
-
-`M-x what-page'
-     Print page number of point, and line number within page.
-
-`M-x what-line'
-     Print line number of point in the buffer.
-
-`M-x line-number-mode'
-     Toggle automatic display of current line number.
-
-`M-='
-     Print number of lines and characters in the current region
-     (`count-lines-region').  *Note Mark::, for information about the
-     region.
-
-`C-x ='
-     Print character code of character after point, character position
-     of point, and column of point (`what-cursor-position').
-
-   There are several commands for printing line numbers:
-
-   * `M-x what-line' counts lines from the beginning of the file and
-     prints the line number point is on.  The first line of the file is
-     line number 1.  You can use these numbers as arguments to `M-x
-     goto-line'.
-
-   * `M-x what-page' counts pages from the beginning of the file, and
-     counts lines within the page, printing both of them.  *Note
-     Pages::, for the command `C-x l', which counts the lines in the
-     current page.
-
-   * `M-=' (`count-lines-region') prints the number of lines in the
-     region (*note Mark::).  *Note Pages::, for the command `C-x l'
-     which counts the lines in the
-
-   The command `C-x =' (`what-cursor-position') can be used to find out
-the column that the cursor is in, and other miscellaneous information
-about point.  It prints a line in the echo area that looks like this:
-
-     Char: c (0143, 99, 0x63)  point=18862 of 24800(76%)  column 53
-
-(In fact, this is the output produced when point is before `column 53'
-in the example.)
-
-   The four values after `Char:' describe the character that follows
-point, first by showing it and then by giving its character code in
-octal, decimal and hex.
-
-   `point=' is followed by the position of point expressed as a
-character count.  The front of the buffer counts as position 1, one
-character later as 2, and so on.  The next, larger number is the total
-number of characters in the buffer.  Afterward in parentheses comes the
-position expressed as a percentage of the total size.
-
-   `column' is followed by the horizontal position of point, in columns
-from the left edge of the window.
-
-   If the buffer has been narrowed, making some of the text at the
-beginning and the end temporarily invisible, `C-x =' prints additional
-text describing the current visible range.  For example, it might say:
-
-     Char: c (0143, 99, 0x63)  point=19674 of 24575(80%) <19591 - 19703>  column 69
-
-where the two extra numbers give the smallest and largest character
-position that point is allowed to assume.  The characters between those
-two positions are the visible ones.  *Note Narrowing::.
-
-   If point is at the end of the buffer (or the end of the visible
-part), `C-x =' omits any description of the character after point.  The
-output looks like
-
-     point=563026 of 563025(100%)  column 0
-
-\1f
-File: xemacs.info,  Node: Arguments,  Prev: Position Info,  Up: Basic
-
-Numeric Arguments
-=================
-
-   In mathematics and computer usage, the word "argument" means "data
-provided to a function or operation."  Any Emacs command can be given a
-"numeric argument" (also called a "prefix argument").  Some commands
-interpret the argument as a repetition count.  For example, giving an
-argument of ten to the key `C-f' (the command `forward-char', move
-forward one character) moves forward ten characters.  With these
-commands, no argument is equivalent to an argument of one.  Negative
-arguments are allowed.  Often they tell a command to move or act  in
-the opposite direction.
-
-   If your keyboard has a <META> key (labelled with a diamond on
-Sun-type keyboards and labelled `Alt' on some other keyboards), the
-easiest way to specify a numeric argument is to type digits and/or a
-minus sign while holding down the <META> key.  For example,
-     M-5 C-n
-
-would move down five lines.  The characters `Meta-1', `Meta-2', and so
-on, as well as `Meta--', do this because they are keys bound to
-commands (`digit-argument' and `negative-argument') that are defined to
-contribute to an argument for the next command.  Digits and `-'
-modified with Control, or Control and Meta, also specify numeric
-arguments.
-
-   Another way of specifying an argument is to use the `C-u'
-(`universal-argument') command followed by the digits of the argument.
-With `C-u', you can type the argument digits without holding down
-modifier keys; `C-u' works on all terminals.  To type a negative
-argument, type a minus sign after `C-u'.  Just a minus sign without
-digits normally means -1.
-
-   `C-u' followed by a character which is neither a digit nor a minus
-sign has the special meaning of "multiply by four".  It multiplies the
-argument for the next command by four.  `C-u' twice multiplies it by
-sixteen.  Thus, `C-u C-u C-f' moves forward sixteen characters.  This
-is a good way to move forward "fast", since it moves about 1/5 of a line
-in the usual size frame.  Other useful combinations are `C-u C-n', `C-u
-C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a
-lot" of blank lines), and `C-u C-k' (kill four lines).
-
-   Some commands care only about whether there is an argument and not
-about its value.  For example, the command `M-q' (`fill-paragraph') with
-no argument fills text; with an argument, it justifies the text as well.
-(*Note Filling::, for more information on `M-q'.)  Just `C-u' is a
-handy way of providing an argument for such commands.
-
-   Some commands use the value of the argument as a repeat count, but do
-something peculiar when there is no argument.  For example, the command
-`C-k' (`kill-line') with argument N kills N lines, including their
-terminating newlines.  But `C-k' with no argument is special: it kills
-the text up to the next newline, or, if point is right at the end of
-the line, it kills the newline itself.  Thus, two `C-k' commands with
-no arguments can kill a non-blank line, just like `C-k' with an
-argument of one.  (*Note Killing::, for more information on `C-k'.)
-
-   A few commands treat a plain `C-u' differently from an ordinary
-argument.  A few others may treat an argument of just a minus sign
-differently from an argument of -1.  These unusual cases are described
-when they come up; they are always for reasons of convenience of use of
-the individual command.
-
-   You can use a numeric argument to insert multiple copies of a
-character.  This is straightforward unless the character is a digit; for
-example, `C-u 6 4 a' inserts 64 copies of the character `a'.  But this
-does not work for inserting digits; `C-u 6 4 1' specifies an argument
-of 641, rather than inserting anything.  To separate the digit to
-insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
-1' does insert 64 copies of the character `1'.
-
-   We use the term "prefix argument" as well as "numeric argument" to
-emphasize that you type the argument before the command, and to
-distinguish these arguments from minibuffer arguments that come after
-the command.
-
-\1f
-File: xemacs.info,  Node: Undo,  Next: Minibuffer,  Prev: Basic,  Up: Top
-
-Undoing Changes
-***************
-
-   Emacs allows you to undo all changes you make to the text of a
-buffer, up to a certain amount of change (8000 characters).  Each
-buffer records changes individually, and the undo command always
-applies to the current buffer.  Usually each editing command makes a
-separate entry in the undo records, but some commands such as
-`query-replace' make many entries, and very simple commands such as
-self-inserting characters are often grouped to make undoing less
-tedious.
-
-`C-x u'
-     Undo one batch of changes (usually, one command's worth) (`undo').
-
-`C-_'
-     The same.
-
-   The command `C-x u' or `C-_' allows you to undo changes.  The first
-time you give this command, it undoes the last change.  Point moves to
-the text affected by the undo, so you can see what was undone.
-
-   Consecutive repetitions of the `C-_' or `C-x u' commands undo
-earlier and earlier changes, back to the limit of what has been
-recorded.  If all recorded changes have already been undone, the undo
-command prints an error message and does nothing.
-
-   Any command other than an undo command breaks the sequence of undo
-commands.  Starting at this moment, the previous undo commands are
-considered ordinary changes that can themselves be undone.  Thus, you
-can redo changes you have undone by typing `C-f' or any other command
-that have no important effect, and then using more undo commands.
-
-   If you notice that a buffer has been modified accidentally, the
-easiest way to recover is to type `C-_' repeatedly until the stars
-disappear from the front of the mode line.  When that happens, all the
-modifications you made have been canceled.  If you do not remember
-whether you changed the buffer deliberately, type `C-_' once. When you
-see Emacs undo the last change you made, you probably remember why you
-made it.  If the change was an accident, leave it undone.  If it was
-deliberate, redo the change as described in the preceding paragraph.
-
-   Whenever an undo command makes the stars disappear from the mode
-line, the buffer contents is the same as it was when the file was last
-read in or saved.
-
-   Not all buffers record undo information.  Buffers whose names start
-with spaces don't; these buffers are used internally by Emacs and its
-extensions to hold text that users don't normally look at or edit.
-Minibuffers, help buffers, and documentation buffers also don't record
-undo information.
-
-   Emacs can remember at most 8000 or so characters of deleted or
-modified text in any one buffer for reinsertion by the undo command.
-There is also a limit on the number of individual insert, delete, or
-change actions that Emacs can remember.
-
-   There are two keys to run the `undo' command, `C-x u' and `C-_',
-because on some keyboards, it is not obvious how to type `C-_'. `C-x u'
-is an alternative you can type in the same fashion on any terminal.
-
-\1f
-File: xemacs.info,  Node: Minibuffer,  Next: M-x,  Prev: Undo,  Up: Top
-
-The Minibuffer
-**************
-
-   The "minibuffer" is the facility used by XEmacs commands to read
-arguments more complicated than a single number.  Minibuffer arguments
-can be file names, buffer names, Lisp function names, XEmacs command
-names, Lisp expressions, and many other things, depending on the command
-reading the argument.  You can use the usual XEmacs editing commands in
-the minibuffer to edit the argument text.
-
-   When the minibuffer is in use, it appears in the echo area, and the
-cursor moves there.  The beginning of the minibuffer line displays a
-"prompt" which says what kind of input you should supply and how it
-will be used.  Often this prompt is derived from the name of the command
-that the argument is for.  The prompt normally ends with a colon.
-
-   Sometimes a "default argument" appears in parentheses after the
-colon; it, too, is part of the prompt.  The default is used as the
-argument value if you enter an empty argument (e.g., by just typing
-<RET>).  For example, commands that read buffer names always show a
-default, which is the name of the buffer that will be used if you type
-just <RET>.
-
-   The simplest way to enter a minibuffer argument is to type the text
-you want, terminated by <RET> which exits the minibuffer.  You can
-cancel the command that wants the argument, and get out of the
-minibuffer, by typing `C-g'.
-
-   Since the minibuffer uses the screen space of the echo area, it can
-conflict with other ways XEmacs customarily uses the echo area.  Here is
-how XEmacs handles such conflicts:
-
-   * If a command gets an error while you are in the minibuffer, this
-     does not cancel the minibuffer.  However, the echo area is needed
-     for the error message and therefore the minibuffer itself is
-     hidden for a while.  It comes back after a few seconds, or as soon
-     as you type anything.
-
-   * If in the minibuffer you use a command whose purpose is to print a
-     message in the echo area, such as `C-x =', the message is printed
-     normally, and the minibuffer is hidden for a while.  It comes back
-     after a few seconds, or as soon as you type anything.
-
-   * Echoing of keystrokes does not take place while the minibuffer is
-     in use.
-
-* Menu:
-
-* File: Minibuffer File.  Entering file names with the minibuffer.
-* Edit: Minibuffer Edit.  How to edit in the minibuffer.
-* Completion::           An abbreviation facility for minibuffer input.
-* Minibuffer History::    Reusing recent minibuffer arguments.
-* Repetition::           Re-executing commands that used the minibuffer.
-
-\1f
-File: xemacs.info,  Node: Minibuffer File,  Next: Minibuffer Edit,  Prev: Minibuffer,  Up: Minibuffer
-
-Minibuffers for File Names
-==========================
-
-   Sometimes the minibuffer starts out with text in it.  For example,
-when you are supposed to give a file name, the minibuffer starts out
-containing the "default directory", which ends with a slash.  This is
-to inform you which directory the file will be found in if you do not
-specify a directory.
-
-   For example, the minibuffer might start out with these contents:
-
-     Find File: /u2/emacs/src/
-
-where `Find File: ' is the prompt.  Typing `buffer.c' specifies the
-file `/u2/emacs/src/buffer.c'.  To find files in nearby directories,
-use `..'; thus, if you type `../lisp/simple.el', you will get the file
-named `/u2/emacs/lisp/simple.el'.  Alternatively, you can kill with
-`M-<DEL>' the directory names you don't want (*note Words::).
-
-   If you don't want any of the default, you can kill it with `C-a
-C-k'.  But you don't need to kill the default; you can simply ignore it.
-Insert an absolute file name, one starting with a slash or a tilde,
-after the default directory.  For example, to specify the file
-`/etc/termcap', just insert that name, giving these minibuffer contents:
-
-     Find File: /u2/emacs/src//etc/termcap
-
-XEmacs gives a special meaning to a double slash (which is not normally
-a useful thing to write): it means, "ignore everything before the
-second slash in the pair."  Thus, `/u2/emacs/src/' is ignored in the
-example above, and you get the file `/etc/termcap'.
-
-   If you set `insert-default-directory' to `nil', the default
-directory is not inserted in the minibuffer.  This way, the minibuffer
-starts out empty.  But the name you type, if relative, is still
-interpreted with respect to the same default directory.
-
-\1f
-File: xemacs.info,  Node: Minibuffer Edit,  Next: Completion,  Prev: Minibuffer File,  Up: Minibuffer
-
-Editing in the Minibuffer
-=========================
-
-   The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
-usual XEmacs commands are available for editing the text of an argument
-you are entering.
-
-   Since <RET> in the minibuffer is defined to exit the minibuffer, you
-can't use it to insert a newline in the minibuffer.  To do that, type
-`C-o' or `C-q C-j'.  (Recall that a newline is really the character
-control-J.)
-
-   The minibuffer has its own window which always has space on the
-screen but acts as if it were not there when the minibuffer is not in
-use.  When the minibuffer is in use, its window is just like the
-others; you can switch to another window with `C-x o', edit text in
-other windows and perhaps even visit more files, before returning to the
-minibuffer to submit the argument.  You can kill text in another window,
-return to the minibuffer window, and then yank the text to use it in the
-argument.  *Note Windows::.
-
-   There are some restrictions on the use of the minibuffer window,
-however.  You cannot switch buffers in it--the minibuffer and its
-window are permanently attached.  Also, you cannot split or kill the
-minibuffer window. But you can make it taller in the normal fashion with
-`C-x ^'.  If you enable Resize-Minibuffer mode, then the minibuffer
-window expands vertically as necessary to hold the text that you put in
-the minibuffer.  Use `M-x resize-minibuffer-mode' to enable or disable
-this minor mode (*note Minor Modes::).
-
-   If while in the minibuffer you issue a command that displays help
-text of any sort in another window, you can use the `C-M-v' command
-while in the minibuffer to scroll the help text.  This lasts until you
-exit the minibuffer.  This feature is especially useful if a completing
-minibuffer gives you a list of possible completions.  *Note Other
-Window::.
-
-   If the variable `minibuffer-confirm-incomplete' is `t', you are
-asked for confirmation if there is no known completion for the text you
-typed. For example, if you attempted to visit a non-existent file, the
-minibuffer might read:
-             Find File: chocolate_bar.c [no completions, confirm]
-   If you press `Return' again, that confirms the filename. Otherwise,
-you can continue editing it.
-
-   XEmacs supports recursive use of the minibuffer.  However, it is easy
-to do this by accident (because of autorepeating keyboards, for example)
-and get confused.  Therefore, most XEmacs commands that use the
-minibuffer refuse to operate if the minibuffer window is selected.  If
-the minibuffer is active but you have switched to a different window,
-recursive use of the minibuffer is allowed--if you know enough to try
-to do this, you probably will not get confused.
-
-   If you set the variable `enable-recursive-minibuffers' to a
-non-`nil', recursive use of the minibuffer is always allowed.
-
-\1f
-File: xemacs.info,  Node: Completion,  Next: Minibuffer History,  Prev: Minibuffer Edit,  Up: Minibuffer
+File: xemacs.info,  Node: Glossary,  Next: Manifesto,  Prev: Intro,  Up: Top
+
+Glossary
+********
+
+Abbrev
+     An abbrev is a text string which expands into a different text
+     string when present in the buffer.  For example, you might define
+     a short word as an abbrev for a long phrase that you want to insert
+     frequently.  *Note Abbrevs::.
+
+Aborting
+     Aborting means getting out of a recursive edit (q.v.).  You can use
+     the commands `C-]' and `M-x top-level' for this.  *Note Quitting::.
+
+Auto Fill mode
+     Auto Fill mode is a minor mode in which text you insert is
+     automatically broken into lines of fixed width.  *Note Filling::.
+
+Auto Saving
+     Auto saving means that Emacs automatically stores the contents of
+     an Emacs buffer in a specially-named file so the information will
+     not be lost if the buffer is lost due to a system error or user
+     error.  *Note Auto Save::.
+
+Backup File
+     A backup file records the contents that a file had before the
+     current editing session.  Emacs creates backup files automatically
+     to help you track down or cancel changes you later regret.  *Note
+     Backup::.
+
+Balance Parentheses
+     Emacs can balance parentheses manually or automatically.  Manual
+     balancing is done by the commands to move over balanced expressions
+     (*note Lists::).  Automatic balancing is done by blinking the
+     parenthesis that matches one just inserted (*note Matching Parens:
+     Matching.).
+
+Bind
+     To bind a key is to change its binding (q.v.).  *Note Rebinding::.
+
+Binding
+     A key gets its meaning in Emacs by having a binding which is a
+     command (q.v.), a Lisp function that is run when the key is typed.
+     *Note Binding: Commands.  Customization often involves rebinding a
+     character to a different command function.  The bindings of all
+     keys are recorded in the keymaps (q.v.).  *Note Keymaps::.
+
+Blank Lines
+     Blank lines are lines that contain only whitespace.  Emacs has
+     several commands for operating on the blank lines in a buffer.
+
+Buffer
+     The buffer is the basic editing unit; one buffer corresponds to one
+     piece of text being edited.  You can have several buffers, but at
+     any time you are editing only one, the `selected' buffer, though
+     several buffers can be visible when you are using multiple
+     windows.  *Note Buffers::.
+
+Buffer Selection History
+     Emacs keeps a buffer selection history which records how recently
+     each Emacs buffer was selected.  Emacs uses this list when
+     choosing a buffer to select.  *Note Buffers::.
+
+C-
+     `C' in the name of a character is an abbreviation for Control.
+     *Note C-: Keystrokes.
+
+C-M-
+     `C-M-' in the name of a character is an abbreviation for
+     Control-Meta.  *Note C-M-: Keystrokes.
+
+Case Conversion
+     Case conversion means changing text from upper case to lower case
+     or vice versa.  *Note Case::, for the commands for case conversion.
+
+Characters
+     Characters form the contents of an Emacs buffer; also, Emacs
+     commands are invoked by keys (q.v.), which are sequences of one or
+     more characters.  *Note Keystrokes::.
+
+Command
+     A command is a Lisp function specially defined to be able to serve
+     as a key binding in Emacs.  When you type a key (q.v.), Emacs
+     looks up its binding (q.v.) in the relevant keymaps (q.v.) to find
+     the command to run.  *Note Commands::.
+
+Command Name
+     A command name is the name of a Lisp symbol which is a command
+     (*note Commands::).  You can invoke any command by its name using
+     `M-x' (*note M-x::).
+
+Comments
+     A comment is text in a program which is intended only for the
+     people reading the program, and is marked specially so that it
+     will be ignored when the program is loaded or compiled.  Emacs
+     offers special commands for creating, aligning, and killing
+     comments.  *Note Comments::.
+
+Compilation
+     Compilation is the process of creating an executable program from
+     source code.  Emacs has commands for compiling files of Emacs Lisp
+     code (*note Lisp Libraries::) and programs in C and other languages
+     (*note Compilation::).
+
+Complete Key
+     A complete key is a character or sequence of characters which,
+     when typed by the user, fully specifies one action to be performed
+     by Emacs.  For example, `X' and `Control-f' and `Control-x m' are
+     keys.  Keys derive their meanings from being bound (q.v.) to
+     commands (q.v.).  Thus, `X' is conventionally bound to a command
+     to insert `X' in the buffer; `C-x m' is conventionally bound to a
+     command to begin composing a mail message. *Note Keystrokes::.

 
 Completion
 
 Completion

-==========
-
-   For certain kinds of arguments, you can use "completion" to enter
-the argument value.  Completion means that you type part of the
-argument, then XEmacs visibly fills in the rest, or as much as can be
-determined from the part you have typed.
-
-   When completion is available, certain keys--<TAB>, <RET>, and
-<SPC>--are rebound to complete the text present in the minibuffer into
-a longer string that it stands for, by matching it against a set of
-"completion alternatives" provided by the command reading the argument.
-`?' is defined to display a list of possible completions of what you
-have inserted.
-
-   For example, when `M-x' uses the minibuffer to read the name of a
-command, it provides a list of all available XEmacs command names to
-complete against.  The completion keys match the text in the minibuffer
-against all the command names, find any additional name characters
-implied by the ones already present in the minibuffer, and add those
-characters to the ones you have given.  This is what makes it possible
-to type `M-x inse <SPC> b <RET>' instead of `M-x insert-buffer <RET>'
-(for example).
-
-   Case is normally significant in completion because it is significant
-in most of the names that you can complete (buffer names, file names and
-command names).  Thus, `fo' does not complete to `Foo'.  When you are
-completing a name in which case does not matter, case may be ignored
-for completion's sake if specified by program.
-
-   When a completion list is displayed, the completions will highlight
-as you move the mouse over them.  Clicking the middle mouse button on
-any highlighted completion will "select" it just as if you had typed it
-in and hit <RET>.
-
-* Menu:
-
-* Example: Completion Example.
-* Commands: Completion Commands.
-* Strict Completion::
-* Options: Completion Options.
+     When Emacs automatically fills an abbreviation for a name into the
+     entire name, that process is called completion.  Completion is
+     done for minibuffer (q.v.) arguments when the set of possible
+     valid inputs is known; for example, on command names, buffer
+     names, and file names.  Completion occurs when you type <TAB>,
+     <SPC>, or <RET>.  *Note Completion::.
+
+Continuation Line
+     When a line of text is longer than the width of the frame, it
+     takes up more than one screen line when displayed.  We say that the
+     text line is continued, and all screen lines used for it after the
+     first are called continuation lines.  *Note Continuation: Basic.
+
+Control-Character
+     ASCII characters with octal codes 0 through 037, and also code
+     0177, do not have graphic images assigned to them.  These are the
+     control characters.  Any control character can be typed by holding
+     down the <CTRL> key and typing some other character; some have
+     special keys on the keyboard.  <RET>, <TAB>, <ESC>, <LFD>, and
+     <DEL> are all control characters.  *Note Keystrokes::.
+
+Copyleft
+     A copyleft is a notice giving the public legal permission to
+     redistribute a program or other work of art.  Copylefts are used
+     by leftists to enrich the public just as copyrights are used by
+     rightists to gain power over the public.
+
+Current Buffer
+     The current buffer in Emacs is the Emacs buffer on which most
+     editing commands operate.  You can select any Emacs buffer as the
+     current one.  *Note Buffers::.
+
+Current Line
+     The line point is on (*note Point::).
+
+Current Paragraph
+     The paragraph that point is in.  If point is between paragraphs,
+     the current paragraph is the one that follows point.  *Note
+     Paragraphs::.
+
+Current Defun
+     The defun (q.v.) that point is in.  If point is between defuns, the
+     current defun is the one that follows point.  *Note Defuns::.
+
+Cursor
+     The cursor is the rectangle on the screen which indicates the
+     position called point (q.v.) at which insertion and deletion takes
+     place.  The cursor is on or under the character that follows
+     point.  Often people speak of `the cursor' when, strictly
+     speaking, they mean `point'.  *Note Cursor: Basic.
+
+Customization
+     Customization is making minor changes in the way Emacs works.  It
+     is often done by setting variables (*note Variables::) or by
+     rebinding keys (*note Keymaps::).
+
+Default Argument
+     The default for an argument is the value that is used if you do not
+     specify one.  When Emacs prompts you in the minibuffer for an
+     argument, the default argument is used if you just type <RET>.
+     *Note Minibuffer::.
+
+Default Directory
+     When you specify a file name that does not start with `/' or `~',
+     it is interpreted relative to the current buffer's default
+     directory.  *Note Default Directory: Minibuffer File.
+
+Defun
+     A defun is a list at the top level of parenthesis or bracket
+     structure in a program.  It is so named because most such lists in
+     Lisp programs are calls to the Lisp function `defun'.  *Note
+     Defuns::.
+
+<DEL>
+     The <DEL> character runs the command that deletes one character of
+     text.  *Note DEL: Basic.
+
+Deletion
+     Deleting text means erasing it without saving it.  Emacs deletes
+     text only when it is expected not to be worth saving (all
+     whitespace, or only one character).  The alternative is killing
+     (q.v.).  *Note Deletion: Killing.
+
+Deletion of Files
+     Deleting a file means removing it from the file system.  *Note
+     Misc File Ops::.
+
+Deletion of Messages
+     Deleting a message means flagging it to be eliminated from your
+     mail file.  Until the mail file is expunged, you can undo this by
+     undeleting the message.
+
+Deletion of Frames
+     When working under the multi-frame X-based version of XEmacs, you
+     can delete individual frames using the Close menu item from the
+     File menu.
+
+Deletion of Windows
+     When you delete a subwindow of an Emacs frame, you eliminate it
+     from the frame.  Other windows expand to use up the space.  The
+     deleted window can never come back, but no actual text is lost.
+     *Note Windows::.
+
+Directory
+     Files in the Unix file system are grouped into file directories.
+     *Note Directories: ListDir.
+
+Dired
+     Dired is the Emacs facility that displays the contents of a file
+     directory and allows you to "edit the directory", performing
+     operations on the files in the directory.  *Note Dired::.
+
+Disabled Command
+     A disabled command is one that you may not run without special
+     confirmation.  Commands are usually disabled because they are
+     confusing for beginning users.  *Note Disabling::.
+
+Dribble File
+     A file into which Emacs writes all the characters that the user
+     types on the keyboard.  Dribble files are used to make a record for
+     debugging Emacs bugs.  Emacs does not make a dribble file unless
+     you tell it to.  *Note Bugs::.
+
+Echo Area
+     The area at the bottom of the Emacs frame which is used for
+     echoing the arguments to commands, for asking questions, and for
+     printing brief messages (including error messages).  *Note Echo
+     Area::.
+
+Echoing
+     Echoing refers to acknowledging the receipt of commands by
+     displaying them (in the echo area).  Emacs never echoes
+     single-character keys; longer keys echo only if you pause while
+     typing them.
+
+Error
+     An error occurs when an Emacs command cannot execute in the current
+     circumstances.  When an error occurs, execution of the command
+     stops (unless the command has been programmed to do otherwise) and
+     Emacs reports the error by printing an error message (q.v.).
+     Type-ahead is discarded.  Then Emacs is ready to read another
+     editing command.
+
+Error Messages
+     Error messages are single lines of output printed by Emacs when the
+     user asks for something impossible to do (such as killing text
+     forward when point is at the end of the buffer).  They appear in
+     the echo area, accompanied by a beep.
+
+<ESC>
+     <ESC> is a character used as a prefix for typing Meta characters on
+     keyboards lacking a <META> key.  Unlike the <META> key (which,
+     like the <SHIFT> key, is held down while another character is
+     typed), the <ESC> key is pressed and released, and applies to the
+     next character typed.
+
+Fill Prefix
+     The fill prefix is a string that Emacs enters at the beginning of
+     each line when it performs filling.  It is not regarded as part of
+     the text to be filled.  *Note Filling::.
+
+Filling
+     Filling text means moving text from line to line so that all the
+     lines are approximately the same length.  *Note Filling::.
+
+Frame
+     When running Emacs on a TTY terminal, "frame" means the terminal's
+     screen.  When running Emacs under X, you can have multiple frames,
+     each corresponding to a top-level X window and each looking like
+     the screen on a TTY.  Each frame contains one or more
+     non-overlapping Emacs windows (possibly with associated
+     scrollbars, under X), an echo area, and (under X) possibly a
+     menubar, toolbar, and/or gutter.
+
+Global
+     Global means `independent of the current environment; in effect
+     throughout Emacs'.  It is the opposite of local (q.v.).  Examples
+     of the use of `global' appear below.
+
+Global Abbrev
+     A global definition of an abbrev (q.v.) is effective in all major
+     modes that do not have local (q.v.) definitions for the same
+     abbrev.  *Note Abbrevs::.
+
+Global Keymap
+     The global keymap (q.v.) contains key bindings that are in effect
+     unless local key bindings in a major mode's local keymap (q.v.)
+     override them.*Note Keymaps::.
+
+Global Substitution
+     Global substitution means replacing each occurrence of one string
+     by another string through a large amount of text.  *Note Replace::.
+
+Global Variable
+     The global value of a variable (q.v.) takes effect in all buffers
+     that do not have their own local (q.v.) values for the variable.
+     *Note Variables::.
+
+Graphic Character
+     Graphic characters are those assigned pictorial images rather than
+     just names.  All the non-Meta (q.v.) characters except for the
+     Control (q.v.) character are graphic characters.  These include
+     letters, digits, punctuation, and spaces; they do not include
+     <RET> or <ESC>.  In Emacs, typing a graphic character inserts that
+     character (in ordinary editing modes).  *Note Basic Editing: Basic.
+
+Grinding
+     Grinding means adjusting the indentation in a program to fit the
+     nesting structure.  *Note Grinding: Indentation.
+
+Hardcopy
+     Hardcopy means printed output.  Emacs has commands for making
+     printed listings of text in Emacs buffers.  *Note Hardcopy::.
+
+<HELP>
+     You can type <HELP> at any time to ask what options you have, or
+     to ask what any command does.  <HELP> is really `Control-h'.
+     *Note Help::.
+
+Inbox
+     An inbox is a file in which mail is delivered by the operating
+     system.  Some mail handlers transfers mail from inboxes to mail
+     files (q.v.) in which the mail is then stored permanently or until
+     explicitly deleted.
+
+Indentation
+     Indentation means blank space at the beginning of a line.  Most
+     programming languages have conventions for using indentation to
+     illuminate the structure of the program, and Emacs has special
+     features to help you set up the correct indentation.  *Note
+     Indentation::.
+
+Insertion
+     Insertion means copying text into the buffer, either from the
+     keyboard or from some other place in Emacs.
+
+Justification
+     Justification means adding extra spaces to lines of text to make
+     them come exactly to a specified width.  *Note Justification:
+     Filling.
+
+Keyboard Macros
+     Keyboard macros are a way of defining new Emacs commands from
+     sequences of existing ones, with no need to write a Lisp program.
+     *Note Keyboard Macros::.
+
+Key
+     A key is a sequence of characters that, when input to Emacs,
+     specify or begin to specify a single action for Emacs to perform.
+     That is, the sequence is considered a single unit.  If the key is
+     enough to specify one action, it is a complete key (q.v.); if it
+     is less than enough, it is a prefix key (q.v.).  *Note
+     Keystrokes::.
+
+Keymap
+     The keymap is the data structure that records the bindings (q.v.)
+     of keys to the commands that they run.  For example, the keymap
+     binds the character `C-n' to the command function `next-line'.
+     *Note Keymaps::.
+
+Kill Ring
+     The kill ring is the place where all text you have killed recently
+     is saved.  You can re-insert any of the killed text still in the
+     ring; this is called yanking (q.v.).  *Note Yanking::.
+
+Killing
+     Killing means erasing text and saving it on the kill ring so it
+     can be yanked (q.v.) later.  Some other systems call this
+     "cutting."  Most Emacs commands to erase text do killing, as
+     opposed to deletion (q.v.).  *Note Killing::.
+
+Killing Jobs
+     Killing a job (such as, an invocation of Emacs) means making it
+     cease to exist.  Any data within it, if not saved in a file, is
+     lost.  *Note Exiting::.
+
+List
+     A list is, approximately, a text string beginning with an open
+     parenthesis and ending with the matching close parenthesis.  In C
+     mode and other non-Lisp modes, groupings surrounded by other kinds
+     of matched delimiters appropriate to the language, such as braces,
+     are also considered lists.  Emacs has special commands for many
+     operations on lists.  *Note Lists::.
+
+Local
+     Local means `in effect only in a particular context'; the relevant
+     kind of context is a particular function execution, a particular
+     buffer, or a particular major mode.  Local is the opposite of
+     `global' (q.v.).  Specific uses of `local' in Emacs terminology
+     appear below.
+
+Local Abbrev
+     A local abbrev definition is effective only if a particular major
+     mode is selected.  In that major mode, it overrides any global
+     definition for the same abbrev.  *Note Abbrevs::.
+
+Local Keymap
+     A local keymap is used in a particular major mode; the key bindings
+     (q.v.) in the current local keymap override global bindings of the
+     same keys.  *Note Keymaps::.
+
+Local Variable
+     A local value of a variable (q.v.) applies to only one buffer.
+     *Note Locals::.
+
+M-
+     `M-' in the name of a character is an abbreviation for <META>, one
+     of the modifier keys that can accompany any character.  *Note
+     Keystrokes::.
+
+M-C-
+     `M-C-' in the name of a character is an abbreviation for
+     Control-Meta; it means the same thing as `C-M-'.  If your terminal
+     lacks a real <META> key, you type a Control-Meta character by
+     typing <ESC> and then typing the corresponding Control character.
+     *Note C-M-: Keystrokes.
+
+M-x
+     `M-x' is the key which is used to call an Emacs command by name.
+     You use it to call commands that are not bound to keys.  *Note
+     M-x::.
+
+Mail
+     Mail means messages sent from one user to another through the
+     computer system, to be read at the recipient's convenience.  Emacs
+     has commands for composing and sending mail, and for reading and
+     editing the mail you have received.  *Note Sending Mail::.
+
+Major Mode
+     The major modes are a mutually exclusive set of options each of
+     which configures Emacs for editing a certain sort of text.
+     Ideally, each programming language has its own major mode.  *Note
+     Major Modes::.
+
+Mark
+     The mark points to a position in the text.  It specifies one end
+     of the region (q.v.), point being the other end.  Many commands
+     operate on the whole region, that is, all the text from point to
+     the mark.  *Note Mark::.
+
+Mark Ring
+     The mark ring is used to hold several recent previous locations of
+     the mark, just in case you want to move back to them.  *Note Mark
+     Ring::.
+
+Message
+     See `mail'.
+
+Meta
+     Meta is the name of a modifier bit which a command character may
+     have.  It is present in a character if the character is typed with
+     the <META> key held down.  Such characters are given names that
+     start with `Meta-'.  For example, `Meta-<' is typed by holding down
+     <META> and at the same time typing `<' (which itself is done, on
+     most terminals, by holding down <SHIFT> and typing `,').  *Note
+     Meta: Keystrokes.
+
+Meta Character
+     A Meta character is one whose character code includes the Meta bit.
+
+Minibuffer
+     The minibuffer is the window that Emacs displays inside the echo
+     area (q.v.) when it prompts you for arguments to commands.  *Note
+     Minibuffer::.
+
+Minor Mode
+     A minor mode is an optional feature of Emacs which can be switched
+     on or off independent of the major mode.  Each minor mode has a
+     command to turn it on or off.  *Note Minor Modes::.
+
+Mode Line
+     The mode line is the line at the bottom of each text window (q.v.),
+     which gives status information on the buffer displayed in that
+     window.  *Note Mode Line::.
+
+Modified Buffer
+     A buffer (q.v.) is modified if its text has been changed since the
+     last time the buffer was saved (or since it was created, if it has
+     never been saved).  *Note Saving::.
+
+Moving Text
+     Moving text means erasing it from one place and inserting it in
+     another.  This is done by killing (q.v.) and then yanking (q.v.).
+     *Note Killing::.
+
+Named Mark
+     A named mark is a register (q.v.) in its role of recording a
+     location in text so that you can move point to that location.
+     *Note Registers::.
+
+Narrowing
+     Narrowing means creating a restriction (q.v.) that limits editing
+     in the current buffer to only a part of the text in the buffer.
+     Text outside that part is inaccessible to the user until the
+     boundaries are widened again, but it is still there, and saving
+     the file saves the invisible text.  *Note Narrowing::.
+
+Newline
+     <LFD> characters in the buffer terminate lines of text and are
+     called newlines.  *Note Newline: Keystrokes.
+
+Numeric Argument
+     A numeric argument is a number, specified before a command, to
+     change the effect of the command.  Often the numeric argument
+     serves as a repeat count.  *Note Arguments::.
+
+Option
+     An option is a variable (q.v.) that allows you to customize Emacs
+     by giving it a new value.  *Note Variables::.
+
+Overwrite Mode
+     Overwrite mode is a minor mode.  When it is enabled, ordinary text
+     characters replace the existing text after point rather than
+     pushing it to the right.  *Note Minor Modes::.
+
+Page
+     A page is a unit of text, delimited by formfeed characters (ASCII
+     Control-L, code 014) coming at the beginning of a line.  Some Emacs
+     commands are provided for moving over and operating on pages.
+     *Note Pages::.
+
+Paragraphs
+     Paragraphs are the medium-size unit of English text.  There are
+     special Emacs commands for moving over and operating on paragraphs.
+     *Note Paragraphs::.
+
+Parsing
+     We say that Emacs parses words or expressions in the text being
+     edited.  Really, all it knows how to do is find the other end of a
+     word or expression.  *Note Syntax::.
+
+Point
+     Point is the place in the buffer at which insertion and deletion
+     occur.  Point is considered to be between two characters, not at
+     one character.  The terminal's cursor (q.v.) indicates the
+     location of point.  *Note Point: Basic.
+
+Prefix Key
+     A prefix key is a key (q.v.) whose sole function is to introduce a
+     set of multi-character keys.  `Control-x' is an example of a prefix
+     key; any two-character sequence starting with `C-x' is also a
+     legitimate key.  *Note Keystrokes::.
+
+Prompt
+     A prompt is text printed to ask the user for input.  Printing a
+     prompt is called prompting.  Emacs prompts always appear in the
+     echo area (q.v.).  One kind of prompting happens when the
+     minibuffer is used to read an argument (*note Minibuffer::); the
+     echoing which happens when you pause in the middle of typing a
+     multi-character key is also a kind of prompting (*note Echo
+     Area::).
+
+Quitting
+     Quitting means cancelling a partially typed command or a running
+     command, using `C-g'.  *Note Quitting::.
+
+Quoting
+     Quoting means depriving a character of its usual special
+     significance.  In Emacs this is usually done with `Control-q'.
+     What constitutes special significance depends on the context and
+     on convention.  For example, an "ordinary" character as an Emacs
+     command inserts itself; so in this context, a special character is
+     any character that does not normally insert itself (such as <DEL>,
+     for example), and quoting it makes it insert itself as if it were
+     not special.  Not all contexts allow quoting.  *Note Quoting:
+     Basic.
+
+Read-only Buffer
+     A read-only buffer is one whose text you are not allowed to change.
+     Normally Emacs makes buffers read-only when they contain text which
+     has a special significance to Emacs, such as Dired buffers.
+     Visiting a file that is write-protected also makes a read-only
+     buffer.  *Note Buffers::.
+
+Recursive Editing Level
+     A recursive editing level is a state in which part of the
+     execution of a command involves asking the user to edit some text.
+     This text may or may not be the same as the text to which the
+     command was applied.  The mode line indicates recursive editing
+     levels with square brackets (`[' and `]').  *Note Recursive Edit::.
+
+Redisplay
+     Redisplay is the process of correcting the image on the screen to
+     correspond to changes that have been made in the text being edited.
+     *Note Redisplay: Frame.
+
+Regexp
+     See `regular expression'.
+
+Region
+     The region is the text between point (q.v.) and the mark (q.v.).
+     Many commands operate on the text of the region.  *Note Region:
+     Mark.
+
+Registers
+     Registers are named slots in which text or buffer positions or
+     rectangles can be saved for later use.  *Note Registers::.
+
+Regular Expression
+     A regular expression is a pattern that can match various text
+     strings; for example, `l[0-9]+' matches `l' followed by one or more
+     digits.  *Note Regexps::.
+
+Replacement
+     See `global substitution'.
+
+Restriction
+     A buffer's restriction is the amount of text, at the beginning or
+     the end of the buffer, that is temporarily invisible and
+     inaccessible.  Giving a buffer a nonzero amount of restriction is
+     called narrowing (q.v.).  *Note Narrowing::.
+
+<RET>
+     <RET> is the character than runs the command to insert a newline
+     into the text.  It is also used to terminate most arguments read
+     in the minibuffer (q.v.).  *Note Return: Keystrokes.
+
+Saving
+     Saving a buffer means copying its text into the file that was
+     visited (q.v.) in that buffer.  To actually change a file you have
+     edited in Emacs, you have to save it.  *Note Saving::.
+
+Scrolling
+     Scrolling means shifting the text in the Emacs window to make a
+     different part of the buffer visible.  *Note Scrolling: Display.
+
+Searching
+     Searching means moving point to the next occurrence of a specified
+     string.  *Note Search::.
+
+Selecting
+     Selecting a buffer means making it the current (q.v.) buffer.
+     *Note Selecting: Buffers.
+
+Self-documentation
+     Self-documentation is the feature of Emacs which can tell you what
+     any command does, or can give you a list of all commands related
+     to a topic you specify.  You ask for self-documentation with the
+     help character, `C-h'.  *Note Help::.
+
+Sentences
+     Emacs has commands for moving by or killing by sentences.  *Note
+     Sentences::.
+
+Sexp
+     An sexp (short for `s-expression,' itself short for `symbolic
+     expression') is the basic syntactic unit of Lisp in its textual
+     form: either a list, or Lisp atom.  Many Emacs commands operate on
+     sexps.  The term `sexp' is generalized to languages other than
+     Lisp to mean a syntactically recognizable expression.  *Note
+     Sexps: Lists.
+
+Simultaneous Editing
+     Simultaneous editing means two users modifying the same file at
+     once.  If simultaneous editing is not detected, you may lose your
+     work.  Emacs detects all cases of simultaneous editing and warns
+     the user to investigate them.  *Note Simultaneous Editing:
+     Interlocking.
+
+String
+     A string is a kind of Lisp data object which contains a sequence of
+     characters.  Many Emacs variables are intended to have strings as
+     values.  The Lisp syntax for a string consists of the characters in
+     the string with a `"' before and another `"' after. Write a `"'
+     that is part of the string as `\"' and a `\' that is part of the
+     string as `\\'.  You can include all other characters, including
+     newline, just by writing them inside the string. You can also
+     include escape sequences as in C, such as `\n' for newline or
+     `\241' using an octal character code.
+
+String Substitution
+     See `global substitution'.
+
+Syntax Table
+     The syntax table tells Emacs which characters are part of a word,
+     which characters balance each other like parentheses, etc.  *Note
+     Syntax::.
+
+Tag Table
+     A tag table is a file that serves as an index to the function
+     definitions in one or more other files.  *Note Tags::.
+
+Termscript File
+     A termscript file contains a record of all characters Emacs sent to
+     the terminal.  It is used for tracking down bugs in Emacs
+     redisplay.  Emacs does not make a termscript file unless
+     explicitly instructed to do so.  *Note Bugs::.
+
+Text
+     Text has two meanings (*note Text::):
+
+        * Data consisting of a sequence of characters, as opposed to
+          binary numbers, images, graphics commands, executable
+          programs, and the like.  The contents of an Emacs buffer are
+          always text in this sense.
+
+        * Data consisting of written human language, as opposed to
+          programs, or something that follows the stylistic conventions
+          of human language.
+
+Top Level
+     Top level is the normal state of Emacs, in which you are editing
+     the text of the file you have visited.  You are at top level
+     whenever you are not in a recursive editing level (q.v.) or the
+     minibuffer (q.v.), and not in the middle of a command.  You can
+     get back to top level by aborting (q.v.) and quitting (q.v.).
+     *Note Quitting::.
+
+Transposition
+     Transposing two units of text means putting each one into the place
+     formerly occupied by the other.  There are Emacs commands to
+     transpose two adjacent characters, words, sexps (q.v.), or lines
+     (*note Transpose::).
+
+Truncation
+     Truncating text lines in the display means leaving out any text on
+     a line that does not fit within the right margin of the window
+     displaying it.  See also `continuation line'.  *Note Truncation:
+     Basic.
+
+Undoing
+     Undoing means making your previous editing go in reverse, bringing
+     back the text that existed earlier in the editing session.  *Note
+     Undo::.
+
+Variable
+     A variable is Lisp object that can store an arbitrary value.
+     Emacs uses some variables for internal purposes, and has others
+     (known as `options' (q.v.)) you can set to control the behavior of
+     Emacs.  The variables used in Emacs that you are likely to be
+     interested in are listed in the Variables Index of this manual.
+     *Note Variables::, for information on variables.
+
+Visiting
+     Visiting a file means loading its contents into a buffer (q.v.)
+     where they can be edited.  *Note Visiting::.
+
+Whitespace
+     Whitespace is any run of consecutive formatting characters (spaces,
+     tabs, newlines, and backspaces).
+
+Widening
+     Widening is removing any restriction (q.v.) on the current buffer;
+     it is the opposite of narrowing (q.v.).  *Note Narrowing::.
+
+Window
+     Emacs divides the frame into one or more windows, each of which can
+     display the contents of one buffer (q.v.) at any time.  *Note
+     Frame::, for basic information on how Emacs uses the frame.  *Note
+     Windows::, for commands to control the use of windows. Note that if
+     you are running Emacs under X, terminology can be confusing: Each
+     Emacs frame occupies a separate X window and can, in turn, be
+     divided into different subwindows.
+
+Word Abbrev
+     Synonymous with `abbrev'.
+
+Word Search
+     Word search is searching for a sequence of words, considering the
+     punctuation between them as insignificant.  *Note Word Search::.
+
+Yanking
+     Yanking means reinserting text previously killed.  It can be used
+     to undo a mistaken kill, or for copying or moving text.  Some other
+     systems call this "pasting".  *Note Yanking::.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Completion Example,  Next: Completion Commands,  Prev: Completion,  Up: Completion
-
-Completion Example
-------------------
-
-   A concrete example may help here.  If you type `M-x au <TAB>', the
-<TAB> looks for alternatives (in this case, command names) that start
-with `au'.  There are several, including `auto-fill-mode' and
-`auto-save-mode'--but they are all the same as far as `auto', so the
-`au' in the minibuffer changes to `auto'.
-
-   If you type <TAB> again immediately, there are multiple
-possibilities for the very next character--it could be any of `c-'--so
-no more characters are added; instead, <TAB> displays a list of all
-possible completions in another window.
-
-   If you go on to type `-f <TAB>', this <TAB> sees `auto-f'.  The only
-command name starting this way is `auto-fill-mode', so completion fills
-in the rest of that.  You now have `auto-fill-mode' in the minibuffer
-after typing just `au <TAB> f <TAB>'.  Note that <TAB> has this effect
-because in the minibuffer it is bound to the command
-`minibuffer-complete' when completion is available.
-
-\1f
-File: xemacs.info,  Node: Completion Commands,  Next: Strict Completion,  Prev: Completion Example,  Up: Completion
-
-Completion Commands
--------------------
-
-   Here is a list of the completion commands defined in the minibuffer
-when completion is available.
-
-`<TAB>'
-     Complete the text in the minibuffer as much as possible
-     (`minibuffer-complete').
-
-`<SPC>'
-     Complete the minibuffer text, but don't go beyond one word
-     (`minibuffer-complete-word').
-
-`<RET>'
-     Submit the text in the minibuffer as the argument, possibly
-     completing first as described below
-     (`minibuffer-complete-and-exit').
-
-`?'
-     Print a list of all possible completions of the text in the
-     minibuffer (`minibuffer-list-completions').
-
-`<button2>'
-     Select the highlighted text under the mouse as a minibuffer
-     response.  When the minibuffer is being used to prompt the user
-     for a completion, any valid completions which are visible on the
-     screen will be highlighted when the mouse moves over them.
-     Clicking <button2> will select the highlighted completion and exit
-     the minibuffer.  (`minibuf-select-highlighted-completion').
-
-   <SPC> completes much like <TAB>, but never goes beyond the next
-hyphen or space.  If you have `auto-f' in the minibuffer and type
-<SPC>, it finds that the completion is `auto-fill-mode', but it stops
-completing after `fill-'.  This gives `auto-fill-'.  Another <SPC> at
-this point completes all the way to `auto-fill-mode'.  <SPC> in the
-minibuffer when completion is available runs the command
-`minibuffer-complete-word'.
-
-   Here are some commands you can use to choose a completion from a
-window that displays a list of completions:
-
-`button2up'
-     Clicking mouse button 2 on a completion in the list of possible
-     completions chooses that completion (`mouse-choose-completion').
-     You normally use this command while point is in the minibuffer;
-     but you must click in the list of completions, not in the
-     minibuffer itself.
-
-`<PRIOR>'
-`M-v'
-     Typing <PRIOR> or `M-v', while in the minibuffer, selects the
-     window showing the completion list buffer
-     (`switch-to-completions').  This paves the way for using the
-     commands below.  (Selecting that window in the usual ways has the
-     same effect, but this way is more convenient.)
-
-`<RET>'
-     Typing <RET> _in the completion list buffer_ chooses the
-     completion that point is in or next to (`choose-completion').  To
-     use this command, you must first switch windows to the window that
-     shows the list of completions.
-
-`<RIGHT>'
-`<TAB>'
-`C-f'
-     Typing the right-arrow key <RIGHT>, <TAB> or `C-f' _in the
-     completion list buffer_ moves point to the following completion
-     (`next-list-mode-item').
-
-`<LEFT>'
-`C-b'
-     Typing the left-arrow key <LEFT> or `C-b' _in the completion list
-     buffer_ moves point toward the beginning of the buffer, to the
-     previous completion (`previous-list-mode-item').
-
-\1f
-File: xemacs.info,  Node: Strict Completion,  Next: Completion Options,  Prev: Completion Commands,  Up: Completion
-
-Strict Completion
------------------
-
-   There are three different ways that <RET> can work in completing
-minibuffers, depending on how the argument will be used.
-
-   * "Strict" completion is used when it is meaningless to give any
-     argument except one of the known alternatives.  For example, when
-     `C-x k' reads the name of a buffer to kill, it is meaningless to
-     give anything but the name of an existing buffer.  In strict
-     completion, <RET> refuses to exit if the text in the minibuffer
-     does not complete to an exact match.
-
-   * "Cautious" completion is similar to strict completion, except that
-     <RET> exits only if the text was an exact match already, not
-     needing completion.  If the text is not an exact match, <RET> does
-     not exit, but it does complete the text.  If it completes to an
-     exact match, a second <RET> will exit.
-
-     Cautious completion is used for reading file names for files that
-     must already exist.
-
-   * "Permissive" completion is used when any string whatever is
-     meaningful, and the list of completion alternatives is just a
-     guide.  For example, when `C-x C-f' reads the name of a file to
-     visit, any file name is allowed, in case you want to create a
-     file.  In permissive completion, <RET> takes the text in the
-     minibuffer exactly as given, without completing it.
-
-   The completion commands display a list of all possible completions in
-a window whenever there is more than one possibility for the very next
-character.  Also, typing `?' explicitly requests such a list.  If the
-list of completions is long, you can scroll it with `C-M-v' (*note
-Other Window::).
+File: xemacs.info,  Node: Manifesto,  Next: Key Index,  Prev: Glossary,  Up: Top
+
+The GNU Manifesto
+*****************
+
+What's GNU?  GNU's Not Unix!
+============================
+
+GNU, which stands for GNU's Not Unix, is the name for the complete
+Unix-compatible software system which I am writing so that I can give it
+away free to everyone who can use it.  Several other volunteers are
+helping me.  Contributions of time, money, programs, and equipment are
+greatly needed.
+
+   So far we have an Emacs text editor with Lisp for writing editor
+commands, a source level debugger, a yacc-compatible parser generator,
+a linker, and around 35 utilities.  A shell (command interpreter) is
+nearly completed.  A new portable optimizing C compiler has compiled
+itself and may be released this year.  An initial kernel exists, but
+many more features are needed to emulate Unix.  When the kernel and
+compiler are finished, it will be possible to distribute a GNU system
+suitable for program development.  We will use TeX as our text
+formatter, but an nroff is being worked on.  We will use the free,
+portable X window system as well.  After this we will add a portable
+Common Lisp, an Empire game, a spreadsheet, and hundreds of other
+things, plus online documentation.  We hope to supply, eventually,
+everything useful that normally comes with a Unix system, and more.
+
+   GNU will be able to run Unix programs, but will not be identical to
+Unix.  We will make all improvements that are convenient, based on our
+experience with other operating systems.  In particular, we plan to
+have longer filenames, file version numbers, a crashproof file system,
+filename completion perhaps, terminal-independent display support, and
+perhaps eventually a Lisp-based window system through which several
+Lisp programs and ordinary Unix programs can share a screen.  Both C
+and Lisp will be available as system programming languages.  We will
+try to support UUCP, MIT Chaosnet, and Internet protocols for
+communication.
+
+   GNU is aimed initially at machines in the 68000/16000 class with
+virtual memory, because they are the easiest machines to make it run
+on.  The extra effort to make it run on smaller machines will be left
+to someone who wants to use it on them.
+
+   To avoid horrible confusion, please pronounce the `G' in the word
+`GNU' when it is the name of this project.
+
+Why I Must Write GNU
+====================
+
+I consider that the golden rule requires that if I like a program I must
+share it with other people who like it.  Software sellers want to divide
+the users and conquer them, making each user agree not to share with
+others.  I refuse to break solidarity with other users in this way.  I
+cannot in good conscience sign a nondisclosure agreement or a software
+license agreement.  For years I worked within the Artificial
+Intelligence Lab to resist such tendencies and other inhospitalities,
+but eventually they had gone too far: I could not remain in an
+institution where such things are done for me against my will.
+
+   So that I can continue to use computers without dishonor, I have
+decided to put together a sufficient body of free software so that I
+will be able to get along without any software that is not free.  I
+have resigned from the AI lab to deny MIT any legal excuse to prevent
+me from giving GNU away.
+
+Why GNU Will Be Compatible With Unix
+====================================
+
+Unix is not my ideal system, but it is not too bad.  The essential
+features of Unix seem to be good ones, and I think I can fill in what
+Unix lacks without spoiling them.  And a system compatible with Unix
+would be convenient for many other people to adopt.
+
+How GNU Will Be Available
+=========================

 
 

-\1f
-File: xemacs.info,  Node: Completion Options,  Prev: Strict Completion,  Up: Completion
-
-Completion Options
-------------------
-
-   When completion is done on file names, certain file names are usually
-ignored.  The variable `completion-ignored-extensions' contains a list
-of strings; a file whose name ends in any of those strings is ignored
-as a possible completion.  The standard value of this variable has
-several elements including `".o"', `".elc"', `".dvi"' and `"~"'.  The
-effect is that, for example, `foo' can complete to `foo.c' even though
-`foo.o' exists as well.  However, if _all_ the possible completions end
-in "ignored" strings, then they are not ignored.  Ignored extensions do
-not apply to lists of completions--those always mention all possible
-completions.
-
-   If a completion command finds the next character is undetermined, it
-automatically displays a list of all possible completions.  If the
-variable `completion-auto-help' is set to `nil', this does not happen,
-and you must type `?' to display the possible completions.
-
-   If the variable `minibuffer-confirm-incomplete' is set to `t', then
-in contexts where `completing-read' allows answers that are not valid
-completions, an extra <RET> must be typed to confirm the response.
-This is helpful for catching typos.
-
-   Icomplete mode presents a constantly-updated display that tells you
-what completions are available for the text you've entered so far.  The
-command to enable or disable this minor mode is `M-x icomplete-mode'.
+GNU is not in the public domain.  Everyone will be permitted to modify
+and redistribute GNU, but no distributor will be allowed to restrict its
+further redistribution.  That is to say, proprietary modifications will
+not be allowed.  I want to make sure that all versions of GNU remain
+free.
+
+Why Many Other Programmers Want to Help
+=======================================
+
+I have found many other programmers who are excited about GNU and want
+to help.
+
+   Many programmers are unhappy about the commercialization of system
+software.  It may enable them to make more money, but it requires them
+to feel in conflict with other programmers in general rather than feel
+as comrades.  The fundamental act of friendship among programmers is the
+sharing of programs; marketing arrangements now typically used
+essentially forbid programmers to treat others as friends.  The
+purchaser of software must choose between friendship and obeying the
+law.  Naturally, many decide that friendship is more important.  But
+those who believe in law often do not feel at ease with either choice.
+They become cynical and think that programming is just a way of making
+money.
+
+   By working on and using GNU rather than proprietary programs, we can
+be hospitable to everyone and obey the law.  In addition, GNU serves as
+an example to inspire and a banner to rally others to join us in
+sharing.  This can give us a feeling of harmony which is impossible if
+we use software that is not free.  For about half the programmers I
+talk to, this is an important happiness that money cannot replace.
+
+How You Can Contribute
+======================
+
+I am asking computer manufacturers for donations of machines and money.
+I'm asking individuals for donations of programs and work.
+
+   One consequence you can expect if you donate machines is that GNU
+will run on them at an early date.  The machines should be complete,
+ready-to-use systems, approved for use in a residential area, and not
+in need of sophisticated cooling or power.
+
+   I have found very many programmers eager to contribute part-time
+work for GNU.  For most projects, such part-time distributed work would
+be very hard to coordinate; the independently-written parts would not
+work together.  But for the particular task of replacing Unix, this
+problem is absent.  A complete Unix system contains hundreds of utility
+programs, each of which is documented separately.  Most interface
+specifications are fixed by Unix compatibility.  If each contributor
+can write a compatible replacement for a single Unix utility, and make
+it work properly in place of the original on a Unix system, then these
+utilities will work right when put together.  Even allowing for Murphy
+to create a few unexpected problems, assembling these components will
+be a feasible task.  (The kernel will require closer communication and
+will be worked on by a small, tight group.)
+
+   If I get donations of money, I may be able to hire a few people full
+or part time.  The salary won't be high by programmers' standards, but
+I'm looking for people for whom building community spirit is as
+important as making money.  I view this as a way of enabling dedicated
+people to devote their full energies to working on GNU by sparing them
+the need to make a living in another way.
+
+Why All Computer Users Will Benefit
+===================================
+
+Once GNU is written, everyone will be able to obtain good system
+software free, just like air.
+
+   This means much more than just saving everyone the price of a Unix
+license.  It means that much wasteful duplication of system programming
+effort will be avoided.  This effort can go instead into advancing the
+state of the art.
+
+   Complete system sources will be available to everyone.  As a result,
+a user who needs changes in the system will always be free to make them
+himself, or hire any available programmer or company to make them for
+him.  Users will no longer be at the mercy of one programmer or company
+which owns the sources and is in sole position to make changes.
+
+   Schools will be able to provide a much more educational environment
+by encouraging all students to study and improve the system code.
+Harvard's computer lab used to have the policy that no program could be
+installed on the system if its sources were not on public display, and
+upheld it by actually refusing to install certain programs.  I was very
+much inspired by this.
+
+   Finally, the overhead of considering who owns the system software
+and what one is or is not entitled to do with it will be lifted.
+
+   Arrangements to make people pay for using a program, including
+licensing of copies, always incur a tremendous cost to society through
+the cumbersome mechanisms necessary to figure out how much (that is,
+which programs) a person must pay for.  And only a police state can
+force everyone to obey them.  Consider a space station where air must
+be manufactured at great cost: charging each breather per liter of air
+may be fair, but wearing the metered gas mask all day and all night is
+intolerable even if everyone can afford to pay the air bill.  And the
+TV cameras everywhere to see if you ever take the mask off are
+outrageous.  It's better to support the air plant with a head tax and
+chuck the masks.
+
+   Copying all or parts of a program is as natural to a programmer as
+breathing, and as productive.  It ought to be as free.
+
+Some Easily Rebutted Objections to GNU's Goals
+==============================================
+
+     "Nobody will use it if it is free, because that means they can't
+     rely on any support."
+
+     "You have to charge for the program to pay for providing the
+     support."
+
+   If people would rather pay for GNU plus service than get GNU free
+without service, a company to provide just service to people who have
+obtained GNU free ought to be profitable.
+
+   We must distinguish between support in the form of real programming
+work and mere handholding.  The former is something one cannot rely on
+from a software vendor.  If your problem is not shared by enough
+people, the vendor will tell you to get lost.
+
+   If your business needs to be able to rely on support, the only way
+is to have all the necessary sources and tools.  Then you can hire any
+available person to fix your problem; you are not at the mercy of any
+individual.  With Unix, the price of sources puts this out of
+consideration for most businesses.  With GNU this will be easy.  It is
+still possible for there to be no available competent person, but this
+problem cannot be blamed on distribution arrangements.  GNU does not
+eliminate all the world's problems, only some of them.
+
+   Meanwhile, the users who know nothing about computers need
+handholding: doing things for them which they could easily do
+themselves but don't know how.
+
+   Such services could be provided by companies that sell just
+hand-holding and repair service.  If it is true that users would rather
+spend money and get a product with service, they will also be willing
+to buy the service having got the product free.  The service companies
+will compete in quality and price; users will not be tied to any
+particular one.  Meanwhile, those of us who don't need the service
+should be able to use the program without paying for the service.
+
+     "You cannot reach many people without advertising, and you must
+     charge for the program to support that."
+
+     "It's no use advertising a program people can get free."
+
+   There are various forms of free or very cheap publicity that can be
+used to inform numbers of computer users about something like GNU.  But
+it may be true that one can reach more microcomputer users with
+advertising.  If this is really so, a business which advertises the
+service of copying and mailing GNU for a fee ought to be successful
+enough to pay for its advertising and more.  This way, only the users
+who benefit from the advertising pay for it.
+
+   On the other hand, if many people get GNU from their friends, and
+such companies don't succeed, this will show that advertising was not
+really necessary to spread GNU.  Why is it that free market advocates
+don't want to let the free market decide this?
+
+     "My company needs a proprietary operating system to get a
+     competitive edge."
+
+   GNU will remove operating system software from the realm of
+competition.  You will not be able to get an edge in this area, but
+neither will your competitors be able to get an edge over you.  You and
+they will compete in other areas, while benefitting mutually in this
+one.  If your business is selling an operating system, you will not
+like GNU, but that's tough on you.  If your business is something else,
+GNU can save you from being pushed into the expensive business of
+selling operating systems.
+
+   I would like to see GNU development supported by gifts from many
+manufacturers and users, reducing the cost to each.
+
+     "Don't programmers deserve a reward for their creativity?"
+
+   If anything deserves a reward, it is social contribution.
+Creativity can be a social contribution, but only in so far as society
+is free to use the results.  If programmers deserve to be rewarded for
+creating innovative programs, by the same token they deserve to be
+punished if they restrict the use of these programs.
+
+     "Shouldn't a programmer be able to ask for a reward for his
+     creativity?"
+
+   There is nothing wrong with wanting pay for work, or seeking to
+maximize one's income, as long as one does not use means that are
+destructive.  But the means customary in the field of software today
+are based on destruction.
+
+   Extracting money from users of a program by restricting their use of
+it is destructive because the restrictions reduce the amount and the
+ways that the program can be used.  This reduces the amount of wealth
+that humanity derives from the program.  When there is a deliberate
+choice to restrict, the harmful consequences are deliberate destruction.
+
+   The reason a good citizen does not use such destructive means to
+become wealthier is that, if everyone did so, we would all become
+poorer from the mutual destructiveness.  This is Kantian ethics; or,
+the Golden Rule.  Since I do not like the consequences that result if
+everyone hoards information, I am required to consider it wrong for one
+to do so.  Specifically, the desire to be rewarded for one's creativity
+does not justify depriving the world in general of all or part of that
+creativity.
+
+     "Won't programmers starve?"
+
+   I could answer that nobody is forced to be a programmer.  Most of us
+cannot manage to get any money for standing on the street and making
+faces.  But we are not, as a result, condemned to spend our lives
+standing on the street making faces, and starving.  We do something
+else.
+
+   But that is the wrong answer because it accepts the questioner's
+implicit assumption: that without ownership of software, programmers
+cannot possibly be paid a cent.  Supposedly it is all or nothing.
+
+   The real reason programmers will not starve is that it will still be
+possible for them to get paid for programming; just not paid as much as
+now.
+
+   Restricting copying is not the only basis for business in software.
+It is the most common basis because it brings in the most money.  If it
+were prohibited, or rejected by the customer, software business would
+move to other bases of organization which are now used less often.
+There are always numerous ways to organize any kind of business.
+
+   Probably programming will not be as lucrative on the new basis as it
+is now.  But that is not an argument against the change.  It is not
+considered an injustice that sales clerks make the salaries that they
+now do.  If programmers made the same, that would not be an injustice
+either.  (In practice they would still make considerably more than
+that.)
+
+     "Don't people have a right to control how their creativity is
+     used?"
+
+   "Control over the use of one's ideas" really constitutes control over
+other people's lives; and it is usually used to make their lives more
+difficult.
+
+   People who have studied the issue of intellectual property rights
+carefully (such as lawyers) say that there is no intrinsic right to
+intellectual property.  The kinds of supposed intellectual property
+rights that the government recognizes were created by specific acts of
+legislation for specific purposes.
+
+   For example, the patent system was established to encourage
+inventors to disclose the details of their inventions.  Its purpose was
+to help society rather than to help inventors.  At the time, the life
+span of 17 years for a patent was short compared with the rate of
+advance of the state of the art.  Since patents are an issue only among
+manufacturers, for whom the cost and effort of a license agreement are
+small compared with setting up production, the patents often do not do
+much harm.  They do not obstruct most individuals who use patented
+products.
+
+   The idea of copyright did not exist in ancient times, when authors
+frequently copied other authors at length in works of non-fiction.  This
+practice was useful, and is the only way many authors' works have
+survived even in part.  The copyright system was created expressly for
+the purpose of encouraging authorship.  In the domain for which it was
+invented--books, which could be copied economically only on a printing
+press--it did little harm, and did not obstruct most of the individuals
+who read the books.
+
+   All intellectual property rights are just licenses granted by society
+because it was thought, rightly or wrongly, that society as a whole
+would benefit by granting them.  But in any particular situation, we
+have to ask: are we really better off granting such license?  What kind
+of act are we licensing a person to do?
+
+   The case of programs today is very different from that of books a
+hundred years ago.  The fact that the easiest way to copy a program is
+from one neighbor to another, the fact that a program has both source
+code and object code which are distinct, and the fact that a program is
+used rather than read and enjoyed, combine to create a situation in
+which a person who enforces a copyright is harming society as a whole
+both materially and spiritually; in which a person should not do so
+regardless of whether the law enables him to.
+
+     "Competition makes things get done better."
+
+   The paradigm of competition is a race: by rewarding the winner, we
+encourage everyone to run faster.  When capitalism really works this
+way, it does a good job; but its defenders are wrong in assuming it
+always works this way.  If the runners forget why the reward is offered
+and become intent on winning, no matter how, they may find other
+strategies--such as, attacking other runners.  If the runners get into
+a fist fight, they will all finish late.
+
+   Proprietary and secret software is the moral equivalent of runners
+in a fist fight.  Sad to say, the only referee we've got does not seem
+to object to fights; he just regulates them ("For every ten yards you
+run, you can fire one shot").  He really ought to break them up, and
+penalize runners for even trying to fight.
+
+     "Won't everyone stop programming without a monetary incentive?"
+
+   Actually, many people will program with absolutely no monetary
+incentive.  Programming has an irresistible fascination for some
+people, usually the people who are best at it.  There is no shortage of
+professional musicians who keep at it even though they have no hope of
+making a living that way.
+
+   But really this question, though commonly asked, is not appropriate
+to the situation.  Pay for programmers will not disappear, only become
+less.  So the right question is, will anyone program with a reduced
+monetary incentive?  My experience shows that they will.
+
+   For more than ten years, many of the world's best programmers worked
+at the Artificial Intelligence Lab for far less money than they could
+have had anywhere else.  They got many kinds of non-monetary rewards:
+fame and appreciation, for example.  And creativity is also fun, a
+reward in itself.
+
+   Then most of them left when offered a chance to do the same
+interesting work for a lot of money.
+
+   What the facts show is that people will program for reasons other
+than riches; but if given a chance to make a lot of money as well, they
+will come to expect and demand it.  Low-paying organizations do poorly
+in competition with high-paying ones, but they do not have to do badly
+if the high-paying ones are banned.
+
+     "We need the programmers desperately.  If they demand that we stop
+     helping our neighbors, we have to obey."
+
+   You're never so desperate that you have to obey this sort of demand.
+Remember: millions for defense, but not a cent for tribute!
+
+     "Programmers need to make a living somehow."
+
+   In the short run, this is true.  However, there are plenty of ways
+that programmers could make a living without selling the right to use a
+program.  This way is customary now because it brings programmers and
+businessmen the most money, not because it is the only way to make a
+living.  It is easy to find other ways if you want to find them.  Here
+are a number of examples.
+
+   A manufacturer introducing a new computer will pay for the porting of
+operating systems onto the new hardware.
+
+   The sale of teaching, hand-holding, and maintenance services could
+also employ programmers.
+
+   People with new ideas could distribute programs as freeware and ask
+for donations from satisfied users or sell hand-holding services.  I
+have met people who are already working this way successfully.
+
+   Users with related needs can form users' groups and pay dues.  A
+group would contract with programming companies to write programs that
+the group's members would like to use.
+
+   All sorts of development can be funded with a Software Tax:
+
+     Suppose everyone who buys a computer has to pay a certain percent
+     of the price as a software tax.  The government gives this to an
+     agency like the NSF to spend on software development.
+
+     But if the computer buyer makes a donation to software development
+     himself, he can take a credit against the tax.  He can donate to
+     the project of his own choosing--often, chosen because he hopes to
+     use the results when
+
+     it is done.  He can take a credit for any amount of donation up to
+     the total tax he had to pay.
+
+     The total tax rate could be decided by a vote of the payers of the
+     tax, weighted according to the amount they will be taxed on.
+
+     The consequences:
+
+        * The computer-using community supports software development.
+
+        * This community decides what level of support is needed.
+
+        * Users who care which projects their share is spent on can
+          choose this for themselves.

 
 

-\1f
-File: xemacs.info,  Node: Minibuffer History,  Next: Repetition,  Prev: Completion,  Up: Minibuffer
-
-Minibuffer History
-==================
-
-   Every argument that you enter with the minibuffer is saved on a
-"minibuffer history list" so that you can use it again later in another
-argument.  Special commands load the text of an earlier argument in the
-minibuffer.  They discard the old minibuffer contents, so you can think
-of them as moving through the history of previous arguments.
-
-`<UP>'
-`M-p'
-     Move to the next earlier argument string saved in the minibuffer
-     history (`previous-history-element').
-
-`<DOWN>'
-`M-n'
-     Move to the next later argument string saved in the minibuffer
-     history (`next-history-element').
-
-`M-r REGEXP <RET>'
-     Move to an earlier saved argument in the minibuffer history that
-     has a match for REGEXP (`previous-matching-history-element').
-
-`M-s REGEXP <RET>'
-     Move to a later saved argument in the minibuffer history that has a
-     match for REGEXP (`next-matching-history-element').
-
-   The simplest way to reuse the saved arguments in the history list is
-to move through the history list one element at a time.  While in the
-minibuffer, use `M-p' or up-arrow (`previous-history-element') to "move
-to" the next earlier minibuffer input, and use `M-n' or down-arrow
-(`next-history-element') to "move to" the next later input.
-
-   The previous input that you fetch from the history entirely replaces
-the contents of the minibuffer.  To use it as the argument, exit the
-minibuffer as usual with <RET>.  You can also edit the text before you
-reuse it; this does not change the history element that you "moved" to,
-but your new argument does go at the end of the history list in its own
-right.
-
-   For many minibuffer arguments there is a "default" value.  In some
-cases, the minibuffer history commands know the default value.  Then you
-can insert the default value into the minibuffer as text by using `M-n'
-to move "into the future" in the history.
-
-   There are also commands to search forward or backward through the
-history; they search for history elements that match a regular
-expression that you specify with the minibuffer.  `M-r'
-(`previous-matching-history-element') searches older elements in the
-history, while `M-s' (`next-matching-history-element') searches newer
-elements.  By special dispensation, these commands can use the
-minibuffer to read their arguments even though you are already in the
-minibuffer when you issue them.  As with incremental searching, an
-uppercase letter in the regular expression makes the search
-case-sensitive (*note Search Case::).
-
-   All uses of the minibuffer record your input on a history list, but
-there are separate history lists for different kinds of arguments.  For
-example, there is a list for file names, used by all the commands that
-read file names.
-
-   There are several other very specific history lists, including one
-for command names read by `M-x', one for buffer names, one for arguments
-of commands like `query-replace', and one for compilation commands read
-by `compile'.  Finally, there is one "miscellaneous" history list that
-most minibuffer arguments use.
+   In the long run, making programs free is a step toward the
+post-scarcity world, where nobody will have to work very hard just to
+make a living.  People will be free to devote themselves to activities
+that are fun, such as programming, after spending the necessary ten
+hours a week on required tasks such as legislation, family counseling,
+robot repair, and asteroid prospecting.  There will be no need to be
+able to make a living from programming.

 
 

-\1f
-File: xemacs.info,  Node: Repetition,  Prev: Minibuffer History,  Up: Minibuffer
-
-Repeating Minibuffer Commands
-=============================
-
-   Every command that uses the minibuffer at least once is recorded on a
-special history list, together with the values of its arguments, so that
-you can repeat the entire command.  In particular, every use of `M-x'
-is recorded there, since `M-x' uses the minibuffer to read the command
-name.
-
-`C-x <ESC> <ESC>'
-     Re-execute a recent minibuffer command (`repeat-complex-command').
-
-`M-p'
-     Within `C-x <ESC> <ESC>', move to previous recorded command
-     (`previous-history-element').
-
-`M-n'
-     Within `C-x <ESC> <ESC>', move to the next (more recent) recorded
-     command (`next-history-element').
-
-`M-x list-command-history'
-     Display the entire command history, showing all the commands `C-x
-     <ESC> <ESC>' can repeat, most recent first.
-
-   `C-x <ESC> <ESC>' is used to re-execute a recent minibuffer-using
-command.  With no argument, it repeats the last such command.  A
-numeric argument specifies which command to repeat; one means the last
-one, and larger numbers specify earlier ones.
-
-   `C-x <ESC> <ESC>' works by turning the previous command into a Lisp
-expression and then entering a minibuffer initialized with the text for
-that expression.  If you type just <RET>, the command is repeated as
-before.  You can also change the command by editing the Lisp
-expression.  Whatever expression you finally submit is what will be
-executed.  The repeated command is added to the front of the command
-history unless it is identical to the most recently executed command
-already there.
-
-   Even if you don't understand Lisp syntax, it will probably be obvious
-which command is displayed for repetition.  If you do not change the
-text, you can be sure the command will repeat exactly as before.
-
-   If you are in the minibuffer for `C-x <ESC> <ESC>' and the command
-shown to you is not the one you want to repeat, you can move around the
-list of previous commands using `M-n' and `M-p'.  `M-p' replaces the
-contents of the minibuffer with the next earlier recorded command, and
-`M-n' replaces it with the next later command.  After finding the
-desired previous command, you can edit its expression and then resubmit
-it by typing <RET>.  Any editing you have done on the command to be
-repeated is lost if you use `M-n' or `M-p'.
-
-   `M-n' and `M-p' are specially defined within `C-x <ESC> <ESC>' to
-run the commands `previous-history-element' and `next-history-element'.
-
-   The list of previous commands using the minibuffer is stored as a
-Lisp list in the variable `command-history'.  Each element of the list
-is a Lisp expression which describes one command and its arguments.
-Lisp programs can reexecute a command by feeding the corresponding
-`command-history' element to `eval'.
+   We have already greatly reduced the amount of work that the whole
+society must do for its actual productivity, but only a little of this
+has translated itself into leisure for workers because much
+nonproductive activity is required to accompany productive activity.
+The main causes of this are bureaucracy and isometric struggles against
+competition.  Free software will greatly reduce these drains in the
+area of software production.  We must do this, in order for technical
+gains in productivity to translate into less work for us.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: M-x,  Next: Help,  Prev: Minibuffer,  Up: Top
-
-Running Commands by Name
-************************
-
-   The Emacs commands that are used often or that must be quick to type
-are bound to keys--short sequences of characters--for convenient use.
-Other Emacs commands that are used more rarely are not bound to keys;
-to run them, you must refer to them by name.
-
-   A command name consists, by convention, of one or more words,
-separated by hyphens: for example, `auto-fill-mode' or `manual-entry'.
-The use of English words makes the command name easier to remember than
-a key made up of obscure characters, even though it results in more
-characters to type.  You can run any command by name, even if it can be
-run by keys as well.
+File: xemacs.info,  Node: Key Index,  Next: Command Index,  Prev: Manifesto,  Up: Top

 
 

-   To run a command by name, start with `M-x', then type the command
-name, and finish with <RET>.  `M-x' uses the minibuffer to read the
-command name.  <RET> exits the minibuffer and runs the command.
+Key (Character) Index
+*********************

 
 

-   Emacs uses the minibuffer for reading input for many different
-purposes; on this occasion, the string `M-x' is displayed at the
-beginning of the minibuffer as a "prompt" to remind you that your input
-should be the name of a command to be run.  *Note Minibuffer::, for
-full information on the features of the minibuffer.
-
-   You can use completion to enter a command name.  For example, to
-invoke the command `forward-char', type:
-
-     M-x forward-char <RET>
-   or
-     M-x fo <TAB> c <RET>
-
-After you type in `M-x fo TAB' emacs will give you a possible list of
-completions from which you can choose. Note that `forward-char' is the
-same command that you invoke with the key `C-f'.  You can call any
-command (interactively callable function) defined in Emacs by its name
-using `M-x' regardless of whether or not any keys are bound to it.
-
-   If you type `C-g' while Emacs reads the command name, you cancel the
-`M-x' command and get out of the minibuffer, ending up at top level.
-
-   To pass a numeric argument to a command you are invoking with `M-x',
-specify the numeric argument before the `M-x'.  `M-x' passes the
-argument along to the function that it calls.  The argument value
-appears in the prompt while the command name is being read.
-
-   You can use the command `M-x interactive' to specify a way of
-parsing arguments for interactive use of a function.  For example,
-write:
-
-       (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
-
-   to make `arg' be the prefix argument when `foo' is called as a
-command.  The call to `interactive' is actually a declaration rather
-than a function; it tells `call-interactively' how to read arguments to
-pass to the function.  When actually called, `interactive' returns
-`nil'.
-
-   The argument of INTERACTIVE is usually a string containing a code
-letter followed by a prompt.  Some code letters do not use I/O to get
-the argument and do not need prompts.  To prompt for multiple arguments,
-you must provide a code letter, its prompt, a newline, and another code
-letter, and so forth.  If the argument is not a string, it is evaluated
-to get a list of arguments to pass to the function.  If you do not
-provide an argument to `interactive', no arguments are passed when
-calling interactively.
-
-   Available code letters are:
-
-`a'
-     Function name: symbol with a function definition
-
-`b'
-     Name of existing buffer
-
-`B'
-     Name of buffer, possibly nonexistent
-
-`c'
-     Character
-
-`C'
-     Command name: symbol with interactive function definition
-
-`d'
-     Value of point as number (does not do I/O)
-
-`D'
-     Directory name
-
-`e'
-     Last mouse event
-
-`f'
-     Existing file name
-
-`F'
-     Possibly nonexistent file name
-
-`k'
-     Key sequence (string)
-
-`m'
-     Value of mark as number (does not do I/O)
-
-`n'
-     Number read using minibuffer
-
-`N'
-     Prefix arg converted to number, or if none, do like code `n'
-
-`p'
-     Prefix arg converted to number (does not do I/O)
-
-`P'
-     Prefix arg in raw form (does not do I/O)
-
-`r'
-     Region: point and mark as two numeric arguments, smallest first
-     (does not do I/O)
-
-`s'
-     Any string
-
-`S'
-     Any symbol
-
-`v'
-     Variable name: symbol that is `user-variable-p'
-
-`x'
-     Lisp expression read but not evaluated
-
-`X'
-     Lisp expression read and evaluated
-
-   In addition, if the string begins with `*', an error is signaled if
-the buffer is read-only.  This happens before reading any arguments.
-If the string begins with `@', the window the mouse is over is selected
-before anything else is done.  You may use both `@' and `*'; they are
-processed in the order that they appear.
-
-   Normally, when describing a command that is run by name, we omit the
-<RET> that is needed to terminate the name.  Thus we may refer to `M-x
-auto-fill-mode' rather than `M-x auto-fill-mode' <RET>.  We mention the
-<RET> only when it is necessary to emphasize its presence, for example,
-when describing a sequence of input that contains a command name and
-arguments that follow it.
+* Menu:

 
 

-   `M-x' is defined to run the command `execute-extended-command',
-which is responsible for reading the name of another command and
-invoking it.
+* ! (query-replace):                     Query Replace.
+* " (TeX mode):                          TeX Editing.
+* , (query-replace):                     Query Replace.
+* . (Calendar mode):                     Specified Dates.
+* . (query-replace):                     Query Replace.
+* ? (Calendar mode):                     General Calendar.
+* ^ (query-replace):                     Query Replace.
+* a (Calendar mode):                     Holidays.
+* BS:                                    Inserting Text.
+* button1:                               Intro to Keystrokes.
+* button1up:                             Intro to Keystrokes.
+* button2:                               Intro to Keystrokes.
+* button2up:                             Intro to Keystrokes.
+* button3:                               Intro to Keystrokes.
+* button3up:                             Intro to Keystrokes.
+* C-<:                                   Setting Mark.
+* C->:                                   Setting Mark.
+* C-@ (Calendar mode):                   Mark and Region.
+* C-\:                                   Select Input Method.
+* C-] <1>:                               Quitting.
+* C-]:                                   Recursive Edit.
+* C-_:                                   Undo.
+* C-a:                                   Moving Point.
+* C-a (Calendar mode):                   Move to Beginning or End.
+* C-b:                                   Moving Point.
+* C-b (Calendar mode):                   Calendar Unit Motion.
+* C-c:                                   Key Sequences.
+* C-c ' (Picture mode):                  Insert in Picture.
+* C-c . (Picture mode):                  Insert in Picture.
+* C-c / (Picture mode):                  Insert in Picture.
+* C-c ; (Fortran mode):                  Fortran Comments.
+* C-c < (Picture mode):                  Insert in Picture.
+* C-c > (Picture mode):                  Insert in Picture.
+* C-c \ (Picture mode):                  Insert in Picture.
+* C-c ^ (Picture mode):                  Insert in Picture.
+* C-c ` (Picture mode):                  Insert in Picture.
+* C-c C-\ (Shell mode):                  Shell Mode.
+* C-c C-b (Outline mode):                Outline Motion.
+* C-c C-b (Picture mode):                Insert in Picture.
+* C-c C-b (TeX mode):                    TeX Print.
+* C-c C-c (Edit Abbrevs):                Editing Abbrevs.
+* C-c C-c (Edit Tab Stops):              Tab Stops.
+* C-c C-c (Mail mode):                   Mail Mode.
+* C-c C-c (Occur mode):                  Other Repeating Search.
+* C-c C-c (Shell mode):                  Shell Mode.
+* C-c C-d (Outline mode):                Outline Visibility.
+* C-c C-d (Picture mode):                Basic Picture.
+* C-c C-d (Shell mode):                  Shell Mode.
+* C-c C-f (LaTeX mode):                  TeX Editing.
+* C-c C-f (Outline mode):                Outline Motion.
+* C-c C-f (Picture mode):                Insert in Picture.
+* C-c C-f C-c (Mail mode):               Mail Mode.
+* C-c C-f C-s (Mail mode):               Mail Mode.
+* C-c C-f C-t (Mail mode):               Mail Mode.
+* C-c C-h (Outline mode):                Outline Visibility.
+* C-c C-i (Outline mode):                Outline Visibility.
+* C-c C-j (Term mode):                   Term Mode.
+* C-c C-k (Picture mode):                Rectangles in Picture.
+* C-c C-k (Term mode):                   Term Mode.
+* C-c C-k (TeX mode):                    TeX Print.
+* C-c C-l (Calendar mode):               General Calendar.
+* C-c C-l (TeX mode):                    TeX Print.
+* C-c C-n (Fortran mode):                Fortran Motion.
+* C-c C-n (Outline mode):                Outline Motion.
+* C-c C-o (Shell mode):                  Shell Mode.
+* C-c C-p (Fortran mode):                Fortran Motion.
+* C-c C-p (Outline mode):                Outline Motion.
+* C-c C-p (TeX mode):                    TeX Print.
+* C-c C-q (Mail mode):                   Mail Mode.
+* C-c C-q (Term mode):                   Paging in Term.
+* C-c C-q (TeX mode):                    TeX Print.
+* C-c C-r (Fortran mode):                Fortran Columns.
+* C-c C-r (Shell mode):                  Shell Mode.
+* C-c C-r (TeX mode):                    TeX Print.
+* C-c C-s (Mail mode):                   Mail Mode.
+* C-c C-u (Outline mode):                Outline Motion.
+* C-c C-u (Shell mode):                  Shell Mode.
+* C-c C-w (Fortran mode):                Fortran Columns.
+* C-c C-w (Mail mode):                   Mail Mode.
+* C-c C-w (Picture mode):                Rectangles in Picture.
+* C-c C-w (Shell mode):                  Shell Mode.
+* C-c C-x (Picture mode):                Rectangles in Picture.
+* C-c C-y (Mail mode):                   Mail Mode.
+* C-c C-y (Picture mode):                Rectangles in Picture.
+* C-c C-y (Shell mode):                  Shell Mode.
+* C-c C-z (Shell mode):                  Shell Mode.
+* C-c TAB (Picture mode):                Tabs in Picture.
+* C-c { (TeX mode):                      TeX Editing.
+* C-c } (TeX mode):                      TeX Editing.
+* C-d:                                   Killing.
+* C-d (Shell mode):                      Shell Mode.
+* C-e:                                   Moving Point.
+* C-e (Calendar mode):                   Move to Beginning or End.
+* C-END:                                 Moving Point.
+* C-f:                                   Moving Point.
+* C-f (Calendar mode):                   Calendar Unit Motion.
+* C-g <1>:                               Quitting.
+* C-g:                                   Minibuffer.
+* C-g (isearch-mode):                    Incremental Search.
+* C-h <1>:                               Help.
+* C-h:                                   Key Sequences.
+* C-h A:                                 Apropos.
+* C-h b:                                 Misc Help.
+* C-h c:                                 Key Help.
+* C-h C-\:                               Select Input Method.
+* C-h C-c:                               Misc Help.
+* C-h C-d:                               Misc Help.
+* C-h C-f:                               Misc Help.
+* C-h C-h:                               Help.
+* C-h C-k:                               Misc Help.
+* C-h C-w:                               Misc Help.
+* C-h f:                                 Documentation.
+* C-h F:                                 Misc Help.
+* C-h f:                                 Name Help.
+* C-h h:                                 Mule Intro.
+* C-h I:                                 Select Input Method.
+* C-h i:                                 Misc Help.
+* C-h k:                                 Key Help.
+* C-h L:                                 Language Environments.
+* C-h l:                                 Misc Help.
+* C-h m:                                 Misc Help.
+* C-h n:                                 Misc Help.
+* C-h p:                                 Library Keywords.
+* C-h s:                                 Syntax Change.
+* C-h t <1>:                             Misc Help.
+* C-h t:                                 Basic.
+* C-h v <1>:                             Examining.
+* C-h v <2>:                             Documentation.
+* C-h v:                                 Name Help.
+* C-h w:                                 Name Help.
+* C-HOME:                                Moving Point.
+* C-k:                                   Killing.
+* C-l <1>:                               Scrolling.
+* C-l:                                   Moving Point.
+* C-l (query-replace):                   Query Replace.
+* C-LEFT:                                Moving Point.
+* C-M-@ <1>:                             Lists.
+* C-M-@:                                 Marking Objects.
+* C-M-\ <1>:                             Multi-line Indent.
+* C-M-\:                                 Indentation Commands.
+* C-M-a:                                 Defuns.
+* C-M-a (Fortran mode):                  Fortran Motion.
+* C-M-b:                                 Lists.
+* C-M-c:                                 Recursive Edit.
+* C-M-d:                                 Lists.
+* C-M-e:                                 Defuns.
+* C-M-e (Fortran mode):                  Fortran Motion.
+* C-M-f:                                 Lists.
+* C-M-h <1>:                             Defuns.
+* C-M-h:                                 Marking Objects.
+* C-M-h (Fortran mode):                  Fortran Motion.
+* C-M-k <1>:                             Lists.
+* C-M-k:                                 Killing.
+* C-M-n:                                 Lists.
+* C-M-o:                                 Indentation Commands.
+* C-M-p:                                 Lists.
+* C-M-q:                                 Multi-line Indent.
+* C-M-q (Fortran mode):                  ForIndent Commands.
+* C-M-t <1>:                             Lists.
+* C-M-t:                                 Transpose.
+* C-M-u:                                 Lists.
+* C-M-v <1>:                             Other Window.
+* C-M-v:                                 Minibuffer Edit.
+* C-M-w:                                 Appending Kills.
+* C-M-x <1>:                             External Lisp.
+* C-M-x:                                 Lisp Eval.
+* C-n:                                   Moving Point.
+* C-n (Calendar mode):                   Calendar Unit Motion.
+* C-o:                                   Blank Lines.
+* C-p:                                   Moving Point.
+* C-p (Calendar mode):                   Calendar Unit Motion.
+* C-q:                                   Inserting Text.
+* C-q (isearch-mode):                    Incremental Search.
+* C-r:                                   Incremental Search.
+* C-r (isearch-mode):                    Incremental Search.
+* C-r (query-replace):                   Query Replace.
+* C-RIGHT:                               Moving Point.
+* C-s:                                   Incremental Search.
+* C-s (isearch-mode):                    Incremental Search.
+* C-SPC:                                 Setting Mark.
+* C-SPC (Calendar mode):                 Mark and Region.
+* C-t <1>:                               Transpose.
+* C-t:                                   Moving Point.
+* C-u:                                   Arguments.
+* C-u - C-x ;:                           Comments.
+* C-u C-@:                               Mark Ring.
+* C-u C-SPC:                             Mark Ring.
+* C-u C-x v v:                           Editing with VC.
+* C-u TAB:                               Multi-line Indent.
+* C-v <1>:                               Scrolling.
+* C-v:                                   Moving Point.
+* C-v (Calendar mode):                   Scroll Calendar.
+* C-w:                                   Killing.
+* C-w (isearch-mode):                    Incremental Search.
+* C-w (query-replace):                   Query Replace.
+* C-x:                                   Key Sequences.
+* C-x $:                                 Selective Display.
+* C-x (:                                 Basic Kbd Macro.
+* C-x ):                                 Basic Kbd Macro.
+* C-x .:                                 Fill Prefix.
+* C-x 0:                                 Change Window.
+* C-x 1:                                 Change Window.
+* C-x 2:                                 Split Window.
+* C-x 3:                                 Split Window.
+* C-x 4:                                 Pop Up Window.
+* C-x 4 .:                               Find Tag.
+* C-x 4 b:                               Select Buffer.
+* C-x 4 d:                               Dired Enter.
+* C-x 4 f:                               Visiting.
+* C-x 4 m:                               Sending Mail.
+* C-x 5 b:                               Select Buffer.
+* C-x 5 C-f:                             Visiting.
+* C-x ;:                                 Comments.
+* C-x <:                                 Horizontal Scrolling.
+* C-x < (Calendar mode):                 Scroll Calendar.
+* C-x <RET> C:                           Coding Systems.
+* C-x =:                                 Position Info.
+* C-x >:                                 Horizontal Scrolling.
+* C-x > (Calendar mode):                 Scroll Calendar.
+* C-x [:                                 Pages.
+* C-x [ (Calendar mode):                 Calendar Unit Motion.
+* C-x ]:                                 Pages.
+* C-x ] (Calendar mode):                 Calendar Unit Motion.
+* C-x ^:                                 Change Window.
+* C-x `:                                 Compilation.
+* C-x a g:                               Defining Abbrevs.
+* C-x a i g:                             Defining Abbrevs.
+* C-x a i l:                             Defining Abbrevs.
+* C-x a l:                               Defining Abbrevs.
+* C-x b:                                 Select Buffer.
+* C-x C-b:                               List Buffers.
+* C-x C-c:                               Exiting.
+* C-x C-d:                               ListDir.
+* C-x C-e:                               Lisp Eval.
+* C-x C-l:                               Case.
+* C-x C-o <1>:                           Killing.
+* C-x C-o:                               Blank Lines.
+* C-x C-p <1>:                           Pages.
+* C-x C-p:                               Marking Objects.
+* C-x C-q:                               Misc Buffer.
+* C-x C-q (version control):             Editing with VC.
+* C-x C-s:                               Saving.
+* C-x C-t:                               Transpose.
+* C-x C-u:                               Case.
+* C-x C-v:                               Visiting.
+* C-x C-w:                               Saving.
+* C-x C-x:                               Setting Mark.
+* C-x C-x (Calendar mode):               Mark and Region.
+* C-x d:                                 Dired Enter.
+* C-x DEL <1>:                           Sentences.
+* C-x DEL <2>:                           Kill Errors.
+* C-x DEL:                               Killing.
+* C-x e:                                 Basic Kbd Macro.
+* C-x ESC ESC:                           Repetition.
+* C-x f:                                 Fill Commands.
+* C-x h:                                 Marking Objects.
+* C-x k:                                 Kill Buffer.
+* C-x l:                                 Pages.
+* C-x m:                                 Sending Mail.
+* C-x n n:                               Narrowing.
+* C-x n w:                               Narrowing.
+* C-x o:                                 Other Window.
+* C-x q:                                 Kbd Macro Query.
+* C-x r +:                               RegNumbers.
+* C-x r b:                               Bookmarks.
+* C-x r g:                               RegText.
+* C-x r i:                               RegText.
+* C-x r j:                               RegPos.
+* C-x r l:                               Bookmarks.
+* C-x r m:                               Bookmarks.
+* C-x r n:                               RegNumbers.
+* C-x r r:                               RegRect.
+* C-x r s:                               RegText.
+* C-x r SPC:                             RegPos.
+* C-x r w:                               RegConfig.
+* C-x RET:                               Mule Intro.
+* C-x RET c:                             Specify Coding.
+* C-x RET C-\:                           Select Input Method.
+* C-x RET f:                             Specify Coding.
+* C-x RET k:                             Specify Coding.
+* C-x RET p:                             Specify Coding.
+* C-x RET t:                             Specify Coding.
+* C-x s:                                 Saving.
+* C-x TAB:                               Indentation Commands.
+* C-x u:                                 Undo.
+* C-x v =:                               Old Versions.
+* C-x v a:                               Change Logs and VC.
+* C-x v c:                               Editing with VC.
+* C-x v d:                               VC Status.
+* C-x v h:                               Version Headers.
+* C-x v i:                               Editing with VC.
+* C-x v l:                               VC Status.
+* C-x v r:                               Making Snapshots.
+* C-x v s:                               Making Snapshots.
+* C-x v u:                               Editing with VC.
+* C-x v ~:                               Old Versions.
+* C-x }:                                 Change Window.
+* C-y:                                   Kill Ring.
+* C-y (isearch-mode):                    Incremental Search.
+* C-z:                                   Exiting.
+* control key:                           Intro to Keystrokes.
+* d (Calendar mode):                     Diary Commands.
+* DEL <1>:                               Program Modes.
+* DEL <2>:                               Major Modes.
+* DEL <3>:                               Kill Errors.
+* DEL:                                   Killing.
+* DEL (isearch-mode):                    Incremental Search.
+* DEL (query-replace):                   Query Replace.
+* DOWN:                                  Moving Point.
+* END:                                   Moving Point.
+* ESC <1>:                               Meta Key.
+* ESC:                                   Key Sequences.
+* ESC (query-replace):                   Query Replace.
+* F1:                                    Help.
+* g CHAR (Calendar mode):                From Other Calendar.
+* g d (Calendar mode):                   Specified Dates.
+* g m l (Calendar mode):                 Mayan Calendar.
+* h (Calendar mode):                     Holidays.
+* Help:                                  Help.
+* HOME:                                  Moving Point.
+* hyper key <1>:                         Super and Hyper Keys.
+* hyper key <2>:                         Representing Keystrokes.
+* hyper key:                             Intro to Keystrokes.
+* i a (Calendar mode):                   Special Diary Entries.
+* i b (Calendar mode):                   Special Diary Entries.
+* i c (Calendar mode):                   Special Diary Entries.
+* i d (Calendar mode):                   Adding to Diary.
+* i m (Calendar mode):                   Adding to Diary.
+* i w (Calendar mode):                   Adding to Diary.
+* i y (Calendar mode):                   Adding to Diary.
+* LEFT:                                  Moving Point.
+* LFD <1>:                               Basic Indent.
+* LFD <2>:                               Major Modes.
+* LFD:                                   String Key Sequences.
+* LFD (TeX mode):                        TeX Editing.
+* m (Calendar mode):                     Diary Commands.
+* M (Calendar mode):                     Lunar Phases.
+* M-!:                                   Single Shell.
+* M-$:                                   Spelling.
+* M-%:                                   Query Replace.
+* M-':                                   Expanding Abbrevs.
+* M-(:                                   Balanced Editing.
+* M-):                                   Balanced Editing.
+* M-,:                                   Tags Search.
+* M--:                                   Arguments.
+* M-- M-c:                               Fixing Case.
+* M-- M-l:                               Fixing Case.
+* M-- M-u:                               Fixing Case.
+* M-.:                                   Find Tag.
+* M-/:                                   Dynamic Abbrevs.
+* M-1:                                   Arguments.
+* M-::                                   Lisp Eval.
+* M-;:                                   Comments.
+* M-<:                                   Moving Point.
+* M-< (Calendar mode):                   Move to Beginning or End.
+* M-=:                                   Position Info.
+* M-= (Calendar mode):                   Mark and Region.
+* M->:                                   Moving Point.
+* M-> (Calendar mode):                   Move to Beginning or End.
+* M-?:                                   Nroff Mode.
+* M-@ <1>:                               Words.
+* M-@:                                   Marking Objects.
+* M-\ <1>:                               Indentation Commands.
+* M-\:                                   Killing.
+* M-^ <1>:                               Indentation Commands.
+* M-^:                                   Killing.
+* M-a:                                   Sentences.
+* M-a (Calendar mode):                   Move to Beginning or End.
+* M-b:                                   Words.
+* M-c:                                   Case.
+* M-C-r:                                 Regexp Search.
+* M-C-s:                                 Regexp Search.
+* M-d <1>:                               Words.
+* M-d:                                   Killing.
+* M-DEL <1>:                             Words.
+* M-DEL <2>:                             Kill Errors.
+* M-DEL:                                 Killing.
+* M-e:                                   Sentences.
+* M-e (Calendar mode):                   Move to Beginning or End.
+* M-f:                                   Words.
+* M-g:                                   Fill Commands.
+* M-h <1>:                               Paragraphs.
+* M-h:                                   Marking Objects.
+* M-i:                                   Tab Stops.
+* M-k <1>:                               Sentences.
+* M-k:                                   Killing.
+* M-l:                                   Case.
+* M-LFD:                                 Comments.
+* M-LFD (Fortran mode):                  ForIndent Commands.
+* M-m:                                   Indentation Commands.
+* M-n <1>:                               Nroff Mode.
+* M-n:                                   Repetition.
+* M-n (isearch-mode):                    Incremental Search.
+* M-n (minibuffer history):              Minibuffer History.
+* M-n (Shell mode):                      Shell Mode.
+* M-p <1>:                               Nroff Mode.
+* M-p:                                   Repetition.
+* M-p (isearch-mode):                    Incremental Search.
+* M-p (minibuffer history):              Minibuffer History.
+* M-p (Shell mode):                      Shell Mode.
+* M-q:                                   Fill Commands.
+* M-r:                                   Moving Point.
+* M-r (minibuffer history):              Minibuffer History.
+* M-s:                                   Fill Commands.
+* M-s (minibuffer history):              Minibuffer History.
+* M-SPC:                                 Killing.
+* M-t <1>:                               Words.
+* M-t:                                   Transpose.
+* M-TAB <1>:                             Tabs in Picture.
+* M-TAB:                                 Lisp Completion.
+* M-TAB (customization buffer):          Changing an Option.
+* M-TAB (isearch-mode):                  Incremental Search.
+* M-u:                                   Case.
+* M-v <1>:                               Scrolling.
+* M-v:                                   Moving Point.
+* M-v (Calendar mode):                   Scroll Calendar.
+* M-w:                                   Kill Ring.
+* M-x:                                   M-x.
+* M-y:                                   Earlier Kills.
+* M-z:                                   Killing.
+* M-{:                                   Paragraphs.
+* M-{ (Calendar mode):                   Calendar Unit Motion.
+* M-|:                                   Single Shell.
+* M-}:                                   Paragraphs.
+* M-} (Calendar mode):                   Calendar Unit Motion.
+* M-~:                                   Saving.
+* META:                                  Meta Key.
+* meta key:                              Intro to Keystrokes.
+* next:                                  Scrolling.
+* o (Calendar mode):                     Specified Dates.
+* p (Calendar mode):                     To Other Calendar.
+* p d (Calendar mode):                   General Calendar.
+* pgdn:                                  Scrolling.
+* PGDN:                                  Moving Point.
+* pgup:                                  Scrolling.
+* PGUP:                                  Moving Point.
+* prior:                                 Scrolling.
+* q (Calendar mode):                     General Calendar.
+* RET:                                   Inserting Text.
+* RET (isearch-mode):                    Incremental Search.
+* RET (Shell mode):                      Shell Mode.
+* RIGHT:                                 Moving Point.
+* s (Calendar mode):                     Diary Commands.
+* S (Calendar mode):                     Sunrise/Sunset.
+* S-TAB (customization buffer):          Changing an Option.
+* shift key:                             Intro to Keystrokes.
+* SPC:                                   Completion Commands.
+* SPC (Calendar mode):                   General Calendar.
+* SPC (query-replace):                   Query Replace.
+* super key <1>:                         Super and Hyper Keys.
+* super key <2>:                         Representing Keystrokes.
+* super key:                             Intro to Keystrokes.
+* t (Calendar mode):                     LaTeX Calendar.
+* TAB <1>:                               Basic Indent.
+* TAB <2>:                               Text Mode.
+* TAB <3>:                               Indentation.
+* TAB <4>:                               Major Modes.
+* TAB <5>:                               Completion Example.
+* TAB:                                   String Key Sequences.
+* TAB (customization buffer):            Changing an Option.
+* TAB (Shell mode):                      Shell Mode.
+* u (Calendar mode) <1>:                 Diary Commands.
+* u (Calendar mode):                     Holidays.
+* UP:                                    Moving Point.
+* x (Calendar mode):                     Holidays.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Help,  Next: Mark,  Prev: M-x,  Up: Top
+File: xemacs.info,  Node: Command Index,  Next: Variable Index,  Prev: Key Index,  Up: Top

 
 

-Help
-****
-
-   XEmacs provides extensive help features accessible through a single
-character, `C-h'.  `C-h' is a prefix key that is used only for
-documentation-printing commands.  The characters that you can type after
-`C-h' are called "help options".  One help option is `C-h'; that is how
-you ask for help about using `C-h'.  To cancel, type `C-g'.  The
-function key <F1> is equivalent to `C-h'.
-
-   `C-h C-h' (`help-for-help') displays a list of the possible help
-options, and then asks you to type the desired option.  It prompts with
-the string:
-
-     A B C F I K L M N P S T V W C-c C-d C-f C-i C-k C-n C-w;  ? for more help:
-
-You should type one of those characters.
-
-   Typing a third `C-h' displays a description of what the options mean;
-Emacs still waits for you to type an option.  To cancel, type `C-g'.
-
-   Most help buffers use a special major mode, Help mode, which lets you
-scroll conveniently with <SPC> and <DEL> or <BS>.
+Command and Function Index
+**************************

 
 * Menu:
 
 
 * Menu:
 

-* Help Summary::       Brief list of all Help commands.
-* Key Help::           Asking what a key does in XEmacs.
-* Name Help::          Asking about a command, variable or function name.
-* Apropos::            Asking what pertains to a given topic.
-* Library Keywords::   Finding Lisp libraries by keywords (topics).
-* Help Mode::           Special features of Help mode and Help buffers.
-* Misc Help::          Other help commands.
+* abbrev-mode <1>:                       Minor Modes.
+* abbrev-mode:                           Abbrevs.
+* abbrev-prefix-mark:                    Expanding Abbrevs.
+* abort-recursive-edit <1>:              Quitting.
+* abort-recursive-edit:                  Recursive Edit.
+* add-change-log-entry:                  Change Log.
+* add-global-abbrev:                     Defining Abbrevs.
+* add-menu:                              Menu Customization.
+* add-menu-item:                         Menu Customization.
+* add-mode-abbrev:                       Defining Abbrevs.
+* add-name-to-file:                      Misc File Ops.
+* american-calendar:                     Date Formats.
+* append-next-kill:                      Appending Kills.
+* append-to-buffer:                      Accumulating Text.
+* append-to-file <1>:                    Misc File Ops.
+* append-to-file:                        Accumulating Text.
+* apropos:                               Apropos.
+* apropos-documentation:                 Apropos.
+* apropos-value:                         Apropos.
+* ask-user-about-lock:                   Interlocking.
+* auto-fill-mode <1>:                    Minor Modes.
+* auto-fill-mode:                        Auto Fill.
+* auto-save-mode:                        Auto Save Control.
+* back-to-indentation:                   Indentation Commands.
+* backward-char:                         Moving Point.
+* backward-delete-char-untabify:         Program Modes.
+* backward-kill-sentence <1>:            Sentences.
+* backward-kill-sentence <2>:            Kill Errors.
+* backward-kill-sentence:                Killing.
+* backward-kill-word <1>:                Words.
+* backward-kill-word <2>:                Kill Errors.
+* backward-kill-word:                    Killing.
+* backward-list:                         Lists.
+* backward-or-forward-delete-char:       Inserting Text.
+* backward-page:                         Pages.
+* backward-paragraph:                    Paragraphs.
+* backward-sentence:                     Sentences.
+* backward-sexp:                         Lists.
+* backward-text-line:                    Nroff Mode.
+* backward-up-list:                      Lists.
+* backward-word:                         Words.
+* batch-byte-compile:                    Compiling Libraries.
+* beginning-of-buffer:                   Moving Point.
+* beginning-of-defun:                    Defuns.
+* beginning-of-fortran-subprogram:       Fortran Motion.
+* beginning-of-line:                     Moving Point.
+* bookmark-delete:                       Bookmarks.
+* bookmark-insert:                       Bookmarks.
+* bookmark-insert-location:              Bookmarks.
+* bookmark-jump:                         Bookmarks.
+* bookmark-load:                         Bookmarks.
+* bookmark-save:                         Bookmarks.
+* bookmark-set:                          Bookmarks.
+* bookmark-write:                        Bookmarks.
+* buffer-menu:                           Several Buffers.
+* byte-compile-and-load-file:            Compiling Libraries.
+* byte-compile-buffer:                   Compiling Libraries.
+* byte-compile-file:                     Compiling Libraries.
+* byte-recompile-directory:              Compiling Libraries.
+* c-indent-line:                         Basic Indent.
+* calendar:                              Calendar/Diary.
+* calendar-backward-day:                 Calendar Unit Motion.
+* calendar-backward-month:               Calendar Unit Motion.
+* calendar-backward-week:                Calendar Unit Motion.
+* calendar-beginning-of-month:           Move to Beginning or End.
+* calendar-beginning-of-week:            Move to Beginning or End.
+* calendar-beginning-of-year:            Move to Beginning or End.
+* calendar-count-days-region:            Mark and Region.
+* calendar-cursor-holidays:              Holidays.
+* calendar-end-of-month:                 Move to Beginning or End.
+* calendar-end-of-week:                  Move to Beginning or End.
+* calendar-end-of-year:                  Move to Beginning or End.
+* calendar-exchange-point-and-mark:      Mark and Region.
+* calendar-forward-day:                  Calendar Unit Motion.
+* calendar-forward-month:                Calendar Unit Motion.
+* calendar-forward-week:                 Calendar Unit Motion.
+* calendar-forward-year:                 Calendar Unit Motion.
+* calendar-goto-astro-day-number:        From Other Calendar.
+* calendar-goto-chinese-date:            From Other Calendar.
+* calendar-goto-coptic-date:             From Other Calendar.
+* calendar-goto-date:                    Specified Dates.
+* calendar-goto-ethiopic-date:           From Other Calendar.
+* calendar-goto-french-date:             From Other Calendar.
+* calendar-goto-hebrew-date:             From Other Calendar.
+* calendar-goto-islamic-date:            From Other Calendar.
+* calendar-goto-iso-date:                From Other Calendar.
+* calendar-goto-julian-date:             From Other Calendar.
+* calendar-goto-mayan-long-count-date:   Mayan Calendar.
+* calendar-goto-persian-date:            From Other Calendar.
+* calendar-goto-today:                   Specified Dates.
+* calendar-mark-today:                   Calendar Customizing.
+* calendar-next-calendar-round-date:     Mayan Calendar.
+* calendar-next-haab-date:               Mayan Calendar.
+* calendar-next-tzolkin-date:            Mayan Calendar.
+* calendar-other-month:                  Specified Dates.
+* calendar-phases-of-moon:               Lunar Phases.
+* calendar-previous-haab-date:           Mayan Calendar.
+* calendar-previous-tzolkin-date:        Mayan Calendar.
+* calendar-print-astro-day-number:       To Other Calendar.
+* calendar-print-chinese-date:           To Other Calendar.
+* calendar-print-coptic-date:            To Other Calendar.
+* calendar-print-day-of-year:            General Calendar.
+* calendar-print-ethiopic-date:          To Other Calendar.
+* calendar-print-french-date:            To Other Calendar.
+* calendar-print-hebrew-date:            To Other Calendar.
+* calendar-print-islamic-date:           To Other Calendar.
+* calendar-print-iso-date:               To Other Calendar.
+* calendar-print-julian-date:            To Other Calendar.
+* calendar-print-mayan-date:             To Other Calendar.
+* calendar-print-persian-date:           To Other Calendar.
+* calendar-set-mark:                     Mark and Region.
+* calendar-star-date:                    Calendar Customizing.
+* calendar-sunrise-sunset:               Sunrise/Sunset.
+* calendar-unmark <1>:                   Diary Commands.
+* calendar-unmark:                       Holidays.
+* call-last-kbd-macro:                   Basic Kbd Macro.
+* cancel-debug-on-entry:                 Lisp Debug.
+* capitalize-word <1>:                   Case.
+* capitalize-word:                       Fixing Case.
+* center-line:                           Fill Commands.
+* choose-completion:                     Completion Commands.
+* clear-rectangle:                       Rectangles.
+* comint-delchar-or-maybe-eof:           Shell Mode.
+* comint-dynamic-complete:               Shell Mode.
+* comint-next-input:                     Shell Mode.
+* comint-previous-input:                 Shell Mode.
+* command-apropos:                       Apropos.
+* compare-windows <1>:                   Other Window.
+* compare-windows:                       Comparing Files.
+* compile:                               Compilation.
+* compile-defun:                         Defuns.
+* convert-mocklisp-buffer:               Mocklisp.
+* conx:                                  CONX.
+* conx-buffer:                           CONX.
+* conx-init:                             CONX.
+* conx-load:                             CONX.
+* conx-region:                           CONX.
+* conx-save:                             CONX.
+* copy-file:                             Misc File Ops.
+* copy-last-shell-input:                 Shell Mode.
+* copy-rectangle-to-register:            RegRect.
+* copy-region-as-kill:                   Kill Ring.
+* copy-to-buffer:                        Accumulating Text.
+* copy-to-register:                      RegText.
+* count-lines-page:                      Pages.
+* count-lines-region:                    Position Info.
+* count-matches:                         Other Repeating Search.
+* count-text-lines:                      Nroff Mode.
+* customize:                             Easy Customization.
+* customize-apropos:                     Specific Customization.
+* customize-browse:                      Customization Groups.
+* customize-customized:                  Specific Customization.
+* customize-face:                        Specific Customization.
+* customize-group:                       Specific Customization.
+* customize-option:                      Specific Customization.
+* customize-saved:                       Specific Customization.
+* dabbrev-expand:                        Dynamic Abbrevs.
+* debug:                                 Lisp Debug.
+* debug-on-entry:                        Lisp Debug.
+* default-value:                         Locals.
+* define-abbrevs:                        Saving Abbrevs.
+* define-key <1>:                        Programmatic Rebinding.
+* define-key:                            Interactive Rebinding.
+* delete-backward-char <1>:              Kill Errors.
+* delete-backward-char:                  Killing.
+* delete-blank-lines <1>:                Killing.
+* delete-blank-lines:                    Blank Lines.
+* delete-char <1>:                       Basic Picture.
+* delete-char:                           Killing.
+* delete-file:                           Misc File Ops.
+* delete-horizontal-space <1>:           Indentation Commands.
+* delete-horizontal-space:               Killing.
+* delete-indentation <1>:                Indentation Commands.
+* delete-indentation:                    Killing.
+* delete-matching-lines:                 Other Repeating Search.
+* delete-menu-item:                      Menu Customization.
+* delete-non-matching-lines:             Other Repeating Search.
+* delete-other-windows:                  Change Window.
+* delete-rectangle:                      Rectangles.
+* delete-window:                         Change Window.
+* describe-bindings:                     Misc Help.
+* describe-calendar-mode:                General Calendar.
+* describe-coding-system:                Coding Systems.
+* describe-copying:                      Misc Help.
+* describe-distribution:                 Misc Help.
+* describe-function <1>:                 Documentation.
+* describe-function:                     Name Help.
+* describe-input-method:                 Select Input Method.
+* describe-key:                          Key Help.
+* describe-key-briefly:                  Key Help.
+* describe-language-environment:         Language Environments.
+* describe-mode:                         Misc Help.
+* describe-no-warranty:                  Misc Help.
+* describe-syntax:                       Syntax Change.
+* describe-variable <1>:                 Examining.
+* describe-variable <2>:                 Documentation.
+* describe-variable:                     Name Help.
+* diary:                                 Diary Commands.
+* diary-anniversary <1>:                 Sexp Diary Entries.
+* diary-anniversary:                     Special Diary Entries.
+* diary-astro-day-number:                Sexp Diary Entries.
+* diary-block:                           Special Diary Entries.
+* diary-cyclic <1>:                      Sexp Diary Entries.
+* diary-cyclic:                          Special Diary Entries.
+* diary-day-of-year:                     Sexp Diary Entries.
+* diary-float:                           Special Diary Entries.
+* diary-french-date:                     Sexp Diary Entries.
+* diary-hebrew-date:                     Sexp Diary Entries.
+* diary-islamic-date:                    Sexp Diary Entries.
+* diary-iso-date:                        Sexp Diary Entries.
+* diary-julian-date:                     Sexp Diary Entries.
+* diary-mail-entries:                    Diary Commands.
+* diary-mayan-date:                      Sexp Diary Entries.
+* diary-omer:                            Sexp Diary Entries.
+* diary-parasha:                         Sexp Diary Entries.
+* diary-phases-of-moon:                  Sexp Diary Entries.
+* diary-rosh-hodesh:                     Sexp Diary Entries.
+* diary-sabbath-candles:                 Sexp Diary Entries.
+* diary-sunrise-sunset:                  Sexp Diary Entries.
+* diary-yahrzeit:                        Sexp Diary Entries.
+* diff:                                  Comparing Files.
+* diff-backup:                           Comparing Files.
+* digit-argument:                        Arguments.
+* dired:                                 Dired Enter.
+* dired-other-window <1>:                Pop Up Window.
+* dired-other-window:                    Dired Enter.
+* disable-command:                       Disabling.
+* disable-menu-item:                     Menu Customization.
+* disassemble:                           Compiling Libraries.
+* display-time:                          Mode Line.
+* dissociated-press:                     Dissociated Press.
+* do-auto-save:                          Auto Save Control.
+* doctor:                                Total Frustration.
+* down-list:                             Lists.
+* downcase-region:                       Case.
+* downcase-word <1>:                     Case.
+* downcase-word:                         Fixing Case.
+* edit-abbrevs:                          Editing Abbrevs.
+* edit-abbrevs-redefine:                 Editing Abbrevs.
+* edit-options:                          Edit Options.
+* edit-picture:                          Picture.
+* edit-tab-stops <1>:                    Text Mode.
+* edit-tab-stops:                        Tab Stops.
+* edit-tab-stops-note-changes:           Tab Stops.
+* edt-emulation-off:                     Emulation.
+* edt-emulation-on:                      Emulation.
+* electric-nroff-mode:                   Nroff Mode.
+* emacs-lisp-mode:                       Lisp Eval.
+* emacs-version:                         Bugs.
+* enable-command:                        Disabling.
+* enable-menu-item:                      Menu Customization.
+* end-kbd-macro:                         Basic Kbd Macro.
+* end-of-buffer:                         Moving Point.
+* end-of-defun:                          Defuns.
+* end-of-fortran-subprogram:             Fortran Motion.
+* end-of-line:                           Moving Point.
+* enlarge-window:                        Change Window.
+* enlarge-window-horizontally:           Change Window.
+* european-calendar:                     Date Formats.
+* eval-current-buffer:                   Lisp Eval.
+* eval-defun:                            Lisp Eval.
+* eval-expression:                       Lisp Eval.
+* eval-last-sexp:                        Lisp Eval.
+* eval-region:                           Lisp Eval.
+* exchange-point-and-mark:               Setting Mark.
+* execute-extended-command:              M-x.
+* exit-calendar:                         General Calendar.
+* exit-recursive-edit:                   Recursive Edit.
+* expand-abbrev:                         Expanding Abbrevs.
+* expand-region-abbrevs:                 Expanding Abbrevs.
+* fancy-diary-display:                   Fancy Diary Display.
+* fill-individual-paragraphs:            Fill Prefix.
+* fill-paragraph:                        Fill Commands.
+* fill-region:                           Fill Commands.
+* fill-region-as-paragraph:              Fill Commands.
+* find-alternate-file:                   Visiting.
+* find-file:                             Visiting.
+* find-file-other-frame <1>:             Visiting.
+* find-file-other-frame:                 XEmacs under X.
+* find-file-other-window <1>:            Pop Up Window.
+* find-file-other-window:                Visiting.
+* find-tag:                              Find Tag.
+* find-tag-other-window <1>:             Find Tag.
+* find-tag-other-window:                 Pop Up Window.
+* find-this-file:                        Visiting.
+* find-this-file-other-window:           Visiting.
+* finder-by-keyword:                     Library Keywords.
+* fortran-column-ruler:                  Fortran Columns.
+* fortran-comment-region:                Fortran Comments.
+* fortran-indent-line:                   ForIndent Commands.
+* fortran-indent-subprogram:             ForIndent Commands.
+* fortran-mode:                          Fortran.
+* fortran-next-statement:                Fortran Motion.
+* fortran-previous-statement:            Fortran Motion.
+* fortran-split-line:                    ForIndent Commands.
+* fortran-window-create:                 Fortran Columns.
+* forward-char:                          Moving Point.
+* forward-list:                          Lists.
+* forward-page:                          Pages.
+* forward-paragraph:                     Paragraphs.
+* forward-sentence:                      Sentences.
+* forward-sexp:                          Lists.
+* forward-text-line:                     Nroff Mode.
+* forward-word:                          Words.
+* frame-configuration-to-register:       RegConfig.
+* global-set-key <1>:                    Programmatic Rebinding.
+* global-set-key:                        Interactive Rebinding.
+* goto-char:                             Moving Point.
+* goto-line:                             Moving Point.
+* hanoi:                                 Amusements.
+* help-command:                          Help.
+* help-for-help:                         Help.
+* help-with-tutorial <1>:                Misc Help.
+* help-with-tutorial:                    Basic.
+* hide-body:                             Outline Visibility.
+* hide-entry:                            Outline Visibility.
+* hide-leaves:                           Outline Visibility.
+* hide-subtree:                          Outline Visibility.
+* holidays:                              Holidays.
+* include-other-diary-files:             Included Diary Files.
+* increment-register:                    RegNumbers.
+* indent-c-exp:                          Multi-line Indent.
+* indent-for-comment:                    Comments.
+* indent-new-comment-line:               Comments.
+* indent-region <1>:                     Multi-line Indent.
+* indent-region:                         Indentation Commands.
+* indent-relative:                       Indentation Commands.
+* indent-rigidly:                        Indentation Commands.
+* indent-sexp:                           Multi-line Indent.
+* indented-text-mode:                    Text Mode.
+* info:                                  Misc Help.
+* Info-elisp-ref:                        Misc Help.
+* Info-goto-emacs-command-node:          Misc Help.
+* insert-abbrevs:                        Saving Abbrevs.
+* insert-anniversary-diary-entry:        Special Diary Entries.
+* insert-block-diary-entry:              Special Diary Entries.
+* insert-cyclic-diary-entry:             Special Diary Entries.
+* insert-diary-entry:                    Adding to Diary.
+* insert-file:                           Misc File Ops.
+* insert-hebrew-diary-entry:             Hebrew/Islamic Entries.
+* insert-islamic-diary-entry:            Hebrew/Islamic Entries.
+* insert-kbd-macro:                      Save Kbd Macro.
+* insert-monthly-diary-entry:            Adding to Diary.
+* insert-monthly-hebrew-diary-entry:     Hebrew/Islamic Entries.
+* insert-monthly-islamic-diary-entry:    Hebrew/Islamic Entries.
+* insert-parentheses:                    Balanced Editing.
+* insert-register:                       RegText.
+* insert-weekly-diary-entry:             Adding to Diary.
+* insert-yearly-diary-entry:             Adding to Diary.
+* insert-yearly-hebrew-diary-entry:      Hebrew/Islamic Entries.
+* insert-yearly-islamic-diary-entry:     Hebrew/Islamic Entries.
+* interactive:                           M-x.
+* interrupt-shell-subjob:                Shell Mode.
+* inverse-add-global-abbrev:             Defining Abbrevs.
+* inverse-add-mode-abbrev:               Defining Abbrevs.
+* invert-face:                           Faces.
+* isearch-abort:                         Incremental Search.
+* isearch-backward:                      Incremental Search.
+* isearch-backward-regexp:               Regexp Search.
+* isearch-complete:                      Incremental Search.
+* isearch-delete-char:                   Incremental Search.
+* isearch-exit:                          Incremental Search.
+* isearch-forward:                       Incremental Search.
+* isearch-forward-regexp:                Regexp Search.
+* isearch-quote-char:                    Incremental Search.
+* isearch-repeat-backward:               Incremental Search.
+* isearch-repeat-forward:                Incremental Search.
+* isearch-ring-advance:                  Incremental Search.
+* isearch-ring-retreat:                  Incremental Search.
+* isearch-yank-line:                     Incremental Search.
+* isearch-yank-word:                     Incremental Search.
+* jump-to-register <1>:                  Split Window.
+* jump-to-register:                      RegPos.
+* just-one-space:                        Killing.
+* kbd-macro-query:                       Kbd Macro Query.
+* kill-all-abbrevs:                      Defining Abbrevs.
+* kill-buffer:                           Kill Buffer.
+* kill-comment:                          Comments.
+* kill-compilation:                      Compilation.
+* kill-line:                             Killing.
+* kill-local-variable:                   Locals.
+* kill-output-from-shell:                Shell Mode.
+* kill-rectangle:                        Rectangles.
+* kill-region:                           Killing.
+* kill-sentence <1>:                     Sentences.
+* kill-sentence:                         Killing.
+* kill-sexp <1>:                         Lists.
+* kill-sexp:                             Killing.
+* kill-some-buffers:                     Kill Buffer.
+* kill-word <1>:                         Words.
+* kill-word:                             Killing.
+* latex-mode:                            TeX Mode.
+* LaTeX-mode:                            TeX Mode.
+* lisp-complete-symbol:                  Lisp Completion.
+* lisp-indent-line:                      Basic Indent.
+* lisp-interaction-mode:                 Lisp Interaction.
+* lisp-mode:                             External Lisp.
+* lisp-send-defun:                       External Lisp.
+* list-abbrevs:                          Editing Abbrevs.
+* list-bookmarks:                        Bookmarks.
+* list-buffers:                          List Buffers.
+* list-calendar-holidays:                Holidays.
+* list-coding-systems:                   Coding Systems.
+* list-command-history:                  Repetition.
+* list-directory:                        ListDir.
+* list-hebrew-diary-entries:             Hebrew/Islamic Entries.
+* list-holidays:                         Holidays.
+* list-input-methods:                    Select Input Method.
+* list-islamic-diary-entries:            Hebrew/Islamic Entries.
+* list-matching-lines:                   Other Repeating Search.
+* list-options:                          Edit Options.
+* list-tags:                             List Tags.
+* list-yahrzeit-dates:                   From Other Calendar.
+* load:                                  Loading.
+* load-default-sounds:                   Audible Bell.
+* load-file:                             Loading.
+* load-library <1>:                      Loading.
+* load-library:                          Startup Paths.
+* load-sound-file:                       Audible Bell.
+* local-set-key:                         Interactive Rebinding.
+* local-unset-key:                       Interactive Rebinding.
+* locate-library:                        Loading.
+* lpr-buffer:                            Hardcopy.
+* lpr-region:                            Hardcopy.
+* mail:                                  Sending Mail.
+* mail-cc:                               Mail Mode.
+* mail-fill-yanked-message:              Mail Mode.
+* mail-interactive-insert-alias:         Mail Headers.
+* mail-other-window <1>:                 Sending Mail.
+* mail-other-window:                     Pop Up Window.
+* mail-send:                             Mail Mode.
+* mail-send-and-exit:                    Mail Mode.
+* mail-signature:                        Mail Mode.
+* mail-subject:                          Mail Mode.
+* mail-to:                               Mail Mode.
+* mail-yank-original:                    Mail Mode.
+* make-directory:                        File Names.
+* make-face-bold:                        Faces.
+* make-face-bold-italic:                 Faces.
+* make-face-italic:                      Faces.
+* make-face-larger:                      Faces.
+* make-face-smaller:                     Faces.
+* make-face-unbold:                      Faces.
+* make-face-unitalic:                    Faces.
+* make-frame:                            XEmacs under X.
+* make-local-variable:                   Locals.
+* make-obsolete:                         Compiling Libraries.
+* make-symbolic-link:                    Misc File Ops.
+* make-variable-buffer-local:            Locals.
+* manual-entry:                          Documentation.
+* mark-beginning-of-buffer:              Setting Mark.
+* mark-calendar-holidays:                Holidays.
+* mark-defun <1>:                        Defuns.
+* mark-defun:                            Marking Objects.
+* mark-diary-entries:                    Diary Commands.
+* mark-end-of-buffer:                    Setting Mark.
+* mark-fortran-subprogram:               Fortran Motion.
+* mark-hebrew-diary-entries:             Hebrew/Islamic Entries.
+* mark-included-diary-files:             Included Diary Files.
+* mark-islamic-diary-entries:            Hebrew/Islamic Entries.
+* mark-page <1>:                         Pages.
+* mark-page:                             Marking Objects.
+* mark-paragraph <1>:                    Paragraphs.
+* mark-paragraph:                        Marking Objects.
+* mark-sexp <1>:                         Lists.
+* mark-sexp:                             Marking Objects.
+* mark-whole-buffer:                     Marking Objects.
+* mark-word <1>:                         Words.
+* mark-word:                             Marking Objects.
+* minibuffer-complete:                   Completion Example.
+* minibuffer-complete-word:              Completion Commands.
+* modify-syntax-entry:                   Syntax Change.
+* mouse-choose-completion:               Completion Commands.
+* mouse-del-char:                        Additional Mouse Operations.
+* mouse-delete-window:                   Additional Mouse Operations.
+* mouse-keep-one-window:                 Additional Mouse Operations.
+* mouse-kill-line:                       Additional Mouse Operations.
+* mouse-line-length:                     Additional Mouse Operations.
+* mouse-scroll:                          Additional Mouse Operations.
+* mouse-select:                          Additional Mouse Operations.
+* mouse-select-and-split:                Additional Mouse Operations.
+* mouse-set-mark:                        Additional Mouse Operations.
+* mouse-set-point:                       Additional Mouse Operations.
+* mouse-track:                           Additional Mouse Operations.
+* mouse-track-adjust:                    Additional Mouse Operations.
+* mouse-track-and-copy-to-cutbuffer:     Additional Mouse Operations.
+* mouse-track-delete-and-insert:         Additional Mouse Operations.
+* move-over-close-and-reindent:          Balanced Editing.
+* move-to-window-line:                   Moving Point.
+* name-last-kbd-macro:                   Save Kbd Macro.
+* narrow-to-region:                      Narrowing.
+* negative-argument:                     Arguments.
+* newline:                               Inserting Text.
+* newline-and-indent:                    Basic Indent.
+* next-complex-command:                  Repetition.
+* next-error:                            Compilation.
+* next-history-element:                  Minibuffer History.
+* next-line:                             Moving Point.
+* next-list-mode-item:                   Completion Commands.
+* next-matching-history-element:         Minibuffer History.
+* not-modified:                          Saving.
+* nroff-mode:                            Nroff Mode.
+* number-to-register:                    RegNumbers.
+* occur:                                 Other Repeating Search.
+* open-dribble-file:                     Bugs.
+* open-line:                             Blank Lines.
+* open-rectangle:                        Rectangles.
+* open-termscript:                       Bugs.
+* other-window:                          Other Window.
+* other-window-any-frame:                Other Window.
+* outline-backward-same-level:           Outline Motion.
+* outline-forward-same-level:            Outline Motion.
+* outline-next-visible-heading:          Outline Motion.
+* outline-previous-visible-heading:      Outline Motion.
+* outline-up-heading:                    Outline Motion.
+* overwrite-mode:                        Minor Modes.
+* phases-of-moon:                        Lunar Phases.
+* picture-backward-clear-column:         Basic Picture.
+* picture-backward-column:               Basic Picture.
+* picture-clear-column:                  Basic Picture.
+* picture-clear-line:                    Basic Picture.
+* picture-clear-rectangle:               Rectangles in Picture.
+* picture-clear-rectangle-to-register:   Rectangles in Picture.
+* picture-forward-column:                Basic Picture.
+* picture-motion:                        Insert in Picture.
+* picture-motion-reverse:                Insert in Picture.
+* picture-move-down:                     Basic Picture.
+* picture-move-up:                       Basic Picture.
+* picture-movement-down:                 Insert in Picture.
+* picture-movement-left:                 Insert in Picture.
+* picture-movement-ne:                   Insert in Picture.
+* picture-movement-nw:                   Insert in Picture.
+* picture-movement-right:                Insert in Picture.
+* picture-movement-se:                   Insert in Picture.
+* picture-movement-sw:                   Insert in Picture.
+* picture-movement-up:                   Insert in Picture.
+* picture-newline:                       Basic Picture.
+* picture-open-line:                     Basic Picture.
+* picture-set-tab-stops:                 Tabs in Picture.
+* picture-tab:                           Tabs in Picture.
+* picture-tab-search:                    Tabs in Picture.
+* picture-yank-rectangle:                Rectangles in Picture.
+* picture-yank-rectangle-from-register:  Rectangles in Picture.
+* plain-TeX-mode:                        TeX Mode.
+* plain-tex-mode:                        TeX Mode.
+* play-sound:                            Audible Bell.
+* point-to-register:                     RegPos.
+* prefer-coding-system:                  Recognize Coding.
+* prepend-to-buffer:                     Accumulating Text.
+* previous-complex-command:              Repetition.
+* previous-history-element:              Minibuffer History.
+* previous-line:                         Moving Point.
+* previous-list-mode-item:               Completion Commands.
+* previous-matching-history-element:     Minibuffer History.
+* print-buffer:                          Hardcopy.
+* print-diary-entries <1>:               Diary Customizing.
+* print-diary-entries:                   Diary Commands.
+* print-region:                          Hardcopy.
+* quail-set-keyboard-layout:             Select Input Method.
+* query-replace:                         Query Replace.
+* query-replace-regexp:                  Query Replace.
+* quietly-read-abbrev-file:              Saving Abbrevs.
+* quit-shell-subjob:                     Shell Mode.
+* quoted-insert:                         Inserting Text.
+* re-search-backward:                    Regexp Search.
+* re-search-forward:                     Regexp Search.
+* read-abbrev-file:                      Saving Abbrevs.
+* read-key-sequence:                     Representing Keystrokes.
+* recenter <1>:                          Scrolling.
+* recenter:                              Moving Point.
+* recover-file:                          Recover.
+* redraw-calendar:                       General Calendar.
+* relabel-menu-item:                     Menu Customization.
+* remove-directory:                      File Names.
+* rename-buffer:                         Misc Buffer.
+* rename-file:                           Misc File Ops.
+* repeat-complex-command:                Repetition.
+* replace-regexp:                        Unconditional Replace.
+* replace-string:                        Unconditional Replace.
+* revert-buffer:                         Reverting.
+* run-lisp:                              External Lisp.
+* save-buffer:                           Saving.
+* save-buffers-kill-emacs:               Exiting.
+* save-some-buffers:                     Saving.
+* scroll-calendar-left:                  Scroll Calendar.
+* scroll-calendar-left-three-months:     Scroll Calendar.
+* scroll-calendar-right:                 Scroll Calendar.
+* scroll-calendar-right-three-months:    Scroll Calendar.
+* scroll-down:                           Scrolling.
+* scroll-left:                           Horizontal Scrolling.
+* scroll-other-window <1>:               General Calendar.
+* scroll-other-window:                   Other Window.
+* scroll-right:                          Horizontal Scrolling.
+* scroll-up:                             Scrolling.
+* search-backward:                       Non-Incremental Search.
+* search-forward:                        Non-Incremental Search.
+* select-input-method:                   Select Input Method.
+* self-insert:                           Inserting Text.
+* send-shell-input:                      Shell Mode.
+* set-buffer-file-coding-system:         Specify Coding.
+* set-buffer-process-coding-system:      Specify Coding.
+* set-comment-column:                    Comments.
+* set-default-file-modes:                Interlocking.
+* set-face-background:                   Faces.
+* set-face-background-pixmap:            Faces.
+* set-face-font:                         Faces.
+* set-face-foreground:                   Faces.
+* set-face-underline-p:                  Faces.
+* set-fill-column:                       Fill Commands.
+* set-fill-prefix:                       Fill Prefix.
+* set-gnu-bindings:                      Emulation.
+* set-goal-column:                       Moving Point.
+* set-gosmacs-bindings:                  Emulation.
+* set-keyboard-coding-system:            Specify Coding.
+* set-language-environment:              Language Environments.
+* set-mark-command:                      Setting Mark.
+* set-selective-display:                 Selective Display.
+* set-terminal-coding-system:            Specify Coding.
+* set-variable:                          Examining.
+* set-visited-file-name:                 Saving.
+* setq-default:                          Locals.
+* shell:                                 Interactive Shell.
+* shell-command:                         Single Shell.
+* shell-command-on-region:               Single Shell.
+* shell-send-eof:                        Shell Mode.
+* show-all:                              Outline Visibility.
+* show-all-diary-entries:                Diary Commands.
+* show-branches:                         Outline Visibility.
+* show-children:                         Outline Visibility.
+* show-entry:                            Outline Visibility.
+* show-output-from-shell:                Shell Mode.
+* show-subtree:                          Outline Visibility.
+* simple-diary-display:                  Fancy Diary Display.
+* sort-columns:                          Sorting.
+* sort-diary-entries:                    Fancy Diary Display.
+* sort-fields:                           Sorting.
+* sort-lines:                            Sorting.
+* sort-numeric-fields:                   Sorting.
+* sort-pages:                            Sorting.
+* sort-paragraphs:                       Sorting.
+* spell-buffer:                          Spelling.
+* spell-region:                          Spelling.
+* spell-string:                          Spelling.
+* spell-word:                            Spelling.
+* split-line:                            Indentation Commands.
+* split-window-horizontally:             Split Window.
+* split-window-vertically:               Split Window.
+* start-kbd-macro:                       Basic Kbd Macro.
+* stop-shell-subjob:                     Shell Mode.
+* substitute-key-definition:             Interactive Rebinding.
+* sunrise-sunset:                        Sunrise/Sunset.
+* suspend-emacs:                         Exiting.
+* switch-to-buffer:                      Select Buffer.
+* switch-to-buffer-other-frame <1>:      Select Buffer.
+* switch-to-buffer-other-frame:          XEmacs under X.
+* switch-to-buffer-other-window <1>:     Pop Up Window.
+* switch-to-buffer-other-window:         Select Buffer.
+* switch-to-completions:                 Completion Commands.
+* switch-to-other-buffer:                Select Buffer.
+* tab-to-tab-stop <1>:                   Text Mode.
+* tab-to-tab-stop:                       Tab Stops.
+* tabify:                                Just Spaces.
+* tags-apropos:                          List Tags.
+* tags-loop-continue:                    Tags Search.
+* tags-query-replace:                    Tags Search.
+* tags-search:                           Tags Search.
+* term:                                  Terminal emulator.
+* term-line-mode:                        Term Mode.
+* term-pager-toggle:                     Paging in Term.
+* tex-buffer:                            TeX Print.
+* tex-close-latex-block:                 TeX Editing.
+* tex-insert-braces:                     TeX Editing.
+* tex-insert-quote:                      TeX Editing.
+* tex-kill-job:                          TeX Print.
+* tex-mode:                              TeX Mode.
+* TeX-mode:                              TeX Mode.
+* tex-print:                             TeX Print.
+* tex-recenter-output-buffer:            TeX Print.
+* tex-region:                            TeX Print.
+* tex-show-print-queue:                  TeX Print.
+* tex-terminate-paragraph:               TeX Editing.
+* text-mode:                             Text Mode.
+* toggle-input-method:                   Select Input Method.
+* toggle-read-only:                      Misc Buffer.
+* top-level <1>:                         Quitting.
+* top-level:                             Recursive Edit.
+* transpose-chars <1>:                   Transpose.
+* transpose-chars:                       Moving Point.
+* transpose-lines:                       Transpose.
+* transpose-sexps <1>:                   Lists.
+* transpose-sexps:                       Transpose.
+* transpose-words <1>:                   Words.
+* transpose-words:                       Transpose.
+* undo:                                  Undo.
+* unexpand-abbrev:                       Expanding Abbrevs.
+* universal-argument:                    Arguments.
+* universal-coding-system-argument:      Specify Coding.
+* untabify:                              Just Spaces.
+* up-list:                               TeX Editing.
+* upcase-region:                         Case.
+* upcase-word <1>:                       Case.
+* upcase-word:                           Fixing Case.
+* validate-tex-buffer:                   TeX Editing.
+* vc-cancel-version:                     Editing with VC.
+* vc-create-snapshot:                    Making Snapshots.
+* vc-diff:                               Old Versions.
+* vc-directory:                          VC Status.
+* vc-insert-headers:                     Version Headers.
+* vc-next-action:                        Editing with VC.
+* vc-print-log:                          VC Status.
+* vc-register:                           Editing with VC.
+* vc-rename-file:                        Renaming and VC.
+* vc-retrieve-snapshot:                  Making Snapshots.
+* vc-revert-buffer:                      Editing with VC.
+* vc-update-change-log:                  Change Logs and VC.
+* vc-version-other-window:               Old Versions.
+* view-buffer:                           Misc Buffer.
+* view-diary-entries:                    Diary Commands.
+* view-emacs-news:                       Misc Help.
+* view-file:                             Misc File Ops.
+* view-hello-file:                       Mule Intro.
+* view-lossage:                          Misc Help.
+* view-register:                         Registers.
+* visit-tags-table:                      Select Tags Table.
+* what-cursor-position:                  Position Info.
+* what-line:                             Position Info.
+* what-page:                             Position Info.
+* where-is:                              Name Help.
+* widen:                                 Narrowing.
+* widget-backward:                       Changing an Option.
+* widget-complete:                       Changing an Option.
+* widget-forward:                        Changing an Option.
+* window-configuration-to-register <1>:  Split Window.
+* window-configuration-to-register:      RegConfig.
+* word-search-backward:                  Word Search.
+* word-search-forward:                   Word Search.
+* write-abbrev-file:                     Saving Abbrevs.
+* write-file:                            Saving.
+* x-copy-primary-selection:              X Selection Commands.
+* x-create-frame:                        X Resources.
+* x-delete-primary-selection:            X Selection Commands.
+* x-insert-selection:                    X Selection Commands.
+* x-kill-primary-selection:              X Selection Commands.
+* x-mouse-kill:                          X Selection Commands.
+* x-own-secondary-selection:             X Selection Commands.
+* x-own-selection:                       X Selection Commands.
+* x-set-point-and-insert-selection:      X Selection Commands.
+* xemacs-local-faq:                      Misc Help.
+* Yank:                                  Kill Ring.
+* yank-pop:                              Earlier Kills.
+* yank-rectangle:                        Rectangles.
+* yow:                                   Amusements.
+* zap-to-char:                           Killing.
+* zmacs-activate-region:                 Active Regions.
+* zmacs-deactivate-region:               Active Regions.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Help Summary,  Next: Key Help,  Prev: Help,  Up: Help
-
-Help Summary
-============
-
-   Here is a summary of the defined help commands.
-
-`C-h a REGEXP <RET>'
-     Display a list of functions and variables whose names match REGEXP
-     (`hyper-apropos').
-
-`C-h A REGEXP'
-     Show all commands whose names contain matches for REGEXP
-     (`command-apropos').
-
-`C-h b'
-     Display a table of all key bindings currently in effect, with local
-     bindings of the current major mode first, followed by all global
-     bindings (`describe-bindings').
-
-`C-h c KEY'
-     Print the name of the command that KEY runs
-     (`describe-key-briefly').  Here `c' stands for `character'.  For
-     more extensive information on KEY, use `C-h k'.
-
-`C-h d FUNCTION <RET>'
-`C-h f FUNCTION <RET>'
-     Display documentation on the Lisp function named FUNCTION
-     (`describe-function').  Since commands are Lisp functions, a
-     command name may be used.
-
-`C-h i'
-     Run Info, the program for browsing documentation files (`info').
-     The complete XEmacs manual is available online in Info.
-
-`C-h k KEY'
-     Display the name and documentation of the command that KEY runs
-     (`describe-key').
-
-`C-h l'
-     Display a description of the last 100 characters you typed
-     (`view-lossage').
-
-`C-h m'
-     Display documentation of the current major mode (`describe-mode').
+File: xemacs.info,  Node: Variable Index,  Next: Concept Index,  Prev: Command Index,  Up: Top

 
 

-`C-h n'
-`C-h C-n'
-     Display documentation of XEmacs changes, most recent first
-     (`view-emacs-news').
-
-`C-h p'
-     Find packages by topic keyword (`finder-by-keyword').
-
-`C-h C-p'
-     Display a table of all mouse bindings currently in effect now, with
-     local bindings of the current major mode first, followed by all
-     global bindings (`describe-pointer').
-
-`C-h s'
-     Display current contents of the syntax table, plus an explanation
-     of what they mean (`describe-syntax').  *Note Syntax::.
-
-`C-h t'
-     Enter the XEmacs interactive tutorial (`help-with-tutorial').
-
-`C-h v VAR <RET>'
-     Display the documentation of the Lisp variable VAR
-     (`describe-variable').
-
-`C-h w COMMAND <RET>'
-     Print which keys run the command named COMMAND (`where-is').
-
-`C-h B <RET>'
-     Display info on how to deal with Beta versions of XEmacs
-     (`describe-beta').
-
-`C-h C GROUP <RET>'
-     Select customization buffer for GROUP (`customize').
-
-`C-h F <RET>'
-     View the local copy of the XEmacs FAQ (`xemacs-local-faq').
-
-`C-h C-i FILE <RET>'
-     Read Info file FILE with Info browser (`Info-query').
+Variable Index
+**************

 
 

-`C-h C-c COMMAND <RET>'
-     Look up an Emacs command COMMAND in the Emacs manual in the Info
-     system (`Info-goto-emacs-command-node').
+* Menu:

 
 

-`C-h C-f FUNCTION <RET>'
-     Look up an Emacs Lisp function FUNCTION in the Elisp manual in the
-     Info system (`Info-elisp-ref').
+* abbrev-all-caps:                       Expanding Abbrevs.
+* abbrev-file-name:                      Saving Abbrevs.
+* abbrev-mode:                           Abbrevs.
+* after-load-alist:                      Loading.
+* after-save-hook:                       Saving.
+* all-christian-calendar-holidays:       Holiday Customizing.
+* all-hebrew-calendar-holidays:          Holiday Customizing.
+* all-islamic-calendar-holidays:         Holiday Customizing.
+* appt-audible:                          Appt Customizing.
+* appt-display-duration:                 Appt Customizing.
+* appt-display-mode-line:                Appt Customizing.
+* appt-message-warning-time:             Appt Customizing.
+* appt-msg-window:                       Appt Customizing.
+* appt-visible:                          Appt Customizing.
+* apropos-do-all:                        Apropos.
+* auto-fill-inhibit-regexp:              Fill Commands.
+* auto-lower-frame:                      XEmacs under X.
+* auto-mode-alist:                       Choosing Modes.
+* auto-raise-frame:                      XEmacs under X.
+* auto-save-default:                     Auto Save Control.
+* auto-save-interval:                    Auto Save Control.
+* auto-save-timeout:                     Auto Save Control.
+* auto-save-visited-file-name:           Auto Save Files.
+* backup-by-copying:                     Backup Copying.
+* backup-by-copying-when-linked:         Backup Copying.
+* backup-by-copying-when-mismatch:       Backup Copying.
+* bell-volume:                           Audible Bell.
+* blink-matching-paren:                  Matching.
+* blink-matching-paren-distance:         Matching.
+* bookmark-save-flag:                    Bookmarks.
+* bookmark-search-size:                  Bookmarks.
+* buffer-file-coding-system:             Recognize Coding.
+* buffer-file-name:                      Visiting.
+* buffer-file-truename:                  Visiting.
+* buffer-read-only:                      Misc Buffer.
+* buffer-tag-table:                      Find Tag.
+* c-argdecl-indent:                      C Indent.
+* c-auto-newline:                        C Indent.
+* c-brace-imaginary-offset:              C Indent.
+* c-brace-offset:                        C Indent.
+* c-continued-statement-offset:          C Indent.
+* c-indent-level:                        C Indent.
+* c-label-offset:                        C Indent.
+* c-mode-hook:                           Program Modes.
+* c-mode-map:                            Keymaps.
+* c-tab-always-indent:                   C Indent.
+* calendar-date-display-form:            Date Display Format.
+* calendar-daylight-savings-ends:        Daylight Savings.
+* calendar-daylight-savings-ends-time:   Daylight Savings.
+* calendar-daylight-savings-starts:      Daylight Savings.
+* calendar-daylight-time-offset:         Daylight Savings.
+* calendar-daylight-time-zone-name:      Sunrise/Sunset.
+* calendar-holiday-marker:               Calendar Customizing.
+* calendar-holidays:                     Holiday Customizing.
+* calendar-latitude:                     Sunrise/Sunset.
+* calendar-load-hook:                    Calendar Customizing.
+* calendar-location-name:                Sunrise/Sunset.
+* calendar-longitude:                    Sunrise/Sunset.
+* calendar-standard-time-zone-name:      Sunrise/Sunset.
+* calendar-time-display-form:            Time Display Format.
+* calendar-time-zone:                    Sunrise/Sunset.
+* calendar-today-marker:                 Calendar Customizing.
+* calendar-week-start-day:               Move to Beginning or End.
+* case-fold-search <1>:                  Replacement and Case.
+* case-fold-search:                      Search Case.
+* case-replace:                          Replacement and Case.
+* christian-holidays:                    Holiday Customizing.
+* coding:                                Recognize Coding.
+* command-history:                       Repetition.
+* command-line-args:                     Command Switches.
+* comment-column:                        Comments.
+* comment-end:                           Comments.
+* comment-indent-hook:                   Comments.
+* comment-line-start:                    Fortran Comments.
+* comment-line-start-skip:               Fortran Comments.
+* comment-multi-line:                    Comments.
+* comment-start:                         Comments.
+* comment-start-skip:                    Comments.
+* compare-ignore-case:                   Comparing Files.
+* compile-command:                       Compilation.
+* completion-auto-help:                  Completion Options.
+* completion-ignored-extensions:         Completion Options.
+* create-frame-hook:                     XEmacs under X.
+* ctl-arrow:                             Display Vars.
+* ctl-x-map:                             Keymaps.
+* current-input-method:                  Select Input Method.
+* data-directory:                        Startup Paths.
+* data-directory-list:                   Startup Paths.
+* debug-on-error:                        Lisp Debug.
+* debug-on-quit:                         Lisp Debug.
+* default-buffer-file-coding-system:     Specify Coding.
+* default-directory:                     File Names.
+* default-directory-alist:               File Names.
+* default-frame-alist:                   XEmacs under X.
+* default-frame-plist:                   XEmacs under X.
+* default-input-method:                  Select Input Method.
+* default-major-mode:                    Choosing Modes.
+* delete-auto-save-files:                Auto Save Files.
+* delete-old-versions:                   Backup Deletion.
+* describe-function-show-arglist:        Name Help.
+* diary-date-forms:                      Diary Customizing.
+* diary-display-hook:                    Fancy Diary Display.
+* diary-entry-marker:                    Calendar Customizing.
+* diary-file:                            Format of Diary File.
+* diary-list-include-blanks:             Fancy Diary Display.
+* diary-mail-days:                       Diary Commands.
+* diff-switches:                         Comparing Files.
+* dired-kept-versions:                   Dired Deletion.
+* dired-listing-switches:                Dired Enter.
+* display-buffer-function:               Pop Up Window.
+* doc-directory:                         Startup Paths.
+* echo-keystrokes:                       Display Vars.
+* emacs-lisp-mode-hook:                  Program Modes.
+* emacs-roots:                           Startup Paths.
+* EMACSDATA:                             Startup Paths.
+* EMACSLOADPATH:                         Startup Paths.
+* EMACSPATH:                             Startup Paths.
+* enable-local-variables:                File Variables.
+* enable-recursive-minibuffers:          Minibuffer Edit.
+* esc-map:                               Keymaps.
+* european-calendar-style:               Date Formats.
+* exec-directory:                        Startup Paths.
+* exec-path:                             Startup Paths.
+* explicit-shell-file-name:              Interactive Shell.
+* face-frob-from-locale-first:           Faces.
+* file-coding-system-alist:              Recognize Coding.
+* file-name-coding-system:               Specify Coding.
+* fill-column:                           Fill Commands.
+* fill-prefix:                           Fill Prefix.
+* find-file-compare-truenames:           Visiting.
+* find-file-hooks:                       Visiting.
+* find-file-not-found-hooks:             Visiting.
+* find-file-run-dired:                   Visiting.
+* find-file-use-truenames:               Visiting.
+* fortran-check-all-num-for-matching-do: ForIndent Vars.
+* fortran-comment-indent-char:           Fortran Comments.
+* fortran-comment-indent-style:          Fortran Comments.
+* fortran-comment-line-column:           Fortran Comments.
+* fortran-comment-region:                Fortran Comments.
+* fortran-continuation-char:             ForIndent Conv.
+* fortran-continuation-indent:           ForIndent Vars.
+* fortran-do-indent:                     ForIndent Vars.
+* fortran-electric-line-number:          ForIndent Num.
+* fortran-if-indent:                     ForIndent Vars.
+* fortran-line-number-indent:            ForIndent Num.
+* fortran-minimum-statement-indent:      ForIndent Vars.
+* frame-icon-title-format <1>:           Command Switches.
+* frame-icon-title-format:               XEmacs under X.
+* frame-title-format <1>:                Command Switches.
+* frame-title-format:                    XEmacs under X.
+* general-holidays:                      Holiday Customizing.
+* global-map:                            Keymaps.
+* hebrew-holidays:                       Holiday Customizing.
+* help-map:                              Keymaps.
+* holidays-in-diary-buffer:              Diary Customizing.
+* indent-tabs-mode:                      Just Spaces.
+* Info-directory-list:                   Startup Paths.
+* INFOPATH:                              Startup Paths.
+* initial-calendar-window-hook:          Calendar Customizing.
+* initial-major-mode:                    Entering Emacs.
+* input-method-highlight-flag:           Input Methods.
+* input-method-verbose-flag:             Input Methods.
+* input-ring-size:                       Interactive Shell.
+* insert-default-directory <1>:          File Names.
+* insert-default-directory:              Minibuffer File.
+* isearch-mode-map:                      Keymaps.
+* islamic-holidays:                      Holiday Customizing.
+* kept-new-versions:                     Backup Deletion.
+* kept-old-versions:                     Backup Deletion.
+* keyboard-translate-table:              Intro to Keystrokes.
+* kill-ring-max:                         Earlier Kills.
+* LaTeX-mode-hook:                       TeX Print.
+* lisp-body-indention:                   Lisp Indent.
+* lisp-directory:                        Startup Paths.
+* lisp-indent-offset:                    Lisp Indent.
+* lisp-interaction-mode-hook:            Program Modes.
+* lisp-mode-hook:                        Program Modes.
+* lisp-mode-map:                         Keymaps.
+* list-diary-entries-hook:               Included Diary Files.
+* list-directory-brief-switches:         ListDir.
+* list-directory-verbose-switches:       ListDir.
+* load-path <1>:                         Loading.
+* load-path:                             Startup Paths.
+* local-holidays:                        Holiday Customizing.
+* lpr-switches:                          Hardcopy.
+* mail-abbrev-mailrc-file:               Mail Headers.
+* mail-abbrev-mode-regexp:               Mail Headers.
+* mail-alias-separator-string:           Mail Headers.
+* mail-archive-file-name:                Mail Headers.
+* mail-header-separator:                 Mail Format.
+* mail-mode-hook:                        Mail Mode.
+* make-backup-files:                     Backup.
+* make-tags-files-invisible:             Find Tag.
+* mark-diary-entries-hook:               Included Diary Files.
+* mark-diary-entries-in-calendar:        Calendar Customizing.
+* mark-holidays-in-calendar:             Calendar Customizing.
+* mark-ring:                             Mark Ring.
+* mark-ring-max:                         Mark Ring.
+* meta-flag:                             Meta Key.
+* minibuffer-confirm-incomplete <1>:     Completion Options.
+* minibuffer-confirm-incomplete:         Minibuffer Edit.
+* minibuffer-local-completion-map:       Keymaps.
+* minibuffer-local-map:                  Keymaps.
+* minibuffer-local-must-match-map:       Keymaps.
+* minibuffer-local-ns-map:               Keymaps.
+* mode-line-inverse-video:               Mode Line.
+* modeline-pointer-glyph:                Mouse Selection.
+* muddle-mode-hook:                      Program Modes.
+* next-line-add-newlines:                Moving Point.
+* next-screen-context-lines:             Scrolling.
+* no-redraw-on-reenter:                  Display Vars.
+* nongregorian-diary-listing-hook:       Hebrew/Islamic Entries.
+* nongregorian-diary-marking-hook:       Hebrew/Islamic Entries.
+* nontext-pointer-glyph:                 Mouse Selection.
+* nroff-mode-hook:                       Nroff Mode.
+* number-of-diary-entries:               Diary Customizing.
+* other-holidays:                        Holiday Customizing.
+* outline-mode-hook:                     Outline Mode.
+* outline-regexp:                        Outline Format.
+* page-delimiter:                        Pages.
+* paragraph-separate:                    Paragraphs.
+* paragraph-start:                       Paragraphs.
+* parse-sexp-ignore-comments:            Syntax Entry.
+* PATH:                                  Startup Paths.
+* picture-mode-hook:                     Picture.
+* picture-tab-chars:                     Tabs in Picture.
+* plain-TeX-mode-hook:                   TeX Print.
+* print-diary-entries-hook:              Diary Customizing.
+* repeat-complex-command-map:            Keymaps.
+* require-final-newline:                 Saving.
+* save-abbrevs:                          Saving Abbrevs.
+* scheme-mode-hook:                      Program Modes.
+* scroll-conservatively:                 Scrolling.
+* scroll-step:                           Scrolling.
+* search-slow-speed:                     Incremental Search.
+* search-slow-window-lines:              Incremental Search.
+* selective-display-ellipses <1>:        Outline Visibility.
+* selective-display-ellipses:            Display Vars.
+* sentence-end:                          Sentences.
+* shell-cd-regexp:                       Interactive Shell.
+* shell-file-name:                       Single Shell.
+* shell-popd-regexp:                     Interactive Shell.
+* shell-prompt-pattern:                  Shell Mode.
+* shell-pushd-regexp:                    Interactive Shell.
+* sound-alist:                           Audible Bell.
+* tab-stop-list:                         Tab Stops.
+* tab-width:                             Display Vars.
+* tag-mark-stack-max:                    Find Tag.
+* tag-table-alist <1>:                   Find Tag.
+* tag-table-alist:                       Select Tags Table.
+* tags-always-build-completion-table:    Select Tags Table.
+* tags-build-completion-table:           Find Tag.
+* tags-file-name <1>:                    Find Tag.
+* tags-file-name:                        Select Tags Table.
+* term-file-prefix:                      Terminal Init.
+* term-setup-hook:                       Terminal Init.
+* TeX-mode-hook:                         TeX Print.
+* text-mode-hook:                        Text Mode.
+* text-pointer-glyph:                    Mouse Selection.
+* today-invisible-calendar-hook:         Calendar Customizing.
+* today-visible-calendar-hook:           Calendar Customizing.
+* track-eol:                             Moving Point.
+* truncate-lines:                        Continuation Lines.
+* truncate-partial-width-windows:        Split Window.
+* vc-command-messages:                   Variables for Check-in/out.
+* vc-comment-alist:                      Version Headers.
+* vc-default-back-end:                   Editing with VC.
+* vc-header-alist:                       Version Headers.
+* vc-initial-comment:                    Editing with VC.
+* vc-keep-workfiles:                     Editing with VC.
+* vc-log-mode-hook:                      Log Entries.
+* vc-make-backup-files:                  Editing with VC.
+* vc-mistrust-permissions:               Variables for Check-in/out.
+* vc-path:                               Variables for Check-in/out.
+* vc-static-header-alist:                Version Headers.
+* vc-suppress-confirm:                   Variables for Check-in/out.
+* version-control:                       Backup Names.
+* view-calendar-holidays-initially:      Calendar Customizing.
+* view-diary-entries-initially:          Calendar Customizing.
+* window-min-height:                     Change Window.
+* window-min-width:                      Change Window.
+* write-file-hooks:                      Saving.
+* x-frame-defaults:                      XEmacs under X.
+* zmacs-region-stays:                    Active Regions.
+* zmacs-regions:                         Active Regions.

 
 \1f
 
 \1f

-File: xemacs.info,  Node: Key Help,  Next: Name Help,  Prev: Help Summary,  Up: Help
-
-Documentation for a Key
-=======================
+File: xemacs.info,  Node: Concept Index,  Next: Frame,  Prev: Variable Index,  Up: Top

 
 

-   The most basic `C-h' options are `C-h c' (`describe-key-briefly')
-and `C-h k' (`describe-key').  `C-h c KEY' prints in the echo area the
-name of the command that KEY is bound to.  For example, `C-h c C-f'
-prints `forward-char'.  Since command names are chosen to describe what
-the commands do, this is a good way to get a very brief description of
-what KEY does.
+Concept Index
+*************

 
 

-   `C-h k KEY' is similar to `C-h c' but gives more information.  It
-displays the documentation string of the function KEY is bound to as
-well as its name.  KEY is a string or vector of events.  When called
-interactively, KEY may also be a menu selection.  This information does
-not usually fit into the echo area, so a window is used for the display.
-
-   `C-h c' and `C-h k' work for any sort of key sequences, including
-function keys and mouse events.
+* Menu:

 
 

-\1f
-File: xemacs.info,  Node: Name Help,  Next: Apropos,  Prev: Key Help,  Up: Help
-
-Help by Command or Variable Name
-================================
-
-   `C-h f' (`describe-function') reads the name of a Lisp function
-using the minibuffer, then displays that function's documentation
-string in a window.  Since commands are Lisp functions, you can use the
-argument FUNCTION to get the documentation of a command that you know
-by name.  For example,
-
-     C-h f auto-fill-mode <RET>
-
-displays the documentation for `auto-fill-mode'. Using `C-h f' is the
-only way to see the documentation of a command that is not bound to any
-key, that is, a command you would normally call using `M-x'.  If the
-variable `describe-function-show-arglist' is `t', `describe-function'
-shows its arglist if the FUNCTION is not an autoload function.
-
-   `C-h f' is also useful for Lisp functions that you are planning to
-use in a Lisp program.  For example, if you have just written the
-expression `(make-vector len)' and want to make sure you are using
-`make-vector' properly, type `C-h f make-vector <RET>'.  Because `C-h
-f' allows all function names, not just command names, you may find that
-some of your favorite abbreviations that work in `M-x' don't work in
-`C-h f'.  An abbreviation may be unique among command names, yet fail
-to be unique when other function names are allowed.
-
-   The function name for `C-h f' to describe has a default which is
-used if you type <RET> leaving the minibuffer empty.  The default is
-the function called by the innermost Lisp expression in the buffer
-around point, _provided_ that is a valid, defined Lisp function name.
-For example, if point is located following the text `(make-vector (car
-x)', the innermost list containing point is the one that starts with
-`(make-vector', so the default is to describe the function
-`make-vector'.
-
-   `C-h f' is often useful just to verify that you have the right
-spelling for the function name.  If `C-h f' mentions a name from the
-buffer as the default, that name must be defined as a Lisp function.  If
-that is all you want to know, just type `C-g' to cancel the `C-h f'
-command, then go on editing.
-
-   `C-h w COMMAND <RET>' (`where-is') tells you what keys are bound to
-COMMAND.  It prints a list of the keys in the echo area. Alternatively,
-it informs you that a command is not bound to any keys, which implies
-that you must use `M-x' to call the command.
-
-   `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
-variables instead of Lisp functions.  Its default is the Lisp symbol
-around or before point, if that is the name of a known Lisp variable.
-*Note Variables::.
+* $ in regexp:                           Regexps.
+* ( in regexp:                           Regexps.
+* ) in regexp:                           Regexps.
+* * in regexp:                           Regexps.
+* *? in regexp:                          Regexps.
+* + in regexp:                           Regexps.
+* +? in regexp:                          Regexps.
+* . in regexp:                           Regexps.
+* .mailrc file:                          Mail Headers.
+* // in file name:                       Minibuffer File.
+* ? in regexp:                           Regexps.
+* ?? in regexp:                          Regexps.
+* [ in regexp:                           Regexps.
+* \ in regexp:                           Regexps.
+* \' in regexp:                          Regexps.
+* \(?: in regexp:                        Regexps.
+* \< in regexp:                          Regexps.
+* \= in regexp:                          Regexps.
+* \> in regexp:                          Regexps.
+* \` in regexp:                          Regexps.
+* \B in regexp:                          Regexps.
+* \b in regexp:                          Regexps.
+* \S in regexp:                          Regexps.
+* \s in regexp:                          Regexps.
+* \W in regexp:                          Regexps.
+* \w in regexp:                          Regexps.
+* \{n,m\} in regexp:                     Regexps.
+* ] in regexp:                           Regexps.
+* ^ in regexp:                           Regexps.
+* Abbrev mode:                           Minor Modes.
+* abbrevs:                               Abbrevs.
+* aborting:                              Quitting.
+* accumulating text:                     Accumulating Text.
+* active fields (customization buffer):  Customization Groups.
+* active regions:                        Active Regions.
+* adding menu items:                     Menu Customization.
+* adding menus:                          Menu Customization.
+* againformation:                        Dissociated Press.
+* Apps menu <1>:                         Apps Menu.
+* Apps menu:                             Pull-down Menus.
+* apropos:                               Apropos.
+* architecture-specific directories:     Startup Paths.
+* arguments (from shell):                Command Switches.
+* arrow keys:                            Moving Point.
+* ASCII:                                 Intro to Keystrokes.
+* Asm mode:                              Asm Mode.
+* astronomical day numbers:              Calendar Systems.
+* audible bell, changing:                Audible Bell.
+* Auto Delete Selection menu item:       Options Menu.
+* Auto Fill mode <1>:                    Minor Modes.
+* Auto Fill mode <2>:                    Comments.
+* Auto Fill mode:                        Auto Fill.
+* Auto-Save mode:                        Auto Save.
+* autoload:                              Loading.
+* automatic package install:             Automatically.
+* available packages:                    Available Packages.
+* backup file:                           Backup.
+* batch mode:                            Command Switches.
+* beginning of line in regexp:           Regexps.
+* bell, changing:                        Audible Bell.
+* binary packages:                       Package Terminology.
+* binding:                               Commands.
+* blank lines <1>:                       Comments.
+* blank lines:                           Blank Lines.
+* body lines (Outline mode):             Outline Format.
+* bold font:                             Face Customization.
+* bookmarks:                             Bookmarks.
+* boredom:                               Amusements.
+* buffer:                                Frame.
+* buffer menu:                           Several Buffers.
+* buffers:                               Buffers.
+* Buffers menu <1>:                      Buffers Menu.
+* Buffers menu:                          Pull-down Menus.
+* Buffers Menu Length... menu item:      Options Menu.
+* Buffers Sub-Menus menu item:           Options Menu.
+* buggestion:                            Dissociated Press.
+* bugs:                                  Bugs.
+* building packages:                     Building Packages.
+* byte code:                             Compiling Libraries.
+* C:                                     Programs.
+* C mode:                                Program Modes.
+* C++ class browser, tags:               Tags.
+* calendar:                              Calendar/Diary.
+* calendar and LaTeX:                    LaTeX Calendar.
+* calendar, first day of week:           Move to Beginning or End.
+* candle lighting times:                 Sexp Diary Entries.
+* case conversion <1>:                   Case.
+* case conversion:                       Fixing Case.
+* Case Sensitive Search menu item:       Options Menu.
+* CCL programs:                          Mule and Fonts.
+* centering:                             Fill Commands.
+* change log:                            Change Log.
+* changing buffers:                      Select Buffer.
+* changing menu items:                   Menu Customization.
+* character set:                         Intro to Keystrokes.
+* character set (in regexp):             Regexps.
+* checking in files:                     Concepts of VC.
+* checking out files:                    Concepts of VC.
+* Chinese:                               Mule.
+* Chinese calendar:                      Calendar Systems.
+* choosing packages <1>:                 Which Packages.
+* choosing packages:                     Installing Packages.
+* class browser, C++:                    Tags.
+* Clear menu item:                       Edit Menu.
+* clipboard selections:                  X Clipboard Selection.
+* coding systems:                        Coding Systems.
+* command <1>:                           Key Bindings.
+* command:                               Commands.
+* command history:                       Repetition.
+* command line arguments:                Command Switches.
+* command name:                          Key Bindings.
+* comments:                              Comments.
+* comparing files:                       Comparing Files.
+* compilation errors:                    Compilation.
+* compiling files:                       Compilation.
+* completion:                            Completion.
+* completion (symbol names):             Lisp Completion.
+* continuation line:                     Continuation Lines.
+* Control-Meta:                          Lists.
+* Coptic calendar:                       Calendar Systems.
+* Copy menu item:                        Edit Menu.
+* copying files:                         Misc File Ops.
+* copying text <1>:                      Accumulating Text.
+* copying text:                          Yanking.
+* core distribution:                     Installing Packages.
+* crashes:                               Auto Save.
+* creating directories:                  File Names.
+* creating files:                        Visiting.
+* current buffer:                        Buffers.
+* current stack frame:                   Lisp Debug.
+* cursor <1>:                            Inserting Text.
+* cursor:                                Point.
+* cursor motion:                         Moving Point.
+* customization <1>:                     Customization.
+* customization <2>:                     Lisp Indent.
+* customization:                         Commands.
+* customization buffer:                  Easy Customization.
+* customization groups:                  Customization Groups.
+* customizing faces:                     Face Customization.
+* cut buffers:                           X Selection Commands.
+* Cut menu item:                         Edit Menu.
+* cutting:                               Killing.
+* Cyrillic:                              Mule.
+* day of year:                           General Calendar.
+* daylight savings time:                 Daylight Savings.
+* debugger:                              Lisp Debug.
+* default argument:                      Minibuffer.
+* defuns:                                Defuns.
+* Delete Frame menu item:                File Menu.
+* deleting blank lines:                  Blank Lines.
+* deleting characters and lines:         Erasing.
+* deleting menu items:                   Menu Customization.
+* deleting packages:                     Removing Packages.
+* deletion <1>:                          Killing.
+* deletion:                              Inserting Text.
+* deletion (of files) <1>:               Misc File Ops.
+* deletion (of files):                   Dired.
+* diary:                                 Diary.
+* diary buffer:                          Fancy Diary Display.
+* diary file:                            Format of Diary File.
+* ding:                                  Audible Bell.
+* directories:                           Startup Paths.
+* directory hierarchies:                 Startup Paths.
+* directory listing:                     ListDir.
+* Dired:                                 Dired.
+* disabled command:                      Disabling.
+* disabling menu items:                  Menu Customization.
+* Distribution:                          License.
+* doctor:                                Total Frustration.
+* double slash in file name:             Minibuffer File.
+* drastic changes:                       Reverting.
+* dribble file:                          Bugs.
+* early package hierarchies:             Startup Paths.
+* Ebrowse:                               Tags.
+* echo area:                             Echo Area.
+* Edit menu <1>:                         Edit Menu.
+* Edit menu:                             Pull-down Menus.
+* editable fields (customization buffer): Customization Groups.
+* editing level, recursive <1>:          Quitting.
+* editing level, recursive:              Recursive Edit.
+* EDT:                                   Emulation.
+* Eliza:                                 Total Frustration.
+* Emacs initialization file:             Init File.
+* Emacs-Lisp mode:                       Lisp Eval.
+* enabling menu items:                   Menu Customization.
+* encoding of characters:                Mule.
+* End Macro Recording menu item:         Edit Menu.
+* entering XEmacs:                       Entering Emacs.
+* environment:                           Single Shell.
+* erasing characters and lines:          Erasing.
+* error log:                             Compilation.
+* etags program:                         Create Tags Table.
+* Ethiopic calendar:                     Calendar Systems.
+* Execute Last Macro menu item:          Edit Menu.
+* Exit Emacs menu item:                  File Menu.
+* exiting <1>:                           Recursive Edit.
+* exiting:                               Exiting.
+* expansion (of abbrevs):                Abbrevs.
+* expression:                            Lists.
+* file dates:                            Interlocking.
+* file directory:                        ListDir.
+* File menu <1>:                         File Menu.
+* File menu:                             Pull-down Menus.
+* file names:                            File Names.
+* file protection:                       Interlocking.
+* files <1>:                             Visiting.
+* files <2>:                             Files.
+* files:                                 Basic Files.
+* files, remote:                         Files.
+* fill prefix:                           Fill Prefix.
+* filling:                               Filling.
+* font encoding:                         Mule and Fonts.
+* Font menu item:                        Options Menu.
+* font registry:                         Mule and Fonts.
+* fonts:                                 Mule and Fonts.
+* fonts and faces:                       Face Customization.
+* formfeed:                              Pages.
+* Fortran mode:                          Fortran.
+* frame:                                 Frame.
+* French Revolutionary calendar:         Calendar Systems.
+* function <1>:                          Key Bindings.
+* function:                              Commands.
+* General Public License:                License.
+* getting help with keys:                Basic Help.
+* global keymap:                         Keymaps.
+* global substitution:                   Replace.
+* graphic characters:                    Inserting Text.
+* Greek:                                 Mule.
+* Gregorian calendar:                    Other Calendars.
+* grinding:                              Grinding.
+* hardcopy:                              Hardcopy.
+* header (TeX mode):                     TeX Print.
+* headers (of mail message):             Mail Headers.
+* heading lines (Outline mode):          Outline Format.
+* Hebrew calendar:                       Calendar Systems.
+* help:                                  Help.
+* Help menu <1>:                         Help Menu.
+* Help menu:                             Pull-down Menus.
+* hierarchies:                           Startup Paths.
+* history of commands:                   Repetition.
+* history of minibuffer input:           Minibuffer History.
+* holiday forms:                         Holiday Customizing.
+* holidays:                              Holidays.
+* horizontal scrolling:                  Horizontal Scrolling.
+* Icomplete mode:                        Completion Options.
+* ignoriginal:                           Dissociated Press.
+* indentation <1>:                       Comments.
+* indentation <2>:                       Grinding.
+* indentation:                           Indentation.
+* inferior process:                      Compilation.
+* Info:                                  Misc Help.
+* init file:                             Init File.
+* input methods:                         Input Methods.
+* Insert File... menu item:              File Menu.
+* inserting blank lines:                 Blank Lines.
+* insertion:                             Inserting Text.
+* install:                               Installing Packages.
+* installing packages:                   Installing Packages.
+* international scripts:                 Mule.
+* interval operator (in regexps):        Etags Regexps.
+* invisible lines:                       Outline Mode.
+* IPA:                                   Mule.
+* Islamic calendar:                      Calendar Systems.
+* ISO commercial calendar:               Calendar Systems.
+* italic font:                           Face Customization.
+* Japanese:                              Mule.
+* Julian calendar:                       Calendar Systems.
+* Julian day numbers:                    Calendar Systems.
+* justification:                         Fill Commands.
+* key rebinding, permanent:              Init File.
+* key rebinding, this session:           Rebinding.
+* keyboard macros:                       Keyboard Macros.
+* keycode:                               Super and Hyper Keys.
+* keymap <1>:                            Keymaps.
+* keymap:                                Commands.
+* keystroke:                             Intro to Keystrokes.
+* keysym:                                Intro to Keystrokes.
+* keysyms:                               Super and Hyper Keys.
+* Kill Buffer menu item:                 File Menu.
+* kill ring:                             Yanking.
+* killing:                               Killing.
+* killing characters and lines:          Erasing.
+* killing Emacs:                         Exiting.
+* Korean:                                Mule.
+* language environments:                 Language Environments.
+* last package hierarchies:              Startup Paths.
+* late package hierarchies:              Startup Paths.
+* LaTeX:                                 TeX Mode.
+* leaving Emacs:                         Exiting.
+* libraries:                             Lisp Libraries.
+* license to copy XEmacs:                License.
+* line number:                           Position Info.
+* line wrapping:                         Continuation Lines.
+* Lisp:                                  Programs.
+* Lisp mode:                             Program Modes.
+* list:                                  Lists.
+* loading libraries:                     Loading.
+* loading Lisp code:                     Lisp Libraries.
+* local keymap:                          Keymaps.
+* local variables:                       Locals.
+* local variables in files:              File Variables.
+* local.rules:                           Local.rules File.
+* locking and version control:           Concepts of VC.
+* log entry:                             Editing with VC.
+* mail <1>:                              Reading Mail.
+* mail:                                  Sending Mail.
+* major modes:                           Major Modes.
+* make:                                  Compilation.
+* manual package install:                Manually.
+* manuals, on-line:                      Misc Help.
+* mark:                                  Mark.
+* mark ring <1>:                         Mark and Region.
+* mark ring:                             Mark Ring.
+* Markov chain:                          Dissociated Press.
+* master file:                           Concepts of VC.
+* matching parentheses:                  Matching.
+* Mayan calendar:                        Calendar Systems.
+* Mayan calendar round:                  Mayan Calendar.
+* Mayan haab calendar:                   Mayan Calendar.
+* Mayan long count:                      Mayan Calendar.
+* Mayan tzolkin calendar:                Mayan Calendar.
+* menus <1>:                             Change Window.
+* menus:                                 Pull-down Menus.
+* message <1>:                           Reading Mail.
+* message:                               Sending Mail.
+* Meta:                                  Words.
+* minibuffer <1>:                        Keymaps.
+* minibuffer <2>:                        M-x.
+* minibuffer:                            Minibuffer.
+* minibuffer history:                    Minibuffer History.
+* minor modes:                           Minor Modes.
+* mistakes, correcting <1>:              Fixit.
+* mistakes, correcting:                  Undo.
+* mocklisp:                              Mocklisp.
+* mode hook:                             Program Modes.
+* mode line <1>:                         Minor Modes.
+* mode line:                             Mode Line.
+* mode, Term:                            Term Mode.
+* modified (buffer):                     Visiting.
+* modifier key:                          Intro to Keystrokes.
+* modifier mapping:                      Super and Hyper Keys.
+* moon, phases of:                       Lunar Phases.
+* mouse operations:                      Additional Mouse Operations.
+* mouse selection:                       Mouse Selection.
+* movement:                              Moving Point.
+* moving inside the calendar:            Calendar Motion.
+* moving point:                          Moving Point.
+* moving text:                           Yanking.
+* moving the cursor:                     Moving Point.
+* MULE:                                  Mule.
+* multi-frame XEmacs:                    XEmacs under X.
+* multibyte characters:                  Mule.
+* named configurations (RCS):            Snapshot Caveats.
+* narrowing:                             Narrowing.
+* New Frame menu item:                   File Menu.
+* newline:                               Inserting Text.
+* non-incremental search:                Non-Incremental Search.
+* nroff:                                 Nroff Mode.
+* numeric arguments:                     Arguments.
+* omer count:                            Sexp Diary Entries.
+* on-line manuals:                       Misc Help.
+* Open File, New Frame... menu item:     File Menu.
+* Open File... menu item:                File Menu.
+* option <1>:                            Examining.
+* option:                                Variables.
+* Options menu <1>:                      Options Menu.
+* Options menu:                          Pull-down Menus.
+* other editors:                         Emulation.
+* outlines:                              Outline Mode.
+* outragedy:                             Dissociated Press.
+* Overstrike menu item:                  Options Menu.
+* Overwrite mode:                        Minor Modes.
+* package building:                      Building Packages.
+* package distributions:                 Package Terminology.
+* package hierarchies:                   Startup Paths.
+* package path:                          Startup Paths.
+* package tools:                         Automatically.
+* packages <1>:                          Available Packages.
+* packages:                              Packages.
+* page number:                           Position Info.
+* pages:                                 Pages.
+* paragraphs:                            Paragraphs.
+* parasha, weekly:                       Sexp Diary Entries.
+* Paren Highlighting menu item:          Options Menu.
+* parentheses:                           Matching.
+* Paste menu item:                       Edit Menu.
+* pasting:                               Yanking.
+* path:                                  Startup Paths.
+* paths:                                 Startup Paths.
+* per-buffer variables:                  Locals.
+* Persian calendar:                      Calendar Systems.
+* phases of the moon:                    Lunar Phases.
+* pictures:                              Picture.
+* point <1>:                             Inserting Text.
+* point:                                 Point.
+* pointer face:                          Mouse Selection.
+* pointer shapes:                        Mouse Selection.
+* prefix key sequence:                   Key Sequences.
+* presidentagon:                         Dissociated Press.
+* primary selections:                    X Selection Commands.
+* Print Buffer menu item:                File Menu.
+* prompt:                                Minibuffer.
+* properbose:                            Dissociated Press.
+* Pull-down Menus <1>:                   Change Window.
+* Pull-down Menus:                       Pull-down Menus.
+* query replace:                         Query Replace.
+* quitting:                              Quitting.
+* quitting (in search):                  Incremental Search.
+* quitting Emacs:                        Exiting.
+* quoting:                               Inserting Text.
+* random sentences:                      CONX.
+* RCS:                                   Concepts of VC.
+* Read Only menu item:                   Options Menu.
+* read-only buffer:                      Misc Buffer.
+* rebinding keys, permanently:           Init File.
+* rebinding keys, this session:          Rebinding.
+* rectangle <1>:                         Rectangles in Picture.
+* rectangle:                             RegRect.
+* rectangles:                            Rectangles.
+* recursive editing level <1>:           Quitting.
+* recursive editing level:               Recursive Edit.
+* redefining keys:                       Key Bindings Using Strings.
+* regexp:                                Regexp Search.
+* regexp alternative:                    Regexps.
+* regexp grouping:                       Regexps.
+* region <1>:                            Case.
+* region:                                Mark.
+* registered file:                       Concepts of VC.
+* registers:                             Registers.
+* regular expression:                    Regexp Search.
+* regular packages:                      Package Terminology.
+* remote files:                          Files.
+* removing directories:                  File Names.
+* removing packages:                     Removing Packages.
+* replacement:                           Replace.
+* restriction:                           Narrowing.
+* Revert Buffer menu item:               File Menu.
+* root of a hierarchy:                   Startup Paths.
+* rosh hodesh:                           Sexp Diary Entries.
+* Russian:                               Mule.
+* Save Buffer As ... menu item:          File Menu.
+* Save Buffer menu item:                 File Menu.
+* Save Options:                          Options Menu.
+* saving:                                Visiting.
+* saving option value:                   Changing an Option.
+* SCCS:                                  Concepts of VC.
+* Scheme mode:                           Program Modes.
+* scrolling:                             Scrolling.
+* scrolling in the calendar:             Scroll Calendar.
+* searching:                             Search.
+* selected buffer:                       Buffers.
+* selected window:                       Basic Window.
+* selective display:                     Outline Mode.
+* self-documentation:                    Help.
+* sentences:                             Sentences.
+* setting option value:                  Changing an Option.
+* setting variables:                     Examining.
+* sexp:                                  Lists.
+* sexp diary entries:                    Sexp Diary Entries.
+* shell commands:                        Shell.
+* Shell mode:                            Shell Mode.
+* shift modifier:                        Representing Keystrokes.
+* shrinking XEmacs frame:                Exiting.
+* simultaneous editing:                  Interlocking.
+* single-file packages:                  Package Terminology.
+* site-specific directories:             Startup Paths.
+* Size menu item:                        Options Menu.
+* slashes repeated in file name:         Minibuffer File.
+* snapshots and version control:         Snapshots.
+* sorting:                               Sorting.
+* sorting diary entries:                 Fancy Diary Display.
+* source packages:                       Package Terminology.
+* spelling:                              Spelling.
+* Split Frame:                           File Menu.
+* Start Macro Recording menu item:       Edit Menu.
+* starting XEmacs:                       Entering Emacs.
+* startup paths:                         Startup Paths.
+* string substitution:                   Replace.
+* subshell:                              Shell.
+* subtree (Outline mode):                Outline Visibility.
+* sumo package install:                  Sumo.
+* sunrise and sunset:                    Sunrise/Sunset.
+* suspending:                            Exiting.
+* switching buffers:                     Select Buffer.
+* Syntax Highlighting menu item:         Options Menu.
+* syntax table <1>:                      Syntax.
+* syntax table:                          Words.
+* tags table:                            Tags.
+* tags, C++:                             Tags.
+* Teach Extended Commands menu item:     Options Menu.
+* techniquitous:                         Dissociated Press.
+* television:                            Appending Kills.
+* Term mode:                             Term Mode.
+* termscript file:                       Bugs.
+* TeX:                                   TeX Mode.
+* text:                                  Text.
+* Text mode:                             Text Mode.
+* Tools menu <1>:                        Tools Menu.
+* Tools menu:                            Pull-down Menus.
+* top level:                             Mode Line.
+* transposition <1>:                     Lists.
+* transposition <2>:                     Words.
+* transposition:                         Transpose.
+* truncation:                            Continuation Lines.
+* typos:                                 Fixit.
+* Un-split (Keep Others):                File Menu.
+* Un-split (Keep This):                  File Menu.
+* undo:                                  Undo.
+* Undo menu item:                        Edit Menu.
+* variable:                              Variables.
+* variables:                             Commands.
+* version control:                       Version Control.
+* version-specific directories:          Startup Paths.
+* vi:                                    Emulation.
+* viewing:                               Misc File Ops.
+* Viper:                                 Emulation.
+* visiting:                              Visiting.
+* visiting files:                        Visiting.
+* weeks, which day they start on:        Move to Beginning or End.
+* Weight menu item:                      Options Menu.
+* which packages:                        Which Packages.
+* widening:                              Narrowing.
+* window:                                Frame.
+* windows:                               Windows.
+* Windows menu:                          Change Window.
+* word search:                           Word Search.
+* words <1>:                             Case.
+* words <2>:                             Words.
+* words:                                 Fixing Case.
+* work file:                             Concepts of VC.
+* wrapping:                              Continuation Lines.
+* X resources:                           X Resources.
+* yahrzeits <1>:                         Sexp Diary Entries.
+* yahrzeits:                             From Other Calendar.
+* yanking:                               Yanking.
+* | in regexp:                           Regexps.

 
 

-\1f
-File: xemacs.info,  Node: Apropos,  Next: Library Keywords,  Prev: Name Help,  Up: Help
-
-Apropos
-=======
-
-`C-h A'
-     Show only symbols that are names of commands (`command-apropos').
-
-`M-x apropos REGEXP'
-     Show all symbols whose names contain matches for REGEXP.
-
-   A more sophisticated sort of question to ask is, "What are the
-commands for working with files?"  To ask this question, type `C-h a
-file <RET>', which displays a list of all command names that contain
-`file', including `copy-file', `find-file', and so on.  With each
-command name appears a brief description of how to use the command, and
-what keys you can currently invoke it with.  For example, it would say
-that you can invoke `find-file' by typing `C-x C-f'.  The `A' in `C-h
-A' stands for `Apropos'; `C-h A' runs the command `command-apropos'.
-This command normally checks only commands (interactive functions); if
-you specify a prefix argument, it checks noninteractive functions as
-well.
-
-   Because `C-h A' looks only for functions whose names contain the
-string you specify, you must use ingenuity in choosing the string.  If
-you are looking for commands for killing backwards and `C-h a
-kill-backwards <RET>' doesn't reveal any, don't give up.  Try just
-`kill', or just `backwards', or just `back'.  Be persistent.  Pretend
-you are playing Adventure.  Also note that you can use a regular
-expression as the argument, for more flexibility (*note Regexps::).
-
-   Here is a set of arguments to give to `C-h a' that covers many
-classes of XEmacs commands, since there are strong conventions for
-naming the standard XEmacs commands.  By giving you a feel for the
-naming conventions, this set should also serve to aid you in developing
-a technique for picking `apropos' strings.
-
-     char, line, word, sentence, paragraph, region, page, sexp, list,
-     defun, rect, buffer, frame, window, face, file, dir, register,
-     mode, beginning, end, forward, backward, next, previous, up, down,
-     search, goto, kill, delete, mark, insert, yank, fill, indent,
-     case, change, set, what, list, find, view, describe, default.
-
-   To list all Lisp symbols that contain a match for a regexp, not just
-the ones that are defined as commands, use the command `M-x apropos'
-instead of `C-h A'.  This command does not check key bindings by
-default; specify a numeric argument if you want it to check them.
-
-   The `apropos-documentation' command is like `apropos' except that it
-searches documentation strings for matches for the specified regular
-expression.
-
-   The `apropos-value' command is like `apropos' except that it
-searches symbols' values for matches for the specified regular
-expression.  This command does not check function definitions or
-property lists by default; specify a numeric argument if you want it to
-check them.
-
-   If the variable `apropos-do-all' is non-`nil', the commands above
-all behave as if they had been given a prefix argument.
-
-   If you want more information about a function definition, variable or
-symbol property listed in the Apropos buffer, you can click on it with
-`Mouse-2' or move there and type <RET>.

 
 

diff --git a/lib-src/ChangeLog b/lib-src/ChangeLog
index 2a80629..d5ffb05 100644 (file)
--- a/lib-src/ChangeLog
+++ b/lib-src/ChangeLog
@@ -1,3 +1,7 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/lib-src/Makefile.in.in b/lib-src/Makefile.in.in
index a90d682..30fbb7b 100644 (file)
--- a/lib-src/Makefile.in.in
+++ b/lib-src/Makefile.in.in
@@ -387,11 +387,11 @@ gnuserv: ${srcdir}/gnuserv.c gnuslib.o ${srcdir}/gnuserv.h
 ## mmencode binary is used by tm - but is really part of the metamail package
 ## mmencode.c was merged copy of mmencode.c and codes.c of metamail
 mmencode : ${srcdir}/mmencode.c
 ## mmencode binary is used by tm - but is really part of the metamail package
 ## mmencode.c was merged copy of mmencode.c and codes.c of metamail
 mmencode : ${srcdir}/mmencode.c

-       $(CC) $(cflags) ${srcdir}/mmencode.c -o $@
+       $(CC) $(cflags) ${srcdir}/mmencode.c $(ldflags) -o $@

 
 
 ## The timer utility (timer.c, getdate.y) is not used in XEmacs
 ## because XEmacs provides built-in timer facilities.
 
 make-path: ${srcdir}/make-path.c ../src/config.h
 
 
 ## The timer utility (timer.c, getdate.y) is not used in XEmacs
 ## because XEmacs provides built-in timer facilities.
 
 make-path: ${srcdir}/make-path.c ../src/config.h

-       $(CC) -Demacs $(cflags) ${srcdir}/make-path.c -o $@
+       $(CC) -Demacs $(cflags) ${srcdir}/make-path.c $(ldflags) -o $@

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index a21be94..8c84814 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,219 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+
+2003-12-12  Katsumi Yamaoka  <yamaoka@jpl.org>
+
+       * itimer.el (activate-itimer): Modify the itimer timeout value as
+       if it were begun at the last time when the itimer driver was woken
+       up.
+
+2004-01-27  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * specifier.el (Copyright):
+       Update.
+       (make-specifier-and-init):
+       (map-specifier):
+       (canonicalize-inst-pair):
+       (canonicalize-spec-list):
+       (set-specifier):
+       Synch docstrings to 21.5 where appropriate.
+
+2004-01-25  Steve Youngs  <sryoungs@bigpond.net.au>
+
+       * package-get.el (package-get-list-packages-where): New.  A
+       function that allows searching for groups of packages.  For
+       example, find all packages that require the fsf-compat package.
+
+2004-01-25  Steve Youngs  <youngs@xemacs.org>
+
+       The Great PUI Sync.
+
+       * auto-autoloads.el: Regenerated.
+
+       * custom-load.el: Regenerated.
+
+       * dumped-lisp.el (packages-hardcoded-lisp): New.
+
+       * menubar-items.el (menu-max-items): New.
+       (menu-submenu-max-items): New.
+       (menu-submenu-name-format): New.
+       (menu-split-long-menu): New.
+       (menu-sort-menu): New.
+       (default-menubar): Sync to 21.5 in regard to the PUI menus.
+
+       * obsolete.el (pui-add-install-directory): Renamed to the more
+       logical `pui-set-local-package-get-directory'.
+       (package-get-download-menu): Moved to `package-ui.el' and renamed
+       to `package-ui-add-download-menu'.
+
+       * package-admin.el (package-admin-install-function-mswindows):
+       Whitespace clean up.
+       (package-admin-add-single-file-package): Removed.
+       (package-admin-default-install-function): Whitespace clean up.
+       (package-admin-find-top-directory): New.
+       (package-admin-get-install-dir): Use it.
+       (package-admin-get-manifest-file): 
+       (package-admin-check-manifest): 
+       (package-admin-add-binary-package):
+       (package-admin-get-lispdir):
+       (package-admin-delete-binary-package):
+       (package-admin):
+
+       * package-get.el (package-get-package-index-file-location): New.
+       (package-get-install-to-user-init-directory): New.
+       (package-get-remote):
+       (package-get-download-sites):
+       (package-get-pre-release-download-sites): New.
+       (package-get-site-release-download-sites): New.
+       (package-get-base-filename):
+       (package-get-always-update):
+       (package-get-user-index-filename): Removed.
+       (package-get-pgp-available-p): New.
+       (package-get-require-signed-base-updates):
+       (package-get-was-current):
+       (package-entries-are-signed): New.
+       (package-get-continue-update-base): New.
+       (package-get-download-menu): Removed.
+       (package-get-require-base):
+       (package-get-update-base-entry):
+       (package-get-locate-file):
+       (package-get-locate-index-file):
+       (package-get-maybe-save-index):
+       (package-get-update-base):
+       (package-get-update-base-from-buffer):
+       (package-get-update-base-entries):
+       (package-get-interactive-package-query):
+       (package-get-update-all):
+       (package-get-all):
+       (package-get-dependencies):
+       (package-get-init-package):
+       (package-get-info): New.
+       (package-get):
+       (package-get-staging-dir):
+       (package-get-set-version-prop): Removed.
+       (package-get-installedp):
+       (package-get-ever-installed-p):
+       (packages): Removed.
+       (package-get-custom-groups): Removed.
+       (package-get-custom): Removed.
+       (package-get-custom-add-entry): Removed.
+
+       * package-info.el (batch-update-package-info):
+
+       * package-net.el (package-net-batch-generate-bin-ini):
+       (package-net-update-installed-db):
+
+       * package-ui.el (pui-info-buffer):
+       (pui-directory-exists): Removed.
+       (pui-package-dir-list): Removed.
+       (pui-add-install-directory): Removed.
+       (package-ui-download-menu): New.
+       (package-ui-pre-release-download-menu): New.
+       (package-ui-site-release-download-menu): New.
+       (pui-set-local-package-get-directory): New.
+       (pui-package-symbol-char):
+       (pui-update-package-display):
+       (pui-toggle-package):
+       (pui-toggle-package-key):
+       (pui-toggle-package-delete):
+       (pui-toggle-package-delete-key):
+       (pui-toggle-package-event):
+       (pui-toggle-verbosity-redisplay):
+       (pui-install-selected-packages):
+       (pui-add-required-packages):
+       (pui-help-echo):
+       (pui-display-info):
+       (list-packages-mode):
+       (pui-list-packages):
+
+       * packages.el (packages-compute-package-locations):
+       (package-require):
+       (package-delete-name):
+       (packages-hardcoded-lisp): Removed.
+       (packages-useful-lisp): Removed.
+       (packages-unbytecompiled-lisp): Removed.
+       (packages-find-package-directories):
+
+       Summary:
+
+       Major code clean up of all things PUI.
+
+       Much improved code to determine where packages should be
+       installed.  PUI no longer depends on any packages being
+       pre-installed to compute where packages are to be installed to.
+
+       The user can specify the location of their package-index file.  It
+       isn't necessary to set this because it has sane defaults.  People
+       who "run-in-place" won't accidently overwrite the CVS
+       package-index file.  See
+       `package-get-package-index-file-location'. 
+
+       PUI will now properly clean up after itself in the event of an
+       unsuccessful package install.  This drastically reduces the number
+       of "wrong md5sum" FAQs.
+
+       non-Mule XEmacsen can no longer install Mule packages.
+
+       Package management via the custom interface has been removed.
+
+       The PUI related menubar items have been reorganised.
+
+       The PGP verification code has been fixed and the default for
+       whether or not it is used is automatically computed.
+
+       * update-elc.el ((preloaded-file-list site-load-packages
+       need-to-dump dumped-exe)):
+       Just a couple of small changes to allow for
+       `packages-(hardcoded|useful|unbytecompiled)-lisp' not really
+       existing anymore.
+
+2003-12-10  Hrvoje Niksic  <hniksic@xemacs.org>
+
+       * bytecomp.el (byte-compile-warn-about-unused-variables): Don't
+       apply `format' to the first argument of byte-compile-warn, it
+       already calls format.
+
+2003-12-03  Adrian Aichner  <adrian@xemacs.org>
+
+       * files.el (delete-old-versions): Avoid going interactive during
+       make install when environment variable VERSION_CONTROL is set.
+
+2003-12-04  Vin Shelton  <acs@xemacs.org>
+
+       * menubar-items.el (menu-item-search): Only bring up search dialog
+       box if the feature is available and desired.
+
+2003-11-04  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * about.el (about-personal-info): Fix typo in Tony Rossini's entry.
+
+2003-11-05  Vin Shelton  <acs@xemacs.org>
+
+       * help.el (Help-prin1-face):
+       (Help-princ-face):
+       princ and prin1 are functions and need to be called as such.  The
+       idea for this patch was submitted by Eric Eide <eeide@cs.utah.edu>.
+
+2003-10-22  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * about.el (about-xemacs): Give full version and build date.
+
+2003-09-19  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * win32-native.el (grep-null-device): This XEmacs has null-device.
+
+2003-09-06  Mike Sperber  <mike@xemacs.org>
+
+       * bytecomp.el (byte-compile-defvar-or-defconst): Actually
+       implement the specified semantics for `defvar.'
+
+2003-09-07  Adrian Aichner  <adrian@xemacs.org>
+
+       * window-xemacs.el (display-buffer): Fix for `shrink-to-fit' by
+       Klaus Berndl, calling `shrink-window-if-larger-than-buffer' when
+       displaying buffer in question.
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/lisp/about.el b/lisp/about.el
index b55845f..3d1d5af 100644 (file)
--- a/lisp/about.el
+++ b/lisp/about.el
@@ -358,11 +358,27 @@
                   :format "%t"
                   :tag-glyph xemacs-logo)
     (widget-insert "\n")
                   :format "%t"
                   :tag-glyph xemacs-logo)
     (widget-insert "\n")

-    (let* ((emacs-short-version (format "%d.%d"
+    (let* ((emacs-short-version (format "%d.%d.%d"

                                        emacs-major-version
                                        emacs-major-version

-                                       emacs-minor-version))
-          (emacs-about-version (format "version %s; April 2001"
-                                       emacs-short-version)))
+                                       emacs-minor-version
+                                       emacs-patch-level))
+          (emacs-about-version (format "version %s; %s %s"
+                                       emacs-short-version
+                                       (cdr (assoc (substring emacs-build-time
+                                                              4 7)
+                                                   '(("Jan" . "January")
+                                                     ("Feb" . "February")
+                                                     ("Mar" . "March")
+                                                     ("Apr" . "April")
+                                                     ("May" . "May")
+                                                     ("Jun" . "June")
+                                                     ("Jul" . "July")
+                                                     ("Aug" . "August")
+                                                     ("Sep" . "September")
+                                                     ("Oct" . "October")
+                                                     ("Nov" . "November")
+                                                     ("Dec" . "December"))))
+                                       (substring emacs-build-time -4))))

       (widget-insert (about-center emacs-about-version))
       (widget-create 'link :help-echo "What's new in XEmacs"
                     :action 'about-news
       (widget-insert (about-center emacs-about-version))
       (widget-create 'link :help-echo "What's new in XEmacs"
                     :action 'about-news

@@ -1288,7 +1304,7 @@ Assistant Professor of Biostatistics at the University of Washington
 and the Fred Hutchinson Cancer Research Center.
 
 See ")
 and the Fred Hutchinson Cancer Research Center.
 
 See ")

-     (about-url-link 'rossini nil "Visit Anothony's home page")
+     (about-url-link 'rossini nil "Visit Anthony's home page")

      (widget-insert ".\n"))
     (slb
      (widget-insert "\
      (widget-insert ".\n"))
     (slb
      (widget-insert "\

diff --git a/lisp/auto-autoloads.el b/lisp/auto-autoloads.el
index 35096b5..4dc16b8 100644 (file)
--- a/lisp/auto-autoloads.el
+++ b/lisp/auto-autoloads.el
@@ -1446,21 +1446,14 @@ Enable mouse wheel support." t nil)
 
 ;;;***
 \f
 
 ;;;***
 \f

-;;;### (autoloads (package-admin-add-binary-package package-admin-add-single-file-package) "package-admin" "lisp/package-admin.el")
-
-(autoload 'package-admin-add-single-file-package "package-admin" "\
-Install a single file Lisp package into XEmacs package hierarchy.
-`file' should be the full path to the lisp file to install.
-`destdir' should be a simple directory name.
-The optional `pkg-dir' can be used to override the default package hierarchy
-\(car (last late-packages))." t nil)
+;;;### (autoloads (package-admin-add-binary-package) "package-admin" "lisp/package-admin.el")

 
 (autoload 'package-admin-add-binary-package "package-admin" "\
 Install a pre-bytecompiled XEmacs package into package hierarchy." t nil)
 
 ;;;***
 \f
 
 (autoload 'package-admin-add-binary-package "package-admin" "\
 Install a pre-bytecompiled XEmacs package into package hierarchy." t nil)
 
 ;;;***
 \f

-;;;### (autoloads (package-get-custom package-get-package-provider package-get package-get-dependencies package-get-all package-get-update-all package-get-delete-package package-get-save-base package-get-update-base-from-buffer package-get-update-base package-get-update-base-entry package-get-require-base package-get-download-menu) "package-get" "lisp/package-get.el")
+;;;### (autoloads (package-get-package-provider package-get package-get-list-packages-where package-get-info package-get-dependencies package-get-all package-get-update-all package-get-delete-package package-get-save-base package-get-update-base-from-buffer package-get-update-base package-get-update-base-entry package-get-require-base) "package-get" "lisp/package-get.el")

 
 (defvar package-get-base nil "\
 List of packages that are installed at this site.
 
 (defvar package-get-base nil "\
 List of packages that are installed at this site.

@@ -1508,10 +1501,15 @@ recent to least recent -- in other words, the version names don't have to
 be lexically ordered.  It is debatable if it makes sense to have more than
 one version of a package available.")
 
 be lexically ordered.  It is debatable if it makes sense to have more than
 one version of a package available.")
 

-(defcustom package-get-download-sites '(("Pre-Releases" "ftp.xemacs.org" "pub/xemacs/beta/experimental/packages") ("xemacs.org" "ftp.xemacs.org" "pub/xemacs/packages") ("ca.xemacs.org (Canada)" "ftp.ca.xemacs.org" "pub/Mirror/xemacs/packages") ("crc.ca (Canada)" "ftp.crc.ca" "pub/packages/editors/xemacs/packages") ("us.xemacs.org (United States)" "ftp.us.xemacs.org" "pub/xemacs/packages") ("ibiblio.org (United States)" "ibiblio.org" "pub/packages/editors/xemacs/packages") ("stealth.net (United States)" "ftp.stealth.net" "pub/mirrors/ftp.xemacs.org/pub/xemacs/packages") ("br.xemacs.org (Brazil)" "ftp.br.xemacs.org" "pub/xemacs/packages") ("at.xemacs.org (Austria)" "ftp.at.xemacs.org" "editors/xemacs/packages") ("be.xemacs.org (Belgium)" "ftp.be.xemacs.org" "xemacs/packages") ("cz.xemacs.org (Czech Republic)" "ftp.cz.xemacs.org" "MIRRORS/ftp.xemacs.org/pub/xemacs/packages") ("dk.xemacs.org (Denmark)" "ftp.dk.xemacs.org" "pub/emacs/xemacs/packages") ("fi.xemacs.org (Finland)" "ftp.fi.xemacs.org" "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/packages") ("fr.xemacs.org (France)" "ftp.fr.xemacs.org" "pub/xemacs/packages") ("pasteur.fr (France)" "ftp.pasteur.fr" "pub/computing/xemacs/packages") ("de.xemacs.org (Germany)" "ftp.de.xemacs.org" "pub/ftp.xemacs.org/tux/xemacs/packages") ("tu-darmstadt.de (Germany)" "ftp.tu-darmstadt.de" "pub/editors/xemacs/packages") ("ie.xemacs.org (Ireland)" "ftp.ie.xemacs.org" "mirrors/ftp.xemacs.org/pub/xemacs/packages") ("it.xemacs.org (Italy)" "ftp.it.xemacs.org" "unix/packages/XEMACS/packages") ("no.xemacs.org (Norway)" "ftp.no.xemacs.org" "pub/xemacs/packages") ("pl.xemacs.org (Poland)" "ftp.pl.xemacs.org" "pub/unix/editors/xemacs/packages") ("ru.xemacs.org (Russia)" "ftp.ru.xemacs.org" "pub/xemacs/packages") ("sk.xemacs.org (Slovakia)" "ftp.sk.xemacs.org" "pub/mirrors/xemacs/packages") ("se.xemacs.org (Sweden)" "ftp.se.xemacs.org" "pub/gnu/xemacs/packages") ("ch.xemacs.org (Switzerland)" "ftp.ch.xemacs.org" "mirror/xemacs/packages") ("uk.xemacs.org (United Kingdom)" "ftp.uk.xemacs.org" "sites/ftp.xemacs.org/pub/xemacs/packages") ("jp.xemacs.org (Japan)" "ftp.jp.xemacs.org" "pub/GNU/xemacs/packages") ("aist.go.jp (Japan)" "ring.aist.go.jp" "pub/text/xemacs/packages") ("asahi-net.or.jp (Japan)" "ring.asahi-net.or.jp" "pub/text/xemacs/packages") ("dti.ad.jp (Japan)" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/packages") ("jaist.ac.jp (Japan)" "ftp.jaist.ac.jp" "pub/GNU/xemacs/packages") ("nucba.ac.jp (Japan)" "mirror.nucba.ac.jp" "mirror/xemacs/packages") ("sut.ac.jp (Japan)" "sunsite.sut.ac.jp" "pub/archives/packages/xemacs/packages") ("kr.xemacs.org (Korea)" "ftp.kr.xemacs.org" "pub/tools/emacs/xemacs/packages") ("za.xemacs.org (South Africa)" "ftp.za.xemacs.org" "mirrorsites/ftp.xemacs.org/packages") ("sa.xemacs.org (Saudi Arabia)" "ftp.sa.xemacs.org" "pub/mirrors/ftp.xemacs.org/xemacs/packages") ("au.xemacs.org (Australia)" "ftp.au.xemacs.org" "pub/xemacs/packages") ("aarnet.edu.au (Australia)" "mirror.aarnet.edu.au" "pub/xemacs/packages") ("nz.xemacs.org (New Zealand)" "ftp.nz.xemacs.org" "mirror/ftp.xemacs.org/packages")) "*List of remote sites available for downloading packages.\nList format is '(site-description site-name directory-on-site).\nSITE-DESCRIPTION is a textual description of the site.  SITE-NAME\nis the internet address of the download site.  DIRECTORY-ON-SITE\nis the directory on the site in which packages may be found.\nThis variable is used to initialize `package-get-remote', the\nvariable actually used to specify package download sites." :tag "Package download sites" :type '(repeat (list (string :tag "Name") host-name directory)) :group 'package-get)
+(defcustom package-get-package-index-file-location (or (getenv "EMACSPACKAGEPATH") user-init-directory) "*The directory where the package-index file can be found." :type 'directory :group 'package-get)

 
 

-(autoload 'package-get-download-menu "package-get" "\
-Build the `Add Download Site' menu." nil nil)
+(defcustom package-get-install-to-user-init-directory nil "*If non-nil install packages under `user-init-directory'." :type 'boolean :group 'package-get)
+
+(defcustom package-get-download-sites '(("US (Main XEmacs Site)" "ftp.xemacs.org" "pub/xemacs/packages") ("Australia (aarnet.edu.au)" "mirror.aarnet.edu.au" "pub/xemacs/packages") ("Australia (au.xemacs.org)" "ftp.au.xemacs.org" "pub/xemacs/packages") ("Austria (at.xemacs.org)" "ftp.at.xemacs.org" "editors/xemacs/packages") ("Belgium (be.xemacs.org)" "ftp.be.xemacs.org" "xemacs/packages") ("Brazil (br.xemacs.org)" "ftp.br.xemacs.org" "pub/xemacs/packages") ("Canada (ca.xemacs.org)" "ftp.ca.xemacs.org" "pub/Mirror/xemacs/packages") ("Canada (crc.ca)" "ftp.crc.ca" "pub/packages/editors/xemacs/packages") ("Canada (ualberta.ca)" "sunsite.ualberta.ca" "pub/Mirror/xemacs/packages") ("Czech Republic (cz.xemacs.org)" "ftp.cz.xemacs.org" "MIRRORS/ftp.xemacs.org/pub/xemacs/packages") ("Denmark (dk.xemacs.org)" "ftp.dk.xemacs.org" "pub/emacs/xemacs/packages") ("Finland (fi.xemacs.org)" "ftp.fi.xemacs.org" "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/packages") ("France (fr.xemacs.org)" "ftp.fr.xemacs.org" "pub/xemacs/packages") ("France (mirror.cict.fr)" "mirror.cict.fr" "xemacs/packages") ("France (pasteur.fr)" "ftp.pasteur.fr" "pub/computing/xemacs/packages") ("Germany (de.xemacs.org)" "ftp.de.xemacs.org" "pub/ftp.xemacs.org/tux/xemacs/packages") ("Germany (tu-darmstadt.de)" "ftp.tu-darmstadt.de" "pub/editors/xemacs/packages") ("Ireland (ie.xemacs.org)" "ftp.ie.xemacs.org" "mirrors/ftp.xemacs.org/pub/xemacs/packages") ("Italy (it.xemacs.org)" "ftp.it.xemacs.org" "unix/packages/XEMACS/packages") ("Japan (aist.go.jp)" "ring.aist.go.jp" "pub/text/xemacs/packages") ("Japan (asahi-net.or.jp)" "ring.asahi-net.or.jp" "pub/text/xemacs/packages") ("Japan (dti.ad.jp)" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/packages") ("Japan (jaist.ac.jp)" "ftp.jaist.ac.jp" "pub/GNU/xemacs/packages") ("Japan (jp.xemacs.org)" "ftp.jp.xemacs.org" "pub/GNU/xemacs/packages") ("Japan (nucba.ac.jp)" "mirror.nucba.ac.jp" "mirror/xemacs/packages") ("Japan (sut.ac.jp)" "sunsite.sut.ac.jp" "pub/archives/packages/xemacs/packages") ("Korea (kr.xemacs.org)" "ftp.kr.xemacs.org" "pub/tools/emacs/xemacs/packages") ("New Zealand (nz.xemacs.org)" "ftp.nz.xemacs.org" "mirror/ftp.xemacs.org/packages") ("Norway (no.xemacs.org)" "ftp.no.xemacs.org" "pub/xemacs/packages") ("Poland (pl.xemacs.org)" "ftp.pl.xemacs.org" "pub/unix/editors/xemacs/packages") ("Russia (ru.xemacs.org)" "ftp.ru.xemacs.org" "pub/xemacs/packages") ("Slovakia (sk.xemacs.org)" "ftp.sk.xemacs.org" "pub/mirrors/xemacs/packages") ("South Africa (za.xemacs.org)" "ftp.za.xemacs.org" "mirrorsites/ftp.xemacs.org/packages") ("Sweden (se.xemacs.org)" "ftp.se.xemacs.org" "pub/gnu/xemacs/packages") ("Switzerland (ch.xemacs.org)" "ftp.ch.xemacs.org" "mirror/xemacs/packages") ("UK (uk.xemacs.org)" "ftp.uk.xemacs.org" "sites/ftp.xemacs.org/pub/xemacs/packages") ("US (ibiblio.org)" "ibiblio.org" "pub/packages/editors/xemacs/packages") ("US (stealth.net)" "ftp.stealth.net" "pub/mirrors/ftp.xemacs.org/pub/xemacs/packages") ("US (unc.edu)" "metalab.unc.edu" "pub/packages/editors/xemacs/packages") ("US (us.xemacs.org)" "ftp.us.xemacs.org" "pub/xemacs/packages") ("US (utk.edu)" "ftp.sunsite.utk.edu" "pub/xemacs/packages")) "*List of remote sites available for downloading packages.\nList format is '(site-description site-name directory-on-site).\nSITE-DESCRIPTION is a textual description of the site.  SITE-NAME\nis the internet address of the download site.  DIRECTORY-ON-SITE\nis the directory on the site in which packages may be found.\nThis variable is used to initialize `package-get-remote', the\nvariable actually used to specify package download sites." :tag "Package download sites" :type '(repeat (list (string :tag "Name") host-name directory)) :group 'package-get)
+
+(defcustom package-get-pre-release-download-sites '(("Pre-Releases (Main XEmacs Site)" "ftp.xemacs.org" "pub/xemacs/beta/experimental/packages") ("Australia Pre-Releases (aarnet.edu.au)" "mirror.aarnet.edu.au" "pub/xemacs/beta/experimental/packages") ("Australia Pre-Releases (au.xemacs.org)" "ftp.au.xemacs.org" "pub/xemacs/beta/experimental/packages") ("Austria Pre-Releases (at.xemacs.org)" "ftp.at.xemacs.org" "editors/xemacs/beta/experimentsl/packages") ("Brazil Pre-Releases (br.xemacs.org)" "ftp.br.xemacs.org" "pub/xemacs/xemacs-21.5/experimental/packages") ("Canada Pre-Releases (ca.xemacs.org)" "ftp.ca.xemacs.org" "pub/Mirror/xemacs/beta/experimental/packages") ("Canada Pre-Releases (crc.ca)" "ftp.crc.ca" "pub/packages/editors/xemacs/beta/experimental/packages") ("Canada Pre-Releases (ualberta.ca)" "sunsite.ualberta.ca" "pub/Mirror/xemacs/beta/experimental/packages") ("Czech Republic Pre-Releases (cz.xemacs.org)" "ftp.cz.xemacs.org" "MIRRORS/ftp.xemacs.org/pub/xemacs/xemacs-21.5/experimental/packages") ("Denmark Pre-Releases (dk.xemacs.org)" "ftp.dk.xemacs.org" "pub/emacs/xemacs/beta/experimental/packages") ("Finland Pre-Releases (fi.xemacs.org)" "ftp.fi.xemacs.org" "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/beta/experimental/packages") ("France Pre-Releases (fr.xemacs.org)" "ftp.fr.xemacs.org" "pub/xemacs/beta/experimental/packages") ("France Pre-Releases (mirror.cict.fr)" "mirror.cict.fr" "xemacs/beta/experimental/packages") ("France Pre-Releases (pasteur.fr)" "ftp.pasteur.fr" "pub/computing/xemacs/beta/experimental/packages") ("Germany Pre-Releases (de.xemacs.org)" "ftp.de.xemacs.org" "pub/ftp.xemacs.org/tux/xemacs/beta/experimental/packages") ("Germany Pre-Releases (tu-darmstadt.de)" "ftp.tu-darmstadt.de" "pub/editors/xemacs/beta/experimental/packages") ("Ireland Pre-Releases (ie.xemacs.org)" "ftp.ie.xemacs.org" "mirrors/ftp.xemacs.org/pub/xemacs/beta/experimental/packages") ("Italy Pre-Releases (it.xemacs.org)" "ftp.it.xemacs.org" "unix/packages/XEMACS/beta/experimental/packages") ("Japan Pre-Releases (aist.go.jp)" "ring.aist.go.jp" "pub/text/xemacs/beta/experimental/packages") ("Japan Pre-Releases (asahi-net.or.jp)" "ring.asahi-net.or.jp" "pub/text/xemacs/beta/experimental/packages") ("Japan Pre-Releases (dti.ad.jp)" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/beta/experimental/packages") ("Japan Pre-Releases (jaist.ac.jp)" "ftp.jaist.ac.jp" "pub/GNU/xemacs/beta/experimental/packages") ("Japan Pre-Releases (jp.xemacs.org)" "ftp.jp.xemacs.org" "pub/GNU/xemacs/beta/experimental/packages") ("Japan Pre-Releases (sut.ac.jp)" "sunsite.sut.ac.jp" "pub/archives/packages/xemacs/xemacs-21.5/experimental/packages") ("New Zealand Pre-Releases (nz.xemacs.org)" "ftp.nz.xemacs.org" "mirror/ftp.xemacs.org/packages") ("Norway Pre-Releases (no.xemacs.org)" "ftp.no.xemacs.org" "pub/xemacs/beta/experimental/packages") ("Poland Pre-Releases (pl.xemacs.org)" "ftp.pl.xemacs.org" "pub/unix/editors/xemacs/beta/experimental/packages") ("Russia Pre-Releases (ru.xemacs.org)" "ftp.ru.xemacs.org" "pub/xemacs/beta/experimental/packages") ("Saudi Arabia Pre-Releases (sa.xemacs.org)" "ftp.sa.xemacs.org" "pub/mirrors/ftp.xemacs.org/xemacs/xemacs-21.5/experimental/packages") ("Slovakia Pre-Releases (sk.xemacs.org)" "ftp.sk.xemacs.org" "pub/mirrors/xemacs/beta/experimental/packages") ("South Africa Pre-Releases (za.xemacs.org)" "ftp.za.xemacs.org" "mirrorsites/ftp.xemacs.org/beta/experimental/packages") ("Sweden Pre-Releases (se.xemacs.org)" "ftp.se.xemacs.org" "pub/gnu/xemacs/beta/experimental/packages") ("Switzerland Pre-Releases (ch.xemacs.org)" "ftp.ch.xemacs.org" "mirror/xemacs/beta/experimental/packages") ("UK Pre-Releases (uk.xemacs.org)" "ftp.uk.xemacs.org" "sites/ftp.xemacs.org/pub/xemacs/beta/experimental/packages") ("US Pre-Releases (ibiblio.org)" "ibiblio.org" "pub/packages/editors/xemacs/beta/experimental/packages") ("US Pre-Releases (stealth.net)" "ftp.stealth.net" "pub/mirrors/ftp.xemacs.org/pub/xemacs/beta/experimental/packages") ("US Pre-Releases (unc.edu)" "metalab.unc.edu" "pub/packages/editors/xemacs/beta/experimental/packages") ("US Pre-Releases (us.xemacs.org)" "ftp.us.xemacs.org" "pub/xemacs/beta/experimental/packages") ("US Pre-Releases (utk.edu)" "ftp.sunsite.utk.edu" "pub/xemacs/beta/experimental/packages")) "*List of remote sites available for downloading \"Pre-Release\" packages.\nList format is '(site-description site-name directory-on-site).\nSITE-DESCRIPTION is a textual description of the site.  SITE-NAME\nis the internet address of the download site.  DIRECTORY-ON-SITE\nis the directory on the site in which packages may be found.\nThis variable is used to initialize `package-get-remote', the\nvariable actually used to specify package download sites." :tag "Pre-Release Package download sites" :type '(repeat (list (string :tag "Name") host-name directory)) :group 'package-get)
+
+(defcustom package-get-site-release-download-sites nil "*List of remote sites available for downloading \"Site Release\" packages.\nList format is '(site-description site-name directory-on-site).\nSITE-DESCRIPTION is a textual description of the site.  SITE-NAME\nis the internet address of the download site.  DIRECTORY-ON-SITE\nis the directory on the site in which packages may be found.\nThis variable is used to initialize `package-get-remote', the\nvariable actually used to specify package download sites." :tag "Site Release Package download sites" :type '(repeat (list (string :tag "Name") host-name directory)) :group 'package-get)

 
 (autoload 'package-get-require-base "package-get" "\
 Require that a package-get database has been loaded.
 
 (autoload 'package-get-require-base "package-get" "\
 Require that a package-get database has been loaded.

@@ -1565,6 +1563,71 @@ Uses `package-get-base' to determine just what is required and what
 package provides that functionality.  Returns the list of packages
 required by PACKAGES." nil nil)
 
 package provides that functionality.  Returns the list of packages
 required by PACKAGES." nil nil)
 

+(autoload 'package-get-info "package-get" "\
+Get information about a package.
+
+Quite similar to `package-get-info-prop', but can retrieve a lot more
+information.
+
+Argument PACKAGE is the name of an XEmacs package (a symbol).  It must
+be a valid package, ie, a member of `package-get-base'.
+
+Argument INFORMATION is a symbol that can be any one of:
+
+   standards-version     Package system version (not used).
+   version               Version of the XEmacs package.
+   author-version        The upstream version of the package.
+   date                  The date the package was last modified.
+   build-date            The date the package was last built.
+   maintainer            The maintainer of the package.
+   distribution          Will always be \"xemacs\" (not used).
+   priority              \"low\", \"medium\", or \"high\" (not used).
+   category              Either \"standard\", \"mule\", or \"unsupported\"..
+   dump                  Is the package dumped (not used).
+   description           A description of the package.
+   filename              The filename of the binary tarball of the package.
+   md5sum                The md5sum of filename.
+   size                  The size in bytes of filename.
+   provides              A list of symbols that this package provides.
+   requires              A list of packages that this package requires.
+   type                  Can be either \"regular\" or \"single-file\".
+
+If optional argument ARG is non-nil insert INFORMATION into current
+buffer at point.  This is very useful for doing things like inserting
+a maintainer's email address into a mail buffer.
+
+If optional argument REMOTE is non-nil use a package list from a
+remote site.  For this to work `package-get-remote' must be non-nil.
+
+If this function is called interactively it will display INFORMATION
+in the minibuffer." t nil)
+
+(autoload 'package-get-list-packages-where "package-get" "\
+Return a list of packages that fulfill certain criteria.
+
+Argument ITEM, a symbol, is what you want to check for.  ITEM must be a
+symbol even when it doesn't make sense to be a symbol (think, searching
+maintainers, descriptions, etc).  The function will convert the symbol
+to a string if a string is what is needed.  The downside to this is that
+ITEM can only ever be a single word.
+
+Argument FIELD, a symbol, is the field to check in.  You can specify
+any one of:
+
+      Field            Sane or Allowable Content
+    description          any single word
+    category             `standard' or `mule'
+    maintainer           any single word
+    build-date           yyyy-mm-dd
+    date                 yyyy-mm-dd
+    type                 `regular' or `single'
+    requires             any package name
+    provides             any symbol
+    priority             `low', `medium', or `high'
+
+Optional Argument ARG, a prefix arg, insert output at point in the
+current buffer." t nil)
+

 (autoload 'package-get "package-get" "\
 Fetch PACKAGE from remote site.
 Optional arguments VERSION indicates which version to retrieve, nil
 (autoload 'package-get "package-get" "\
 Fetch PACKAGE from remote site.
 Optional arguments VERSION indicates which version to retrieve, nil

@@ -1577,8 +1640,7 @@ fetched packages should be installed.
 
 The value of `package-get-base' is used to determine what files should
 be retrieved.  The value of `package-get-remote' is used to determine
 
 The value of `package-get-base' is used to determine what files should
 be retrieved.  The value of `package-get-remote' is used to determine

-where a package should be retrieved from.  The sites are tried in
-order so one is better off listing easily reached sites first.
+where a package should be retrieved from.

 
 Once the package is retrieved, its md5 checksum is computed.  If that
 sum does not match that stored in `package-get-base' for this version
 
 Once the package is retrieved, its md5 checksum is computed.  If that
 sum does not match that stored in `package-get-base' for this version

@@ -1597,9 +1659,6 @@ Search for a package that provides SYM and return the name and
 If FORCE-CURRENT is non-nil make sure the database is up to date. This might
 lead to Emacs accessing remote sites." t nil)
 
 If FORCE-CURRENT is non-nil make sure the database is up to date. This might
 lead to Emacs accessing remote sites." t nil)
 

-(autoload 'package-get-custom "package-get" "\
-Fetch and install the latest versions of all customized packages." t nil)
-

 ;;;***
 \f
 ;;;### (autoloads (package-net-update-installed-db package-net-setup-directory) "package-net" "lisp/package-net.el")
 ;;;***
 \f
 ;;;### (autoloads (package-net-update-installed-db package-net-setup-directory) "package-net" "lisp/package-net.el")

@@ -1613,13 +1672,22 @@ DESTDIR defaults to the value of `package-net-setup-directory'." nil nil)
 
 ;;;***
 \f
 
 ;;;***
 \f

-;;;### (autoloads (pui-list-packages pui-add-install-directory package-ui-add-site) "package-ui" "lisp/package-ui.el")
+;;;### (autoloads (pui-list-packages pui-set-local-package-get-directory package-ui-site-release-download-menu package-ui-pre-release-download-menu package-ui-download-menu package-ui-add-site) "package-ui" "lisp/package-ui.el")

 
 (autoload 'package-ui-add-site "package-ui" "\
 Add site to package-get-remote and possibly offer to update package list." nil nil)
 
 
 (autoload 'package-ui-add-site "package-ui" "\
 Add site to package-get-remote and possibly offer to update package list." nil nil)
 

-(autoload 'pui-add-install-directory "package-ui" "\
-Add a new package binary directory to the head of `package-get-remote'.
+(autoload 'package-ui-download-menu "package-ui" "\
+Build the `Add Download Site' menu." nil nil)
+
+(autoload 'package-ui-pre-release-download-menu "package-ui" "\
+Build the 'Pre-Release Download Sites' menu." nil nil)
+
+(autoload 'package-ui-site-release-download-menu "package-ui" "\
+Build the 'Site Release Download Sites' menu." nil nil)
+
+(autoload 'pui-set-local-package-get-directory "package-ui" "\
+Set a new package binary directory in `package-get-remote'.

 Note that no provision is made for saving any changes made by this function.
 It exists mainly as a convenience for one-time package installations from
 disk." t nil)
 Note that no provision is made for saving any changes made by this function.
 It exists mainly as a convenience for one-time package installations from
 disk." t nil)

diff --git a/lisp/bytecomp.el b/lisp/bytecomp.el
index c1cc824..d467d54 100644 (file)
--- a/lisp/bytecomp.el
+++ b/lisp/bytecomp.el
@@ -1284,7 +1284,7 @@ otherwise pop it")
     (setq unreferenced (nreverse unreferenced))
     (while unreferenced
       (byte-compile-warn
     (setq unreferenced (nreverse unreferenced))
     (while unreferenced
       (byte-compile-warn

-       (format "variable %s bound but not referenced" (car unreferenced)))
+       "variable %s bound but not referenced" (car unreferenced))

       (setq unreferenced (cdr unreferenced)))))
 
 \f
       (setq unreferenced (cdr unreferenced)))))
 
 \f

@@ -3869,7 +3869,7 @@ If FORM is a lambda or a macro, byte-compile it as a function."
              ;; `defconst' sets `var' unconditionally.
              `(setq ,var ,value)
            ;; `defvar' sets `var' only when unbound.
              ;; `defconst' sets `var' unconditionally.
              `(setq ,var ,value)
            ;; `defvar' sets `var' only when unbound.

-           `(if (not (boundp ',var)) (setq ,var ,value))))
+           `(if (not (default-boundp ',var)) (set-default ',var ,value))))

       `',var))))
 
 (defun byte-compile-autoload (form)
       `',var))))
 
 (defun byte-compile-autoload (form)

diff --git a/lisp/custom-load.el b/lisp/custom-load.el
index b0e7ad7..4d2a113 100644 (file)
--- a/lisp/custom-load.el
+++ b/lisp/custom-load.el
@@ -73,7 +73,7 @@
 (custom-add-loads 'fill '("simple" "fill"))
 (custom-add-loads 'custom-magic-faces '("cus-edit"))
 (custom-add-loads 'display '("modeline" "auto-show" "scrollbar" "toolbar"))
 (custom-add-loads 'fill '("simple" "fill"))
 (custom-add-loads 'custom-magic-faces '("cus-edit"))
 (custom-add-loads 'display '("modeline" "auto-show" "scrollbar" "toolbar"))

-(custom-add-loads 'faces '("faces" "font" "cus-edit" "font-lock" "hyper-apropos" "info" "wid-edit"))
+(custom-add-loads 'faces '("faces" "cus-edit" "font-lock" "font" "hyper-apropos" "info" "wid-edit"))

 (custom-add-loads 'emacs '("faces" "help" "files" "cus-edit" "package-get"))
 (custom-add-loads 'processes '("process" "gnuserv"))
 (custom-add-loads 'hyper-apropos '("hyper-apropos"))
 (custom-add-loads 'emacs '("faces" "help" "files" "cus-edit" "package-get"))
 (custom-add-loads 'processes '("process" "gnuserv"))
 (custom-add-loads 'hyper-apropos '("hyper-apropos"))

diff --git a/lisp/dumped-lisp.el b/lisp/dumped-lisp.el
index 731eef2..f348942 100644 (file)
--- a/lisp/dumped-lisp.el
+++ b/lisp/dumped-lisp.el
@@ -1,3 +1,11 @@
+(defvar packages-hardcoded-lisp
+  '(
+    ;; Nothing at this time
+    )
+  "Lisp packages that are always dumped with XEmacs.
+This includes every package that is loaded directly by a package listed
+in dumped-lisp.el and is not itself listed.")
+

 (setq preloaded-file-list
       (assemble-list
         "backquote"            ; needed for defsubst etc.
 (setq preloaded-file-list
       (assemble-list
         "backquote"            ; needed for defsubst etc.

diff --git a/lisp/files.el b/lisp/files.el
index 9bdd6d4..e1c32f6 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -198,7 +198,7 @@ nil means make them for files that have some already.
 ;(defvar dired-kept-versions 2
 ;  "*When cleaning directory, number of versions to keep.")
 
 ;(defvar dired-kept-versions 2
 ;  "*When cleaning directory, number of versions to keep.")
 

-(defcustom delete-old-versions nil
+(defcustom delete-old-versions (when noninteractive 'leave)

   "*If t, delete excess backup versions silently.
 If nil, ask confirmation.  Any other value prevents any trimming."
   :type '(choice (const :tag "Delete" t)
   "*If t, delete excess backup versions silently.
 If nil, ask confirmation.  Any other value prevents any trimming."
   :type '(choice (const :tag "Delete" t)

diff --git a/lisp/help.el b/lisp/help.el
index 1835b7d..3bde4cd 100644 (file)
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1095,7 +1095,7 @@ part of the documentation of internal subroutines."
           (princ object)
           (put-nonduplicable-text-property
            pos (marker-position standard-output) 'face face buf)))
           (princ object)
           (put-nonduplicable-text-property
            pos (marker-position standard-output) 'face face buf)))

-       (t princ object)))
+       (t (princ object))))

 
 ;; replacement for `prin1' that puts the text in the specified face,
 ;; if possible
 
 ;; replacement for `prin1' that puts the text in the specified face,
 ;; if possible

@@ -1111,7 +1111,7 @@ part of the documentation of internal subroutines."
           (prin1 object)
           (put-nonduplicable-text-property
            pos (marker-position standard-output) 'face face buf)))
           (prin1 object)
           (put-nonduplicable-text-property
            pos (marker-position standard-output) 'face face buf)))

-       (t prin1 object)))
+       (t (prin1 object))))

 
 (defvar help-symbol-regexp
   (let ((sym-char "[+a-zA-Z0-9_:*]")
 
 (defvar help-symbol-regexp
   (let ((sym-char "[+a-zA-Z0-9_:*]")

diff --git a/lisp/info.el b/lisp/info.el
index 8296b9c..41cfc46 100644 (file)
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -1510,7 +1510,7 @@ versions of NAME. Only the suffixes are tried."
                           (format (cdr (car suff)) file)
                         (concat (cdr (car suff)) " < " file))))
          (message "%s..." command)
                           (format (cdr (car suff)) file)
                         (concat (cdr (car suff)) " < " file))))
          (message "%s..." command)

-         (call-process shell-file-name nil t nil "-c" command)
+         (call-process shell-file-name nil t nil shell-command-switch command)

          (message "")
          (when visit
            (setq buffer-file-name file)
          (message "")
          (when visit
            (setq buffer-file-name file)

diff --git a/lisp/itimer.el b/lisp/itimer.el
index 705df24..6c2d793 100644 (file)
--- a/lisp/itimer.el
+++ b/lisp/itimer.el
@@ -406,6 +406,14 @@ its FUNCTION will be called when it expires, and so on."
        (error "itimer named \"%s\" already existing and activated"
               (itimer-name itimer))))
   (let ((inhibit-quit t))
        (error "itimer named \"%s\" already existing and activated"
               (itimer-name itimer))))
   (let ((inhibit-quit t))

+    (if itimer-timer
+       ;; Modify the itimer timeout value as if it were begun
+       ;; at the last time when the itimer driver was woken up.
+       (set-itimer-value
+        itimer
+        (+ (itimer-value itimer)
+           (itimer-time-difference (current-time)
+                                   itimer-timer-last-wakeup))))

     ;; add the itimer to the global list
     (setq itimer-list (cons itimer itimer-list))
     ;; If the itimer process is scheduled to wake up too late for
     ;; add the itimer to the global list
     (setq itimer-list (cons itimer itimer-list))
     ;; If the itimer process is scheduled to wake up too late for

diff --git a/lisp/menubar-items.el b/lisp/menubar-items.el
index 1c410a3..58473b9 100644 (file)
--- a/lisp/menubar-items.el
+++ b/lisp/menubar-items.el
@@ -128,6 +128,95 @@ which will not be used as accelerators."
             "")))
        (t "")))
 
             "")))
        (t "")))
 

+(defcustom menu-max-items 25
+  "*Maximum number of items in generated menus.
+If number of entries in such a menu is larger than this value, split menu
+into submenus of nearly equal length (see `menu-submenu-max-items').  If
+nil, never split menu into submenus."
+  :group 'menu
+  :type '(choice (const :tag "no submenus" nil)
+                (integer)))
+
+(defcustom menu-submenu-max-items 20
+  "*Maximum number of items in submenus when splitting menus.
+We split large menus into submenus of this many items, and then balance
+them out as much as possible (otherwise the last submenu may have very few
+items)."
+  :group 'menu
+  :type 'integer)
+
+(defcustom menu-submenu-name-format "%-12.12s ... %.12s"
+  "*Format specification of the submenu name when splitting menus.
+Used by `menu-split-long-menu' if the number of entries in a menu is
+larger than `menu-menu-max-items'.
+This string should contain one %s for the name of the first entry and
+one %s for the name of the last entry in the submenu.
+If the value is a function, it should return the submenu name.  The
+function is be called with two arguments, the names of the first and
+the last entry in the menu."
+  :group 'menu
+  :type '(choice (string :tag "Format string")
+                (function)))
+
+(defun menu-split-long-menu (menu)
+  "Split MENU according to `menu-max-items' and add accelerator specs.
+
+You should normally use the idiom
+
+\(menu-split-long-menu (menu-sort-menu menu))
+
+See also `menu-sort-menu'."
+  (let ((len (length menu)))
+    (if (or (null menu-max-items)
+           (<= len menu-max-items))
+       (submenu-generate-accelerator-spec menu)
+      (let* ((outer (/ (+ len (1- menu-submenu-max-items))
+                      menu-submenu-max-items))
+            (inner (/ (+ len (1- outer)) outer))
+            (result nil))
+       (while menu
+         (let ((sub nil)
+               (from (car menu)))
+           (dotimes (foo (min inner len))
+             (setq sub  (cons (car menu) sub)
+                   menu (cdr menu)))
+           (setq len (- len inner))
+           (let ((to (car sub)))
+             (setq sub (nreverse sub))
+             (setq result
+                   (cons (cons (if (stringp menu-submenu-name-format)
+                                   (format menu-submenu-name-format
+                                           (menu-item-strip-accelerator-spec
+                                            (aref from 0))
+                                           (menu-item-strip-accelerator-spec
+                                            (aref to 0)))
+                                 (funcall menu-submenu-name-format
+                                          (menu-item-strip-accelerator-spec
+                                           (aref from 0))
+                                          (menu-item-strip-accelerator-spec
+                                           (aref to 0))))
+                               (submenu-generate-accelerator-spec sub))
+                         result)))))
+       (submenu-generate-accelerator-spec (nreverse result))))))
+
+(defun menu-sort-menu (menu)
+  "Sort MENU alphabetically.
+
+You should normally use the idiom
+
+\(menu-split-long-menu (menu-sort-menu menu))
+
+See also `menu-split-long-menu'."
+  (sort menu
+       #'(lambda (a b) (string-lessp (aref a 0) (aref b 0)))))
+
+(defun menu-item-search ()
+  "Bring up a search dialog if possible and desired, else do interactive search"
+  (interactive)
+  (if (should-use-dialog-box-p)
+      (make-search-dialog)
+    (isearch-forward)))
+

 (defconst default-menubar
 ; (purecopy-menubar ;purespace is dead
    ;; note backquote.
 (defconst default-menubar
 ; (purecopy-menubar ;purespace is dead
    ;; note backquote.

@@ -201,7 +290,7 @@ which will not be used as accelerators."
       ["Select %_All" mark-whole-buffer]
       ["Select Pa%_ge" mark-page]
       "----"
       ["Select %_All" mark-whole-buffer]
       ["Select Pa%_ge" mark-page]
       "----"

-      ["%_Find..." make-search-dialog]
+      ["%_Find..." menu-item-search]

       ["R%_eplace..." query-replace]
       ["Replace (Rege%_xp)..." query-replace-regexp]
       ["%_List Matching Lines..." list-matching-lines]
       ["R%_eplace..." query-replace]
       ["Replace (Rege%_xp)..." query-replace-regexp]
       ["%_List Matching Lines..." list-matching-lines]

@@ -404,23 +493,26 @@ which will not be used as accelerators."
 
      ("%_Tools"
       ("%_Packages"
 
      ("%_Tools"
       ("%_Packages"

-       ("%_Add Download Site"
-        :filter (lambda (&rest junk)
-                  (submenu-generate-accelerator-spec
-                  (package-get-download-menu))))
+       ("%_Set Download Site"
+       ("%_Official Releases"
+        :filter (lambda (&rest junk)
+                  (menu-split-long-menu
+                   (submenu-generate-accelerator-spec
+                    (package-ui-download-menu)))))
+       ("%_Pre-Releases"
+        :filter (lambda (&rest junk)
+                  (menu-split-long-menu
+                   (submenu-generate-accelerator-spec
+                    (package-ui-pre-release-download-menu)))))
+       ("%_Site Releases"
+        :filter (lambda (&rest junk)
+                  (menu-split-long-menu
+                   (submenu-generate-accelerator-spec
+                    (package-ui-site-release-download-menu))))))
+       "--:shadowEtchedIn"

        ["%_Update Package Index" package-get-update-base]
        ["%_List and Install" pui-list-packages]
        ["U%_pdate Installed Packages" package-get-update-all]
        ["%_Update Package Index" package-get-update-base]
        ["%_List and Install" pui-list-packages]
        ["U%_pdate Installed Packages" package-get-update-all]

-       ;; hack-o-matic, we can't force a load of package-base here
-       ;; since it triggers dialog box interactions which we can't
-       ;; deal with while using a menu
-       ("Using %_Custom"
-       :filter (lambda (&rest junk)
-                 (if package-get-base
-                     (submenu-generate-accelerator-spec
-                      (cdr (custom-menu-create 'packages)))
-                   '("Please load Package Index"))))
-

        ["%_Help" (Info-goto-node "(xemacs)Packages")])
       ("%_Internet"
        ["Read Mail %_1 (VM)..." vm
        ["%_Help" (Info-goto-node "(xemacs)Packages")])
       ("%_Internet"
        ["Read Mail %_1 (VM)..." vm

diff --git a/lisp/obsolete.el b/lisp/obsolete.el
index 4970f11..4d8f2eb 100644 (file)
--- a/lisp/obsolete.el
+++ b/lisp/obsolete.el
@@ -177,6 +177,8 @@ set Info-directory-list.")
   "This used to be the name of the user whose init file was read at startup.")
 (make-obsolete-variable 'init-file-user 'load-user-init-file-p)
 
   "This used to be the name of the user whose init file was read at startup.")
 (make-obsolete-variable 'init-file-user 'load-user-init-file-p)
 

+(define-obsolete-function-alias 'pui-add-install-directory
+  'pui-set-local-package-get-directory) ; misleading name

 ;;;;;;;;;;;;;;;;;;;;;;;;;;;; hooks
 
 (make-compatible-variable 'lisp-indent-hook 'lisp-indent-function)
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;; hooks
 
 (make-compatible-variable 'lisp-indent-hook 'lisp-indent-function)

@@ -227,6 +229,9 @@ set Info-directory-list.")
 ;; Can't make this obsolete.  easymenu depends on it.
 (make-compatible 'add-menu 'add-submenu)
 
 ;; Can't make this obsolete.  easymenu depends on it.
 (make-compatible 'add-menu 'add-submenu)
 

+(define-obsolete-function-alias 'package-get-download-menu 
+  'package-ui-download-menu)
+

 ;;;;;;;;;;;;;;;;;;;;;;;;;;;; minibuffer
 
 (define-compatible-function-alias 'read-minibuffer
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;; minibuffer
 
 (define-compatible-function-alias 'read-minibuffer

diff --git a/lisp/package-admin.el b/lisp/package-admin.el
index 925f6de..efa527a 100644 (file)
--- a/lisp/package-admin.el
+++ b/lisp/package-admin.el
@@ -1,6 +1,7 @@
 ;;; package-admin.el --- Installation and Maintenance of XEmacs packages
 
 ;; Copyright (C) 1997 by Free Software Foundation, Inc.
 ;;; package-admin.el --- Installation and Maintenance of XEmacs packages
 
 ;; Copyright (C) 1997 by Free Software Foundation, Inc.

+;; Copyright (C) 2003, Steve Youngs.

 
 ;; Author: SL Baur <steve@xemacs.org>
 ;; Keywords: internal
 
 ;; Author: SL Baur <steve@xemacs.org>
 ;; Keywords: internal

@@ -114,25 +115,6 @@ the install directory.")
 hook is called *before* the package is deleted. The hook function is passed
 two arguments: the package name, and the install directory.")
 
 hook is called *before* the package is deleted. The hook function is passed
 two arguments: the package name, and the install directory.")
 

-;;;###autoload
-(defun package-admin-add-single-file-package (file destdir &optional pkg-dir)
-  "Install a single file Lisp package into XEmacs package hierarchy.
-`file' should be the full path to the lisp file to install.
-`destdir' should be a simple directory name.
-The optional `pkg-dir' can be used to override the default package hierarchy
-\(car \(last late-packages))."
-  (interactive "fLisp File: \nsDestination: ")
-  (when (null pkg-dir)
-    (setq pkg-dir (car (last late-packages))))
-  (let ((destination (concat pkg-dir "/lisp/" destdir))
-       (buf (get-buffer-create package-admin-temp-buffer)))
-    (call-process "add-little-package.sh"
-                 nil
-                 buf
-                 t
-                 ;; rest of command line follows
-                 package-admin-xemacs file destination)))
-

 (defun package-admin-install-function-mswindows (file pkg-dir buffer)
   "Install function for mswindows."
   (let ((default-directory (file-name-as-directory pkg-dir)))
 (defun package-admin-install-function-mswindows (file pkg-dir buffer)
   "Install function for mswindows."
   (let ((default-directory (file-name-as-directory pkg-dir)))

@@ -152,80 +134,193 @@ to BUFFER."
     ;; Don't assume GNU tar.
     (if (shell-command (concat "gunzip -c " filename " | tar xvf -") buffer)
        0
     ;; Don't assume GNU tar.
     (if (shell-command (concat "gunzip -c " filename " | tar xvf -") buffer)
        0

-      1)
-    ))
-
-;  (call-process "add-big-package.sh"
-;              nil
-;              buffer
-;              t
-;              ;; rest of command line follows
-;              package-admin-xemacs file pkg-dir))
-
-(defun package-admin-get-install-dir (package pkg-dir &optional mule-related)
-  "If PKG-DIR is non-nil return that,
-else return the current location of the package if it is already installed
-or return a location appropriate for the package otherwise."
-  (if pkg-dir
+      1)))
+
+;; A few things needed by the following 2 functions.
+(eval-when-compile
+  (require 'packages)
+  (autoload 'package-get-info "package-get")
+  (autoload 'paths-decode-directory-path "find-paths")
+  (defvar package-get-install-to-user-init-directory))
+
+(defun package-admin-find-top-directory (type &optional user-dir)
+  "Return the top level directory for a package.
+
+Argument TYPE is a symbol that determines the type of package we're
+trying to find a directory for.
+
+Optional Argument USER-DIR if non-nil use directories off
+`user-init-directory'.  This overrides everything except
+\"EMACSPACKAGEPATH\".
+
+This function honours the environment variable \"EMACSPACKAGEPATH\"
+and returns directories found there as a priority.  If that variable
+doesn't exist and USER-DIR is nil, check in the normal places.
+
+If we still can't find a suitable directory, return nil.
+
+Possible values for TYPE are:
+
+    std  == For \"standard\" packages that go in '/xemacs-packages/'
+    mule == For \"mule\" packages that go in '/mule-packages/'
+    site == For \"unsupported\" packages that go in '/site-packages/'
+
+Note:  Type \"site\" is not yet fully supported."
+  (let* ((env-value (getenv "EMACSPACKAGEPATH"))
+        top-dir)
+    ;; First, check the environment var.
+    (if env-value
+       (let ((path-list (paths-decode-directory-path env-value 'drop-empties)))
+         (cond ((eq type 'std)
+                (while path-list
+                  (if (equal (substring (car path-list) -16) 
+                             (concat "xemacs-packages" (char-to-string directory-sep-char)))
+                      (setq top-dir (car path-list)))
+                  (setq path-list (cdr path-list))))
+               ((eq type 'mule)
+                (while path-list
+                  (if (equal (substring (car path-list) -14) 
+                             (concat "mule-packages" (char-to-string directory-sep-char)))
+                      (setq top-dir (car path-list)))
+                  (setq path-list (cdr path-list)))))))
+    ;; Wasn't in the environment, try `user-init-directory' if
+    ;; USER-DIR is non-nil.
+    (if (and user-dir
+            (not top-dir))
+       (cond ((eq type 'std)
+              (setq top-dir (file-name-as-directory
+                             (expand-file-name "xemacs-packages" user-init-directory))))
+             ((eq type 'mule)
+              (setq top-dir (file-name-as-directory
+                             (expand-file-name "mule-packages" user-init-directory))))))
+    ;; Finally check the normal places
+    (if (not top-dir)
+       (let ((path-list (nth 1 (packages-find-packages
+                                emacs-roots
+                                (packages-compute-package-locations user-init-directory)))))
+         (cond ((eq type 'std)
+                (while path-list
+                  (if (equal (substring (car path-list) -16) 
+                             (concat "xemacs-packages" (char-to-string directory-sep-char)))
+                      (setq top-dir (car path-list)))
+                  (setq path-list (cdr path-list))))
+               ((eq type 'mule)
+                (while path-list
+                  (if (equal (substring (car path-list) -14) 
+                             (concat "mule-packages" (char-to-string directory-sep-char)))
+                      (setq top-dir (car path-list)))
+                  (setq path-list (cdr path-list)))))))
+    ;; Now return either the directory or nil.
+    top-dir))
+
+(defun package-admin-get-install-dir (package &optional pkg-dir)
+  "Find a suitable installation directory for a package.
+
+Argument PACKAGE is the package to find a installation directory for.
+Optional Argument PKG-DIR, if non-nil is a directory to use for
+installation.
+
+If PKG-DIR is non-nil and writable, return that.  Otherwise check to
+see if the PACKAGE is already installed and return that location, if
+it is writable.  Finally, fall back to the `user-init-directory' if
+all else fails.  As a side effect of installing packages under
+`user-init-directory' these packages become part of `early-packages'."
+  ;; If pkg-dir specified, return that if writable.
+  (if (and pkg-dir
+          (file-writable-p (directory-file-name pkg-dir)))

       pkg-dir
       pkg-dir

-    (let ((package-feature (intern-soft (concat
-                                        (symbol-name package) "-autoloads")))
-         autoload-dir)
-      (when (and (not (eq package 'unknown))
-                (featurep package-feature)
-                (setq autoload-dir (feature-file package-feature))
-                (setq autoload-dir (file-name-directory autoload-dir))
-                (member autoload-dir (append early-package-load-path late-package-load-path)))
-       ;; Find the corresponding entry in late-package
-       (setq pkg-dir
-             (car-safe (member-if (lambda (h)
-                          (string-match (concat "^" (regexp-quote h))
-                                        autoload-dir))
-                        (append (cdr early-packages) late-packages)))))
-      (if pkg-dir
-         pkg-dir
-       ;; Ok we need to guess
-       (if mule-related
-           (package-admin-get-install-dir 'mule-base nil nil)
-         (if (eq package 'xemacs-base)
-             (car (last late-packages))
-           (package-admin-get-install-dir 'xemacs-base nil nil)))))))
-
-
+    ;; If the user want her packages under ~/.xemacs/, do so.
+    (let ((type (package-get-info package 'category)))
+      (if package-get-install-to-user-init-directory
+         (progn
+           (cond ((equal type "standard")
+                  (setq pkg-dir (package-admin-find-top-directory 'std 'user-dir)))
+                 ((equal type "mule")
+                  (setq pkg-dir (package-admin-find-top-directory 'mule 'user-dir))))
+           pkg-dir)
+       ;; Maybe the package has been installed before, if so, return
+       ;; that directory.
+       (let ((package-feature (intern-soft (concat
+                                            (symbol-name package) "-autoloads")))
+             autoload-dir)
+         (when (and (not (eq package 'unknown))
+                    (featurep package-feature)
+                    (setq autoload-dir (feature-file package-feature))
+                    (setq autoload-dir (file-name-directory autoload-dir))
+                    (member autoload-dir (append early-package-load-path late-package-load-path)))
+           ;; Find the corresponding entry in late-package
+           (setq pkg-dir
+                 (car-safe (member-if (lambda (h)
+                                        (string-match (concat "^" (regexp-quote h))
+                                                      autoload-dir))
+                                      (append (cdr early-packages) late-packages)))))
+         (if (and pkg-dir
+                  (file-writable-p (directory-file-name pkg-dir)))
+             pkg-dir
+           ;; OK, the package hasn't been previously installed so we need
+           ;; to guess where it should go.
+           (cond ((equal type "standard")
+                  (setq pkg-dir (package-admin-find-top-directory 'std)))
+                 ((equal type "mule")
+                  (setq pkg-dir (package-admin-find-top-directory 'mule)))
+                 (t
+                  (error 'invalid-operation
+                         "Invalid package type")))
+           (if (and pkg-dir
+                    (file-writable-p (directory-file-name pkg-dir)))
+               pkg-dir
+             ;; Oh no!  Either we still haven't found a suitable
+             ;; directory, or we can't write to the one we did find.
+             ;; Drop back to the `user-init-directory'.
+             (if (y-or-n-p (format "Directory isn't writable, use %s instead? "
+                                   user-init-directory))
+                 (progn
+                   (cond ((equal type "standard")
+                          (setq pkg-dir (package-admin-find-top-directory 'std 'user-dir)))
+                         ((equal type "mule")
+                          (setq pkg-dir (package-admin-find-top-directory 'mule 'user-dir)))
+                         (t
+                          (error 'invalid-operation
+                                 "Invalid package type")))
+                   ;; Turn on `package-get-install-to-user-init-directory'
+                   ;; so we don't get asked for each package we try to
+                   ;; install in this session.
+                   (setq package-get-install-to-user-init-directory t)
+                   pkg-dir)
+               ;; If we get to here XEmacs can't make up its mind and
+               ;; neither can the user, nothing left to do except barf. :-(
+               (error 'search-failed
+                      (format
+                       "Can't find suitable installation directory for package: %s" 
+                       package))))))))))

 
 (defun package-admin-get-manifest-file (pkg-topdir package)
   "Return the name of the MANIFEST file for package PACKAGE.
 Note that PACKAGE is a symbol, and not a string."
 
 (defun package-admin-get-manifest-file (pkg-topdir package)
   "Return the name of the MANIFEST file for package PACKAGE.
 Note that PACKAGE is a symbol, and not a string."

-  (let (dir)
-    (setq dir (expand-file-name "pkginfo" pkg-topdir))
-    (expand-file-name (concat "MANIFEST." (symbol-name package)) dir)
-    ))
+  (let ((dir (file-name-as-directory
+             (expand-file-name "pkginfo" pkg-topdir))))
+    (expand-file-name (concat "MANIFEST." (symbol-name package)) dir)))

 
 (defun package-admin-check-manifest (pkg-outbuf pkg-topdir)
   "Check for a MANIFEST.<package> file in the package distribution.
 If it doesn't exist, create and write one.
 PKG-OUTBUF is the buffer that holds the output from `tar', and PKG-TOPDIR
 is the top-level directory under which the package was installed."
 
 (defun package-admin-check-manifest (pkg-outbuf pkg-topdir)
   "Check for a MANIFEST.<package> file in the package distribution.
 If it doesn't exist, create and write one.
 PKG-OUTBUF is the buffer that holds the output from `tar', and PKG-TOPDIR
 is the top-level directory under which the package was installed."

-  (let ( (manifest-buf " *pkg-manifest*")
-        old-case-fold-search regexp package-name pathname regexps)
-    ;; Save and restore the case-fold-search status.
-    ;; We do this in case we have to screw with it (as it the case of
-    ;; case-insensitive filesystems such as MS Windows).
-    (setq old-case-fold-search case-fold-search)
+  (let ((manifest-buf " *pkg-manifest*")
+       (old-case-fold-search case-fold-search)
+       regexp package-name pathname regexps)

     (unwind-protect
        (save-excursion                         ;; Probably redundant.
     (unwind-protect
        (save-excursion                         ;; Probably redundant.

-         (set-buffer (get-buffer pkg-outbuf))  ;; Probably already the
-                                               ;; current buffer.
+         (set-buffer (get-buffer pkg-outbuf))  ;; Probably already the current buffer.

          (goto-char (point-min))
 
          ;; Make filenames case-insensitive, if necessary
          (if (eq system-type 'windows-nt)
              (setq case-fold-search t))
 
          (goto-char (point-min))
 
          ;; Make filenames case-insensitive, if necessary
          (if (eq system-type 'windows-nt)
              (setq case-fold-search t))
 

-         ;; We really should compute the regexp.
-         ;; However, directory-sep-char is currently broken, but we need
-         ;; functional code *NOW*.
-         (setq regexp "\\bpkginfo[\\/]MANIFEST\\...*")
+         (setq regexp (concat "\\bpkginfo" 
+                              (char-to-string directory-sep-char)
+                              "MANIFEST\\...*"))

 
          ;; Look for the manifest.
          (if (not (re-search-forward regexp nil t))
 
          ;; Look for the manifest.
          (if (not (re-search-forward regexp nil t))

@@ -234,22 +329,18 @@ is the top-level directory under which the package was installed."
 
                ;; Yuk.  We weren't passed the package name, and so we have
                ;; to dig for it.  Look for it as the subdirectory name below
 
                ;; Yuk.  We weren't passed the package name, and so we have
                ;; to dig for it.  Look for it as the subdirectory name below

-               ;; "lisp", "man", "info", or "etc".
+               ;; "lisp", or "man".

                ;; Here, we don't use a single regexp because we want to search
                ;; the directories for a package name in a particular order.
                ;; Here, we don't use a single regexp because we want to search
                ;; the directories for a package name in a particular order.

-               ;; The problem is that packages could have directories like
-               ;; "etc/sounds/" or "etc/photos/" and we don't want to get
-               ;; these confused with the actual package name (although, in
-               ;; the case of "etc/sounds/", it's probably correct).

                (if (catch 'done
                (if (catch 'done

-                     (let ( (dirs '("lisp" "info" "man" "etc")) rexp)
+                     (let ((dirs '("lisp" "man")) 
+                           rexp)

                        (while dirs
                          (setq rexp (concat "\\b" (car dirs)
                                             "[\\/]\\([^\\/]+\\)[\//]"))
                          (if (re-search-forward rexp nil t)
                              (throw 'done t))
                        (while dirs
                          (setq rexp (concat "\\b" (car dirs)
                                             "[\\/]\\([^\\/]+\\)[\//]"))
                          (if (re-search-forward rexp nil t)
                              (throw 'done t))

-                         (setq dirs (cdr dirs))
-                         )))
+                         (setq dirs (cdr dirs)))))

                    (progn
                      (setq package-name (buffer-substring (match-beginning 1)
                                                           (match-end 1)))
                    (progn
                      (setq package-name (buffer-substring (match-beginning 1)
                                                           (match-end 1)))

@@ -277,22 +368,16 @@ is the top-level directory under which the package was installed."
                                            (buffer-substring
                                             (match-beginning 1)
                                             (match-end 1)))
                                            (buffer-substring
                                             (match-beginning 1)
                                             (match-end 1)))

-                                     (throw 'found-path t)
-                                     ))
-                               (setq regexps (cdr regexps))
-                               )
-                             )
+                                     (throw 'found-path t)))
+                               (setq regexps (cdr regexps))))

                            (progn
                              ;; found a pathname -- add it to the manifest
                              ;; buffer
                              (save-excursion
                                (set-buffer manifest-buf)
                                (goto-char (point-max))
                            (progn
                              ;; found a pathname -- add it to the manifest
                              ;; buffer
                              (save-excursion
                                (set-buffer manifest-buf)
                                (goto-char (point-max))

-                               (insert pathname "\n")
-                               )
-                             ))
-                       (forward-line 1)
-                       )
+                               (insert pathname "\n"))))
+                       (forward-line 1))

 
                      ;; Processed all lines.
                      ;; Now, create the file, pkginfo/MANIFEST.<pkgname>
 
                      ;; Processed all lines.
                      ;; Now, create the file, pkginfo/MANIFEST.<pkgname>

@@ -310,24 +395,18 @@ is the top-level directory under which the package was installed."
                      (save-excursion
                        (set-buffer manifest-buf)
                        ;; Put the files in sorted order
                      (save-excursion
                        (set-buffer manifest-buf)
                        ;; Put the files in sorted order

-                       (sort-lines nil (point-min) (point-max))
+                       (if (fboundp 'sort-lines)
+                           (sort-lines nil (point-min) (point-max))
+                         (warn "`xemacs-base' not installed, MANIFEST.%s not sorted"
+                               package-name))

                        ;; Write the file.
                        ;; Note that using `write-region' *BYPASSES* any check
                        ;; to see if XEmacs is currently editing/visiting the
                        ;; file.
                        ;; Write the file.
                        ;; Note that using `write-region' *BYPASSES* any check
                        ;; to see if XEmacs is currently editing/visiting the
                        ;; file.

-                       (write-region (point-min) (point-max) pathname)
-                       )
-                     (kill-buffer manifest-buf)
-                     )
-                 (progn
-                   ;; We can't determine the package name from an extracted
-                   ;; file in the tar output buffer.
-                   ))
-               ))
-         )
+                       (write-region (point-min) (point-max) pathname))
+                     (kill-buffer manifest-buf))))))

       ;; Restore old case-fold-search status
       ;; Restore old case-fold-search status

-      (setq case-fold-search old-case-fold-search))
-    ))
+      (setq case-fold-search old-case-fold-search))))

 
 ;;;###autoload
 (defun package-admin-add-binary-package (file &optional pkg-dir)
 
 ;;;###autoload
 (defun package-admin-add-binary-package (file &optional pkg-dir)

@@ -335,8 +414,7 @@ is the top-level directory under which the package was installed."
   (interactive "fPackage tarball: ")
   (let ((buf (get-buffer-create package-admin-temp-buffer))
        (status 1)
   (interactive "fPackage tarball: ")
   (let ((buf (get-buffer-create package-admin-temp-buffer))
        (status 1)

-       start err-list
-       )
+       start err-list)

     (setq pkg-dir (package-admin-get-install-dir 'unknown pkg-dir))
     ;; Ensure that the current directory doesn't change
     (save-excursion
     (setq pkg-dir (package-admin-get-install-dir 'unknown pkg-dir))
     ;; Ensure that the current directory doesn't change
     (save-excursion

@@ -358,17 +436,11 @@ is the top-level directory under which the package was installed."
                (if (re-search-forward (car err-list) nil t)
                    (progn
                      (setq status 1)
                (if (re-search-forward (car err-list) nil t)
                    (progn
                      (setq status 1)

-                     (throw 'done nil)
-                     ))
-               (setq err-list (cdr err-list))
-               )
-             )
+                     (throw 'done nil)))
+               (setq err-list (cdr err-list))))

            ;; Make sure that the MANIFEST file exists
            ;; Make sure that the MANIFEST file exists

-           (package-admin-check-manifest buf pkg-dir)
-           ))
-      )
-    status
-    ))
+           (package-admin-check-manifest buf pkg-dir))))
+    status))

 
 (defun package-admin-rmtree (directory)
   "Delete a directory and all of its contents, recursively.
 
 (defun package-admin-rmtree (directory)
   "Delete a directory and all of its contents, recursively.

@@ -403,13 +475,12 @@ This is a feeble attempt at making a portable rmdir."
             (setq package-lispdir (expand-file-name (symbol-name package)
                                                     package-lispdir))
             (file-accessible-directory-p package-lispdir))
             (setq package-lispdir (expand-file-name (symbol-name package)
                                                     package-lispdir))
             (file-accessible-directory-p package-lispdir))

-       package-lispdir)
-    ))
+       package-lispdir)))

 
 (defun package-admin-delete-binary-package (package pkg-topdir)
   "Delete a binary installation of PACKAGE below directory PKG-TOPDIR.
 PACKAGE is a symbol, not a string."
 
 (defun package-admin-delete-binary-package (package pkg-topdir)
   "Delete a binary installation of PACKAGE below directory PKG-TOPDIR.
 PACKAGE is a symbol, not a string."

-  (let ( (tmpbuf " *pkg-manifest*") manifest-file package-lispdir dirs file)
+  (let (manifest-file package-lispdir dirs file)

     (setq pkg-topdir (package-admin-get-install-dir package pkg-topdir))
     (setq manifest-file (package-admin-get-manifest-file pkg-topdir package))
     (run-hook-with-args 'package-delete-hook package pkg-topdir)
     (setq pkg-topdir (package-admin-get-install-dir package pkg-topdir))
     (setq manifest-file (package-admin-get-manifest-file pkg-topdir package))
     (run-hook-with-args 'package-delete-hook package pkg-topdir)

@@ -418,8 +489,7 @@ PACKAGE is a symbol, not a string."
          ;; The manifest file exists!  Use it to delete the old distribution.
          (message "Removing old files for package \"%s\" ..." package)
          (sit-for 0)
          ;; The manifest file exists!  Use it to delete the old distribution.
          (message "Removing old files for package \"%s\" ..." package)
          (sit-for 0)

-         (setq tmpbuf (get-buffer-create tmpbuf))
-         (with-current-buffer tmpbuf
+         (with-temp-buffer

            (buffer-disable-undo)
            (erase-buffer)
            (insert-file-contents manifest-file)
            (buffer-disable-undo)
            (erase-buffer)
            (insert-file-contents manifest-file)

@@ -451,66 +521,31 @@ PACKAGE is a symbol, not a string."
 
            ;; Delete empty directories.
            (if dirs
 
            ;; Delete empty directories.
            (if dirs

-               (let ( (orig-default-directory default-directory)
-                      ;; directory files file
-                      )
-                 ;; Make sure we preserve the existing `default-directory'.
-                 ;; JV, why does this change the default directory? Does it indeed?
-                 (unwind-protect
-                     (progn
-                       ;; Warning: destructive sort!
-                       (setq dirs (nreverse (sort dirs 'string<)))
-;                      ;; For each directory ...
-;                      (while dirs
-;                        (setq directory (file-name-as-directory (car dirs)))
-;                        (setq files (directory-files directory))
-;                        ;; Delete the directory if it's empty.
-;                        (if (catch 'done
-;                              (while files
-;                                (setq file (car files))
-;                                (if (and (not (string= file "."))
-;                                         (not (string= file "..")))
-;                                    (throw 'done nil))
-;                                (setq files (cdr files))
-;                                )
-;                              t)
-;                            (
-;                            (delete-directory directory))
-;                        (setq dirs (cdr dirs))
-;                        )
-                       ;; JV, On all OS's that I know of delete-directory fails on
-                       ;; on non-empty dirs anyway
-                       (mapc
-                          (lambda (dir)
-                            (condition-case ()
-                                (delete-directory dir)))
-                          dirs))
-                   (setq default-directory orig-default-directory)
-                   )))
-           )
-         (kill-buffer tmpbuf)
+               (progn
+                 (mapc
+                  (lambda (dir)
+                    (condition-case ()
+                        (delete-directory dir)))
+                  dirs)))

          ;; Delete the MANIFEST file
          ;; (set-file-modes manifest-file 438) ;; 438 -> #o666
          ;; Note. Packages can have MANIFEST in MANIFEST.
          (condition-case ()
              (delete-file manifest-file)
            (error nil)) ;; Do warning?
          ;; Delete the MANIFEST file
          ;; (set-file-modes manifest-file 438) ;; 438 -> #o666
          ;; Note. Packages can have MANIFEST in MANIFEST.
          (condition-case ()
              (delete-file manifest-file)
            (error nil)) ;; Do warning?

-         (message "Removing old files for package \"%s\" ... done" package))
-       ;; The manifest file doesn't exist.  Fallback to just deleting the
-       ;; package-specific lisp directory, if it exists.
-       ;;
-       ;; Delete old lisp directory, if any
-       ;; Gads, this is ugly.  However, we're not supposed to use `concat'
-       ;; in the name of portability.
-       (when (setq package-lispdir (package-admin-get-lispdir pkg-topdir
-                                                            package))
-             (message "Removing old lisp directory \"%s\" ..."
-                      package-lispdir)
-             (sit-for 0)
-             (package-admin-rmtree package-lispdir)
-             (message "Removing old lisp directory \"%s\" ... done"
-                      package-lispdir)
-             ))
+         (message "Removing old files for package \"%s\" ... done" package)))
+      ;; The manifest file doesn't exist.  Fallback to just deleting the
+      ;; package-specific lisp directory, if it exists.
+      ;;
+      ;; Delete old lisp directory, if any
+      ;; Gads, this is ugly.  However, we're not supposed to use `concat'
+      ;; in the name of portability.
+      (setq package-lispdir (package-admin-get-lispdir pkg-topdir package))
+      (when package-lispdir
+       (message "Removing old lisp directory \"%s\" ..." package-lispdir)
+       (sit-for 0)
+       (package-admin-rmtree package-lispdir)
+       (message "Removing old lisp directory \"%s\" ... done" package-lispdir)))

     ;; Delete the package from the database of installed packages.
     (package-delete-name package)))
 
     ;; Delete the package from the database of installed packages.
     (package-delete-name package)))
 

diff --git a/lisp/package-get.el b/lisp/package-get.el
index 5ae5de3..4222b78 100644 (file)
--- a/lisp/package-get.el
+++ b/lisp/package-get.el
@@ -1,10 +1,13 @@
 ;;; package-get.el --- Retrieve XEmacs package
 
 ;; Copyright (C) 1998 by Pete Ware
 ;;; package-get.el --- Retrieve XEmacs package
 
 ;; Copyright (C) 1998 by Pete Ware

+;; Copyright (C) 2002 Ben Wing.
+;; Copyright (C) 2003, Steve Youngs

 
 ;; Author: Pete Ware <ware@cis.ohio-state.edu>
 ;; Heavy-Modifications: Greg Klanderman <greg@alphatech.com>
 ;;                      Jan Vroonhof    <vroonhof@math.ethz.ch>
 
 ;; Author: Pete Ware <ware@cis.ohio-state.edu>
 ;; Heavy-Modifications: Greg Klanderman <greg@alphatech.com>
 ;;                      Jan Vroonhof    <vroonhof@math.ethz.ch>

+;;                      Steve Youngs    <youngs@xemacs.org>

 ;; Keywords: internal
 
 ;; This file is part of XEmacs.
 ;; Keywords: internal
 
 ;; This file is part of XEmacs.

@@ -166,80 +169,82 @@ one version of a package available.")
   :type 'directory
   :group 'package-get)
 
   :type 'directory
   :group 'package-get)
 

+;;;###autoload
+(defcustom package-get-package-index-file-location 
+  (or (getenv "EMACSPACKAGEPATH")
+      user-init-directory)
+  "*The directory where the package-index file can be found."
+  :type 'directory
+  :group 'package-get)
+
+;;;###autoload
+(defcustom package-get-install-to-user-init-directory nil
+  "*If non-nil install packages under `user-init-directory'."
+  :type 'boolean
+  :group 'package-get)
+

 (define-widget 'host-name 'string
   "A Host name."
   :tag "Host")
 
 (defcustom package-get-remote nil
 (define-widget 'host-name 'string
   "A Host name."
   :tag "Host")
 
 (defcustom package-get-remote nil

-  "*List of remote sites to contact for downloading packages.
-List format is '(site-name directory-on-site).  Each site is tried in
-order until the package is found.  As a special case, `site-name' can be
-`nil', in which case `directory-on-site' is treated as a local directory."
+  "*The remote site to contact for downloading packages.
+Format is '(site-name directory-on-site).  As a special case, `site-name'
+can be `nil', in which case `directory-on-site' is treated as a local
+directory."

   :tag "Package repository"
   :tag "Package repository"

-  :type '(repeat (choice (list :tag "Local" (const :tag "Local" nil) directory )
-                        (list :tag "Remote" host-name directory) ))
+  :type '(set (choice (const :tag "None" nil)
+                     (list :tag "Local" (const :tag "Local" nil) directory)
+                     (list :tag "Remote" host-name directory)))

   :group 'package-get)
 
 ;;;###autoload
 (defcustom package-get-download-sites
   '(
   :group 'package-get)
 
 ;;;###autoload
 (defcustom package-get-download-sites
   '(

-    ;; North America
-    ("Pre-Releases" "ftp.xemacs.org" "pub/xemacs/beta/experimental/packages")
-    ("xemacs.org" "ftp.xemacs.org" "pub/xemacs/packages")
-    ("ca.xemacs.org (Canada)" "ftp.ca.xemacs.org" "pub/Mirror/xemacs/packages")
-    ("crc.ca (Canada)" "ftp.crc.ca" "pub/packages/editors/xemacs/packages")
-    ("us.xemacs.org (United States)" "ftp.us.xemacs.org" "pub/xemacs/packages")
-    ("ibiblio.org (United States)" "ibiblio.org" "pub/packages/editors/xemacs/packages")
-    ("stealth.net (United States)" "ftp.stealth.net" "pub/mirrors/ftp.xemacs.org/pub/xemacs/packages")
-    ;("uiuc.edu (United States)" "uiarchive.uiuc.edu" "pub/packages/xemacs/packages")
-
-    ;; South America
-    ("br.xemacs.org (Brazil)" "ftp.br.xemacs.org" "pub/xemacs/packages")
-
-    ;; Europe
-    ("at.xemacs.org (Austria)" "ftp.at.xemacs.org" "editors/xemacs/packages")
-    ("be.xemacs.org (Belgium)" "ftp.be.xemacs.org" "xemacs/packages")
-    ("cz.xemacs.org (Czech Republic)" "ftp.cz.xemacs.org" "MIRRORS/ftp.xemacs.org/pub/xemacs/packages")
-    ("dk.xemacs.org (Denmark)" "ftp.dk.xemacs.org" "pub/emacs/xemacs/packages")
-    ("fi.xemacs.org (Finland)" "ftp.fi.xemacs.org" "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/packages")
-    ("fr.xemacs.org (France)" "ftp.fr.xemacs.org" "pub/xemacs/packages")
-    ("pasteur.fr (France)" "ftp.pasteur.fr" "pub/computing/xemacs/packages")
-    ("de.xemacs.org (Germany)" "ftp.de.xemacs.org" "pub/ftp.xemacs.org/tux/xemacs/packages")
-    ("tu-darmstadt.de (Germany)" "ftp.tu-darmstadt.de" "pub/editors/xemacs/packages")
-    ;("hu.xemacs.org (Hungary)" "ftp.hu.xemacs.org" "pub/packages/xemacs/packages")
-    ("ie.xemacs.org (Ireland)" "ftp.ie.xemacs.org" "mirrors/ftp.xemacs.org/pub/xemacs/packages")
-    ("it.xemacs.org (Italy)" "ftp.it.xemacs.org" "unix/packages/XEMACS/packages")
-    ("no.xemacs.org (Norway)" "ftp.no.xemacs.org" "pub/xemacs/packages")
-    ("pl.xemacs.org (Poland)" "ftp.pl.xemacs.org" "pub/unix/editors/xemacs/packages")
-    ("ru.xemacs.org (Russia)" "ftp.ru.xemacs.org" "pub/xemacs/packages")
-    ("sk.xemacs.org (Slovakia)" "ftp.sk.xemacs.org" "pub/mirrors/xemacs/packages")
-    ("se.xemacs.org (Sweden)" "ftp.se.xemacs.org" "pub/gnu/xemacs/packages")
-    ("ch.xemacs.org (Switzerland)" "ftp.ch.xemacs.org" "mirror/xemacs/packages")
-    ("uk.xemacs.org (United Kingdom)" "ftp.uk.xemacs.org" "sites/ftp.xemacs.org/pub/xemacs/packages")
-
-    ;; Asia
-    ("jp.xemacs.org (Japan)" "ftp.jp.xemacs.org" "pub/GNU/xemacs/packages")
-    ("aist.go.jp (Japan)" "ring.aist.go.jp" "pub/text/xemacs/packages")
-    ("asahi-net.or.jp (Japan)" "ring.asahi-net.or.jp" "pub/text/xemacs/packages")
-    ("dti.ad.jp (Japan)" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/packages")
-    ("jaist.ac.jp (Japan)" "ftp.jaist.ac.jp" "pub/GNU/xemacs/packages")
-    ("nucba.ac.jp (Japan)" "mirror.nucba.ac.jp" "mirror/xemacs/packages")
-    ("sut.ac.jp (Japan)" "sunsite.sut.ac.jp" "pub/archives/packages/xemacs/packages")
-    ("kr.xemacs.org (Korea)" "ftp.kr.xemacs.org" "pub/tools/emacs/xemacs/packages")
-    ;("tw.xemacs.org (Taiwan)" "ftp.tw.xemacs.org" "Editors/xemacs/packages")
-
-    ;; Africa
-    ("za.xemacs.org (South Africa)" "ftp.za.xemacs.org" "mirrorsites/ftp.xemacs.org/packages")
-
-    ;; Middle East
-    ("sa.xemacs.org (Saudi Arabia)" "ftp.sa.xemacs.org" "pub/mirrors/ftp.xemacs.org/xemacs/packages")
-
-    ;; Australia
-    ("au.xemacs.org (Australia)" "ftp.au.xemacs.org" "pub/xemacs/packages")
-    ("aarnet.edu.au (Australia)" "mirror.aarnet.edu.au" "pub/xemacs/packages")
-
-    ;; Oceania
-    ("nz.xemacs.org (New Zealand)" "ftp.nz.xemacs.org" "mirror/ftp.xemacs.org/packages")
+    ;; Main XEmacs Site (ftp.xemacs.org)
+    ("US (Main XEmacs Site)"
+     "ftp.xemacs.org" "pub/xemacs/packages")
+    ;; In alphabetical order of Country, our mirrors...
+    ("Australia (aarnet.edu.au)" "mirror.aarnet.edu.au" "pub/xemacs/packages")
+    ("Australia (au.xemacs.org)" "ftp.au.xemacs.org" "pub/xemacs/packages")
+    ("Austria (at.xemacs.org)" "ftp.at.xemacs.org" "editors/xemacs/packages")
+    ("Belgium (be.xemacs.org)" "ftp.be.xemacs.org" "xemacs/packages")
+    ("Brazil (br.xemacs.org)" "ftp.br.xemacs.org" "pub/xemacs/packages")
+    ("Canada (ca.xemacs.org)" "ftp.ca.xemacs.org" "pub/Mirror/xemacs/packages")
+    ("Canada (crc.ca)" "ftp.crc.ca" "pub/packages/editors/xemacs/packages")
+    ("Canada (ualberta.ca)" "sunsite.ualberta.ca" "pub/Mirror/xemacs/packages")
+    ("Czech Republic (cz.xemacs.org)" "ftp.cz.xemacs.org" "MIRRORS/ftp.xemacs.org/pub/xemacs/packages")
+    ("Denmark (dk.xemacs.org)" "ftp.dk.xemacs.org" "pub/emacs/xemacs/packages")
+    ("Finland (fi.xemacs.org)" "ftp.fi.xemacs.org" "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/packages")
+    ("France (fr.xemacs.org)" "ftp.fr.xemacs.org" "pub/xemacs/packages")
+    ("France (mirror.cict.fr)" "mirror.cict.fr" "xemacs/packages")
+    ("France (pasteur.fr)" "ftp.pasteur.fr" "pub/computing/xemacs/packages")
+    ("Germany (de.xemacs.org)" "ftp.de.xemacs.org" "pub/ftp.xemacs.org/tux/xemacs/packages")
+    ("Germany (tu-darmstadt.de)" "ftp.tu-darmstadt.de" "pub/editors/xemacs/packages")
+    ("Ireland (ie.xemacs.org)" "ftp.ie.xemacs.org" "mirrors/ftp.xemacs.org/pub/xemacs/packages")
+    ("Italy (it.xemacs.org)" "ftp.it.xemacs.org" "unix/packages/XEMACS/packages")
+    ("Japan (aist.go.jp)" "ring.aist.go.jp" "pub/text/xemacs/packages")
+    ("Japan (asahi-net.or.jp)" "ring.asahi-net.or.jp" "pub/text/xemacs/packages")
+    ("Japan (dti.ad.jp)" "ftp.dti.ad.jp" "pub/unix/editor/xemacs/packages")
+    ("Japan (jaist.ac.jp)" "ftp.jaist.ac.jp" "pub/GNU/xemacs/packages")
+    ("Japan (jp.xemacs.org)" "ftp.jp.xemacs.org" "pub/GNU/xemacs/packages")
+    ("Japan (nucba.ac.jp)" "mirror.nucba.ac.jp" "mirror/xemacs/packages")
+    ("Japan (sut.ac.jp)" "sunsite.sut.ac.jp" "pub/archives/packages/xemacs/packages")
+    ("Korea (kr.xemacs.org)" "ftp.kr.xemacs.org" "pub/tools/emacs/xemacs/packages")
+    ("New Zealand (nz.xemacs.org)" "ftp.nz.xemacs.org" "mirror/ftp.xemacs.org/packages")
+    ("Norway (no.xemacs.org)" "ftp.no.xemacs.org" "pub/xemacs/packages")
+    ("Poland (pl.xemacs.org)" "ftp.pl.xemacs.org" "pub/unix/editors/xemacs/packages")
+    ("Russia (ru.xemacs.org)" "ftp.ru.xemacs.org" "pub/xemacs/packages")
+    ("Slovakia (sk.xemacs.org)" "ftp.sk.xemacs.org" "pub/mirrors/xemacs/packages")
+    ("South Africa (za.xemacs.org)" "ftp.za.xemacs.org" "mirrorsites/ftp.xemacs.org/packages")
+    ("Sweden (se.xemacs.org)" "ftp.se.xemacs.org" "pub/gnu/xemacs/packages")
+    ("Switzerland (ch.xemacs.org)" "ftp.ch.xemacs.org" "mirror/xemacs/packages")
+    ("UK (uk.xemacs.org)" "ftp.uk.xemacs.org" "sites/ftp.xemacs.org/pub/xemacs/packages")
+    ("US (ibiblio.org)" "ibiblio.org" "pub/packages/editors/xemacs/packages")
+    ("US (stealth.net)" "ftp.stealth.net" "pub/mirrors/ftp.xemacs.org/pub/xemacs/packages")
+    ("US (unc.edu)" "metalab.unc.edu" "pub/packages/editors/xemacs/packages")
+    ("US (us.xemacs.org)" "ftp.us.xemacs.org" "pub/xemacs/packages")
+    ("US (utk.edu)" "ftp.sunsite.utk.edu" "pub/xemacs/packages")

     )
   "*List of remote sites available for downloading packages.
 List format is '(site-description site-name directory-on-site).
     )
   "*List of remote sites available for downloading packages.
 List format is '(site-description site-name directory-on-site).

@@ -252,6 +257,113 @@ variable actually used to specify package download sites."
   :type '(repeat (list (string :tag "Name") host-name directory))
   :group 'package-get)
 
   :type '(repeat (list (string :tag "Name") host-name directory))
   :group 'package-get)
 

+;;;###autoload
+(defcustom package-get-pre-release-download-sites
+  '(
+    ;; Main XEmacs Site (ftp.xemacs.org)
+    ("Pre-Releases (Main XEmacs Site)" "ftp.xemacs.org"
+     "pub/xemacs/beta/experimental/packages")
+    ;; In alphabetical order of Country, our mirrors...
+    ("Australia Pre-Releases (aarnet.edu.au)" "mirror.aarnet.edu.au"
+     "pub/xemacs/beta/experimental/packages")
+    ("Australia Pre-Releases (au.xemacs.org)" "ftp.au.xemacs.org"
+     "pub/xemacs/beta/experimental/packages")
+    ("Austria Pre-Releases (at.xemacs.org)" "ftp.at.xemacs.org"
+     "editors/xemacs/beta/experimentsl/packages")
+    ("Brazil Pre-Releases (br.xemacs.org)" "ftp.br.xemacs.org"
+     "pub/xemacs/xemacs-21.5/experimental/packages")
+    ("Canada Pre-Releases (ca.xemacs.org)" "ftp.ca.xemacs.org"
+     "pub/Mirror/xemacs/beta/experimental/packages")
+    ("Canada Pre-Releases (crc.ca)" "ftp.crc.ca"
+     "pub/packages/editors/xemacs/beta/experimental/packages")
+    ("Canada Pre-Releases (ualberta.ca)" "sunsite.ualberta.ca"
+     "pub/Mirror/xemacs/beta/experimental/packages")
+    ("Czech Republic Pre-Releases (cz.xemacs.org)" "ftp.cz.xemacs.org"
+     "MIRRORS/ftp.xemacs.org/pub/xemacs/xemacs-21.5/experimental/packages")
+    ("Denmark Pre-Releases (dk.xemacs.org)" "ftp.dk.xemacs.org"
+     "pub/emacs/xemacs/beta/experimental/packages")
+    ("Finland Pre-Releases (fi.xemacs.org)" "ftp.fi.xemacs.org"
+     "pub/mirrors/ftp.xemacs.org/pub/tux/xemacs/beta/experimental/packages")
+    ("France Pre-Releases (fr.xemacs.org)" "ftp.fr.xemacs.org"
+     "pub/xemacs/beta/experimental/packages")
+    ("France Pre-Releases (mirror.cict.fr)" "mirror.cict.fr"
+     "xemacs/beta/experimental/packages")
+    ("France Pre-Releases (pasteur.fr)" "ftp.pasteur.fr"
+     "pub/computing/xemacs/beta/experimental/packages")
+    ("Germany Pre-Releases (de.xemacs.org)" "ftp.de.xemacs.org"
+     "pub/ftp.xemacs.org/tux/xemacs/beta/experimental/packages")
+    ("Germany Pre-Releases (tu-darmstadt.de)" "ftp.tu-darmstadt.de"
+     "pub/editors/xemacs/beta/experimental/packages")
+    ("Ireland Pre-Releases (ie.xemacs.org)" "ftp.ie.xemacs.org"
+     "mirrors/ftp.xemacs.org/pub/xemacs/beta/experimental/packages")
+    ("Italy Pre-Releases (it.xemacs.org)" "ftp.it.xemacs.org"
+     "unix/packages/XEMACS/beta/experimental/packages")
+    ("Japan Pre-Releases (aist.go.jp)" "ring.aist.go.jp"
+     "pub/text/xemacs/beta/experimental/packages")
+    ("Japan Pre-Releases (asahi-net.or.jp)" "ring.asahi-net.or.jp"
+     "pub/text/xemacs/beta/experimental/packages")
+    ("Japan Pre-Releases (dti.ad.jp)" "ftp.dti.ad.jp"
+     "pub/unix/editor/xemacs/beta/experimental/packages")
+    ("Japan Pre-Releases (jaist.ac.jp)" "ftp.jaist.ac.jp"
+     "pub/GNU/xemacs/beta/experimental/packages")
+    ("Japan Pre-Releases (jp.xemacs.org)" "ftp.jp.xemacs.org"
+     "pub/GNU/xemacs/beta/experimental/packages")
+    ("Japan Pre-Releases (sut.ac.jp)" "sunsite.sut.ac.jp"
+     "pub/archives/packages/xemacs/xemacs-21.5/experimental/packages")
+    ("New Zealand Pre-Releases (nz.xemacs.org)" "ftp.nz.xemacs.org" "mirror/ftp.xemacs.org/packages")
+    ("Norway Pre-Releases (no.xemacs.org)" "ftp.no.xemacs.org"
+     "pub/xemacs/beta/experimental/packages")
+    ("Poland Pre-Releases (pl.xemacs.org)" "ftp.pl.xemacs.org"
+     "pub/unix/editors/xemacs/beta/experimental/packages")
+    ("Russia Pre-Releases (ru.xemacs.org)" "ftp.ru.xemacs.org"
+     "pub/xemacs/beta/experimental/packages")
+    ("Saudi Arabia Pre-Releases (sa.xemacs.org)" "ftp.sa.xemacs.org"
+     "pub/mirrors/ftp.xemacs.org/xemacs/xemacs-21.5/experimental/packages")
+    ("Slovakia Pre-Releases (sk.xemacs.org)" "ftp.sk.xemacs.org"
+     "pub/mirrors/xemacs/beta/experimental/packages")
+    ("South Africa Pre-Releases (za.xemacs.org)" "ftp.za.xemacs.org"
+     "mirrorsites/ftp.xemacs.org/beta/experimental/packages")
+    ("Sweden Pre-Releases (se.xemacs.org)" "ftp.se.xemacs.org"
+     "pub/gnu/xemacs/beta/experimental/packages")
+    ("Switzerland Pre-Releases (ch.xemacs.org)" "ftp.ch.xemacs.org"
+     "mirror/xemacs/beta/experimental/packages")
+    ("UK Pre-Releases (uk.xemacs.org)" "ftp.uk.xemacs.org"
+     "sites/ftp.xemacs.org/pub/xemacs/beta/experimental/packages")
+    ("US Pre-Releases (ibiblio.org)" "ibiblio.org"
+     "pub/packages/editors/xemacs/beta/experimental/packages")
+    ("US Pre-Releases (stealth.net)" "ftp.stealth.net"
+     "pub/mirrors/ftp.xemacs.org/pub/xemacs/beta/experimental/packages")
+    ("US Pre-Releases (unc.edu)" "metalab.unc.edu"
+     "pub/packages/editors/xemacs/beta/experimental/packages")
+    ("US Pre-Releases (us.xemacs.org)" "ftp.us.xemacs.org"
+     "pub/xemacs/beta/experimental/packages")
+    ("US Pre-Releases (utk.edu)" "ftp.sunsite.utk.edu"
+     "pub/xemacs/beta/experimental/packages"))
+  "*List of remote sites available for downloading \"Pre-Release\" packages.
+List format is '(site-description site-name directory-on-site).
+SITE-DESCRIPTION is a textual description of the site.  SITE-NAME
+is the internet address of the download site.  DIRECTORY-ON-SITE
+is the directory on the site in which packages may be found.
+This variable is used to initialize `package-get-remote', the
+variable actually used to specify package download sites."
+  :tag "Pre-Release Package download sites"
+  :type '(repeat (list (string :tag "Name") host-name directory))
+  :group 'package-get)
+
+;;;###autoload
+(defcustom package-get-site-release-download-sites
+  nil
+  "*List of remote sites available for downloading \"Site Release\" packages.
+List format is '(site-description site-name directory-on-site).
+SITE-DESCRIPTION is a textual description of the site.  SITE-NAME
+is the internet address of the download site.  DIRECTORY-ON-SITE
+is the directory on the site in which packages may be found.
+This variable is used to initialize `package-get-remote', the
+variable actually used to specify package download sites."
+  :tag "Site Release Package download sites"
+  :type '(repeat (list (string :tag "Name") host-name directory))
+  :group 'package-get)
+

 (defcustom package-get-remove-copy t
   "*After copying and installing a package, if this is t, then remove the
 copy.  Otherwise, keep it around."
 (defcustom package-get-remove-copy t
   "*After copying and installing a package, if this is t, then remove the
 copy.  Otherwise, keep it around."

@@ -261,50 +373,68 @@ copy.  Otherwise, keep it around."
 ;; #### it may make sense for this to be a list of names.
 ;; #### also, should we rename "*base*" to "*index*" or "*db*"?
 ;;      "base" is a pretty poor name.
 ;; #### it may make sense for this to be a list of names.
 ;; #### also, should we rename "*base*" to "*index*" or "*db*"?
 ;;      "base" is a pretty poor name.

-(defcustom package-get-base-filename "package-index.LATEST.pgp"
+(defcustom package-get-base-filename "package-index.LATEST.gpg"

   "*Name of the default package-get database file.
 This may either be a relative path, in which case it is interpreted
 with respect to `package-get-remote', or an absolute path."
   :type 'file
   :group 'package-get)
 
   "*Name of the default package-get database file.
 This may either be a relative path, in which case it is interpreted
 with respect to `package-get-remote', or an absolute path."
   :type 'file
   :group 'package-get)
 

-(defvar package-get-user-index-filename
-  (paths-construct-path (list user-init-directory package-get-base-filename))
-  "Name for the user-specific location of the package-get database file.")
-

 (defcustom package-get-always-update nil
   "*If Non-nil always make sure we are using the latest package index (base).
 Otherwise respect the `force-current' argument of `package-get-require-base'."
   :type 'boolean
   :group 'package-get)
 
 (defcustom package-get-always-update nil
   "*If Non-nil always make sure we are using the latest package index (base).
 Otherwise respect the `force-current' argument of `package-get-require-base'."
   :type 'boolean
   :group 'package-get)
 

-(defcustom package-get-require-signed-base-updates nil
-  "*If set to a non-nil value, require explicit user confirmation for updates
-to the package-get database which cannot have their signature verified via PGP.
-When nil, updates which are not PGP signed are allowed without confirmation."
+(defun package-get-pgp-available-p ()
+  "Checks the availability of Mailcrypt and PGP executable.
+
+Returns t if both are found, nil otherwise.  As a side effect, set
+`mc-default-scheme' dependent on the PGP executable found."
+  (let (result)
+    (when (featurep 'mailcrypt-autoloads)
+      (autoload 'mc-setversion "mc-setversion"))
+    (when (fboundp 'mc-setversion)
+      (cond ((locate-file "gpg" exec-path
+                         '("" ".btm" ".bat" ".cmd" ".exe" ".com")
+                         'executable)
+            (mc-setversion "gpg")
+            (setq result t))
+           ((locate-file "pgpe" exec-path
+                         '("" ".btm" ".bat" ".cmd" ".exe" ".com")
+                         'executable)
+            (mc-setversion "5.0")
+            (setq result t))
+           ((locate-file "pgp" exec-path
+                         '("" ".btm" ".bat" ".cmd" ".exe" ".com")
+                         'executable)
+            (mc-setversion "2.6")
+            (setq result t))))
+    (if result
+       result
+      nil)))
+
+(defcustom package-get-require-signed-base-updates (package-get-pgp-available-p)
+  "*If non-nil, try to verify the package index database via PGP.
+
+If nil, no PGP verification is done.  If the package index database
+entries are not PGP signed and this variable is non-nil, require user
+confirmation to continue with the package-get procedure.
+
+The default for this variable is the return value of
+`package-get-pgp-available-p', non-nil if both the \"Mailcrypt\"
+package and a suitable PGP executable are available, nil otherwise."

   :type 'boolean
   :group 'package-get)
 
   :type 'boolean
   :group 'package-get)
 

-(defvar package-get-was-current nil
-  "Non-nil we did our best to fetch a current database.")
+(defvar package-entries-are-signed nil
+  "Non-nil when the package index file has been PGP signed.")

 
 

+(defvar package-get-continue-update-base nil
+  "Non-nil update the index even if it hasn't been signed.")

 
 

-;Shouldn't this be in package-ui?
-;;;###autoload
-(defun package-get-download-menu ()
-  "Build the `Add Download Site' menu."
-  (mapcar (lambda (site)
-           (vector (car site)
-                   `(if (member (quote ,(cdr site))
-                                package-get-remote)
-                        (setq package-get-remote
-                              (delete (quote ,(cdr site))
-                                      package-get-remote))
-                      (package-ui-add-site (quote ,(cdr site))))
-                   :style 'toggle
-                   :selected `(member (quote ,(cdr site))
-                                      package-get-remote)))
-         package-get-download-sites))
+(defvar package-get-was-current nil
+  "Non-nil we did our best to fetch a current database.")

 
 ;;;###autoload
 (defun package-get-require-base (&optional force-current)
 
 ;;;###autoload
 (defun package-get-require-base (&optional force-current)

@@ -323,7 +453,8 @@ and remote access is likely in the near future."
     (package-get-update-base nil force-current))
   (if (or (not (boundp 'package-get-base))
          (not package-get-base))
     (package-get-update-base nil force-current))
   (if (or (not (boundp 'package-get-base))
          (not package-get-base))

-      (error "Package-get database not loaded")
+      (error 'void-variable
+            "Package-get database not loaded")

     (setq package-get-was-current force-current)))
 
 (defconst package-get-pgp-signed-begin-line "^-----BEGIN PGP SIGNED MESSAGE-----"
     (setq package-get-was-current force-current)))
 
 (defconst package-get-pgp-signed-begin-line "^-----BEGIN PGP SIGNED MESSAGE-----"

@@ -339,8 +470,7 @@ and remote access is likely in the near future."
   (let ((existing (assq (car entry) package-get-base)))
     (if existing
         (setcdr existing (cdr entry))
   (let ((existing (assq (car entry) package-get-base)))
     (if existing
         (setcdr existing (cdr entry))

-      (setq package-get-base (cons entry package-get-base))
-      (package-get-custom-add-entry (car entry) (car (cdr entry))))))
+      (setq package-get-base (cons entry package-get-base)))))

 
 (defun package-get-locate-file (file &optional nil-if-not-found no-remote)
   "Locate an existing FILE with respect to `package-get-remote'.
 
 (defun package-get-locate-file (file &optional nil-if-not-found no-remote)
   "Locate an existing FILE with respect to `package-get-remote'.

@@ -350,27 +480,48 @@ if FILE can not be located.
 If NO-REMOTE is non-nil never search remote locations."
   (if (file-name-absolute-p file)
       file
 If NO-REMOTE is non-nil never search remote locations."
   (if (file-name-absolute-p file)
       file

-    (let ((entries package-get-remote)
+    (let ((site package-get-remote)

           (expanded nil))
           (expanded nil))

-      (while entries
-       (unless (and no-remote (caar entries))
-         (let ((expn (package-get-remote-filename (car entries) file)))
+      (when site
+       (unless (and no-remote (caar (list site)))
+         (let ((expn (package-get-remote-filename (car (list site)) file)))

            (if (and expn (file-exists-p expn))
            (if (and expn (file-exists-p expn))

-               (setq entries  nil
-                     expanded expn))))
-        (setq entries (cdr entries)))
+               (setq site nil
+                     expanded expn)))))

       (or expanded
           (and (not nil-if-not-found)
                file)))))
 
 (defun package-get-locate-index-file (no-remote)
       (or expanded
           (and (not nil-if-not-found)
                file)))))
 
 (defun package-get-locate-index-file (no-remote)

-  "Locate the package-get index file.  Do not return remote paths if NO-REMOTE
-is non-nil."
+  "Locate the package-get index file.  
+
+Do not return remote paths if NO-REMOTE is non-nil.  If the index
+file doesn't exist in `package-get-package-index-file-location', ask
+the user if one should be created using the index file in core as a
+template."

   (or (package-get-locate-file package-get-base-filename t no-remote)
   (or (package-get-locate-file package-get-base-filename t no-remote)

-      (if (file-exists-p package-get-user-index-filename)
-         package-get-user-index-filename)
-      (locate-data-file package-get-base-filename)
-      (error "Can't locate a package index file.")))
+      (if (file-exists-p (expand-file-name package-get-base-filename
+                                          package-get-package-index-file-location))
+         (expand-file-name package-get-base-filename
+                           package-get-package-index-file-location)
+       (if (y-or-n-p (format "No index file, shall I create one in %s? "
+                             package-get-package-index-file-location))
+           (progn
+             (save-excursion
+               (set-buffer 
+                (find-file-noselect (expand-file-name
+                                     package-get-base-filename
+                                     package-get-package-index-file-location)))
+               (let ((coding-system-for-write 'binary))
+                 (erase-buffer)
+                 (insert-file-contents-literally
+                  (locate-data-file package-get-base-filename))
+                 (save-buffer (current-buffer))
+                 (kill-buffer (current-buffer))))
+             (expand-file-name package-get-base-filename
+                               package-get-package-index-file-location))
+         (error 'search-failed
+                "Can't locate a package index file.")))))

 
 (defun package-get-maybe-save-index (filename)
   "Offer to save the current buffer as the local package index file,
 
 (defun package-get-maybe-save-index (filename)
   "Offer to save the current buffer as the local package index file,

@@ -382,13 +533,18 @@ if different."
                          (with-temp-buffer
                            (insert-file-contents-literally location)
                            (md5 (current-buffer)))))
                          (with-temp-buffer
                            (insert-file-contents-literally location)
                            (md5 (current-buffer)))))

-       (unless (and location (file-writable-p location))
-         (setq location package-get-user-index-filename))
+       (when (not (file-writable-p location))
+         (if (y-or-n-p (format "Sorry, %s is read-only, can I use %s? "
+                               location user-init-directory))
+             (setq location (expand-file-name
+                             package-get-base-filename
+                             package-get-package-index-file-location))
+           (error 'file-error
+                  (format "%s is read-only" location))))

        (when (y-or-n-p (concat "Update package index in " location "? "))
          (let ((coding-system-for-write 'binary))
            (write-file location)))))))
 
        (when (y-or-n-p (concat "Update package index in " location "? "))
          (let ((coding-system-for-write 'binary))
            (write-file location)))))))
 

-

 ;;;###autoload
 (defun package-get-update-base (&optional db-file force-current)
   "Update the package-get database file with entries from DB-FILE.
 ;;;###autoload
 (defun package-get-update-base (&optional db-file force-current)
   "Update the package-get database file with entries from DB-FILE.

@@ -404,9 +560,11 @@ Unless FORCE-CURRENT is non-nil never try to update the database."
                                       (package-get-locate-index-file
                                         (not force-current)))))
   (if (not (file-exists-p db-file))
                                       (package-get-locate-index-file
                                         (not force-current)))))
   (if (not (file-exists-p db-file))

-      (error "Package-get database file `%s' does not exist" db-file))
+      (error 'file-error
+            (format "Package-get database file `%s' does not exist" db-file)))

   (if (not (file-readable-p db-file))
   (if (not (file-readable-p db-file))

-      (error "Package-get database file `%s' not readable" db-file))
+      (error 'file-error
+            (format "Package-get database file `%s' not readable" db-file)))

   (let ((buf (get-buffer-create "*package database*")))
     (unwind-protect
         (save-excursion
   (let ((buf (get-buffer-create "*package database*")))
     (unwind-protect
         (save-excursion

@@ -425,49 +583,45 @@ BUFFER defaults to the current buffer.  This command can be
 used interactively, for example from a mail or news buffer."
   (interactive)
   (setq buf (or buf (current-buffer)))
 used interactively, for example from a mail or news buffer."
   (interactive)
   (setq buf (or buf (current-buffer)))

-  (let (content-beg content-end beg end)
+  (let (content-beg content-end)

     (save-excursion
       (set-buffer buf)
       (goto-char (point-min))
       (setq content-beg (point))
       (setq content-end (save-excursion (goto-char (point-max)) (point)))
       (when (re-search-forward package-get-pgp-signed-begin-line nil t)
     (save-excursion
       (set-buffer buf)
       (goto-char (point-min))
       (setq content-beg (point))
       (setq content-end (save-excursion (goto-char (point-max)) (point)))
       (when (re-search-forward package-get-pgp-signed-begin-line nil t)

-        (setq beg (match-beginning 0))

         (setq content-beg (match-end 0)))
       (when (re-search-forward package-get-pgp-signature-begin-line nil t)
         (setq content-beg (match-end 0)))
       (when (re-search-forward package-get-pgp-signature-begin-line nil t)

-        (setq content-end (match-beginning 0)))
-      (when (re-search-forward package-get-pgp-signature-end-line nil t)
-        (setq end (point)))
-      (if (not (and content-beg content-end beg end))
-          (or (not package-get-require-signed-base-updates)
-              (yes-or-no-p "Package-get entries not PGP signed, continue? ")
-              (error "Package-get database not updated")))
-      (if (and content-beg content-end beg end)
-          (if (not (condition-case nil
-                       (or (fboundp 'mc-pgp-verify-region)
-                           (load-library "mc-pgp")
-                           (fboundp 'mc-pgp-verify-region))
-                     (error nil)))
-              (or (not package-get-require-signed-base-updates)
-                  (yes-or-no-p
-                   "No mailcrypt; can't verify package-get DB signature, continue? ")
-                  (error "Package-get database not updated"))))
-      (if (and beg end
-               (fboundp 'mc-pgp-verify-region)
-               (or (not
-                    (condition-case err
-                        (mc-pgp-verify-region beg end)
-                      (file-error
-                       (and (string-match "No such file" (nth 2 err))
-                            (or (not package-get-require-signed-base-updates)
-                                (yes-or-no-p
-                                 (concat "Can't find PGP, continue without "
-                                         "package-get DB verification? ")))))
-                      (t nil)))))
-          (error "Package-get PGP signature failed to verify"))
+        (setq content-end (match-beginning 0))
+       (setq package-entries-are-signed t))
+      (re-search-forward package-get-pgp-signature-end-line nil t)
+      (setq package-get-continue-update-base t)
+      ;; This is a little overkill because the default value of
+      ;; `package-get-require-signed-base-updates' is the return of
+      ;; `package-get-pgp-available-p', but we have to allow for
+      ;; someone explicitly setting
+      ;; `package-get-require-signed-base-updates' to t. --SY
+      (when (and package-get-require-signed-base-updates
+                (package-get-pgp-available-p))
+       (if package-entries-are-signed
+           (let (good-sig)
+             (setq package-get-continue-update-base nil)
+             (autoload 'mc-verify "mc-toplev")
+             (when (mc-verify)
+               (setq good-sig t))
+             (if good-sig
+                 (setq package-get-continue-update-base t)
+               (error 'process-error 
+                      "GnuPG error.  Package database not updated")))
+         (if (yes-or-no-p
+              "Package Index is not PGP signed.  Continue anyway? ")
+             (setq package-get-continue-update-base t)
+           (setq package-get-continue-update-base nil)
+           (warn "Package database not updated"))))

       ;; ToDo: We should call package-get-maybe-save-index on the region
       ;; ToDo: We should call package-get-maybe-save-index on the region

-      (package-get-update-base-entries content-beg content-end)
-      (message "Updated package-get database"))))
+      (when package-get-continue-update-base
+       (package-get-update-base-entries content-beg content-end)
+       (message "Updated package database")))))

 
 (defun package-get-update-base-entries (start end)
   "Update the package-get database with the entries found between
 
 (defun package-get-update-base-entries (start end)
   "Update the package-get database with the entries found between

@@ -475,7 +629,8 @@ START and END in the current buffer."
   (save-excursion
     (goto-char start)
     (if (not (re-search-forward "^(package-get-update-base-entry" nil t))
   (save-excursion
     (goto-char start)
     (if (not (re-search-forward "^(package-get-update-base-entry" nil t))

-        (error "Buffer does not contain package-get database entries"))
+        (error 'search-failed
+              "Buffer does not contain package-get database entries"))

     (beginning-of-line)
     (let ((count 0))
       (while (and (< (point) end)
     (beginning-of-line)
     (let ((count 0))
       (while (and (< (point) end)

@@ -484,7 +639,8 @@ START and END in the current buffer."
         (let ((entry (read (current-buffer))))
           (if (or (not (consp entry))
                   (not (eq (car entry) 'package-get-update-base-entry)))
         (let ((entry (read (current-buffer))))
           (if (or (not (consp entry))
                   (not (eq (car entry) 'package-get-update-base-entry)))

-              (error "Invalid package-get database entry found"))
+              (error 'syntax-error
+                    "Invalid package-get database entry found"))

           (package-get-update-base-entry
            (car (cdr (car (cdr entry)))))
           (setq count (1+ count))))
           (package-get-update-base-entry
            (car (cdr (car (cdr entry)))))
           (setq count (1+ count))))

@@ -547,12 +703,10 @@ The return value is suitable for direct passing to `interactive'."
                   'version))
            (while (string=
                    (setq version (read-string "Version: " default-version))
                   'version))
            (while (string=
                    (setq version (read-string "Version: " default-version))

-                   "")
-             )
+                   ""))

            (if package-symbol
                (list package-symbol version)
            (if package-symbol
                (list package-symbol version)

-             (list package version))
-           )
+             (list package version)))

        (if package-symbol
            (list package-symbol)
          (list package))))))
        (if package-symbol
            (list package-symbol)
          (list package))))))

@@ -574,8 +728,7 @@ This is just an interactive wrapper for `package-admin-delete-binary-package'."
   (catch 'exit
     (mapcar (lambda (pkg)
              (if (not (package-get (car pkg) nil 'never))
   (catch 'exit
     (mapcar (lambda (pkg)
              (if (not (package-get (car pkg) nil 'never))

-                 (throw 'exit nil)             ;; Bail out if error detected
-                 ))
+                 (throw 'exit nil)))           ;; Bail out if error detected

            packages-package-list))
   (package-net-update-installed-db))
 
            packages-package-list))
   (package-net-update-installed-db))
 

@@ -595,8 +748,7 @@ Returns nil upon error."
                                                     package))
         (this-package (package-get-info-version
                        the-package version))
                                                     package))
         (this-package (package-get-info-version
                        the-package version))

-        (this-requires (package-get-info-prop this-package 'requires))
-        )
+        (this-requires (package-get-info-prop this-package 'requires)))

     (catch 'exit
       (setq version (package-get-info-prop this-package 'version))
       (unless (package-get-installedp package version)
     (catch 'exit
       (setq version (package-get-info-prop this-package 'version))
       (unless (package-get-installedp package version)

@@ -619,18 +771,16 @@ Returns nil upon error."
                   (reqd-version (cadr reqd-package))
                   (reqd-name (car reqd-package)))
              (if (null reqd-name)
                   (reqd-version (cadr reqd-package))
                   (reqd-name (car reqd-package)))
              (if (null reqd-name)

-                 (error "Unable to find a provider for %s"
-                        (car this-requires)))
+                 (error 'search-failed
+                        (format "Unable to find a provider for %s"
+                                (car this-requires))))

              (if (not (setq fetched-packages
                             (package-get-all reqd-name reqd-version
                                              fetched-packages
                                               install-dir)))
              (if (not (setq fetched-packages
                             (package-get-all reqd-name reqd-version
                                              fetched-packages
                                               install-dir)))

-                 (throw 'exit nil)))
-         )
-       (setq this-requires (cdr this-requires)))
-      )
-    fetched-packages
-    ))
+                 (throw 'exit nil))))
+       (setq this-requires (cdr this-requires))))
+    fetched-packages))

 
 ;;;###autoload
 (defun package-get-dependencies (packages)
 
 ;;;###autoload
 (defun package-get-dependencies (packages)

@@ -654,7 +804,8 @@ required by PACKAGES."
                                   (let* ((reqd-package (package-get-package-provider reqd))
                                          (reqd-name    (car reqd-package)))
                                     (if (null reqd-name)
                                   (let* ((reqd-package (package-get-package-provider reqd))
                                          (reqd-name    (car reqd-package)))
                                     (if (null reqd-name)

-                                        (error "Unable to find a provider for %s" reqd))
+                                        (error 'search-failed
+                                              (format "Unable to find a provider for %s" reqd)))

                                     reqd-name))
                               this-requires)
                              dependencies))
                                     reqd-name))
                               this-requires)
                              dependencies))

@@ -692,20 +843,136 @@ Return `t' upon complete success, `nil' if any errors occurred."
        (progn
          ;; Add lispdir to load-path if it doesn't already exist.
          ;; NOTE: this does not take symlinks, etc., into account.
        (progn
          ;; Add lispdir to load-path if it doesn't already exist.
          ;; NOTE: this does not take symlinks, etc., into account.

-         (if (let ( (dirs load-path) )
+         (if (let ((dirs load-path))

                (catch 'done
                  (while dirs
                    (if (string-equal (car dirs) lispdir)
                        (throw 'done nil))
                (catch 'done
                  (while dirs
                    (if (string-equal (car dirs) lispdir)
                        (throw 'done nil))

-                   (setq dirs (cdr dirs))
-                   )
+                   (setq dirs (cdr dirs)))

                  t))
              (setq load-path (cons lispdir load-path)))
          (if (not (package-get-load-package-file lispdir "auto-autoloads"))
              (package-get-load-package-file lispdir "_pkg"))
          t)
                  t))
              (setq load-path (cons lispdir load-path)))
          (if (not (package-get-load-package-file lispdir "auto-autoloads"))
              (package-get-load-package-file lispdir "_pkg"))
          t)

-      nil)
-    ))
+      nil)))
+
+;;;###autoload
+(defun package-get-info (package information &optional arg remote)
+  "Get information about a package.
+
+Quite similar to `package-get-info-prop', but can retrieve a lot more
+information.
+
+Argument PACKAGE is the name of an XEmacs package (a symbol).  It must
+be a valid package, ie, a member of `package-get-base'.
+
+Argument INFORMATION is a symbol that can be any one of:
+
+   standards-version     Package system version (not used).
+   version               Version of the XEmacs package.
+   author-version        The upstream version of the package.
+   date                  The date the package was last modified.
+   build-date            The date the package was last built.
+   maintainer            The maintainer of the package.
+   distribution          Will always be \"xemacs\" (not used).
+   priority              \"low\", \"medium\", or \"high\" (not used).
+   category              Either \"standard\", \"mule\", or \"unsupported\"..
+   dump                  Is the package dumped (not used).
+   description           A description of the package.
+   filename              The filename of the binary tarball of the package.
+   md5sum                The md5sum of filename.
+   size                  The size in bytes of filename.
+   provides              A list of symbols that this package provides.
+   requires              A list of packages that this package requires.
+   type                  Can be either \"regular\" or \"single-file\".
+
+If optional argument ARG is non-nil insert INFORMATION into current
+buffer at point.  This is very useful for doing things like inserting
+a maintainer's email address into a mail buffer.
+
+If optional argument REMOTE is non-nil use a package list from a
+remote site.  For this to work `package-get-remote' must be non-nil.
+
+If this function is called interactively it will display INFORMATION
+in the minibuffer."
+  (interactive "SPackage: \nSInfo: \nP")
+    (if remote
+       (package-get-require-base t)
+      (package-get-require-base nil))
+    (let ((all-pkgs package-get-base)
+         info)
+      (loop until (equal package (caar all-pkgs))
+       do (setq all-pkgs (cdr all-pkgs))
+       do (if (not all-pkgs)
+              (error 'invalid-argument
+                     (format "%s is not a valid package" package))))
+      (setq info (plist-get (cadar all-pkgs) information))
+      (if (interactive-p)
+         (if arg
+             (insert (format "%s" info))
+           (if (package-get-key package :version)
+               (message "%s" info)
+             (message "%s (Package: %s is not installed)" info package)))
+       (if arg
+           (insert (format "%s" info))
+         info))))
+
+;;;###autoload
+(defun package-get-list-packages-where (item field &optional arg)
+  "Return a list of packages that fulfill certain criteria.
+
+Argument ITEM, a symbol, is what you want to check for.  ITEM must be a
+symbol even when it doesn't make sense to be a symbol \(think, searching
+maintainers, descriptions, etc\).  The function will convert the symbol
+to a string if a string is what is needed.  The downside to this is that
+ITEM can only ever be a single word.
+
+Argument FIELD, a symbol, is the field to check in.  You can specify
+any one of:
+
+      Field            Sane or Allowable Content
+    description          any single word
+    category             `standard' or `mule'
+    maintainer           any single word
+    build-date           yyyy-mm-dd
+    date                 yyyy-mm-dd
+    type                 `regular' or `single'
+    requires             any package name
+    provides             any symbol
+    priority             `low', `medium', or `high'
+
+Optional Argument ARG, a prefix arg, insert output at point in the
+current buffer."
+  (interactive "SList packages that have (item): \nSin their (field): \nP")
+  (package-get-require-base nil)
+  (let ((pkgs package-get-base)
+       (strings '(description category maintainer build-date date))
+       (symbols '(type requires provides priority))
+       results)
+    (cond ((memq field strings)
+          (setq item (symbol-name item))
+          (while pkgs
+            (when (string-match item (package-get-info (caar pkgs) field))
+              (setq results (push (caar pkgs) results)))
+            (setq pkgs (cdr pkgs))))
+         ((memq field symbols)
+          (if (or (eq field 'type)
+                  (eq field 'priority))
+              (while pkgs
+                (when (eq item (package-get-info (caar pkgs) field))
+                  (setq results (push (caar pkgs) results)))
+                (setq pkgs (cdr pkgs)))
+            (while pkgs
+              (when (memq item (package-get-info (caar pkgs) field))
+                (setq results (push (caar pkgs) results)))
+              (setq pkgs (cdr pkgs)))))
+         (t 
+          (error 'wrong-type-argument field)))
+    (if (interactive-p)
+       (if arg
+           (insert (format "%s" results))
+         (message "%s" results)))
+    results))

 
 ;;;###autoload
 (defun package-get (package &optional version conflict install-dir)
 
 ;;;###autoload
 (defun package-get (package &optional version conflict install-dir)

@@ -720,8 +987,7 @@ fetched packages should be installed.
 
 The value of `package-get-base' is used to determine what files should
 be retrieved.  The value of `package-get-remote' is used to determine
 
 The value of `package-get-base' is used to determine what files should
 be retrieved.  The value of `package-get-remote' is used to determine

-where a package should be retrieved from.  The sites are tried in
-order so one is better off listing easily reached sites first.
+where a package should be retrieved from.

 
 Once the package is retrieved, its md5 checksum is computed.  If that
 sum does not match that stored in `package-get-base' for this version
 
 Once the package is retrieved, its md5 checksum is computed.  If that
 sum does not match that stored in `package-get-base' for this version

@@ -738,23 +1004,27 @@ successfully installed but errors occurred during initialization, or
                                          package) version))
          (latest (package-get-info-prop this-package 'version))
          (installed (package-get-key package :version))
                                          package) version))
          (latest (package-get-info-prop this-package 'version))
          (installed (package-get-key package :version))

-        (this-requires (package-get-info-prop this-package 'requires))

         (found nil)
         (found nil)

-        (search-dirs package-get-remote)
+        (search-dir package-get-remote)

         (base-filename (package-get-info-prop this-package 'filename))
         (package-status t)
         filenames full-package-filename)
         (base-filename (package-get-info-prop this-package 'filename))
         (package-status t)
         filenames full-package-filename)

+    (if (and (equal (package-get-info package 'category) "mule")
+            (not (featurep 'mule)))
+       (error 'invalid-state 
+              "Mule packages can't be installed with a non-Mule XEmacs"))

     (if (null this-package)
        (if package-get-remote
     (if (null this-package)
        (if package-get-remote

-           (error "Couldn't find package %s with version %s"
-                  package version)
-         (error "No download sites or local package locations specified.")))
+           (error 'search-failed
+                  (format "Couldn't find package %s with version %s"
+                          package version))
+         (error 'syntax-error
+                "No download site or local package location specified.")))

     (if (null base-filename)
     (if (null base-filename)

-       (error "No filename associated with package %s, version %s"
-              package version))
-    (setq install-dir
-         (package-admin-get-install-dir package install-dir
-               (or (eq package 'mule-base) (memq 'mule-base this-requires))))
+       (error 'syntax-error
+              (format "No filename associated with package %s, version %s"
+                      package version)))
+    (setq install-dir (package-admin-get-install-dir package install-dir))

 
     ;; If they asked for the latest using version=nil, don't get an older
     ;; version than we already have.
 
     ;; If they asked for the latest using version=nil, don't get an older
     ;; version than we already have.

@@ -767,9 +1037,9 @@ successfully installed but errors occurred during initialization, or
                  latest))
             (if (not (null version))
                 (warn "Installing %s package version %s, you had a newer version %s"
                  latest))
             (if (not (null version))
                 (warn "Installing %s package version %s, you had a newer version %s"

-                      package latest installed)
+                 package latest installed)

               (warn "Skipping %s package, you have a newer version %s"
               (warn "Skipping %s package, you have a newer version %s"

-                    package installed)
+               package installed)

               (throw 'skip-update t))))
 
     ;; Contrive a list of possible package filenames.
               (throw 'skip-update t))))
 
     ;; Contrive a list of possible package filenames.

@@ -787,15 +1057,12 @@ successfully installed but errors occurred during initialization, or
       ;; and copy it into the staging directory.  Then validate
       ;; the checksum.  Finally, install the package.
       (catch 'done
       ;; and copy it into the staging directory.  Then validate
       ;; the checksum.  Finally, install the package.
       (catch 'done

-       (let (search-filenames current-dir-entry host dir current-filename
-                              dest-filename)
+       (let (search-filenames host dir current-filename dest-filename)

          ;; In each search directory ...
          ;; In each search directory ...

-         (while search-dirs
-           (setq current-dir-entry (car search-dirs)
-                 host (car current-dir-entry)
-                 dir (car (cdr current-dir-entry))
-                 search-filenames filenames
-                 )
+         (when search-dir
+           (setq host (car search-dir)
+                 dir (car (cdr search-dir))
+                 search-filenames filenames)

 
            ;; Look for one of the possible package filenames ...
            (while search-filenames
 
            ;; Look for one of the possible package filenames ...
            (while search-filenames

@@ -803,56 +1070,45 @@ successfully installed but errors occurred during initialization, or
                    dest-filename (package-get-staging-dir current-filename))
              (cond
               ;; No host means look on the current system.
                    dest-filename (package-get-staging-dir current-filename))
              (cond
               ;; No host means look on the current system.

-              ( (null host)
-                (setq full-package-filename
-                      (substitute-in-file-name
-                       (expand-file-name current-filename
-                                         (file-name-as-directory dir))))
-                )
+              ((null host)
+               (setq full-package-filename
+                     (substitute-in-file-name
+                      (expand-file-name current-filename
+                                        (file-name-as-directory dir)))))

 
               ;; If it's already on the disk locally, and the size is
 
               ;; If it's already on the disk locally, and the size is

-              ;; greater than zero ...
-              ( (and (file-exists-p dest-filename)
-                     (let (attrs)
-                       ;; file-attributes could return -1 for LARGE files,
-                       ;; but, hopefully, packages won't be that large.
-                       (and (setq attrs (file-attributes dest-filename))
-                            (> (nth 7 attrs) 0))))
-                (setq full-package-filename dest-filename)
-                )
+              ;; correct
+              ((and (file-exists-p dest-filename)
+                    (eq (nth 7 (file-attributes dest-filename))
+                        (package-get-info package 'size)))
+                (setq full-package-filename dest-filename))

 
               ;; If the file exists on the remote system ...
 
               ;; If the file exists on the remote system ...

-              ( (file-exists-p (package-get-remote-filename
-                                current-dir-entry current-filename))
-                ;; Get it
-                (setq full-package-filename dest-filename)
-                (message "Retrieving package `%s' ..."
-                         current-filename)
-                (sit-for 0)
-                (copy-file (package-get-remote-filename current-dir-entry
-                                                        current-filename)
-                           full-package-filename t)
-                )
-              )
+              ((file-exists-p (package-get-remote-filename
+                               search-dir current-filename))
+               ;; Get it
+               (setq full-package-filename dest-filename)
+               (message "Retrieving package `%s' ..."
+                        current-filename)
+               (sit-for 0)
+               (copy-file (package-get-remote-filename search-dir
+                                                       current-filename)
+                          full-package-filename t)))

 
              ;; If we found it, we're done.
              (if (and full-package-filename
                       (file-exists-p full-package-filename))
                  (throw 'done nil))
              ;; Didn't find it.  Try the next possible filename.
 
              ;; If we found it, we're done.
              (if (and full-package-filename
                       (file-exists-p full-package-filename))
                  (throw 'done nil))
              ;; Didn't find it.  Try the next possible filename.

-             (setq search-filenames (cdr search-filenames))
-             )
-           ;; Try looking in the next possible directory ...
-           (setq search-dirs (cdr search-dirs))
-           )
-         ))
+             (setq search-filenames (cdr search-filenames))))))

 
       (if (or (not full-package-filename)
              (not (file-exists-p full-package-filename)))
          (if package-get-remote
 
       (if (or (not full-package-filename)
              (not (file-exists-p full-package-filename)))
          (if package-get-remote

-             (error "Unable to find file %s" base-filename)
-           (error
-            "No download sites or local package locations specified.")))
+             (error 'search-failed
+                    (format "Unable to find file %s" base-filename))
+           (error 'syntax-error
+                  "No download sites or local package locations specified.")))

       ;; Validate the md5 checksum
       ;; Doing it with XEmacs removes the need for an external md5 program
       (message "Validating checksum for `%s'..." package) (sit-for 0)
       ;; Validate the md5 checksum
       ;; Doing it with XEmacs removes the need for an external md5 program
       (message "Validating checksum for `%s'..." package) (sit-for 0)

@@ -861,7 +1117,11 @@ successfully installed but errors occurred during initialization, or
        (if (not (string= (md5 (current-buffer))
                          (package-get-info-prop this-package
                                                 'md5sum)))
        (if (not (string= (md5 (current-buffer))
                          (package-get-info-prop this-package
                                                 'md5sum)))

-           (error "Package %s does not match md5 checksum" base-filename)))
+           (progn
+             (delete-file full-package-filename)
+             (error 'process-error
+                    (format "Package %s does not match md5 checksum %s has been deleted"
+                            base-filename full-package-filename)))))

 
       (package-admin-delete-binary-package package install-dir)
 
 
       (package-admin-delete-binary-package package install-dir)
 

@@ -879,30 +1139,25 @@ successfully installed but errors occurred during initialization, or
                  (progn
                    (run-hook-with-args 'package-install-hook package install-dir)
                    (message "Added package `%s'" package)
                  (progn
                    (run-hook-with-args 'package-install-hook package install-dir)
                    (message "Added package `%s'" package)

-                   (sit-for 0)
-                   )
+                   (sit-for 0))

                (progn
                  ;; display message only if there isn't already one.
                  (if (not (current-message))
                      (progn
                        (message "Added package `%s' (errors occurred)"
                                 package)
                (progn
                  ;; display message only if there isn't already one.
                  (if (not (current-message))
                      (progn
                        (message "Added package `%s' (errors occurred)"
                                 package)

-                       (sit-for 0)
-                       ))
+                       (sit-for 0)))

                  (if package-status
                  (if package-status

-                     (setq package-status 'errors))
-                 ))
-             )
+                     (setq package-status 'errors)))))

          (message "Installation of package %s failed." base-filename)
          (sit-for 0)
          (switch-to-buffer package-admin-temp-buffer)
          (message "Installation of package %s failed." base-filename)
          (sit-for 0)
          (switch-to-buffer package-admin-temp-buffer)

-         (setq package-status nil)
-         ))
+         (delete-file full-package-filename)
+         (setq package-status nil)))

       (setq found t))
     (if (and found package-get-remove-copy)
        (delete-file full-package-filename))
       (setq found t))
     (if (and found package-get-remove-copy)
        (delete-file full-package-filename))

-    package-status
-    )))
+    package-status)))

 
 (defun package-get-info-find-package (which name)
   "Look in WHICH for the package called NAME and return all the info
 
 (defun package-get-info-find-package (which name)
   "Look in WHICH for the package called NAME and return all the info

@@ -953,13 +1208,6 @@ md5sum            - computed md5 checksum"
    (package-get-info-version
     (package-get-info-find-package package-list package) version) property))
 
    (package-get-info-version
     (package-get-info-find-package package-list package) version) property))
 

-(defun package-get-set-version-prop (package-list package version
-                                                 property value)
-  "A utility to make it easier to add a VALUE for a specific PROPERTY
-  in this VERSION of a specific PACKAGE kept in the PACKAGE-LIST.
-Returns the modified PACKAGE-LIST.  Any missing fields are created."
-  )
-

 (defun package-get-staging-dir (filename)
   "Return a good place to stash FILENAME when it is retrieved.
 Use `package-get-dir' for directory to store stuff.
 (defun package-get-staging-dir (filename)
   "Return a good place to stash FILENAME when it is retrieved.
 Use `package-get-dir' for directory to store stuff.

@@ -997,7 +1245,6 @@ If (car search) is nil, (cadr search is interpreted as  a local directory).
                (concat dir "/"))
              filename))))
 
                (concat dir "/"))
              filename))))
 

-

 (defun package-get-installedp (package version)
   "Determine if PACKAGE with VERSION has already been installed.
 I'm not sure if I want to do this by searching directories or checking
 (defun package-get-installedp (package version)
   "Determine if PACKAGE with VERSION has already been installed.
 I'm not sure if I want to do this by searching directories or checking

@@ -1006,7 +1253,9 @@ some built in variables.  For now, use packages-package-list."
   (equal (plist-get
          (package-get-info-find-package packages-package-list
                                         package) ':version)
   (equal (plist-get
          (package-get-info-find-package packages-package-list
                                         package) ':version)

-        (if (floatp version) version (string-to-number version))))
+        (if (floatp version)
+            version
+          (string-to-number version))))

 
 ;;;###autoload
 (defun package-get-package-provider (sym &optional force-current)
 
 ;;;###autoload
 (defun package-get-package-provider (sym &optional force-current)

@@ -1044,26 +1293,6 @@ lead to Emacs accessing remote sites."
         (message "No appropriate package found")))
     found))
 
         (message "No appropriate package found")))
     found))
 

-;;
-;; customize interfaces.
-;; The group is in this file so that custom loads includes this file.
-;;
-(defgroup packages nil
-  "Configure XEmacs packages."
-  :group 'emacs)
-
-;;;###autoload
-(defun package-get-custom ()
-  "Fetch and install the latest versions of all customized packages."
-  (interactive)
-  (package-get-require-base t)
-  (mapcar (lambda (pkg)
-           (if (eval (intern (concat (symbol-name (car pkg)) "-package")))
-               (package-get (car pkg) nil))
-           t)
-         package-get-base)
-  (package-net-update-installed-db))
-

 (defun package-get-ever-installed-p (pkg &optional notused)
   (string-match "-package$" (symbol-name pkg))
   (custom-initialize-set
 (defun package-get-ever-installed-p (pkg &optional notused)
   (string-match "-package$" (symbol-name pkg))
   (custom-initialize-set

@@ -1073,26 +1302,5 @@ lead to Emacs accessing remote sites."
        (intern (substring (symbol-name pkg) 0 (match-beginning 0))))
        t)))
 
        (intern (substring (symbol-name pkg) 0 (match-beginning 0))))
        t)))
 

-(defvar package-get-custom-groups nil
-  "List of package-get-custom groups")
-
-(defun package-get-custom-add-entry (package props)
-  (let* ((category (plist-get props 'category))
-         (group (intern (concat category "-packages")))
-         (custom-var (intern (concat (symbol-name package) "-package")))
-         (description (plist-get props 'description)))
-    (when (not (memq group package-get-custom-groups))
-      (setq package-get-custom-groups (cons group
-                                            package-get-custom-groups))
-      (eval `(defgroup ,group nil
-               ,(concat category " package group")
-               :group 'packages)))
-    (eval `(defcustom ,custom-var nil
-             ,description
-             :group ',group
-             :initialize 'package-get-ever-installed-p
-             :type 'boolean))))
-
-

 (provide 'package-get)
 ;;; package-get.el ends here
 (provide 'package-get)
 ;;; package-get.el ends here

diff --git a/lisp/package-info.el b/lisp/package-info.el
index 6226664..7428f49 100644 (file)
--- a/lisp/package-info.el
+++ b/lisp/package-info.el
@@ -94,7 +94,8 @@ author-version -- The original Author's version #.
 maintainer -- The package maintainer.
 category -- The build category."
   (unless noninteractive
 maintainer -- The package maintainer.
 category -- The build category."
   (unless noninteractive

-    (error "`batch-update-package-info' is to be used only with -batch"))
+    (error 'invalid-operation
+          "`batch-update-package-info' is to be used only with -batch"))

   (let ((version (nth 0 command-line-args-left))
        (filename (nth 1 command-line-args-left))
        (requires (nth 2 command-line-args-left))
   (let ((version (nth 0 command-line-args-left))
        (filename (nth 1 command-line-args-left))
        (requires (nth 2 command-line-args-left))

diff --git a/lisp/package-net.el b/lisp/package-net.el
index 1fadce1..cef7ace 100644 (file)
--- a/lisp/package-net.el
+++ b/lisp/package-net.el
@@ -136,7 +136,8 @@
 (defun package-net-batch-generate-bin-ini ()
   "Convert the package index to ini file format."
   (unless noninteractive
 (defun package-net-batch-generate-bin-ini ()
   "Convert the package index to ini file format."
   (unless noninteractive

-    (error "`package-net-batch-generate-bin-ini' is to be used only with -batch"))
+    (error 'invalid-operation
+          "`package-net-batch-generate-bin-ini' is to be used only with -batch"))

   (package-net-generate-bin-ini package-net-setup-version))
 
 ;;;###autoload
   (package-net-generate-bin-ini package-net-setup-version))
 
 ;;;###autoload

diff --git a/lisp/package-ui.el b/lisp/package-ui.el
index c0b93ad..60b31d0 100644 (file)
--- a/lisp/package-ui.el
+++ b/lisp/package-ui.el
@@ -80,11 +80,10 @@ Set this to `nil' to use the `default' face."
    :group 'pui
    :type 'face)
    
    :group 'pui
    :type 'face)
    

-
-
-
-(defvar pui-info-buffer "*Packages*"
-  "Buffer to use for displaying package information.")
+(defcustom pui-info-buffer "*Packages*"
+  "*Buffer to use for displaying package information."
+  :group 'pui
+  :type 'string)

 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; End of user-changeable variables.
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; End of user-changeable variables.

@@ -105,6 +104,7 @@ Set this to `nil' to use the `default' face."
     (define-key m "q" 'pui-quit)
     (define-key m "g" 'pui-list-packages)
     (define-key m "i" 'pui-display-info)
     (define-key m "q" 'pui-quit)
     (define-key m "g" 'pui-list-packages)
     (define-key m "i" 'pui-display-info)

+    (define-key m "m" 'pui-display-maintainer)

     (define-key m "?" 'describe-mode)
     (define-key m "v" 'pui-toggle-verbosity-redisplay)
     (define-key m "d" 'pui-toggle-package-delete-key)
     (define-key m "?" 'describe-mode)
     (define-key m "v" 'pui-toggle-verbosity-redisplay)
     (define-key m "d" 'pui-toggle-package-delete-key)

@@ -137,46 +137,11 @@ Set this to `nil' to use the `default' face."
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Configuration routines
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Configuration routines
 

-(defun pui-directory-exists (dir)
-  "Check to see if DIR exists in `package-get-remote'."
-  (let (found)
-    (mapcar #'(lambda (item)
-               (if (and (null (car item))
-                        (string-equal (file-name-as-directory (car (cdr item)))
-                                      (file-name-as-directory dir)))
-                   (setq found t)))
-           package-get-remote)
-    found
-    ))
-
-(defun pui-package-dir-list (buffer)
-  "In BUFFER, format the list of package binary paths."
-  (let ( (count 1) paths sys dir)
-    (set-buffer buffer)
-    (buffer-disable-undo buffer)
-    (erase-buffer buffer)
-    (insert "Existing package binary paths:\n\n")
-    (setq paths package-get-remote)
-    (while paths
-      (setq sys (car (car paths))
-           dir (car (cdr (car paths))))
-      (insert (format "%2s. " count))
-      (if (null sys)
-         (insert dir)
-       (insert sys ":" dir))
-      (insert "\n")
-      (setq count (1+ count))
-      (setq paths (cdr paths))
-      )
-    (insert "\nThese are the places that will be searched for package binaries.\n")
-    (goto-char (point-min))
-    ))
-

 ;;;###autoload
 (defun package-ui-add-site (site)
   "Add site to package-get-remote and possibly offer to update package list."
   (let ((had-none (null package-get-remote)))
 ;;;###autoload
 (defun package-ui-add-site (site)
   "Add site to package-get-remote and possibly offer to update package list."
   (let ((had-none (null package-get-remote)))

-    (push site package-get-remote)    
+    (setq package-get-remote site)    

     (when (and had-none package-get-was-current
               (y-or-n-p "Update Package list?"))
       (setq package-get-was-current nil)
     (when (and had-none package-get-was-current
               (y-or-n-p "Update Package list?"))
       (setq package-get-was-current nil)

@@ -185,39 +150,64 @@ Set this to `nil' to use the `default' face."
          (save-window-excursion
            (pui-list-packages))))
     (set-menubar-dirty-flag)))
          (save-window-excursion
            (pui-list-packages))))
     (set-menubar-dirty-flag)))

-    

 
 ;;;###autoload
 
 ;;;###autoload

-(defun pui-add-install-directory (dir)
-  "Add a new package binary directory to the head of `package-get-remote'.
+(defun package-ui-download-menu ()
+  "Build the `Add Download Site' menu."
+  (mapcar (lambda (site)
+           (vector (car site)
+                   `(if (equal package-get-remote (quote ,(cdr site)))
+                     (setq package-get-remote nil)
+                     (package-ui-add-site (quote ,(cdr site))))
+                   ;; I've used radio buttons so that only a single
+                   ;; site can be selected, but they are in fact
+                   ;; toggles.  SY.
+                   :style 'radio
+                   :selected `(equal package-get-remote (quote ,(cdr site)))))
+         package-get-download-sites))
+
+;;;###autoload
+(defun package-ui-pre-release-download-menu ()
+  "Build the 'Pre-Release Download Sites' menu."
+  (mapcar (lambda (site)
+           (vector (car site)
+                   `(if (equal package-get-remote (quote ,(cdr site)))
+                     (setq package-get-remote nil)
+                     (package-ui-add-site (quote ,(cdr site))))
+                   ;; I've used radio buttons so that only a single
+                   ;; site can be selected, but they are in fact
+                   ;; toggles.  SY.
+                   :style 'radio
+                   :selected `(equal package-get-remote (quote ,(cdr site)))))
+         package-get-pre-release-download-sites))
+
+;;;###autoload
+(defun package-ui-site-release-download-menu ()
+  "Build the 'Site Release Download Sites' menu."
+  (mapcar (lambda (site)
+           (vector (car site)
+                   `(if (equal package-get-remote (quote ,(cdr site)))
+                     (setq package-get-remote nil)
+                     (package-ui-add-site (quote ,(cdr site))))
+                   ;; I've used radio buttons so that only a single
+                   ;; site can be selected, but they are in fact
+                   ;; toggles.  SY.
+                   :style 'radio
+                   :selected `(equal package-get-remote (quote ,(cdr site)))))
+         package-get-site-release-download-sites))
+
+;;;###autoload
+(defun pui-set-local-package-get-directory ()
+  "Set a new package binary directory in `package-get-remote'.

 Note that no provision is made for saving any changes made by this function.
 It exists mainly as a convenience for one-time package installations from
 disk."
 Note that no provision is made for saving any changes made by this function.
 It exists mainly as a convenience for one-time package installations from
 disk."

-  (interactive (let ( (tmpbuf (get-buffer-create
-                              "*Existing Package Binary Paths*"))
-                     dir)
-                (save-window-excursion
-                  (save-excursion
-                    (unwind-protect
-                        (progn
-                          (pui-package-dir-list tmpbuf)
-                          (display-buffer tmpbuf)
-                          (setq dir (read-directory-name
-                                     "New package binary directory to add? "
-                                     nil nil t))
-                          )
-                      (kill-buffer tmpbuf)
-                      )))
-                (list dir)
-                ))
-  (progn
-    (if (not (pui-directory-exists dir))
-       (progn
-         (setq package-get-remote (cons (list nil dir) package-get-remote))
-         (message "Package directory \"%s\" added." dir)
-         )
-      (message "Directory \"%s\" already exists in `package-get-remote'." dir))
-    ))
+  (interactive) 
+  (let ((dir (read-directory-name
+             "New package binary directory to add? "
+             nil nil t)))
+    (setq package-get-remote (list nil dir))
+    (message "Package directory \"%s\" added." dir)))

 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Package list/installer routines
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Package list/installer routines

@@ -238,8 +228,7 @@ disk."
                     version))
               (list " " pui-up-to-date-package-face)
             (list "*" pui-outdated-package-face)))
                     version))
               (list " " pui-up-to-date-package-face)
             (list "*" pui-outdated-package-face)))

-      (list "-" pui-uninstalled-package-face))
-    ))
+      (list "-" pui-uninstalled-package-face))))

 
 (defun pui-update-package-display (extent &optional pkg-sym version)
   "Update the package status for EXTENT.
 
 (defun pui-update-package-display (extent &optional pkg-sym version)
   "Update the package status for EXTENT.

@@ -272,9 +261,7 @@ and whether or not it is up-to-date."
       (goto-char (extent-start-position extent))
       (delete-char 1)
       (insert sym-char)
       (goto-char (extent-start-position extent))
       (delete-char 1)
       (insert sym-char)

-      (set-buffer-modified-p nil)
-      )
-    ))
+      (set-buffer-modified-p nil))))

 
 (defun pui-toggle-package (extent)
   (let (pkg-sym)
 
 (defun pui-toggle-package (extent)
   (let (pkg-sym)

@@ -286,8 +273,7 @@ and whether or not it is up-to-date."
            (cons pkg-sym pui-selected-packages))
       (setq pui-deleted-packages
            (delete pkg-sym pui-deleted-packages)))
            (cons pkg-sym pui-selected-packages))
       (setq pui-deleted-packages
            (delete pkg-sym pui-deleted-packages)))

-    (pui-update-package-display extent pkg-sym)
-    ))
+    (pui-update-package-display extent pkg-sym)))

 
 (defun pui-toggle-package-key ()
   "Select/unselect package for installation, using the keyboard."
 
 (defun pui-toggle-package-key ()
   "Select/unselect package for installation, using the keyboard."

@@ -296,10 +282,9 @@ and whether or not it is up-to-date."
     (if (setq extent (extent-at (point) (current-buffer) 'pui))
        (progn
          (pui-toggle-package extent)
     (if (setq extent (extent-at (point) (current-buffer) 'pui))
        (progn
          (pui-toggle-package extent)

-         (forward-line 1)
-         )
-      (error "No package under cursor!"))
-    ))
+         (forward-line 1))
+      (error 'invalid-operation
+            "No package under cursor!"))))

 
 (defun pui-toggle-package-delete (extent)
   (let (pkg-sym)
 
 (defun pui-toggle-package-delete (extent)
   (let (pkg-sym)

@@ -311,8 +296,7 @@ and whether or not it is up-to-date."
            (cons pkg-sym pui-deleted-packages))
       (setq pui-selected-packages
            (delete pkg-sym pui-selected-packages)))
            (cons pkg-sym pui-deleted-packages))
       (setq pui-selected-packages
            (delete pkg-sym pui-selected-packages)))

-    (pui-update-package-display extent pkg-sym)
-    ))
+    (pui-update-package-display extent pkg-sym)))

   
 
 (defun pui-toggle-package-delete-key ()
   
 
 (defun pui-toggle-package-delete-key ()

@@ -322,10 +306,9 @@ and whether or not it is up-to-date."
     (if (setq extent (extent-at (point) (current-buffer) 'pui))
        (progn
          (pui-toggle-package-delete extent)
     (if (setq extent (extent-at (point) (current-buffer) 'pui))
        (progn
          (pui-toggle-package-delete extent)

-         (forward-line 1)
-         )
-      (error "No package under cursor!"))
-    ))
+         (forward-line 1))
+      (error 'invalid-operation
+            "No package under cursor!"))))

 
 (defun pui-current-package ()
   (let ((extent (extent-at (point) (current-buffer) 'pui)))
 
 (defun pui-current-package ()
   (let ((extent (extent-at (point) (current-buffer) 'pui)))

@@ -335,25 +318,23 @@ and whether or not it is up-to-date."
 (defun pui-toggle-package-event (event)
   "Select/unselect package for installation, using the mouse."
   (interactive "e")
 (defun pui-toggle-package-event (event)
   "Select/unselect package for installation, using the mouse."
   (interactive "e")

-  (let* ( (ep (event-point event))
-          (buffer (window-buffer (event-window event)))
-          (extent (extent-at ep buffer 'pui-package))
-          )
-    (pui-toggle-package extent)
-    ))
+  (let* ((ep (event-point event))
+        (buffer (window-buffer (event-window event)))
+        (extent (extent-at ep buffer 'pui-package)))
+    (pui-toggle-package extent)))

 
 (defun pui-toggle-verbosity-redisplay ()
   "Toggle verbose package info."
   (interactive)
   (progn
     (setq pui-list-verbose (not pui-list-verbose))
 
 (defun pui-toggle-verbosity-redisplay ()
   "Toggle verbose package info."
   (interactive)
   (progn
     (setq pui-list-verbose (not pui-list-verbose))

-    (pui-list-packages)
-    ))
+    (pui-list-packages)))

 
 (defun pui-install-selected-packages ()
   "Install selected packages."
   (interactive)
 
 (defun pui-install-selected-packages ()
   "Install selected packages."
   (interactive)

-  (let ( (tmpbuf "*Packages-To-Remove*") do-delete)
+  (let ((tmpbuf "*Packages-To-Remove*") 
+       do-delete)

     (when pui-deleted-packages
       (save-window-excursion
        (with-output-to-temp-buffer tmpbuf
     (when pui-deleted-packages
       (save-window-excursion
        (with-output-to-temp-buffer tmpbuf

@@ -362,8 +343,7 @@ and whether or not it is up-to-date."
                                    #'string<)
                                   :activate-callback nil
                                   :help-string "Packages selected for removal:\n"
                                    #'string<)
                                   :activate-callback nil
                                   :help-string "Packages selected for removal:\n"

-                                  :completion-string t
-                                  ))
+                                  :completion-string t))

        (setq tmpbuf (get-buffer-create tmpbuf))
        (display-buffer tmpbuf)
        (setq do-delete (yes-or-no-p "Remove these packages? "))
        (setq tmpbuf (get-buffer-create tmpbuf))
        (display-buffer tmpbuf)
        (setq do-delete (yes-or-no-p "Remove these packages? "))

@@ -372,11 +352,12 @@ and whether or not it is up-to-date."
        (message "Deleting selected packages ...") (sit-for 0)
        (mapcar (lambda (pkg)
                  (package-admin-delete-binary-package
        (message "Deleting selected packages ...") (sit-for 0)
        (mapcar (lambda (pkg)
                  (package-admin-delete-binary-package

-                  pkg (package-admin-get-install-dir pkg nil)))
+                  pkg (package-admin-get-install-dir pkg)))

                (nreverse pui-deleted-packages))
        (message "Packages deleted"))))
         
                (nreverse pui-deleted-packages))
        (message "Packages deleted"))))
         

-  (let ( (tmpbuf "*Packages-To-Install*") do-install)
+  (let ((tmpbuf "*Packages-To-Install*") 
+       do-install)

     (if pui-selected-packages
        (progn
          ;; Don't change window config when asking the user if he really
     (if pui-selected-packages
        (progn
          ;; Don't change window config when asking the user if he really

@@ -390,21 +371,18 @@ and whether or not it is up-to-date."
               (sort (mapcar #'symbol-name pui-selected-packages) #'string<)
               :activate-callback nil
               :help-string "Packages selected for installation:\n"
               (sort (mapcar #'symbol-name pui-selected-packages) #'string<)
               :activate-callback nil
               :help-string "Packages selected for installation:\n"

-              :completion-string t
-              ))
+              :completion-string t))

            (setq tmpbuf (get-buffer-create tmpbuf))
            (display-buffer tmpbuf)
            (setq do-install (y-or-n-p "Install these packages? "))
            (setq tmpbuf (get-buffer-create tmpbuf))
            (display-buffer tmpbuf)
            (setq do-install (y-or-n-p "Install these packages? "))

-           (kill-buffer tmpbuf)
-           )
+           (kill-buffer tmpbuf))

          (if do-install
              (progn
                (save-excursion
                  ;; Clear old temp buffer history
                  (set-buffer (get-buffer-create package-admin-temp-buffer))
                  (buffer-disable-undo package-admin-temp-buffer)
          (if do-install
              (progn
                (save-excursion
                  ;; Clear old temp buffer history
                  (set-buffer (get-buffer-create package-admin-temp-buffer))
                  (buffer-disable-undo package-admin-temp-buffer)

-                 (erase-buffer package-admin-temp-buffer)
-                 )
+                 (erase-buffer package-admin-temp-buffer))

                (message "Installing selected packages ...") (sit-for 0)
                (if (catch 'done
                      (mapcar (lambda (pkg)
                (message "Installing selected packages ...") (sit-for 0)
                (if (catch 'done
                      (mapcar (lambda (pkg)

@@ -415,18 +393,14 @@ and whether or not it is up-to-date."
                      t)
                    (progn
                      (pui-list-packages)
                      t)
                    (progn
                      (pui-list-packages)

-                     (message "Packages installed")
-                     ))
-               )
-           (clear-message)
-           )
-         )
+                     (message "Packages installed"))))
+           (clear-message)))

       (if pui-deleted-packages
          (pui-list-packages)
       (if pui-deleted-packages
          (pui-list-packages)

-       (error "No packages have been selected!")))
+       (error 'invalid-operation
+              "No packages have been selected!")))

     ;; sync with windows type systems
     ;; sync with windows type systems

-    (package-net-update-installed-db)
-    ))
+    (package-net-update-installed-db)))

 
 (defun pui-add-required-packages ()
   "Select packages required by those already selected for installation."
 
 (defun pui-add-required-packages ()
   "Select packages required by those already selected for installation."

@@ -482,20 +456,21 @@ and whether or not it is up-to-date."
                              nil nil nil nil nil 'pui)
                 (message "added dependencies"))
              (clear-message)))
                              nil nil nil nil nil 'pui)
                 (message "added dependencies"))
              (clear-message)))

-      (error "No packages have been selected!"))))
+      (error 'invalid-operation
+            "No packages have been selected!"))))

 
 (defun pui-help-echo (extent &optional force-update)
   "Display additional package info in the modeline.
 EXTENT determines the package to display (the package information is
 attached to the extent as properties)."
 
 (defun pui-help-echo (extent &optional force-update)
   "Display additional package info in the modeline.
 EXTENT determines the package to display (the package information is
 attached to the extent as properties)."

-  (let (pkg-sym info inst-ver auth-ver date maintainer balloon req)
+  (let (pkg-sym info inst-ver inst-auth-ver auth-ver date maintainer balloon req)

     (if (or force-update (not (current-message))
     (if (or force-update (not (current-message))

-           (string-match ".*: .*: " (current-message))
-           )
+           (string-match ".*: .*: " (current-message)))

        (progn
          (setq pkg-sym (extent-property extent 'pui-package)
                info (extent-property extent 'pui-info)
                inst-ver (package-get-key pkg-sym :version)
        (progn
          (setq pkg-sym (extent-property extent 'pui-package)
                info (extent-property extent 'pui-info)
                inst-ver (package-get-key pkg-sym :version)

+               inst-auth-ver (package-get-key pkg-sym :author-version)

                auth-ver (package-get-info-prop info 'author-version)
                date (package-get-info-prop info 'date)
                maintainer (package-get-info-prop info 'maintainer)
                auth-ver (package-get-info-prop info 'author-version)
                date (package-get-info-prop info 'date)
                maintainer (package-get-info-prop info 'maintainer)

@@ -507,22 +482,16 @@ attached to the extent as properties)."
                (setq balloon (format "
 Package Information:  [For package: \"%s\"]
 ================
                (setq balloon (format "
 Package Information:  [For package: \"%s\"]
 ================

-Installed Version : %.2f
-Author Version : %s
-Maintainer: %s
-Released: %s
+Installed Upstream Ver: %s  Available Upstream Ver: %s
+Maintainer : %s
+Released : %s

 Required Packages : %s\n\n"
 Required Packages : %s\n\n"

-                                     pkg-sym inst-ver auth-ver maintainer 
+                                     pkg-sym inst-auth-ver auth-ver maintainer 

                                      date req))
                (set-extent-property extent 'balloon-help balloon)))
                                      date req))
                (set-extent-property extent 'balloon-help balloon)))

-         (if pui-list-verbose
-             (format 
-              "Inst V: %.2f Auth V: %s Maint: %s" 
-              inst-ver auth-ver maintainer)
-           (format "%.2f : %s : %s"
-                   inst-ver auth-ver maintainer))
-         ))
-    ))
+         (format 
+          "Installed upstream ver: %s  Available upstream ver: %s" 
+          inst-auth-ver auth-ver)))))

 
 (defun pui-display-info (&optional no-error event)
   "Display additional package info in the modeline.
 
 (defun pui-display-info (&optional no-error event)
   "Display additional package info in the modeline.

@@ -535,8 +504,25 @@ Designed to be called interactively (from a keypress)."
          (message (pui-help-echo extent t))
        (if no-error
            (clear-message nil)
          (message (pui-help-echo extent t))
        (if no-error
            (clear-message nil)

-         (error "No package under cursor!")))
-      )))
+         (error 'invalid-operation
+                "No package under cursor!"))))))
+
+(defun pui-display-maintainer (&optional no-error event)
+  "Display a package's maintainer in the minibuffer."
+  (interactive)
+  (let (extent pkg-sym info maintainer)
+    (save-excursion
+      (beginning-of-line)
+      (if (setq extent         (extent-at (point) (current-buffer) 'pui))
+         (progn
+           (setq pkg-sym (extent-property extent 'pui-package)
+                 info (extent-property extent 'pui-info)
+                 maintainer (package-get-info-prop info 'maintainer))
+           (message (format "Maintainer: %s" maintainer)))
+       (if no-error
+           (clear-message nil)
+         (error 'invalid-operation
+                "No package under cursor!"))))))

 
 (defvar pui-menu
   '("Packages"
 
 (defvar pui-menu
   '("Packages"

@@ -580,11 +566,13 @@ Useful keys:
   `\\[pui-add-required-packages]' to add any packages required by those selected.
   `\\[pui-install-selected-packages]' to install/delete selected packages.
   `\\[pui-display-info]' to display additional information about the package in the modeline.
   `\\[pui-add-required-packages]' to add any packages required by those selected.
   `\\[pui-install-selected-packages]' to install/delete selected packages.
   `\\[pui-display-info]' to display additional information about the package in the modeline.

+  `\\[pui-display-maintainer]' to display the package's maintainer in the minibuffer

   `\\[pui-list-packages]' to refresh the package list.
   `\\[pui-toggle-verbosity-redisplay]' to toggle between a verbose and non-verbose display.
   `\\[pui-quit]' to kill this buffer.
 "
   `\\[pui-list-packages]' to refresh the package list.
   `\\[pui-toggle-verbosity-redisplay]' to toggle between a verbose and non-verbose display.
   `\\[pui-quit]' to kill this buffer.
 "

-  (error "You cannot enter this mode directly. Use `pui-list-packages'"))
+  (error 'invalid-operation
+        "You cannot enter this mode directly. Use `pui-list-packages'"))

 
 (put 'list-packages-mode 'mode-class 'special)
 
 
 (put 'list-packages-mode 'mode-class 'special)
 

@@ -597,9 +585,9 @@ which are out-of-date (a newer version is available).  The user can then
 select packages for installation via the keyboard or mouse."
   (interactive)
   (package-get-require-base t)
 select packages for installation via the keyboard or mouse."
   (interactive)
   (package-get-require-base t)

-  (let ( (outbuf (get-buffer-create pui-info-buffer))
-        (sep-string "===============================================================================\n")
-        start )
+  (let ((outbuf (get-buffer-create pui-info-buffer))
+       (sep-string "===============================================================================\n")
+       start)

     (message "Creating package list ...") (sit-for 0)
     (set-buffer outbuf)
     (setq buffer-read-only nil)
     (message "Creating package list ...") (sit-for 0)
     (set-buffer outbuf)
     (setq buffer-read-only nil)

@@ -643,27 +631,21 @@ Warning: No download sites specified.  Package index may be out of date.
               (progn
                 (setq current-vers (package-get-key pkg-sym :version))
                 (cond
               (progn
                 (setq current-vers (package-get-key pkg-sym :version))
                 (cond

-                 ( (not current-vers)
-                   (setq current-vers "-----") )
-                 ( (stringp current-vers)
-                   (setq current-vers
-                         (format "%.2f"
-                                 (string-to-number current-vers))) )
-                 ( (numberp current-vers)
-                   (setq current-vers (format "%.2f" current-vers)) )
-                 )
+                 ((not current-vers)
+                  (setq current-vers "-----"))
+                 ((stringp current-vers)
+                  (setq current-vers
+                        (format "%.2f"
+                                (string-to-number current-vers))))
+                 ((numberp current-vers)
+                  (setq current-vers (format "%.2f" current-vers))))

                 (insert
                  (format "%s %-15s %-5.2f  %-5s  %s\n"
                          (car disp) pkg-sym 
                          (if (stringp version)
                              (string-to-number version)
                            version)
                 (insert
                  (format "%s %-15s %-5.2f  %-5s  %s\n"
                          (car disp) pkg-sym 
                          (if (stringp version)
                              (string-to-number version)
                            version)

-                         current-vers desc))
-                ;; (insert
-                ;;  (format "\t\t  %-12s  %s\n"
-                ;;    (package-get-info-prop info 'author-version)
-                ;;    (package-get-info-prop info 'date)))
-                )
+                         current-vers desc)))

             (insert (format "%s %-15s %-5s %s\n"
                             (car disp)
                             pkg-sym version desc)))
             (insert (format "%s %-15s %-5s %s\n"
                             (car disp)
                             pkg-sym version desc)))

@@ -681,8 +663,7 @@ Warning: No download sites specified.  Package index may be out of date.
           (set-extent-property extent 'pui-package pkg-sym)
           (set-extent-property extent 'pui-info info)
           (set-extent-property extent 'help-echo 'pui-help-echo)
           (set-extent-property extent 'pui-package pkg-sym)
           (set-extent-property extent 'pui-info info)
           (set-extent-property extent 'help-echo 'pui-help-echo)

-          (set-extent-property extent 'keymap pui-package-keymap)
-          ))
+          (set-extent-property extent 'keymap pui-package-keymap)))

      (sort (copy-sequence package-get-base)
           #'(lambda (a b)
               (string< (symbol-name (car a))
      (sort (copy-sequence package-get-base)
           #'(lambda (a b)
               (string< (symbol-name (car a))

@@ -700,9 +681,7 @@ Warning: No download sites specified.  Package index may be out of date.
       (set-buffer-menubar current-menubar)
       (add-submenu '() pui-menu)
       (setq mode-popup-menu pui-menu))
       (set-buffer-menubar current-menubar)
       (add-submenu '() pui-menu)
       (setq mode-popup-menu pui-menu))

-    (clear-message)
-    ;;    (message (substitute-command-keys "Press `\\[pui-help]' for help."))
-    ))
+    (clear-message)))

 
 ;;;###autoload
 (defalias 'list-packages 'pui-list-packages)
 
 ;;;###autoload
 (defalias 'list-packages 'pui-list-packages)

diff --git a/lisp/packages.el b/lisp/packages.el
index e0b8fdb..86f1782 100644 (file)
--- a/lisp/packages.el
+++ b/lisp/packages.el
@@ -1,6 +1,7 @@
 ;;; packages.el --- Low level support for XEmacs packages
 
 ;; Copyright (C) 1997 Free Software Foundation, Inc.
 ;;; packages.el --- Low level support for XEmacs packages
 
 ;; Copyright (C) 1997 Free Software Foundation, Inc.

+;; Copyright (C) 2002, 2003 Ben Wing.

 
 ;; Author: Steven L Baur <steve@xemacs.org>
 ;; Maintainer: Steven L Baur <steve@xemacs.org>
 
 ;; Author: Steven L Baur <steve@xemacs.org>
 ;; Maintainer: Steven L Baur <steve@xemacs.org>

@@ -96,6 +97,10 @@ show up in.
 The third component is a thunk which, if it returns NIL, causes
 the directory to be ignored."
   (list
 The third component is a thunk which, if it returns NIL, causes
 the directory to be ignored."
   (list

+   (list (paths-construct-path (list user-init-directory "site-packages"))
+        'early #'(lambda () t))
+   (list (paths-construct-path (list user-init-directory "infodock-packages"))
+        'early #'(lambda () (featurep 'infodock)))

    (list (paths-construct-path (list user-init-directory "mule-packages"))
         'early #'(lambda () (featurep 'mule)))
    (list (paths-construct-path (list user-init-directory "xemacs-packages"))
    (list (paths-construct-path (list user-init-directory "mule-packages"))
         'early #'(lambda () (featurep 'mule)))
    (list (paths-construct-path (list user-init-directory "xemacs-packages"))

@@ -129,11 +134,13 @@ the directory to be ignored."
 (defun package-require (name version)
   (let ((pkg (assq name packages-package-list)))
     (cond ((null pkg)
 (defun package-require (name version)
   (let ((pkg (assq name packages-package-list)))
     (cond ((null pkg)

-          (error "Package %s has not been loaded into this XEmacsen"
-                 name))
+          (error 'invalid-state
+                 (format "Package %s has not been loaded into this XEmacsen"
+                         name)))

          ((< (package-get-key name :version) version)
          ((< (package-get-key name :version) version)

-          (error "Need version %g of package %s, got version %g"
-                 version name (cdr pkg)))
+          (error 'search-failed
+                 (format "Need version %g of package %s, got version %g"
+                         version name (cdr pkg))))

          (t t))))
 
 (defun package-delete-name (name)
          (t t))))
 
 (defun package-delete-name (name)

@@ -144,40 +151,14 @@ the directory to be ignored."
     ;; one.
     (while (setq pkg (assq name packages-package-list))
       (setq packages-package-list (delete pkg (copy-alist
     ;; one.
     (while (setq pkg (assq name packages-package-list))
       (setq packages-package-list (delete pkg (copy-alist

-                                              packages-package-list)))
-      )
-    ))
+                                              packages-package-list))))))

 
 ;;; Build time stuff
 
 (defvar autoload-file-name "auto-autoloads.el"
   "Filename that autoloads are expected to be found in.")
 
 
 ;;; Build time stuff
 
 (defvar autoload-file-name "auto-autoloads.el"
   "Filename that autoloads are expected to be found in.")
 

-(defvar packages-hardcoded-lisp
-  '(
-    ;; Nothing at this time
-    )
-  "Lisp packages that are always dumped with XEmacs.
-This includes every package that is loaded directly by a package listed
-in dumped-lisp.el and is not itself listed.")
-
-(defvar packages-useful-lisp
-  '("bytecomp"
-    "byte-optimize"
-    "shadow"
-    "cl-macs")
-  "Lisp packages that need early byte compilation.")
-
-(defvar packages-unbytecompiled-lisp
-  '("paths.el"
-    "dumped-lisp.el"
-    "dumped-pkg-lisp.el"
-    "version.el"
-    "very-early-lisp.el")
-  "Lisp packages that should not be byte compiled.")
-
-
-;; Copied from help.el, could possibly move it to here permanently.
+;; Moved from help.el.

 ;; Unlike the FSF version, our `locate-library' uses the `locate-file'
 ;; primitive, which should make it lightning-fast.
 
 ;; Unlike the FSF version, our `locate-library' uses the `locate-file'
 ;; primitive, which should make it lightning-fast.
 

@@ -352,7 +333,7 @@ This function is basically a wrapper over `locate-file'."
   ;; make sure paths-find-version-directory and paths-find-site-directory
   ;; don't both pick up version-independent directories ...
   (let ((version-directory (paths-find-version-directory roots base nil nil t))
   ;; make sure paths-find-version-directory and paths-find-site-directory
   ;; don't both pick up version-independent directories ...
   (let ((version-directory (paths-find-version-directory roots base nil nil t))

-       (site-directory (paths-find-site-directory roots base nil nil t)))
+       (site-directory (paths-find-site-directory roots base)))

     (paths-uniq-append
      (and version-directory (list version-directory))
      (and site-directory (list site-directory)))))
     (paths-uniq-append
      (and version-directory (list version-directory))
      (and site-directory (list site-directory)))))

diff --git a/lisp/specifier.el b/lisp/specifier.el
index fb26c2e..55801b1 100644 (file)
--- a/lisp/specifier.el
+++ b/lisp/specifier.el
@@ -1,7 +1,7 @@
 ;;; specifier.el --- Lisp interface to specifiers
 
 ;;; specifier.el --- Lisp interface to specifiers
 

-;; Copyright (C) 1997 Free Software Foundation, Inc.
-;; Copyright (C) 1995, 1996, 2000 Ben Wing.
+;; Copyright (C) 1997, 2004 Free Software Foundation, Inc.
+;; Copyright (C) 1995, 1996, 2000, 2002 Ben Wing.

 
 ;; Author: Ben Wing <ben@xemacs.org>
 ;; Keywords: internal, dumped
 
 ;; Author: Ben Wing <ben@xemacs.org>
 ;; Keywords: internal, dumped

@@ -32,16 +32,15 @@
 ;;; Code:
 
 (defun make-specifier-and-init (type spec-list &optional dont-canonicalize)
 ;;; Code:
 
 (defun make-specifier-and-init (type spec-list &optional dont-canonicalize)

-  "Create and initialize a new specifier.
-
-This is a front-end onto `make-specifier' that allows you to create a
-specifier and add specs to it at the same time.  TYPE specifies the
-specifier type.  SPEC-LIST supplies the specification(s) to be added
-to the specifier. Normally, almost any reasonable abbreviation of the
-full spec-list form is accepted, and is converted to the full form;
-however, if optional argument DONT-CANONICALIZE is non-nil, this
-conversion is not performed, and the SPEC-LIST must already be in full
-form.  See `canonicalize-spec-list'."
+  "Create and initialize a specifier of type TYPE with spec(s) SPEC-LIST.
+
+A convenience API combining `make-specifier' and `set-specifier', allowing you
+to create a specifier and add specs to it at the same time.
+TYPE specifies the specifier type.  See `make-specifier' for known types.
+SPEC-LIST supplies the specification(s) to be added to the specifier, in any
+  form acceptable to `canonicalize-spec-list'.
+Optional DONT-CANONICALIZE, if non-nil, inhibits the conversion, and the
+  SPEC-LIST must already be in full form."

   (let ((sp (make-specifier type)))
     (if (not dont-canonicalize)
        (setq spec-list (canonicalize-spec-list spec-list type)))
   (let ((sp (make-specifier type)))
     (if (not dont-canonicalize)
        (setq spec-list (canonicalize-spec-list spec-list type)))

@@ -53,10 +52,12 @@ form.  See `canonicalize-spec-list'."
 (defun map-specifier (ms-specifier ms-func &optional ms-locale ms-maparg)
   "Apply MS-FUNC to the specification(s) for MS-LOCALE in MS-SPECIFIER.
 
 (defun map-specifier (ms-specifier ms-func &optional ms-locale ms-maparg)
   "Apply MS-FUNC to the specification(s) for MS-LOCALE in MS-SPECIFIER.
 

-If MS-LOCALE is a locale, MS-FUNC will be called for that locale.
-If MS-LOCALE is a locale type, MS-FUNC will be mapped over all locales
-of that type.  If MS-LOCALE is 'all or nil, MS-FUNC will be mapped
-over all locales in MS-SPECIFIER.
+If optional MS-LOCALE is a locale, MS-FUNC will be called for that locale.
+If MS-LOCALE is a locale type, MS-FUNC will be mapped over all locales of that
+type.  If MS-LOCALE is 'all or nil, MS-FUNC will be mapped over all locales in
+MS-SPECIFIER.
+
+Optional MS-MAPARG will be passed to MS-FUNC.

 
 MS-FUNC is called with four arguments: the MS-SPECIFIER, the locale
 being mapped over, the inst-list for that locale, and the
 
 MS-FUNC is called with four arguments: the MS-SPECIFIER, the locale
 being mapped over, the inst-list for that locale, and the

@@ -76,7 +77,7 @@ returns nil."
 (defun canonicalize-inst-pair (inst-pair specifier-type &optional noerror)
   "Canonicalize the given INST-PAIR.
 
 (defun canonicalize-inst-pair (inst-pair specifier-type &optional noerror)
   "Canonicalize the given INST-PAIR.
 

-SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+SPECIFIER-TYPE specifies the type of specifier that this INST-PAIR

 will be used for.
 
 Canonicalizing means converting to the full form for an inst-pair, i.e.
 will be used for.
 
 Canonicalizing means converting to the full form for an inst-pair, i.e.

@@ -169,8 +170,7 @@ otherwise return t."
 (defun canonicalize-spec (spec specifier-type &optional noerror)
   "Canonicalize the given SPEC (a specification).
 
 (defun canonicalize-spec (spec specifier-type &optional noerror)
   "Canonicalize the given SPEC (a specification).
 

-SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
-will be used for.
+SPECIFIER-TYPE is the type of specifier that this SPEC will be used for.

 
 Canonicalizing means converting to the full form for a spec, i.e.
 `(LOCALE (TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
 
 Canonicalizing means converting to the full form for a spec, i.e.
 `(LOCALE (TAG-SET . INSTANTIATOR) ...)'.  This function accepts a

@@ -222,9 +222,42 @@ a possibly abbreviated specification or a list of such things. (See
 accepted by `set-specifier' and such into a form suitable for
 `add-spec-list-to-specifier'.
 
 accepted by `set-specifier' and such into a form suitable for
 `add-spec-list-to-specifier'.
 

-This function tries extremely hard to resolve any ambiguities,
-and the built-in specifier types (font, image, toolbar, etc.) are
-designed so that there won't be any ambiguities.
+The canonicalization algorithm is as follows:
+
+1. Attempt to parse SPEC-LIST as a single, possibly abbreviated, specification.
+2. If (1) fails, attempt to parse SPEC-LIST as a list of (abbreviated)
+   specifications.
+3. If (2) fails, SPEC-LIST is invalid.
+
+A possibly abbreviated specification SPEC is parsed by
+
+1. Attempt to parse SPEC as a possibly abbreviated inst-list.
+2. If (1) fails, attempt to parse SPEC as a cons of a locale and an
+   (abbreviated) inst-list.
+3. If (2) fails, SPEC is invalid.
+
+A possibly abbreviated inst-list INST-LIST is parsed by
+
+1. Attempt to parse INST-LIST as a possibly abbreviated inst-pair.
+2. If (1) fails, attempt to parse INST-LIST as a list of (abbreviated)
+   inst-pairs.
+3. If (2) fails, INST-LIST is invalid.
+
+A possibly abbreviated inst-pair INST-PAIR is parsed by
+
+1. Check if INST-PAIR is `valid-instantiator-p'.
+2. If not, check if INST-PAIR is a cons of something that is a tag, ie,
+   `valid-specifier-tag-p', and something that is `valid-instantiator-p'.
+3. If not, check if INST-PAIR is a cons of a list of tags and something that
+   is `valid-instantiator-p'.
+
+In summary, this function generally prefers more abbreviated forms.
+
+This function tries extremely hard to resolve any ambiguities, and the
+built-in specifier types (font, image, toolbar, etc.) are designed so that
+there won't be any ambiguities.  (#### Unfortunately there are bugs in the
+treatment of toolbar spec-lists and generic spec-lists; avoid depending on
+canonicalization for these types.)

 
 If NOERROR is nil, signal an error if the spec-list is invalid;
 otherwise return t."
 
 If NOERROR is nil, signal an error if the spec-list is invalid;
 otherwise return t."

@@ -265,51 +298,47 @@ otherwise return t."
            (nreverse result)))))))
 
 (defun set-specifier (specifier value &optional locale tag-set how-to-add)
            (nreverse result)))))))
 
 (defun set-specifier (specifier value &optional locale tag-set how-to-add)

-  "Add a specification or specifications to SPECIFIER.
+  "Add the specification(s) given by VALUE to SPECIFIER in LOCALE.
+
+VALUE may be any of the values accepted by `canonicalize-spec-list', including
+
+-- an instantiator (either a Lisp object which will be returned when the
+   specifier is instanced, or a Lisp object that can be instantiated to
+   produce an opaque value: eg, a font name (string) can be used for a font
+   specifier, but an instance will be a font object)
+-- a list of instantiators
+-- a cons of a locale and an instantiator, or of a locale and a list of
+   instantiators
+-- a cons of a tag or tag-set and an instantiator (or list of instantiators)
+-- a cons of a locale and the previous type of item
+-- a list of one or more of any of the previous types of items
+-- a canonical spec-list.
+
+See `canonicalize-spec-list' for details.  If you need to know the details,
+though, strongly consider using the unambiguous APIs `add-spec-to-specifier'
+and `add-spec-list-to-specifier' instead.
+
+Finally, VALUE can itself be a specifier (of the same type as
+SPECIFIER), if you want to copy specifications from one specifier
+to another; this is equivalent to calling `copy-specifier', and
+LOCALE, TAG-SET, and HOW-TO-ADD have the same semantics as with
+that function.
+
+Note that a VALUE of `nil' is either illegal or will be treated as a value of
+`nil'; it does not remove existing specifications.  Use `remove-specifier' for
+that.  N.B. `remove-specifier' defaults to removing all specifications, not
+just the 'global one!
+
+Warning: this function is inherently heuristic, and should not be relied on to
+properly resolve ambiguities, when specifier instantiators can be lists
+\(currently, for toolbar specifiers and generic specifiers).  In those cases
+use either `add-spec-to-specifier' or `add-spec-list-to-specifier'.

 
 

-This function adds a specification of VALUE in locale LOCALE.

 LOCALE indicates where this specification is active, and should be
 a buffer, a window, a frame, a device, or the symbol `global' to
 LOCALE indicates where this specification is active, and should be
 a buffer, a window, a frame, a device, or the symbol `global' to

-indicate that it applies everywhere.  LOCALE usually defaults to
-`global' if omitted.
-
-VALUE is usually what is called an \"instantiator\" (which, roughly
-speaking, corresponds to the \"value\" of the property governed by
-SPECIFIER).  The valid instantiators for SPECIFIER depend on the type
-of SPECIFIER (which you can determine using `specifier-type').  The
-specifier `scrollbar-width', for example, is of type `integer',
-meaning its valid instantiators are integers.  The specifier governing
-the background color of the `default' face (you can retrieve this
-specifier using `(face-background 'default)') is of type `color',
-meaning its valid instantiators are strings naming colors and
-color-instance objects.  For some types of specifiers, such as `image'
-and `toolbar', the instantiators can be very complex.  Generally this
-is documented in the appropriate creation function --
-e.g. `make-color-specifier', `make-font-specifier',
-`make-image-specifier' -- or in the global variable holding the most
-common specifier for that type (`default-toolbar', `default-gutter',
-`current-display-table').
-
-NOTE: It does *not* work to give a VALUE of nil as a way of
-removing the specifications for a locale.  Use `remove-specifier'
-instead. (And keep in mind that, if you omit the LOCALE argument
-to `remove-specifier', it removes *all* specifications!  If you
-want to remove just the `global' specification, make sure to
-specify a LOCALE of `global'.)
-
-VALUE can also be a list of instantiators.  This means basically,
-\"try each one in turn until you get one that works\".  This allows
-you to give funky instantiators that may only work in some cases,
-and provide more normal backups for the other cases. (For example,
-you might like the color \"darkseagreen2\", but some X servers
-don't recognize this color, so you could provide a backup
-\"forest green\".  Color TTY devices probably won't recognize this
-either, so you could provide a second backup \"green\".  You'd
-do this by specifying this list of instantiators:
-
-'(\"darkseagreen2\" \"forest green\" \"green\")
-
-VALUE can also be various more complicated forms; see below.
+indicate that it applies everywhere.  LOCALE defaults to
+`global' if omitted, and is overridden by locales provided by VALUE (in the
+cases where value is a full specification or a spec-list).

 
 Optional argument TAG-SET is a tag or a list of tags, to be associated
 with the VALUE.  Tags are symbols (usually naming device types, such
 
 Optional argument TAG-SET is a tag or a list of tags, to be associated
 with the VALUE.  Tags are symbols (usually naming device types, such

@@ -329,25 +358,6 @@ the default behavior of `remove-tag-set-prepend' is usually fine.
 See `copy-specifier' and `add-spec-to-specifier' for a full
 description of what each of these means.
 
 See `copy-specifier' and `add-spec-to-specifier' for a full
 description of what each of these means.
 

-VALUE can actually be anything acceptable to `canonicalize-spec-list';
-this includes, among other things:
-
--- a cons of a locale and an instantiator (or list of instantiators)
--- a cons of a tag or tag-set and an instantiator (or list of
-   instantiators)
--- a cons of a locale and the previous type of item
--- a list of one or more of any of the previous types of items
-
-However, in these cases, you cannot give a LOCALE or TAG-SET,
-because they do not make sense. (You will probably get an error if
-you try this.)
-
-Finally, VALUE can itself be a specifier (of the same type as
-SPECIFIER), if you want to copy specifications from one specifier
-to another; this is equivalent to calling `copy-specifier', and
-LOCALE, TAG-SET, and HOW-TO-ADD have the same semantics as with
-that function.
-

 Note that `set-specifier' is exactly complementary to `specifier-specs'
 except in the case where SPECIFIER has no specs at all in it but nil
 is a valid instantiator (in that case, `specifier-specs' will return
 Note that `set-specifier' is exactly complementary to `specifier-specs'
 except in the case where SPECIFIER has no specs at all in it but nil
 is a valid instantiator (in that case, `specifier-specs' will return

@@ -355,14 +365,7 @@ nil (meaning no specs) and `set-specifier' will interpret the `nil'
 as meaning \"I'm adding a global instantiator and its value is `nil'\"),
 or in strange cases where there is an ambiguity between a spec-list
 and an inst-list, etc. (The built-in specifier types are designed
 as meaning \"I'm adding a global instantiator and its value is `nil'\"),
 or in strange cases where there is an ambiguity between a spec-list
 and an inst-list, etc. (The built-in specifier types are designed

-in such a way as to avoid any such ambiguities.)
-
-NOTE: If you want to work with spec-lists, you should probably not
-use either `set-specifier' or `specifier-specs', but should use the
-lower-level functions `add-spec-list-to-specifier' and `specifier-spec-list'.
-These functions always work with fully-qualified spec-lists; thus, there
-is no possibility for ambiguity and no need to go through the function
-`canonicalize-spec-list', which is potentially time-consuming."
+in such a way as to avoid any such ambiguities.)"

 
   ;; backward compatibility: the old function had HOW-TO-ADD as the
   ;; third argument and no arguments after that.
 
   ;; backward compatibility: the old function had HOW-TO-ADD as the
   ;; third argument and no arguments after that.

@@ -406,7 +409,7 @@ is no possibility for ambiguity and no need to go through the function
   value)
 
 (defun modify-specifier-instances (specifier func &optional args force default
   value)
 
 (defun modify-specifier-instances (specifier func &optional args force default

-                                            locale tag-set)
+                                  locale tag-set)

   "Modify all specifications that match LOCALE and TAG-SET by FUNC.
 
 For each specification that exists for SPECIFIER, in locale LOCALE
   "Modify all specifications that match LOCALE and TAG-SET by FUNC.
 
 For each specification that exists for SPECIFIER, in locale LOCALE

diff --git a/lisp/update-elc.el b/lisp/update-elc.el
index 1fda28d..53ca9ee 100644 (file)
--- a/lisp/update-elc.el
+++ b/lisp/update-elc.el
@@ -106,7 +106,6 @@
   (setq preloaded-file-list
        (append packages-hardcoded-lisp
                preloaded-file-list
   (setq preloaded-file-list
        (append packages-hardcoded-lisp
                preloaded-file-list

-               packages-useful-lisp

                site-load-packages))
   (while preloaded-file-list
     (let ((arg (car preloaded-file-list)))
                site-load-packages))
   (while preloaded-file-list
     (let ((arg (car preloaded-file-list)))

@@ -131,25 +130,25 @@
                                 dumped-exe))))
              (setq need-to-dump t)))
 
                                 dumped-exe))))
              (setq need-to-dump t)))
 

-      (if (null (member (file-name-nondirectory arg)
-                       packages-unbytecompiled-lisp))
+;      (if (null (member (file-name-nondirectory arg)
+;                      packages-unbytecompiled-lisp))
+;        (progn
+      (setq arg (locate-library arg))
+      (if (null arg)

          (progn
          (progn

-           (setq arg (locate-library arg))
-           (if (null arg)
-               (progn
-                 (print (format "Error: Library file %s not found"
-                                (car preloaded-file-list)))
-                 ;; Uncomment in case of trouble
-                 ;;(print (format "late-packages: %S" late-packages))
-                 ;;(print (format "guessed-roots: %S" (paths-find-emacs-roots invocation-directory invocation-name)))
-                 (kill-emacs)))
-           (if (string-match "\\.elc?\\'" arg)
-               (setq arg (substring arg 0 (match-beginning 0))))
-           (if (and (null (member arg processed))
-                    (file-exists-p (concat arg ".el"))
-                    (file-newer-than-file-p (concat arg ".el")
-                                            (concat arg ".elc")))
-               (setq processed (cons (concat arg ".el") processed)))))
+           (print (format "Error: Library file %s not found"
+                          (car preloaded-file-list)))
+           ;; Uncomment in case of trouble
+           ;;(print (format "late-packages: %S" late-packages))
+           ;;(print (format "guessed-roots: %S" (paths-find-emacs-roots invocation-directory invocation-name)))
+           (kill-emacs)))
+      (if (string-match "\\.elc?\\'" arg)
+         (setq arg (substring arg 0 (match-beginning 0))))
+      (if (and (null (member arg processed))
+              (file-exists-p (concat arg ".el"))
+              (file-newer-than-file-p (concat arg ".el")
+                                      (concat arg ".elc")))
+         (setq processed (cons (concat arg ".el") processed)))

       (setq preloaded-file-list (cdr preloaded-file-list))))
 
   (if need-to-dump
       (setq preloaded-file-list (cdr preloaded-file-list))))
 
   (if need-to-dump

diff --git a/lisp/win32-native.el b/lisp/win32-native.el
index a7187e2..23b38d0 100644 (file)
--- a/lisp/win32-native.el
+++ b/lisp/win32-native.el
@@ -56,8 +56,8 @@
 (setq path-separator ";")
 
 ;; Set the null device (for compile.el).
 (setq path-separator ";")
 
 ;; Set the null device (for compile.el).

-;; #### There should be such a global thingy as null-device - kkm
-(setq grep-null-device "NUL")
+;; Backward-compatibility; recent compile.el uses null-device if available.
+(setq grep-null-device null-device)

 
 ;; Set the grep regexp to match entries with drive letters.
 (setq grep-regexp-alist
 
 ;; Set the grep regexp to match entries with drive letters.
 (setq grep-regexp-alist

diff --git a/lisp/window-xemacs.el b/lisp/window-xemacs.el
index 4950427..502c6dc 100644 (file)
--- a/lisp/window-xemacs.el
+++ b/lisp/window-xemacs.el
@@ -385,7 +385,7 @@ Returns the window displaying BUFFER."
         ;; and does `returns' all over the place and there's no sense
         ;; in trying to rewrite it to be more Lispy.
         (catch 'done
         ;; and does `returns' all over the place and there's no sense
         ;; in trying to rewrite it to be more Lispy.
         (catch 'done

-          (let (window old-frame target-frame explicit-frame)
+          (let (window old-frame target-frame explicit-frame shrink-it)

             (setq old-frame (or (last-nonminibuf-frame) (selected-frame)))
             (setq buffer (get-buffer buffer))
             (check-argument-type 'bufferp buffer)
             (setq old-frame (or (last-nonminibuf-frame) (selected-frame)))
             (setq buffer (get-buffer buffer))
             (check-argument-type 'bufferp buffer)

@@ -573,9 +573,7 @@ Returns the window displaying BUFFER."
                                (and (window-leftmost-p window)
                                     (window-rightmost-p window))))
                       (setq window (split-window window))
                                (and (window-leftmost-p window)
                                     (window-rightmost-p window))))
                       (setq window (split-window window))

-                    (let (upper
-;;                        lower
-                          other)
+                    (let (upper other)

                       (setq window (get-lru-window target-frame))
                       ;; If the LRU window is selected, and big enough,
                       ;; and can be split, split it.
                       (setq window (get-lru-window target-frame))
                       ;; If the LRU window is selected, and big enough,
                       ;; and can be split, split it.

@@ -605,11 +603,9 @@ Returns the window displaying BUFFER."
                       ;; even out their heights.
                       (if (window-previous-child window)
                           (setq other (window-previous-child window)
                       ;; even out their heights.
                       (if (window-previous-child window)
                           (setq other (window-previous-child window)

-;;                              lower window

                                 upper other))
                       (if (window-next-child window)
                           (setq other (window-next-child window)
                                 upper other))
                       (if (window-next-child window)
                           (setq other (window-next-child window)

-;;                              lower other

                                 upper window))
                       ;; Check that OTHER and WINDOW are vertically arrayed.
                       (if (and other
                                 upper window))
                       ;; Check that OTHER and WINDOW are vertically arrayed.
                       (if (and other

@@ -622,8 +618,11 @@ Returns the window displaying BUFFER."
                                                 2)
                                              (window-height upper))
                                           nil upper))
                                                 2)
                                              (window-height upper))
                                           nil upper))

-                      (if shrink-to-fit
-                          (shrink-window-if-larger-than-buffer window)))))
+                       ;; Klaus Berndl <klaus.berndl@sdm.de>: Only in
+                       ;; this situation we shrink-to-fit but we can do
+                       ;; this first after we have displayed buffer in
+                       ;; window (s.b. (set-window-buffer window buffer))
+                       (setq shrink-it shrink-to-fit))))

 
               (setq window (get-lru-window target-frame)))
 
 
               (setq window (get-lru-window target-frame)))
 

@@ -636,6 +635,12 @@ Returns the window displaying BUFFER."
 
             (set-window-buffer window buffer)
 
 
             (set-window-buffer window buffer)
 

+             ;; Now window's previous buffer has been brought to the top
+             ;; of the MRU chain and window displays buffer - now we can
+             ;; shrink-to-fit if necessary
+             (if shrink-it
+                 (shrink-window-if-larger-than-buffer window))
+

             (display-buffer-1 window)))))
     (or (equal wconfig (current-window-configuration))
        (push-window-configuration wconfig))
             (display-buffer-1 window)))))
     (or (equal wconfig (current-window-configuration))
        (push-window-configuration wconfig))

diff --git a/lwlib/ChangeLog b/lwlib/ChangeLog
index 24b7bc7..52502ed 100644 (file)
--- a/lwlib/ChangeLog
+++ b/lwlib/ChangeLog
@@ -1,3 +1,7 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/man/ChangeLog b/man/ChangeLog
index d332342..21e5cd0 100644 (file)
--- a/man/ChangeLog
+++ b/man/ChangeLog
@@ -1,3 +1,144 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+
+2004-01-27  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * lispref/lispref.texi (Top): Pluralize node name Specifier Examples.
+       * lispref/specifiers.texi: Synch to 21.5 where appropriate.
+
+2003-11-04  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * xemacs-faq.texi: Fix Tony Rossini's address.
+
+2004-01-25  Steve Youngs  <youngs@xemacs.org>
+
+       * xemacs-faq.texi (Q2.0.2): Rewrite, mentioning the correct way to
+       remove a package.
+       (Q3.8.2): big-menubar is in the edit-utils package.
+       (Q4.3.2): Add a comment about not needing TM for things like Gnus,
+       MH-E and VM.
+       (Q5.3.3): State correct location of ps-print.el.
+
+       * xemacs/packages.texi (Packages): Remove "Creating Packages" menu
+       entry.
+       (Package Terminology): Whitespace clean up.
+       (Installing Packages): Whitespace clean up and add some @code
+       formatters. 
+       Re-organise the menu so that installation via PUI is first and
+       Sumo is last.
+       (Automatically): mule-base is no longer a requirement for using
+       PUI.
+       Mention optionally requiring mailcrypt.
+       (Note): Removed.
+       (Manually): Move to below the PUI installation method.
+       (Sumo): Move to below the manual installation method.
+       (Which Packages): Add mailcrypt.
+       (Building Packages): Remove duplicated stuff that is in
+       lispref/packaging.texi, xref to it instead.
+       (Local.rules File): xref to the appropriate node in
+       lispref/packaging.texi. 
+       (Available Packages): Update to current reality.
+       (all): Removed.
+       (srckit): Removed.
+       (binkit): Removed.
+       
+       * xemacs/reading.texi (Reading Mail): Mention Gnus and MEW.
+
+       * new-users-guide/custom2.texi (Init File): big-menubar.el is in
+       the edit-utils package.
+
+       * lispref/packaging.texi (Packaging):
+       (The User View):
+       (The Library Maintainer View):
+       (Infrastructure):
+       (Control Files):
+       (Obtaining):
+       (The Package Release Engineer View):
+       (Package Terminology):
+       (Building Packages):
+       (Makefile Targets):
+       (packages): New.
+       (Local.rules File):
+       (XEMACS_PACKAGES): Removed.
+       (XEMACS_INSTALLED_PACKAGES_ROOT): New.
+       (NONMULE_PACKAGES): New.
+       (EXCLUDES): New.
+       (Creating Packages):
+       (BATCH): New.
+       (VERSION): Removed.
+       (AUTHOR_VERSION): Removed.
+       (MAINTAINER): Removed.
+       (PACKAGE): Removed.
+       (PKG_TYPE): Removed.
+       (REQUIRES): Removed.
+       (CATEGORY): Removed.
+       (ELS): Removed.
+       (ELCS): Removed.
+       (all): Removed.
+       (srckit): Removed.
+       (binkit): Removed.
+       (are): New.
+       (STANDARD_DOCS): New.
+       (ELCS_1_DEST): New.
+       (example): New.
+       (PACKAGE_SUPPRESS): New.
+       (EXPLICIT_DOCS): New.
+       (DATA_DEST): New.
+       (Documenting Packages):
+
+       Not quite a total rewrite, but a fairly thorough audit
+       nonetheless.
+
+2003-08-15  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * internals/internals.texi: Update copyright notice.
+       (GCPROing): Add missing period.
+       (Adding Global Lisp Variables): general.c -> general-slots.h.
+       (A Reader's Guide to XEmacs Coding Conventions): New node.
+
+2003-10-22  Ilya N. Golubev  <gin@mo.msk.ru>
+
+       * custom.texi (The Init File):
+       * xemacs-faq.texi (Q2.1.3):
+       (Q2.1.5):
+       * internals/internals.texi (Modules for Internationalization):
+       * lispref/display.texi (Beeping):
+       * lispref/ldap.texi (Encoder/Decoder Functions):
+       * lispref/markers.texi (The Mark):
+       (The Region):
+       * lispref/menus.texi (Menu Accelerator Functions):
+       * lispref/numbers.texi (Math Functions):
+       * lispref/packaging.texi (package-compile.el):
+       (Makefile Targets):
+       (Local.rules File):
+       * lispref/postgresql.texi (libpq Lisp Symbols and DataTypes):
+       (libpq Lisp Variables):
+       (Synchronous Interface Functions):
+       (Other libpq Functions):
+       * new-users-guide/custom2.texi (Init File):
+       (Setting Variables):
+       * new-users-guide/files.texi (File Names):
+       (Saving Files):
+       * new-users-guide/search.texi (Search and Replace):
+       * xemacs/custom.texi (X Resources):
+       Fix up erroneous uses of @var instead of @code for the names of
+       particular variables in programming languages.
+
+2003-10-20  Ilya N. Golubev  <gin@mo.msk.ru>
+
+       * lispref/tips.texi (Style Tips): Note disabling undo in temporary
+       buffers.
+
+2003-10-16  Ilya N. Golubev  <gin@mo.msk.ru>
+
+       * lispref/tips.texi (Comment Tips): Typo fix.
+
+2003-09-22  Adrian Aichner  <adrian@xemacs.org>
+
+       * lispref/backups.texi (Reverting): Fix the PRINTED-MANUAL-TITLE
+       argument for a cross reference to  "The XEmacs User's Manual".
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/man/custom.texi b/man/custom.texi
index 66acee1..a3960a8 100644 (file)
--- a/man/custom.texi
+++ b/man/custom.texi
@@ -291,7 +291,7 @@ and older XEmacs) and is @file{custom.el} in the same directory as
 @file{init.el} (in XEmacs 21.4 and later).  If you use another file, you
 must explicitly load it yourself.
 
 @file{init.el} (in XEmacs 21.4 and later).  If you use another file, you
 must explicitly load it yourself.
 

-As of XEmacs 21.4.7, when @var{custom-file} is present, it is loaded
+As of XEmacs 21.4.7, when @code{custom-file} is present, it is loaded

 @emph{after} @file{init.el}.  This is likely to change in the future,
 because (1) actions in @file{init.el} often would like to depend on
 customizations for consistent appearance and (2) Custom is quite brutal
 @emph{after} @file{init.el}.  This is likely to change in the future,
 because (1) actions in @file{init.el} often would like to depend on
 customizations for consistent appearance and (2) Custom is quite brutal

diff --git a/man/internals/internals.texi b/man/internals/internals.texi
index 548a62f..322f7ef 100644 (file)
--- a/man/internals/internals.texi
+++ b/man/internals/internals.texi
@@ -12,7 +12,7 @@
 
 Copyright @copyright{} 1992 - 1996 Ben Wing.
 Copyright @copyright{} 1996, 1997 Sun Microsystems.
 
 Copyright @copyright{} 1992 - 1996 Ben Wing.
 Copyright @copyright{} 1996, 1997 Sun Microsystems.

-Copyright @copyright{} 1994 - 1998 Free Software Foundation.
+Copyright @copyright{} 1994 - 1998, 2002, 2003 Free Software Foundation.

 Copyright @copyright{} 1994, 1995 Board of Trustees, University of Illinois.
 
 
 Copyright @copyright{} 1994, 1995 Board of Trustees, University of Illinois.
 
 

@@ -1938,6 +1938,7 @@ 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
 situations, often in code far away from where the actual breakage is.
 
 @menu

+* A Reader's Guide to XEmacs Coding Conventions::

 * General Coding Rules::
 * Writing Lisp Primitives::
 * Writing Good Comments::
 * General Coding Rules::
 * Writing Lisp Primitives::
 * Writing Good Comments::

@@ -1947,6 +1948,99 @@ situations, often in code far away from where the actual breakage is.
 * Techniques for XEmacs Developers::
 @end menu
 
 * Techniques for XEmacs Developers::
 @end menu
 

+@node A Reader's Guide to XEmacs Coding Conventions
+@section A Reader's Guide to XEmacs Coding Conventions
+@cindex coding conventions
+@cindex reader's guide
+@cindex coding rules, naming
+
+Of course the low-level implementation language of XEmacs is C, but much
+of that uses the Lisp engine to do its work.  However, because the code
+is ``inside'' of the protective containment shell around the ``reactor
+core,'' you'll see lots of complex ``plumbing'' needed to do the work
+and ``safety mechanisms,'' whose failure results in a meltdown.  This
+section provides a quick overview (or review) of the various components
+of the implementation of Lisp objects.
+
+  Two typographic conventions help to identify C objects that implement
+Lisp objects.  The first is that capitalized identifiers, especially
+beginning with the letters @samp{Q}, @samp{V}, @samp{F}, and @samp{S},
+for C variables and functions, and C macros with beginning with the
+letter @samp{X}, are used to implement Lisp.  The second is that where
+Lisp uses the hyphen @samp{-} in symbol names, the corresponding C
+identifiers use the underscore @samp{_}.  Of course, since XEmacs Lisp
+contains interfaces to many external libraries, those external names
+will follow the coding conventions their authors chose, and may overlap
+the ``XEmacs name space.''  However these cases are usually pretty
+obvious.
+
+  All Lisp objects are handled indirectly.  The @code{Lisp_Object}
+type is usually a pointer to a structure, except for a very small number
+of types with immediate representations (currently characters and
+integers).  However, these types cannot be directly operated on in C
+code, either, so they can also be considered indirect.  Types that do
+not have an immediate representation always have a C typedef
+@code{Lisp_@var{type}} for a corresponding structure.
+@c #### mention l(c)records here?
+
+  In older code, it was common practice to pass around pointers to
+@code{Lisp_@var{type}}, but this is now deprecated in favor of using
+@code{Lisp_Object} for all function arguments and return values that are
+Lisp objects.  The @code{X@var{type}} macro is used to extract the
+pointer and cast it to @code{(Lisp_@var{type} *)} for the desired type.
+
+  @strong{Convention}: macros whose names begin with @samp{X} operate on
+@code{Lisp_Object}s and do no type-checking.  Many such macros are type
+extractors, but others implement Lisp operations in C (@emph{e.g.},
+@code{XCAR} implements the Lisp @code{car} function).  These are unsafe,
+and must only be used where types of all data have already been checked.
+Such macros are only applied to @code{Lisp_Object}s.  In internal
+implementations where the pointer has already been converted, the
+structure is operated on directly using the C @code{->} member access
+operator.
+
+  The @code{@var{type}P}, @code{CHECK_@var{type}}, and
+@code{CONCHECK_@var{type}} macros are used to test types.  The first
+returns a Boolean value, and the latter signal errors.  (The
+@samp{CONCHECK} variety allows execution to be CONtinued under some
+circumstances, thus the name.)  Functions which expect to be passed user
+data invariably call @samp{CHECK} macros on arguments.
+
+  There are many types of specialized Lisp objects implemented in C, but
+the most pervasive type is the @dfn{symbol}.  Symbols are used as
+identifiers, variables, and functions.
+
+  @strong{Convention}: Global variables whose names begin with @samp{Q}
+are constants whose value is a symbol.  The name of the variable should
+be derived from the name of the symbol using the same rules as for Lisp
+primitives.  Such variables allow the C code to check whether a
+particular @code{Lisp_Object} is equal to a given symbol.  Symbols are
+Lisp objects, so these variables may be passed to Lisp primitives.  (An
+alternative to the use of @samp{Q...} variables is to call the
+@code{intern} function at initialization in the
+@code{vars_of_@var{module}} function, which is hardly less efficient.)
+
+  @strong{Convention}: Global variables whose names begin with @samp{V}
+are variables that contain Lisp objects.  The convention here is that
+all global variables of type @code{Lisp_Object} begin with @samp{V}, and
+no others do (not even integer and boolean variables that have Lisp
+equivalents). Most of the time, these variables have equivalents in
+Lisp, which are defined via the @samp{DEFVAR} family of macros, but some
+don't.  Since the variable's value is a @code{Lisp_Object}, it can be
+passed to Lisp primitives.
+
+  The implementation of Lisp primitives is more complex.
+@strong{Convention}: Global variables with names beginning with @samp{S}
+contain a structure that allows the Lisp engine to identify and call a C
+function.  In modern versions of XEmacs, these identifiers are almost
+always completely hidden in the @code{DEFUN} and @code{SUBR} macros, but
+you will encounter them if you look at very old versions of XEmacs or at
+GNU Emacs.  @strong{Convention}: Functions with names beginning with
+@samp{F} implement Lisp primitives.  Of course all their arguments and
+their return values must be Lisp_Objects.  (This is hidden in the
+@code{DEFUN} macro.)
+
+

 @node General Coding Rules
 @section General Coding Rules
 @cindex coding rules, general
 @node General Coding Rules
 @section General Coding Rules
 @cindex coding rules, general

@@ -2406,10 +2500,15 @@ XEmacs crash!].)
 @code{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
 @code{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
+will sometimes crash in obscure ways during certain operations!
+
+To avoid this problem, declare any symbols with common names (such as

 @code{text}) that are not obviously associated with this particular
 @code{text}) that are not obviously associated with this particular

-module in the module @file{general.c}.
+module in the file @file{general-slots.h}.  The ``-slots'' suffix
+indicates that this is a file that is included multiple times in
+@file{general.c}.  Redefinition of preprocessor macros allows the
+effects to be different in each context, so this is actually more
+convenient and less error-prone than doing it in your module.

 
   Global variables whose names begin with @samp{V} are variables that
 contain Lisp objects.  The convention here is that all global variables
 
   Global variables whose names begin with @samp{V} are variables that
 contain Lisp objects.  The convention here is that all global variables

@@ -4986,7 +5085,7 @@ respectively.  This is currently in beta.
 
 @file{mule-mcpath.c} provides some functions to allow for pathnames
 containing extended characters.  This code is fragmentary, obsolete, and
 
 @file{mule-mcpath.c} provides some functions to allow for pathnames
 containing extended characters.  This code is fragmentary, obsolete, and

-completely non-working.  Instead, @var{pathname-coding-system} is used
+completely non-working.  Instead, @code{pathname-coding-system} is used

 to specify conversions of names of files and directories.  The standard
 C I/O functions like @samp{open()} are wrapped so that conversion occurs
 automatically.
 to specify conversions of names of files and directories.  The standard
 C I/O functions like @samp{open()} are wrapped so that conversion occurs
 automatically.

@@ -5315,7 +5414,7 @@ different section of code.
 
 If you don't understand whether to @code{GCPRO} in a particular
 instance, ask on the mailing lists.  A general hint is that @code{prog1}
 
 If you don't understand whether to @code{GCPRO} in a particular
 instance, ask on the mailing lists.  A general hint is that @code{prog1}

-is the canonical example
+is the canonical example.

 
 @cindex garbage collection, conservative
 @cindex conservative garbage collection
 
 @cindex garbage collection, conservative
 @cindex conservative garbage collection

diff --git a/man/lispref/backups.texi b/man/lispref/backups.texi
index 7ea6cc4..cac8e56 100644 (file)
--- a/man/lispref/backups.texi
+++ b/man/lispref/backups.texi
@@ -579,7 +579,7 @@ name.
   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 @code{revert-buffer} command.  @xref{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 @code{revert-buffer} command.  @xref{Reverting, ,

-Reverting a Buffer, xemacs, The XEmacs Lisp Reference Manual}.
+Reverting a Buffer, xemacs, The XEmacs User's Manual}.

 
 @deffn Command revert-buffer &optional check-auto-save noconfirm preserve-modes
 This command replaces the buffer text with the text of the visited
 
 @deffn Command revert-buffer &optional check-auto-save noconfirm preserve-modes
 This command replaces the buffer text with the text of the visited

diff --git a/man/lispref/display.texi b/man/lispref/display.texi
index 3263dbe..e34d3ff 100644 (file)
--- a/man/lispref/display.texi
+++ b/man/lispref/display.texi
@@ -1244,7 +1244,7 @@ This function reads in an audio file and adds it to @code{sound-alist}.
 The sound file must be in the Sun/NeXT U-LAW format.  @var{sound-name}
 should be a symbol, specifying the name of the sound.  If @var{volume}
 is specified, the sound will be played at that volume; otherwise, the
 The sound file must be in the Sun/NeXT U-LAW format.  @var{sound-name}
 should be a symbol, specifying the name of the sound.  If @var{volume}
 is specified, the sound will be played at that volume; otherwise, the

-value of @var{bell-volume} will be used.
+value of @code{bell-volume} will be used.

 @end deffn
 
 @defun play-sound sound &optional volume device
 @end deffn
 
 @defun play-sound sound &optional volume device

diff --git a/man/lispref/ldap.texi b/man/lispref/ldap.texi
index 827fca0..5099e92 100644 (file)
--- a/man/lispref/ldap.texi
+++ b/man/lispref/ldap.texi
@@ -431,21 +431,21 @@ A function that decodes a LDAP boolean string representation
 @end defun
 
 @defun ldap-decode-string str
 @end defun
 
 @defun ldap-decode-string str

-Decode a string @var{str} according to @var{ldap-coding-system}.
+Decode a string @var{str} according to @code{ldap-coding-system}.

 @end defun
 
 @defun ldap-encode-string str
 @end defun
 
 @defun ldap-encode-string str

-Encode a string @var{str} according to @var{ldap-coding-system}.
+Encode a string @var{str} according to @code{ldap-coding-system}.

 @end defun
 
 @defun ldap-decode-address str
 @end defun
 
 @defun ldap-decode-address str

-Decode an address @var{str} according to @var{ldap-coding-system} and
+Decode an address @var{str} according to @code{ldap-coding-system} and

 replacing $ signs with newlines as specified by LDAP encoding rules for
 addresses.
 @end defun
 
 @defun ldap-encode-address str
 replacing $ signs with newlines as specified by LDAP encoding rules for
 addresses.
 @end defun
 
 @defun ldap-encode-address str

-Encode an address @var{str} according to @var{ldap-coding-system} and
+Encode an address @var{str} according to @code{ldap-coding-system} and

 replacing newlines with $ signs as specified by LDAP encoding rules for
 addresses.
 @end defun
 replacing newlines with $ signs as specified by LDAP encoding rules for
 addresses.
 @end defun

diff --git a/man/lispref/lispref.texi b/man/lispref/lispref.texi
index 538ac59..6cbad13 100644 (file)
--- a/man/lispref/lispref.texi
+++ b/man/lispref/lispref.texi
@@ -263,9 +263,9 @@ Packaging
 
 Package Overview
 
 
 Package Overview
 

-* The User's View::
-* The Library Maintainer's View::
-* The Package Release Engineer's View::
+* The User View::
+* The Library Maintainer View::
+* The Package Release Engineer View::

 
 The Library Maintainer's View
 
 
 The Library Maintainer's View
 

@@ -275,9 +275,8 @@ The Library Maintainer's View
 
 Creating Packages
 
 
 Creating Packages
 

-* package-compile.el::
-* package-info.in Fields::
-* Makefile Variables::
+* package-info.in::             package-info.in
+* Makefile::                    @file{Makefile}

 * Makefile Targets::
 
 Lisp Data Types
 * Makefile Targets::
 
 Lisp Data Types

@@ -947,7 +946,7 @@ Specifiers
 * Retrieving Specifications::  Querying a specifier's specifications.
 * Specifier Instancing Functions::
                                Functions to instance a specifier.
 * Retrieving Specifications::  Querying a specifier's specifications.
 * Specifier Instancing Functions::
                                Functions to instance a specifier.

-* Specifier Example::          Making all this stuff clearer.
+* Specifier Examples::         Making all this stuff clearer.

 * Creating Specifiers::                Creating specifiers for your own use.
 * Specifier Validation Functions::
                                Validating the components of a specifier.
 * Creating Specifiers::                Creating specifiers for your own use.
 * Specifier Validation Functions::
                                Validating the components of a specifier.

diff --git a/man/lispref/markers.texi b/man/lispref/markers.texi
index b22c287..18212de 100644 (file)
--- a/man/lispref/markers.texi
+++ b/man/lispref/markers.texi
@@ -508,7 +508,7 @@ However, if @var{force} is non-@code{nil}, then @code{mark} returns the
 mark position anyway---or @code{nil}, if the mark is not yet set for
 the buffer.
 
 mark position anyway---or @code{nil}, if the mark is not yet set for
 the buffer.
 

-(Remember that if @var{zmacs-regions} is @code{nil}, the mark is
+(Remember that if @code{zmacs-regions} is @code{nil}, the mark is

 always active as long as it exists, and the @var{force} argument
 will have no effect.)
 
 always active as long as it exists, and the @var{force} argument
 will have no effect.)
 

@@ -687,8 +687,8 @@ these functions, however.  A command designed to operate on a region
 should normally use @code{interactive} with the @samp{r} specification
 to find the beginning and end of the region.  This lets other Lisp
 programs specify the bounds explicitly as arguments and automatically
 should normally use @code{interactive} with the @samp{r} specification
 to find the beginning and end of the region.  This lets other Lisp
 programs specify the bounds explicitly as arguments and automatically

-respects the user's setting for @var{zmacs-regions}.  (@xref{Interactive
-Codes}.)
+respects the user's setting for @code{zmacs-regions}.
+(@xref{Interactive Codes}.)

 
 @defun region-beginning &optional buffer
 This function returns the position of the beginning of @var{buffer}'s
 
 @defun region-beginning &optional buffer
 This function returns the position of the beginning of @var{buffer}'s

@@ -730,7 +730,7 @@ region or on something else (e.g. the word or paragraph at point).
 @defvar zmacs-region-stays
 If a command sets this variable to true, the currently active region
 will remain activated when the command finishes. (Normally the region is
 @defvar zmacs-region-stays
 If a command sets this variable to true, the currently active region
 will remain activated when the command finishes. (Normally the region is

-deactivated when each command terminates.) If @var{zmacs-regions} is
+deactivated when each command terminates.) If @code{zmacs-regions} is

 false, however, this has no effect.  Under normal circumstances, you do
 not need to set this; use the interactive specification @samp{_}
 instead, if you want the region to remain active.
 false, however, this has no effect.  Under normal circumstances, you do
 not need to set this; use the interactive specification @samp{_}
 instead, if you want the region to remain active.

@@ -740,15 +740,15 @@ instead, if you want the region to remain active.
 This function activates the region in the current buffer (this is
 equivalent to activating the current buffer's mark).  This will normally
 also highlight the text in the active region and set
 This function activates the region in the current buffer (this is
 equivalent to activating the current buffer's mark).  This will normally
 also highlight the text in the active region and set

-@var{zmacs-region-stays} to @code{t}. (If @var{zmacs-regions} is false,
-however, this function has no effect.)
+@code{zmacs-region-stays} to @code{t}. (If @code{zmacs-regions} is
+false, however, this function has no effect.)

 @end defun
 
 @defun zmacs-deactivate-region
 This function deactivates the region in the current buffer (this is
 equivalent to deactivating the current buffer's mark).  This will
 normally also unhighlight the text in the active region and set
 @end defun
 
 @defun zmacs-deactivate-region
 This function deactivates the region in the current buffer (this is
 equivalent to deactivating the current buffer's mark).  This will
 normally also unhighlight the text in the active region and set

-@var{zmacs-region-stays} to @code{nil}. (If @var{zmacs-regions} is
+@code{zmacs-region-stays} to @code{nil}. (If @code{zmacs-regions} is

 false, however, this function has no effect.)
 @end defun
 
 false, however, this function has no effect.)
 @end defun
 

@@ -768,21 +768,21 @@ happens as a result of a command that activates the region, such as
 @code{set-mark-command}, @code{activate-region}, or
 @code{exchange-point-and-mark}.) Note that calling
 @file{zmacs-activate-region} will call this hook, even if the region is
 @code{set-mark-command}, @code{activate-region}, or
 @code{exchange-point-and-mark}.) Note that calling
 @file{zmacs-activate-region} will call this hook, even if the region is

-already active.  If @var{zmacs-regions} is false, however, this hook
+already active.  If @code{zmacs-regions} is false, however, this hook

 will never get called under any circumstances.
 @end defvar
 
 @defvar zmacs-deactivate-region-hook
 This normal hook is called when an active region becomes inactive.
 (Calling @file{zmacs-deactivate-region} when the region is inactive will
 will never get called under any circumstances.
 @end defvar
 
 @defvar zmacs-deactivate-region-hook
 This normal hook is called when an active region becomes inactive.
 (Calling @file{zmacs-deactivate-region} when the region is inactive will

-@emph{not} cause this hook to be called.)  If @var{zmacs-regions} is
+@emph{not} cause this hook to be called.)  If @code{zmacs-regions} is

 false, this hook will never get called.
 @end defvar
 
 @defvar zmacs-update-region-hook
 This normal hook is called when an active region is "updated" by
 @code{zmacs-update-region}.  This normally gets called at the end
 false, this hook will never get called.
 @end defvar
 
 @defvar zmacs-update-region-hook
 This normal hook is called when an active region is "updated" by
 @code{zmacs-update-region}.  This normally gets called at the end

-of each command that sets @var{zmacs-region-stays} to @code{t},
+of each command that sets @code{zmacs-region-stays} to @code{t},

 indicating that the region should remain activated.  The motion
 commands do this.
 @end defvar
 indicating that the region should remain activated.  The motion
 commands do this.
 @end defvar

diff --git a/man/lispref/menus.texi b/man/lispref/menus.texi
index 53d1ef7..4a00115 100644 (file)
--- a/man/lispref/menus.texi
+++ b/man/lispref/menus.texi
@@ -677,14 +677,14 @@ accelerator keys can be used regardless of the value of this variable.
 precedence over bindings in the current keymap(s).  @code{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
 precedence over bindings in the current keymap(s).  @code{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 @var{menu-accelerator-enabled} is @code{menu-force}.
-However, if @var{menu-accelerator-enabled} is @code{menu-fallback}, then
+keypress of Meta-t if @code{menu-accelerator-enabled} is @code{menu-force}.
+However, if @code{menu-accelerator-enabled} is @code{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 @code{nil}.
 
 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 @code{nil}.
 

-See also @var{menu-accelerator-modifiers} and @var{menu-accelerator-prefix}.
+See also @code{menu-accelerator-modifiers} and @code{menu-accelerator-prefix}.

 @end defvar
 
 @defvar menu-accelerator-map
 @end defvar
 
 @defvar menu-accelerator-map

@@ -698,12 +698,12 @@ accelerator in order for the top level menu to be activated in response to
 a keystroke.  The default value of @code{(meta)} mirrors the usage of the alt key
 as a menu accelerator in popular PC operating systems.
 
 a keystroke.  The default value of @code{(meta)} mirrors the usage of the alt key
 as a menu accelerator in popular PC operating systems.
 

-The modifier keys in @var{menu-accelerator-modifiers} must match exactly the
+The modifier keys in @code{menu-accelerator-modifiers} must match exactly the

 modifiers present in the keypress.  The only exception is that the shift
 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.
+modifier is accepted in conjunction with alphabetic keys even if it is not a
+menu accelerator modifier.

 
 

-See also @var{menu-accelerator-enabled} and @var{menu-accelerator-prefix}.
+See also @code{menu-accelerator-enabled} and @code{menu-accelerator-prefix}.

 @end defvar
 
 @defvar menu-accelerator-prefix
 @end defvar
 
 @defvar menu-accelerator-prefix

diff --git a/man/lispref/numbers.texi b/man/lispref/numbers.texi
index 6258217..afbd666 100644 (file)
--- a/man/lispref/numbers.texi
+++ b/man/lispref/numbers.texi
@@ -1028,7 +1028,7 @@ base of natural logarithms.
 
 @defun log number &optional base
 This function returns the logarithm of @var{number}, with base @var{base}.
 
 @defun log number &optional base
 This function returns the logarithm of @var{number}, with base @var{base}.

-If you don't specify @var{base}, the base @var{e} is used.  If @var{number}
+If you don't specify @var{base}, the base @code{e} is used.  If @var{number}

 is negative, the result is a NaN.
 @end defun
 
 is negative, the result is a NaN.
 @end defun
 

diff --git a/man/lispref/postgresql.texi b/man/lispref/postgresql.texi
index 3a6dbc4..5053498 100644 (file)
--- a/man/lispref/postgresql.texi
+++ b/man/lispref/postgresql.texi
@@ -104,27 +104,27 @@ backend database server during the establishment of a database
 connection and when the @code{pq-setenv} call is made.
 
 @defvar pg:host
 connection and when the @code{pq-setenv} call is made.
 
 @defvar pg:host

-Initialized from the @var{PGHOST} environment variable.  The default
+Initialized from the @code{PGHOST} environment variable.  The default

 host to connect to.
 @end defvar
 
 @defvar pg:user
 host to connect to.
 @end defvar
 
 @defvar pg:user

-Initialized from the @var{PGUSER} environment variable.  The default
+Initialized from the @code{PGUSER} environment variable.  The default

 database user name.
 @end defvar
 
 @defvar pg:options
 database user name.
 @end defvar
 
 @defvar pg:options

-Initialized from the @var{PGOPTIONS} environment variable.  Default
+Initialized from the @code{PGOPTIONS} environment variable.  Default

 additional server options.
 @end defvar
 
 @defvar pg:port
 additional server options.
 @end defvar
 
 @defvar pg:port

-Initialized from the @var{PGPORT} environment variable.  The default TCP
-port to connect to.
+Initialized from the @code{PGPORT} environment variable.  The default
+TCP port to connect to.

 @end defvar
 
 @defvar pg:tty
 @end defvar
 
 @defvar pg:tty

-Initialized from the @var{PGTTY} environment variable.  The default
+Initialized from the @code{PGTTY} environment variable.  The default

 debugging TTY.
 
 Compatibility note:  Debugging TTYs are turned off in the XEmacs Lisp
 debugging TTY.
 
 Compatibility note:  Debugging TTYs are turned off in the XEmacs Lisp

@@ -132,17 +132,17 @@ binding.
 @end defvar
 
 @defvar pg:database
 @end defvar
 
 @defvar pg:database

-Initialized from the @var{PGDATABASE} environment variable.  The default
-database to connect to.
+Initialized from the @code{PGDATABASE} environment variable.  The
+default database to connect to.

 @end defvar
 
 @defvar pg:realm
 @end defvar
 
 @defvar pg:realm

-Initialized from the @var{PGREALM} environment variable.  The default
+Initialized from the @code{PGREALM} environment variable.  The default

 Kerberos realm.
 @end defvar
 
 @defvar pg:client-encoding
 Kerberos realm.
 @end defvar
 
 @defvar pg:client-encoding

-Initialized from the @var{PGCLIENTENCODING} environment variable.  The
+Initialized from the @code{PGCLIENTENCODING} environment variable.  The

 default client encoding.
 
 Compatibility note:  This variable is not present in non-Mule XEmacsen.
 default client encoding.
 
 Compatibility note:  This variable is not present in non-Mule XEmacsen.

@@ -153,35 +153,35 @@ In the current implementation, client encoding is equivalent to the
 
 @c unused
 @defvar pg:authtype
 
 @c unused
 @defvar pg:authtype

-Initialized from the @var{PGAUTHTYPE} environment variable.  The default
-authentication scheme used.
+Initialized from the @code{PGAUTHTYPE} environment variable.  The
+default authentication scheme used.

 
 Compatibility note:  This variable is unused in versions of libpq after
 6.5.  It is not implemented at all in the XEmacs Lisp binding.
 @end defvar
 
 @defvar pg:geqo
 
 Compatibility note:  This variable is unused in versions of libpq after
 6.5.  It is not implemented at all in the XEmacs Lisp binding.
 @end defvar
 
 @defvar pg:geqo

-Initialized from the @var{PGGEQO} environment variable.  Genetic
+Initialized from the @code{PGGEQO} environment variable.  Genetic

 optimizer options.
 @end defvar
 
 @defvar pg:cost-index
 optimizer options.
 @end defvar
 
 @defvar pg:cost-index

-Initialized from the @var{PGCOSTINDEX} environment variable.  Cost index
-options.
+Initialized from the @code{PGCOSTINDEX} environment variable.  Cost
+index options.

 @end defvar
 
 @defvar pg:cost-heap
 @end defvar
 
 @defvar pg:cost-heap

-Initialized from the @var{PGCOSTHEAP} environment variable.  Cost heap
+Initialized from the @code{PGCOSTHEAP} environment variable.  Cost heap

 options.
 @end defvar
 
 @defvar pg:tz
 options.
 @end defvar
 
 @defvar pg:tz

-Initialized from the @var{PGTZ} environment variable.  Default
+Initialized from the @code{PGTZ} environment variable.  Default

 timezone.
 @end defvar
 
 @defvar pg:date-style
 timezone.
 @end defvar
 
 @defvar pg:date-style

-Initialized from the @var{PGDATESTYLE} environment variable.  Default
+Initialized from the @code{PGDATESTYLE} environment variable.  Default

 date style in returned date objects.
 @end defvar
 
 date style in returned date objects.
 @end defvar
 

@@ -338,7 +338,7 @@ Copy In data transfer is in progress.
 An unexpected response was received from the backend.
 @item pgres::nonfatal-error
 Undocumented.  This value is returned when the libpq function
 An unexpected response was received from the backend.
 @item pgres::nonfatal-error
 Undocumented.  This value is returned when the libpq function

-@code{PQresultStatus} is called with a @var{NULL} pointer.
+@code{PQresultStatus} is called with a @code{NULL} pointer.

 @item pgres::fatal-error
 Undocumented.  An error has occurred in processing the query and the
 operation was not completed.
 @item pgres::fatal-error
 Undocumented.  An error has occurred in processing the query and the
 operation was not completed.

@@ -510,7 +510,7 @@ Return the length of a specific value.
 @end defun
 
 @defun pq-get-is-null result tup-num field-num
 @end defun
 
 @defun pq-get-is-null result tup-num field-num

-Return t if the specific value is the SQL @var{NULL}.
+Return t if the specific value is the SQL @code{NULL}.

 @var{result} is a PGresult object.
 @var{tup-num} selects which tuple to fetch from.
 @var{field-num} selects which field to fetch from.
 @var{result} is a PGresult object.
 @var{tup-num} selects which tuple to fetch from.
 @var{field-num} selects which field to fetch from.

@@ -648,24 +648,24 @@ example idiom is:
 The following options are available in the options string:
 @table @code
 @item authtype
 The following options are available in the options string:
 @table @code
 @item authtype

-Authentication type.  Same as @var{PGAUTHTYPE}.  This is no longer used.
+Authentication type.  Same as @code{PGAUTHTYPE}.  This is no longer used.

 @item user
 @item user

-Database user name.  Same as @var{PGUSER}.
+Database user name.  Same as @code{PGUSER}.

 @item password
 Database password.
 @item dbname
 @item password
 Database password.
 @item dbname

-Database name.  Same as @var{PGDATABASE}
+Database name.  Same as @code{PGDATABASE}

 @item host
 @item host

-Symbolic hostname.  Same as @var{PGHOST}.
+Symbolic hostname.  Same as @code{PGHOST}.

 @item hostaddr
 Host address as four octets (eg. like 192.168.1.1).
 @item port
 @item hostaddr
 Host address as four octets (eg. like 192.168.1.1).
 @item port

-TCP port to connect to.  Same as @var{PGPORT}.
+TCP port to connect to.  Same as @code{PGPORT}.

 @item tty
 @item tty

-Debugging TTY.  Same as @var{PGTTY}.  This value is suppressed in the
+Debugging TTY.  Same as @code{PGTTY}.  This value is suppressed in the

 XEmacs Lisp API.
 @item options
 XEmacs Lisp API.
 @item options

-Extra backend database options.  Same as @var{PGOPTIONS}.
+Extra backend database options.  Same as @code{PGOPTIONS}.

 @end table
 A database connection object is returned regardless of whether a
 connection was established or not.
 @end table
 A database connection object is returned regardless of whether a
 connection was established or not.

@@ -897,7 +897,8 @@ does not exist in a non-Mule XEmacs.
 @end defun
 
 @defun pq-env-2-encoding
 @end defun
 
 @defun pq-env-2-encoding

-Return the integer code representing the coding system in @var{PGCLIENTENCODING}.
+Return the integer code representing the coding system in
+@code{PGCLIENTENCODING}.

 
 @example
 (pq-env-2-encoding)
 
 @example
 (pq-env-2-encoding)

diff --git a/man/lispref/specifiers.texi b/man/lispref/specifiers.texi
index adb36ff..dfdc88a 100644 (file)
--- a/man/lispref/specifiers.texi
+++ b/man/lispref/specifiers.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c Copyright (C) 1995, 1996 Ben Wing.
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c Copyright (C) 1995, 1996 Ben Wing.

+@c Copyright (C) 2002, 2004 Free Software Foundation, Inc.

 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/specifiers.info
 @node Specifiers, Faces and Window-System Objects, Extents, top
 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/specifiers.info
 @node Specifiers, Faces and Window-System Objects, Extents, top

@@ -8,14 +9,13 @@
 @cindex specifier
 
 A specifier is an object used to keep track of a property whose value
 @cindex specifier
 
 A specifier is an object used to keep track of a property whose value

-may vary depending on the particular situation (e.g. particular buffer
-displayed in a particular window) that it is used in.  The value of many
-built-in properties, such as the font, foreground, background, and such
-properties of a face and variables such as
-@code{modeline-shadow-thickness} and @code{top-toolbar-height}, is
-actually a specifier object.  The specifier object, in turn, is
-``instanced'' in a particular situation to yield the real value
-of the property in that situation.
+should vary according to @emph{display context}, a window, a frame, or
+device.  The value of many built-in properties, such as the font,
+foreground, background, and such properties of a face and variables
+such as @code{modeline-shadow-thickness} and
+@code{top-toolbar-height}, is actually a specifier object.  The
+specifier object, in turn, is ``instanced'' in a particular situation
+to yield the real value of the property in the current context.

 
 @defun specifierp object
 This function returns non-@code{nil} if @var{object} is a specifier.
 
 @defun specifierp object
 This function returns non-@code{nil} if @var{object} is a specifier.

@@ -26,6 +26,7 @@ This function returns non-@code{nil} if @var{object} is a specifier.
                                 display and other properties to vary
                                 (under user control) in a wide variety
                                 of contexts.
                                 display and other properties to vary
                                 (under user control) in a wide variety
                                 of contexts.

+* Simple Specifier Usage::      Getting started with specifiers.

 * Specifiers In-Depth::         Gory details about specifier innards.
 * Specifier Instancing::        Instancing means obtaining the ``value'' of
                                 a specifier in a particular context.
 * Specifiers In-Depth::         Gory details about specifier innards.
 * Specifier Instancing::        Instancing means obtaining the ``value'' of
                                 a specifier in a particular context.

@@ -37,7 +38,7 @@ This function returns non-@code{nil} if @var{object} is a specifier.
 * Specifier Tag Functions::     Working with specifier tags.
 * Specifier Instancing Functions::
                                 Functions to instance a specifier.
 * Specifier Tag Functions::     Working with specifier tags.
 * Specifier Instancing Functions::
                                 Functions to instance a specifier.

-* Specifier Example::           Making all this stuff clearer.
+* Specifier Examples::          Making all this stuff clearer.

 * Creating Specifiers::         Creating specifiers for your own use.
 * Specifier Validation Functions::
                                 Validating the components of a specifier.
 * Creating Specifiers::         Creating specifiers for your own use.
 * Specifier Validation Functions::
                                 Validating the components of a specifier.

@@ -48,14 +49,16 @@ This function returns non-@code{nil} if @var{object} is a specifier.
 @node Introduction to Specifiers
 @section Introduction to Specifiers
 
 @node Introduction to Specifiers
 @section Introduction to Specifiers
 

-Sometimes you may want the value of a property to vary depending on
-the context the property is used in.  A simple example of this in XEmacs
-is buffer-local variables.  For example, the variable
+Perhaps the most useful way to explain specifiers is via an analogy.
+Emacs Lisp programmers are used to @emph{buffer-local variables}
+@ref{Buffer-Local Variables}. For example, the variable

 @code{modeline-format}, which controls the format of the modeline, can
 have different values depending on the particular buffer being edited.
 The variable has a default value which most modes will use, but a
 @code{modeline-format}, which controls the format of the modeline, can
 have different values depending on the particular buffer being edited.
 The variable has a default value which most modes will use, but a

-specialized package such as Calendar might change the variable so
-as to tailor the modeline to its own purposes.
+specialized package such as Calendar might change the variable so as to
+tailor the modeline to its own purposes. Other variables are perhaps
+best thought of as ``mode local,'' such as font-lock keywords, but they
+are implemented as buffer locals.

 
 Other properties (such as those that can be changed by the
 @code{modify-frame-parameters} function, for example the color of the
 
 Other properties (such as those that can be changed by the
 @code{modify-frame-parameters} function, for example the color of the

@@ -70,11 +73,41 @@ displayed on a particular frame, another value in all other buffers
 displayed in all other frames on any mono (two-color, e.g. black and
 white only) displays, and a default value in all other circumstances.
 
 displayed in all other frames on any mono (two-color, e.g. black and
 white only) displays, and a default value in all other circumstances.
 

-A @dfn{specifier} is a generalization of this, allowing a great deal
-of flexibility in controlling exactly what value a property has in which
-circumstances.  It is most commonly used for display properties, such as
-an image or the foreground color of a face.  As a simple example, you can
-specify that the foreground of the default face be
+Specifiers generalize both buffer- and frame-local properties.
+Specifiers vary according to the @emph{display} context.  Font-lock
+keywords in a buffer will be the same no matter which window the
+buffer is displayed in, but windows on TTY devices will simply not be
+capable of the flexibility that windows on modern GUI devices are.
+Specifiers provide a way for the programmer to @emph{declare} that an
+emphasized text should be italic on GUI devices and inverse video on
+TTYs.  They also provide a way for the programmer to declare
+fallbacks, so that a color specified as ``chartreuse'' where possible
+can fall back to ``yellow'' on devices where only ANSI (4-bit) color
+is available.  The complex calculations and device querying are
+transparent to both user and programmer.  You ask for what you want;
+it's up to XEmacs to provide it, or a reasonable approximation.
+
+We call such a declaration a @dfn{specification}.  A @dfn{specification}
+applies in a particular @dfn{locale}, which is a window, buffer, frame,
+device, or the global locale.  The value part of the specification is
+called an @dfn{instantiator}.  The process of determining the value in a
+particular context, or @dfn{domain}, is called @dfn{instantiation} or
+@dfn{instancing}.  A domain is a window, frame, or device.
+
+The difference between @dfn{locale} and @dfn{domain} is somewhat subtle.
+You may think of a locale as a class of domains, which may span
+different devices.  Since the specification is abstract (a Lisp form),
+you can state it without reference to a device.  On the other hand, when
+you instantiate a specification, you must know the type of the device.
+It is useless to specify that ``blue means emphasis'' on a monochrome
+device.  Thus instantiation requires specification of the device on
+which it will be rendered.
+
+Thus a @dfn{specifier} allows a great deal of flexibility in
+controlling exactly what value a property has in which circumstances.
+Specifiers are most commonly used for display properties, such as an image or
+the foreground color of a face.  As a simple example, you can specify
+that the foreground of the default face be

 
 @itemize @bullet
 @item
 
 @itemize @bullet
 @item

@@ -98,6 +131,150 @@ red for all other buffers displayed on a color device
 white for all other buffers
 @end itemize
 
 white for all other buffers
 @end itemize
 

+@node Simple Specifier Usage
+@section Simple Specifier Usage
+@cindex specifier examples
+@cindex examples, specifier
+@cindex adding a button to a toolbar
+@cindex toolbar button, adding
+
+A useful specifier application is adding a button to a toolbar.  XEmacs
+provides several toolbars, one along each edge of the frame.  Normally
+only one is used at a time, the default.  The default toolbar is
+actually a specifier object which is the value of
+@code{default-toolbar}.  @xref{Toolbar Intro}.
+
+The specification of a toolbar is simple:  it is a list of buttons.
+Each button is a vector with four elements:  an icon, a command, the
+enabled flag, and a help string.  Let's retrieve the instance of the
+toolbar you see in the selected frame.
+
+@example
+(specifier-instance default-toolbar)
+@end example
+
+The value returned is, as promised, a list of vectors.  Now let's build
+up a button, and add it to the toolbar.  Our button will invoke the last
+defined keyboard macro.  This is an alternative to
+@code{name-last-kbd-macro} for creating a persistent macro, rather than
+an alias for @kbd{C-x e}.
+
+A toolbar button icon can be quite sophisticated, with different images
+for button up, button down, and disabled states, and a similar set with
+captions.  We'll use a very simple icon, but we have to jump through a
+few non-obvious hoops designed to support the sophisticated applications.
+The rest of the button descriptor is straightforward.
+
+@example
+(setq toolbar-my-kbd-macro-button
+  `[ (list (make-glyph "MyKbdMac"))
+     (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
+     t
+     "Execute a previously defined keyboard macro." ])
+
+(set-specifier default-toolbar
+               (cons toolbar-my-kbd-macro-button
+                     (specifier-specs default-toolbar 'global))
+               'global)
+@end example
+
+To remove the button, just substitute the function @code{delete} for the
+@code{cons} above.
+
+What is the difference between @code{specifier-instance}, which we used
+in the example of retrieving the toolbar descriptor, and
+@code{specifier-specs}, which was used in the toolbar manipulating code?
+@code{specifier-specs} retrieves a copy of the instantiator, which is
+abstract and does not depend on context.  @code{specifier-instance}, on
+the other hand, actually instantiates the specification, and returns the
+result for the given context.  Another way to express this is:
+@code{specifier-specs} takes a @emph{locale} as an argument, while
+@code{specifier-instance} takes a @emph{domain}.  The reason for
+providing @code{specifier-instance} is that sometimes you wish to see
+the object that XEmacs will actually use.  @code{specifier-specs}, on
+the other hand, shows you what the programmer (or user) requested.  When
+a program manipulates specifications, clearly it's the latter that is
+desirable.
+
+In the case of the toolbar descriptor, it turns out that these are the
+same:  the instancing process is trivial.  However, many specifications
+have non-trivial instancing.  Compare the results of the following forms
+on my system.  (The @samp{(cdr (first ...))} form is due to my use of
+Mule.  On non-Mule XEmacsen, just use @code{specifier-specs}.)
+
+@example
+(cdr (first (specifier-specs (face-font 'default) 'global)))
+=> "-*--14-*jisx0208*-0"
+
+(specifier-instance (face-font 'default))
+#<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
+@end example
+
+In this case, @code{specifier-instance} returns an opaque object;
+programs can't work on it, they can only pass it around.  Worse, in some
+environments the instantiation will fail, resulting in a different value
+(when another instantiation succeeds), or worse yet, an error, if all
+attempts to instance the specifier fail.  @code{specifier-instance} is
+context-dependent, even for the exact same specification.
+@code{specifier-specs} is deterministic, and only depends on the
+specifications.
+
+Note that in the toolbar-changing code we operate in the global locale.
+This means that narrower locales, if they have specifications, will
+shadow our changes.  (Specifier instancing does not merge
+specifications.  It selects the "highest-priority successful
+specification" and instances that.)
+
+In fact, in our example, it seems pretty likely that different buffers
+@emph{should} have different buttons.  (The icon can be the same, but
+the keyboard macro you create in a Dired buffer is highly unlikely to be
+useful in a LaTeX buffer!)  Here's one way to implement this:
+
+@example
+(setq toolbar-my-kbd-macro-button
+  `[ (list (make-glyph "MyKbdMac"))
+     (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
+     t
+     "Execute a previously defined keyboard macro." ])
+
+(set-specifier default-toolbar
+               (cons toolbar-my-kbd-macro-button
+                     (cond ((specifier-specs default-toolbar
+                                             (current-buffer)))
+                           ((specifier-specs default-toolbar
+                                             'global)))
+               (current-buffer))
+@end example
+
+Finally, a cautionary note: the use of @code{specifier-specs} in the
+code above is for expository purposes.  Don't use it in production code.
+In fact, the @code{set-specifier} form above is likely to fail
+occasionally, because you can add many specifications for the same
+locale.
+
+In these cases, @code{specifier-specs} will return a list.  A further
+refinement is that a specification may be associated with a set of
+@dfn{specifier tags}.  If the list of specifier tags is non-nil, then
+@code{specifier-specs} will return a cons of the tag set and the
+instantiator.  Evidently @code{specifier-specs} is a bit unreliable.
+(For toolbars, the code above should work 99% of the time, because
+toolbars are rarely changed.  Since instantiation is trivial, multiple
+specs are not useful---the first one always succeeds.)
+
+In fact, @code{specifier-specs} is intended to be used to display specs
+to humans with a minimum of clutter. The robust way to access
+specifications is via @code{specifier-spec-list}. @xref{Adding
+Specifications}, for the definition of @dfn{spec-list}. @xref{Retrieving
+Specifications}, for documentation of @code{specifier-specs} and
+@code{specifier-spec-list}. To get the desired effect, replace the form
+@code{(specifier-spec default-toolbar 'global)} with
+
+@example
+(cdr (second (first (specifier-spec-list default-toolbar 'global))))
+@end example
+
+(It should be obvious why the example uses the lazy unreliable method!)
+

 @node Specifiers In-Depth
 @section In-Depth Overview of a Specifier
 @cindex specification (in a specifier)
 @node Specifiers In-Depth
 @section In-Depth Overview of a Specifier
 @cindex specification (in a specifier)

@@ -121,12 +298,36 @@ white for all other buffers
 @cindex specifier, tag
 @cindex specifier, tag set
 
 @cindex specifier, tag
 @cindex specifier, tag set
 

-A specifier object encapsulates a set of @dfn{specifications}, each of
-which says what its value should be if a particular condition applies.
+Having variables vary according the editing context is very useful, and
+the buffer is the natural ``atomic'' unit of editing context.  In a GUI
+environment, it can be similarly useful to have variables whose values
+vary according to display context.  The atomic unit of display context
+is the Emacs window.  Buffers are cleanly grouped by modes, but windows
+are not so easily pigeonholed.  On the one hand, a window displays a
+buffer, and thus one possible hierarchy is window, buffer, mode.  On the
+other, a window is a component of a frame.  This generates the window,
+frame, device hierarchy.  Finally, there are objects such as toolbars
+whose properties are described by specifiers.  These do not fit
+naturally into either hierarchy.  This problem is as yet not cleanly
+solved.
+
+Another potential source of conceptual confusion is the instantiation
+process.  Instantiating a buffer-local variable is simple: at any given
+point in time there is a current buffer, and its local values are used
+and set whenever the variable is accessed, unless the programmer goes to
+some special effort (uses @code{default-value} and @code{set-default}.
+However, a specifier object encapsulates a set of @dfn{specifications},
+each of which says what its value should be if a particular condition
+applies.  Several such conditions might apply simultaneously in a given
+window.
+

 For example, one specification might be ``The value should be
 darkseagreen2 on X devices'' another might be ``The value should be blue
 For example, one specification might be ``The value should be
 darkseagreen2 on X devices'' another might be ``The value should be blue

-in the *Help* buffer''.  In specifier terminology, these conditions are
-called @dfn{locales} and the values are called @dfn{instantiators}.
+in the *Help* buffer''.  So what do we do for "the *Help* buffer on an X
+device"?  The answer is simple: give each type of locale a priority and
+check them in priority order, returning the first instantiator that
+successfully instantiates a value.
+

 Given a specifier, a logical question is ``What is its value in a
 particular situation?'' This involves looking through the specifications
 to see which ones apply to this particular situation, and perhaps
 Given a specifier, a logical question is ``What is its value in a
 particular situation?'' This involves looking through the specifications
 to see which ones apply to this particular situation, and perhaps

@@ -140,6 +341,13 @@ of the default face and @dfn{instances} it in the domain given by that
 window; in other words, it asks the specifier, ``What is your value in
 this window?''.
 
 window; in other words, it asks the specifier, ``What is your value in
 this window?''.
 

+Note that the redisplay example is in a sense canonical.  That is,
+specifiers are designed to present a uniform and @emph{efficient} API
+to redisplay.  It is the efficiency constraint that motivates the
+introduction of specifier tags, and many restrictions on access (for
+example, a buffer is not a domain, and you cannot instantiate a
+specifier over a buffer).
+

 More specifically, a specifier contains a set of @dfn{specifications},
 each of which associates a @dfn{locale} (a window object, a buffer
 object, a frame object, a device object, or the symbol @code{global})
 More specifically, a specifier contains a set of @dfn{specifications},
 each of which associates a @dfn{locale} (a window object, a buffer
 object, a frame object, a device object, or the symbol @code{global})

@@ -160,8 +368,9 @@ same specifier and not interfere with each other.  Each tag can have a
 device. (If a tag does not have a predicate, it matches all devices.)
 All tags in a tag set must match a device for the associated inst-pair
 to be instantiable over that device.  (A null tag set is perfectly
 device. (If a tag does not have a predicate, it matches all devices.)
 All tags in a tag set must match a device for the associated inst-pair
 to be instantiable over that device.  (A null tag set is perfectly

-valid.)
+valid, and trivially matches all devices.)

 
 

+@c #### don't we have more device types now, gtk, ms-windows, mac-carbon?

 The valid device types (normally @code{x}, @code{tty}, and
 @code{stream}) and device classes (normally @code{color},
 @code{grayscale}, and @code{mono}) can always be used as tags, and match
 The valid device types (normally @code{x}, @code{tty}, and
 @code{stream}) and device classes (normally @code{color},
 @code{grayscale}, and @code{mono}) can always be used as tags, and match

@@ -474,8 +683,13 @@ specifications.
 the existing ones, and has the same semantics as for
 @code{add-spec-to-specifier}.
 
 the existing ones, and has the same semantics as for
 @code{add-spec-to-specifier}.
 

-In many circumstances, the higher-level function @code{set-specifier} is
-more convenient and should be used instead.
+The higher-level function @code{set-specifier} is often
+more convenient because it allows abbreviations of spec-lists to be used
+instead of the heavily nested canonical syntax.  However, one should
+take great care in using them with specifiers types which can have lists
+as instantiators, such as toolbar specifiers and generic specifiers.  In
+those cases it's probably best to use @code{add-spec-to-specifier} or
+@code{add-spec-list-to-specifier}.

 @end defun
 
 @defspec let-specifier specifier-list &rest body
 @end defun
 
 @defspec let-specifier specifier-list &rest body

@@ -525,7 +739,7 @@ specification), a list of tagged and/or untagged instantiators (added as
 a global specification), a cons of a locale and instantiator or locale
 and instantiator list, a list of such conses, or nearly any other
 reasonable form.  More specifically, @var{value} can be anything
 a global specification), a cons of a locale and instantiator or locale
 and instantiator list, a list of such conses, or nearly any other
 reasonable form.  More specifically, @var{value} can be anything

-accepted by @code{canonicalize-spec-list}.
+accepted by @code{canonicalize-spec-list} (described below).

 
 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
 @code{add-spec-to-specifier}.
 
 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
 @code{add-spec-to-specifier}.

@@ -538,7 +752,10 @@ specs at all in it but @code{nil} is a valid instantiator (in that case,
 adding a global instantiator and its value is @code{nil}''), or in
 strange cases where there is an ambiguity between a spec-list and an
 inst-list, etc. (The built-in specifier types are designed in such a way
 adding a global instantiator and its value is @code{nil}''), or in
 strange cases where there is an ambiguity between a spec-list and an
 inst-list, etc. (The built-in specifier types are designed in such a way

-as to avoid any such ambiguities.)
+as to avoid any such ambiguities.)  For robust code,
+@code{set-specifier} should probably be avoided for specifier types
+which accept lists as instantiators (currently toolbar specifiers and
+generic specifiers).

 
 If you want to work with spec-lists, you should probably not use these
 functions, but should use the lower-level functions
 
 If you want to work with spec-lists, you should probably not use these
 functions, but should use the lower-level functions

@@ -601,6 +818,10 @@ specifications).
 @var{specifier-type} specifies the type of specifier that this
 @var{spec-list} will be used for.
 
 @var{specifier-type} specifies the type of specifier that this
 @var{spec-list} will be used for.
 

+If @var{noerror} is @code{nil}, signal an error if the spec-list is
+invalid; otherwise return @code{t} for an invalid spec-list.  (Note that
+this cannot be confused with a canonical spec-list.)
+

 Canonicalizing means converting to the full form for a spec-list, i.e.
 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
 This function accepts a possibly abbreviated specification or a list of
 Canonicalizing means converting to the full form for a spec-list, i.e.
 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
 This function accepts a possibly abbreviated specification or a list of

@@ -612,8 +833,59 @@ This function tries extremely hard to resolve any ambiguities,
 and the built-in specifier types (font, image, toolbar, etc.) are
 designed so that there won't be any ambiguities.
 
 and the built-in specifier types (font, image, toolbar, etc.) are
 designed so that there won't be any ambiguities.
 

-If @var{noerror} is @code{nil}, signal an error if the spec-list is
-invalid; otherwise return @code{t}.
+The canonicalization algorithm is as follows:
+
+@enumerate
+@item
+Attempt to parse @var{spec-list} as a single, possibly abbreviated,
+specification.
+@item
+If that fails, attempt to parse @var{spec-list} as a list of (abbreviated)
+specifications.
+@item
+If that fails, @var{spec-list} is invalid.
+@end enumerate
+
+A possibly abbreviated specification @var{spec} is parsed by
+
+@enumerate
+@item
+Attempt to parse @var{spec} as a possibly abbreviated inst-list.
+@item
+If that fails, attempt to parse @var{spec} as a cons of a locale and an
+(abbreviated) inst-list.
+@item
+If that fails, @var{spec} is invalid.
+@end enumerate
+
+A possibly abbreviated inst-list @var{inst-list} is parsed by
+
+@enumerate
+@item
+Attempt to parse @var{inst-list} as a possibly abbreviated inst-pair.
+@item
+If that fails, attempt to parse @var{inst-list} as a list of (abbreviated)
+inst-pairs.
+@item
+If that fails, @var{inst-list} is invalid.
+@end enumerate
+
+A possibly abbreviated inst-pair @var{inst-pair} is parsed by
+
+@enumerate
+@item
+Check if @var{inst-pair} is @code{valid-instantiator-p}.
+@item
+If not, check if @var{inst-pair} is a cons of something that is a tag, ie,
+@code{valid-specifier-tag-p}, and something that is @code{valid-instantiator-p}.
+@item
+If not, check if @var{inst-pair} is a cons of a list of tags and something that
+is @code{valid-instantiator-p}.
+@item
+Otherwise, @var{inst-pair} is invalid.
+@end enumerate
+
+In summary, this function generally prefers more abbreviated forms.

 @end defun
 
 @node Retrieving Specifications
 @end defun
 
 @node Retrieving Specifications

@@ -775,7 +1047,7 @@ This function returns the predicate for the given specifier tag.
 @section Functions for Instancing a Specifier
 
 @defun specifier-instance specifier &optional domain default no-fallback
 @section Functions for Instancing a Specifier
 
 @defun specifier-instance specifier &optional domain default no-fallback

-This function instantiates @var{specifier} (return its value) in
+This function instantiates @var{specifier} (returns its value) in

 @var{domain}.  If no instance can be generated for this domain, return
 @var{default}.
 
 @var{domain}.  If no instance can be generated for this domain, return
 @var{default}.
 

@@ -829,6 +1101,34 @@ returned value will be a font-instance object.  For images, the returned
 value will be a string, pixmap, or subwindow.
 @end defun
 
 value will be a string, pixmap, or subwindow.
 @end defun
 

+@defun specifier-matching-instance specifier matchspec &optional domain default no-fallback
+This function returns an instance for @var{specifier} in @var{domain}
+that matches @var{matchspec}.  If no instance can be generated for
+@var{domain}, return @var{default}.
+
+This function is identical to @code{specifier-instance} except that a
+specification will only be considered if it matches @var{matchspec}.
+The definition of ``match,'' and allowed values for @var{matchspec}, are
+dependent on the particular type of specifier.  Here are some examples:
+
+@itemize
+@item
+For chartable (e.g. display table) specifiers, @var{matchspec} should be a
+character, and the specification (a chartable) must give a value for
+that character in order to be considered.  This allows you to specify,
+@emph{e.g.}, a buffer-local display table that only gives values for particular
+characters.  All other characters are handled as if the buffer-local
+display table is not there. (Chartable specifiers are not yet
+implemented.)
+@item
+For font specifiers, @var{matchspec} should be a charset,
+and the specification (a font string) must have
+a registry that matches the charset's registry.  (This only makes sense
+with Mule support.)  This makes it easy to choose a font that can
+display a particular character.  (This is what redisplay does, in fact.)
+@end itemize
+@end defun
+

 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
 This function attempts to convert a particular inst-list into an
 instance.  This attempts to instantiate @var{inst-list} in the given
 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
 This function attempts to convert a particular inst-list into an
 instance.  This attempts to instantiate @var{inst-list} in the given

@@ -838,8 +1138,8 @@ In most circumstances, you should not use this function; use
 @code{specifier-instance} instead.
 @end defun
 
 @code{specifier-instance} instead.
 @end defun
 

-@node Specifier Example
-@section Example of Specifier Usage
+@node Specifier Examples
+@section Examples of Specifier Usage

 
 Now let us present an example to clarify the theoretical discussions we
 have been through.  In this example, we will use the general specifier
 
 Now let us present an example to clarify the theoretical discussions we
 have been through.  In this example, we will use the general specifier

@@ -912,6 +1212,143 @@ our window is on recognizes the color @samp{moccasin}, and so the
 instantiation method succeeds and returns a color instance.
 @end enumerate
 
 instantiation method succeeds and returns a color instance.
 @end enumerate
 

+Here's another example, which implements something like GNU Emacs's
+``frame-local'' variables.
+
+@example
+;; Implementation
+
+;; There are probably better ways to write this macro
+;; Heaven help you if VAR is a buffer-local; you will become very
+;; confused.  Probably should error on that.
+(defmacro define-frame-local-variable (var)
+  "Make the unbound symbol VAR become a frame-local variable."
+  (let ((val (if (boundp var) (symbol-value var) nil)))
+    `(progn
+      (setq ,var (make-specifier 'generic))
+      (add-spec-to-specifier ,var ',val 'global))))
+
+;; I'm not real happy about this terminology, how can `setq' be a defun?
+;; But `frame-set' would have people writing "(frame-set 'foo value)".
+(defun frame-setq (var value &optional frame)
+  "Set the local value of VAR to VALUE in FRAME.
+
+FRAME defaults to the selected frame."
+  (and frame (not (framep frame))
+       (error 'invalid-argument "FRAME must be a frame", frame))
+  (add-spec-to-specifier var value (or frame (selected-frame))))
+
+(defun frame-value (var &optional frame)
+  "Get the local value of VAR in FRAME.
+
+FRAME defaults to the selected frame."
+  (and frame (not (framep frame))
+       (error 'invalid-argument "FRAME must be a frame", frame))
+  ;; this is not just a map from frames to values; it also falls back
+  ;; to the global value
+  (specifier-instance var (or frame (selected-frame))))
+
+;; for completeness
+(defun frame-set-default (var value)
+  "Set the default value of frame-local variable VAR to VALUE."
+  (add-spec-to-specifier var value 'global))
+
+(defun frame-get-default (var)
+  "Get the default value of frame-local variable VAR."
+  (car (specifier-specs var 'global)))
+@end example
+
+Now you can execute the above definitions (eg, with @code{eval-last-sexp})
+and switch to @file{*scratch*} to play.  Things will work differently if
+you already have a variable named @code{foo}.
+
+@example
+;; Usage
+
+foo
+@error{} Symbol's value as variable is void: foo
+
+(define-frame-local-variable foo)
+@result{} nil
+
+;; the value of foo is a specifier, which is an opaque object;
+;; you must use accessor functions to get values
+
+foo
+@result{} #<generic-specifier global=(nil) 0x4f5cb>
+
+;; since no frame-local value is set, the global value (which is the
+;; constant `nil') is returned
+(frame-value foo)
+@result{} nil
+
+;; get the default explicitly
+(frame-get-default foo)
+@result{} nil
+
+;; get the whole specification list
+(specifier-specs foo 'global)
+@result{} (nil)
+
+;; give foo a frame-local value
+
+(frame-setq foo 'bar)
+@result{} nil
+
+;; access foo in several ways
+
+;; Note that the print function for this kind of specifier only
+;; gives you the global setting.  To get the full list of specs for
+;; debugging or study purposes, you must use specifier-specs or
+;; specifier-spec-list.
+foo
+@result{} #<generic-specifier global=(nil) 0x4f5cb>
+
+;; get the whole specification list
+(specifier-specs foo)
+@result{} ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))
+
+;; get the frame-local value
+(frame-value foo)
+@result{} bar
+
+;; get the default explicitly
+(frame-get-default foo)
+@result{} nil
+
+;; Switch to another frame and evaluate:
+;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
+@result{} baz
+
+;; Switch back.
+;; C-x 5 o
+(specifier-specs foo)
+@result{} ((#<x-frame "emacs" 0x28ec> (nil . baz))
+    (#<x-frame "Message" 0x1bd66> (nil . bar))
+    (global (nil)))
+
+(frame-value foo)
+@result{} bar
+
+(frame-get-default foo)
+@result{} nil
+@end example
+
+Note that since specifiers generalize both frame-local and buffer-local
+variables in a sensible way, XEmacs is not likely to put a high priority
+on implementing frame-local variables.
+@c Thanks to Jerry James for the following explanation.  He is not
+@c responsible for its use here, Stephen Turnbull is.
+In fact, some developers think that frame-local variables are evil for
+the same reason that buffer-local variables are evil: the declaration is
+both global and invisible.  That is, you cannot tell whether a variable
+is ``normal,'' buffer-local, or frame-local just by looking at it.  So
+if you have namespace management problems, and some other Lisp package
+happens to use a variable name that you already declared frame- or
+buffer-local, weird stuff happens, and it is extremely hard to track
+down.
+
+

 @node Creating Specifiers
 @section Creating New Specifier Objects
 
 @node Creating Specifiers
 @section Creating New Specifier Objects
 

@@ -943,16 +1380,20 @@ functions @code{make-generic-specifier}, @code{make-integer-specifier},
 @end defun
 
 @defun make-specifier-and-init type spec-list &optional dont-canonicalize
 @end defun
 
 @defun make-specifier-and-init type spec-list &optional dont-canonicalize

-This function creates and initialize a new specifier.
+This function creates and initializes a new specifier.

 
 

-This is a front-end onto @code{make-specifier} that allows you to create
+This is a convenience API combining @code{make-specifier} and
+@code{set-specifier} that allows you to create

 a specifier and add specs to it at the same time.  @var{type} specifies
 a specifier and add specs to it at the same time.  @var{type} specifies

-the specifier type.  @var{spec-list} supplies the specification(s) to be
-added to the specifier. Normally, almost any reasonable abbreviation of
-the full spec-list form is accepted, and is converted to the full form;
-however, if optional argument @var{dont-canonicalize} is non-@code{nil},
-this conversion is not performed, and the @var{spec-list} must already
-be in full form.  See @code{canonicalize-spec-list}.
+the specifier type.  Allowed types are as for @code{make-specifier}.
+
+@var{spec-list} supplies the specification(s) to be
+added to the specifier.  Any abbreviation of
+the full spec-list form accepted by @code{canonicalize-spec-list} may
+be used.
+However, if the optional argument @var{dont-canonicalize} is non-@code{nil},
+canonicalization is not performed, and the @var{spec-list} must already
+be in full form.

 @end defun
 
 @defun make-integer-specifier spec-list
 @end defun
 
 @defun make-integer-specifier spec-list

@@ -1137,12 +1578,15 @@ instantiator's tag set for the instantiator to be removed.
 This function applies @var{func} to the specification(s) for
 @var{locale} in @var{specifier}.
 
 This function applies @var{func} to the specification(s) for
 @var{locale} in @var{specifier}.
 

-If @var{locale} is a locale, @var{func} will be called for that locale.
+If optional @var{locale} is a locale, @var{func} will be called for that
+locale.

 If @var{locale} is a locale type, @var{func} will be mapped over all
 locales of that type.  If @var{locale} is @code{nil} or the symbol
 @code{all}, @var{func} will be mapped over all locales in
 @var{specifier}.
 
 If @var{locale} is a locale type, @var{func} will be mapped over all
 locales of that type.  If @var{locale} is @code{nil} or the symbol
 @code{all}, @var{func} will be mapped over all locales in
 @var{specifier}.
 

+Optional @var{ms-maparg} will be passed to @var{ms-func}.
+

 @var{func} is called with four arguments: the @var{specifier}, the
 locale being mapped over, the inst-list for that locale, and the
 optional @var{maparg}.  If any invocation of @var{func} returns
 @var{func} is called with four arguments: the @var{specifier}, the
 locale being mapped over, the inst-list for that locale, and the
 optional @var{maparg}.  If any invocation of @var{func} returns

@@ -1154,4 +1598,3 @@ value returned from @code{map-specifier}.  Otherwise,
 @defun specifier-locale-type-from-locale locale
 Given a specifier @var{locale}, this function returns its type.
 @end defun
 @defun specifier-locale-type-from-locale locale
 Given a specifier @var{locale}, this function returns its type.
 @end defun

-

diff --git a/man/lispref/tips.texi b/man/lispref/tips.texi
index a8ce727..0af08d0 100644 (file)
--- a/man/lispref/tips.texi
+++ b/man/lispref/tips.texi
@@ -239,6 +239,13 @@ only for program-generated buffers.)  The users will find Emacs more
 coherent if all libraries use the same conventions.
 
 @item
 coherent if all libraries use the same conventions.
 
 @item

+Use names starting with a space for temporary buffers (@pxref{Buffer
+Names}), or at least call @code{buffer-disable-undo} on them.  Otherwise
+they may stay referenced by internal undo variable(s) after getting
+killed.  If this happens before dumping (@pxref{Building XEmacs}), this
+may cause fatal error when portable dumper is used.
+
+@item

 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
 default indentation parameters.
 
 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
 default indentation parameters.
 

@@ -488,7 +495,7 @@ at that point.  For example:
 @end group
 @end smallexample
 
 @end group
 @end smallexample
 

-Every function that has no documentation string (because it is use only
+Every function that has no documentation string (because it is used only

 internally within the package it belongs to), should have instead a
 two-semicolon comment right before the function, explaining what the
 function does and how to call it properly.  Explain precisely what each
 internally within the package it belongs to), should have instead a
 two-semicolon comment right before the function, explaining what the
 function does and how to call it properly.  Explain precisely what each

diff --git a/man/new-users-guide/custom2.texi b/man/new-users-guide/custom2.texi
index e7ab517..a801ba7 100644 (file)
--- a/man/new-users-guide/custom2.texi
+++ b/man/new-users-guide/custom2.texi
@@ -93,7 +93,7 @@ M-x describe variable
 
 After you type any of the above commands, you will be prompted for a
 variable name in the @dfn{echo area}. Type in the name of the variable,
 
 After you type any of the above commands, you will be prompted for a
 variable name in the @dfn{echo area}. Type in the name of the variable,

-for example, type  @var{case-fold-search} @key{RET}
+for example, type  @code{case-fold-search} @key{RET}

 Your window will split into two and you will see the following message
 in that window:
 
 Your window will split into two and you will see the following message
 in that window:
 

@@ -219,9 +219,9 @@ the left margin or in the line's indentation:
 @end example
 
 @noindent
 @end example
 
 @noindent

-The value of the variable @var{c-tab-always-indent} is usually @samp{t}
+The value of the variable @code{c-tab-always-indent} is usually @samp{t}

 for @samp{true}. When this variable is true, then hitting the @key{TAB}
 for @samp{true}. When this variable is true, then hitting the @key{TAB}

-key always indents the current line. 
+key always indents the current line.

 
 @item
 This expression will turn on the @var{auto-fill-mode} when you are in
 
 @item
 This expression will turn on the @var{auto-fill-mode} when you are in

@@ -233,7 +233,7 @@ text mode:
 
 This mode will automatically break lines when you type a space so that
 the lines don't become too long. The length of the lines is controlled
 
 This mode will automatically break lines when you type a space so that
 the lines don't become too long. The length of the lines is controlled

-by the variable @var{fill-column}. You can set this variable to a value
+by the variable @code{fill-column}. You can set this variable to a value

 you wish. Look at the documentation for this variable to see its default
 value. To change the value to 75 for example, use:
 
 you wish. Look at the documentation for this variable to see its default
 value. To change the value to 75 for example, use:
 

@@ -383,7 +383,7 @@ will not be highlighted.
 
 @item 
 To control the number of buffers listed when you select the @b{Buffers}
 
 @item 
 To control the number of buffers listed when you select the @b{Buffers}

-menu, you need to set the variable @var{buffers-menu-max-size} to
+menu, you need to set the variable @code{buffers-menu-max-size} to

 whatever value you wish. For example, if you want 20 buffers to be listed
 when you select @b{Buffers} use:
 
 whatever value you wish. For example, if you want 20 buffers to be listed
 when you select @b{Buffers} use:
 

@@ -419,7 +419,7 @@ If you want an extensive menu-bar use the following expression in your
 @noindent
 If you want to write your own menus, you can look at some of the
 examples in
 @noindent
 If you want to write your own menus, you can look at some of the
 examples in

-@file{/usr/local/lib/xemacs-VERSION/lisp/packages/big-menubar.el} file.
+@file{/usr/local/lib/xemacs/xemacs-packages/lisp/edit-utils/big-menubar.el} file.

 
 @end itemize
 
 
 @end itemize
 

diff --git a/man/new-users-guide/files.texi b/man/new-users-guide/files.texi
index 1cfd3bf..9b68029 100644 (file)
--- a/man/new-users-guide/files.texi
+++ b/man/new-users-guide/files.texi
@@ -49,7 +49,7 @@ prompts you for a file, it uses the default-directory unless you specify
 a directory. You can see what the default directory of the current
 buffer is by using the @b{Describe Variable} option from the @b{Help}
 menu. When Emacs prompts you for the variable name to describe, type
 a directory. You can see what the default directory of the current
 buffer is by using the @b{Describe Variable} option from the @b{Help}
 menu. When Emacs prompts you for the variable name to describe, type

-@var{default-directory}. If you wish to open a file in some other
+@code{default-directory}. If you wish to open a file in some other

 directory, use @key{DEL} or the @key{BackSpace} key to go back and type
 the path name of the new directory.
 
 directory, use @key{DEL} or the @key{BackSpace} key to go back and type
 the path name of the new directory.
 

@@ -201,7 +201,7 @@ saved by reading the text from the file again (called
 
 @vindex make-backup-files
    When you save a file in Emacs, it destroys its old contents. However,
 
 @vindex make-backup-files
    When you save a file in Emacs, it destroys its old contents. However,

-if you set the variable @var{make-backup-files} to non-@code{nil}
+if you set the variable @code{make-backup-files} to non-@code{nil}

 i.e. @samp{t}, Emacs will create a @dfn{backup} file. Select the
 @b{Describe variable} option from the @b{Help} menu and look at the
 documentation for this variable. Its default value should be
 i.e. @samp{t}, Emacs will create a @dfn{backup} file. Select the
 @b{Describe variable} option from the @b{Help} menu and look at the
 documentation for this variable. Its default value should be

diff --git a/man/new-users-guide/search.texi b/man/new-users-guide/search.texi
index d4cc7f6..70b321a 100644 (file)
--- a/man/new-users-guide/search.texi
+++ b/man/new-users-guide/search.texi
@@ -11,7 +11,7 @@ complete typing the whole string. All searches in Emacs ignore the case
 of the text they are searching, i.e. if you are searching for "String",
 then "string" will also be one of the selections. If you want a case
 sensitive search select the @b{Case Sensitive Search} from the
 of the text they are searching, i.e. if you are searching for "String",
 then "string" will also be one of the selections. If you want a case
 sensitive search select the @b{Case Sensitive Search} from the

-@b{Option} menu. You can also set the variable @var{case-fold-search} to
+@b{Option} menu. You can also set the variable @code{case-fold-search} to

 @code{nil} for making searches case-sensitive. For information on setting
 variables, @xref{Setting Variables}. The two commands for searching for
 strings in XEmacs are:
 @code{nil} for making searches case-sensitive. For information on setting
 variables, @xref{Setting Variables}. The two commands for searching for
 strings in XEmacs are:

diff --git a/man/xemacs-faq.texi b/man/xemacs-faq.texi
index a56aca7..8f8b3eb 100644 (file)
--- a/man/xemacs-faq.texi
+++ b/man/xemacs-faq.texi
@@ -7,9 +7,9 @@
 @finalout
 @titlepage
 @title XEmacs FAQ
 @finalout
 @titlepage
 @title XEmacs FAQ

-@subtitle Frequently asked questions about XEmacs @* Last Modified: $Date: 2003/05/02 06:00:43 $
+@subtitle Frequently asked questions about XEmacs @* Last Modified: $Date: 2003/10/09 19:16:02 $

 @sp 1
 @sp 1

-@author Tony Rossini <rossini@@biostat.washington.edu>
+@author Tony Rossini <rossini@@u.washington.edu>

 @author Ben Wing <ben@@xemacs.org>
 @author Chuck Thompson <cthomp@@xemacs.org>
 @author Steve Baur <steve@@xemacs.org>
 @author Ben Wing <ben@@xemacs.org>
 @author Chuck Thompson <cthomp@@xemacs.org>
 @author Steve Baur <steve@@xemacs.org>

@@ -1430,24 +1430,18 @@ you don't use.  @emph{Nothing bad will happen if you delete a package
 that you do not use}.  You must be sure you do not use it though, so be
 conservative at first.
 
 that you do not use}.  You must be sure you do not use it though, so be
 conservative at first.
 

-Possible candidates for deletion include w3, games, hyperbole, mh-e,
-hm-html-menus, vm, viper, oobr, gnus, etc.  Ask yourself, @emph{Do I
-ever want to use this package?}  If the answer is no, then it is a
-candidate for removal.
+Any package with the possible exceptions of xemacs-base, and EFS are
+candidates for removal.  Ask yourself, @emph{Do I ever want to use this
+package?}  If the answer is no, then it is a candidate for removal.

 
 First, gzip all the .el files.  Then go about package by package and
 start gzipping the .elc files.  Then run XEmacs and do whatever it is
 
 First, gzip all the .el files.  Then go about package by package and
 start gzipping the .elc files.  Then run XEmacs and do whatever it is

-you normally do.  If nothing bad happens, then delete the directory.  Be
-conservative about deleting directories, and it would be handy to have a
-backup around in case you get too zealous.
+you normally do.  If nothing bad happens, then remove the package.  You
+can remove a package via the PUI interface 
+(@code{M-x pui-list-packages}, then press @kbd{d} to mark the packages
+you wish to delete, and then @kbd{x} to delete them.

 
 

-@file{prim}, @file{modes}, @file{packages}, and @file{utils} are four
-directories you definitely do @strong{not} want to delete, although
-certain packages can be removed from them if you do not use them.
-
-Online texinfo sources in the @file{info} can either be compressed them
-or remove them.  In either case, @kbd{C-h i} (info mode) will no longer
-work.
+Another method is to do @code{M-x package-get-delete-package}.

 
 @node Q2.0.3, Q2.0.4, Q2.0.2, Installation
 @unnumberedsubsec Q2.0.3: Compiling XEmacs with Netaudio.
 
 @node Q2.0.3, Q2.0.4, Q2.0.2, Installation
 @unnumberedsubsec Q2.0.3: Compiling XEmacs with Netaudio.

@@ -1944,7 +1938,7 @@ file @file{XKeysymDB}.
 The binary cannot find the @file{XKeysymDB} file.  The location is
 hardcoded at compile time so if the system the binary was built on puts
 it a different place than your system does, you have problems.  To fix,
 The binary cannot find the @file{XKeysymDB} file.  The location is
 hardcoded at compile time so if the system the binary was built on puts
 it a different place than your system does, you have problems.  To fix,

-set the environment variable @var{XKEYSYMDB} to the location of the
+set the environment variable @code{XKEYSYMDB} to the location of the

 @file{XKeysymDB} file on your system or to the location of the one
 included with XEmacs which should be at
 @iftex
 @file{XKeysymDB} file on your system or to the location of the one
 included with XEmacs which should be at
 @iftex

@@ -1957,7 +1951,7 @@ The binary is finding the XKeysymDB but it is out-of-date on your system
 and does not contain the necessary lines.  Either ask your system
 administrator to replace it with the one which comes with XEmacs (which
 is the stock R6 version and is backwards compatible) or set your
 and does not contain the necessary lines.  Either ask your system
 administrator to replace it with the one which comes with XEmacs (which
 is the stock R6 version and is backwards compatible) or set your

-@var{XKEYSYMDB} variable to the location of XEmacs's described above.
+@code{XKEYSYMDB} variable to the location of XEmacs's described above.

 @end itemize
 
 @node Q2.1.4, Q2.1.5, Q2.1.3, Installation
 @end itemize
 
 @node Q2.1.4, Q2.1.5, Q2.1.3, Installation

@@ -1993,7 +1987,7 @@ The buffer still exists; it just isn't in your face.
 
 Help!  I can not get XEmacs to display on my Envizex X-terminal!
 
 
 Help!  I can not get XEmacs to display on my Envizex X-terminal!
 

-Try setting the @var{DISPLAY} variable using the numeric IP address of
+Try setting the @code{DISPLAY} variable using the numeric IP address of

 the host you are running XEmacs from.
 
 @node Q2.1.6, Q2.1.7, Q2.1.5, Installation
 the host you are running XEmacs from.
 
 @node Q2.1.6, Q2.1.7, Q2.1.5, Installation

@@ -3762,9 +3756,8 @@ For an extensive menubar, add this line to your @file{init.el}/@file{.emacs}:
 @end lisp
 
 If you'd like to write your own, this file provides as good a set of
 @end lisp
 
 If you'd like to write your own, this file provides as good a set of

-examples as any to start from.  The file is located in
-@file{lisp/packages/big-menubar.el} in the XEmacs installation
-directory.
+examples as any to start from.  The file is located in edit-utils
+package. 

 
 @node Q3.8.3, Q3.8.4, Q3.8.2, Customization
 @unnumberedsubsec Q3.8.3: How do I control how many buffers are listed in the menu @code{Buffers List}?
 
 @node Q3.8.3, Q3.8.4, Q3.8.2, Customization
 @unnumberedsubsec Q3.8.3: How do I control how many buffers are listed in the menu @code{Buffers List}?

@@ -4546,6 +4539,14 @@ Don't let the installation procedure & instructions stop you from trying
 this package out---it's much simpler than it looks, and once installed,
 trivial to use.
 
 this package out---it's much simpler than it looks, and once installed,
 trivial to use.
 

+@email{youngs@@xemacs.org, Steve Youngs} writes:
+
+@quotation
+All the major Emacs Lisp based MUAs (Gnus, MH-E, and VM) all do their
+own thing when it comes to MIME so you won't need TM to get MIME support
+in these packages.
+@end quotation
+

 @node Q4.3.3, Q4.3.4, Q4.3.2, Subsystems
 @unnumberedsubsec Q4.3.3: Why isn't this @code{movemail} program working?
 
 @node Q4.3.3, Q4.3.4, Q4.3.2, Subsystems
 @unnumberedsubsec Q4.3.3: Why isn't this @code{movemail} program working?
 

@@ -5903,7 +5904,9 @@ document?
 
 The package @code{ps-print}, which is now included with XEmacs, provides
 the ability to do this.  The source code contains complete instructions
 
 The package @code{ps-print}, which is now included with XEmacs, provides
 the ability to do this.  The source code contains complete instructions

-on its use, in @file{<xemacs_src_root>/lisp/packages/ps-print.el}.
+on its use, in
+@file{$prefix/lib/xemacs/xemacs-packages/lisp/ps-print/ps-print.el},
+being the default location of an installed ps-print package.

 
 @node Q5.3.4, Q5.3.5, Q5.3.3, Miscellaneous
 @unnumberedsubsec Q5.3.4: Getting @kbd{M-x lpr} to work with postscript printer.
 
 @node Q5.3.4, Q5.3.5, Q5.3.3, Miscellaneous
 @unnumberedsubsec Q5.3.4: Getting @kbd{M-x lpr} to work with postscript printer.

diff --git a/man/xemacs/custom.texi b/man/xemacs/custom.texi
index 183abd7..5aeef5d 100644 (file)
--- a/man/xemacs/custom.texi
+++ b/man/xemacs/custom.texi
@@ -2106,7 +2106,7 @@ run both variants.
 Starting with XEmacs 21, XEmacs uses the class @samp{XEmacs} if it finds
 any XEmacs resources in the resource database when the X connection is
 initialized.  Otherwise, it will use the class @samp{Emacs} for
 Starting with XEmacs 21, XEmacs uses the class @samp{XEmacs} if it finds
 any XEmacs resources in the resource database when the X connection is
 initialized.  Otherwise, it will use the class @samp{Emacs} for

-backwards compatibility.  The variable @var{x-emacs-application-class}
+backwards compatibility.  The variable @code{x-emacs-application-class}

 may be consulted to determine the application class being used.
 
 The examples in this section assume the application class is @samp{Emacs}.
 may be consulted to determine the application class being used.
 
 The examples in this section assume the application class is @samp{Emacs}.

diff --git a/man/xemacs/packages.texi b/man/xemacs/packages.texi
index 32adac7..5696ebe 100644 (file)
--- a/man/xemacs/packages.texi
+++ b/man/xemacs/packages.texi
@@ -20,7 +20,6 @@ local needs with safe removal of unnecessary code.
 * Installing Packages:: How to install packages.
 * Building Packages::   Building packages from CVS sources.
 * Local.rules File::    This is an important file that you must create.
 * Installing Packages:: How to install packages.
 * Building Packages::   Building packages from CVS sources.
 * Local.rules File::    This is an important file that you must create.

-* Creating Packages::   The basics.

 * Available Packages::  A brief directory of packaged LISP.
 @end menu
 
 * Available Packages::  A brief directory of packaged LISP.
 @end menu
 

@@ -32,13 +31,13 @@ local needs with safe removal of unnecessary code.
 There are two main flavors of packages.
 
 @itemize @bullet
 There are two main flavors of packages.
 
 @itemize @bullet

-@item
+@item 

 Regular Packages
 @cindex regular packages
 A regular package is one in which multiple files are involved and one
 may not in general safely remove any of them.
 
 Regular Packages
 @cindex regular packages
 A regular package is one in which multiple files are involved and one
 may not in general safely remove any of them.
 

-@item
+@item 

 Single-File Packages
 @cindex single-file packages
 A single-file package is an aggregate collection of thematically
 Single-File Packages
 @cindex single-file packages
 A single-file package is an aggregate collection of thematically

@@ -70,6 +69,7 @@ savings).
 
 Currently, source packages are only available via CVS.  See
 @url{http://cvs.xemacs.org/} for details.
 
 Currently, source packages are only available via CVS.  See
 @url{http://cvs.xemacs.org/} for details.

+

 @node Installing Packages, Building Packages, Package Terminology, Packages
 @comment  node-name,  next,  previous,  up
 @cindex installing packages
 @node Installing Packages, Building Packages, Package Terminology, Packages
 @comment  node-name,  next,  previous,  up
 @cindex installing packages

@@ -95,7 +95,7 @@ where you grabbed the core distribution from, and are located in the
 subdirectory @file{packages}.  Package file names follow
 the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
 
 subdirectory @file{packages}.  Package file names follow
 the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
 

-If you have @ref{(EFS)}, packages can be installed over the network.
+If you have EFS @ref{(EFS)}, packages can be installed over the network.

 Alternatively, if you have copies of the packages locally, you can
 install packages from a local disk or CDROM.
 
 Alternatively, if you have copies of the packages locally, you can
 install packages from a local disk or CDROM.
 

@@ -107,13 +107,13 @@ are installed, using the visual package browser and installer.  You can
 access it via the menus:
 
 @example
 access it via the menus:
 
 @example

-        Tools -> Packages -> List and Install
+Tools -> Packages -> List and Install

 @end example
 
 Or, you can get to it via the keyboard:
 
 @example
 @end example
 
 Or, you can get to it via the keyboard:
 
 @example

-M-x pui-list-packages
+@code{M-x pui-list-packages}

 @end example
 
 Hint to system administrators of multi-user systems: it might be a good
 @end example
 
 Hint to system administrators of multi-user systems: it might be a good

@@ -125,10 +125,10 @@ using the @code{package-get-package-provider} function. Eg., if you know
 that you need @code{thingatpt}, type:
 
 @example
 that you need @code{thingatpt}, type:
 
 @example

-M-x package-get-package-provider RET thingatpt
+@code{M-x package-get-package-provider RET thingatpt}

 @end example
 
 @end example
 

-which will return something like (fsf-compat "1.08"). You can the use
+which will return something like @samp{(fsf-compat "1.08")}. You can the use

 one of the methods above for installing the package you want.
 
 @subsection XEmacs and Installing Packages
 one of the methods above for installing the package you want.
 
 @subsection XEmacs and Installing Packages

@@ -136,80 +136,18 @@ one of the methods above for installing the package you want.
 There are three main ways to install packages:
 
 @menu
 There are three main ways to install packages:
 
 @menu

-* Sumo::              All at once, using the 'Sumo Tarball'.
-* Manually::          Using individual package tarballs.

 * Automatically::     Using the package tools from XEmacs.
 * Automatically::     Using the package tools from XEmacs.

+* Manually::          Using individual package tarballs.
+* Sumo::              All at once, using the 'Sumo Tarball'.

 * Which Packages::    Which packages to install.
 * Removing Packages:: Removing packages.
 @end menu
 
 But regardless of the method you use to install packages, they can only
 * Which Packages::    Which packages to install.
 * Removing Packages:: Removing packages.
 @end menu
 
 But regardless of the method you use to install packages, they can only

-be used by XEmacs after a restart.
-
-@node Sumo, Manually, ,Installing Packages
-@comment  node-name,  next,  previous,  up
-@cindex sumo package install
-@heading Installing the Sumo Packages:
-Those with little time, cheap connections and plenty of disk space can
-install all the packages at once using the sumo tarballs.
-Download the file: @file{xemacs-sumo.tar.gz}
-
-For an XEmacs compiled with Mule you also need: @file{xemacs-mule-sumo.tar.gz}
-
-N.B. They are called 'Sumo Tarballs' for good reason. They are
-currently about 19MB and 4.5MB (gzipped) respectively.
-
-Install them by:
-
-@code{cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET}
-
-Or, if you have GNU tar:
-
-@code{cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET}
+be used by XEmacs after a restart unless the package in question has not
+been previously installed.

 
 

-As the Sumo tarballs are not regenerated as often as the individual
-packages, it is recommended that you use the automatic package tools
-afterwards to pick up any recent updates.
-
-@node Manually, Automatically, Sumo, Installing Packages
-@comment  node-name,  next,  previous,  up
-@cindex manual package install
-@heading Manual Package Installation:
-Fetch the packages from the FTP site, CD-ROM whatever. The filenames
-have the form @file{name-<version>-pkg.tar.gz} and are gzipped tar files. For
-a fresh install it is sufficient to untar the file at the top of the
-package hierarchy. 
-
-Note: If you are upgrading packages already installed, it's best to
-remove the old package first @ref{Removing Packages}.
-
-For example if we are installing the @file{xemacs-base}
-package (version 1.48):
-
-@example
-   mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
-   cd $prefix/lib/xemacs/xemacs-packages RET
-   gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
-
-Or if you have GNU tar, the last step can be:
-
-   tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
-@end example
-
-For MULE related packages, it is best to untar into the mule-packages
-hierarchy, i.e. for the @file{mule-base} package, version 1.37:
-
-@example
-   mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
-   cd $prefix/lib/xemacs/mule-packages RET
-   gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
-
-Or if you have GNU tar, the last step can be:
-
-   tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
-@end example
-
-@node Automatically, Which Packages ,Manually, Installing Packages
+@node Automatically, Manually, ,Installing Packages

 @comment  node-name,  next,  previous,  up
 @cindex automatic package install
 @cindex package tools
 @comment  node-name,  next,  previous,  up
 @cindex automatic package install
 @cindex package tools

@@ -229,33 +167,31 @@ you need are:
 
 and optionally:
 
 
 and optionally:
 

-   mule-base    - Needed if you want to use XEmacs with MULE.
+   mailcrypt    - To do PGP verification of the @file{package-index}
+                  file. 

 @end example
 
 After installing these by hand, fire up XEmacs and follow these
 steps.
 
 @enumerate 1
 @end example
 
 After installing these by hand, fire up XEmacs and follow these
 steps.
 
 @enumerate 1

-@item
+@item 

 Choose a download site.
 Choose a download site.

-via menu: Tools -> Packages -> Add Download Site 
+via menu: Tools -> Packages -> Set Download Site 

 via keyb: @code{M-x customize-variable RET package-get-remote RET}
 (put in the details of remote host and directory)
 
 If the package tarballs _AND_ the package-index file are in a
 via keyb: @code{M-x customize-variable RET package-get-remote RET}
 (put in the details of remote host and directory)
 
 If the package tarballs _AND_ the package-index file are in a

-local directory, you can: @code{M-x pui-add-install-directory RET}
+local directory, you can: @code{M-x pui-set-local-package-get-directory RET}

 
 

-@item
+@item 

 Obtain a list of packages and display the list in a buffer named
 @file{*Packages*}.
 menu: Tools -> Packages -> List & Install
 keyb: @code{M-x pui-list-packages RET}
 
 XEmacs will now connect to the remote site and download the
 Obtain a list of packages and display the list in a buffer named
 @file{*Packages*}.
 menu: Tools -> Packages -> List & Install
 keyb: @code{M-x pui-list-packages RET}
 
 XEmacs will now connect to the remote site and download the

-latest package-index file.  If you see an error about the
-package-index entries not being PGP signed, you can safely
-ignore this because PGP has not been integrated into the XEmacs
-package tools yet.
+latest package-index file.

 
 The visual package browser will then display a list of all packages.
 Help information will be displayed at the very bottom of the buffer; you
 
 The visual package browser will then display a list of all packages.
 Help information will be displayed at the very bottom of the buffer; you

@@ -278,7 +214,7 @@ installed and is up to date.
 
 From here, you can select or unselect packages for installation using
 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
 
 From here, you can select or unselect packages for installation using
 the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from

-the (Popup) Menu.
+the Popup @kbd{Mouse-3} Menu.

 Once you've finished selecting the packages, you can
 press the @kbd{x} key (or use the menu) to actually install the
 packages. Note that you will have to restart XEmacs for XEmacs to
 Once you've finished selecting the packages, you can
 press the @kbd{x} key (or use the menu) to actually install the
 packages. Note that you will have to restart XEmacs for XEmacs to

@@ -307,15 +243,17 @@ Kill the package buffer.
 @end table
 
 Moving the mouse over a package will also cause additional information
 @end table
 
 Moving the mouse over a package will also cause additional information

-about the package to be displayed in the minibuffer.
+about the package to be displayed in the minibuffer.  If you have
+balloon-help enabled a balloon-help frame will pop up and display
+additional package information also.

 
 
 
 

-@item
+@item 

 Choose the packages you wish to install.
 mouse: Click button 2 on the package name.
  keyb: @kbd{RET} on the package name
 
 Choose the packages you wish to install.
 mouse: Click button 2 on the package name.
  keyb: @kbd{RET} on the package name
 

-@item
+@item 

 Make sure you have everything you need.
 menu: Packages -> Add Required
 keyb: @kbd{r}
 Make sure you have everything you need.
 menu: Packages -> Add Required
 keyb: @kbd{r}

@@ -327,7 +265,7 @@ those packages also.
 For novices and gurus alike, this step can save your bacon.
 It's easy to forget to install a critical package.
 
 For novices and gurus alike, this step can save your bacon.
 It's easy to forget to install a critical package.
 

-@item
+@item 

 Download and install the packages.
 menu: Packages -> Install/Remove Selected
 keyb: @kbd{x}
 Download and install the packages.
 menu: Packages -> Install/Remove Selected
 keyb: @kbd{x}

@@ -343,7 +281,81 @@ Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
 will search for the latest version and install it and any packages that
 it depends upon.
 
 will search for the latest version and install it and any packages that
 it depends upon.
 

-@node Which Packages, Removing Packages, Automatically, Installing Packages
+@heading Keeping Packages Up To Date:
+Once you have the packages you want installed (using any of the above
+methods) you'll want to keep them up to date.  You can do this easily
+from the menubar:
+
+@example
+Tools -> Packages -> Set Download Site
+Tools -> Packages -> Update Installed Packages
+@end example
+
+
+@node Manually, Sumo, Automatically, Installing Packages
+@comment  node-name,  next,  previous,  up
+@cindex manual package install
+@heading Manual Package Installation:
+Fetch the packages from the FTP site, CD-ROM whatever. The filenames
+have the form @file{name-<version>-pkg.tar.gz} and are gzipped tar files. For
+a fresh install it is sufficient to untar the file at the top of the
+package hierarchy. 
+
+Note: If you are upgrading packages already installed, it's best to
+remove the old package first @ref{Removing Packages}.
+
+For example if we are installing the @file{xemacs-base}
+package (version 1.48):
+
+@example
+   mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
+   cd $prefix/lib/xemacs/xemacs-packages RET
+   gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
+
+Or if you have GNU tar, the last step can be:
+
+   tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
+@end example
+
+For MULE related packages, it is best to untar into the mule-packages
+hierarchy, i.e. for the @file{mule-base} package, version 1.37:
+
+@example
+   mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
+   cd $prefix/lib/xemacs/mule-packages RET
+   gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
+
+Or if you have GNU tar, the last step can be:
+
+   tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
+@end example
+
+@node Sumo, Which Packages, Manually, Installing Packages
+@comment  node-name,  next,  previous,  up
+@cindex sumo package install
+@heading Installing the Sumo Packages:
+Those with little time, cheap connections and plenty of disk space can
+install all the packages at once using the sumo tarballs.
+Download the file: @file{xemacs-sumo.tar.gz}
+
+For an XEmacs compiled with Mule you also need: @file{xemacs-mule-sumo.tar.gz}
+
+N.B. They are called 'Sumo Tarballs' for good reason. They are
+currently about 19MB and 4.5MB (gzipped) respectively.
+
+Install them by:
+
+@code{cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET}
+
+Or, if you have GNU tar:
+
+@code{cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET}
+
+As the Sumo tarballs are not regenerated as often as the individual
+packages, it is recommended that you use the automatic package tools
+afterwards to pick up any recent updates.
+
+@node Which Packages, Removing Packages, Sumo, Installing Packages

 @comment  node-name,  next,  previous,  up
 @cindex which packages
 @cindex choosing packages
 @comment  node-name,  next,  previous,  up
 @cindex which packages
 @cindex choosing packages

@@ -354,7 +366,7 @@ everything. A good minimal set of packages for XEmacs-latin1 would be
 
 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
 
 xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
 edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,

-text-modes, time
+text-modes, time, mailcrypt

 
 If you are using the XEmacs package tools, don't forget to do:
 
 
 If you are using the XEmacs package tools, don't forget to do:
 

@@ -402,7 +414,7 @@ Currently, source packages are only available via anonymous CVS.  See
 @item GNU make 
 (3.75 or later preferred).
 @item makeinfo 
 @item GNU make 
 (3.75 or later preferred).
 @item makeinfo 

-(1.68 from texinfo-3.11 or later required).
+(4.2 from GNU texinfo 4.2 or later required).

 @item GNU tar
 (or equivalent).
 @item GNU gzip
 @item GNU tar
 (or equivalent).
 @item GNU gzip

@@ -418,52 +430,10 @@ The packages CVS sources are most useful for creating XEmacs package
 tarballs for installation into your own XEmacs installations or for
 distributing to others.
 
 tarballs for installation into your own XEmacs installations or for
 distributing to others.
 

-Supported operations from @file{make} are:
-
-@table @code
-@item all
-Bytecompile all files, build and bytecompile byproduct files like
-@file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
-of TeXinfo documentation if present.
-
-@item bindist
-Does a @code{make all} as well as create a binary package tarball in the
-staging directory.
-
-@item install
-Bytecompile all files, build and bytecompile byproduct files like
-@file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
-of TeXinfo documentation if present.  And install everything into the
-staging directory.
-
-@item srckit
-Usually aliased to @code{srckit-std}.  This does a @code{make
-distclean} and creates a package source tarball in the staging
-directory.  This is generally only of use for package maintainers.
-
-@item binkit
-May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
-@code{binkit-sourcedata}, or
-@code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
-nothing to install in a data directory or info directory.
-@code{sourceinfo} indicates that source and info files are to be
-installed.  @code{sourcedata} indicates that source and etc (data) files
-are to be installed.  @code{sourcedatainfo} indicates source, etc
-(data), and info files are to be installed.  A few packages have needs
-beyond the basic templates so this is not yet complete.
-
-@item dist
-Runs the rules @code{srckit} followed by @code{binkit}.  This is
-primarily of use by XEmacs maintainers producing files for distribution.
-
-@item clean
-Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
-
-@item distclean
-Remove all created files.
-@end table
+For a list and description of the different @file{Makefile} targets,
+@xref{Makefile Targets,,,lispref}.

 
 

-@node Local.rules File, Creating Packages, Building Packages, Packages
+@node Local.rules File, Available Packages, Building Packages, Packages

 @comment  node-name,  next,  previous,  up
 @cindex local.rules
 @heading The Local.rules File:
 @comment  node-name,  next,  previous,  up
 @cindex local.rules
 @heading The Local.rules File:

@@ -472,201 +442,10 @@ the top level of the CVS module, @file{packages}, contains the
 file, @file{Local.rules.template}.  Simply copy that to
 @file{Local.rules} and edit it to suit your needs.
 
 file, @file{Local.rules.template}.  Simply copy that to
 @file{Local.rules} and edit it to suit your needs.
 

-These are the variables in 'Local.rules' that you will need to
-address. Items that have default settings have those defaults shown. 
-
-@table @var
-@item XEMACS = xemacs
-If your XEmacs isn't in your path, change this.  Native MS Windows users
-should double quote this if the path has embedded spaces.
-
-@item BUILD_WITHOUT_MULE =
-Building from CVS defaults to building the Mule
-packages.  Set this to 't' if you don't want/have Mule
-
-@item XEMACS_NATIVE_NT =
-Set this to 't' if you are building on WinNT.  NT users should note that
-you still need the Cygwin environment to build the packages.
-
-@item XEMACS_INSTALLED_PACKAGES_ROOT = /usr/local/lib/xemacs
-This is the directory tree under which the installed packages go.  Under
-this directory there would normally be @file{xemacs-packages/} for
-standard (non-Mule) packages, @file{mule-packages/} for Mule packages
-(if you built XEmacs with Mule), and possibly @file{site-packages/} for
-3rd party packages that aren't distributed by XEmacs.org.
-
-@item symlink = 
-Set this to 't' if you want to do a "run in place".
-Setting this doesn't work well with 'make bindist'
-
-@item NONMULE_INSTALLED_PACKAGES_ROOT = $@{XEMACS_INSTALLED_PACKAGES_ROOT@}/xemacs-packages
-This is where the non-Mule packages are installed to.  You probably
-don't want to change this.
-
-@item MULE_INSTALLED_PACKAGES_ROOT = $@{XEMACS_INSTALLED_PACKAGES_ROOT@}/mule-packages
-This is where the Mule packages are installed to.  You probably don't
-want to change this.  Please note that @code{make bindist} does
-@emph{not} use this variable.  When doing a @code{make bindist}
-@emph{everything} goes into @var{NONMULE_INSTALLED_PACKAGES_ROOT}.
-
-@item NONMULE_PACKAGES = xemacs-packages
-This is where you set the non-Mule packages that you want to install. eg:
-@example
-      XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb
-@end example
-
-@item MULE_PACKAGES = mule-packages
-Same as for 'XEMACS_PACKAGES' except you list the Mule
-packages you want to install here. eg:
-@example
-      MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
-@end example
-
-@item PACKAGE_INDEX = package-index
-If you want the package-index file to have a different
-name, change this.
+For a complete discussion of the @file{Local.rules} file,
+@xref{Local.rules File,,,lispref}.

 
 

-@item INSTALL = install -c
-The path to your BSD compatible install program.
-
-@item TAR = tar
-The path to your tar program
-
-@item BZIP2 =
-If you want bzip2 tarballs, set this.
-
-@item MAKEINFO = makeinfo
-The path to your makeinfo program
-@end table
-
-
-@node Creating Packages, Available Packages, Local.rules File, Packages
-@comment  node-name,  next,  previous,  up
-@cindex creating packages
-@heading Creating Packages:
-Creating a package from an existing Lisp library is not very difficult.
-
-In addition to the Lisp libraries themselves, you need a
-@file{package-info.in} file and a simple @file{Makefile}.  The rest is
-done by @file{XEmacs.rules}, part of the packaging system
-infrastructure.
-
-@file{package-info.in} contains a single Lisp form like this:
-
-@example
-(name                               ; your package's name
-  (standards-version 1.1
-   version VERSION
-   author-version AUTHOR_VERSION
-   date DATE
-   build-date BUILD_DATE
-   maintainer MAINTAINER
-   distribution xemacs              ; change to "mule" if MULE is needed
-   priority high
-   category CATEGORY
-   dump nil
-   description "DESCRIPTION"        ; one-line period-terminated string
-   filename FILENAME
-   md5sum MD5SUM
-   size SIZE
-   provides (feature1 feature2)     ; one for every `provides' form
-   requires (REQUIRES)
-   type regular
-))
-@end example
-
-You must fill in the four commented lines.  The value of @code{name} is
-the name of your package as an unquoted symbol.  Normally it is the name
-of the main Lisp file or principal feature provided.  The allowed values
-for distribution are @code{xemacs} and @code{mule}.  Write them as
-unquoted symbols.  The @code{description} is a quoted Lisp string; use
-the usual conventions.  The first letter should be capitalized, and the
-string should end in a period.  It need not be a complete sentence
-grammatically.  The value for @code{provides} is a list of feature
-symbols (written unquoted).  All of the features provided by libraries
-in your package should be elements of this list.  Implementing an
-automatic method for generating the @file{provides} line is desirable,
-but as yet undone.
-
-The variables in upper-case are references to variables set in the
-@file{Makefile} or automatically generated.  Do not change them; they
-are automatically filled in by the build process.
-
-The remaining lines refer to implementation constants
-(@code{standards-version}), or features that are unimplemented or have
-been removed (@code{priority} and @code{dump}).  The @code{type} line is
-not normally relevant to external maintainers; the alternate value is
-@code{single-file}, which refers to packages consed up out of a number
-of single-file libraries that are more or less thematically related.  An
-example is @code{prog-modes}.  Single-file packages are basically for
-administrative convenience, and new packages should generally be created
-as regular packages.
-
-The @file{Makefile} is quite stylized.  The idea is similar to an
-@file{Imakefile} or an @code{automake} file: the complexity is hidden in
-generic rules files, in this case the @file{XEmacs.rules} include file
-in the top directory of the packages hierarchy.  Although a number of
-facilities are available for complex libraries, most simple packages'
-@file{Makefile}s contain a copyright notice, a few variable definitions,
-an include for @file{XEmacs.rules}, and a couple of standard targets.
-
-The first few @code{make} variables defined are @code{VERSION},
-@code{AUTHOR_VERSION}, @code{MAINTAINER}, @code{PACKAGE},
-@code{PKG_TYPE}, @code{REQUIRES}, and @code{CATEGORY}.  All but one were
-described in the description of @file{package-info.in}.  The last is an
-administrative grouping.  Current categories include @code{standard},
-and @code{mule}.
-
-Next, define the variable @code{ELCS}.  This contains the list of the
-byte-compiled Lisp files used by the package.  These files and their
-@file{.el} versions will be included in the binary package.  If there
-are other files (such as extra Lisp sources or an upstream
-@file{Makefile}) that are normally placed in the installed Lisp
-directory, but not byte-compiled, they can be listed as the value of
-@code{EXTRA_SOURCES}.
-
-The include is simply
-@example
-include ../../XEmacs.rules
-@end example
-
-The standard targets follow.  These are
-
-@example
-all:: $(ELCS) auto-autoloads.elc
-
-srckit: srckit-alias
-
-binkit: binkit-alias
-@end example
-
-Other targets (such as Texinfo sources) may need to be added as
-dependencies for the @code{all} target.  Dependencies for @code{srckit}
-and @code{binkit} (that is, values for @var{srckit-alias} and
-@var{binkit-alias}) are defined in @file{XEmacs.rules}.  The most useful
-of these values are given in the following table.
-
-@table @var
-@item srckit-alias
-Usually set to @code{srckit-std}.
-
-@item binkit-alias
-May be set to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
-@code{binkit-sourcedata}, or
-@code{binkit-sourcedatainfo}.  @code{sourceonly} indicates there is
-nothing to install in a data directory or info directory.
-@code{sourceinfo} indicates that source and info files are to be
-installed.  @code{sourcedata} indicates that source and etc (data) files
-are to be installed.  @code{sourcedatainfo} indicates source, etc
-(data), and info files are to be installed.
-@end table
-
-Data files include things like pixmaps for a package-specific toolbar,
-and are normally installed in @file{etc/@var{PACKAGE_NAME}}.  A few
-packages have needs beyond the basic templates.  See @file{XEmacs.rules}
-or a future revision of this manual for details.
-
-@node Available Packages,  , Creating Packages, Packages
+@node Available Packages,  , Local.rules File, Packages

 @comment  node-name,  next,  previous,  up
 @cindex available packages
 @cindex packages
 @comment  node-name,  next,  previous,  up
 @cindex available packages
 @cindex packages

@@ -676,7 +455,7 @@ xemacs.org and it's mirrors.  If a particular package that you are
 looking for isn't here, please send a message to the
 @email{xemacs-beta@@xemacs.org, XEmacs Beta list}.
 
 looking for isn't here, please send a message to the
 @email{xemacs-beta@@xemacs.org, XEmacs Beta list}.
 

-This data is up to date as of September 22, 2002.
+This data is up to date as of June 27, 2003.

 
 @subsection Normal Packages
 A very broad selection of elisp packages.
 
 @subsection Normal Packages
 A very broad selection of elisp packages.

@@ -793,6 +572,9 @@ GNU Emacs compatibility files.
 @item games
 Tetris, Sokoban, and Snake.
 
 @item games
 Tetris, Sokoban, and Snake.
 

+@item general-docs
+General documentation.  Presently, empty.
+

 @item gnats
 XEmacs bug reports.
 
 @item gnats
 XEmacs bug reports.
 

@@ -851,13 +633,13 @@ Support for Multiple Major Modes within a single buffer.
 Miscellaneous Networking Utilities.  This is a single-file package and 
 files may be deleted at will.
 
 Miscellaneous Networking Utilities.  This is a single-file package and 
 files may be deleted at will.
 

+@item ocaml
+Objective Caml editing support.
+

 @item os-utils
 Miscellaneous single-file O/S utilities, for printing, archiving,
 compression, remote shells, etc.
 
 @item os-utils
 Miscellaneous single-file O/S utilities, for printing, archiving,
 compression, remote shells, etc.
 

-@item ocaml
-Objective Caml language support.
-

 @item pc
 PC style interface emulation.
 
 @item pc
 PC style interface emulation.
 

@@ -870,6 +652,9 @@ Provides programmatic completion.
 @item perl-modes
 Perl language support.
 
 @item perl-modes
 Perl language support.
 

+@item pgg
+Emacs interface to various PGP implementations.
+

 @item prog-modes
 Miscellaneous single-file lisp files for various programming languages.
 
 @item prog-modes
 Miscellaneous single-file lisp files for various programming languages.
 

@@ -982,6 +767,9 @@ An Emacs mailer.
 @item w3
 A Web browser.
 
 @item w3
 A Web browser.
 

+@item x-symbol
+Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts.
+

 @item xemacs-base
 Fundamental XEmacs support.  Install this unless you wish a totally
 naked XEmacs.
 @item xemacs-base
 Fundamental XEmacs support.  Install this unless you wish a totally
 naked XEmacs.

diff --git a/man/xemacs/reading.texi b/man/xemacs/reading.texi
index 57e965c..ca1e156 100644 (file)
--- a/man/xemacs/reading.texi
+++ b/man/xemacs/reading.texi
@@ -4,29 +4,35 @@
 @cindex mail
 @cindex message
 
 @cindex mail
 @cindex message
 

-XEmacs provides three separate mail-reading packages.  Each one comes with
-its own manual, which is included standard with the XEmacs distribution.
+XEmacs provides several mail-reading packages.  Each one comes with
+its own manual, which is included in each package.

 
 The recommended mail-reading package for new users is VM.  VM works
 with standard Unix-mail-format folders and was designed as a replacement
 for the older Rmail.
 
 XEmacs also provides a sophisticated and comfortable front-end to the
 
 The recommended mail-reading package for new users is VM.  VM works
 with standard Unix-mail-format folders and was designed as a replacement
 for the older Rmail.
 
 XEmacs also provides a sophisticated and comfortable front-end to the

-MH mail-processing system, called @samp{mh-e}.  Unlike in other
+MH mail-processing system, called @samp{MH-E}.  Unlike in other

 mail programs, folders in MH are stored as file-system directories,
 with each message occupying one (numbered) file.  This facilitates
 working with mail using shell commands, and many other features of
 MH are also designed to integrate well with the shell and with
 mail programs, folders in MH are stored as file-system directories,
 with each message occupying one (numbered) file.  This facilitates
 working with mail using shell commands, and many other features of
 MH are also designed to integrate well with the shell and with

-shell scripts.  Keep in mind, however, that in order to use mh-e
+shell scripts.  Keep in mind, however, that in order to use MH-E

 you must have the MH mail-processing system installed on your
 computer.
 
 you must have the MH mail-processing system installed on your
 computer.
 

-Finally, XEmacs provides the Rmail package.  Rmail is (currently) the
-only mail reading package distributed with FSF GNU Emacs, and is
-powerful in its own right.  However, it stores mail folders in a special
-format called @samp{Babyl}, that is incompatible with all other
-frequently-used mail programs.  A utility program is provided for
-converting Babyl folders to standard Unix-mail format; however, unless
-you already have mail in Babyl-format folders, you should consider
-using VM or mh-e instead. (If at times you have to use FSF Emacs, it
-is not hard to obtain and install VM for that editor.)
+The @dfn{Everything including the kitchen sink} package @samp{Gnus} is
+also available as an XEmacs package.  Gnus also handles Usenet articles
+as well as mail.
+
+@samp{MEW} (Messaging in the Emacs World) is another mail-reading
+package available for XEmacs.
+
+Finally, XEmacs provides the Rmail package.  Rmail is (currently)
+the only mail reading package distributed with FSF GNU Emacs, and is
+powerful in its own right.  However, it stores mail folders in a
+special format called @samp{Babyl}, that is incompatible with all
+other frequently-used mail programs.  A utility program is provided
+for converting Babyl folders to standard Unix-mail format; however,
+unless you already have mail in Babyl-format folders, you should
+consider using Gnus, VM, or MH-E instead.

diff --git a/man/xemacs/xemacs.texi b/man/xemacs/xemacs.texi
index d5d83b6..89fd4b3 100644 (file)
--- a/man/xemacs/xemacs.texi
+++ b/man/xemacs/xemacs.texi
@@ -241,7 +241,6 @@ Packages
 * Installing Packages:: How to install packages.
 * Building Packages::   Building packages from sources.
 * Local.rules File::    An important part of building packages.
 * Installing Packages:: How to install packages.
 * Building Packages::   Building packages from sources.
 * Local.rules File::    An important part of building packages.

-* Creating Packages::   The basics.

 * Available Packages::  A brief directory of packaged LISP.
 
 Basic Editing Commands
 * Available Packages::  A brief directory of packaged LISP.
 
 Basic Editing Commands

diff --git a/netinstall/ChangeLog b/netinstall/ChangeLog
index 696f348..7a19f38 100644 (file)
--- a/netinstall/ChangeLog
+++ b/netinstall/ChangeLog
@@ -1,3 +1,7 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/nt/ChangeLog b/nt/ChangeLog
index d568d0b..1fa8429 100644 (file)
--- a/nt/ChangeLog
+++ b/nt/ChangeLog
@@ -1,3 +1,21 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+
+2003-12-10  Adrian Aichner  <adrian@xemacs.org>
+
+       * xemacs.mak (COPYCMD): New.
+       * xemacs.mak (COPY): New.
+       * xemacs.mak (COPYDIR): New.
+       * xemacs.mak (XEMACS_INCLUDES):
+       * xemacs.mak (install): Allow xemacs.mak to overwrite existing
+       installation.
+
+2003-11-06  Adrian Aichner  <adrian@xemacs.org>
+
+       * minitar.c: Sync with Xemacs 21.5 version to fix package
+       installation in native Windows XEmacs.
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/nt/minitar.c b/nt/minitar.c
index a704d5f..d5e3d40 100644 (file)
--- a/nt/minitar.c
+++ b/nt/minitar.c
@@ -23,12 +23,12 @@
 
 #include <zlib.h>
 
 
 #include <zlib.h>
 

-static int
-Usage(char *name)
+static void
+Usage (char *name)

 {
 {

-  fprintf(stderr,"Usage: %s file.tar.gz [base-dir]\n",name);
-  fprintf(stderr,"\tExtracts the contents compressed tar file to base-dir\n");
-  exit(-1);
+  fprintf (stderr, "Usage: %s file.tar.gz [base-dir]\n", name);
+  fprintf (stderr, "\tExtracts the contents compressed tar file to base-dir\n");
+  exit (-1);

 }
 
 
 }
 
 

@@ -36,10 +36,10 @@ Usage(char *name)
 #define MAXNAMELEN 1024
 
 static int
 #define MAXNAMELEN 1024
 
 static int

-octal(char *str)
+octal (char *str)

 {
   int ret = -1;
 {
   int ret = -1;

-  sscanf(str,"%o",&ret);
+  sscanf (str, "%o", &ret);

   return ret;
 }
 
   return ret;
 }
 

@@ -48,39 +48,40 @@ octal(char *str)
    path component, so it is not created as a directory */
 
 static int
    path component, so it is not created as a directory */
 
 static int

-makepath(char *path)
+makepath (char *path)

 {
   char tmp[MAXNAMELEN];
   char *cp;
 
 {
   char tmp[MAXNAMELEN];
   char *cp;
 

-  for (cp=path; cp; cp = (char*)strchr(cp+1,'/')){
-    if (!*cp)
-      break;
-    if (*cp != '/')
-      continue;
-    strncpy(tmp, path, cp-path);
-    tmp[cp-path] = '\0';
-    if (strlen(tmp) == 0)
-      continue;
+  for (cp=path; cp; cp = (char*)strchr (cp+1, '/'))
+    {
+      if (!*cp)
+       break;
+      if (*cp != '/')
+       continue;
+      strncpy (tmp, path, cp-path);
+      tmp[cp-path] = '\0';
+      if (strlen (tmp) == 0)
+       continue;

 #ifdef WIN32_NATIVE
 #ifdef WIN32_NATIVE

-    if (mkdir(tmp)){
+      if (mkdir (tmp))

 #else
 #else

-    if (mkdir(tmp,0777)){
+       if (mkdir (tmp, 0777))

 #endif
 #endif

-      if (errno == EEXIST)
-       continue;
-      else
-       return -1;
+         {
+           if (errno == EEXIST)
+             continue;
+           else
+             return -1;
+         }

     }
     }

-  }

   return 0;
 }
 
   return 0;
 }
 

-  
-                    
+

 
 int
 
 int

-main(int argc, char **argv)
+main (int argc, char **argv)

 {
   char fullname[MAXNAMELEN];
   char *basedir = ".";
 {
   char fullname[MAXNAMELEN];
   char *basedir = ".";

@@ -101,124 +102,145 @@ main(int argc, char **argv)
   int directory = 0;
 
   if (argc < 2 || argc > 3)
   int directory = 0;
 
   if (argc < 2 || argc > 3)

-    Usage(argv[0]);
+    Usage (argv[0]);

 
   tarfile = argv[1];
   if (argc==3)
     basedir = argv[2];
 
 
   tarfile = argv[1];
   if (argc==3)
     basedir = argv[2];
 

-  if (! (infile = gzopen(tarfile,"rb"))){
-    fprintf(stderr,"Cannot open %s\n", tarfile);
-    exit(-2);
-  }
-  
-  while (1){
-  
-
-    nread = gzread(infile,block,512);
-
-    if (!in_block && nread == 0)
-      break;
-
-    if (nread != BLOCKSIZE){
-      fprintf(stderr,"Error: incomplete block read. Exiting.\n");
-      exit(-2);
+  if (! (infile = gzopen (tarfile, "rb")))
+    {
+      fprintf (stderr, "Cannot open %s\n", tarfile);
+      exit (-2);

     }
     }

+  
+  while (1)
+    {
+      nread = gzread (infile, block, 512);

 
 

-    if (!in_block){
-      if (block[0]=='\0')  /* We're done */
+      if (!in_block && nread == 0)

        break;
 
        break;
 

-      strncpy(magic,block+257,6);
-      magic[6] = '\0';
-      if (strcmp(magic,"ustar ")){
-       fprintf(stderr,
-               "Error: incorrect magic number in tar header. Exiting\n");
-      }
-
-      strncpy(name,block,100);
-      name[100] = '\0';
-      sprintf(fullname,"%s/%s",basedir,name);
-      printf("%s\n",fullname);
-      type = block[156];
+      if (nread != BLOCKSIZE)
+       {
+         fprintf (stderr, "Error: incomplete block read. Exiting.\n");
+         exit (-2);
+       }
+
+      if (!in_block)
+       {
+         if (block[0]=='\0')  /* We're done */
+           break;
+
+         strncpy (magic, block+257, 6);
+         magic[6] = '\0';
+         if (strcmp (magic, "ustar "))
+           {
+             fprintf (stderr,
+                      "Error: incorrect magic number in tar header. Exiting\n");
+             exit (-2);
+           }
+
+         strncpy (name, block, 100);
+         name[100] = '\0';
+         sprintf (fullname, "%s/%s", basedir, name);
+         printf ("%s\n", fullname);
+         type = block[156];

       
       

-      switch(type){
-      case '0':
-      case '\0':
-       directory = 0;
-       break;
-      case '5':
-       directory = 1;
-       break;
-      default:
-       fprintf(stderr,"Error: unknown type flag %c. Exiting.\n",type);
-       break;
-      }
+         switch (type)
+           {
+           case '0':
+           case '\0':
+             directory = 0;
+             break;
+           case '5':
+             directory = 1;
+             break;
+           default:
+             fprintf (stderr, "Error: unknown type flag %c. Exiting.\n", type);
+             exit (-2);
+             break;
+           }

       
       

-      if (directory){
-       in_block = 0;
+         if (directory)
+           {
+             in_block = 0;

        
        

-       /* makepath will ignore the final path component, so make sure 
-          dirnames have a trailing slash */
-
-       if (fullname[strlen(fullname)-1] != '/')
-         strcat(fullname,"/");
-       if (makepath(fullname)){
-         fprintf(stderr, "Error: cannot create directory %s. Exiting.\n",
-                 fullname);
-         exit(-2);
+             /* makepath will ignore the final path component, so make sure 
+                dirnames have a trailing slash */
+
+             if (fullname[strlen (fullname)-1] != '/')
+               strcat (fullname, "/");
+             if (makepath (fullname))
+               {
+                 fprintf (stderr, "Error: cannot create directory %s. Exiting.\n",
+                          fullname);
+                 exit (-2);
+               }
+             continue;
+           }
+         else
+           { /*file */
+             in_block = 1;
+             if (outfile)
+               {
+                 if (fclose (outfile))
+                   {
+                     fprintf (stderr, "Error: cannot close file %s. Exiting.\n",
+                              fullname);
+                     exit (-2);
+                   }
+                 outfile = (FILE*)0;
+               }
+
+             if (!(outfile = fopen (fullname, "wb")))
+               {
+                 /*try creating the directory, maybe it's not there */
+                 if (makepath (fullname))
+                   {
+                     fprintf (stderr, "Error: cannot create file %s. Exiting.\n",
+                              fullname);
+                     exit (-2);
+                   }
+                 /* now try again to open the file */
+                 if (!(outfile = fopen (fullname, "wb")))
+                   {
+                     fprintf (stderr, "Error: cannot create file %s. Exiting.\n",
+                              fullname);
+                     exit (-2);
+                   }
+               }
+
+             strncpy (osize, block+124, 12);
+             osize[12] = '\0';
+             size = octal (osize);
+             if (size<0)
+               {
+                 fprintf (stderr, "Error: invalid size in tar header. Exiting.\n");
+                 exit (-2);
+               }
+             if (size==0)      /* file of size 0 is done */
+               in_block = 0;
+           }

        }
        }

-       continue;
-      } else { /*file */
-       in_block = 1;
-       if (outfile){
-         if (fclose(outfile)){
-           fprintf(stderr,"Error: cannot close file %s. Exiting.\n",
-                   fullname);
-           exit(-2);
-         }
-         outfile = (FILE*)0;
-       }
-
-       if ( !(outfile = fopen(fullname,"wb"))){
-         /*try creating the directory, maybe it's not there */
-         if (makepath(fullname)){
-           fprintf(stderr,"Error: cannot create file %s. Exiting.\n",
-                   fullname);
-           exit(-2);
-         }
-         /* now try again to open the file */
-         if (!(outfile = fopen(fullname,"wb"))){
-           fprintf(stderr,"Error: cannot create file %s. Exiting.\n",
-                   fullname);
-           exit(-2);
-         }
-       }
-
-       strncpy(osize,block+124,12);
-       osize[12] = '\0';
-       size = octal(osize);
-       if (size<0){
-         fprintf(stderr,"Error: invalid size in tar header. Exiting.\n");
-         exit(-2);
-       }
-      }
-    } else { /* write or continue writing file contents */
-      nbytes = size>512? 512:size;
+      else
+       { /* write or continue writing file contents */
+         nbytes = size>512? 512:size;

       
       

-      nwritten = fwrite(block, 1, nbytes, outfile);
-      if (nwritten != nbytes){
-       fprintf(stderr, "Error: only wrote %d bytes to file %s. Exiting.\n",
-               nwritten, fullname);
-      }
-      size -= nbytes;
-      if (size==0)
-       in_block = 0;
+         nwritten = fwrite (block, 1, nbytes, outfile);
+         if (nwritten != nbytes)
+           {
+             fprintf (stderr, "Error: only wrote %d bytes to file %s. Exiting.\n",
+                      nwritten, fullname);
+             exit (-2);
+           }
+         size -= nbytes;
+         if (size==0)
+           in_block = 0;
+       }

     }
     }

-  }
-  exit (0);
-}      
-
+  return 0;
+}

 
 
   
 
 
   

diff --git a/nt/xemacs.mak b/nt/xemacs.mak
index 235937b..35ddb91 100644 (file)
--- a/nt/xemacs.mak
+++ b/nt/xemacs.mak
@@ -44,16 +44,25 @@ LWLIB_SRCDIR=$(XEMACS)\lwlib
 MAKEDIRSTRING=$(MAKEDIR:\=\\)
 XEMACSDIRSTRING=$(MAKEDIRSTRING:\\nt=)
 
 MAKEDIRSTRING=$(MAKEDIR:\=\\)
 XEMACSDIRSTRING=$(MAKEDIRSTRING:\\nt=)
 

-
-# Define a variable for the 'del' command to use
-# N.B. Windows Millenium Edition's ERASE can only handle one target (file or
-# wildcard) per invocation.  Make sure each use has only one target!
-DEL=-del
-

 # Program name and version
 
 !include "$(XEMACS)\version.sh"
 
 # Program name and version
 
 !include "$(XEMACS)\version.sh"
 

+# Put these before including config.inc so they can be overridden there.
+# Note that some versions of some commands are deficient.
+
+# Define a variable for the 'del' command to use.
+# WinME's DEL command can only handle one argument and only has the /P flag.
+# So only delete one glob at a time.  Override flags in config.inc.
+DEL=-del
+
+# Tell COPY, MOVE, and XCOPY to suppress confirmation for overwriting
+# files.
+COPYCMD=/y
+# Define the 'copy' command to use.
+COPY=xcopy /q
+COPYDIR=xcopy /q /e
+

 !include "config.inc"
 
 !if !defined(INFODOCK)
 !include "config.inc"
 
 !if !defined(INFODOCK)

@@ -490,12 +499,15 @@ XEMACS_INCLUDES=\
 
 # #### Copying is cheap, we should just force these
 $(SRC)\config.h:       config.h
 
 # #### Copying is cheap, we should just force these
 $(SRC)\config.h:       config.h

+       set COPYCMD=$(COPYCMD)

        copy config.h $(SRC)
 
 $(SRC)\Emacs.ad.h:     Emacs.ad.h
        copy config.h $(SRC)
 
 $(SRC)\Emacs.ad.h:     Emacs.ad.h

+       set COPYCMD=$(COPYCMD)

        copy Emacs.ad.h $(SRC)
 
 $(SRC)\paths.h:        paths.h
        copy Emacs.ad.h $(SRC)
 
 $(SRC)\paths.h:        paths.h

+       set COPYCMD=$(COPYCMD)

        copy paths.h $(SRC)
 
 #------------------------------------------------------------------------------
        copy paths.h $(SRC)
 
 #------------------------------------------------------------------------------

@@ -1405,6 +1417,7 @@ temacs: $(LASTFILE) $(TEMACS)
 # use this rule to install the system
 install:       all
        cd $(NT)
 # use this rule to install the system
 install:       all
        cd $(NT)

+       set COPYCMD=$(COPYCMD)

        @echo Installing in $(INSTALL_DIR) ...
        @echo PlaceHolder > PlaceHolder
        @xcopy /q PROBLEMS "$(INSTALL_DIR)\"
        @echo Installing in $(INSTALL_DIR) ...
        @echo PlaceHolder > PlaceHolder
        @xcopy /q PROBLEMS "$(INSTALL_DIR)\"

diff --git a/src/ChangeLog b/src/ChangeLog
index 4aaac55..1351f2c 100644 (file)
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,90 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+
+2004-01-30  Glynn Clements  <glynn.clements@virgin.net>
+
+       * device-x.c (x_error_handler): Don't call stderr_out
+
+2003-11-07  Katsumi Yamaoka <yamaoka@jpl.org>
+
+       * buffer.c (other-buffer): Clarify documentation of order of
+       arguments for FSF Emacs.
+
+2003-10-11  Olivier Galibert  <galibert@pobox.com>
+
+       * window.c (Fdelete_window): Dirty the mirror structure _before_
+       marking the window deleted.
+
+2003-09-15  Jerry James  <james@xemacs.org>
+
+       * event-msw.c (debug_mswin_messages): Conditionally compile
+       messages missing from the Cygwin headers.
+
+2003-06-16  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * data.c (eq_with_ebola_notice): Fix typo in comment.
+       (Ftrue_list_p): Improve docstring.
+
+2003-10-13  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * frame-x.c (x_update_frame_external_traits): Fix XtSetArg idiom.
+
+2003-09-27  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * search.c (trivial_regexp_p): Regexps containing "\{" are
+       nontrivial.  Thanks to Manfred Bartz for reporting the bug and
+       Stefan Monnier for suggesting a diagnosis.
+
+2003-09-25  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * elhash.c (make-hash-table): Clarify use of :test #'equal.
+
+2003-09-12  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * search.c (Fsearch_forward):
+       (Fsearch_backward):
+       Document negative count.
+
+2003-09-13  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * regex.c (re_max_failures): Bump to 20000 for REGEX_MALLOC, too.
+
+2003-09-13  Martin Buchholz  <martin@xemacs.org>
+
+       * s/sol2.h: Use OS_RELEASE=os_release_major*100+os_release_minor
+
+2003-09-15  Vin Shelton  <acs@xemacs.org>
+
+       * .gdbinit (pobj): Remove Ilya's fix that was only intended for
+       21.5.
+
+2003-09-12  Yoshiki Hayashi  <yoshiki@xemacs.org>
+
+       * regex.c (TRANSLATE_EXTENDED_UNSAFE): Remove.
+       (re_search_2): Match the first byte of Bufbyte, not Emchar.
+       (re_match_2_internal): Use TRANSLATE instead of
+       TRANSLATE_EXTENDED_UNSAFE.  The latter was a hack to bypass
+       non-ASCII char case conversion.
+
+2003-09-08  Mike Sperber  <mike@xemacs.org>
+
+       * symbols.c (Fvariable_binding_locus): Add, as per suggestion from
+       RMS at: http://article.gmane.org/gmane.emacs.pretest.bugs/1010
+
+2003-06-14  Ilya N. Golubev  <gin@mo.msk.ru>
+
+       * .gdbinit (pobj): fix printing of symbol name.
+
+2003-08-01  Ilya N. Golubev  <gin@mo.msk.ru>
+
+       * frame-x.c (x_layout_widgets): When resizing is about to cause
+       frame size slip, mark it for redisplay.
+
+2003-08-18  Jerry James  <james@xemacs.org>
+
+       * opaque.h: Remove unused (X)OPAQUE_MARKFUN definitions.
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/src/buffer.c b/src/buffer.c
index 8685e5a..bd44a47 100644 (file)
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -998,8 +998,8 @@ The ordering is for this frame; If second optional argument FRAME
 is provided, then the ordering is for that frame.  If the second arg
 is t, then the global ordering is returned.
 
 is provided, then the ordering is for that frame.  If the second arg
 is t, then the global ordering is returned.
 

-Note: In FSF Emacs, this function takes two arguments: BUFFER and
-VISIBLE-OK.
+Note: In FSF Emacs, this function takes the arguments in the order of
+BUFFER, VISIBLE-OK and FRAME.

 */
        (buffer, frame, visible_ok))
 {
 */
        (buffer, frame, visible_ok))
 {

diff --git a/src/data.c b/src/data.c
index b90b3ca..b2ef666 100644 (file)
--- a/src/data.c
+++ b/src/data.c
@@ -80,7 +80,7 @@ eq_with_ebola_notice (Lisp_Object obj1, Lisp_Object obj2)
       && ((CHARP (obj1) && INTP (obj2)) || (CHARP (obj2) && INTP (obj1))))
     {
       /* #### It would be really nice if this were a proper warning
       && ((CHARP (obj1) && INTP (obj2)) || (CHARP (obj2) && INTP (obj1))))
     {
       /* #### It would be really nice if this were a proper warning

-         instead of brain-dead print ro Qexternal_debugging_output.  */
+         instead of brain-dead print to Qexternal_debugging_output.  */

       write_c_string ("Comparison between integer and character is constant nil (",
                      Qexternal_debugging_output);
       Fprinc (obj1, Qexternal_debugging_output);
       write_c_string ("Comparison between integer and character is constant nil (",
                      Qexternal_debugging_output);
       Fprinc (obj1, Qexternal_debugging_output);

@@ -246,7 +246,7 @@ Return t if OBJECT is not a list.  `nil' is a list.
 }
 
 DEFUN ("true-list-p", Ftrue_list_p, 1, 1, 0, /*
 }
 
 DEFUN ("true-list-p", Ftrue_list_p, 1, 1, 0, /*

-Return t if OBJECT is a non-dotted, i.e. nil-terminated, list.
+Return t if OBJECT is an acyclic, nil-terminated (ie, not dotted), list.

 */
        (object))
 {
 */
        (object))
 {

diff --git a/src/device-x.c b/src/device-x.c
index 4bfa4b0..6fc5ff9 100644 (file)
--- a/src/device-x.c
+++ b/src/device-x.c
@@ -1057,10 +1057,14 @@ x_error_handler (Display *disp, XErrorEvent *event)
       }
 #endif /* EXTERNAL_WIDGET */
 
       }
 #endif /* EXTERNAL_WIDGET */
 

+#if 0
+      /* This ends up calling X, which isn't allowed in an X error handler
+       */

       stderr_out ("\n%s: ",
                  (STRINGP (Vinvocation_name)
                   ? (char *) XSTRING_DATA (Vinvocation_name)
                   : "xemacs"));
       stderr_out ("\n%s: ",
                  (STRINGP (Vinvocation_name)
                   ? (char *) XSTRING_DATA (Vinvocation_name)
                   : "xemacs"));

+#endif

       XmuPrintDefaultErrorMessage (disp, event, stderr);
     }
   return 0;
       XmuPrintDefaultErrorMessage (disp, event, stderr);
     }
   return 0;

diff --git a/src/elhash.c b/src/elhash.c
index b034860..0293331 100644 (file)
--- a/src/elhash.c
+++ b/src/elhash.c
@@ -809,7 +809,7 @@ Use Common Lisp style keywords to specify hash table properties.
 Keyword :test can be `eq', `eql' (default) or `equal'.
 Comparison between keys is done using this function.
 If speed is important, consider using `eq'.
 Keyword :test can be `eq', `eql' (default) or `equal'.
 Comparison between keys is done using this function.
 If speed is important, consider using `eq'.

-When storing strings in the hash table, you will likely need to use `equal'.
+When hash table keys may be strings, you will likely need to use `equal'.

 
 Keyword :size specifies the number of keys likely to be inserted.
 This number of entries can be inserted without enlarging the hash table.
 
 Keyword :size specifies the number of keys likely to be inserted.
 This number of entries can be inserted without enlarging the hash table.

diff --git a/src/event-msw.c b/src/event-msw.c
index bf87090..779f049 100644 (file)
--- a/src/event-msw.c
+++ b/src/event-msw.c
@@ -3875,7 +3875,7 @@ FROB (WM_SETHOTKEY)
 FROB (WM_GETHOTKEY)
 FROB (WM_QUERYDRAGICON)
 FROB (WM_COMPAREITEM)
 FROB (WM_GETHOTKEY)
 FROB (WM_QUERYDRAGICON)
 FROB (WM_COMPAREITEM)

-#if(WINVER >= 0x0500)
+#if(WINVER >= 0x0500) && defined(WM_GETOBJECT)

 FROB (WM_GETOBJECT)
 #endif /* WINVER >= 0x0500 */
 FROB (WM_COMPACTING)
 FROB (WM_GETOBJECT)
 #endif /* WINVER >= 0x0500 */
 FROB (WM_COMPACTING)

@@ -3957,10 +3957,18 @@ FROB (WM_MENUCHAR)
 FROB (WM_ENTERIDLE)
 #if(WINVER >= 0x0500)
 FROB (WM_MENURBUTTONUP)
 FROB (WM_ENTERIDLE)
 #if(WINVER >= 0x0500)
 FROB (WM_MENURBUTTONUP)

+#ifdef WM_MENUDRAG

 FROB (WM_MENUDRAG)
 FROB (WM_MENUDRAG)

+#endif
+#ifdef WM_MENUGETOBJECT

 FROB (WM_MENUGETOBJECT)
 FROB (WM_MENUGETOBJECT)

+#endif
+#ifdef WM_UNINITMENUPOPUP

 FROB (WM_UNINITMENUPOPUP)
 FROB (WM_UNINITMENUPOPUP)

+#endif
+#ifdef WM_MENUCOMMAND

 FROB (WM_MENUCOMMAND)
 FROB (WM_MENUCOMMAND)

+#endif

 #endif /* WINVER >= 0x0500 */
 
 
 #endif /* WINVER >= 0x0500 */
 
 

@@ -4036,7 +4044,7 @@ FROB (WM_IME_COMPOSITIONFULL)
 FROB (WM_IME_SELECT)
 FROB (WM_IME_CHAR)
 #endif /* WINVER >= 0x0400 */
 FROB (WM_IME_SELECT)
 FROB (WM_IME_CHAR)
 #endif /* WINVER >= 0x0400 */

-#if(WINVER >= 0x0500)
+#if(WINVER >= 0x0500) && defined(WM_IME_REQUEST)

 FROB (WM_IME_REQUEST)
 #endif /* WINVER >= 0x0500 */
 #if(WINVER >= 0x0400) && !defined(CYGWIN)
 FROB (WM_IME_REQUEST)
 #endif /* WINVER >= 0x0500 */
 #if(WINVER >= 0x0400) && !defined(CYGWIN)

diff --git a/src/frame-x.c b/src/frame-x.c
index f174a06..f3aaef1 100644 (file)
--- a/src/frame-x.c
+++ b/src/frame-x.c
@@ -1811,10 +1811,14 @@ x_layout_widgets (Widget w, XtPointer client_data, XtPointer call_data)
 #endif
 
   /* finally the text area */
 #endif
 
   /* finally the text area */

-  XtConfigureWidget (text, text_x, text_y,
-                    width - 2*textbord,
-                    height - text_y - 2*textbord,
-                    textbord);
+  {
+    Dimension nw = width - 2*textbord;
+    Dimension nh = height - text_y - 2*textbord;
+
+    if (nh != f->pixheight || nw != f->pixwidth)
+      MARK_FRAME_SIZE_SLIPPED (f);
+    XtConfigureWidget (text, text_x, text_y, nw, nh, textbord);
+  }

 }
 
 static void
 }
 
 static void

@@ -2744,9 +2748,11 @@ x_update_frame_external_traits (struct frame* frm, Lisp_Object name)
      Lisp_Object font = FACE_FONT (Vdefault_face, frame, Vcharset_ascii);
 
      if (!EQ (font, Vthe_null_font_instance))
      Lisp_Object font = FACE_FONT (Vdefault_face, frame, Vcharset_ascii);
 
      if (!EQ (font, Vthe_null_font_instance))

-       XtSetArg (al[ac], XtNfont,
-                (void *) FONT_INSTANCE_X_FONT (XFONT_INSTANCE (font)));
-     ac++;
+       {
+        XtSetArg (al[ac], XtNfont,
+                  (void *) FONT_INSTANCE_X_FONT (XFONT_INSTANCE (font)));
+        ac++;
+       }

    }
   else
    abort ();
    }
   else
    abort ();

diff --git a/src/opaque.h b/src/opaque.h
index 527ae6b..d308eb0 100644 (file)
--- a/src/opaque.h
+++ b/src/opaque.h
@@ -47,10 +47,8 @@ DECLARE_LRECORD (opaque, Lisp_Opaque);
 
 #define OPAQUE_SIZE(op) ((op)->size)
 #define OPAQUE_DATA(op) ((void *) ((op)->data))
 
 #define OPAQUE_SIZE(op) ((op)->size)
 #define OPAQUE_DATA(op) ((void *) ((op)->data))

-#define OPAQUE_MARKFUN(op) ((op)->markfun)

 #define XOPAQUE_SIZE(op) OPAQUE_SIZE (XOPAQUE (op))
 #define XOPAQUE_DATA(op) OPAQUE_DATA (XOPAQUE (op))
 #define XOPAQUE_SIZE(op) OPAQUE_SIZE (XOPAQUE (op))
 #define XOPAQUE_DATA(op) OPAQUE_DATA (XOPAQUE (op))

-#define XOPAQUE_MARKFUN(op) OPAQUE_MARKFUN (XOPAQUE (op))

 
 Lisp_Object make_opaque (const void *data, size_t size);
 
 
 Lisp_Object make_opaque (const void *data, size_t size);
 

diff --git a/src/regex.c b/src/regex.c
index f5897a2..06b142b 100644 (file)
--- a/src/regex.c
+++ b/src/regex.c
@@ -1135,7 +1135,7 @@ static const char *re_error_msgid[] =
    exactly that if always used MAX_FAILURE_SPACE each time we failed.
    This is a variable only so users of regex can assign to it; we never
    change it ourselves.  */
    exactly that if always used MAX_FAILURE_SPACE each time we failed.
    This is a variable only so users of regex can assign to it; we never
    change it ourselves.  */

-#if defined (MATCH_MAY_ALLOCATE)
+#if defined (MATCH_MAY_ALLOCATE) || defined (REGEX_MALLOC)

 /* 4400 was enough to cause a crash on Alpha OSF/1,
    whose default stack limit is 2mb.  */
 int re_max_failures = 20000;
 /* 4400 was enough to cause a crash on Alpha OSF/1,
    whose default stack limit is 2mb.  */
 int re_max_failures = 20000;

@@ -1591,13 +1591,6 @@ static unsigned char reg_unset_dummy;
    when we use a character as a subscript we must make it unsigned.  */
 #define TRANSLATE(d) (TRANSLATE_P (translate) ? RE_TRANSLATE (d) : (d))
 
    when we use a character as a subscript we must make it unsigned.  */
 #define TRANSLATE(d) (TRANSLATE_P (translate) ? RE_TRANSLATE (d) : (d))
 

-#ifdef MULE
-
-#define TRANSLATE_EXTENDED_UNSAFE(emch) \
-  (TRANSLATE_P (translate) && emch < 0x80 ? RE_TRANSLATE (emch) : (emch))
-
-#endif
-

 /* Macros for outputting the compiled pattern into `buffer'.  */
 
 /* If the buffer isn't allocated when it comes in, use this.  */
 /* Macros for outputting the compiled pattern into `buffer'.  */
 
 /* If the buffer isn't allocated when it comes in, use this.  */

@@ -4114,10 +4107,12 @@ re_search_2 (struct re_pattern_buffer *bufp, const char *str1,
                  {
 #ifdef MULE
                    Emchar buf_ch;
                  {
 #ifdef MULE
                    Emchar buf_ch;

+                   Bufbyte str[MAX_EMCHAR_LEN];

 
                    buf_ch = charptr_emchar (d);
                    buf_ch = RE_TRANSLATE (buf_ch);
 
                    buf_ch = charptr_emchar (d);
                    buf_ch = RE_TRANSLATE (buf_ch);

-                   if (buf_ch >= 0200 || fastmap[(unsigned char) buf_ch])
+                   set_charptr_emchar (str, buf_ch);
+                   if (buf_ch >= 0200 || fastmap[(unsigned char) *str])

                      break;
 #else
                    if (fastmap[(unsigned char)RE_TRANSLATE (*d)])
                      break;
 #else
                    if (fastmap[(unsigned char)RE_TRANSLATE (*d)])

@@ -4865,7 +4860,7 @@ re_match_2_internal (struct re_pattern_buffer *bufp, re_char *string1,
 
            REGEX_PREFETCH ();
            c = charptr_emchar ((const Bufbyte *) d);
 
            REGEX_PREFETCH ();
            c = charptr_emchar ((const Bufbyte *) d);

-           c = TRANSLATE_EXTENDED_UNSAFE (c); /* The character to match.  */
+           c = TRANSLATE (c); /* The character to match.  */

 
            if (EQ (Qt, unified_range_table_lookup (p, c, Qnil)))
              not_p = !not_p;
 
            if (EQ (Qt, unified_range_table_lookup (p, c, Qnil)))
              not_p = !not_p;

diff --git a/src/s/sol2.h b/src/s/sol2.h
index d780f91..be814d7 100644 (file)
--- a/src/s/sol2.h
+++ b/src/s/sol2.h
@@ -11,7 +11,7 @@
 #endif
 
 /* Fix understandable GCC lossage on Solaris 2.6 */
 #endif
 
 /* Fix understandable GCC lossage on Solaris 2.6 */

-#if defined(__GNUC__) && OS_RELEASE >= 56 && !defined(NOT_C_CODE)
+#if defined(__GNUC__) && OS_RELEASE >= 506 && !defined(NOT_C_CODE)

 
 /* GCC va_list munging is a little messed up */
 #define __GNUC_VA_LIST
 
 /* GCC va_list munging is a little messed up */
 #define __GNUC_VA_LIST

@@ -66,7 +66,7 @@ extern int     __xnet_getsockopt (int, int, int, void *, size_t *);
  */
 
 #undef UNEXEC
  */
 
 #undef UNEXEC

-#if OS_RELEASE < 56
+#if OS_RELEASE < 506

 #define UNEXEC "unexsol2.o"
 #else
 #define UNEXEC "unexsol2-6.o"
 #define UNEXEC "unexsol2.o"
 #else
 #define UNEXEC "unexsol2-6.o"

@@ -74,7 +74,7 @@ extern int     __xnet_getsockopt (int, int, int, void *, size_t *);
 
 #else /* C_CODE */
 
 
 #else /* C_CODE */
 

-#if OS_RELEASE <= 53
+#if OS_RELEASE <= 503

 /* Solaris 2.3 has a bug in XListFontsWithInfo.  */
 #define BROKEN_XLISTFONTSWITHINFO
 #endif
 /* Solaris 2.3 has a bug in XListFontsWithInfo.  */
 #define BROKEN_XLISTFONTSWITHINFO
 #endif

@@ -91,7 +91,7 @@ extern int     __xnet_getsockopt (int, int, int, void *, size_t *);
 #define BROKEN_SIGCHLD
 #endif
 
 #define BROKEN_SIGCHLD
 #endif
 

-#if OS_RELEASE < 55
+#if OS_RELEASE < 505

 
 #if __STDC__ == 1 && defined(__SUNPRO_C)
 #define _POSIX_C_SOURCE 1
 
 #if __STDC__ == 1 && defined(__SUNPRO_C)
 #define _POSIX_C_SOURCE 1

@@ -103,7 +103,7 @@ extern int     __xnet_getsockopt (int, int, int, void *, size_t *);
 extern void *__builtin_alloca (size_t);
 #endif /* before SunOS 5.5 */
 
 extern void *__builtin_alloca (size_t);
 #endif /* before SunOS 5.5 */
 

-#if OS_RELEASE == 55
+#if OS_RELEASE == 505

 /* The following functions were added in Solaris 2.5,
    but they forgot to add prototypes to the system header files. */
 int getpagesize (void);
 /* The following functions were added in Solaris 2.5,
    but they forgot to add prototypes to the system header files. */
 int getpagesize (void);

@@ -113,13 +113,13 @@ int usleep (unsigned int useconds);
 #endif /* SunOS 5.5 */
 
 /* 2.5 now has `random' back in libc but we don't want to use it. */
 #endif /* SunOS 5.5 */
 
 /* 2.5 now has `random' back in libc but we don't want to use it. */

-#if OS_RELEASE >= 55
+#if OS_RELEASE >= 505

 #undef HAVE_RANDOM
 /* Apparently not necessary here, and it causes 10% CPU chewage. */
 #undef BROKEN_SIGCHLD
 #endif /* >= SunOS 5.5 */
 
 #undef HAVE_RANDOM
 /* Apparently not necessary here, and it causes 10% CPU chewage. */
 #undef BROKEN_SIGCHLD
 #endif /* >= SunOS 5.5 */
 

-#if OS_RELEASE < 56
+#if OS_RELEASE < 506

 /* Missing prototypes, added in Solaris 2.6 */
 struct timeval;
 int utimes (char *file, struct timeval *tvp);
 /* Missing prototypes, added in Solaris 2.6 */
 struct timeval;
 int utimes (char *file, struct timeval *tvp);

diff --git a/src/search.c b/src/search.c
index 7c5f447..7eebe5c 100644 (file)
--- a/src/search.c
+++ b/src/search.c
@@ -1115,6 +1115,7 @@ trivial_regexp_p (Lisp_Object regexp)
     {
       switch (*s++)
        {
     {
       switch (*s++)
        {

+       /* ']' doesn't appear here because it's only special after ] */

        case '.': case '*': case '+': case '?': case '[': case '^': case '$':
          return 0;
        case '\\':
        case '.': case '*': case '+': case '?': case '[': case '^': case '$':
          return 0;
        case '\\':

@@ -1124,7 +1125,7 @@ trivial_regexp_p (Lisp_Object regexp)
            {
            case '|': case '(': case ')': case '`': case '\'': case 'b':
            case 'B': case '<': case '>': case 'w': case 'W': case 's':
            {
            case '|': case '(': case ')': case '`': case '\'': case 'b':
            case 'B': case '<': case '>': case 'w': case 'W': case 's':

-           case 'S': case '=':
+           case 'S': case '=': case '{': case '}':

 #ifdef MULE
            /* 97/2/25 jhod Added for category matches */
            case 'c': case 'C':
 #ifdef MULE
            /* 97/2/25 jhod Added for category matches */
            case 'c': case 'C':

diff --git a/src/symbols.c b/src/symbols.c
index b147805..58cf76f 100644 (file)
--- a/src/symbols.c
+++ b/src/symbols.c
@@ -3192,6 +3192,31 @@ variable chain of symbols.
   return follow_varalias_pointers (object, follow_past_lisp_magic);
 }
 
   return follow_varalias_pointers (object, follow_past_lisp_magic);
 }
 

+DEFUN ("variable-binding-locus", Fvariable_binding_locus, 1, 1, 0, /*
+Return a value indicating where VARIABLE's current binding comes from.
+If the current binding is buffer-local, the value is the current buffer.
+If the current binding is global (the default), the value is nil. 
+*/
+       (variable))
+{
+  Lisp_Object valcontents;
+
+  CHECK_SYMBOL (variable);
+  variable = Findirect_variable (variable, Qnil);
+
+  /* Make sure the current binding is actually swapped in.  */
+  find_symbol_value (variable);
+
+  valcontents = XSYMBOL (variable)->value;
+
+  if (SYMBOL_VALUE_MAGIC_P (valcontents)
+      && ((XSYMBOL_VALUE_MAGIC_TYPE (valcontents) == SYMVAL_BUFFER_LOCAL)
+         || (XSYMBOL_VALUE_MAGIC_TYPE (valcontents) == SYMVAL_SOME_BUFFER_LOCAL))
+      && (!NILP (Flocal_variable_p (variable, Fcurrent_buffer (), Qnil))))
+    return Fcurrent_buffer ();
+  else
+    return Qnil;
+}

 \f
 /************************************************************************/
 /*                            initialization                            */
 \f
 /************************************************************************/
 /*                            initialization                            */

@@ -3548,7 +3573,6 @@ syms_of_symbols (void)
   DEFSYMBOL (Qsymbol_value_in_buffer);
   DEFSYMBOL (Qsymbol_value_in_console);
   DEFSYMBOL (Qlocal_variable_p);
   DEFSYMBOL (Qsymbol_value_in_buffer);
   DEFSYMBOL (Qsymbol_value_in_console);
   DEFSYMBOL (Qlocal_variable_p);

-

   DEFSYMBOL (Qconst_integer);
   DEFSYMBOL (Qconst_boolean);
   DEFSYMBOL (Qconst_object);
   DEFSYMBOL (Qconst_integer);
   DEFSYMBOL (Qconst_boolean);
   DEFSYMBOL (Qconst_object);

@@ -3595,6 +3619,7 @@ syms_of_symbols (void)
   DEFSUBR (Fdefvaralias);
   DEFSUBR (Fvariable_alias);
   DEFSUBR (Findirect_variable);
   DEFSUBR (Fdefvaralias);
   DEFSUBR (Fvariable_alias);
   DEFSUBR (Findirect_variable);

+  DEFSUBR (Fvariable_binding_locus);

   DEFSUBR (Fdontusethis_set_symbol_value_handler);
 }
 
   DEFSUBR (Fdontusethis_set_symbol_value_handler);
 }
 

diff --git a/src/window.c b/src/window.c
index bdf7764..680c7b8 100644 (file)
--- a/src/window.c
+++ b/src/window.c
@@ -2109,9 +2109,13 @@ will automatically call `save-buffers-kill-emacs'.)
   else if (!NILP (w->vchild))
     delete_all_subwindows (XWINDOW (w->vchild));
 
   else if (!NILP (w->vchild))
     delete_all_subwindows (XWINDOW (w->vchild));
 

+  /* Warning: mark_window_as_deleted calls window_unmap_subwindows and
+     therefore redisplay, so it requires the mirror structure to be
+     correct.  We must dirty the mirror before it is called.  */
+  f->mirror_dirty = 1;
+

   mark_window_as_deleted (w);
 
   mark_window_as_deleted (w);
 

-  f->mirror_dirty = 1;

   return Qnil;
 }
 
   return Qnil;
 }
 

diff --git a/tests/ChangeLog b/tests/ChangeLog
index 0fc8e1c..fcf1415 100644 (file)
--- a/tests/ChangeLog
+++ b/tests/ChangeLog
@@ -1,3 +1,27 @@
+2004-02-02  Vin Shelton <acs@xemacs.org>
+
+       * XEmacs 21.4.15 is released
+
+2003-10-22  Vin Shelton  <acs@xemacs.org>
+
+       * automated/hash-table-tests.el: Remove debugging print
+       statements.
+
+2003-10-22  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * automated/test-harness.el: Synch to 21.5.
+
+2003-09-25  Stephen J. Turnbull  <stephen@xemacs.org>
+
+       * automated/regexp-tests.el (multiple-match): Test \{m,n\}.
+
+2003-09-09  Adrian Aichner  <adrian@xemacs.org>
+
+       * automated/test-harness.el (test-harness-from-buffer): Log
+       results when running noninteractive.
+       * automated/test-harness.el (batch-test-emacs): Remove misplaced
+       debugging code.
+

 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released
 2003-09-03  Vin Shelton <acs@xemacs.org>
 
        * XEmacs 21.4.14 is released

diff --git a/tests/automated/hash-table-tests.el b/tests/automated/hash-table-tests.el
index 1c8af88..f3465c2 100644 (file)
--- a/tests/automated/hash-table-tests.el
+++ b/tests/automated/hash-table-tests.el
@@ -103,8 +103,6 @@
 
   (let ((k-sum 0) (v-sum 0))
     (maphash #'(lambda (k v) (incf k-sum k) (incf v-sum v)) ht)
 
   (let ((k-sum 0) (v-sum 0))
     (maphash #'(lambda (k v) (incf k-sum k) (incf v-sum v)) ht)

-    (print k-sum)
-    (print v-sum)

     (Assert (= k-sum (/ (* size (- size 1)) 2)))
     (Assert (= v-sum (- k-sum))))
 
     (Assert (= k-sum (/ (* size (- size 1)) 2)))
     (Assert (= v-sum (- k-sum))))
 

diff --git a/tests/automated/regexp-tests.el b/tests/automated/regexp-tests.el
index 98fd3a9..fde7991 100644 (file)
--- a/tests/automated/regexp-tests.el
+++ b/tests/automated/regexp-tests.el
@@ -152,6 +152,89 @@
   (Assert (string-match "^\\(Ä\\)\\1$" "ÄÄ"))
   (Assert (not (string-match "^\\(Ä\\)\\1$" "Ää"))))
 
   (Assert (string-match "^\\(Ä\\)\\1$" "ÄÄ"))
   (Assert (not (string-match "^\\(Ä\\)\\1$" "Ää"))))
 

+;; multiple-match
+;; Thanks to Manfred Bartz <MBartz@xix.com>
+;; c.e.x <vn4rkkm7ouf3b5@corp.supernews.com>
+;; #### Need to do repetitions of more complex regexps
+;; #### WASH ME!
+(with-temp-buffer
+  (Assert (not (string-match "^a\\{4,4\\}$" "aaa")))
+  (Assert      (string-match "^a\\{4,4\\}$" "aaaa"))
+  (Assert (not (string-match "^a\\{4,4\\}$" "aaaaa")))
+  (Assert (not (string-match "^[a]\\{4,4\\}$" "aaa")))
+  (Assert      (string-match "^[a]\\{4,4\\}$" "aaaa"))
+  (Assert (not (string-match "^[a]\\{4,4\\}$" "aaaaa")))
+  (Assert (not (string-match "^\\(a\\)\\{4,4\\}$" "aaa")))
+  (Assert      (string-match "^\\(a\\)\\{4,4\\}$" "aaaa"))
+  (Assert (not (string-match "^\\(a\\)\\{4,4\\}$" "aaaaa")))
+  ;; Use class because repetition of single char broken in 21.5.15
+  (Assert (not (string-match "^[a]\\{3,5\\}$" "aa")))
+  (Assert      (string-match "^[a]\\{3,5\\}$" "aaa"))
+  (Assert      (string-match "^[a]\\{3,5\\}$" "aaaa"))
+  (Assert      (string-match "^[a]\\{3,5\\}$" "aaaaa"))
+  (Assert (not (string-match "^[a]\\{3,5\\}$" "aaaaaa")))
+  (insert "\
+aa
+aaa
+aaaa
+aaaaa
+aaaaaa
+baaaa
+")
+  (goto-char (point-min))
+  (forward-line 1)
+  (Assert (not (looking-at "^a\\{4,4\\}$")))
+  (forward-line 1)
+  (Assert      (looking-at "^a\\{4,4\\}$"))
+  (forward-line 1)
+  (Assert (not (looking-at "^a\\{4,4\\}$")))
+  (goto-char (point-min))
+  (forward-line 1)
+  (Assert (not (looking-at "^[a]\\{4,4\\}$")))
+  (forward-line 1)
+  (Assert      (looking-at "^[a]\\{4,4\\}$"))
+  (forward-line 1)
+  (Assert (not (looking-at "^[a]\\{4,4\\}$")))
+  (goto-char (point-min))
+  (forward-line 1)
+  (Assert (not (looking-at "^\\(a\\)\\{4,4\\}$")))
+  (forward-line 1)
+  (Assert      (looking-at "^\\(a\\)\\{4,4\\}$"))
+  (forward-line 1)
+  (Assert (not (looking-at "^\\(a\\)\\{4,4\\}$")))
+  ;; Use class because repetition of single char broken in 21.5.15
+  (goto-char (point-min))
+  (Assert (not (looking-at "^[a]\\{3,5\\}$")))
+  (forward-line 1)
+  (Assert      (looking-at "^[a]\\{3,5\\}$"))
+  (forward-line 1)
+  (Assert      (looking-at "^[a]\\{3,5\\}$"))
+  (forward-line 1)
+  (Assert      (looking-at "^[a]\\{3,5\\}$"))
+  (forward-line 1)
+  (Assert (not (looking-at "^[a]\\{3,5\\}$")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "a\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "b?a\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 31 (re-search-forward "ba\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 31 (re-search-forward "[b]a\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 31 (re-search-forward "\\(b\\)a\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "^a\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "^a\\{4,4\\}$")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "[a]\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "^[a]\\{4,4\\}")))
+  (goto-char (point-min))
+  (Assert (= 12 (re-search-forward "^[a]\\{4,4\\}$")))
+  )
+

 ;; charset, charset_not
 ;; Not called because it takes too much time.
 (defun test-regexp-charset-paranoid ()
 ;; charset, charset_not
 ;; Not called because it takes too much time.
 (defun test-regexp-charset-paranoid ()

diff --git a/tests/automated/test-harness.el b/tests/automated/test-harness.el
index 89852fc..6e8d632 100644 (file)
--- a/tests/automated/test-harness.el
+++ b/tests/automated/test-harness.el
@@ -1,8 +1,10 @@
 ;; test-harness.el --- Run Emacs Lisp test suites.
 
 ;; test-harness.el --- Run Emacs Lisp test suites.
 

-;;; Copyright (C) 1998 Free Software Foundation, Inc.
+;;; Copyright (C) 1998, 2002, 2003 Free Software Foundation, Inc.
+;;; Copyright (C) 2002 Ben Wing.

 
 ;; Author: Martin Buchholz
 
 ;; Author: Martin Buchholz

+;; Maintainer: Stephen J. Turnbull <stephen@xemacs.org>

 ;; Keywords: testing
 
 ;; This file is part of XEmacs.
 ;; Keywords: testing
 
 ;; This file is part of XEmacs.

@@ -29,22 +31,55 @@
 ;;; A test suite harness for testing XEmacs.
 ;;; The actual tests are in other files in this directory.
 ;;; Basically you just create files of emacs-lisp, and use the
 ;;; A test suite harness for testing XEmacs.
 ;;; The actual tests are in other files in this directory.
 ;;; Basically you just create files of emacs-lisp, and use the

-;;; Assert, Check-Error, and Check-Message functions to create tests.
+;;; Assert, Check-Error, Check-Message, and Check-Error-Message functions
+;;; to create tests.  See `test-harness-from-buffer' below.
+;;; Don't suppress tests just because they're due to known bugs not yet
+;;; fixed -- use the Known-Bug-Expect-Failure and
+;;; Implementation-Incomplete-Expect-Failure wrapper macros to mark them.
+;;; A lot of the tests we run push limits; suppress Ebola message with the
+;;; Ignore-Ebola wrapper macro.
+;;; 

 ;;; You run the tests using M-x test-emacs-test-file,
 ;;; or $(EMACS) -batch -l .../test-harness.el -f batch-test-emacs file ...
 ;;; which is run for you by the `make check' target in the top-level Makefile.
 
 (require 'bytecomp)
 
 ;;; You run the tests using M-x test-emacs-test-file,
 ;;; or $(EMACS) -batch -l .../test-harness.el -f batch-test-emacs file ...
 ;;; which is run for you by the `make check' target in the top-level Makefile.
 
 (require 'bytecomp)
 

+(defvar test-harness-test-compiled nil
+  "Non-nil means the test code was compiled before execution.")
+

 (defvar test-harness-verbose
   (and (not noninteractive) (> (device-baud-rate) search-slow-speed))
   "*Non-nil means print messages describing progress of emacs-tester.")
 
 (defvar test-harness-verbose
   (and (not noninteractive) (> (device-baud-rate) search-slow-speed))
   "*Non-nil means print messages describing progress of emacs-tester.")
 

+(defvar test-harness-file-results-alist nil
+  "Each element is a list (FILE SUCCESSES TESTS).
+The order is the reverse of the order in which tests are run.
+
+FILE is a string naming the test file.
+SUCCESSES is a non-negative integer, the number of successes.
+TESTS is a non-negative integer, the number of tests run.")
+
+(defvar test-harness-risk-infloops nil
+  "*Non-nil to run tests that may loop infinitely in buggy implementations.")
+

 (defvar test-harness-current-file nil)
 
 (defvar emacs-lisp-file-regexp (purecopy "\\.el\\'")
   "*Regexp which matches Emacs Lisp source files.")
 
 (defvar test-harness-current-file nil)
 
 (defvar emacs-lisp-file-regexp (purecopy "\\.el\\'")
   "*Regexp which matches Emacs Lisp source files.")
 

+(defconst test-harness-file-summary-template
+  (format "%%-%ds %%%dd of %%%dd tests successful (%%3d%%%%)."
+         (length "byte-compiler-tests.el:") ; use the longest file name
+         5
+         5)
+  "Format for summary lines printed after each file is run.")
+
+(defconst test-harness-null-summary-template
+  (format "%%-%ds             No tests run."
+         (length "byte-compiler-tests.el:")) ; use the longest file name
+  "Format for \"No tests\" lines printed after a file is run.")
+

 ;;;###autoload
 (defun test-emacs-test-file (filename)
   "Test a file of Lisp code named FILENAME.
 ;;;###autoload
 (defun test-emacs-test-file (filename)
   "Test a file of Lisp code named FILENAME.

@@ -99,7 +134,8 @@ The output file's name is made by appending `c' to the end of FILENAME."
          (setq body (cons (read buffer) body)))
       (end-of-file nil)
       (error
          (setq body (cons (read buffer) body)))
       (end-of-file nil)
       (error

-       (princ (format "Unexpected error %S reading forms from buffer\n" error-info))))
+       (princ (format "Unexpected error %S reading forms from buffer\n"
+                     error-info))))

     `(lambda ()
        (defvar passes)
        (defvar assertion-failures)
     `(lambda ()
        (defvar passes)
        (defvar assertion-failures)

@@ -130,20 +166,60 @@ The output file's name is made by appending `c' to the end of FILENAME."
 
        (trick-optimizer nil)
        (unexpected-test-suite-failure nil)
 
        (trick-optimizer nil)
        (unexpected-test-suite-failure nil)

-       (debug-on-error t))
+       (debug-on-error t)
+       (pass-stream nil))

     (with-output-to-temp-buffer "*Test-Log*"
     (with-output-to-temp-buffer "*Test-Log*"

+      (princ (format "Testing %s...\n\n" filename))
+
+      (defconst test-harness-failure-tag "FAIL")
+      (defconst test-harness-success-tag "PASS")
+
+      (defmacro Known-Bug-Expect-Failure (&rest body)
+       `(let ((test-harness-failure-tag "KNOWN BUG")
+              (test-harness-success-tag "PASS (FAILURE EXPECTED)"))
+         ,@body))
+    
+      (defmacro Implementation-Incomplete-Expect-Failure (&rest body)
+       `(let ((test-harness-failure-tag "IMPLEMENTATION INCOMPLETE")
+              (test-harness-success-tag "PASS (FAILURE EXPECTED)"))
+         ,@body))
+    
+      (defun Print-Failure (fmt &rest args)
+       (setq fmt (format "%s: %s" test-harness-failure-tag fmt))
+       (if (noninteractive) (apply #'message fmt args))
+       (princ (concat (apply #'format fmt args) "\n")))
+
+      (defun Print-Pass (fmt &rest args)
+       (setq fmt (format "%s: %s" test-harness-success-tag fmt))
+       (and test-harness-verbose
+            (princ (concat (apply #'format fmt args) "\n"))))
+
+      (defun Print-Skip (test reason &optional fmt &rest args)
+       (setq fmt (concat "SKIP: %S BECAUSE %S" fmt))
+       (princ (concat (apply #'format fmt test reason args) "\n")))
+
+      (defmacro Skip-Test-Unless (condition reason description &rest body)
+       "Unless CONDITION is satisfied, skip test BODY.
+REASON is a description of the condition failure, and must be unique (it
+is used as a hash key).  DESCRIPTION describes the tests that were skipped.
+BODY is a sequence of expressions and may contain several tests."
+       `(if (not ,condition)
+            (let ((count (gethash ,reason skipped-test-reasons)))
+              (puthash ,reason (if (null count) 1 (1+ count))
+                       skipped-test-reasons)
+              (Print-Skip ,description ,reason))
+          ,@body))

 
       (defmacro Assert (assertion)
        `(condition-case error-info
             (progn
               (assert ,assertion)
 
       (defmacro Assert (assertion)
        `(condition-case error-info
             (progn
               (assert ,assertion)

-              (princ (format "PASS: %S" (quote ,assertion)))
-              (terpri)
+              (Print-Pass "%S" (quote ,assertion))

               (incf passes))
           (cl-assertion-failed
               (incf passes))
           (cl-assertion-failed

-           (princ (format "FAIL: Assertion failed: %S\n" (quote ,assertion)))
+           (Print-Failure "Assertion failed: %S" (quote ,assertion))

            (incf assertion-failures))
            (incf assertion-failures))

-          (t (princ (format "FAIL: %S ==> error: %S\n" (quote ,assertion) error-info))
+          (t (Print-Failure "%S ==> error: %S" (quote ,assertion) error-info)

              (incf other-failures)
              )))
 
              (incf other-failures)
              )))
 

@@ -153,60 +229,52 @@ The output file's name is made by appending `c' to the end of FILENAME."
          `(condition-case error-info
               (progn
                 (setq trick-optimizer (progn ,@body))
          `(condition-case error-info
               (progn
                 (setq trick-optimizer (progn ,@body))

-                (princ (format "FAIL: %S executed successfully, but expected error %S\n"
+                (Print-Failure "%S executed successfully, but expected error %S"

                                ,quoted-body
                                ,quoted-body

-                               ',expected-error))
+                               ',expected-error)

                 (incf no-error-failures))
             (,expected-error
                 (incf no-error-failures))
             (,expected-error

-             (princ (format "PASS: %S ==> error %S, as expected\n"
-                            ,quoted-body ',expected-error))
+             (Print-Pass "%S ==> error %S, as expected"
+                         ,quoted-body ',expected-error)

              (incf passes))
             (error
              (incf passes))
             (error

-             (princ (format "FAIL: %S ==> expected error %S, got error %S instead\n"
-                            ,quoted-body ',expected-error error-info))
+             (Print-Failure "%S ==> expected error %S, got error %S instead"
+                            ,quoted-body ',expected-error error-info)

              (incf wrong-error-failures)))))
 
              (incf wrong-error-failures)))))
 

-      (defmacro Check-Error-Message (expected-error expected-error-regexp &rest body)
+      (defmacro Check-Error-Message (expected-error expected-error-regexp
+                                                   &rest body)

        (let ((quoted-body (if (= 1 (length body))
                               `(quote ,(car body)) `(quote (progn ,@body)))))
          `(condition-case error-info
               (progn
                 (setq trick-optimizer (progn ,@body))
        (let ((quoted-body (if (= 1 (length body))
                               `(quote ,(car body)) `(quote (progn ,@body)))))
          `(condition-case error-info
               (progn
                 (setq trick-optimizer (progn ,@body))

-                (princ (format "FAIL: %S executed successfully, but expected error %S\n"
-                               ,quoted-body
-                               ',expected-error))
+                (Print-Failure "%S executed successfully, but expected error %S"
+                               ,quoted-body ',expected-error)

                 (incf no-error-failures))
             (,expected-error
              (let ((error-message (second error-info)))
                (if (string-match ,expected-error-regexp error-message)
                    (progn
                 (incf no-error-failures))
             (,expected-error
              (let ((error-message (second error-info)))
                (if (string-match ,expected-error-regexp error-message)
                    (progn

-                     (princ (format "PASS: %S ==> error %S %S, as expected\n"
-                                    ,quoted-body error-message ',expected-error))
+                     (Print-Pass "%S ==> error %S %S, as expected"
+                                 ,quoted-body error-message ',expected-error)

                      (incf passes))
                      (incf passes))

-                 (princ (format "FAIL: %S ==> got error %S as expected, but error message %S did not match regexp %S\n"
-                                ,quoted-body ',expected-error error-message ,expected-error-regexp))
+                 (Print-Failure "%S ==> got error %S as expected, but error message %S did not match regexp %S"
+                                ,quoted-body ',expected-error error-message ,expected-error-regexp)

                  (incf wrong-error-failures))))
             (error
                  (incf wrong-error-failures))))
             (error

-             (princ (format "FAIL: %S ==> expected error %S, got error %S instead\n"
-                            ,quoted-body ',expected-error error-info))
+             (Print-Failure "%S ==> expected error %S, got error %S instead"
+                            ,quoted-body ',expected-error error-info)

              (incf wrong-error-failures)))))
 
              (incf wrong-error-failures)))))
 

-      (defun Print-Skip (test reason &optional fmt &rest args)
-       (setq fmt (concat "SKIP: %S.  REASON: %S" fmt))
-       (princ (concat (apply #'format fmt test reason args) "\n")))
-

 
       (defmacro Check-Message (expected-message-regexp &rest body)
 
       (defmacro Check-Message (expected-message-regexp &rest body)

-       (if (not (fboundp 'defadvice))
-           ;; #### This whole thing should go inside a macro Skip-Test
-           (let* ((reason "advice unavailable")
-                  (count (gethash reason skipped-test-reasons)))
-             ;(message "%S: %S" reason count)
-             (puthash reason (if (null count) 1 (1+ count))
-                      skipped-test-reasons)
-             `(Print-Skip ,expected-message-regexp ,reason))
+       (Skip-Test-Unless (fboundp 'defadvice)
+                         "can't defadvice"
+                         expected-message-regexp

          (let ((quoted-body (if (= 1 (length body))
          (let ((quoted-body (if (= 1 (length body))

-                                `(quote ,(car body)) `(quote (progn ,@body)))))
+                                `(quote ,(car body))
+                              `(quote (progn ,@body)))))

            `(let ((messages ""))
               (defadvice message (around collect activate)
                 (defvar messages)
            `(let ((messages ""))
               (defadvice message (around collect activate)
                 (defvar messages)

@@ -218,15 +286,16 @@ The output file's name is made by appending `c' to the end of FILENAME."
                     (setq trick-optimizer (progn ,@body))
                     (if (string-match ,expected-message-regexp messages)
                         (progn
                     (setq trick-optimizer (progn ,@body))
                     (if (string-match ,expected-message-regexp messages)
                         (progn

-                          (princ (format "PASS: %S ==> value %S, message %S, matching %S, as expected\n"
-                                         ,quoted-body trick-optimizer messages ',expected-message-regexp))
+                          (Print-Pass "%S ==> value %S, message %S, matching %S, as expected"
+                                      ,quoted-body trick-optimizer messages ',expected-message-regexp)

                           (incf passes))
                           (incf passes))

-                      (princ (format "FAIL: %S ==> value %S, message %S, NOT matching expected %S\n"
-                                     ,quoted-body  trick-optimizer messages ',expected-message-regexp))
+                      (Print-Failure "%S ==> value %S, message %S, NOT matching expected %S"
+                                     ,quoted-body  trick-optimizer messages
+                                     ',expected-message-regexp)

                       (incf missing-message-failures)))
                 (error
                       (incf missing-message-failures)))
                 (error

-                 (princ (format "FAIL: %S ==> unexpected error %S\n"
-                                ,quoted-body error-info))
+                 (Print-Failure "%S ==> unexpected error %S"
+                                ,quoted-body error-info)

                  (incf other-failures)))
               (ad-unadvise 'message)))))
 
                  (incf other-failures)))
               (ad-unadvise 'message)))))
 

@@ -251,7 +320,8 @@ The output file's name is made by appending `c' to the end of FILENAME."
         (message "Test suite execution aborted." error-info)
         ))
       (princ "\nTesting Compiled Lisp\n\n")
         (message "Test suite execution aborted." error-info)
         ))
       (princ "\nTesting Compiled Lisp\n\n")

-      (let (code)
+      (let (code
+           (test-harness-test-compiled t))

        (condition-case error-info
            (setq code
                  ;; our lisp code is often intentionally dubious,
        (condition-case error-info
            (setq code
                  ;; our lisp code is often intentionally dubious,

@@ -269,7 +339,7 @@ The output file's name is made by appending `c' to the end of FILENAME."
           (message "Unexpected error %S while executing byte-compiled code." error-info)
           (message "Test suite execution aborted." error-info)
           )))
           (message "Unexpected error %S while executing byte-compiled code." error-info)
           (message "Test suite execution aborted." error-info)
           )))

-      (princ "\nSUMMARY:\n")
+      (princ (format "\nSUMMARY for %s:\n" filename))

       (princ (format "\t%5d passes\n" passes))
       (princ (format "\t%5d assertion failures\n" assertion-failures))
       (princ (format "\t%5d errors that should have been generated, but weren't\n" no-error-failures))
       (princ (format "\t%5d passes\n" passes))
       (princ (format "\t%5d assertion failures\n" assertion-failures))
       (princ (format "\t%5d errors that should have been generated, but weren't\n" no-error-failures))

@@ -285,14 +355,16 @@ The output file's name is made by appending `c' to the end of FILENAME."
             (basename (file-name-nondirectory filename))
             (summary-msg
              (if (> total 0)
             (basename (file-name-nondirectory filename))
             (summary-msg
              (if (> total 0)

-                 (format "%s: %d of %d (%d%%) tests successful."
-                         basename passes total (/ (* 100 passes) total))
-               (format "%s: No tests run" basename)))
+                 (format test-harness-file-summary-template
+                         (concat basename ":")
+                         passes total (/ (* 100 passes) total))
+               (format test-harness-null-summary-template
+                       (concat basename ":"))))

             (reasons ""))
        (maphash (lambda (key value)
                   (setq reasons
                         (concat reasons
             (reasons ""))
        (maphash (lambda (key value)
                   (setq reasons
                         (concat reasons

-                                (format "\n    %d tests skipped because %s"
+                                (format "\n    %d tests skipped because %s."

                                         value key))))
                 skipped-test-reasons)
        (when (> (length reasons) 1)
                                         value key))))
                 skipped-test-reasons)
        (when (> (length reasons) 1)

@@ -300,6 +372,9 @@ The output file's name is made by appending `c' to the end of FILENAME."
     Probably XEmacs cannot find your installed packages.  Set EMACSPACKAGEPATH
     to the package hierarchy root or configure with --package-path to enable
     the skipped tests.")))
     Probably XEmacs cannot find your installed packages.  Set EMACSPACKAGEPATH
     to the package hierarchy root or configure with --package-path to enable
     the skipped tests.")))

+       (setq test-harness-file-results-alist
+             (cons (list filename passes total)
+                   test-harness-file-results-alist))

        (message "%s" summary-msg))
       (when unexpected-test-suite-failure
        (message "Test suite execution failed unexpectedly."))
        (message "%s" summary-msg))
       (when unexpected-test-suite-failure
        (message "Test suite execution failed unexpectedly."))

@@ -309,6 +384,9 @@ The output file's name is made by appending `c' to the end of FILENAME."
       (fmakunbound 'Check-Error-Message)
       (fmakunbound 'Ignore-Ebola)
       (fmakunbound 'Int-to-Marker)
       (fmakunbound 'Check-Error-Message)
       (fmakunbound 'Ignore-Ebola)
       (fmakunbound 'Int-to-Marker)

+      (and noninteractive
+          (message "%s" (buffer-substring-no-properties
+                         nil nil "*Test-Log*")))

       )))
 
 (defvar test-harness-results-point-max nil)
       )))
 
 (defvar test-harness-results-point-max nil)

@@ -388,8 +466,45 @@ For example, invoke \"xemacs -batch -f batch-test-emacs tests/*.el\""
                  (setq error t))))
        (or (batch-test-emacs-1 file)
            (setq error t))))
                  (setq error t))))
        (or (batch-test-emacs-1 file)
            (setq error t))))

-    ;;(message "%s" (buffer-string nil nil "*Test-Log*"))
-    (message "Done")
+    (let ((namelen 0)
+         (succlen 0)
+         (testlen 0)
+         (results test-harness-file-results-alist))
+      ;; compute maximum lengths of variable components of report
+      ;; probably should just use (length "byte-compiler-tests.el")
+      ;; and 5-place sizes -- this will also work for the file-by-file
+      ;; printing when Adrian's kludge gets reverted
+      (flet ((print-width (i)
+              (let ((x 10) (y 1))
+                (while (>= i x)
+                  (setq x (* 10 x) y (1+ y)))
+                y)))
+       (while results
+         (let* ((head (car results))
+                (nn (length (file-name-nondirectory (first head))))
+                (ss (print-width (second head)))
+                (tt (print-width (third head))))
+           (when (> nn namelen) (setq namelen nn))
+           (when (> ss succlen) (setq succlen ss))
+           (when (> tt testlen) (setq testlen tt)))
+         (setq results (cdr results))))
+      ;; create format and print
+      (let ((results (reverse test-harness-file-results-alist)))
+       (while results
+         (let* ((head (car results))
+                (basename (file-name-nondirectory (first head)))
+                (nsucc (second head))
+                (ntest (third head)))
+           (if (> ntest 0)
+               (message test-harness-file-summary-template
+                        (concat basename ":")
+                        nsucc
+                        ntest
+                        (/ (* 100 nsucc) ntest))
+             (message test-harness-null-summary-template
+                      (concat basename ":")))
+           (setq results (cdr results))))))
+    (message "\nDone")

     (kill-emacs (if error 1 0))))
 
 (provide 'test-harness)
     (kill-emacs (if error 1 0))))
 
 (provide 'test-harness)

diff --git a/version.sh b/version.sh
index 7faed11..03a4ee2 100644 (file)
--- a/version.sh
+++ b/version.sh
@@ -2,8 +2,8 @@
 emacs_is_beta=
 emacs_major_version=21
 emacs_minor_version=4
 emacs_is_beta=
 emacs_major_version=21
 emacs_minor_version=4

-emacs_beta_version=14
-xemacs_codename="Reasonable Discussion"
+emacs_beta_version=15
+xemacs_codename="Security Through Obscurity"

 emacs_kit_version=
 infodock_major_version=4
 infodock_minor_version=0
 emacs_kit_version=
 infodock_major_version=4
 infodock_minor_version=0