comparison man/faq.texi @ 56817:99e9271dee93

Fix texinfo usage, esp. doublequotes. (Difference between Emacs and XEmacs): Some clarification.

56816:f3448e5d371d

Copyright 1992,1993 Steven Byrnes@*
Copyright 1990,1991,1992 Joseph Brian Wells@*

@quotation
This list of frequently asked questions about GNU Emacs with answers
("FAQ") may be translated into other languages, transformed into other
formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.

The same conditions apply to any derivative of the FAQ as apply to the FAQ
itself.  Every copy of the FAQ must include this notice or an approved
translation, information on who is currently maintaining the FAQ and how to

@item COPYING
Emacs General Public License

@item DISTRIB
Emacs Availability Information, including the popular "Free Software
Foundation Order Form"

@item FTP
How to get GNU Software by Internet FTP or by UUCP

@item GNU

@item SERVICE
GNU Service Directory

@item SUN-SUPPORT
including "Using Emacstool with GNU Emacs"

@end table

Latest versions of the above files also available at

send usenet/news.answers/GNU-Emacs-FAQ/part4
send usenet/news.answers/GNU-Emacs-FAQ/part5
@end example

For more information, send email to @email{mail-server@@rtfm.mit.edu}
with "help" and "index" in the body on separate lines.

@item
As the very last resort, you can e-mail a request to
@email{emacs-faq@@lerner.co.il}.  Don't do this unless you have made a
good-faith effort to obtain the FAQ list via one of the methods listed

@item
@code{hscroll-step-percent} controls how far to jump once we decide to do so.
@end itemize

@node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests
@section How do I make Emacs "typeover" or "overwrite" instead of inserting?
@cindex @key{Insert}
@cindex @code{overwrite-mode}
@cindex Overwriting existing text
@cindex Toggling @code{overwrite-mode}

You can also use a resource editor, such as editres (for X11R5 and
onwards), to look at the resource names for the menu bar, assuming Emacs
was compiled with the X toolkit.

@node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests
@section How do I execute ("evaluate") a piece of Emacs Lisp code?
@cindex Evaluating Lisp code
@cindex Lisp forms, evaluating

There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
Emacs Lisp @dfn{form}:

citation for yanked mail and news messages; it is included in Emacs
since version 19.20.  @xref{Changing the included text prefix}, for
additional information.

@node Underlining paragraphs, Repeating a command as many times as possible, Inserting > at the beginning of each line, Common requests
@section How do I insert "_^H" before each character in a region to get an underlined paragraph?
@cindex Underlining a region of text
@cindex @code{underline-region}

Mark the region and then type @kbd{M-x underline-region @key{RET}}.

@cindex Disabling backups

You probably don't want to do this, since backups are useful, especially
when something goes wrong.

To avoid seeing backup files (and other "uninteresting" files) in Dired,
load @code{dired-x} by adding the following to your @file{.emacs} file:

