+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.
+
+@emph{NOTE}: For detailed information about how the package
+hierarchies work, @xref{Package Overview,,,lispref, the XEmacs Lisp
+Reference Manual}.
+
+@node Q2.1.2, Q2.1.3, Q2.1.1, Installation
+@unnumberedsubsec Q2.1.2: Can I install the packages individually?
+
+Yes, you can download individual packages from the FTP site (@pxref{Q2.1.1}). Since packages are automatically noticed at startup, you just have to put them in the right place.
+
+Note: If you are upgrading packages already installed, it's best to
+remove the old package first (@pxref{Q2.1.4}).
+
+For example if we are installing the @samp{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
+@end example
+
+Or if you have GNU tar, the last step can be:
+
+@example
+ 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 @samp{mule-packages}
+hierarchy, i.e. for the @samp{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
+@end example
+
+Or if you have GNU tar, the last step can be:
+
+@example
+ tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
+@end example
+
+@node Q2.1.3, Q2.1.4, Q2.1.2, Installation
+@unnumberedsubsec Q2.1.3: Can I install the packages automatically?
+
+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:
+
+@example
+ efs - To fetch the files from the FTP site or mirrors.
+ xemacs-base - Needed by efs.
+@end example
+
+and optionally:
+
+@example
+ mailcrypt - For PGP verification of the package-index file.
+@end example
+
+After installing these by hand, fire up XEmacs and follow these
+steps.
+
+@enumerate
+@item
+Choose a download site.
+@itemize @bullet
+@item
+via menu: Tools -> Packages -> Set Download Site
+@item
+via keyb: M-x customize-variable RET package-get-remote RET
+(put in the details of remote host and directory)
+@end itemize
+
+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
+
+@item
+Obtain a list of packages and display the list in a buffer named
+"*Packages*".
+@itemize @bullet
+@item
+menu: Tools -> Packages -> List & Install
+@item
+keyb: M-x pui-list-packages RET
+@end itemize
+
+XEmacs will now connect to the remote site and download the
+latest package-index file.
+
+The resulting buffer, "*Packages*" has brief instructions at the
+end of the buffer.
+
+@item
+Choose the packages you wish to install.
+@itemize @bullet
+@item
+mouse: Click button 2 on the package name.
+@item
+keyb: RET on the package name
+@end itemize
+
+@item
+Make sure you have everything you need.
+@itemize @bullet
+@item
+menu: Packages -> Add Required
+@item
+keyb: r
+@end itemize
+
+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.
+
+For novices and gurus alike, this step can save your bacon.
+It's easy to forget to install a critical package.
+
+@item
+Download and install the packages.
+@itemize @bullet
+@item
+menu: Packages -> Install/Remove Selected
+@item
+keyb: x
+@end itemize
+@end enumerate
+
+@node Q2.1.4, Q2.1.5, Q2.1.3, Installation
+@unnumberedsubsec Q2.1.4: Can I upgrade or remove packages?
+
+As 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 belong to the
+package. M-x package-admin-delete-binary-package RET can be used to
+remove a package using this file.
+
+Note that the interactive package tools included with XEmacs already do
+this for you.
+
+@node Q2.1.5, Q2.1.6, Q2.1.4, Installation
+@unnumberedsubsec Q2.1.5: Which packages to install?
+
+Unless you are an advanced user, just install everything.
+
+If you really want to install only what's absolutely needed, a good
+minimal set of packages for XEmacs-latin1 would be
+
+@example
+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
+@end example
+
+If you are using the XEmacs package tools, don't forget to do:
+
+@example
+ Packages -> Add Required
+@end example
+
+To make sure you have everything that the packages you have chosen to
+install need.
+
+@xref{Q1.7.2}, for a description of the various packages.
+
+@node Q2.1.6, Q2.1.7, Q2.1.5, Installation
+@unnumberedsubsec Q2.1.6: Can you describe the package location process in more detail?
+
+On startup XEmacs looks for packages in so-called package hierarchies.
+Normally, there are three system wide hierarchies, like this:
+
+@example
+$prefix/lib/xemacs/xemacs-packages/
+ Normal packages go here.
+
+$prefix/lib/xemacs/mule-packages/
+ Mule packages go here and are only searched by MULE-enabled XEmacsen.
+
+$prefix/lib/xemacs/site-packages/
+ Local and 3rd party packages go here.
+@end example
+
+This is what you get when you untar the SUMO tarballs under
+@file{$prefix/lib/xemacs}.
+
+@file{$prefix} is specified using the @samp{--prefix} parameter to
+@file{configure}, and defaults to @file{usr/local}.
+
+If the package path is not explicitly specified, XEmacs looks for the
+package directory @file{xemacs-packages} (and @file{mule-packages} and
+@file{site-packages}) first under @samp{~/.xemacs}, then for a sister
+directory @file{lib/xemacs-VERSION} of the directory in which the
+XEmacs executable is located, then for a sister directory
+@file{lib/xemacs}. The XEmacs executable (under Unix at least) is
+installed by default in @file{/usr/local/bin}; this explains why
+XEmacs in its default installation will find packages that you put
+under @file{/usr/local/lib/xemacs}.
+
+You can specify where exactly XEmacs looks for packages by using the
+@samp{--with-package-prefix} or @samp{--with-package-path} parameters to
+@file{configure} (or the equivalent settings in @file{config.inc}, under
+Windows), or setting the @samp{EMACSPACKAGEPATH} environment variable
+(which has the same format as @samp{--with-package-path}). @xref{Q2.1.1}.
+
+See @file{configure.usage} for more info about the format of these
+@file{configure} parameters.
+
+In addition to the system wide packages, each user can have his own
+packages installed under @file{~/.xemacs/}. If you want to install
+packages there using the interactive tools, you need to set
+@code{package-get-install-to-user-init-directory} to @code{t}.
+
+The site-packages hierarchy replaces the old @file{site-lisp}
+directory. XEmacs no longer looks into a @file{site-lisp} directly by
+default. A good place to put @file{site-start.el} would be in
+@file{$prefix/lib/xemacs/site-packages/lisp/}.
+
+@node Q2.1.7, Q2.2.1, Q2.1.6, Installation
+@unnumberedsubsec Q2.1.7: EFS fails with "500 AUTH not understood" (NEW)
+
+A typical error: FTP Error: USER request failed; 500 AUTH not understood.
+
+Thanks to giacomo boffi @email{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.
+
+@unnumberedsec 2.2: Unix/Mac OS X Installation (Also Relevant to Cygwin, MinGW)
+
+@node Q2.2.1, Q2.2.2, Q2.1.7, Installation
+@unnumberedsubsec Q2.2.1: Libraries in non-standard locations
+
+If your libraries are in a non-standard location, you can specify the location
+using the following flags to @file{configure}. Under 21.4 or earlier:
+
+@example
+--site-libraries=WHATEVER
+--site-includes=WHATEVER
+@end example
+
+Under 21.5 or later:
+
+@example
+--with-site-libraries=WHATEVER
+--with-site-includes=WHATEVER
+@end example
+
+If you have multiple paths to specify, use the following syntax:
+
+@example
+--site-libraries='/path/one /path/two /path/etc'
+@end example
+
+If the libraries and headers reside in the directories @samp{lib} and
+@samp{include} of a common root (say @samp{/sw}) then both can be
+specified with a single option:
+
+@example
+--site-prefixes=WHATEVER
+@end example
+
+or for 21.5:
+
+@example
+--with-site-prefixes=WHATEVER
+@end example
+
+@node Q2.2.2, Q2.2.3, Q2.2.1, Installation
+@unnumberedsubsec Q2.2.2: Why can't I strip XEmacs?
+
+@email{cognot@@fronsac.ensg.u-nancy.fr, Richard Cognot} writes:
+
+@quotation
+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 @file{not} part of the binary
+kits).
+@end quotation
+
+@email{nat@@nataa.fr.eu.org, Nat Makarevitch} writes:
+
+@quotation
+Here is the trick:
+
+@enumerate
+@item
+[ ./configure; make ]
+
+@item
+rm src/xemacs
+
+@item
+strip src/temacs
+
+@item
+make
+
+@item
+cp src/xemacs /usr/local/bin/xemacs
+
+@item
+cp lib-src/DOC-19.16-XEmacs
+@iftex
+\ @*
+@end iftex
+/usr/local/lib/xemacs-19.16/i586-unknown-linuxaout
+@end enumerate
+@end quotation
+
+@node Q2.2.3, Q2.3.1, Q2.2.2, Installation
+@unnumberedsubsec Q2.2.3: X11/bitmaps/gray (or other X11-related file) not found.
+
+The X11R6 distribution was monolithic, but the X11R7 distribution is
+much more modular. Many OS distributions omit these bitmaps (assuming
+nobody uses them, evidently). Your OS distribution should have a
+developer's package containing these files, probably with a name
+containing the string "bitmap". Known package names (you may need to
+add an extension such as .deb or .rpm) include x11/xbitmaps (Ubuntu)
+and xorg-x11-xbitmaps (Fedora Core 5).
+
+@unnumberedsec 2.3: Windows Installation (Windows, Cygwin, MinGW)
+
+@node Q2.3.1, Q2.3.2, Q2.2.3, Installation
+@unnumberedsubsec Q2.3.1: 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. @xref{Q1.2.5, What are Cygwin
+and MinGW, and do I need them to run XEmacs?}, for more information.
+
+A third way is the MinGW port. It uses the Cygwin environment to
+build but does not require it at runtime. @xref{Q1.2.5, What are
+Cygwin and MinGW, and do I need them to run XEmacs?}, 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.)
+
+@node Q2.3.2, Q2.3.3, Q2.3.1, Installation
+@unnumberedsubsec Q2.3.2: 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. @xref{Q1.2.5, What are Cygwin
+and MinGW, and do I need them to run XEmacs?}, for more information on
+Cygwin and MinGW.
+
+@node Q2.3.3, Q2.3.4, Q2.3.2, Installation
+@unnumberedsubsec Q2.3.3: How do I compile the native port?
+
+Please read the file @file{nt/README} in the XEmacs distribution, which
+contains the full description.
+
+@node Q2.3.4, Q2.3.5, Q2.3.3, Installation
+@unnumberedsubsec Q2.3.4: What do I need for Cygwin?
+
+You can find the Cygwin tools and compiler at:
+
+@uref{http://www.cygwin.com/}
+
+Click on the @samp{Install or update now!} link, which will download a
+file @file{setup.exe}, which you can use to download everything
+else. (You will need to pick a mirror site; @samp{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. You can also get X Windows here, if you
+want to compile under X.
+
+If you want to compile without X, you will need the @file{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 @file{cygXpm-noX4.dll}.
+
+@node Q2.3.5, Q2.3.6, Q2.3.4, Installation
+@unnumberedsubsec Q2.3.5: How do I compile under Cygwin?
+
+Similar as on Unix; use the usual `configure' and `make' process.
+Some problems to watch out for:
+
+@itemize @bullet
+@item
+make sure HOME is set. This controls where you
+@file{init.el} file comes from;
+
+@item
+@samp{CYGWIN} needs to be set to @samp{tty} for process support to work;
+
+@item
+picking up some other grep or other UNIX-like tools can kill configure;
+
+@item
+static heap too small, adjust @file{src/sheap-adjust.h} to a more positive
+number;
+
+@item
+(Unconfirmed) The Cygwin version doesn't understand
+@file{//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;
+
+@item
+If you're building @strong{WITHOUT} X11, don't forget to change symlinks
+@file{/usr/lib/libXpm.a} and @file{/usr/lib/libXpm.dll.a} to point to
+the non-X versions of these libraries. By default they point to the X
+versions. So:
+
+@example
+/usr/lib/libXpm.a -> /usr/lib/libXpm-noX.a
+/usr/lib/libXpm.dll.a -> /usr/lib/libXpm-noX.dll.a
+@end example
+
+(This advice may now be obsolete because of the availability of the
+cygXpm-noX4.dll package from Cygwin. Send confirmation to
+@email{faq@@xemacs.org}.)
+
+@item
+Other problems are listed in the @file{PROBLEMS} file, in the top-level
+directory of the XEmacs sources.
+
+@end itemize
+
+
+@node Q2.3.6, Q2.3.7, Q2.3.5, Installation
+@unnumberedsubsec Q2.3.6: How do I compile using MinGW (aka @samp{the -mno-cygwin flag to gcc})?
+
+Similar to the method for Unix. Things to remember:
+
+@itemize @bullet
+@item
+Specify the target host on the command line for @file{./configure}, e.g.
+@samp{./configure i586-pc-mingw32}.
+
+@item
+Be sure that your build directory is mounted such that it has the
+same path either as a cygwin path (@file{/build/xemacs}) or as a Windows
+path (@file{c:\build\xemacs}).
+
+@item
+Build @samp{gcc -mno-cygwin} versions of the extra libs, i.e. @file{libpng},
+@file{compface}, etc.
+
+@item
+Specify the target location of the extra libs on the command line
+to @file{configure}, e.g.for 21.4 or earlier
+@samp{./configure --site-prefixes=/build/libs i586-pc-mingw32} and for
+21.5 or later
+@samp{./configure --with-site-prefixes=/build/libs i586-pc-mingw32}.
+@end itemize
+
+@node Q2.3.7, Q2.3.8, Q2.3.6, Installation
+@unnumberedsubsec Q2.3.7: How do I compile with X support?
+
+To compile under Cygwin, all you need to do is install XFree86, which
+is available as part of the standard Cygwin installation.
+@uref{http://www.cygwin.com/}. Once installed, @file{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
+@file{nt/README} in some detail. Basically, you need to get X11
+libraries from @uref{http://ftp.x.org}, and compile them. If the
+precompiled versions are available somewhere, we don't know of it.
+
+@node Q2.3.8, Q2.4.1, Q2.3.7, Installation
+@unnumberedsubsec Q2.3.8: 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
+
+@example
+This application has failed to start because cygXpm-noX4.dll was not found.
+Re-installing the application may fix this problem.
+@end example
+
+Andy Piper <andy@@xemacs.org> sez:
+
+@example
+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.
+@end example
+
+Ie, reinstalling XEmacs won't help because it is not part of the XEmacs
+distribution.
+
+@unnumberedsec 2.4: General Troubleshooting
+
+@node Q2.4.1, Q2.4.2, Q2.3.8, Installation
+@unnumberedsubsec Q2.4.1: How do I deal with bugs or with problems building, installing, or running?
+
+The file @file{PROBLEMS} contains information on many common problems that
+occur in building, installing and running XEmacs.
+
+Reports of bugs in XEmacs should be sent to
+@email{xemacs-beta@@xemacs.org}. You can also post to the newsgroup
+comp.emacs.xemacs (or equivalentlt, send to the mailing list
+@email{xemacs@@xemacs.org}), but it is less likely that the developers
+will see it in a timely fashion. @xref{Bugs,,, xemacs, the XEmacs
+User's Manual}, for more information on how to report bugs.
+@xref{Q1.4.2}, for more information on mailing lists relating to
+XEmacs.
+
+There are three ways to read the Bugs section.
+
+@enumerate
+@item
+In a printed copy of the XEmacs manual.
+
+@item
+With Info. First, start XEmacs. From the menu, select
+@samp{Help->Info (Online Docs)->Info Contents} to enter Info, then
+click on @samp{XEmacs}, then on @samp{Bugs}. Or, use the keyboard: do
+@kbd{C-h i} to enter Info, then @kbd{m XEmacs RET} to get to the Emacs
+manual, then @kbd{m Bugs RET} to get to the section on bugs. Or use
+standalone Info in a like manner. (Standalone Info is part of the
+Texinfo distribution, not part of the XEmacs distribution.)
+
+@item
+By hand. Do
+@example
+cat info/xemacs* | more "+/^File: xemacs.info, Node: Bugs,"
+@end example
+@end enumerate
+
+@node Q2.4.2, Q2.4.3, Q2.4.1, Installation
+@unnumberedsubsec Q2.4.2: 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 @code{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 @kbd{M-x recover-file} to retrieve the
+auto-saved version of the file.
+
+You can use the command @kbd{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 @kbd{M-x report-emacs-bug} (or by
+selecting @samp{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 @email{xemacs-beta@@xemacs.org}. @emph{MAKE SURE} to include
+the output from the crash, especially including the Lisp backtrace, as
+well as the XEmacs configuration from @kbd{M-x describe-installation}
+(or equivalently, the file @file{Installation} in the top of the build
+tree). Note that the developers do @emph{not} usually follow
+@samp{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 and Mac OS
+X, you need to locate the core file (it's called @file{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:
+
+@example
+gdb `which xemacs` core
+@end example
+
+and then issue the command @samp{where} to get the stack backtrace. You
+might have to use @code{dbx} or some similar debugger in place of
+@code{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 or the stack trace
+from gdb is garbage, in which case you're out of luck unless you can
+reproduce the bug. A nonexistent core file can happen in some
+circumstances on some operating systems, depending on what exactly
+triggered the crash. It's also possible, however, that your limits
+are set to turn them off. You may be able to reenable them using a
+command like @samp{unlimit coredumpsize} or @samp{ulimit -c}. (To find
+out how your limits are set, use the command @samp{limit}.) However, if
+you didn't explicitly set your limits this way, go complain to your
+system administrator and tell him not to disable core files by
+default.
+
+A garbaged stack trace can happen for various reasons. Some versions
+of gdb are broken on certain operating systems and aren't able to read
+the core file. It's also possible that the stack got overwritten
+during the crash. A very simple reason, however, is that your version
+of XEmacs was compiled without debugging information or had the
+debugging information stripped. A compilation with optimization can
+also result in partly or completely garbaged stack trace. In such
+cases, you will need to recompile XEmacs with debugging information
+and without optimization; @xref{Q2.4.4, How to debug an XEmacs problem
+with a debugger}. Note also that core files currently don't work at
+all under Cygwin, and the only way to get a backtrace is to run XEmacs
+from gdb.
+
+If you cannot get a backtrace from the core dump, but can reproduce
+the problem, try running XEmacs under gdb. The goal is to get clean C
+and Lisp backtraces and submit a bug report including full
+configuration information as described above, as this will greatly
+assist in the process of tracking down the bug. However, even partial
+information is better than none. The process of getting backtraces
+from gdb is described in detail in @ref{Q2.4.4, How to debug an XEmacs
+problem 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 @samp{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:
+
+@enumerate
+@item
+Report @strong{all} of the information output by XEmacs during the
+crash.
+
+@item
+You mention what O/S and Hardware you are running XEmacs on.
+
+@item
+What version of XEmacs you are running.
+
+@item
+What build options you are using.
+
+@item
+If the problem is related to graphics and you are running Unix or Mac
+OS X, we will also need to know what version of the X Window System
+you are running, and what window manager you are using.
+
+@item
+If the problem happened on a TTY, please include the terminal type.
+
+@item
+Try very hard to get both C and Lisp backtraces, as described above.
+@end enumerate
+
+Much of the information above is automatically generated by @kbd{M-x
+report-emacs-bug}. Even more, and often useful, information can be
+generated by redirecting the output of @code{make} and @code{make check}
+to a file (@file{beta.err} is the default used by @code{build-report}),
+and executing @kbd{M-x build-report}.
+
+
+@node Q2.4.3, Q2.4.4, Q2.4.2, Installation
+@unnumberedsubsec Q2.4.3: XEmacs crashes and I compiled it myself.
+
+There have been a variety of reports of crashes due to compilers with
+buggy optimizers. If you are compiling with optimization, consider
+turning it off (@pxref{Q2.4.4, How to debug an XEmacs problem with a
+debugger}) and recompiling.
+
+Please see the @file{PROBLEMS} file that comes with XEmacs (it's in
+the top-level source directory) to read what it says about your
+platform.
+
+If you compiled XEmacs 21.4 or ealier using @samp{--use-union-type}, or
+21.5 or later using @samp{--enable-union-type} (or in either case used
+the option @samp{USE_UNION_TYPE} in @file{config.inc} under Windows),
+try recompiling again without it. The union type has been known to
+trigger compiler errors in a number of cases.
+
+@node Q2.4.4, Q2.4.5, Q2.4.3, Installation
+@unnumberedsubsec Q2.4.4: 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:
+
+@itemize @bullet
+@item
+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 @samp{-g -O0} --
+that's an "oh" followed by a zero), and with the configure options
+@samp{--debug=yes} and @samp{--error-checking=all}
+(@samp{--enable-debug=yes} and @samp{--enable-error-checking=all} on
+XEmacs 21.5 or later). 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. The way to control the compiler flags is with the
+configuration option @samp{--cflags} (@samp{--with-cflags} in 21.5). If
+you have a recent version of 21.5, you should use
+@samp{--without-optimization} in preference to directly setting
+@samp{--cflags}.
+
+@item
+If it's not a true crash (@emph{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. Under Unix and Mac OS X, the typical way to do this is to
+first use some variant of the @samp{ps} command to figure out the
+process ID of XEmacs, for example @samp{ps -auxww | grep xemacs} under
+a BSD variant, @samp{ps -elf | grep xemacs} under Linux or System V,
+or @samp{ps -aW | grep xemacs} under Cygwin. Then run
+
+@example
+gdb /path/to/xemacs/xemacs ####
+@end example
+
+Where @code{####} is the process id of your XEmacs. (If you're not
+sure, try using @samp{which xemacs}.) When gdb attaches, the xemacs
+will stop and you can type @samp{where} in gdb to get a stack trace as
+usual. To get things moving again, you can just type @samp{quit} in
+gdb. It'll tell you the program is running and ask if you want to
+quit anyways. Say @samp{y} and it'll quit and have your emacs
+continue from where it was at.
+
+If you're running another debugger, a similar method may work, or you
+may have to run the debugger first and then use the @code{attach}
+command or something similar.
+
+Under Microsoft Windows, use the menu item @samp{Build->Start
+Debug->Attach to Process...} and select the XEmacs process from the list
+given.
+
+@item
+If you're able to run XEmacs under a debugger and reproduce the crash,
+here are some things you can do:
+
+@item
+If XEmacs is hitting an assertion failure, put a breakpoint on
+@code{assert_failed()}.
+
+@item
+If XEmacs is hitting some weird Lisp error that's causing it to crash
+(e.g. during startup), put a breakpoint on @code{signal_1()}---this is
+declared static in @file{eval.c}.
+
+@item
+If XEmacs is outputting lots of X errors, put a breakpoint on
+@code{x_error_handler()}; that will tell you which call is causing
+them. Note that the result may not be very useful by default because
+X Windows normally operates asynchronously: A bunch of commands are
+buffered up and then sent to the server all at once. This greatly
+improves performance over a network but means that an error may not be
+reported until the server receives the commands, which can be long
+after XEmacs made the erroneous calls. For best results, you need to
+make the X server synchronous before getting the backtrace. This can
+be done by starting XEmacs with the @samp{-sync} option or executing
+the Lisp code @code{(x-debug-mode t)}.
+
+@item
+Internally, you will probably see lots of variables that hold objects of
+type @code{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:
+
+@example
+call debug_print (OBJECT)
+@end example
+
+where @var{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.
+
+Under 21.5 and later, @code{dp} is defined as an easier-to-type equivalent
+of @code{debug_print}. You can also try @code{dpa} if you can't see
+the output from @code{debug_print} (this will return a string containing
+the output), or use @code{debug_p3} if @code{debug_print} itself triggers
+a crash (this is a less comprehensive but super-safe way to print out
+a Lisp object).
+
+@item
+If you want to get a Lisp backtrace showing the Lisp call
+stack, do this:
+
+@example
+call debug_backtrace ()
+@end example
+
+Under 21.5 and later, @code{db} is defined as an easier-to-type equivalent
+of @code{debug_backtrace}.
+
+@item
+Using @code{debug_print} and @code{debug_backtrace} 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
+@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:
+
+@table @code
+@item pobj
+Usage: pobj lisp_object @*
+Print the internal C representation of a lisp object.
+
+@item xtype
+Usage: xtype lisp_object @*
+Print the Lisp type of a lisp object.
+
+@item lbt
+Usage: lbt @*
+Print the current Lisp stack trace.
+Requires a running xemacs process. (It works by calling the db
+routine described above.)
+
+@item 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.)
+
+@item 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.
+
+@item 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.
+
+@item check-xemacs
+Usage: check-xemacs @*
+Run the test suite. Equivalent to 'make check'.
+
+@item 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.
+@end table
+
+If you are using Sun's @file{dbx} debugger, there is an equivalent file
+@file{src/.dbxrc}, which defines the same commands for dbx.
+
+@item
+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 @samp{--dynamic=no} (@samp{--with-dynamic=no} in 21.5
+or later). 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.
+
+@email{1CMC3466@@ibm.mtsac.edu, Curtiss} suggests upgrading to ld.so
+version 1.8 if dynamic linking and debugging is a problem on Linux.
+
+@item
+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:
+
+@enumerate a
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+You will get a Lisp backtrace output when XEmacs crashes, so you'll have
+something useful.
+
+@end enumerate
+
+@item
+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.
+
+@item
+In versions of XEmacs before 21.2.27, @file{src/.gdbinit} was named
+@file{src/gdbinit}. This had the disadvantage of not being sourced
+automatically by gdb, so you had to set that up yourself.
+
+@item
+If you are running Microsoft Windows, the the file @file{nt/README} for
+further information about debugging XEmacs.
+
+@end itemize
+
+@node Q2.4.5, Q2.4.6, Q2.4.4, Installation
+@unnumberedsubsec Q2.4.5: I get a cryptic error message when trying to do something.
+
+When I try to use some particular option of some particular package, I
+get a cryptic error message in the minibuffer.
+
+If the message went by too quickly, use @samp{Help->Recent Messages}
+from the menubar (or type @kbd{C-h l}) to see recent messages.
+
+If you can't figure out what's going on, select
+@samp{Options->Troubleshooting->Debug on Error} from the menubar (or
+type @kbd{M-:} then @kbd{(setq debug-on-error t)}) then try and make
+the error happen again. This will put in the debugger (you can get
+out of this and continue what you were doing before by typing @kbd{c})
+and give you a backtrace that may be enlightening. If not, try
+reading through this FAQ; if that fails, you could try posting to
+@samp{comp.emacs.xemacs} (making sure to include the backtrace) and
+someone may be able to help. If you can identify which XEmacs Lisp
+source file the error is coming from you can get a more detailed stack
+backtrace by doing the following:
+
+@enumerate
+@item
+Visit the .el file in an XEmacs buffer.
+
+@item
+Issue the command @kbd{M-x eval-current-buffer}.
+
+@item
+Reproduce the error.
+@end enumerate
+
+For more information on debugging Lisp code, @xref{Debugging,,,
+lispref, XEmacs Lisp Reference Manual}.
+
+@node Q2.4.6, Q2.4.7, Q2.4.5, Installation
+@unnumberedsubsec Q2.4.6: XEmacs hangs when I try to do something.
+
+XEmacs might just be slow; some operations take a long time. XEmacs
+may also be waiting on a response from the network, for example when
+you are trying to send mail.
+
+You can usually interrupt XEmacs by typing @kbd{C-g}. If not (for
+example, Lisp code explicitly disabled this by setting
+@code{inhibit-quit}), you can use the "critical quit" mechanism by
+typing @kbd{Control-Shift-G}. This should also pop you into the
+debugger and give you a backtrace, which can tell you where the
+problem is (@pxref{Q2.4.4, How to debug an XEmacs problem with a
+debugger}). (Note that setting @code{debug-on-quit} or selecting
+@samp{Options->Troubleshooting->Debug on Quit} will also cause regular
+@kbd{C-g} to enter the debugger and give you a backtrace.)
+
+If you can't interrupt XEmacs this way, or for some reason XEmacs is
+not talking to the keyboard, you can try sending the @samp{SIGINT}
+signal using the @samp{kill} command.
+
+If the Lisp backtrace isn't enlightening, or if XEmacs is so hung that
+you can't interrupt it at all, you could try attaching to the process
+and getting a C stack backtrace. @xref{Q2.4.4, How to debug an XEmacs
+problem with a debugger}.
+
+@node Q2.4.7, Q2.4.8, Q2.4.6, Installation
+@unnumberedsubsec Q2.4.7: I get an error message when XEmacs is running in batch mode.
+
+Typically this happens when you are trying to compile some Elisp code.
+If you are doing this as part of XEmacs or the XEmacs packages, you
+should automatically get a backtrace, which can help you determine the
+source of the problem. In other cases, you can get equivalent results
+by setting the environment variable @samp{XEMACSDEBUG} to @samp{(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)} (this needs to be all on one line; to set an environment variable,
+use @samp{export XEMACSDEBUG='FOO'} under @samp{bash}, @samp{zsh},
+etc. or @samp{setenv XEMACSDEBUG 'FOO'} under @samp{csh} and
+@samp{tcsh}). @samp{XEMACSDEBUG} specifies Lisp code that will be
+executed at startup time.
+
+If the backtrace is not sufficiently useful in helping you diagnose
+the problem, you should consider using a debugger such as GDB.
+@xref{Q2.4.4, How to debug an XEmacs problem with a debugger}. You
+probably want to set a breakpoint on @code{signal_1}. Since such
+errors often occur during compiling, which is often triggered by a
+complex command run from a make suite, it may be easier to attach to
+the process once it's running.
+
+Under Microsoft Windows (and perhaps other operating systems), there is
+another useful trick you can do if you have configured with debugging
+support (configure option @samp{--debug} (@samp{--with-debug} in 21.5)
+or setting @samp{DEBUG_XEMACS} in @file{nt/config.inc}). Set the
+environment variable @samp{XEMACSDEBUG} (as described above) to
+@samp{(setq debug-on-error t)}. Then, when an error occurs
+noninteractively, instead of trying to invoke the Lisp debugger (which
+obviously won't work), XEmacs will break out to a C debugger using
+@code{(force-debugging-signal t)}. @emph{NOTE}: This runs
+@code{abort()}!!! (As well as and after executing INT 3 under MS
+Windows, which should invoke a debugger if it's active.) This is
+guaranteed to kill XEmacs! (But in this situation, XEmacs is about to
+die anyway, and if no debugger is present, this will usefully dump
+core.)
+
+@node Q2.4.8, Q2.4.9, Q2.4.7, Installation
+@unnumberedsubsec Q2.4.8: The keyboard or mouse is not working properly, or I have some other event-related problem.
+
+XEmacs has various facilities for debugging event handling.
+
+First, try setting the variable @code{debug-emacs-events} to non-zero.
+This will output various information showing which events are being
+received and how they are being translated. This may show you, for
+example, that a key command is getting intercepted using
+@code{key-translation-map}; this problem can otherwise be very tricky
+to debug.
+
+Under X, you can see exactly which events are being received from the
+window system by setting @code{x-debug-events} to non-zero. (The value
+@samp{1} gives you regular output, and @samp{2} gives you verbose
+output, including all parameters.)
+
+A similar facility exists under MS Windows: Set
+@code{debug-mswindows-events} to non-zero. (The value @samp{1} gives
+you regular output. The value @samp{2} gives you verbose output,
+including all parameters. The value @samp{3} gives you
+super-gorily-detailed output.)
+
+@node Q2.4.9, Q2.4.10, Q2.4.8, Installation
+@unnumberedsubsec Q2.4.9: @kbd{C-g} doesn't work for me. Is it broken?
+
+@kbd{C-g} does work for most people in most circumstances. If it
+doesn't, there are two possible explanations:
+
+@enumerate
+@item
+XEmacs is hung in a way that prevents @kbd{C-g} from working. This
+can happen when code is wrapped with a binding of @code{inhibit-quit}
+to @code{t}; you should still be able interrupt XEmacs using "critical
+quit". On the other hand, XEmacs may be seriously wedged. (If you're
+lucky, sending @samp{SIGINT} to the XEmacs process will interrupt it.)
+@xref{Q2.4.6, XEmacs hangs when I try to do something.}.
+
+@item
+@kbd{C-g} is indeed broken on your system. To test, try executing
+@code{(while t)} from the @samp{*scratch*} buffer. If @kbd{C-g}
+doesn't interrupt, then it's broken. This used to happen with systems
+where @samp{SIGIO} was broken, but @samp{BROKEN_SIGIO} wasn't defined.
+However, there may not be very many such systems nowadays.
+@end enumerate
+
+@node Q2.4.10, Q2.4.11, Q2.4.9, Installation
+@unnumberedsubsec Q2.4.10: How do I debug process-related problems?
+
+Under MS Windows, you can set the variable
+@code{debug-mswindows-process-command-lines} to non-@samp{nil} to get
+information on exactly what is getting passed to a process. This can
+be useful in determining problems with quoting. (Under Unix, a process
+receives each argument separately, but under MS Windows a single
+command line is received, and arguments with spaces or other special
+characters in them must be quoted. Unfortunately this means that each
+process, potentially at least, has its own quoting conventions, and
+the code to process quoting conventions in @file{cmd.exe}, the Visual
+C++ startup code and the like is baroque and poorly documented.
+XEmacs uses the variable
+@code{mswindows-construct-process-command-line-alist} to construct a
+command line from a list of arguments based on the command to be run,
+but it is (and cannot be) a perfect solution.)
+
+@node Q2.4.11, Q2.4.12, Q2.4.10, Installation
+@unnumberedsubsec Q2.4.11: 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 @ref{Q2.4.4, How to debug an XEmacs
+problem with a debugger}. Try to get both a C and Lisp backtrace, and
+send them along with the full error output to
+@email{xemacs-beta@@xemacs.org}.
+
+@node Q2.4.12, Q2.5.1, Q2.4.11, Installation
+@unnumberedsubsec Q2.4.12: 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 @file{etc/PACKAGES}), or install the `Sumo Tarball'
+(@pxref{Q2.1.2, How do I figure out which packages to install?}).
+
+@c #### should xref to XEmacs manual here
+
+@unnumberedsec 2.5: Startup-Related Problems
+
+@node Q2.5.1, Q2.5.2, Q2.4.12, Installation
+@unnumberedsubsec Q2.5.1: XEmacs cannot connect to my X Terminal!
+
+Help! I can not get XEmacs to display on my Envizex X-terminal!
+
+Try setting the @code{DISPLAY} variable using the numeric IP address of
+the host you are running XEmacs from.
+
+@node Q2.5.2, Q2.5.3, Q2.5.1, Installation
+@unnumberedsubsec Q2.5.2 Startup problems related to paths or package locations.
+
+First of all, if XEmacs can't find the packages, check to make sure
+that you put the packages in the right place, or that you told XEmacs
+where to look for the packages when you compiled it. @xref{Q2.1.1}.
+
+If something is still going wrong, or you get a startup warning about
+not being able to deduce some paths, you can get detailed information
+on the path-searching process at startup by setting the environment
+variable @samp{EMACSDEBUGPATHS} to a non-null value. One thing to
+look for if you're having package problems is the value of
+@samp{configure-package-path}. This corresponds to what was compiled
+into XEmacs using the @samp{--package-prefix} or @samp{--package-path}
+parameter (@pxref{Q2.1.1}). If this has the value of @samp{nil},
+this means that no value was compiled into XEmacs using these parameters.
+
+@node Q2.5.3, Q2.5.4, Q2.5.2, Installation
+@unnumberedsubsec Q2.5.3: 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
+@file{/etc/hosts} file. The file should contain an entry like:
+
+@example
+127.0.0.1 localhost
+@end example
+
+Add that line, and XEmacs will be happy.
+
+@node Q2.5.4, Q2.5.5, Q2.5.3, Installation
+@unnumberedsubsec Q2.5.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:
+
+@format
+-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
+@end format
+
+More precisely, do the following in your resource file:
+
+@format
+Emacs.default.attributeFont: \
+-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
+@end format
+
+If you just don't want to see the @samp{*Warnings*} buffer at startup
+time, you can set this:
+
+@lisp
+(setq display-warning-minimum-level 'error)
+@end lisp
+
+The buffer still exists; it just isn't in your face.
+
+@node Q2.5.5, Q2.5.6, Q2.5.4, Installation
+@unnumberedsubsec Q2.5.5: Warnings from incorrect key modifiers.
+
+The following information comes from the @file{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.
+
+@example
+#! /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
+@end example
+
+@node Q2.5.6, , Q2.5.5, Installation
+@unnumberedsubsec Q2.5.6: 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 @file{temacs} (and in turn, @file{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 @file{runemacs}, a small
+Windows application that existed merely to start @file{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
+@file{CMD.EXE}/@file{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.)
+
+@node Editing, Display, Installation, Top
+@unnumbered 3 Editing Functions
+
+This is part 3 of the XEmacs Frequently Asked Questions list. This
+section is devoted to the editing-related capabilities of XEmacs (the
+keyboard, mouse, buffers, text selections, etc.) and how to customize
+them.
+
+@menu
+3.0: The Keyboard
+* Q3.0.1:: How can I customize the keyboard?
+* Q3.0.2:: How can I bind complex functions (or macros) to keys?
+* Q3.0.3:: How do I bind C-. and C-; to scroll one line up and down?
+* Q3.0.4:: Globally binding @kbd{Delete}?
+* Q3.0.5:: How to map @kbd{Help} key alone on Sun type4 keyboard?
+* Q3.0.6:: How can you type in special characters in XEmacs?
+* Q3.0.7:: Can I turn on @dfn{sticky} modifier keys?
+* Q3.0.8:: How do I map the arrow keys?
+* Q3.0.9:: HP Alt key as Meta.
+* Q3.0.10:: Why does edt emulation not work?
+* Q3.0.11:: How can I emulate VI and use it as my default mode?
+
+3.1: The Mouse
+* Q3.1.1:: How can I turn off Mouse pasting?
+* Q3.1.2:: How do I set control/meta/etc modifiers on mouse buttons?
+* Q3.1.3:: Clicking the left button does not do anything in buffer list.
+* Q3.1.4:: How can I get a list of buffers when I hit mouse button 3?
+* Q3.1.5:: How can I set XEmacs up so that it pastes where the text cursor is?
+
+3.2: Buffers, Text Editing
+* Q3.2.1:: Can I have the end of the buffer delimited in some way?
+* Q3.2.2:: How do I insert today's date into a buffer?
+* Q3.2.3:: How do I get a single minibuffer frame?
+* Q3.2.4:: How can I enable auto-indent and/or Filladapt?
+* Q3.2.5:: How can I get XEmacs to come up in text/auto-fill mode by default?
+
+3.3: Text Selections
+* Q3.3.1:: How do I select a rectangular region?
+* Q3.3.2:: How can I turn off or change highlighted selections?
+* Q3.3.3:: How do I cause typing on an active region to remove it?
+* Q3.3.4:: Can I turn off the highlight during isearch?
+* Q3.3.5:: Why is killing so slow?
+* Q3.3.6:: Why does @kbd{M-w} take so long?
+
+3.4: Editing Source Code
+* Q3.4.1:: I do not like cc-mode. How do I use the old c-mode?
+* Q3.4.2:: How do you make XEmacs indent CL if-clauses correctly?
+@end menu
+
+@unnumberedsec 3.0: The Keyboard
+
+@node Q3.0.1, Q3.0.2, Editing, Editing
+@unnumberedsubsec Q3.0.1: How can I customize the keyboard?
+
+#### Write me.
+
+@node Q3.0.2, Q3.0.3, Q3.0.1, Editing
+@unnumberedsubsec Q3.0.2: How can I bind complex functions (or macros) to keys?
+
+As an example, say you want the @kbd{paste} key on a Sun keyboard to
+insert the current Primary X selection at point. You can accomplish this
+with:
+
+@lisp
+(define-key global-map [f18] 'x-insert-selection)
+@end lisp
+
+However, this only works if there is a current X selection (the
+selection will be highlighted). The functionality I like is for the
+@kbd{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 @code{x-insert-selection}. This is done by wrapping
+the call in a 'lambda form:
+
+@lisp
+(global-set-key [f18]
+ (lambda () (interactive) (x-insert-selection t nil)))
+@end lisp
+
+This binds the f18 key to a @dfn{generic} functional object. The
+interactive spec is required because only interactive functions can be
+bound to keys.
+
+For the FAQ example you could use:
+
+@lisp
+(global-set-key [(control ?.)]
+ (lambda () (interactive) (scroll-up 1)))
+(global-set-key [(control ?;)]
+ (lambda () (interactive) (scroll-up -1)))
+@end lisp
+
+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.
+@xref{Q3.0.3, How do I bind C-. and C-; to scroll one line up and
+down?}.
+
+@node Q3.0.3, Q3.0.4, Q3.0.2, Editing
+@unnumberedsubsec Q3.0.3: How do I bind C-. and C-; to scroll one line up and down?
+
+Add the following (Thanks to @email{mly@@adoc.xerox.com, Richard Mlynarik} and
+@email{wayne@@zen.cac.stratus.com, Wayne Newberry}) to @file{.emacs}:
+
+@lisp
+(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-;
+@end lisp
+
+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. (@pxref{Q3.0.2, How can I bind complex functions (or macros) to
+keys?} for a better answer).
+
+@node Q3.0.4, Q3.0.5, Q3.0.3, Editing
+@unnumberedsubsec Q3.0.4: Globally binding @kbd{Delete}?
+
+I cannot manage to globally bind my @kbd{Delete} key to something other
+than the default. How does one do this?
+
+Answer: The problem is that many modes explicitly bind @kbd{Delete}. To
+get around this, try the following:
+
+@lisp
+(defun foo ()
+ (interactive)
+ (message "You hit DELETE"))
+
+(define-key key-translation-map 'delete 'redirected-delete)
+(global-set-key 'redirected-delete 'foo)
+@end lisp
+
+@node Q3.0.5, Q3.0.6, Q3.0.4, Editing
+@unnumberedsubsec Q3.0.5: How to map @kbd{Help} key alone on Sun type4 keyboard?
+
+The following works in GNU Emacs 19:
+
+@lisp
+(global-set-key [help] 'help-command);; Help
+@end lisp
+
+The following works in XEmacs with the addition of shift:
+
+@lisp
+(global-set-key [(shift help)] 'help-command);; Help
+@end lisp
+
+But it doesn't work alone. This is in the file @file{PROBLEMS} which
+should have come with your XEmacs installation: @emph{Emacs ignores the
+@kbd{help} key when running OLWM}.
+
+OLWM grabs the @kbd{help} key, and retransmits it to the appropriate
+client using
+@iftex
+@*
+@end iftex
+@code{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 @code{x-allow-sendevents} to t. You
+can also cause fix this by telling OLWM to not grab the help key, with
+the null binding @code{OpenWindows.KeyboardCommand.Help:}.
+
+@node Q3.0.6, Q3.0.7, Q3.0.5, Editing
+@unnumberedsubsec Q3.0.6: How can you type in special characters in XEmacs?
+One way is to use the package @code{x-compose}. Then you can use
+sequences like @kbd{Compose " a} to get ä, etc.
+
+Another way is to use the @code{iso-insert} package. Then you can use
+sequences like @kbd{C-x 8 " a} to get ä, etc.
+
+@email{glynn@@sensei.co.uk, Glynn Clements} writes:
+
+@quotation
+It depends upon your X server.
+
+Generally, the simplest way is to define a key as Multi_key with
+xmodmap, e.g.
+@c hey, show some respect, willya -- there's xkeycaps, isn't there? --
+@c chr ;)
+@example
+ xmodmap -e 'keycode 0xff20 = Multi_key'
+@end example
+
+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.
+@example
+ Multi a ' => á
+ Multi e " => ë
+ Multi c , => ç
+@end example
+
+etc.
+
+Also, recent versions of XFree86 define various AltGr-<key>
+combinations as dead keys, i.e.
+@example
+ AltGr [ => dead_diaeresis
+ AltGr ] => dead_tilde
+ AltGr ; => dead_acute
+@end example
+etc.
+
+Running @samp{xmodmap -pk} will list all of the defined keysyms.
+@end quotation
+
+For the related problem of @emph{displaying} non-ASCII characters in a
+non-Mule XEmacs, @xref{Q4.0.8, How do I display non-ASCII characters?}.
+
+@node Q3.0.7, Q3.0.8, Q3.0.6, Editing
+@unnumberedsubsec Q3.0.7: Can I turn on @dfn{sticky} modifier keys?
+
+Yes, with @code{(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.
+
+@email{ben@@xemacs.org, Ben Wing} writes:
+
+@quotation
+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.
+@end quotation
+
+@node Q3.0.8, Q3.0.9, Q3.0.7, Editing
+@unnumberedsubsec Q3.0.8: How do I map the arrow keys?
+@c New
+Say you want to map @kbd{C-@key{right}} to forward-word:
+
+@email{sds@@usa.net, Sam Steingold} writes:
+
+@quotation
+@lisp
+; both XEmacs and Emacs
+(define-key global-map [(control right)] 'forward-word)
+@end lisp
+or
+@lisp
+; Emacs only
+(define-key global-map [C-right] 'forward-word)
+@end lisp
+or
+@lisp
+; ver > 20, both
+(define-key global-map (kbd "C-<right>") 'forward-word)
+@end lisp
+@end quotation
+
+@node Q3.0.9, Q3.0.10, Q3.0.8, Editing
+@unnumberedsubsec Q3.0.9: 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:
+
+@example
+remove Mod1 = Mode_switch
+@end example
+
+@node Q3.0.10, Q3.0.11, Q3.0.9, Editing
+@unnumberedsubsec Q3.0.10: 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 @file{init.el}:
+
+@lisp
+(tpu-edt)
+@end lisp
+
+If you don't want it to replace @kbd{C-h} with an edt-style help menu
+add this as well:
+
+@lisp
+(global-set-key [(control h)] 'help-for-help)
+@end lisp
+
+@node Q3.0.11, Q3.1.1, Q3.0.10, Editing
+@unnumberedsubsec Q3.0.11: 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 @file{init.el}:
+
+@lisp
+(viper-mode)
+@end lisp
+
+@email{kifer@@CS.SunySB.EDU, Michael Kifer} writes:
+
+@quotation
+This should be added as close to the top of @file{init.el} as you can get
+it, otherwise some minor modes may not get viper-ized.
+@end quotation
+
+@unnumberedsec 3.1: The Mouse
+
+@node Q3.1.1, Q3.1.2, Q3.0.11, Editing
+@unnumberedsubsec Q3.1.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 @code{define-key} or @code{global-set-key}.
+
+@lisp
+(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)
+@end lisp
+
+@node Q3.1.2, Q3.1.3, Q3.1.1, Editing
+@unnumberedsubsec Q3.1.2: How do I set control/meta/etc modifiers on mouse buttons?
+
+Use, for instance, @code{[(meta button1)]}. For example, here is a common
+setting for Common Lisp programmers who use the bundled @code{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]
+
+@lisp
+(local-set-key [(meta button1)] 'edit-definitions-lisp)
+@end lisp
+
+@node Q3.1.3, Q3.1.4, Q3.1.2, Editing
+@unnumberedsubsec Q3.1.3: Clicking the left button does not do anything in buffer list.
+
+I do @kbd{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.