@lisp
(add-hook 'dired-load-hook
          (lambda ()

#define VALBITS 26
#define GCTYPEBITS 5
@end example

@noindent
This method may result in "ILLEGAL DATATYPE" and other random errors on
some machines.

@email{daveg@@csvax.cs.caltech.edu, David Gillespie} explains how this
problems crops up; while his numbers are true only for pre-19.29
versions of Emacs, the theory remains the same with current versions.

@example
stty -icrnl -onlcr -echo susp ^Z
@end example

@node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems
@section Why do I get "Process shell exited abnormally with code 1"?
@cindex Abnormal exits from @code{shell-mode}
@cindex @code{shell-mode} exits
@cindex Process shell exited

The most likely reason for this message is that the @samp{env} program

Some people have trouble with Shell Mode because of intrusive
antivirus software; disabling the resident antivirus program solves
the problems in those cases.

@node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems
@section Where is the termcap/terminfo entry for terminal type "emacs"?
@cindex Termcap
@cindex Terminfo
@cindex Emacs entries for termcap/terminfo

The termcap entry for terminal type @samp{emacs} is ordinarily put in

@example
if ("$term" == emacs) set term=dumb
@end example

@node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems
@section Why does Emacs spontaneously start displaying "I-search:" and beeping?
@cindex Spontaneous entry into isearch-mode
@cindex isearch-mode, spontaneous entry into
@cindex Beeping without obvious reason

Your terminal (or something between your terminal and the computer) is

properly told to do DNS lookups with the correct command line switch.

@end itemize

@node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems
@section Why does Emacs say "Error in init file"?
@cindex Error in @file{.emacs}
@cindex Error in init file
@cindex Init file, errors in
@cindex @file{.emacs} file, errors in
@cindex Debugging @file{.emacs} file

@end example

@end itemize

@node Dired claims that no file is on this line,  , Security risks with Emacs, Bugs and problems
@section Dired says, "no file on this line" when I try to do something.
@cindex Dired does not see a file

@c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
@c check.
Chances are you're using a localized version of Unix that doesn't use US

Emacs needs to be linked with the static version of the X11 library,
@file{libX11.a}.  This may be missing.

On OpenWindows, you may need to use @code{add_services} to add the
"OpenWindows Programmers" optional software category from the CD-ROM.

On HP-UX 8.0, you may need to run @code{update} again to load the
X11-PRG ``fileset''.  This may be missing even if you specified ``all
filesets'' the first time.  If @file{libcurses.a} is missing, you may
need to load the ``Berkeley Development Option.''

A list of sites mirroring @samp{ftp.gnu.org} can be found at

@uref{http://www.gnu.org/order/ftp.html}

@node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages
@section What is the difference between Emacs and XEmacs (formerly "Lucid Emacs")?
@cindex XEmacs
@cindex Difference Emacs and XEmacs
@cindex Lucid Emacs
@cindex Epoch

XEmacs is a branch version of Emacs.  It was earlier called as Lucid
Emacs, and it was based on a prerelease version of Emacs 19.  In this
FAQ, we use the name ``Emacs'' only for the official version.

Emacs and XEmacs each come with Lisp packages that are lacking in the
other.  The two versions have some significant differences at the Lisp
programming level.  Many XEmacs features have found their way into
recent versions of Emacs, and more features can be expected in the
future, but there are still many differences between the two.

We have used some of the code in XEmacs, and would like to use other
parts, but the earlier XEmacs maintainers did not always keep track of
the authors of contributed code, which makes it impossible for the FSF
to get copyright papers signed for that code.  (The FSF requires these
papers for all the code included in the Emacs release, aside from
generic C support packages that retain their separate identity and are
not integrated into the code of Emacs proper.)

If you want to talk about these two versions and distinguish them,
please call them ``Emacs'' and ``XEmacs.''  To contrast ``XEmacs''
with ``GNU Emacs'' would be misleading, since XEmacs too has its
origin in the GNU Project.

@node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages
@section Where can I get Emacs for my PC running MS-DOS?
@cindex MS-DOS, Emacs for
@cindex DOS, Emacs for

The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
directory of the Emacs sources contains some additional information
regarding Emacs under MS-DOS.

For a list of other MS-DOS implementations of Emacs (and Emacs
look-alikes), consult the list of "Emacs implementations and literature,"
available at

@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}

Note that while many of these programs look similar to Emacs, they often

@node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages
@section Where can I get Emacs for my Apple computer?
@cindex Apple computers, Emacs for
@cindex Macintosh, Emacs for

An unofficial port of GNU Emacs 18.59 to the Macintosh is available at a
number of ftp sites, the home being
@uref{ftp://ftp.cs.cornell.edu/pub/parmet/Emacs-1.17.sit.bin}.

A port of Emacs 20.4 is available at
@uref{http://www.cs.hku.hk/~choi/emacs/index.html}.

Beginning with version 21.1, the Macintosh is supported in the official
Emacs distribution; see the files @file{mac/README} and
@file{mac/INSTALL} in the Emacs distribution for build instructions.

Apple's forthcoming "OS X" is based largely on NeXTSTEP and OpenStep.
@xref{Emacs for NeXTSTEP}, for more details about that version.

@node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages
@section Where do I get Emacs that runs on VMS under DECwindows?
@cindex DECwindows, Emacs for

@uref{http://sunsite.auc.dk/jde/}

@end table

@node Patch,  , JDE, Major packages and programs
@section Patch --- program to apply "diffs" for updating files
@cindex Updating files with diffs
@cindex Patching source files with diffs
@cindex Diffs and patching
@cindex @file{patch}

(global-set-key (quote [f1]) (quote help-for-help))
@end lisp

@noindent
can be placed directly into the @file{.emacs} file.  If the key binding is
local, the command is used in conjunction with the "add-hook" command.
For example, in tex-mode, a local binding might be

@lisp
(add-hook 'tex-mode-hook
  (lambda ()
   (local-set-key (quote [f1]) (quote help-for-help))))

@end lisp

@end itemize

@node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings
@section Why does Emacs say "Key sequence XXX uses invalid prefix characters"?
@cindex Prefix characters, invalid
@cindex Invalid prefix characters
@cindex Misspecified key sequences

Usually, one of two things has happened.  In one case, the control

@section How do I produce C-XXX with my keyboard?
@cindex Producing control characters
@cindex Generating control characters
@cindex Control characters, generating

On terminals (but not under X), some common "aliases" are:

@table @asis

@item @kbd{C-2}  or  @kbd{C-@key{SPC}}
@kbd{C-@@}

56817:99e9271dee93

Copyright 1992,1993 Steven Byrnes@*
Copyright 1990,1991,1992 Joseph Brian Wells@*

@quotation
This list of frequently asked questions about GNU Emacs with answers
(``FAQ'') may be translated into other languages, transformed into other
formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.

The same conditions apply to any derivative of the FAQ as apply to the FAQ
itself.  Every copy of the FAQ must include this notice or an approved
translation, information on who is currently maintaining the FAQ and how to

@item COPYING
Emacs General Public License

@item DISTRIB
Emacs Availability Information, including the popular Free Software
Foundation Order Form

@item FTP
How to get GNU Software by Internet FTP or by UUCP

@item GNU

@item SERVICE
GNU Service Directory

@item SUN-SUPPORT
including ``Using Emacstool with GNU Emacs''

@end table

Latest versions of the above files also available at

send usenet/news.answers/GNU-Emacs-FAQ/part4
send usenet/news.answers/GNU-Emacs-FAQ/part5
@end example

For more information, send email to @email{mail-server@@rtfm.mit.edu}
with @samp{help} and @samp{index} in the body on separate lines.

@item
As the very last resort, you can e-mail a request to
@email{emacs-faq@@lerner.co.il}.  Don't do this unless you have made a
good-faith effort to obtain the FAQ list via one of the methods listed

@item
@code{hscroll-step-percent} controls how far to jump once we decide to do so.
@end itemize

@node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests
@section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
@cindex @key{Insert}
@cindex @code{overwrite-mode}
@cindex Overwriting existing text
@cindex Toggling @code{overwrite-mode}

You can also use a resource editor, such as editres (for X11R5 and
onwards), to look at the resource names for the menu bar, assuming Emacs
was compiled with the X toolkit.

@node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests
@section How do I execute (``evaluate'') a piece of Emacs Lisp code?
@cindex Evaluating Lisp code
@cindex Lisp forms, evaluating

There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
Emacs Lisp @dfn{form}:

citation for yanked mail and news messages; it is included in Emacs
since version 19.20.  @xref{Changing the included text prefix}, for
additional information.

@node Underlining paragraphs, Repeating a command as many times as possible, Inserting > at the beginning of each line, Common requests
@section How do I insert @samp{_^H} before each character in a region to get an underlined paragraph?
@cindex Underlining a region of text
@cindex @code{underline-region}

Mark the region and then type @kbd{M-x underline-region @key{RET}}.

@cindex Disabling backups

You probably don't want to do this, since backups are useful, especially
when something goes wrong.

To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
load @code{dired-x} by adding the following to your @file{.emacs} file:

@lisp
(add-hook 'dired-load-hook
          (lambda ()

#define VALBITS 26
#define GCTYPEBITS 5
@end example

@noindent
This method may result in ``ILLEGAL DATATYPE'' and other random errors on
some machines.

@email{daveg@@csvax.cs.caltech.edu, David Gillespie} explains how this
problems crops up; while his numbers are true only for pre-19.29
versions of Emacs, the theory remains the same with current versions.

@example
stty -icrnl -onlcr -echo susp ^Z
@end example

@node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems
@section Why do I get ``Process shell exited abnormally with code 1''?
@cindex Abnormal exits from @code{shell-mode}
@cindex @code{shell-mode} exits
@cindex Process shell exited

The most likely reason for this message is that the @samp{env} program

Some people have trouble with Shell Mode because of intrusive
antivirus software; disabling the resident antivirus program solves
the problems in those cases.

@node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems
@section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
@cindex Termcap
@cindex Terminfo
@cindex Emacs entries for termcap/terminfo

The termcap entry for terminal type @samp{emacs} is ordinarily put in

@example
if ("$term" == emacs) set term=dumb
@end example

@node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems
@section Why does Emacs spontaneously start displaying @samp{I-search:} and beeping?
@cindex Spontaneous entry into isearch-mode
@cindex isearch-mode, spontaneous entry into
@cindex Beeping without obvious reason

Your terminal (or something between your terminal and the computer) is

properly told to do DNS lookups with the correct command line switch.

@end itemize

@node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems
@section Why does Emacs say @samp{Error in init file}?
@cindex Error in @file{.emacs}
@cindex Error in init file
@cindex Init file, errors in
@cindex @file{.emacs} file, errors in
@cindex Debugging @file{.emacs} file

@end example

@end itemize

@node Dired claims that no file is on this line,  , Security risks with Emacs, Bugs and problems
@section Dired says, @samp{no file on this line} when I try to do something.
@cindex Dired does not see a file

@c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
@c check.
Chances are you're using a localized version of Unix that doesn't use US

Emacs needs to be linked with the static version of the X11 library,
@file{libX11.a}.  This may be missing.

On OpenWindows, you may need to use @code{add_services} to add the
``OpenWindows Programmers'' optional software category from the CD-ROM.

On HP-UX 8.0, you may need to run @code{update} again to load the
X11-PRG ``fileset''.  This may be missing even if you specified ``all
filesets'' the first time.  If @file{libcurses.a} is missing, you may
need to load the ``Berkeley Development Option.''

A list of sites mirroring @samp{ftp.gnu.org} can be found at

@uref{http://www.gnu.org/order/ftp.html}

@node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages
@section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
@cindex XEmacs
@cindex Difference Emacs and XEmacs
@cindex Lucid Emacs
@cindex Epoch

XEmacs is a branch version of Emacs.  It was first called Lucid Emacs,
and was initially derived from a prerelease version of Emacs 19.  In
this FAQ, we use the name ``Emacs'' only for the official version.

Emacs and XEmacs each come with Lisp packages that are lacking in the
other.  The two versions have some significant differences at the Lisp
programming level.  Their current features are roughly comparable,
though the support for some operating systems, character sets and
specific packages might be quite different.

Some XEmacs code has been contributed to Emacs, and we would like to
use other parts, but the earlier XEmacs maintainers did not always
keep track of the authors of contributed code, which makes it
impossible for the FSF to get copyright papers signed for that code.
(The FSF requires these papers for all the code included in the Emacs
release, aside from generic C support packages that retain their
separate identity and are not integrated into the code of Emacs
proper.)

If you want to talk about these two versions and distinguish them,
please call them ``Emacs'' and ``XEmacs.''  To contrast ``XEmacs''
with ``GNU Emacs'' would be misleading, since XEmacs too has its
origin in the work of the GNU Project.  Terms such as ``Emacsen'' and
``(X)Emacs'' are not wrong, but they are not very clear, so it
is better to write ``Emacs and XEmacs.''

@node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages
@section Where can I get Emacs for my PC running MS-DOS?
@cindex MS-DOS, Emacs for
@cindex DOS, Emacs for

The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
directory of the Emacs sources contains some additional information
regarding Emacs under MS-DOS.

For a list of other MS-DOS implementations of Emacs (and Emacs
look-alikes), consult the list of ``Emacs implementations and literature,''
available at

@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}

Note that while many of these programs look similar to Emacs, they often

@node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages
@section Where can I get Emacs for my Apple computer?
@cindex Apple computers, Emacs for
@cindex Macintosh, Emacs for

Beginning with version 21.1, the Macintosh is supported in the official
Emacs distribution; see the files @file{mac/README} and
@file{mac/INSTALL} in the Emacs distribution for build instructions.

Apple's ``OS X'' is based largely on NeXTSTEP and OpenStep.
@xref{Emacs for NeXTSTEP}, for more details about that version.

@node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages
@section Where do I get Emacs that runs on VMS under DECwindows?
@cindex DECwindows, Emacs for

@uref{http://sunsite.auc.dk/jde/}

@end table

@node Patch,  , JDE, Major packages and programs
@section Patch --- program to apply ``diffs'' for updating files
@cindex Updating files with diffs
@cindex Patching source files with diffs
@cindex Diffs and patching
@cindex @file{patch}

(global-set-key (quote [f1]) (quote help-for-help))
@end lisp

@noindent
can be placed directly into the @file{.emacs} file.  If the key binding is
local, the command is used in conjunction with the @samp{add-hook} function.
For example, in TeX mode, a local binding might be

@lisp
(add-hook 'tex-mode-hook
  (lambda ()
   (local-set-key (quote [f1]) (quote help-for-help))))

@end lisp

@end itemize

@node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings
@section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
@cindex Prefix characters, invalid
@cindex Invalid prefix characters
@cindex Misspecified key sequences

Usually, one of two things has happened.  In one case, the control

@section How do I produce C-XXX with my keyboard?
@cindex Producing control characters
@cindex Generating control characters
@cindex Control characters, generating

On terminals (but not under X), some common ``aliases'' are:

@table @asis

@item @kbd{C-2}  or  @kbd{C-@key{SPC}}
@kbd{C-@@}