1 \input texinfo @c -*- mode: texinfo; -*-
3 @setfilename ../../info/efaq
4 @settitle GNU Emacs FAQ
7 @c This is used in many places
10 @c This file is maintained by Romain Francoise <rfrancoise@gnu.org>.
11 @c Feel free to install changes without prior permission (but I'd
12 @c appreciate a notice if you do).
15 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
16 Free Software Foundation, Inc.@*
17 Copyright 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner@*
18 Copyright 1992,1993 Steven Byrnes@*
19 Copyright 1990,1991,1992 Joseph Brian Wells@*
22 This list of frequently asked questions about GNU Emacs with answers
23 (``FAQ'') may be translated into other languages, transformed into other
24 formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.
26 The same conditions apply to any derivative of the FAQ as apply to the FAQ
27 itself. Every copy of the FAQ must include this notice or an approved
28 translation, information on who is currently maintaining the FAQ and how to
29 contact them (including their e-mail address), and information on where the
30 latest version of the FAQ is archived (including FTP information).
32 The FAQ may be copied and redistributed under these conditions, except that
33 the FAQ may not be embedded in a larger literary work unless that work
34 itself allows free copying and redistribution.
36 [This version has been heavily edited since it was included in the Emacs
43 * Emacs FAQ: (efaq). Frequently Asked Questions about Emacs.
46 @c The @titlepage stuff only appears in the printed version
49 @center @titlefont{GNU Emacs FAQ}
51 @c The following two commands start the copyright page.
53 @vskip 0pt plus 1filll
59 @node Top, FAQ notation, (dir), (dir)
61 This is the GNU Emacs FAQ, last updated on @today{}.
63 This FAQ is maintained as a part of GNU Emacs. If you find any errors,
64 or have any suggestions, please use @kbd{M-x report-emacs-bug} to report
78 * Compiling and installing Emacs::
79 * Finding Emacs and related packages::
80 * Major packages and programs::
82 * Alternate character sets::
87 @c ------------------------------------------------------------
88 @node FAQ notation, General questions, Top, Top
92 This chapter describes notation used in the GNU Emacs FAQ, as well as in
93 the Emacs documentation. Consult this section if this is the first time
94 you are reading the FAQ, or if you are confused by notation or terms
101 * File-name conventions::
105 @node Basic keys, Extended commands, FAQ notation, FAQ notation
106 @section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
108 @cindex Control key, notation for
109 @cindex @key{Meta} key, notation for
110 @cindex Control-Meta characters, notation for
111 @cindex @kbd{C-h}, definition of
112 @cindex @kbd{C-M-h}, definition of
113 @cindex @key{DEL}, definition of
114 @cindex @key{ESC}, definition of
115 @cindex @key{LFD}, definition of
116 @cindex @key{RET}, definition of
117 @cindex @key{SPC}, definition of
118 @cindex @key{TAB}, definition of
119 @cindex Notation for keys
124 @kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
127 @kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
128 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
131 @kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
135 @kbd{C-M-x}: a synonym for the above
138 @key{LFD}: Linefeed or Newline; same as @kbd{C-j}
141 @key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
144 @key{DEL}: @key{Delete}, usually @strong{not} the same as
145 @key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
146 deleting invokes Emacs help)
149 @key{ESC}: Escape; same as @kbd{C-[}
152 @key{TAB}: Tab; same as @kbd{C-i}
159 Key sequences longer than one key (and some single-key sequences) are
160 written inside quotes or on lines by themselves, like this:
163 @kbd{M-x frobnicate-while-foo RET}
167 Any real spaces in such a key sequence should be ignored; only @key{SPC}
168 really means press the space key.
170 The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
171 that would be sent by pressing just @key{x} minus 96 (or 64 for
172 upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
173 terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
174 @acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
175 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
177 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
180 @kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
181 @kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON.
182 Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
184 @inforef{Text Characters, Text Characters, emacs}, and @inforef{Keys,
185 Keys, emacs}, for more information. (@xref{On-line manual}, for more
186 information about Info.)
188 @node Extended commands, On-line manual, Basic keys, FAQ notation
189 @section What does @file{M-x @var{command}} mean?
190 @cindex Extended commands
191 @cindex Commands, extended
192 @cindex M-x, meaning of
194 @kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
195 command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
196 what @kbd{M-x} and @key{RET} mean.)
198 @kbd{M-x} (by default) invokes the command
199 @code{execute-extended-command}. This command allows you to run any
200 Emacs command if you can remember the command's name. If you can't
201 remember the command's name, you can type @key{TAB} and @key{SPC} for
202 completion, @key{?} for a list of possibilities, and @kbd{M-p} and
203 @kbd{M-n} (or up-arrow and down-arrow on terminals that have these
204 editing keys) to see previous commands entered. An Emacs @dfn{command}
205 is an @dfn{interactive} Emacs function.
208 Your system administrator may have bound other key sequences to invoke
209 @code{execute-extended-command}. A function key labeled @kbd{Do} is a
210 good candidate for this, on keyboards that have such a key.
212 If you need to run non-interactive Emacs functions, see @ref{Evaluating
215 @node On-line manual, File-name conventions, Extended commands, FAQ notation
216 @section How do I read topic XXX in the on-line manual?
217 @cindex On-line manual, reading topics in
218 @cindex Reading topics in the on-line manual
219 @cindex Finding topics in the on-line manual
220 @cindex Info, finding topics in
222 When we refer you to some @var{topic} in the on-line manual, you can
223 read this manual node inside Emacs (assuming nothing is broken) by
224 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
226 This invokes Info, the GNU hypertext documentation browser. If you don't
227 already know how to use Info, type @key{?} from within Info.
229 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
230 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
232 If these commands don't work as expected, your system administrator may
233 not have installed the Info files, or may have installed them
234 improperly. In this case you should complain.
236 @xref{Getting a printed manual}, if you would like a paper copy of the
239 @node File-name conventions, Common acronyms, On-line manual, FAQ notation
240 @section What are @file{etc/SERVICE}, @file{src/config.h}, and @file{lisp/default.el}?
241 @cindex File-name conventions
242 @cindex Conventions for file names
243 @cindex Directories and files that come with Emacs
245 These are files that come with Emacs. The Emacs distribution is divided
246 into subdirectories; the important ones are @file{etc}, @file{lisp}, and
249 If you use Emacs, but don't know where it is kept on your system, start
250 Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
251 name displayed by this will be the full pathname of the installed
252 @file{etc} directory. (This full path is recorded in the Emacs variable
253 @code{data-directory}, and @kbd{C-h v} displays the value and the
254 documentation of a variable.)
256 The location of your Info directory (i.e., where on-line documentation
257 is stored) is kept in the variable @code{Info-default-directory-list}. Use
258 @kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
259 this variable, which will be a list of directory names. The last
260 directory in that list is probably where most Info files are stored. By
261 default, Info documentation is placed in @file{/usr/local/info}.
263 Some of these files are available individually via FTP or e-mail; see
264 @ref{Informational files for Emacs}. They all are available in the
265 source distribution. Many of the files in the @file{etc} directory are
266 also available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?}
267 (@kbd{M-x help-for-help}).
269 Your system administrator may have removed the @file{src} directory and
270 many files from the @file{etc} directory.
272 @node Common acronyms, , File-name conventions, FAQ notation
273 @section What are FSF, LPF, GNU, RMS, FTP, and GPL?
274 @cindex FSF, definition of
275 @cindex LPF, definition of
276 @cindex GNU, definition of
277 @cindex RMS, definition of
278 @cindex Stallman, Richard, acronym for
279 @cindex Richard Stallman, acronym for
280 @cindex FTP, definition of
281 @cindex GPL, definition of
282 @cindex Acronyms, definitions for
283 @cindex Common acronyms, definitions for
288 Free Software Foundation
291 League for Programming Freedom
297 Richard Matthew Stallman
300 File Transfer Protocol
303 GNU General Public License
307 Avoid confusing the FSF and the LPF. The LPF opposes
308 look-and-feel copyrights and software patents. The FSF aims to make
309 high quality free software available for everyone.
311 The word ``free'' in the title of the Free Software Foundation refers to
312 ``freedom,'' not ``zero cost.'' Anyone can charge any price for
313 GPL-covered software that they want to. However, in practice, the
314 freedom enforced by the GPL leads to low prices, because you can always
315 get the software for less money from someone else, since everyone has
316 the right to resell or give away GPL-covered software.
318 @c ------------------------------------------------------------
319 @node General questions, Getting help, FAQ notation, Top
320 @chapter General questions
321 @cindex General questions
323 This chapter contains general questions having to do with Emacs, the
324 Free Software Foundation, and related organizations.
328 * Real meaning of copyleft::
329 * Guidelines for newsgroup postings::
330 * Newsgroup archives::
332 * Unsubscribing from Emacs lists::
333 * Contacting the FSF::
336 @node The LPF, Real meaning of copyleft, General questions, General questions
337 @section What is the LPF?
338 @cindex LPF, description of
339 @cindex League for Programming Freedom
340 @cindex Software patents, opposition to
341 @cindex Patents for software, opposition to
343 The LPF opposes the expanding danger of software patents and
344 look-and-feel copyrights. More information on the LPF's views is
345 available at @uref{http://progfree.org/, the LPF home page}.
347 @node Real meaning of copyleft, Guidelines for newsgroup postings, The LPF, General questions
348 @section What is the real legal meaning of the GNU copyleft?
349 @cindex Copyleft, real meaning of
350 @cindex GPL, real meaning of
351 @cindex General Public License, real meaning of
352 @cindex Discussion of the GPL
354 The real legal meaning of the GNU General Public License (copyleft) will
355 only be known if and when a judge rules on its validity and scope.
356 There has never been a copyright infringement case involving the GPL to
357 set any precedents. Please take any discussion regarding this issue to
358 the newsgroup @uref{news:gnu.misc.discuss}, which was created to hold the
359 extensive flame wars on the subject.
364 The legal meaning of the GNU copyleft is less important than the spirit,
365 which is that Emacs is a free software project and that work pertaining
366 to Emacs should also be free software. ``Free'' means that all users
367 have the freedom to study, share, change and improve Emacs. To make
368 sure everyone has this freedom, pass along source code when you
369 distribute any version of Emacs or a related program, and give the
370 recipients the same freedom that you enjoyed.
373 @node Guidelines for newsgroup postings, Newsgroup archives, Real meaning of copyleft, General questions
374 @section What are appropriate messages for @uref{news:gnu.emacs.help}, @uref{news:gnu.emacs.bug}, @uref{news:comp.emacs}, etc.?
375 @cindex Newsgroups, appropriate messages for
376 @cindex GNU newsgroups, appropriate messages for
377 @cindex Usenet groups, appropriate messages for
378 @cindex Mailing lists, appropriate messages for
379 @cindex Posting messages to newsgroups
381 @cindex GNU mailing lists
382 The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
383 mailing list. (@xref{Informational files for Emacs}, if you want a copy
384 of the file.) For those lists which are gatewayed with newsgroups, it
385 lists both the newsgroup name and the mailing list address.
387 The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
388 in general. This includes Emacs along with various other
389 implementations, such as XEmacs, JOVE, MicroEmacs, Freemacs, MG,
390 Unipress, CCA, and Epsilon.
392 Many people post Emacs questions to @uref{news:comp.emacs} because they
393 don't receive any of the @code{gnu.*} newsgroups. Arguments have been
394 made both for and against posting GNU-Emacs-specific material to
395 @uref{news:comp.emacs}. You have to decide for yourself.
397 Messages advocating ``non-free'' software are considered unacceptable on
398 any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
399 which was created to hold the extensive flame-wars on the subject.
400 ``Non-free'' software includes any software for which the end user can't
401 freely modify the source code and exchange enhancements. Be careful to
402 remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
403 posting a followup that recommends such software.
405 @uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
406 posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
408 @node Newsgroup archives, Reporting bugs, Guidelines for newsgroup postings, General questions
409 @section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
410 @cindex Archived postings from @code{gnu.emacs.help}
411 @cindex Usenet archives for GNU groups
412 @cindex Old Usenet postings for GNU groups
414 The FSF has maintained archives of all of the GNU mailing lists for many
415 years, although there may be some unintentional gaps in coverage. The
416 archive is not particularly well organized or easy to retrieve
417 individual postings from, but pretty much everything is there.
419 The archive is at @uref{ftp://lists.gnu.org/}.
421 The archive can be browsed over the web at
422 @uref{http://lists.gnu.org/archive/html/, the GNU mail archive}.
424 Web-based Usenet search services, such as
425 @uref{http://groups.google.com/groups/dir?sel=33592484, Google}, also
426 archive the @code{gnu.*} groups.
428 You can read the archives of the @code{gnu.*} groups and post new
429 messages at @uref{http://gmane.org/, Gmane}.
431 @node Reporting bugs, Unsubscribing from Emacs lists, Newsgroup archives, General questions
432 @section Where should I report bugs and other problems with Emacs?
433 @cindex Bug reporting
434 @cindex Good bug reports
435 @cindex How to submit a bug report
436 @cindex Reporting bugs
438 The correct way to report Emacs bugs is to use the command
439 @kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
440 essential information and the correct e-mail address which is
441 @email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs.
442 Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the
443 newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
444 news to submit the bug report. This ensures a reliable return address
445 so you can be contacted for further details.
447 Be sure to read the ``Bugs'' section of the Emacs manual before reporting
448 a bug! The manual describes in detail how to submit a useful bug
449 report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
450 (@xref{On-line manual}, if you don't know how to read the manual.)
455 Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
456 effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
457 it takes the time of an unnecessarily large group of people, most of
458 whom are just users and have no idea how to fix these problem.
459 @email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
460 who are more likely to know what to do and have expressed a wish to
461 receive more messages about Emacs than the others.
464 RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
467 If you have reported a bug and you don't hear about a possible fix,
468 then after a suitable delay (such as a week) it is okay to post on
469 @code{gnu.emacs.help} asking if anyone can help you.
472 If you are unsure whether you have found a bug, consider the following
473 non-exhaustive list, courtesy of RMS:
476 If Emacs crashes, that is a bug. If Emacs gets compilation errors
477 while building, that is a bug. If Emacs crashes while building, that
478 is a bug. If Lisp code does not do what the documentation says it
482 @node Unsubscribing from Emacs lists, Contacting the FSF, Reporting bugs, General questions
483 @section How do I unsubscribe from this mailing list?
484 @cindex Unsubscribing from GNU mailing lists
485 @cindex Removing yourself from GNU mailing lists
487 If you are receiving a GNU mailing list named @var{list}, you might be
488 able to unsubscribe from it by sending a request to the address
489 @email{@var{list}-request@@gnu.org}. However, this will not work if you are
490 not listed on the main mailing list, but instead receive the mail from a
491 distribution point. In that case, you will have to track down at which
492 distribution point you are listed. Inspecting the @samp{Received} headers
493 on the mail messages may help, along with liberal use of the @samp{EXPN} or
494 @samp{VRFY} sendmail commands through @samp{telnet @var{site-address}
495 smtp}. Ask your postmaster for help, if you cannot figure out these
498 @node Contacting the FSF, , Unsubscribing from Emacs lists, General questions
499 @section What is the current address of the FSF?
500 @cindex Snail mail address of the FSF
501 @cindex Postal address of the FSF
502 @cindex Contracting the FSF
503 @cindex Free Software Foundation, contacting
517 @uref{http://www.gnu.org/}
520 Free Software Foundation@*
521 51 Franklin Street, Fifth Floor@*
522 Boston, MA 02110-1301@*
527 @cindex Ordering GNU software
528 For details on how to order items directly from the FSF, see the
529 @uref{http://www.gnu.org/order/order.html, GNU Web site}.
531 @c ------------------------------------------------------------
532 @node Getting help, Status of Emacs, General questions, Top
533 @chapter Getting help
536 This chapter tells you how to get help with Emacs
540 * Learning how to do something::
541 * Getting a printed manual::
542 * Emacs Lisp documentation::
543 * Installing Texinfo documentation::
544 * Printing a Texinfo file::
545 * Viewing Info files outside of Emacs::
546 * Informational files for Emacs::
547 * Help installing Emacs::
548 * Obtaining the FAQ::
551 @node Basic editing, Learning how to do something, Getting help, Getting help
552 @section I'm just starting Emacs; how do I do basic editing?
553 @cindex Basic editing with Emacs
554 @cindex Beginning editing
555 @cindex Tutorial, invoking the
556 @cindex Self-paced tutorial, invoking the
557 @cindex Help system, entering the
559 Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
560 @kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
561 is available in many foreign languages such as French, German, Japanese,
562 Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
563 to choose your language and start the tutorial.
565 Your system administrator may have changed @kbd{C-h} to act like
566 @key{DEL} to deal with local keyboards. You can use @kbd{M-x
567 help-for-help} instead to invoke help. To discover what key (if any)
568 invokes help on your system, type @kbd{M-x where-is @key{RET}
569 help-for-help @key{RET}}. This will print a comma-separated list of key
570 sequences in the echo area. Ignore the last character in each key
571 sequence listed. Each of the resulting key sequences invokes help.
573 Emacs help works best if it is invoked by a single key whose value
574 should be stored in the variable @code{help-char}.
576 @node Learning how to do something, Getting a printed manual, Basic editing, Getting help
577 @section How do I find out how to do something in Emacs?
578 @cindex Help for Emacs
579 @cindex Learning to do something in Emacs
580 @cindex Reference card for Emacs
581 @cindex Overview of help systems
583 There are several methods for finding out how to do things in Emacs.
587 @cindex Reading the Emacs manual
589 The complete text of the Emacs manual is available on-line via the Info
590 hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
591 Typing @key{h} immediately after entering Info will provide a short
592 tutorial on how to use it.
594 @cindex Lookup a subject in a manual
595 @cindex Index search in a manual
597 To quickly locate the section of the manual which discusses a certain
598 issue, or describes a command or a variable, type @kbd{C-h i m emacs
599 @key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
600 topic, the command, or the variable which you are looking for. If this
601 does not land you on the right place in the manual, press @kbd{,}
602 (comma) repeatedly until you find what you need. (The @kbd{i} and
603 @kbd{,} keys invoke the index-searching functions, which look for the
604 @var{topic} you type in all the indices of the Emacs manual.)
608 You can list all of the commands whose names contain a certain word
609 (actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
612 @cindex Command description in the manual
614 The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
615 for the name of a command, and then attempts to find the section in the
616 Emacs manual where that command is described.
618 @cindex Finding commands and variables
620 You can list all of the functions and variables whose names contain a
621 certain word using @kbd{M-x apropos}.
624 You can list all of the functions and variables whose documentation
625 matches a regular expression or a string, using @kbd{M-x
626 apropos-documentation}.
629 You can order a hardcopy of the manual from the FSF. @xref{Getting a
632 @cindex Reference cards, in other languages
634 You can get a printed reference card listing commands and keys to
635 invoke them. You can order one from the FSF for $2 (or 10 for $18),
636 or you can print your own from the @file{etc/refcards/refcard.tex} or
637 @file{etc/refcards/refcard.pdf} files in the Emacs distribution.
638 Beginning with version 21.1, the Emacs distribution comes with
639 translations of the reference card into several languages; look for
640 files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang}
641 is a two-letter code of the language. For example, the German version
642 of the reference card is in the files @file{etc/refcards/de-refcard.tex}
643 and @file{etc/recards/de-refcard.pdf}.
646 There are many other commands in Emacs for getting help and
647 information. To get a list of these commands, type @samp{?} after
652 @node Getting a printed manual, Emacs Lisp documentation, Learning how to do something, Getting help
653 @section How do I get a printed copy of the Emacs manual?
654 @cindex Printed Emacs manual, obtaining
655 @cindex Manual, obtaining a printed or HTML copy of
656 @cindex Emacs manual, obtaining a printed or HTML copy of
658 You can order a printed copy of the Emacs manual from the FSF. For
659 details see the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
661 @c The number 620 below is version-dependent!
662 The full Texinfo source for the manual also comes in the @file{doc/emacs}
663 directory of the Emacs distribution, if you're daring enough to try to
664 print out this several-hundred-page manual yourself (@pxref{Printing a Texinfo
667 If you absolutely have to print your own copy, and you don't have @TeX{},
668 you can get a PostScript or PDF (or HTML) version from
670 @uref{http://www.gnu.org/software/emacs/manual/}
672 @xref{Learning how to do something}, for how to view the manual on-line.
674 @node Emacs Lisp documentation, Installing Texinfo documentation, Getting a printed manual, Getting help
675 @section Where can I get documentation on Emacs Lisp?
676 @cindex Documentation on Emacs Lisp
677 @cindex Function documentation
678 @cindex Variable documentation
679 @cindex Emacs Lisp Reference Manual
680 @cindex Reference manual for Emacs Lisp
682 Within Emacs, you can type @kbd{C-h f} to get the documentation for a
683 function, @kbd{C-h v} for a variable.
685 For more information, the Emacs Lisp Reference Manual is available
686 on-line, in Info format. @xref{Top, Emacs Lisp,, elisp, The
687 Emacs Lisp Reference Manual}.
689 You can also order a hardcopy of the manual, details on ordering it from
690 FSF are on the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
692 An HTML version of the Emacs Lisp Reference Manual is available at
694 @uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
696 @node Installing Texinfo documentation, Printing a Texinfo file, Emacs Lisp documentation, Getting help
697 @section How do I install a piece of Texinfo documentation?
698 @cindex Texinfo documentation, installing
699 @cindex Installing Texinfo documentation
700 @cindex New Texinfo files, installing
701 @cindex Documentation, installing new Texinfo files
702 @cindex Info files, how to install
704 First, you must turn the Texinfo files into Info files. You may do this
705 using the stand-alone @file{makeinfo} program, available as part of the latest
708 @uref{ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-4.8.tar.gz}
710 and all mirrors of @samp{ftp.gnu.org} (for a list, @pxref{Current GNU
713 For information about the Texinfo format, read the Texinfo manual which
714 comes with the Texinfo package. This manual also comes installed in
715 Info format, so you can read it on-line; type @kbd{C-h i m texinfo
718 Alternatively, you could use the Emacs command @kbd{M-x
719 texinfo-format-buffer}, after visiting the Texinfo source file of the
720 manual you want to convert.
722 Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
723 resulting Info files in Emacs's Info tree. To install Info files,
728 Move the files to the @file{info} directory in the installed Emacs
729 distribution. @xref{File-name conventions}, if you don't know where that
733 Run the @code{install-info} command, which is part of the Texinfo
734 distribution, to update the main Info directory menu, like this:
737 install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
741 where @var{dir-path} is the full path to the directory where you copied
742 the produced Info file(s), and @var{file} is the name of the Info file
743 you produced and want to install.
745 If you don't have the @code{install-info} command installed, you can
746 edit the file @file{info/dir} in the installed Emacs distribution, and
747 add a line for the top level node in the Info package that you are
748 installing. Follow the examples already in this file. The format is:
751 * Topic: (relative-pathname). Short description of topic.
756 If you want to install Info files and you don't have the necessary
757 privileges, you have several options:
761 Info files don't actually need to be installed before being used.
762 You can use a prefix argument for the @code{info} command and specify
763 the name of the Info file in the minibuffer. This goes to the node
764 named @samp{Top} in that file. For example, to view a Info file named
765 @file{@var{info-file}} in your home directory, you can type this:
768 @kbd{C-u C-h i ~/@var{info-file} @key{RET}}
771 Alternatively, you can feed a file name to the @code{Info-goto-node}
772 command (invoked by pressing @key{g} in Info mode) by typing the name
773 of the file in parentheses, like this:
776 @kbd{C-h i g (~/@var{info-file}) @key{RET}}
780 You can create your own Info directory. You can tell Emacs where that
781 Info directory is by adding its pathname to the value of the variable
782 @code{Info-default-directory-list}. For example, to use a private Info
783 directory which is a subdirectory of your home directory named @file{Info},
784 you could put this in your @file{.emacs} file:
787 (setq Info-default-directory-list
788 (cons "~/Info" Info-default-directory-list))
791 You will need a top-level Info file named @file{dir} in this directory
792 which has everything the system @file{dir} file has in it, except it should
793 list only entries for Info files in that directory. You might not need
794 it if all files in this directory were referenced by other @file{dir}
795 files. The node lists from all @file{dir} files in
796 @code{Info-default-directory-list} are merged by the Info system.
800 @node Printing a Texinfo file, Viewing Info files outside of Emacs, Installing Texinfo documentation, Getting help
801 @section How do I print a Texinfo file?
802 @cindex Printing a Texinfo file
803 @cindex Texinfo file, printing
804 @cindex Printing documentation
806 You can't get nicely printed output from Info files; you must still have
807 the original Texinfo source file for the manual you want to print.
809 Assuming you have @TeX{} installed on your system, follow these steps:
814 Make sure the first line of the Texinfo file looks like this:
820 You may need to change @samp{texinfo} to the full pathname of the
821 @file{texinfo.tex} file, which comes with Emacs as
822 @file{doc/misc/texinfo.tex} (or copy or link it into the current directory).
825 Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
826 the name of the Texinfo source file for which you want to produce a
829 The @samp{texi2dvi} script is part of the GNU Texinfo distribution
830 (@pxref{Installing Texinfo documentation}).
833 Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
834 printing DVI files at your site. For example, if you have a PostScript
835 printer, run the @code{dvips} program to print the DVI file on that
840 To get more general instructions, retrieve the latest Texinfo package
841 (@pxref{Installing Texinfo documentation}).
843 @node Viewing Info files outside of Emacs, Informational files for Emacs, Printing a Texinfo file, Getting help
844 @section Can I view Info files without using Emacs?
845 @cindex Viewing Info files
846 @cindex Info file viewers
847 @cindex Alternative Info file viewers
849 Yes. Here are some alternative programs:
854 @code{info}, a stand-alone version of the Info program, comes as part of
855 the Texinfo package. @xref{Installing Texinfo documentation}, for
859 Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
860 You can get Tkinfo at
861 @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
865 @node Informational files for Emacs, Help installing Emacs, Viewing Info files outside of Emacs, Getting help
866 @section What informational files are available for Emacs?
867 @cindex Informational files included with Emacs
868 @cindex Files included with Emacs
869 @cindex @file{COPYING}, description of file
870 @cindex @file{DISTRIB}, description of file
871 @cindex @file{FTP}, description of file
872 @cindex @file{GNU}, description of file
873 @cindex @file{INTERVIEW}, description of file
874 @cindex @file{MACHINES}, description of file
875 @cindex @file{MAILINGLISTS}, description of file
876 @cindex @file{NEWS}, description of file
877 @cindex @file{SERVICE}, description of file
879 This isn't a frequently asked question, but it should be! A variety of
880 informational files about Emacs and relevant aspects of the GNU project
881 are available for you to read.
883 The following files are available in the @file{etc} directory of the
884 Emacs distribution (see @ref{File-name conventions}, if you're not sure
890 GNU General Public License
893 Emacs Availability Information
896 How to get GNU Software by Internet FTP
902 Richard Stallman discusses his public-domain UNIX-compatible software
903 system with BYTE editors
906 Status of Emacs on Various Machines and Systems
909 GNU Project Electronic Mailing Lists
912 Emacs news, a history of recent user-visible changes
915 GNU Service Directory
919 More GNU information, including back issues of the @cite{GNU's
922 @uref{http://www.gnu.org/bulletins/bulletins.html} and
924 @uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
926 @node Help installing Emacs, Obtaining the FAQ, Informational files for Emacs, Getting help
927 @section Where can I get help in installing Emacs?
928 @cindex Installation help
929 @cindex Help installing Emacs
931 @xref{Installing Emacs}, for some basic installation hints, and see
932 @ref{Problems building Emacs}, if you have problems with the installation.
934 The web-page @uref{http://www.fsf.org/resources/service/} lists
935 companies and individuals willing to sell you help in installing or
938 @node Obtaining the FAQ, , Help installing Emacs, Getting help
939 @section Where can I get the latest version of this FAQ?
940 @cindex FAQ, obtaining the
941 @cindex Latest FAQ version, obtaining the
943 The Emacs FAQ is distributed with Emacs in Info format. You can read it
944 by selecting the @samp{Emacs FAQ} option from the @samp{Help} menu of
945 the Emacs menu bar at the top of any Emacs frame, or by typing @kbd{C-h
946 C-f} (@kbd{M-x view-emacs-FAQ}).
949 @c ------------------------------------------------------------
950 @node Status of Emacs, Common requests, Getting help, Top
951 @chapter Status of Emacs
952 @cindex Status of Emacs
954 This chapter gives you basic information about Emacs, including its
955 latest version status.
958 * Origin of the term Emacs::
959 * Latest version of Emacs::
965 @node Origin of the term Emacs, Latest version of Emacs, Status of Emacs, Status of Emacs
966 @section Where does the name ``Emacs'' come from?
967 @cindex Origin of the term ``Emacs''
968 @cindex Emacs name origin
970 @cindex Original version of Emacs
972 Emacs originally was an acronym for Editor MACroS. RMS says he ``picked
973 the name Emacs because @key{E} was not in use as an abbreviation on ITS at
974 the time.'' The first Emacs was a set of macros written in 1976 at MIT
975 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
976 Editor and COrrector) under ITS on a PDP-10. RMS had already extended
977 TECO with a ``real-time'' full-screen mode with reprogrammable keys.
978 Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project
979 to unify the many divergent TECO command sets and key bindings at MIT,
980 and completed by RMS.
982 Many people have said that TECO code looks a lot like line noise; you
983 can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
984 implementation in Emacs Lisp (to find it, see @ref{Packages that do not
985 come with Emacs}); it would be an interesting project to run the
986 original TECO Emacs inside of Emacs.
989 For some not-so-serious alternative reasons for Emacs to have that
990 name, check out the file @file{etc/JOKES} (@pxref{File-name
993 @node Latest version of Emacs, New in Emacs 20, Origin of the term Emacs, Status of Emacs
994 @section What is the latest version of Emacs?
995 @cindex Version, latest
996 @cindex Latest version of Emacs
998 Emacs @value{VER} is the current version as of this writing.
1000 @node New in Emacs 20, New in Emacs 21, Latest version of Emacs, Status of Emacs
1001 @section What is different about Emacs 20?
1002 @cindex Differences between Emacs 19 and Emacs 20
1003 @cindex Emacs 20, new features in
1005 To find out what has changed in recent versions, type @kbd{C-h C-n}
1006 (@kbd{M-x view-emacs-news}). The oldest changes are at the bottom of
1007 the file, so you might want to read it starting there, rather than at
1010 The differences between Emacs versions 18 and 19 was rather dramatic;
1011 the introduction of frames, faces, and colors on windowing systems was
1012 obvious to even the most casual user.
1014 There are differences between Emacs versions 19 and 20 as well, but many
1015 are more subtle or harder to find. Among the changes are the inclusion
1016 of MULE code for languages that use non-Latin characters and for mixing
1017 several languages in the same document; the ``Customize'' facility for
1018 modifying variables without having to use Lisp; and automatic conversion
1019 of files from Macintosh, Microsoft, and Unix platforms.
1021 A number of older Lisp packages, such as Gnus, Supercite and the
1022 calendar/diary, have been updated and enhanced to work with Emacs 20,
1023 and are now included with the standard distribution.
1026 @node New in Emacs 21, New in Emacs 22, New in Emacs 20, Status of Emacs
1027 @section What is different about Emacs 21?
1028 @cindex Differences between Emacs 20 and Emacs 21
1029 @cindex Emacs 21, new features in
1030 @cindex Recently introduced features
1032 @cindex Variable-size fonts
1033 @cindex Toolbar support
1034 Emacs 21 features a thorough rewrite of the display engine. The new
1035 display engine supports variable-size fonts, images, and can play sounds
1036 on platforms which support that. As a result, the visual appearance of
1037 Emacs, when it runs on a windowed display, is much more reminiscent of
1038 modern GUI programs, and includes 3D widgets (used for the mode line and
1039 the scroll bars), a configurable and extensible toolbar, tooltips
1040 (a.k.a.@: balloon help), and other niceties.
1042 @cindex Colors on text-only terminals
1044 In addition, Emacs 21 supports faces on text-only terminals. This means
1045 that you can now have colors when you run Emacs on a GNU/Linux console
1046 and on @code{xterm} with @kbd{emacs -nw}.
1048 @node New in Emacs 22, , New in Emacs 21, Status of Emacs
1049 @section What is different about Emacs 22?
1050 @cindex Differences between Emacs 21 and Emacs 22
1051 @cindex Emacs 22, new features in
1052 @cindex Recently introduced features
1053 @cindex Default features
1056 @cindex GTK+ Toolkit
1057 @cindex Drag-and-drop
1059 Emacs can be built with GTK+ widgets, and supports drag-and-drop
1062 @cindex Supported systems
1064 Emacs 22 features support for GNU/Linux systems on S390 and x86-64
1065 machines, as well as support for the Mac OS X and Cygwin operating
1069 The native MS-Windows, and Mac OS X builds include full support
1070 for images, toolbar, and tooltips.
1073 Font Lock mode, Auto Compression mode, and File Name Shadow Mode are
1077 The maximum size of buffers has been doubled and is 256M on 32-bit
1081 Links can be followed with @kbd{mouse-1}, in addition to @kbd{mouse-2}.
1085 Mouse wheel support is enabled by default.
1088 Window fringes are customizable.
1091 The mode line of the selected window is now highlighted.
1094 The minibuffer prompt is displayed in a distinct face.
1097 Abbrev definitions are read automatically at startup.
1100 Grep mode is separate from Compilation mode and has many new options and
1101 commands specific to grep.
1104 The original Emacs macro system has been replaced by the new Kmacro
1105 package, which provides many new commands and features and a simple
1106 interface that uses the function keys F3 and F4. Macros are stored in a
1107 macro ring, and can be debugged and edited interactively.
1110 The Grand Unified Debugger (GUD) can be used with a full graphical user
1111 interface to GDB; this provides many features found in traditional
1112 development environments, making it easy to manipulate breakpoints, add
1113 watch points, display the call stack, etc. Breakpoints are visually
1114 indicated in the source buffer.
1118 Many new modes and packages have been included in Emacs, such as Calc,
1119 TRAMP, URL, IDO, CUA, ERC, rcirc, Table, Image-Dired, SES, Ruler, Org,
1120 PGG, Flymake, Password, Printing, Reveal, wdired, t-mouse, longlines,
1121 savehist, Conf mode, Python mode, DNS mode, etc.
1123 @cindex Multilingual Environment
1125 Leim is now part of Emacs. Unicode support has been much improved, and
1126 the following input methods have been added: belarusian, bulgarian-bds,
1127 bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian,
1128 latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard,
1129 lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345,
1130 russian-computer, sgml, slovenian, tamil-inscript, ucs,
1131 ukrainian-computer, vietnamese-telex, and welsh.
1133 The following language environments have also been added: Belarusian,
1134 Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6,
1135 Latin-7, Latvian, Lithuanian, Malayalam, Russian, Slovenian, Swedish,
1136 Tajik, Tamil, UTF-8, Ukrainian, Welsh, and Windows-1255.
1138 @cindex Documentation
1139 @cindex Emacs Lisp Manual
1141 In addition, Emacs 22 now includes the Emacs Lisp Reference Manual
1142 (@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro.
1145 Many other changes have been made in Emacs 22, use @kbd{C-h n} to get a
1148 @c ------------------------------------------------------------
1149 @node Common requests, Bugs and problems, Status of Emacs, Top
1150 @chapter Common requests
1151 @cindex Common requests
1154 * Setting up a customization file::
1157 * Debugging a customization file::
1158 * Displaying the current line or column::
1159 * Displaying the current file name in the titlebar::
1160 * Turning on abbrevs by default::
1161 * Associating modes with files::
1162 * Highlighting a region::
1163 * Replacing highlighted text::
1164 * Controlling case sensitivity::
1165 * Working with unprintable characters::
1166 * Searching for/replacing newlines::
1167 * Yanking text in isearch::
1168 * Wrapping words automatically::
1169 * Turning on auto-fill by default::
1171 * Checking TeX and *roff documents::
1172 * Changing load-path::
1173 * Using an already running Emacs process::
1174 * Compiler error messages::
1175 * Indenting switch statements::
1176 * Customizing C and C++ indentation::
1177 * Horizontal scrolling::
1179 * Turning off beeping::
1180 * Turning the volume down::
1181 * Automatic indentation::
1182 * Matching parentheses::
1183 * Hiding #ifdef lines::
1184 * Repeating commands::
1185 * Valid X resources::
1186 * Evaluating Emacs Lisp code::
1187 * Changing the length of a Tab::
1188 * Inserting text at the beginning of each line::
1189 * Underlining paragraphs::
1190 * Forcing the cursor to remain in the same column::
1191 * Forcing Emacs to iconify itself::
1192 * Using regular expressions::
1193 * Replacing text across multiple files::
1194 * Documentation for etags::
1195 * Disabling backups::
1196 * Disabling auto-save-mode::
1197 * Going to a line by number::
1198 * Modifying pull-down menus::
1199 * Deleting menus and menu options::
1200 * Turning on syntax highlighting::
1201 * Scrolling only one line::
1202 * Editing MS-DOS files::
1203 * Filling paragraphs with a single space::
1204 * Escape sequences in shell output::
1205 * Fullscreen mode on MS-Windows::
1208 @node Setting up a customization file, Using Customize, Common requests, Common requests
1209 @section How do I set up a @file{.emacs} file properly?
1210 @cindex @file{.emacs} file, setting up
1211 @cindex @file{.emacs} file, locating
1212 @cindex Init file, setting up
1213 @cindex Customization file, setting up
1215 @inforef{Init File, Init File, emacs}.
1217 In general, new Emacs users should not have @file{.emacs} files, because
1218 it causes confusing non-standard behavior. Then they send questions to
1219 @email{help-gnu-emacs@@gnu.org} asking why Emacs isn't behaving as
1222 Beginning with version 20.1, Emacs includes the new Customize facility
1223 (@pxref{Using Customize}). This allows users who are unfamiliar with
1224 Emacs Lisp to modify their @file{.emacs} files in a relatively
1225 straightforward way, using menus rather than Lisp code. Most packages
1226 support Customize as of this writing.
1228 While Customize might indeed make it easier to configure Emacs,
1229 consider taking a bit of time to learn Emacs Lisp and modifying your
1230 @file{.emacs} directly. Simple configuration options are described
1231 rather completely in @inforef{Init File, Init File, emacs}, for users
1232 interested in performing frequently requested, basic tasks.
1234 Sometimes users are unsure as to where their @file{.emacs} file should
1235 be found. Visiting the file as @file{~/.emacs} from Emacs will find
1238 @node Using Customize, Colors on a TTY, Setting up a customization file, Common requests
1239 @section How do I start using Customize?
1240 @cindex Customize groups
1241 @cindex Customizing variables
1242 @cindex Customizing faces
1244 The main Customize entry point is @kbd{M-x customize @key{RET}}. This
1245 command takes you to a buffer listing all the available Customize
1246 groups. From there, you can access all customizable options and faces,
1247 change their values, and save your changes to your init file.
1248 @inforef{Easy Customization, Easy Customization, emacs}.
1250 If you know the name of the group in advance (e.g. ``shell''), use
1251 @kbd{M-x customize-group @key{RET}}.
1253 If you wish to customize a single option, use @kbd{M-x customize-option
1254 @key{RET}}. This command prompts you for the name of the option to
1255 customize, with completion.
1257 @node Colors on a TTY, Debugging a customization file, Using Customize, Common requests
1258 @section How do I get colors and syntax highlighting on a TTY?
1259 @cindex Colors on a TTY
1260 @cindex Syntax highlighting on a TTY
1261 @cindex Console, colors
1263 In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
1264 i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when
1265 invoked as @samp{emacs -nw} on X, and MS-Windows. (Colors and faces were
1266 supported in the MS-DOS port since Emacs 19.29.) Emacs automatically
1267 detects color support at startup and uses it if available. If you think
1268 that your terminal supports colors, but Emacs won't use them, check the
1269 @code{termcap} entry for your display type for color-related
1272 The command @kbd{M-x list-colors-display} pops up a window which
1273 exhibits all the colors Emacs knows about on the current display.
1275 Syntax highlighting is on by default since version 22.1.
1277 @node Debugging a customization file, Displaying the current line or column, Colors on a TTY, Common requests
1278 @section How do I debug a @file{.emacs} file?
1279 @cindex Debugging @file{.emacs} file
1280 @cindex @file{.emacs} debugging
1281 @cindex Init file debugging
1282 @cindex @samp{-debug-init} option
1284 Start Emacs with the @samp{-debug-init} command-line option. This
1285 enables the Emacs Lisp debugger before evaluating your @file{.emacs}
1286 file, and places you in the debugger if something goes wrong. The top
1287 line in the @file{trace-back} buffer will be the error message, and the
1288 second or third line of that buffer will display the Lisp code from your
1289 @file{.emacs} file that caused the problem.
1291 You can also evaluate an individual function or argument to a function
1292 in your @file{.emacs} file by moving the cursor to the end of the
1293 function or argument and typing @kbd{C-x C-e} (@kbd{M-x
1296 Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
1297 variables which you are trying to set or use.
1299 @node Displaying the current line or column, Displaying the current file name in the titlebar, Debugging a customization file, Common requests
1300 @section How do I make Emacs display the current line (or column) number?
1301 @cindex @code{line-number-mode}
1302 @cindex Displaying the current line or column
1303 @cindex Line number, displaying the current
1304 @cindex Column, displaying the current
1305 @cindex @code{mode-line-format}
1307 To have Emacs automatically display the current line number of the point
1308 in the mode line, do @kbd{M-x line-number-mode}. You can also put the
1312 (setq line-number-mode t)
1316 in your @file{.emacs} file to achieve this whenever you start Emacs.
1317 (Line number display is on by default, unless your site-specific
1318 initialization disables it.) Note that Emacs will not display the line
1319 number if the buffer's size in bytes is larger than the value of the
1320 variable @code{line-number-display-limit}.
1322 You can similarly display the current column with
1323 @kbd{M-x column-number-mode}, or by putting the form
1326 (setq column-number-mode t)
1330 in your @file{.emacs} file.
1332 The @code{"%c"} format specifier in the variable @code{mode-line-format}
1333 will insert the current column's value into the mode line. See the
1334 documentation for @code{mode-line-format} (using @kbd{C-h v
1335 mode-line-format @key{RET}}) for more information on how to set and use
1338 Users of all Emacs versions can display the current column using the
1339 @samp{column} package written by @email{abraham@@dina.kvl.dk, Per
1340 Abrahamsen}. @xref{Packages that do not come with Emacs}, for
1341 instructions on how to get it.
1343 @cindex Set number capability in @code{vi} emulators
1344 None of the @code{vi} emulation modes provide the ``set number''
1345 capability of @code{vi} (as far as we know). The @samp{setnu} package
1346 written by @email{kyle@@wonderworks.com, Kyle Jones} provides this
1347 feature. So too does @samp{wb-line-number}, written by
1348 @email{naoki.y.nakamura@@nifty.com, Naoki Nakamura}.
1350 @node Displaying the current file name in the titlebar, Turning on abbrevs by default, Displaying the current line or column, Common requests
1351 @section How can I modify the titlebar to contain the current file name?
1352 @cindex Titlebar, displaying the current file name in
1353 @cindex File name, displaying in the titlebar
1354 @cindex @code{frame-title-format}
1356 The contents of an Emacs frame's titlebar is controlled by the variable
1357 @code{frame-title-format}, which has the same structure as the variable
1358 @code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x
1359 describe-variable} to get information about one or both of these
1362 By default, the titlebar for a frame does contain the name of the buffer
1363 currently being visited, except if there is a single frame. In such a
1364 case, the titlebar contains Emacs invocation name and the name of the
1365 machine at which Emacs was invoked. This is done by setting
1366 @code{frame-title-format} to the default value of
1369 (multiple-frames "%b" ("" invocation-name "@@" system-name))
1372 To modify the behavior such that frame titlebars contain the buffer's
1373 name regardless of the number of existing frames, include the following
1374 in your @file{.emacs}:
1377 (setq frame-title-format "%b")
1380 @node Turning on abbrevs by default, Associating modes with files, Displaying the current file name in the titlebar, Common requests
1381 @section How do I turn on abbrevs by default just in mode @var{mymode}?
1382 @cindex Abbrevs, turning on by default
1384 Put this in your @file{.emacs} file:
1388 (quietly-read-abbrev-file)
1391 (add-hook '@var{mymode}-mode-hook
1393 (setq abbrev-mode t)))
1396 Starting with Emacs 22, the standard abbrevs file is read automatically
1397 at startup, so the first of these two forms becomes unnecessary.
1399 @node Associating modes with files, Highlighting a region, Turning on abbrevs by default, Common requests
1400 @section How do I make Emacs use a certain major mode for certain files?
1401 @cindex Associating modes with files
1402 @cindex File extensions and modes
1403 @cindex @code{auto-mode-alist}, modifying
1404 @cindex Modes, associating with file extensions
1406 If you want to use a certain mode @var{foo} for all files whose names end
1407 with the extension @file{.@var{bar}}, this will do it for you:
1410 (setq auto-mode-alist (cons '("\\.@var{bar}\\'" . @var{foo}-mode) auto-mode-alist))
1413 Otherwise put this somewhere in the first line of any file you want to
1414 edit in the mode @var{foo} (in the second line, if the first line begins
1421 @cindex Major mode for shell scripts
1422 Beginning with Emacs 19, the variable @code{interpreter-mode-alist}
1423 specifies which mode to use when loading a shell script. (Emacs
1424 determines which interpreter you're using by examining the first line of
1425 the script.) Use @kbd{C-h v} (or @kbd{M-x describe-variable})
1426 on @code{interpreter-mode-alist} to learn more.
1428 @node Highlighting a region, Replacing highlighted text, Associating modes with files, Common requests
1429 @section How can I highlight a region of text in Emacs?
1430 @cindex Highlighting text
1431 @cindex Text, highlighting
1432 @cindex @code{transient-mark-mode}
1433 @cindex Region, highlighting a
1435 You can cause the region to be highlighted when the mark is active by
1439 (transient-mark-mode t)
1443 in your @file{.emacs} file.
1445 @node Replacing highlighted text, Controlling case sensitivity, Highlighting a region, Common requests
1446 @section How can I replace highlighted text with what I type?
1447 @cindex @code{delete-selection-mode}
1448 @cindex Replacing highlighted text
1449 @cindex Highlighting and replacing text
1451 Use @code{delete-selection-mode}, which you can start automatically by
1452 placing the following Lisp form in your @file{.emacs} file:
1455 (delete-selection-mode 1)
1458 According to the documentation string for @code{delete-selection-mode}
1459 (which you can read using @kbd{M-x describe-function @key{RET}
1460 delete-selection-mode @key{RET}}):
1463 When ON, typed text replaces the selection if the selection is active.
1464 When OFF, typed text is just inserted at point.
1467 This mode also allows you to delete (not kill) the highlighted region by
1470 @node Controlling case sensitivity, Working with unprintable characters, Replacing highlighted text, Common requests
1471 @section How do I control Emacs's case-sensitivity when searching/replacing?
1472 @cindex @code{case-fold-search}
1473 @cindex Case sensitivity of searches
1474 @cindex Searching without case sensitivity
1475 @cindex Ignoring case in searches
1477 For searching, the value of the variable @code{case-fold-search}
1478 determines whether they are case sensitive:
1481 (setq case-fold-search nil) ; make searches case sensitive
1482 (setq case-fold-search t) ; make searches case insensitive
1485 @cindex Case sensitivity in replacements
1486 @cindex Replacing, and case sensitivity
1487 @cindex @code{case-replace}
1488 Similarly, for replacing, the variable @code{case-replace} determines
1489 whether replacements preserve case.
1491 You can also toggle case sensitivity at will in isearch with @kbd{M-c}.
1493 To change the case sensitivity just for one major mode, use the major
1494 mode's hook. For example:
1497 (add-hook '@var{foo}-mode-hook
1499 (setq case-fold-search nil)))
1502 @node Working with unprintable characters, Searching for/replacing newlines, Controlling case sensitivity, Common requests
1503 @section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
1504 @cindex Unprintable characters, working with
1505 @cindex Working with unprintable characters
1506 @cindex Control characters, working with
1507 @cindex Eight-bit characters, working with
1508 @cindex Searching for unprintable characters
1509 @cindex Regexps and unprintable characters
1511 To search for a single character that appears in the buffer as, for
1512 example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}. (This assumes
1513 the value of @code{search-quote-char} is 17 (i.e., @kbd{C-q}).)
1514 Searching for @strong{all} unprintable characters is best done with a
1515 regular expression (@dfn{regexp}) search. The easiest regexp to use for
1516 the unprintable chars is the complement of the regexp for the printable
1522 Regexp for the printable chars: @samp{[\t\n\r\f -~]}
1525 Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
1529 To type these special characters in an interactive argument to
1530 @code{isearch-forward-regexp} or @code{re-search-forward}, you need to
1531 use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
1532 respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So,
1533 to search for unprintable characters using @code{re-search-forward}:
1535 @kbd{M-x re-search-forward @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET}}
1537 Using @code{isearch-forward-regexp}:
1539 @kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
1541 To delete all unprintable characters, simply use replace-regexp:
1543 @kbd{M-x replace-regexp @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET} @key{RET}}
1545 Replacing is similar to the above. To replace all unprintable
1546 characters with a colon, use:
1548 M-x replace-regexp @key{RET} [^ @key{TAB} C-q @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~] @key{RET} : @key{RET}
1550 @node Searching for/replacing newlines, Yanking text in isearch, Working with unprintable characters, Common requests
1551 @section How do I input a newline character in isearch or query-replace?
1552 @cindex Searching for newlines
1553 @cindex Replacing newlines
1555 Use @kbd{C-q C-j}. For more information, see @inforef{Special Isearch,
1556 Special Input for Incremental Search, emacs}.
1559 @node Yanking text in isearch, Wrapping words automatically, Searching for/replacing newlines, Common requests
1560 @section How do I copy text from the kill ring into the search string?
1561 @cindex Yanking text into the search string
1562 @cindex isearch yanking
1564 Use @kbd{M-y}. @inforef{Isearch Yank, Isearch Yanking, emacs}.
1566 @node Wrapping words automatically, Turning on auto-fill by default, Yanking text in isearch, Common requests
1567 @section How do I make Emacs wrap words for me?
1568 @cindex Wrapping word automatically
1569 @cindex Wrapping lines
1571 @cindex @code{auto-fill-mode}, introduction to
1572 @cindex Maximum line width, default value
1573 @cindex @code{fill-column}, default value
1575 Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
1576 The default maximum line width is 70, determined by the variable
1577 @code{fill-column}. To learn how to turn this on automatically, see
1578 @ref{Turning on auto-fill by default}.
1580 @node Turning on auto-fill by default, Spell-checkers, Wrapping words automatically, Common requests
1581 @section How do I turn on @code{auto-fill-mode} by default?
1582 @cindex @code{auto-fill-mode}, activating automatically
1583 @cindex Filling automatically
1584 @cindex Automatic entry to @code{auto-fill-mode}
1586 To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
1589 To turn it on for every buffer in a certain mode, you must use the hook
1590 for that mode. For example, to turn on @code{auto-fill} mode for all
1591 text buffers, including the following in your @file{.emacs} file:
1594 (add-hook 'text-mode-hook 'turn-on-auto-fill)
1597 If you want @code{auto-fill} mode on in all major modes, do this:
1600 (setq-default auto-fill-function 'do-auto-fill)
1603 @node Spell-checkers, Checking TeX and *roff documents, Turning on auto-fill by default, Common requests
1604 @section Where can I get a better spelling checker for Emacs?
1605 @cindex Checking spelling
1606 @cindex Spelling, checking text documents
1608 Use Ispell. @xref{Ispell}.
1610 @node Checking TeX and *roff documents, Changing load-path, Spell-checkers, Common requests
1611 @section How can I spell-check @TeX{} or *roff documents?
1612 @cindex Spelling, checking @TeX{} documents
1613 @cindex @TeX{} documents, checking spelling in
1615 Use Ispell. Ispell can handle @TeX{} and *roff documents.
1618 @node Changing load-path, Using an already running Emacs process, Checking TeX and *roff documents, Common requests
1619 @section How do I change @code{load-path}?
1620 @cindex @code{load-path}, modifying
1621 @cindex Modifying @code{load-path}
1622 @cindex Adding to @code{load-path}
1624 In general, you should only add to the @code{load-path}. You can add
1625 directory @var{/dir/subdir} to the load path like this:
1628 (setq load-path (cons "/dir/subdir/" load-path))
1631 To do this relative to your home directory:
1634 (setq load-path (cons "~/mysubdir/" load-path))
1637 @node Using an already running Emacs process, Compiler error messages, Changing load-path, Common requests
1638 @section How do I use an already running Emacs from another window?
1639 @cindex @code{emacsclient}
1640 @cindex Emacs server functions
1641 @cindex Using an existing Emacs process
1643 @code{emacsclient}, which comes with Emacs, is for editing a file using
1644 an already running Emacs rather than starting up a new Emacs. It does
1645 this by sending a request to the already running Emacs, which must be
1646 expecting the request.
1653 Emacs must have executed the @code{server-start} function for
1654 @samp{emacsclient} to work. This can be done either by a command line
1658 emacs -f server-start
1661 or by invoking @code{server-start} from @file{.emacs}:
1664 (if (@var{some conditions are met}) (server-start))
1667 When this is done, Emacs creates a Unix domain socket named
1668 @file{server} in @file{/tmp/emacs@var{userid}}. See
1669 @code{server-socket-dir}.
1671 To get your news reader, mail reader, etc., to invoke
1672 @samp{emacsclient}, try setting the environment variable @code{EDITOR}
1673 (or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may
1674 have to specify the full pathname of the @samp{emacsclient} program
1679 setenv EDITOR emacsclient
1681 # using full pathname
1682 setenv EDITOR /usr/local/emacs/etc/emacsclient
1685 EDITOR=emacsclient ; export EDITOR
1691 When @samp{emacsclient} is run, it connects to the socket and passes its
1692 command line options to Emacs, which at the next opportunity will visit
1693 the files specified. (Line numbers can be specified just like with
1694 Emacs.) The user will have to switch to the Emacs window by hand. When
1695 the user is done editing a file, the user can type @kbd{C-x #} (or
1696 @kbd{M-x server-edit}) to indicate this. If there is another buffer
1697 requested by @code{emacsclient}, Emacs will switch to it; otherwise
1698 @code{emacsclient} will exit, signaling the calling program to continue.
1700 @cindex @code{gnuserv}
1701 There is an enhanced version of @samp{emacsclient} called
1702 @samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman}
1703 (@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses
1704 Internet domain sockets, so it can work across most network connections.
1706 The most recent @samp{gnuserv} package is available at
1708 @uref{http://meltin.net/hacks/emacs/}
1712 @node Compiler error messages, Indenting switch statements, Using an already running Emacs process, Common requests
1713 @section How do I make Emacs recognize my compiler's funny error messages?
1714 @cindex Compiler error messages, recognizing
1715 @cindex Recognizing non-standard compiler errors
1716 @cindex Regexps for recognizing compiler errors
1717 @cindex Errors, recognizing compiler
1719 Customize the @code{compilation-error-regexp-alist} variable.
1721 @node Indenting switch statements, Customizing C and C++ indentation, Compiler error messages, Common requests
1722 @section How do I change the indentation for @code{switch}?
1723 @cindex @code{switch}, indenting
1724 @cindex Indenting of @code{switch}
1726 Many people want to indent their @code{switch} statements like this:
1744 The solution at first appears to be: set @code{c-indent-level} to 4 and
1745 @code{c-label-offset} to -2. However, this will give you an indentation
1746 spacing of four instead of two.
1748 The @emph{real} solution is to use @code{cc-mode} (the default mode for
1749 C programming in Emacs 20 and later) and add the following line to your
1753 (c-set-offset 'case-label '+)
1756 There appears to be no way to do this with the old @code{c-mode}.
1758 @node Customizing C and C++ indentation, Horizontal scrolling, Indenting switch statements, Common requests
1759 @section How to customize indentation in C, C@t{++}, and Java buffers?
1760 @cindex Indentation, how to customize
1761 @cindex Customize indentation
1763 The Emacs @code{cc-mode} features an interactive procedure for
1764 customizing the indentation style, which is fully explained in the
1765 @cite{CC Mode} manual that is part of the Emacs distribution, see
1766 @ref{Customizing Indentation, , Customization Indentation, ccmode,
1767 The CC Mode Manual}. Here's a short summary of the procedure:
1771 Go to the beginning of the first line where you don't like the
1772 indentation and type @kbd{C-c C-o}. Emacs will prompt you for the
1773 syntactic symbol; type @key{RET} to accept the default it suggests.
1776 Emacs now prompts for the offset of this syntactic symbol, showing the
1777 default (the current definition) inside parentheses. You can choose
1782 No extra indentation.
1784 Indent one basic offset.
1786 Outdent one basic offset.
1788 Indent two basic offsets
1790 Outdent two basic offsets.
1792 Indent half basic offset.
1794 Outdent half basic offset.
1798 After choosing one of these symbols, type @kbd{C-c C-q} to reindent
1799 the line or the block according to what you just specified.
1802 If you don't like the result, go back to step 1. Otherwise, add the
1803 following line to your @file{.emacs}:
1806 (c-set-offset '@var{syntactic-symbol} @var{offset})
1810 where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
1811 when you type @kbd{C-c C-o} at the beginning of the line, and
1812 @var{offset} is one of the indentation symbols listed above (@code{+},
1813 @code{/}, @code{0}, etc.) that you've chosen during the interactive
1817 Go to the next line whose indentation is not to your liking and repeat
1821 It is recommended to put all the resulting @code{(c-set-offset ...)}
1822 customizations inside a C mode hook, like this:
1825 (defun my-c-mode-hook ()
1828 (add-hook 'c-mode-hook 'my-c-mode-hook)
1832 Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
1833 'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
1834 might be unavailable when @code{cc-mode} is not loaded.
1836 Note that @code{c-mode-hook} runs for C source files only; use
1837 @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
1838 Java sources, etc. If you want the same customizations to be in
1839 effect in @emph{all} languages supported by @code{cc-mode}, use
1840 @code{c-mode-common-hook}.
1842 @node Horizontal scrolling, Overwrite mode, Customizing C and C++ indentation, Common requests
1843 @section How can I make Emacs automatically scroll horizontally?
1844 @cindex @code{hscroll-mode}
1845 @cindex Horizontal scrolling
1846 @cindex Scrolling horizontally
1848 In Emacs 21 and later, this is on by default: if the variable
1849 @code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
1850 automatically scrolls the display horizontally when point moves off the
1851 left or right edge of the window.
1853 Note that this is overridden by the variable
1854 @code{truncate-partial-width-windows} if that variable is non-nil
1855 and the current buffer is not full-frame width.
1857 In Emacs 20, use the @code{hscroll-mode}. Here is some information from
1858 the documentation, available by typing @kbd{C-h f hscroll-mode @key{RET}}:
1860 Automatically scroll horizontally when the point moves off the
1861 left or right edge of the window.
1865 Type @kbd{M-x hscroll-mode} to enable it in the current buffer.
1868 Type @kbd{M-x hscroll-global-mode} to enable it in every buffer.
1871 @code{turn-on-hscroll} is useful in mode hooks as in:
1874 (add-hook 'text-mode-hook 'turn-on-hscroll)
1878 @code{hscroll-margin} controls how close the cursor can get to the
1882 @code{hscroll-step-percent} controls how far to jump once we decide to do so.
1885 @node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests
1886 @section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
1887 @cindex @key{Insert}
1888 @cindex @code{overwrite-mode}
1889 @cindex Overwriting existing text
1890 @cindex Toggling @code{overwrite-mode}
1892 @kbd{M-x overwrite-mode} (a minor mode). This toggles
1893 @code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
1894 is as easy as another @kbd{M-x overwrite-mode}.
1896 On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
1898 @node Turning off beeping, Turning the volume down, Overwrite mode, Common requests
1899 @section How do I stop Emacs from beeping on a terminal?
1900 @cindex Beeping, turning off
1901 @cindex Visible bell
1902 @cindex Bell, visible
1904 @email{martin@@cc.gatech.edu, Martin R. Frank} writes:
1906 Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
1907 and set the visible bell to nothing.
1909 That is, put the following in your @code{TERMCAP} environment variable
1910 (assuming you have one):
1916 And evaluate the following Lisp form:
1919 (setq visible-bell t)
1922 @node Turning the volume down, Automatic indentation, Turning off beeping, Common requests
1923 @section How do I turn down the bell volume in Emacs running under X?
1924 @cindex Bell, volume of
1925 @cindex Volume of bell
1927 On X Window system, you can adjust the bell volume and duration for all
1928 programs with the shell command @code{xset}.
1930 Invoking @code{xset} without any arguments produces some basic
1931 information, including the following:
1934 usage: xset [-display host:dpy] option ...
1937 To set bell volume, pitch and duration:
1938 b [vol [pitch [dur]]] b on
1941 @node Automatic indentation, Matching parentheses, Turning the volume down, Common requests
1942 @section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
1943 @cindex Indenting new lines
1944 @cindex New lines, indenting of
1945 @cindex Previous line, indenting according to
1946 @cindex Text indentation
1948 Such behavior is automatic in Emacs 20 and later. From the
1949 @file{etc/NEWS} file for Emacs 20.2:
1952 ** In Text mode, now only blank lines separate paragraphs. This makes
1953 it possible to get the full benefit of Adaptive Fill mode in Text mode,
1954 and other modes derived from it (such as Mail mode). @key{TAB} in Text
1955 mode now runs the command @code{indent-relative}; this makes a practical
1956 difference only when you use indented paragraphs.
1958 As a result, the old Indented Text mode is now identical to Text mode,
1959 and is an alias for it.
1961 If you want spaces at the beginning of a line to start a paragraph, use
1962 the new mode, Paragraph Indent Text mode.
1965 @cindex Prefixing lines
1967 If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
1968 by default}), you can tell Emacs to prefix every line with a certain
1969 character sequence, the @dfn{fill prefix}. Type the prefix at the
1970 beginning of a line, position point after it, and then type @kbd{C-x .}
1971 (@code{set-fill-prefix}) to set the fill prefix. Thereafter,
1972 auto-filling will automatically put the fill prefix at the beginning of
1973 new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
1974 prefix when refilling the paragraph.
1976 If you have paragraphs with different levels of indentation, you will
1977 have to set the fill prefix to the correct value each time you move to a
1978 new paragraph. There are many packages available to deal with this
1979 (@pxref{Packages that do not come with Emacs}). Look for ``fill'' and
1980 ``indent'' keywords for guidance.
1982 @node Matching parentheses, Hiding #ifdef lines, Automatic indentation, Common requests
1983 @section How do I show which parenthesis matches the one I'm looking at?
1984 @cindex Parentheses, matching
1985 @cindex @file{paren.el}
1986 @cindex Highlighting matching parentheses
1987 @cindex Pairs of parentheses, highlighting
1988 @cindex Matching parentheses
1990 Call @code{show-paren-mode} in your @file{.emacs} file:
1996 You can also enable this mode by selecting the @samp{Paren Match
1997 Highlighting} option from the @samp{Options} menu of the Emacs menu bar
1998 at the top of any Emacs frame.
2000 Alternatives to this mode include:
2005 If you're looking at a right parenthesis (or brace or bracket) you can
2006 delete it and reinsert it. Emacs will momentarily move the cursor to
2007 the matching parenthesis.
2010 @kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
2011 will skip over one set of balanced parentheses, so you can see which
2012 parentheses match. (You can train it to skip over balanced brackets
2013 and braces at the same time by modifying the syntax table.)
2015 @cindex Show matching paren as in @code{vi}
2017 Here is some Emacs Lisp that will make the @key{%} key show the matching
2018 parenthesis, like in @code{vi}. In addition, if the cursor isn't over a
2019 parenthesis, it simply inserts a % like normal.
2022 ;; By an unknown contributor
2024 (global-set-key "%" 'match-paren)
2026 (defun match-paren (arg)
2027 "Go to the matching paren if on a paren; otherwise insert %."
2029 (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
2030 ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
2031 (t (self-insert-command (or arg 1)))))
2036 @node Hiding #ifdef lines, Repeating commands, Matching parentheses, Common requests
2037 @section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
2038 @cindex @code{#ifdef}, selective display of
2039 @cindex @code{hide-ifdef-mode}
2040 @cindex Hiding @code{#ifdef} text
2041 @cindex Selectively displaying @code{#ifdef} code
2043 @kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want
2044 to investigate @file{cpp.el}, which is distributed with Emacs.
2046 @node Repeating commands, Valid X resources, Hiding #ifdef lines, Common requests
2047 @section How do I repeat a command as many times as possible?
2048 @cindex Repeating commands many times
2049 @cindex Commands, repeating many times
2050 @cindex @code{.}, equivalent to @code{vi} command
2052 As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
2053 that repeats the last command. If you preface it with a prefix
2054 argument, the prefix arg is applied to the command.
2056 You can also type @kbd{C-x @key{ESC} @key{ESC}}
2057 (@code{repeat-complex-command}) to reinvoke commands that used the
2058 minibuffer to get arguments. In @code{repeat-complex-command} you can
2059 type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
2060 keyboard has these keys) to scan through all the different complex
2061 commands you've typed.
2063 To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and
2064 @kbd{C-x )} to make a keyboard macro that invokes the command and then
2065 type @kbd{C-x e}. (@inforef{Keyboard Macros, Keyboard Macros, emacs}.)
2067 If you're really desperate for the @code{.} command in @code{vi} that
2068 redoes the last insertion/deletion, use VIPER, a @code{vi} emulation
2069 mode which comes with Emacs, and which appears to support it.
2071 @node Valid X resources, Evaluating Emacs Lisp code, Repeating commands, Common requests
2072 @section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
2073 @cindex Resources, X
2075 @cindex Setting X resources
2077 @inforef{X Resources, X Resources, emacs}.
2079 You can also use a resource editor, such as editres (for X11R5 and
2080 onwards), to look at the resource names for the menu bar, assuming Emacs
2081 was compiled with the X toolkit.
2083 @node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests
2084 @section How do I execute (``evaluate'') a piece of Emacs Lisp code?
2085 @cindex Evaluating Lisp code
2086 @cindex Lisp forms, evaluating
2088 There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
2089 Emacs Lisp @dfn{form}:
2094 If you want it evaluated every time you run Emacs, put it in a file
2095 named @file{.emacs} in your home directory. This is known as ``your
2096 @file{.emacs} file,'' and contains all of your personal customizations.
2099 You can type the form in the @file{*scratch*} buffer, and then type
2100 @key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form
2101 will be inserted in the buffer.
2104 In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
2105 before or around point.
2108 Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
2109 before point and prints its value in the echo area.
2112 Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
2113 form in the minibuffer which will be evaluated once you press @key{RET}.
2116 You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
2117 forms in a file. (To do this from Lisp use the function @code{load}
2120 The functions @code{load-library}, @code{eval-region},
2121 @code{eval-buffer}, @code{require}, and @code{autoload} are also
2122 useful; see @ref{Emacs Lisp documentation}, if you want to learn more
2127 @node Changing the length of a Tab, Inserting text at the beginning of each line, Evaluating Emacs Lisp code, Common requests
2128 @section How do I change Emacs's idea of the @key{TAB} character's length?
2130 @cindex Length of tab character
2131 @cindex @code{default-tab-width}
2133 Set the variable @code{default-tab-width}. For example, to set
2134 @key{TAB} stops every 10 characters, insert the following in your
2138 (setq default-tab-width 10)
2141 Do not confuse variable @code{tab-width} with variable
2142 @code{tab-stop-list}. The former is used for the display of literal
2143 @key{TAB} characters. The latter controls what characters are inserted
2144 when you press the @key{TAB} character in certain modes.
2146 @node Inserting text at the beginning of each line, Underlining paragraphs, Changing the length of a Tab, Common requests
2147 @section How do I insert <some text> at the beginning of every line?
2148 @cindex Prefixing a region with some text
2149 @cindex Prefix character, inserting in mail/news replies
2150 @cindex Replies to mail/news, inserting a prefix character
2151 @cindex @code{mail-yank-prefix}
2152 @cindex Mail replies, inserting a prefix character
2153 @cindex News replies, inserting a prefix character
2155 To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
2156 @key{RET} ^ @key{RET} your text @key{RET}}.
2158 To do this to a region, use @code{string-insert-rectangle}.
2159 Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
2160 want to prefix, move the cursor to last line to be prefixed, and type
2161 @kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole
2162 buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
2164 If you are trying to prefix a yanked mail message with @samp{>}, you
2165 might want to set the variable @code{mail-yank-prefix}. In Message
2166 buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;}
2167 runs the function @code{comment-region}, it is a general-purpose
2168 mechanism to comment regions) (@pxref{Changing the included text prefix}).
2170 @node Underlining paragraphs, Forcing the cursor to remain in the same column, Inserting text at the beginning of each line, Common requests
2171 @section How do I insert @samp{_^H} before each character in a region to get an underlined paragraph?
2172 @cindex Underlining a region of text
2173 @cindex @code{underline-region}
2175 Mark the region and then type @kbd{M-x underline-region @key{RET}}.
2177 @node Forcing the cursor to remain in the same column, Forcing Emacs to iconify itself, Underlining paragraphs, Common requests
2178 @section How do I make Emacs behave like this: when I go up or down, the cursor should stay in the same column even if the line is too short?
2179 @cindex @code{picture-mode}
2180 @cindex Remaining in the same column, regardless of contents
2181 @cindex Vertical movement in empty documents
2183 Use @kbd{M-x picture-mode}.
2185 See also the variable @code{track-eol} and the command
2186 @code{set-goal-column} bound to @kbd{C-x C-n}
2187 (@pxref{Moving Point, , , emacs, The GNU Emacs Manual}).
2189 @node Forcing Emacs to iconify itself, Using regular expressions, Forcing the cursor to remain in the same column, Common requests
2190 @section How do I tell Emacs to iconify itself?
2191 @cindex Iconification under the X Window System
2192 @cindex X Window System and iconification
2193 @cindex Suspending Emacs
2195 @kbd{C-z} iconifies Emacs when running under X and suspends Emacs
2196 otherwise. @inforef{Frame Commands, Frame Commands, emacs}.
2198 @node Using regular expressions, Replacing text across multiple files, Forcing Emacs to iconify itself, Common requests
2199 @section How do I use regexps (regular expressions) in Emacs?
2201 @cindex Regular expressions
2202 @cindex Differences between Unix and Emacs regexps
2203 @cindex Unix regexps, differences from Emacs
2204 @cindex Text strings, putting regexps in
2206 @inforef{Regexp Backslash, Regexp Backslash, emacs}.
2208 The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
2209 are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is
2210 @samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)}
2211 in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
2213 Note the doubled backslashes!
2218 Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
2219 (@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@:
2220 @kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
2221 characters not to match.
2224 The character syntax regexps (e.g., @samp{\sw}) are not
2225 meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This
2226 is actually typical for regexp syntax.)
2230 @node Replacing text across multiple files, Documentation for etags, Using regular expressions, Common requests
2231 @section How do I perform a replace operation across more than one file?
2232 @cindex Replacing strings across files
2233 @cindex Multiple files, replacing across
2234 @cindex Files, replacing strings across multiple
2235 @cindex Recursive search/replace operations
2237 As of Emacs 19.29, Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x
2238 d}) supports the command @code{dired-do-query-replace} (@kbd{Q}), which
2239 allows users to replace regular expressions in multiple files.
2241 You can use this command to perform search/replace operations on
2242 multiple files by following the following steps:
2246 Assemble a list of files you want to operate on with either
2247 @code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}.
2250 Mark all files in the resulting Dired buffer using @kbd{t}.
2253 Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked
2257 To accept all replacements in each file, hit @kbd{!}.
2260 Another way to do the same thing is to use the ``tags'' feature of
2261 Emacs: it includes the command @code{tags-query-replace} which performs
2262 a query-replace across all the files mentioned in the @file{TAGS} file.
2263 @inforef{Tags Search, Tags Search, emacs}.
2265 @node Documentation for etags, Disabling backups, Replacing text across multiple files, Common requests
2266 @section Where is the documentation for @code{etags}?
2267 @cindex Documentation for @code{etags}
2268 @cindex @code{etags}, documentation for
2270 The @code{etags} man page should be in the same place as the
2271 @code{emacs} man page.
2273 Quick command-line switch descriptions are also available. For example,
2276 @node Disabling backups, Disabling auto-save-mode, Documentation for etags, Common requests
2277 @section How do I disable backup files?
2278 @cindex Backups, disabling
2279 @cindex Disabling backups
2281 You probably don't want to do this, since backups are useful, especially
2282 when something goes wrong.
2284 To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
2285 load @code{dired-x} by adding the following to your @file{.emacs} file:
2288 (add-hook 'dired-load-hook
2293 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
2294 You can make omitting the default for new dired buffers by putting the
2295 following in your @file{.emacs}:
2298 (add-hook 'dired-mode-hook 'dired-omit-toggle)
2301 If you're tired of seeing backup files whenever you do an @samp{ls} at
2302 the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU
2303 @code{ls} is part of the GNU Fileutils package, available from
2304 @samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
2306 To disable or change the way backups are made, @inforef{Backup Names, ,
2309 @cindex Backup files in a single directory
2310 Beginning with Emacs 21.1, you can control where Emacs puts backup files
2311 by customizing the variable @code{backup-directory-alist}. This
2312 variable's value specifies that files whose names match specific patters
2313 should have their backups put in certain directories. A typical use is
2314 to add the element @code{("." . @var{dir})} to force Emacs to put
2315 @strong{all} backup files in the directory @file{dir}.
2317 @node Disabling auto-save-mode, Going to a line by number, Disabling backups, Common requests
2318 @section How do I disable @code{auto-save-mode}?
2319 @cindex Disabling @code{auto-save-mode}
2321 @cindex Saving at frequent intervals
2323 You probably don't want to do this, since auto-saving is useful,
2324 especially when Emacs or your computer crashes while you are editing a
2327 Instead, you might want to change the variable
2328 @code{auto-save-interval}, which specifies how many keystrokes Emacs
2329 waits before auto-saving. Increasing this value forces Emacs to wait
2330 longer between auto-saves, which might annoy you less.
2332 You might also want to look into Sebastian Kremer's @code{auto-save}
2333 package (@pxref{Packages that do not come with Emacs}). This
2334 package also allows you to place all auto-save files in one directory,
2335 such as @file{/tmp}.
2337 To disable or change how @code{auto-save-mode} works, @inforef{Auto
2340 @node Going to a line by number, Modifying pull-down menus, Disabling auto-save-mode, Common requests
2341 @section How can I go to a certain line given its number?
2342 @cindex Going to a line by number
2343 @cindex Compilation error messages
2344 @cindex Recompilation
2346 Are you sure you indeed need to go to a line by its number? Perhaps all
2347 you want is to display a line in your source file for which a compiler
2348 printed an error message? If so, compiling from within Emacs using the
2349 @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
2350 effective way of doing that. Emacs automatically intercepts the compile
2351 error messages, inserts them into a special buffer called
2352 @code{*compilation*}, and lets you visit the locus of each message in
2353 the source. Type @kbd{C-x `} to step through the offending lines one by
2354 one (starting with Emacs 22, you can also use @kbd{M-g M-p} and
2355 @kbd{M-g M-n} to go to the previous and next matches directly). Click
2356 @kbd{Mouse-2} or press @key{RET} on a message text in the
2357 @code{*compilation*} buffer to go to the line whose number is mentioned
2360 But if you indeed need to go to a certain text line, type @kbd{M-g M-g}
2361 (which is the default binding of the @code{goto-line} function starting
2362 with Emacs 22). Emacs will prompt you for the number of the line and go
2365 You can do this faster by invoking @code{goto-line} with a numeric
2366 argument that is the line's number. For example, @kbd{C-u 286 M-g M-g}
2367 will jump to line number 286 in the current buffer.
2369 @node Modifying pull-down menus, Deleting menus and menu options, Going to a line by number, Common requests
2370 @section How can I create or modify new pull-down menu options?
2371 @cindex Pull-down menus, creating or modifying
2372 @cindex Menus, creating or modifying
2373 @cindex Creating new menu options
2374 @cindex Modifying pull-down menus
2375 @cindex Menus and keymaps
2376 @cindex Keymaps and menus
2378 Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
2379 represents a local or global keymap. Selecting a menu title with the
2380 mouse displays that keymap's non-@code{nil} contents in the form of a menu.
2382 So to add a menu option to an existing menu, all you have to do is add a
2383 new definition to the appropriate keymap. Adding a @samp{Forward Word}
2384 item to the @samp{Edit} menu thus requires the following Lisp code:
2387 (define-key global-map
2388 [menu-bar edit forward]
2389 '("Forward word" . forward-word))
2393 The first line adds the entry to the global keymap, which includes
2394 global menu bar entries. Replacing the reference to @code{global-map}
2395 with a local keymap would add this menu option only within a particular
2398 The second line describes the path from the menu-bar to the new entry.
2399 Placing this menu entry underneath the @samp{File} menu would mean
2400 changing the word @code{edit} in the second line to @code{file}.
2402 The third line is a cons cell whose first element is the title that will
2403 be displayed, and whose second element is the function that will be
2404 called when that menu option is invoked.
2406 To add a new menu, rather than a new option to an existing menu, we must
2407 define an entirely new keymap:
2410 (define-key global-map [menu-bar words]
2411 (cons "Words" (make-sparse-keymap "Words")))
2414 The above code creates a new sparse keymap, gives it the name
2415 @samp{Words}, and attaches it to the global menu bar. Adding the
2416 @samp{Forward Word} item to this new menu would thus require the
2420 (define-key global-map
2421 [menu-bar words forward]
2422 '("Forward word" . forward-word))
2426 Note that because of the way keymaps work, menu options are displayed
2427 with the more recently defined items at the top. Thus if you were to
2428 define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
2429 order), the menu option @samp{baz} would appear at the top, and
2430 @samp{foo} would be at the bottom.
2432 One way to avoid this problem is to use the function @code{define-key-after},
2433 which works the same as @code{define-key}, but lets you modify where items
2434 appear. The following Lisp code would insert the @samp{Forward Word}
2435 item in the @samp{Edit} menu immediately following the @samp{Undo} item:
2439 (lookup-key global-map [menu-bar edit])
2441 '("Forward word" . forward-word)
2445 Note how the second and third arguments to @code{define-key-after} are
2446 different from those of @code{define-key}, and that we have added a new
2447 (final) argument, the function after which our new key should be
2450 To move a menu option from one position to another, simply evaluate
2451 @code{define-key-after} with the appropriate final argument.
2453 More detailed information---and more examples of how to create and
2454 modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
2455 ``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on
2458 @node Deleting menus and menu options, Turning on syntax highlighting, Modifying pull-down menus, Common requests
2459 @section How do I delete menus and menu options?
2460 @cindex Deleting menus and menu options
2461 @cindex Menus, deleting
2463 The simplest way to remove a menu is to set its keymap to @samp{nil}.
2464 For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
2468 (define-key global-map [menu-bar words] nil)
2471 Similarly, removing a menu option requires redefining a keymap entry to
2472 @code{nil}. For example, to delete the @samp{Forward word} menu option
2473 from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
2477 (define-key global-map [menu-bar edit forward] nil)
2480 @node Turning on syntax highlighting, Scrolling only one line, Deleting menus and menu options, Common requests
2481 @section How do I turn on syntax highlighting?
2482 @cindex Syntax highlighting
2483 @cindex @code{font-lock-mode}
2484 @cindex Highlighting based on syntax
2485 @cindex Colorizing text
2486 @cindex FAQ, @code{font-lock-mode}
2488 @code{font-lock-mode} is the standard way to have Emacs perform syntax
2489 highlighting in the current buffer. It is enabled by default in Emacs
2492 With @code{font-lock-mode} turned on, different types of text will
2493 appear in different colors. For instance, in a programming mode,
2494 variables will appear in one face, keywords in a second, and comments in
2497 @cindex hilit19 is deprecated
2498 Earlier versions of Emacs supported hilit19, a similar package. Use of
2499 hilit19 is now considered non-standard, although @file{hilit19.el} comes
2500 with the stock Emacs distribution. It is no longer maintained.
2502 To turn @code{font-lock-mode} off within an existing buffer, use
2503 @kbd{M-x font-lock-mode @key{RET}}.
2505 In Emacs 21 and earlier versions, you could use the following code in
2506 your @file{.emacs} file to turn on @code{font-lock-mode} globally:
2509 (global-font-lock-mode 1)
2512 Highlighting a buffer with @code{font-lock-mode} can take quite a while,
2513 and cause an annoying delay in display, so several features exist to
2516 @cindex Just-In-Time syntax highlighting
2517 In Emacs 21 and later, turning on @code{font-lock-mode} automatically
2518 activates the new @dfn{Just-In-Time fontification} provided by
2519 @code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
2520 portions of buffer until you actually need to see them, and can also
2521 fontify while Emacs is idle. This makes display of the visible portion
2522 of a buffer almost instantaneous. For details about customizing
2523 @code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
2525 @cindex Levels of syntax highlighting
2526 @cindex Decoration level, in @code{font-lock-mode}
2527 In versions of Emacs before 21, different levels of decoration are
2528 available, from slight to gaudy. More decoration means you need to wait
2529 more time for a buffer to be fontified (or a faster machine). To
2530 control how decorated your buffers should become, set the value of
2531 @code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
2532 @code{nil} value indicating default (usually minimum) decoration, and a
2533 @code{t} value indicating the maximum decoration. For the gaudiest
2534 possible look, then, include the line
2537 (setq font-lock-maximum-decoration t)
2541 in your @file{.emacs} file. You can also set this variable such that
2542 different modes are highlighted in a different ways; for more
2543 information, see the documentation for
2544 @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
2545 describe-variable @key{RET}}).
2547 Also see the documentation for the function @code{font-lock-mode},
2548 available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
2549 describe-function @key{RET} font-lock-mode @key{RET}}).
2551 To print buffers with the faces (i.e., colors and fonts) intact, use
2552 @kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
2553 ps-print-region-with-faces}. You will need a way to send text to a
2554 PostScript printer, or a PostScript interpreter such as Ghostscript;
2555 consult the documentation of the variables @code{ps-printer-name},
2556 @code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
2558 @node Scrolling only one line, Editing MS-DOS files, Turning on syntax highlighting, Common requests
2559 @section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
2560 @cindex Scrolling only one line
2561 @cindex Reducing the increment when scrolling
2563 Customize the @code{scroll-conservatively} variable with @kbd{M-x
2564 customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
2565 to a large value like, say, 10000. For an explanation of what this
2566 means, @inforef{Auto Scrolling, Auto Scrolling, emacs}.
2568 Alternatively, use the following Lisp form in your @file{.emacs}:
2571 (setq scroll-conservatively most-positive-fixnum)
2574 @node Editing MS-DOS files, Filling paragraphs with a single space, Scrolling only one line, Common requests
2575 @section How can I edit MS-DOS files using Emacs?
2576 @cindex Editing MS-DOS files
2577 @cindex MS-DOS files, editing
2578 @cindex Microsoft files, editing
2579 @cindex Windows files, editing
2581 As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
2582 performed transparently. You can open MS-DOS files on a Unix system,
2583 edit it, and save it without having to worry about the file format.
2585 When editing an MS-DOS style file, the mode line will indicate that it
2586 is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh,
2587 the string @samp{(DOS)} will appear near the left edge of the mode line;
2588 on DOS and Windows, where the DOS end-of-line (EOL) format is the
2589 default, a backslash (@samp{\}) will appear in the mode line.
2591 If you are running a version of Emacs before 20.1, get @code{crypt++}
2592 (@pxref{Packages that do not come with Emacs}). Among other things,
2593 @code{crypt++} transparently modifies MS-DOS files as they are loaded
2594 and saved, allowing you to ignore the different conventions that Unix
2595 and MS-DOS have for delineating the end of a line.
2597 @node Filling paragraphs with a single space, Escape sequences in shell output, Editing MS-DOS files, Common requests
2598 @section How can I tell Emacs to fill paragraphs with a single space after each period?
2599 @cindex One space following periods
2600 @cindex Single space following periods
2601 @cindex Periods, one space following
2603 Add the following line to your @file{.emacs} file:
2606 (setq sentence-end-double-space nil)
2609 @node Escape sequences in shell output, Fullscreen mode on MS-Windows, Filling paragraphs with a single space, Common requests
2610 @section Why these strange escape sequences from @code{ls} from the Shell mode?
2611 @cindex Escape sequences in @code{ls} output
2612 @cindex @code{ls} in Shell mode
2614 This happens because @code{ls} is aliased to @samp{ls --color} in your
2615 shell init file. You have two alternatives to solve this:
2619 Make the alias conditioned on the @code{EMACS} variable in the
2620 environment. When Emacs runs a subsidiary shell, it exports the
2621 @code{EMACS} variable to that shell, with value equal to the absolute
2622 file name of Emacs. You can
2623 unalias @code{ls} when that happens, thus limiting the alias to your
2624 interactive sessions.
2627 Install the @code{ansi-color} package (bundled with Emacs 21.1 and
2628 later), which converts these ANSI escape sequences into colors.
2631 @node Fullscreen mode on MS-Windows, , Escape sequences in shell output, Common requests
2632 @section How can I start Emacs in fullscreen mode on MS-Windows?
2633 @cindex Maximize frame
2634 @cindex Fullscreen mode
2636 Use the function @code{w32-send-sys-command}. For example, you can
2637 put the following in your @file{.emacs} file:
2640 (add-hook 'term-setup-hook
2641 #'(lambda () (w32-send-sys-command ?\xF030)))
2644 To avoid the slightly distracting visual effect of Emacs starting with
2645 its default frame size and then growing to fullscreen, you can add an
2646 @samp{Emacs.Geometry} entry to the Windows registry settings (see
2647 @pxref{(emacs)X Resources}).
2649 To compute the correct values for width and height, first maximize the
2650 Emacs frame and then evaluate @code{(frame-height)} and
2651 @code{(frame-width)} with @kbd{M-:}.
2653 @c ------------------------------------------------------------
2654 @node Bugs and problems, Compiling and installing Emacs, Common requests, Top
2655 @chapter Bugs and problems
2656 @cindex Bugs and problems
2658 The Emacs manual lists some common kinds of trouble users could get
2659 into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
2660 Emacs Manual}, so you might look there if the problem you encounter
2661 isn't described in this chapter. If you decide you've discovered a bug,
2662 see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
2663 instructions how to do that.
2665 The file @file{etc/PROBLEMS} in the Emacs distribution lists various
2666 known problems with building and using Emacs on specific platforms;
2667 type @kbd{C-h C-e} to read it.
2670 * Problems with very large files::
2671 * ^M in the shell buffer::
2672 * Shell process exits abnormally::
2673 * Problems with Shell Mode on MS-Windows::
2674 * Termcap/Terminfo entries for Emacs::
2675 * Spontaneous entry into isearch-mode::
2676 * Problems talking to certain hosts::
2677 * Errors with init files::
2678 * Emacs ignores X resources::
2679 * Emacs ignores frame parameters::
2680 * Emacs takes a long time to visit files::
2681 * Editing files with $ in the name::
2682 * Shell mode loses the current directory::
2683 * Security risks with Emacs::
2684 * Dired claims that no file is on this line::
2687 @node Problems with very large files, ^M in the shell buffer, Bugs and problems, Bugs and problems
2688 @section Does Emacs have problems with files larger than 8 megabytes?
2689 @cindex Very large files, opening
2690 @cindex Large files, opening
2691 @cindex Opening very large files
2692 @cindex Maximum file size
2693 @cindex Files, maximum size
2695 Old versions (i.e., anything before 19.29) of Emacs had problems editing
2696 files larger than 8 megabytes. In versions 19.29 and later, the maximum
2697 buffer size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes.
2698 And in Emacs 22, the maximum buffer size has been increased to
2699 268,435,455 bytes (or 256 MBytes) on 32-bit machines.
2701 @node ^M in the shell buffer, Shell process exits abnormally, Problems with very large files, Bugs and problems
2702 @section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
2703 @cindex Shell buffer, echoed commands and @samp{^M} in
2704 @cindex Echoed commands in @code{shell-mode}
2706 Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
2707 make them go away. If that doesn't work, you have several options:
2709 For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
2714 if ("$EMACS" =~ /*) then
2715 if ($?tcsh) unset edit
2721 Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file:
2728 Alternatively, use @code{csh} in your shell buffers instead of
2729 @code{tcsh}. One way is:
2732 (setq explicit-shell-file-name "/bin/csh")
2736 and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
2740 setenv ESHELL /bin/csh
2744 (You must start Emacs over again with the environment variable properly
2745 set for this to take effect.)
2747 You can also set the @code{ESHELL} environment variable in Emacs Lisp
2748 with the following Lisp form,
2751 (setenv "ESHELL" "/bin/csh")
2754 The above solutions try to prevent the shell from producing the
2755 @samp{^M} characters in the first place. If this is not possible
2756 (e.g., if you use a Windows shell), you can get Emacs to remove these
2757 characters from the buffer by adding this to your @file{.emacs} init
2761 (add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
2764 On a related note: if your shell is echoing your input line in the shell
2765 buffer, you might want to customize the @code{comint-process-echoes}
2766 variable in your shell buffers, or try the following command in your
2767 shell start-up file:
2770 stty -icrnl -onlcr -echo susp ^Z
2773 @node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems
2774 @section Why do I get ``Process shell exited abnormally with code 1''?
2775 @cindex Abnormal exits from @code{shell-mode}
2776 @cindex @code{shell-mode} exits
2777 @cindex Process shell exited
2779 The most likely reason for this message is that the @samp{env} program
2780 is not properly installed. Compile this program for your architecture,
2781 and install it with @samp{a+x} permission in the architecture-dependent
2782 Emacs program directory. (You can find what this directory is at your
2783 site by inspecting the value of the variable @code{exec-directory} by
2784 typing @kbd{C-h v exec-directory @key{RET}}.)
2786 You should also check for other programs named @samp{env} in your path
2787 (e.g., SunOS has a program named @file{/usr/bin/env}). We don't
2788 understand why this can cause a failure and don't know a general
2789 solution for working around the problem in this case.
2791 The @samp{make clean} command will remove @samp{env} and other vital
2792 programs, so be careful when using it.
2794 It has been reported that this sometimes happened when Emacs was started
2795 as an X client from an xterm window (i.e., had a controlling tty) but the
2796 xterm was later terminated.
2798 See also @samp{PROBLEMS} (in the @file{etc} subdirectory of the
2799 top-level directory when you unpack the Emacs source) for other
2800 possible causes of this message.
2802 @node Problems with Shell Mode on MS-Windows, Termcap/Terminfo entries for Emacs, Shell process exits abnormally, Bugs and problems
2803 @section Why do I get an error message when I try to run @kbd{M-x shell}?
2805 @cindex Shell Mode, and MS-Windows
2806 @cindex @code{explicit-shell-file-name}
2807 On MS-Windows, this might happen because Emacs tries to look for the
2808 shell in a wrong place. The default file name @file{/bin/sh} is
2809 usually incorrect for non-Unix systems. If you know where your shell
2810 executable is, set the variable @code{explicit-shell-file-name} in
2811 your @file{.emacs} file to point to its full file name, like this:
2814 (setq explicit-shell-file-name "d:/shells/bash.exe")
2817 If you don't know what shell does Emacs use, try the @kbd{M-!}
2818 command; if that works, put the following line into your
2822 (setq explicit-shell-file-name shell-file-name)
2825 @cindex Antivirus programs, and Shell Mode
2826 Some people have trouble with Shell Mode because of intrusive
2827 antivirus software; disabling the resident antivirus program solves
2828 the problems in those cases.
2830 @node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems
2831 @section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
2834 @cindex Emacs entries for termcap/terminfo
2836 The termcap entry for terminal type @samp{emacs} is ordinarily put in
2837 the @samp{TERMCAP} environment variable of subshells. It may help in
2838 certain situations (e.g., using rlogin from shell buffer) to add an
2839 entry for @samp{emacs} to the system-wide termcap file. Here is a
2840 correct termcap entry for @samp{emacs}:
2846 To make a terminfo entry for @samp{emacs}, use @code{tic} or
2847 @code{captoinfo}. You need to generate
2848 @file{/usr/lib/terminfo/e/emacs}. It may work to simply copy
2849 @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
2851 Having a termcap/terminfo entry will not enable the use of full screen
2852 programs in shell buffers. Use @kbd{M-x terminal-emulator} for that
2855 A workaround to the problem of missing termcap/terminfo entries is to
2856 change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
2857 in your shell start up file. @code{csh} users could put this in their
2858 @file{.cshrc} files:
2861 if ("$term" == emacs) set term=dumb
2864 @node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems
2865 @section Why does Emacs spontaneously start displaying @samp{I-search:} and beeping?
2866 @cindex Spontaneous entry into isearch-mode
2867 @cindex isearch-mode, spontaneous entry into
2868 @cindex Beeping without obvious reason
2870 Your terminal (or something between your terminal and the computer) is
2871 sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving
2872 these characters and interpreting them as commands. (The @kbd{C-s}
2873 character normally invokes the @code{isearch-forward} command.) For
2874 possible solutions, see @ref{Handling C-s and C-q with flow control}.
2876 @node Problems talking to certain hosts, Errors with init files, Spontaneous entry into isearch-mode, Bugs and problems
2877 @section Why can't Emacs talk to certain hosts (or certain hostnames)?
2878 @cindex Hosts, Emacs cannot talk to
2879 @cindex @code{gethostbyname}, problematic version
2881 The problem may be that Emacs is linked with a wimpier version of
2882 @code{gethostbyname} than the rest of the programs on the machine. This
2883 is often manifested as a message on startup of ``X server not responding.
2884 Check your @samp{DISPLAY} environment variable.'' or a message of
2885 ``Unknown host'' from @code{open-network-stream}.
2887 On a Sun, this may be because Emacs had to be linked with the static C
2888 library. The version of @code{gethostbyname} in the static C library
2889 may only look in @file{/etc/hosts} and the NIS (YP) maps, while the
2890 version in the dynamic C library may be smart enough to check DNS in
2891 addition to or instead of NIS. On a Motorola Delta running System V
2892 R3.6, the version of @code{gethostbyname} in the standard library works,
2893 but the one that works with NIS doesn't (the one you get with -linet).
2894 Other operating systems have similar problems.
2901 Explicitly add the host you want to communicate with to @file{/etc/hosts}.
2904 Relink Emacs with this line in @file{src/config.h}:
2907 #define LIBS_SYSTEM -lresolv
2911 Replace @code{gethostbyname} and friends in @file{libc.a} with more
2912 useful versions such as the ones in @file{libresolv.a}. Then relink
2916 If you are actually running NIS, make sure that @code{ypbind} is
2917 properly told to do DNS lookups with the correct command line switch.
2921 @node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems
2922 @section Why does Emacs say @samp{Error in init file}?
2923 @cindex Error in @file{.emacs}
2924 @cindex Error in init file
2925 @cindex Init file, errors in
2926 @cindex @file{.emacs} file, errors in
2927 @cindex Debugging @file{.emacs} file
2929 An error occurred while loading either your @file{.emacs} file or the
2930 system-wide file @file{lisp/default.el}. Emacs 21.1 and later pops the
2931 @file{*Messages*} buffer, and puts there some additional information
2932 about the error, to provide some hints for debugging.
2934 For information on how to debug your @file{.emacs} file, see
2935 @ref{Debugging a customization file}.
2937 It may be the case that you need to load some package first, or use a
2938 hook that will be evaluated after the package is loaded. A common case
2939 of this is explained in @ref{Terminal setup code works after Emacs has
2942 @node Emacs ignores X resources, Emacs ignores frame parameters, Errors with init files, Bugs and problems
2943 @section Why does Emacs ignore my X resources (my .Xdefaults file)?
2944 @cindex X resources being ignored
2945 @cindex Ignored X resources
2946 @cindex @file{.Xdefaults}
2948 As of version 19, Emacs searches for X resources in the files specified
2949 by the following environment variables:
2953 @item @code{XFILESEARCHPATH}
2954 @item @code{XUSERFILESEARCHPATH}
2955 @item @code{XAPPLRESDIR}
2959 This emulates the functionality provided by programs written using the
2962 @code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
2963 of file names separated by colons. @code{XAPPLRESDIR} should be a list
2964 of directory names separated by colons.
2966 Emacs searches for X resources:
2971 specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
2974 then in the value of the @samp{XENVIRONMENT} environment variable,
2979 or if that is unset, in the file named
2980 @file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
2981 the name of the machine Emacs is running on),
2986 then in the screen-specific and server-wide resource properties provided
2992 or if those properties are unset, in the file named @file{~/.Xdefaults}
2998 then in the files listed in @samp{XUSERFILESEARCHPATH},
3003 or in files named @file{@var{lang}/Emacs} in directories listed in
3004 @samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
3005 environment variable), if the @samp{LANG} environment variable is set,
3007 or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
3009 or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
3012 or in @file{~/Emacs},
3017 then in the files listed in @code{XFILESEARCHPATH}.
3021 @node Emacs ignores frame parameters, Emacs takes a long time to visit files, Emacs ignores X resources, Bugs and problems
3022 @section Why don't my customizations of the frame parameters work?
3023 @cindex Frame parameters
3025 This probably happens because you have set the frame parameters in the
3026 variable @code{initial-frame-alist}. That variable holds parameters
3027 used only for the first frame created when Emacs starts. To customize
3028 the parameters of all frames, change the variable
3029 @code{default-frame-alist} instead.
3031 These two variables exist because many users customize the initial frame
3032 in a special way. For example, you could determine the position and
3033 size of the initial frame, but would like to control the geometry of the
3034 other frames by individually positioning each one of them.
3037 @node Emacs takes a long time to visit files, Editing files with $ in the name, Emacs ignores frame parameters, Bugs and problems
3038 @section Why does Emacs take 20 seconds to visit a file?
3039 @cindex Visiting files takes a long time
3040 @cindex Delay when visiting files
3041 @cindex Files, take a long time to visit
3043 Old versions of Emacs (i.e., versions before Emacs 20.x) often
3044 encountered this when the master lock file, @file{!!!SuperLock!!!}, has
3045 been left in the lock directory somehow. Delete it.
3047 @email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug
3048 where an exclusive create succeeds but returns an error status. This
3049 can cause the same problem. Since Emacs's file locking doesn't work
3050 over NFS anyway, the best solution is to recompile Emacs with
3051 @code{CLASH_DETECTION} undefined.
3053 @node Editing files with $ in the name, Shell mode loses the current directory, Emacs takes a long time to visit files, Bugs and problems
3054 @section How do I edit a file with a @samp{$} in its name?
3055 @cindex Editing files with @samp{$} in the name
3056 @cindex @samp{$} in file names
3057 @cindex File names containing @samp{$}, editing
3059 When entering a file name in the minibuffer, Emacs will attempt to expand
3060 a @samp{$} followed by a word as an environment variable. To suppress
3061 this behavior, type @kbd{$$} instead.
3063 @node Shell mode loses the current directory, Security risks with Emacs, Editing files with $ in the name, Bugs and problems
3064 @section Why does shell mode lose track of the shell's current directory?
3065 @cindex Current directory and @code{shell-mode}
3066 @cindex @code{shell-mode} and current directory
3067 @cindex Directory, current in @code{shell-mode}
3069 Emacs has no way of knowing when the shell actually changes its
3070 directory. This is an intrinsic limitation of Unix. So it tries to
3071 guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed
3072 by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
3073 with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
3074 correctly guess the shell's new current directory. A huge variety of
3075 fixes and enhancements to shell mode for this problem have been written
3076 to handle this problem (@pxref{Finding a package with particular
3079 You can tell Emacs the shell's current directory with the command
3082 @node Security risks with Emacs, Dired claims that no file is on this line, Shell mode loses the current directory, Bugs and problems
3083 @section Are there any security risks in Emacs?
3084 @cindex Security with Emacs
3085 @cindex @samp{movemail} and security
3086 @cindex @code{file-local-variable} and security
3087 @cindex Synthetic X events and security
3088 @cindex X events and security
3093 The @file{movemail} incident. (No, this is not a risk.)
3095 In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
3096 chapter 4. The site at LBL had installed the @file{/etc/movemail}
3097 program setuid root. (As of version 19, @file{movemail} is in your
3098 architecture-specific directory; type @kbd{C-h v exec-directory
3099 @key{RET}} to see what it is.) Since @code{movemail} had not been
3100 designed for this situation, a security hole was created and users could
3101 get root privileges.
3103 @code{movemail} has since been changed so that this security hole will
3104 not exist, even if it is installed setuid root. However,
3105 @code{movemail} no longer needs to be installed setuid root, which
3106 should eliminate this particular risk.
3108 We have heard unverified reports that the 1988 Internet worm took
3109 advantage of this configuration problem.
3112 The @code{file-local-variable} feature. (Yes, a risk, but easy to
3115 There is an Emacs feature that allows the setting of local values for
3116 variables when editing a file by including specially formatted text near
3117 the end of the file. This feature also includes the ability to have
3118 arbitrary Emacs Lisp code evaluated when the file is visited.
3119 Obviously, there is a potential for Trojan horses to exploit this
3122 As of Emacs 22, Emacs has a list of local variables that are known to
3123 be safe to set. If a file tries to set any variable outside this
3124 list, it asks the user to confirm whether the variables should be set.
3125 You can also tell Emacs whether to allow the evaluation of Emacs Lisp
3126 code found at the bottom of files by setting the variable
3127 @code{enable-local-eval}.
3129 For more information, @inforef{File Variables, File Variables, emacs}.
3132 Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
3135 Emacs accepts synthetic X events generated by the @code{SendEvent}
3136 request as though they were regular events. As a result, if you are
3137 using the trivial host-based authentication, other users who can open X
3138 connections to your X workstation can make your Emacs process do
3139 anything, including run other processes with your privileges.
3141 The only fix for this is to prevent other users from being able to open
3142 X connections. The standard way to prevent this is to use a real
3143 authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using
3144 the @code{xauth} program has any effect, then you are probably using
3145 @samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior
3146 authentication method; ask your system administrator.
3148 If real authentication is not a possibility, you may be satisfied by
3149 just allowing hosts access for brief intervals while you start your X
3150 programs, then removing the access. This reduces the risk somewhat by
3151 narrowing the time window when hostile users would have access, but
3152 @emph{does not eliminate the risk}.
3154 On most computers running Unix and X, you enable and disable
3155 access using the @code{xhost} command. To allow all hosts access to
3163 at the shell prompt, which (on an HP machine, at least) produces the
3167 access control disabled, clients can connect from any host
3170 To deny all hosts access to your X server (except those explicitly
3171 allowed by name), use
3177 On the test HP computer, this command generated the following message:
3180 access control enabled, only authorized clients can connect
3185 @node Dired claims that no file is on this line, , Security risks with Emacs, Bugs and problems
3186 @section Dired says, @samp{no file on this line} when I try to do something.
3187 @cindex Dired does not see a file
3189 @c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
3191 Chances are you're using a localized version of Unix that doesn't use US
3192 date format in dired listings. You can check this by looking at dired
3193 listings or by typing @kbd{ls -l} to a shell and looking at the dates that
3196 Dired uses a regular expression to find the beginning of a file name.
3197 In a long Unix-style directory listing (@samp{ls -l}), the file name
3198 starts after the date. The regexp has thus been written to look for the
3199 date, the format of which can vary on non-US systems.
3201 There are two approaches to solving this. The first one involves
3202 setting things up so that @samp{ls -l} outputs US date format. This can
3203 be done by setting the locale. See your OS manual for more information.
3205 The second approach involves changing the regular expression used by
3206 dired, @code{directory-listing-before-filename-regexp}.
3208 @c ------------------------------------------------------------
3209 @node Compiling and installing Emacs, Finding Emacs and related packages, Bugs and problems, Top
3210 @chapter Compiling and installing Emacs
3211 @cindex Compiling and installing Emacs
3214 * Installing Emacs::
3216 * Problems building Emacs::
3219 @node Installing Emacs, Updating Emacs, Compiling and installing Emacs, Compiling and installing Emacs
3220 @section How do I install Emacs?
3221 @cindex Installing Emacs
3222 @cindex Unix systems, installing Emacs on
3223 @cindex Downloading and installing Emacs
3224 @cindex Retrieving and installing Emacs
3225 @cindex Building Emacs from source
3226 @cindex Source code, building Emacs from
3227 @cindex Unpacking and installing Emacs
3229 This answer is meant for users of Unix and Unix-like systems. Users of
3230 other operating systems should see the series of questions beginning
3231 with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
3232 and binaries, and how to install Emacs on those systems.
3234 For Unix and Unix-like systems, the easiest way is often to compile it
3235 from scratch. You will need:
3240 Emacs sources. @xref{Current GNU distributions}, for a list of ftp sites
3241 that make them available. On @file{ftp.gnu.org}, the main GNU
3242 distribution site, sources are available as
3244 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-@value{VER}.tar.gz}
3246 The above will obviously change as new versions of Emacs come out. For
3247 instance, when Emacs 24.3 is released, it will most probably be
3250 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-24.3.tar.gz}
3252 Again, you should use one of the GNU mirror sites (see @ref{Current GNU
3253 distributions}, and adjust the URL accordingly) so as to reduce load on
3257 @code{gzip}, the GNU compression utility. You can get @code{gzip} via
3258 anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile
3259 and install without much trouble on most systems. Once you have
3260 retrieved the Emacs sources, you will probably be able to uncompress
3261 them with the command
3264 gunzip --verbose emacs-@value{VER}.tar.gz
3268 changing the Emacs version (@value{VER}), as necessary. Once
3269 @code{gunzip} has finished doing its job, a file by the name of
3270 @file{emacs-@value{VER}.tar} should be in your build directory.
3273 @code{tar}, the @dfn{tape archiving} program, which moves multiple files
3274 into and out of archive files, or @dfn{tarfiles}. All of the files
3275 comprising the Emacs source come in a single tarfile, and must be
3276 extracted using @code{tar} before you can build Emacs. Typically, the
3277 extraction command would look like
3280 tar -xvvf emacs-@value{VER}.tar
3284 The @samp{x} indicates that we want to extract files from this tarfile,
3285 the two @samp{v}s force verbose output, and the @samp{f} tells
3286 @code{tar} to use a disk file, rather than one on the tape drive.
3288 If you're using GNU @code{tar} (available at mirrors of
3289 @file{ftp.gnu.org}), you can combine this step and the previous one by
3293 tar -zxvvf emacs-@value{VER}.tar.gz
3297 The additional @samp{z} at the beginning of the options list tells GNU
3298 @code{tar} to uncompress the file with @code{gunzip} before extracting
3299 the tarfile's components.
3303 At this point, the Emacs sources (all 70+ megabytes of them) should be
3304 sitting in a directory called @file{emacs-@value{VER}}. On most common
3305 Unix and Unix-like systems, you should be able to compile Emacs (with X
3306 Window system support) with the following commands:
3309 cd emacs-@value{VER} # change directory to emacs-@value{VER}
3310 ./configure # configure Emacs for your particular system
3311 make # use Makefile to build components, then Emacs
3314 If the @code{make} completes successfully, the odds are fairly good that
3315 the build has gone well. (@xref{Problems building Emacs}, if you weren't
3318 By default, Emacs is installed in the following directories:
3321 @item /usr/local/bin
3324 @item /usr/local/share/emacs/@value{VER}
3325 Lisp code and support files.
3327 @item /usr/local/info
3331 To install files in those default directories, become the superuser and
3338 Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
3339 and any Emacs Info files that might be in @file{/usr/local/info}.
3341 Much more verbose instructions (with many more hints and suggestions)
3342 come with the Emacs sources, in the file @file{INSTALL}.
3344 @node Updating Emacs, Problems building Emacs, Installing Emacs, Compiling and installing Emacs
3345 @section How do I update Emacs to the latest version?
3346 @cindex Updating Emacs
3348 @xref{Installing Emacs}, and follow the instructions there for
3351 Most files are placed in version-specific directories. Emacs
3352 @value{VER}, for instance, places files in
3353 @file{/usr/local/share/emacs/@value{VER}}.
3355 Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs
3356 binary) and documentation in @file{/usr/local/info}. Back up these
3357 files before you upgrade, and you shouldn't have too much trouble.
3359 @node Problems building Emacs, , Updating Emacs, Compiling and installing Emacs
3360 @section What should I do if I have trouble building Emacs?
3361 @cindex Problems building Emacs
3362 @cindex Errors when building Emacs
3364 First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
3365 source) to see if there is already a solution for your problem. Next,
3366 look for other questions in this FAQ that have to do with Emacs
3367 installation and compilation problems.
3369 If you'd like to have someone look at your problem and help solve it,
3370 see @ref{Help installing Emacs}.
3372 If you cannot find a solution in the documentation, send a message to
3373 @email{bug-gnu-emacs@@gnu.org}.
3375 Please don't post it to @uref{news:gnu.emacs.help} or send e-mail to
3376 @email{help-gnu-emacs@@gnu.org}. For further guidelines, see
3377 @ref{Guidelines for newsgroup postings} and @ref{Reporting bugs}.
3380 @c ------------------------------------------------------------
3381 @node Finding Emacs and related packages, Major packages and programs, Compiling and installing Emacs, Top
3382 @chapter Finding Emacs and related packages
3383 @cindex Finding Emacs and related packages
3386 * Finding Emacs on the Internet::
3387 * Finding a package with particular functionality::
3388 * Packages that do not come with Emacs::
3389 * Current GNU distributions::
3390 * Difference between Emacs and XEmacs::
3391 * Emacs for minimalists::
3392 * Emacs for MS-DOS::
3393 * Emacs for Windows::
3394 * Emacs for GNUstep::
3395 * Emacs for Apple computers::
3396 * Modes for various languages::
3399 @node Finding Emacs on the Internet, Finding a package with particular functionality, Finding Emacs and related packages, Finding Emacs and related packages
3400 @section Where can I get Emacs on the net (or by snail mail)?
3401 @cindex Finding Emacs on the Internet
3402 @cindex Snail mail, ordering Emacs via
3403 @cindex Postal service, ordering Emacs via
3404 @cindex Distribution, retrieving Emacs
3405 @cindex Internet, retrieving from
3407 Look in the files @file{etc/DISTRIB} and @file{etc/FTP} for
3408 information on nearby archive sites. If you don't already have Emacs,
3409 see @ref{Informational files for Emacs}, for how to get these files.
3411 @xref{Installing Emacs}, for information on how to obtain and build the latest
3412 version of Emacs, and see @ref{Current GNU distributions}, for a list of
3413 archive sites that make GNU software available.
3415 @node Finding a package with particular functionality, Packages that do not come with Emacs, Finding Emacs on the Internet, Finding Emacs and related packages
3416 @section How do I find a Emacs Lisp package that does XXX?
3417 @cindex Package, finding
3418 @cindex Finding an Emacs Lisp package
3419 @cindex Functionality, finding a particular package
3421 First of all, you should check to make sure that the package isn't
3422 already available. For example, typing @kbd{M-x apropos @key{RET}
3423 wordstar @key{RET}} lists all functions and variables containing the
3424 string @samp{wordstar}.
3426 It is also possible that the package is on your system, but has not been
3427 loaded. To see which packages are available for loading, look through
3428 your computer's lisp directory (@pxref{File-name conventions}). The Lisp
3429 source to most packages contains a short description of how they
3430 should be loaded, invoked, and configured---so before you use or
3431 modify a Lisp package, see if the author has provided any hints in the
3434 The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
3435 the constituent Emacs packages.
3437 For advice on how to find extra packages that are not part of Emacs,
3438 see @ref{Packages that do not come with Emacs}.
3440 @node Packages that do not come with Emacs, Current GNU distributions, Finding a package with particular functionality, Finding Emacs and related packages
3441 @section Where can I get Emacs Lisp packages that don't come with Emacs?
3442 @cindex Unbundled packages
3443 @cindex Finding other packages
3444 @cindex Lisp packages that do not come with Emacs
3445 @cindex Packages, those that do not come with Emacs
3446 @cindex Emacs Lisp List
3447 @cindex Emacs Lisp Archive
3449 @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs Lisp
3450 List (ELL)}, maintained by @email{S.J.Eglen@@damtp.cam.ac.uk, Stephen Eglen},
3451 aims to provide one compact list with links to all of the current Emacs
3452 Lisp files on the Internet. The ELL can be browsed over the web, or
3453 from Emacs with @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.el,
3454 the @file{ell} package}.
3456 Many authors post their packages to the @uref{news:gnu.emacs.sources,
3457 Emacs sources newsgroup}. You can search the archives of this
3458 group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google},
3459 or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example.
3461 Several packages are stored in
3462 @uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}.
3464 Read the file @file{etc/MORE.STUFF} for more information about
3467 @node Current GNU distributions, Difference between Emacs and XEmacs, Packages that do not come with Emacs, Finding Emacs and related packages
3468 @section Where can I get other up-to-date GNU stuff?
3469 @cindex Current GNU distributions
3470 @cindex Sources for current GNU distributions
3471 @cindex Stuff, current GNU
3472 @cindex Up-to-date GNU stuff
3473 @cindex Finding current GNU software
3474 @cindex Official GNU software sites
3476 The most up-to-date official GNU software is normally kept at
3478 @uref{ftp://ftp.gnu.org/pub/gnu}
3480 Read the files @file{etc/DISTRIB} and @file{etc/FTP} for more
3483 A list of sites mirroring @samp{ftp.gnu.org} can be found at
3485 @uref{http://www.gnu.org/order/ftp.html}
3487 @node Difference between Emacs and XEmacs, Emacs for minimalists, Current GNU distributions, Finding Emacs and related packages
3488 @section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
3490 @cindex Difference Emacs and XEmacs
3494 XEmacs is a branch version of Emacs. It was first called Lucid Emacs,
3495 and was initially derived from a prerelease version of Emacs 19. In
3496 this FAQ, we use the name ``Emacs'' only for the official version.
3498 Emacs and XEmacs each come with Lisp packages that are lacking in the
3499 other. The two versions have some significant differences at the Lisp
3500 programming level. Their current features are roughly comparable,
3501 though the support for some operating systems, character sets and
3502 specific packages might be quite different.
3504 Some XEmacs code has been contributed to Emacs, and we would like to
3505 use other parts, but the earlier XEmacs maintainers did not always
3506 keep track of the authors of contributed code, which makes it
3507 impossible for the FSF to get copyright papers signed for that code.
3508 (The FSF requires these papers for all the code included in the Emacs
3509 release, aside from generic C support packages that retain their
3510 separate identity and are not integrated into the code of Emacs
3513 If you want to talk about these two versions and distinguish them,
3514 please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs''
3515 with ``GNU Emacs'' would be misleading, since XEmacs too has its
3516 origin in the work of the GNU Project. Terms such as ``Emacsen'' and
3517 ``(X)Emacs'' are not wrong, but they are not very clear, so it
3518 is better to write ``Emacs and XEmacs.''
3520 @node Emacs for minimalists, Emacs for MS-DOS, Difference between Emacs and XEmacs, Finding Emacs and related packages
3521 @section I don't have enough disk space to install Emacs
3523 @cindex Not enough disk space to install Emacs
3525 GNU Zile is a lightweight Emacs clone. Zile is short for @samp{Zile Is
3526 Lossy Emacs}. It has all of Emacs's basic editing features. The Zile
3527 binary typically has a size of about 130 kbytes, so this can be useful
3528 if you are in an extremely space-restricted environment. More
3529 information is available from
3531 @uref{http://www.gnu.org/software/zile/}
3534 @node Emacs for MS-DOS, Emacs for Windows, Emacs for minimalists, Finding Emacs and related packages
3535 @section Where can I get Emacs for my PC running MS-DOS?
3536 @cindex MS-DOS, Emacs for
3537 @cindex DOS, Emacs for
3538 @cindex Compiling Emacs for DOS
3539 @cindex Emacs for MS-DOS
3540 @cindex Tools needed to compile Emacs under DOS
3542 A pre-built binary distribution of Emacs is available from the
3543 SimTel.NET archives. This version apparently works under MS-DOS and
3544 Windows (3.X, 9X, ME, NT, and 2000) and supports long file names under
3545 Windows 9X, Windows ME, and Windows 2000. More information is available
3548 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README}
3550 The binary itself is available in the files @file{em*.zip} in the
3553 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/}
3555 If you prefer to compile Emacs for yourself, you can do so with the
3556 current distribution directly. You will need a 386 (or
3557 better) processor, and to be running MS-DOS 3.0 or later. According to
3558 @email{eliz@@gnu.org, Eli Zaretskii} and
3559 @email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the
3565 DJGPP version 1.12 maint 1 or later. Djgpp 2.0 or later is
3566 recommended, since 1.x is very old an unmaintained. Djgpp 2 supports
3567 long file names on Windows 9X/ME/2K.
3569 You can get the latest release of DJGPP by retrieving all of
3572 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2*}
3574 @item Unpacking program
3575 The easiest way is to use @code{djtar} which comes with DJGPP v2.x,
3576 because it can open gzip'ed tarfiles (i.e., those ending with
3577 @file{.tar.gz}) in one step. @code{Djtar} comes in
3578 @file{djdev@var{nnn}.zip} archive (where @var{nnn} is the DJGPP version
3579 number), from the URL mentioned above.
3581 @strong{Warning!} Do @strong{not} use the popular WinZip program to
3582 unpack the Emacs distribution! WinZip is known to corrupt some of the
3583 files by converting them to the DOS CR-LF format, it doesn't always
3584 preserve the directory structure recorded in the compressed Emacs
3585 archive, and commits other atrocities. Some of these problems could
3586 actually prevent Emacs from building successfully!
3588 @item make, mv, sed, and rm
3589 All of these utilities are available at
3591 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu}
3593 16-bit utilities can be found in GNUish, at
3595 @uref{http://www.simtel.net/pub/gnuish/}
3598 (@code{mv} and @code{rm} are in the Fileutils package, @code{sed} and
3599 @code{make} are each one in a separate package named after them.)
3603 The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
3604 directory of the Emacs sources contains some additional information
3605 regarding Emacs under MS-DOS.
3607 For a list of other MS-DOS implementations of Emacs (and Emacs
3608 look-alikes), consult the list of ``Emacs implementations and literature,''
3611 @uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}
3613 Note that while many of these programs look similar to Emacs, they often
3614 lack certain features, such as the Emacs Lisp extension language.
3616 @node Emacs for Windows, Emacs for GNUstep, Emacs for MS-DOS, Finding Emacs and related packages
3617 @section Where can I get Emacs for Microsoft Windows?
3618 @cindex FAQ for NT Emacs
3619 @cindex Emacs for MS-Windows
3620 @cindex Microsoft Windows, Emacs for
3621 @cindex Windows 9X, ME, NT, 2K, and CE, Emacs for
3623 For information on Emacs for Windows 95 and NT, read the FAQ produced by
3624 @email{voelker@@cs.washington.edu, Geoff Voelker} and currently maintained
3625 by @email{ramprasad@@gnu.org, Ramprasad B}, available at
3627 @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html}
3629 @xref{Emacs for MS-DOS}, for Windows 3.1.
3632 @node Emacs for GNUstep, Emacs for Apple computers, Emacs for Windows, Finding Emacs and related packages
3633 @section Where can I get Emacs for GNUstep?
3634 @cindex GNUSTEP, Emacs for
3636 Beginning with version 23.1, Emacs supports GNUstep natively.
3638 @node Emacs for Apple computers, Modes for various languages, Emacs for GNUstep, Finding Emacs and related packages
3639 @section Where can I get Emacs for my Apple computer?
3640 @cindex Apple computers, Emacs for
3641 @cindex Macintosh, Emacs for
3643 Beginning with version 22.1, Emacs supports Mac OS X natively.
3645 @node Modes for various languages, , Emacs for Apple computers, Finding Emacs and related packages
3646 @section Where can I get modes for Lex, Yacc/Bison, Bourne shell, csh, C@t{++}, Objective-C, Pascal, Java, and Awk?
3647 @cindex Awk, mode for
3648 @cindex @code{awk-mode}
3649 @cindex Bison, mode for
3650 @cindex Bourne Shell, mode for
3651 @cindex C@t{++}, mode for
3652 @cindex Java, mode for
3654 @cindex Objective-C, mode for
3655 @cindex @code{pascal-mode}
3658 @cindex @file{csh} mode
3659 @cindex @code{sh-mode}
3660 @cindex @code{cc-mode}
3662 Most of these modes are now available in standard Emacs distribution.
3663 To get additional modes, see @ref{Finding a package with particular
3666 Barry Warsaw's @code{cc-mode} now works for C, C@t{++}, Objective-C, and
3667 Java code. It is distributed with Emacs, but has
3668 @uref{http://cc-mode.sourceforge.net/, its own homepage}.
3670 @c ------------------------------------------------------------
3671 @node Major packages and programs, Key bindings, Finding Emacs and related packages, Top
3672 @chapter Major packages and programs
3673 @cindex Major packages and programs
3687 @node VM, AUCTeX, Major packages and programs, Major packages and programs
3688 @section VM (View Mail) --- another mail reader within Emacs, with MIME support
3690 @cindex Alternative mail software
3692 @cindex E-mail reader, VM
3697 @email{hack@@robf.de, Robert Widhopf-Fenk}
3699 @item Latest version
3703 @uref{http://www.nongnu.org/viewmail/}
3705 @item Informational newsgroup
3706 @uref{news:gnu.emacs.vm.info}@*
3708 @item Bug reports newsgroup
3709 @uref{news:gnu.emacs.vm.bug}@*
3712 VM was originally written by @uref{http://www.wonderworks.com/vm/,Kyle Jones}.
3713 @uref{ftp://ftp.wonderworks.com/pub/vm/,Older versions} of VM remain
3717 @node AUCTeX, BBDB, VM, Major packages and programs
3718 @section AUC@TeX{} --- enhanced @TeX{} modes with debugging facilities
3719 @cindex Mode for @TeX{}
3721 @cindex AUC@TeX{} mode for editing @TeX{}
3722 @cindex Writing and debugging @TeX{}
3724 AUC@TeX{} is a set of sophisticated major modes for @TeX{}, LaTeX,
3725 ConTeXt, and Texinfo offering context-sensitive syntax highlighting,
3726 indentation, formatting and folding, macro completion, @TeX{} shell
3727 functionality, and debugging. Be also sure to check out
3728 @ref{Introduction, RefTeX, Introduction, reftex, Ref@TeX{} User Manual}.
3729 Current versions of AUC@TeX{} include the
3730 @uref{http://www.gnu.org/software/auctex/preview-latex.html,preview-latex}
3731 package for WYSIWYG previews of various LaTeX constructs in the Emacs
3737 @email{krab@@iesd.auc.dk, Kresten Krab Thorup}, @*
3738 @email{abraham@@dina.kvl.dk, Per Abrahamsen}, @* and others.
3741 @email{dak@@gnu.org, David Kastrup}
3743 @item Latest version
3747 @uref{ftp://ftp.gnu.org/pub/gnu/auctex/}
3750 @uref{http://www.gnu.org/software/auctex/}
3753 Subscription requests to @email{auctex-request@@gnu.org}@*
3754 Submissions to @email{auctex@@gnu.org}
3758 @node BBDB, Ispell, AUCTeX, Major packages and programs
3759 @section BBDB --- personal Info Rolodex integrated with mail/news readers
3761 @cindex Rolodex-like functionality
3762 @cindex Integrated contact database
3763 @cindex Contact database
3764 @cindex Big Brother Database
3765 @cindex Address book
3770 @email{hack@@robf.de, Robert Widhopf-Fenk}
3772 @item Latest version
3776 @uref{http://bbdb.sourceforge.net/}
3779 Subscription requests to @email{bbdb-info-request@@lists.sourceforge.net}@*
3780 Submissions to @email{bbdb-info@@lists.sourceforge.net}@*
3781 Release announcements: @email{bbdb-announce-request@@lists.sourceforge.net}
3785 @node Ispell, Emacs/W3, BBDB, Major packages and programs
3786 @section Ispell --- spell checker in C with interface for Emacs
3787 @cindex Spell-checker
3788 @cindex Checking spelling
3794 @email{geoff@@cs.hmc.edu, Geoff Kuenning}
3796 @item Latest version
3800 @uref{http://fmg-www.cs.ucla.edu/geoff/tars/ispell-3.3.02.tar.gz}@*
3803 @uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
3807 This Ispell program is distinct from GNU Ispell 4.0. GNU Ispell 4.0 is
3808 no longer a supported product.
3810 @node Emacs/W3, EDB, Ispell, Major packages and programs
3811 @section Emacs/W3 --- A World Wide Web browser inside of Emacs
3814 @cindex HTML browser in Emacs
3815 @cindex @code{w3-mode}
3820 @email{wmperry@@gnu.org, Bill Perry}
3823 Emacs/W3 needs a maintainer. It has lain dormant for several years. If
3824 you would like to take over the project, please contact
3825 @email{maintainers@@gnu.org}.
3827 @item Latest version
3831 @uref{http://savannah.gnu.org/projects/w3}
3834 Receive announcements from @email{w3-announce@@gnu.org}@*
3835 Help to develop Emacs/W3 at @email{w3-dev@@gnu.org}
3839 @node EDB, Mailcrypt, Emacs/W3, Major packages and programs
3840 @section EDB --- Database program for Emacs; replaces forms editing modes
3847 @email{mernst@@theory.lcs.mit.edu, Michael Ernst}
3849 @item Latest version
3853 @uref{ftp://theory.lcs.mit.edu/pub/emacs/edb}
3857 @node Mailcrypt, JDE, EDB, Major packages and programs
3858 @section Mailcrypt --- PGP interface within Emacs mail and news
3861 @cindex Interface to PGP from Emacs mail and news
3862 @cindex News, interface to PGP from
3863 @cindex Mail, interface to PGP from
3864 @cindex Encryption software, interface to
3869 @email{patl@@lcs.mit.edu, Patrick J. LoPresti} and
3870 @email{jin@@atype.com, Jin S. Choi}
3873 @email{warner-mailcrypt@@lothar.com, Brian Warner}
3875 @item Latest version
3879 @uref{http://dl.sourceforge.net/sourceforge/mailcrypt/mailcrypt-3.5.8.tar.gz}
3882 @uref{http://mailcrypt.sourceforge.net/}
3886 Note that a new package called PGG is bundled with Emacs starting with
3887 version 22.1. It is a modern interface to various PGP implementations,
3888 including @uref{http://www.gnupg.org/, The GNU Privacy Guard} and
3889 supports symmetric encryption.
3891 @node JDE, Patch, Mailcrypt, Major packages and programs
3892 @section JDE --- Integrated development environment for Java
3893 @cindex Java development environment
3894 @cindex Integrated Java development environment
3900 @email{paulk@@mathworks.com, Paul Kinnucan}
3902 @item Latest version
3906 @uref{http://jdee.sunsite.dk/}
3909 Subscription requests to @email{jde-subscribe@@sunsite.dk}@*
3910 Receive announcements from @email{jde-announce-subscribe@@sunsite.dk}
3914 @node Patch, , JDE, Major packages and programs
3915 @section Patch --- program to apply ``diffs'' for updating files
3916 @cindex Updating files with diffs
3917 @cindex Patching source files with diffs
3918 @cindex Diffs and patching
3919 @cindex @file{patch}
3924 @email{lwall@@wall.org, Larry Wall} (with GNU modifications)
3926 @item Latest version
3930 @xref{Current GNU distributions}.
3934 @c ------------------------------------------------------------
3935 @node Key bindings, Alternate character sets, Major packages and programs, Top
3936 @chapter Key bindings
3937 @cindex Key bindings
3940 * Binding keys to commands::
3941 * Invalid prefix characters::
3942 * Terminal setup code works after Emacs has begun::
3943 * Using function keys under X::
3944 * Working with function and arrow keys::
3945 * X key translations for Emacs::
3946 * Handling C-s and C-q with flow control::
3947 * Binding C-s and C-q::
3948 * Backspace invokes help::
3949 * stty and Backspace key::
3951 * Producing C-XXX with the keyboard::
3954 * Compose Character::
3955 * Binding combinations of modifiers and function keys::
3956 * Meta key does not work in xterm::
3957 * ExtendChar key does not work as Meta::
3958 * SPC no longer completes file names::
3961 @node Binding keys to commands, Invalid prefix characters, Key bindings, Key bindings
3962 @section How do I bind keys (including function keys) to commands?
3963 @cindex Binding keys to commands
3964 @cindex Keys, binding to commands
3965 @cindex Commands, binding keys to
3967 Keys can be bound to commands either interactively or in your
3968 @file{.emacs} file. To interactively bind keys for all modes, type
3969 @kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3971 To bind a key just in the current major mode, type @kbd{M-x
3972 local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3974 @inforef{Key Bindings, Key Bindings, emacs}, for further details.
3976 To make the process of binding keys interactively easier, use the
3977 following ``trick'': First bind the key interactively, then immediately
3978 type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
3979 to bind the key is in the kill ring, and can be yanked into your
3980 @file{.emacs} file. If the key binding is global, no changes to the
3981 command are required. For example,
3984 (global-set-key (quote [f1]) (quote help-for-help))
3988 can be placed directly into the @file{.emacs} file. If the key binding is
3989 local, the command is used in conjunction with the @samp{add-hook} function.
3990 For example, in TeX mode, a local binding might be
3993 (add-hook 'tex-mode-hook
3995 (local-set-key (quote [f1]) (quote help-for-help))))
4002 Control characters in key sequences, in the form yanked from the kill
4003 ring are given in their graphic form---i.e., @key{CTRL} is shown as
4004 @samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want
4005 to convert these into their vector or string forms.
4008 If a prefix key of the character sequence to be bound is already
4009 bound as a complete key, then you must unbind it before the new
4010 binding. For example, if @kbd{ESC @{} is previously bound:
4013 (global-unset-key [?\e ?@{]) ;; or
4014 (local-unset-key [?\e ?@{])
4018 Aside from commands and ``lambda lists,'' a vector or string also
4019 can be bound to a key and thus treated as a macro. For example:
4022 (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or
4023 (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
4028 @node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings
4029 @section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
4030 @cindex Prefix characters, invalid
4031 @cindex Invalid prefix characters
4032 @cindex Misspecified key sequences
4034 Usually, one of two things has happened. In one case, the control
4035 character in the key sequence has been misspecified (e.g. @samp{C-f}
4036 used instead of @samp{\C-f} within a Lisp expression). In the other
4037 case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
4038 was already bound as a @dfn{complete key}. Historically, the @samp{ESC [}
4039 prefix was usually the problem, in which case you should evaluate either
4040 of these forms before attempting to bind the key sequence:
4043 (global-unset-key [?\e ?[]) ;; or
4044 (global-unset-key "\e[")
4047 @node Terminal setup code works after Emacs has begun, Using function keys under X, Invalid prefix characters, Key bindings
4048 @section Why doesn't this [terminal or window-system setup] code work in my @file{.emacs} file, but it works just fine after Emacs starts up?
4049 @cindex Terminal setup code in @file{.emacs}
4051 During startup, Emacs initializes itself according to a given code/file
4052 order. If some of the code executed in your @file{.emacs} file needs to
4053 be postponed until the initial terminal or window-system setup code has
4054 been executed but is not, then you will experience this problem (this
4055 code/file execution order is not enforced after startup).
4057 To postpone the execution of Emacs Lisp code until after terminal or
4058 window-system setup, treat the code as a @dfn{lambda list} and set the
4059 value of either the @code{term-setup-hook} or @code{window-setup-hook}
4060 variable to this lambda function. For example,
4063 (add-hook 'term-setup-hook
4065 (when (string-match "\\`vt220" (or (getenv "TERM") ""))
4066 ;; Make vt220's "Do" key behave like M-x:
4067 (global-set-key [do] 'execute-extended-command))))
4070 For information on what Emacs does every time it is started, see the
4071 @file{lisp/startup.el} file.
4073 @node Using function keys under X, Working with function and arrow keys, Terminal setup code works after Emacs has begun, Key bindings
4074 @section How do I use function keys under X?
4075 @cindex Function keys
4076 @cindex X Window System and function keys
4077 @cindex Binding function keys
4079 With Emacs 19, functions keys under X are bound like any other key. @xref{Binding keys to commands}, for details.
4081 @node Working with function and arrow keys, X key translations for Emacs, Using function keys under X, Key bindings
4082 @section How do I tell what characters or symbols my function or arrow keys emit?
4083 @cindex Working with arrow keys
4084 @cindex Arrow keys, symbols generated by
4085 @cindex Working with function keys
4086 @cindex Function keys, symbols generated by
4087 @cindex Symbols generated by function keys
4089 Type @kbd{C-h c} then the function or arrow keys. The command will
4090 return either a function key symbol or character sequence (see the
4091 Emacs on-line documentation for an explanation). This works for other
4094 @node X key translations for Emacs, Handling C-s and C-q with flow control, Working with function and arrow keys, Key bindings
4095 @section How do I set the X key ``translations'' for Emacs?
4096 @cindex X key translations
4097 @cindex Key translations under X
4098 @cindex Translations for keys under X
4100 Emacs is not written using the Xt library by default, so there are no
4101 ``translations'' to be set. (We aren't sure how to set such translations
4102 if you do build Emacs with Xt; please let us know if you've done this!)
4104 The only way to affect the behavior of keys within Emacs is through
4105 @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The
4106 @code{define-key} command should be used in conjunction with the
4107 @code{function-key-map} map. For instance,
4110 (define-key function-key-map [M-@key{TAB}] [?\M-\t])
4114 defines the @kbd{M-@key{TAB}} key sequence.
4116 @node Handling C-s and C-q with flow control, Binding C-s and C-q, X key translations for Emacs, Key bindings
4117 @section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control?
4118 @cindex Flow control, @kbd{C-s} and @kbd{C-q} with
4119 @cindex @kbd{C-s} and @kbd{C-q} with flow control
4121 @kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol.
4122 This messes things up when you're using Emacs over a serial line,
4123 because Emacs binds these keys to commands by default. Because Emacs
4124 won't honor them as flow control characters, too many of these
4125 characters are not passed on and overwhelm output buffers. Sometimes,
4126 intermediate software using XON/XOFF flow control will prevent Emacs
4127 from ever seeing @kbd{C-s} and @kbd{C-q}.
4134 Disable the use of @kbd{C-s} and @kbd{C-q} for flow control.
4136 You need to determine the cause of the flow control.
4143 Your terminal may use XON/XOFF flow control to have time to display
4144 all the characters it receives. For example, VT series terminals do
4145 this. It may be possible to turn this off from a setup menu. For
4146 example, on a VT220 you may select ``No XOFF'' in the setup menu. This
4147 is also true for some terminal emulation programs on PCs.
4149 When you turn off flow control at the terminal, you will also need to
4150 turn it off at the other end, which might be at the computer you are
4151 logged in to or at some terminal server in between.
4153 If you turn off flow control, characters may be lost; using a printer
4154 connected to the terminal may fail. You may be able to get around
4155 this problem by modifying the @samp{termcap} entry for your terminal to
4156 include extra NUL padding characters.
4161 If you are using a dialup connection, the modems may be using
4162 XON/XOFF flow control. It's not clear how to get around this.
4165 a router or terminal server
4167 Some network box between the terminal and your computer may be using
4168 XON/XOFF flow control. It may be possible to make it use some other
4169 kind of flow control. You will probably have to ask your local
4170 network experts for help with this.
4173 @code{tty} and/or @code{pty} devices
4175 If your connection to Emacs goes through multiple @code{tty} and/or
4176 @code{pty} devices, they may be using XON/XOFF flow control even when it
4179 @email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes:
4182 Some versions of @code{rlogin} (and possibly @code{telnet}) do not pass
4183 flow control characters to the remote system to which they connect. On
4184 such systems, Emacs on the remote system cannot disable flow control on
4185 the local system. Sometimes @samp{rlogin -8} will avoid this problem.
4187 One way to cure this is to disable flow control on the local host (the
4188 one running @code{rlogin}, not the one running @code{rlogind}) using the
4189 @code{stty} command, before starting the @code{rlogin} process. On many
4190 systems, @samp{stty start u stop u} will do this.
4192 Some versions of @samp{tcsh} will prevent even this from working. One
4193 way around this is to start another shell before starting rlogin,
4194 and issue the @samp{stty} command to disable flow control from that shell.
4197 Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems.
4202 Make Emacs speak the XON/XOFF flow control protocol.
4204 You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by
4208 (enable-flow-control)
4212 to unconditionally enable flow control or
4215 (enable-flow-control-on "vt100" "h19")
4219 (using your terminal names instead of @samp{vt100} or @samp{h19}) to
4220 enable selectively. These commands will automatically swap @kbd{C-s}
4221 and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}. Variables can be used to
4222 change the default swap keys (@code{flow-control-c-s-replacement} and
4223 @code{flow-control-c-q-replacement}).
4225 If you are fixing this for yourself, simply put the form in your
4226 @file{.emacs} file. If you are fixing this for your entire site, the
4227 best place to put it is in the @file{site-lisp/site-start.el} file.
4228 (Here @file{site-lisp} is actually a subdirectory of your Emacs
4229 installation directory, typically @file{/usr/local/share/emacs}.)
4230 Putting this form in @file{site-lisp/default.el} has the problem that
4231 if the user's @file{.emacs} file has an error, this will prevent
4232 @file{default.el} from being loaded and Emacs may be unusable for the
4233 user, even for correcting their @file{.emacs} file (unless they're
4234 smart enough to move it to another name).
4236 @code{enable-flow-control} can be invoked interactively as well:
4237 @kbd{M-x enable-flow-control @key{RET}}.
4241 For further discussion of this issue, read the file @file{etc/PROBLEMS}
4242 (in the Emacs source directory when you unpack the Emacs distribution).
4244 @node Binding C-s and C-q, Backspace invokes help, Handling C-s and C-q with flow control, Key bindings
4245 @section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out?
4246 @cindex Binding @kbd{C-s} and @kbd{C-q}
4247 @cindex @kbd{C-s} and @kbd{C-q}, binding
4249 To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control}
4250 or @code{enable-flow-control-on}. @xref{Handling C-s and C-q with flow
4251 control}, for usage and implementation details.
4253 To bind other keys, use @code{keyboard-translate}. @xref{Swapping
4254 keys}, for usage details. To do this for an entire site, you should
4255 swap the keys in @file{site-lisp/site-start.el}. @xref{Handling C-s
4256 and C-q with flow control}, for an explanation of why
4257 @file{site-lisp/default.el} should not be used.
4262 If you do this for an entire site, the users will be confused by
4263 the disparity between what the documentation says and how Emacs
4268 @node Backspace invokes help, stty and Backspace key, Binding C-s and C-q, Key bindings
4269 @section Why does the @key{Backspace} key invoke help?
4270 @cindex Backspace key invokes help
4271 @cindex Help invoked by Backspace
4272 @cindex DEL key does not delete
4274 The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8.
4275 @kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes
4276 help-command. This is intended to be easy to remember since the first
4277 letter of @samp{help} is @samp{h}. The easiest solution to this problem
4278 is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
4279 @key{Delete} key) for deleting the previous character.
4281 For many people this solution may be problematic:
4286 They normally use @key{Backspace} outside of Emacs for deleting the
4287 previous character. This can be solved by making @key{DEL} the command
4288 for deleting the previous character outside of Emacs. On many Unix
4289 systems, this command will remap @key{DEL}:
4296 The user may prefer the @key{Backspace} key for deleting the
4297 previous character because it is more conveniently located on their
4298 keyboard or because they don't even have a separate @key{Delete} key.
4299 In this case, the @key{Backspace} key should be made to behave like
4300 @key{Delete}. There are several methods.
4304 Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
4305 TeraTerm) allow the character generated by the @key{Backspace} key to be
4306 changed from a setup menu.
4309 You may be able to get a keyboard that is completely programmable, or a
4310 terminal emulator that supports remapping of any key to any other key.
4313 With Emacs 21.1 and later, you can control the effect of the
4314 @key{Backspace} and @key{Delete} keys, on both dumb terminals and a
4315 windowed displays, by customizing the option
4316 @code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
4317 normal-erase-is-backspace}. See the documentation of these symbols
4318 (@pxref{Emacs Lisp documentation}) for more info.
4321 It is possible to swap the @key{Backspace} and @key{DEL} keys inside
4325 (keyboard-translate ?\C-h ?\C-?)
4329 This is the recommended method of forcing @key{Backspace} to act as
4330 @key{DEL}, because it works even in modes which bind @key{DEL} to
4331 something other than @code{delete-backward-char}.
4333 Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
4334 default deletes forward:
4337 (keyboard-translate ?\C-? ?\C-d)
4340 @xref{Swapping keys}, for further details about @code{keyboard-translate}.
4343 Another approach is to switch key bindings and put help on @kbd{C-x h}
4347 (global-set-key "\C-h" 'delete-backward-char)
4349 ;; overrides mark-whole-buffer
4350 (global-set-key "\C-xh" 'help-command)
4354 This method is not recommended, though: it only solves the problem for
4355 those modes which bind @key{DEL} to @code{delete-backward-char}. Modes
4356 which bind @key{DEL} to something else, such as @code{view-mode}, will
4357 not work as you expect when you press the @key{Backspace} key. For this
4358 reason, we recommend the @code{keyboard-translate} method, shown
4361 Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
4364 Don't try to bind @key{DEL} to @code{help-command}, because there are
4365 many modes that have local bindings of @key{DEL} that will interfere.
4369 When Emacs 21 or later runs on a windowed display, it binds the
4370 @key{Delete} key to a command which deletes the character at point, to
4371 make Emacs more consistent with keyboard operation on these systems.
4373 For more information about troubleshooting this problem, see @ref{DEL
4374 Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
4377 @node stty and Backspace key, Swapping keys, Backspace invokes help, Key bindings
4378 @section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}?
4379 @cindex @file{stty} and Emacs
4380 @cindex Backspace and @file{stty}
4381 @cindex Delete and @file{stty}
4385 @c FIXME: RMS explained the reasons for this on emacs-hackers. It's
4386 @c probably worth putting that explanation here.
4388 @node Swapping keys, Producing C-XXX with the keyboard, stty and Backspace key, Key bindings
4389 @section How do I swap two keys?
4390 @cindex Swapping keys
4391 @cindex Keys, swapping
4392 @cindex @code{keyboard-translate}
4394 You can swap two keys (or key sequences) by using the
4395 @code{keyboard-translate} function. For example, to turn @kbd{C-h}
4396 into @key{DEL} and @key{DEL} to @kbd{C-h}, use
4399 (keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL
4400 (keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.
4404 The first key sequence of the pair after the function identifies what is
4405 produced by the keyboard; the second, what is matched for in the
4408 However, in the specific case of @kbd{C-h} and @key{DEL}, you should
4409 toggle @code{normal-erase-is-backspace-mode} instead of calling
4410 @code{keyboard-translate}. @inforef{DEL Does Not Delete, DEL Does Not Delete,
4413 Keyboard translations are not the same as key bindings in keymaps.
4414 Emacs contains numerous keymaps that apply in different situations, but
4415 there is only one set of keyboard translations, and it applies to every
4416 character that Emacs reads from the terminal. Keyboard translations
4417 take place at the lowest level of input processing; the keys that are
4418 looked up in keymaps contain the characters that result from keyboard
4421 @node Producing C-XXX with the keyboard, No Meta key, Swapping keys, Key bindings
4422 @section How do I produce C-XXX with my keyboard?
4423 @cindex Producing control characters
4424 @cindex Generating control characters
4425 @cindex Control characters, generating
4427 On terminals (but not under X), some common ``aliases'' are:
4431 @item @kbd{C-2} or @kbd{C-@key{SPC}}
4437 @item @kbd{C-7} or @kbd{C-S--}
4451 Often other aliases exist; use the @kbd{C-h c} command and try
4452 @key{CTRL} with all of the digits on your keyboard to see what gets
4453 generated. You can also try the @kbd{C-h w} command if you know the
4454 name of the command.
4456 @node No Meta key, No Escape key, Producing C-XXX with the keyboard, Key bindings
4457 @section What if I don't have a @key{Meta} key?
4458 @cindex No @key{Meta} key
4459 @cindex @key{Meta} key, what to do if you lack it
4461 On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
4463 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact,
4464 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
4465 (depending on the value of @code{meta-prefix-char}). Note that you
4466 press @key{Meta} and @key{a} together, but with @key{ESC}, you press
4467 @key{ESC}, release it, and then press @key{a}.
4469 @node No Escape key, Compose Character, No Meta key, Key bindings
4470 @section What if I don't have an @key{Escape} key?
4471 @cindex No Escape key
4472 @cindex Lacking an Escape key
4473 @cindex Escape key, lacking
4475 Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an
4476 Escape key would. @kbd{C-3} may also work on some terminal (but not
4477 under X). For many terminals (notably DEC terminals) @key{F11}
4478 generates @key{ESC}. If not, the following form can be used to bind it:
4481 ;; F11 is the documented ESC replacement on DEC terminals.
4482 (define-key function-key-map [f11] [?\e])
4485 @node Compose Character, Binding combinations of modifiers and function keys, No Escape key, Key bindings
4486 @section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
4487 @cindex @key{Compose Character} key, using as @key{Meta}
4488 @cindex @key{Meta}, using @key{Compose Character} for
4490 On a dumb terminal such as a VT220, no. It is rumored that certain
4491 VT220 clones could have their @key{Compose} key configured this way. If
4492 you're using X, you might be able to do this with the @code{xmodmap}
4495 @node Binding combinations of modifiers and function keys, Meta key does not work in xterm, Compose Character, Key bindings
4496 @section How do I bind a combination of modifier key and function key?
4497 @cindex Modifiers and function keys
4498 @cindex Function keys and modifiers
4499 @cindex Binding modifiers and function keys
4501 With Emacs 19 and later, you can represent modified function keys in
4502 vector format by adding prefixes to the function key symbol. For
4503 example (from the on-line documentation):
4506 (global-set-key [?\C-x right] 'forward-page)
4510 where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
4512 You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
4513 @key{Super}, @key{Alt}, and @key{Shift} with function keys. To
4514 represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
4515 @samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here
4516 is how to make @kbd{H-M-RIGHT} move forward a word:
4519 (global-set-key [H-M-right] 'forward-word)
4525 Not all modifiers are permitted in all situations. @key{Hyper},
4526 @key{Super}, and @key{Alt} are not available on Unix character
4527 terminals. Non-@acronym{ASCII} keys and mouse events (e.g. @kbd{C-=} and
4528 @kbd{Mouse-1}) also fall under this category.
4532 @xref{Binding keys to commands}, for general key binding instructions.
4534 @node Meta key does not work in xterm, ExtendChar key does not work as Meta, Binding combinations of modifiers and function keys, Key bindings
4535 @section Why doesn't my @key{Meta} key work in an @code{xterm} window?
4536 @cindex @key{Meta} key and @code{xterm}
4537 @cindex Xterm and @key{Meta} key
4539 @inforef{Unibyte Mode, Single-Byte Character Set Support, emacs}.
4541 If the advice in the Emacs manual fails, try all of these methods before
4542 asking for further help:
4547 You may have big problems using @code{mwm} as your window manager.
4548 (Does anyone know a good generic solution to allow the use of the
4549 @key{Meta} key in Emacs with @file{mwm}?)
4552 For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to
4553 find out what keysym your @key{Meta} key generates. It should be either
4554 @code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix
4555 the situation. If @key{Meta} does generate @code{Meta_L} or
4556 @code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in
4557 your @file{~/.Xdefaults} file:
4560 XTerm*eightBitInput: false
4561 XTerm*eightBitOutput: true
4565 Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
4566 characters. @samp{stty -a} (or @samp{stty everything}) should show
4567 @samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty
4568 cs8 -istrip} (or @samp{stty pass8}) to fix it.
4571 If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
4572 @samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
4576 If Emacs is running on Ultrix, it is reported that evaluating
4577 @code{(set-input-mode t nil)} helps.
4580 If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
4581 you type @kbd{M-W}, which is the same conversion Emacs would make if it
4582 got the @kbd{M-W} anyway. In X11R4, the following resource
4583 specification will do this:
4586 XTerm.VT100.EightBitInput: false
4590 (This changes the behavior of the @code{insert-eight-bit} action.)
4592 With older @code{xterm}s, you can specify this behavior with a translation:
4595 XTerm.VT100.Translations: #override \
4596 Meta<KeyPress>: string(0x1b) insert()
4600 You might have to replace @samp{Meta} with @samp{Alt}.
4604 @node ExtendChar key does not work as Meta, SPC no longer completes file names, Meta key does not work in xterm, Key bindings
4605 @section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
4606 @cindex @key{ExtendChar} key as @key{Meta}
4607 @cindex @key{Meta}, using @key{ExtendChar} for
4608 @cindex HP-UX, the @key{ExtendChar} key
4610 This is a result of an internationalization extension in X11R4 and the
4611 fact that HP is now using this extension. Emacs assumes that the
4612 @code{XLookupString} function returns the same result regardless of the
4613 @key{Meta} key state which is no longer necessarily true. Until Emacs
4614 is fixed, the temporary kludge is to run this command after each time
4615 the X server is started but preferably before any xterm clients are:
4618 xmodmap -e 'remove mod1 = Mode_switch'
4621 @c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
4624 This will disable the use of the extra keysyms systemwide, which may be
4625 undesirable if you actually intend to use them.
4627 @node SPC no longer completes file names, , ExtendChar key does not work as Meta, Key bindings
4628 @section Why doesn't SPC complete file names anymore?
4629 @cindex @kbd{SPC} file name completion
4631 Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in
4632 the minibuffer, so that file names with embedded spaces could be typed
4633 without the need to quote the spaces.
4635 You can get the old behavior by binding @kbd{SPC} to
4636 @code{minibuffer-complete-word} in the minibuffer, as follows:
4639 (define-key minibuffer-local-filename-completion-map (kbd "SPC")
4640 'minibuffer-complete-word)
4642 (define-key minibuffer-local-must-match-filename-map (kbd "SPC")
4643 'minibuffer-complete-word)
4646 @c ------------------------------------------------------------
4647 @node Alternate character sets, Mail and news, Key bindings, Top
4648 @chapter Alternate character sets
4649 @cindex Alternate character sets
4652 * Emacs does not display 8-bit characters::
4653 * Inputting eight-bit characters::
4654 * Kanji and Chinese characters::
4655 * Right-to-left alphabets::
4656 * How to add fonts::
4659 @node Emacs does not display 8-bit characters, Inputting eight-bit characters, Alternate character sets, Alternate character sets
4660 @section How do I make Emacs display 8-bit characters?
4661 @cindex Displaying eight-bit characters
4662 @cindex Eight-bit characters, displaying
4664 @inforef{Unibyte Mode, Single-byte Character Set
4665 Support, emacs}. On a Unix, when Emacs runs on a text-only terminal
4666 display or is invoked with @samp{emacs -nw}, you typically need to use
4667 @code{set-terminal-coding-system} to tell Emacs what the terminal can
4668 display, even after setting the language environment; otherwise
4669 non-@acronym{ASCII} characters will display as @samp{?}. On other operating
4670 systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
4671 character set supported by the display, and sets up the required
4672 terminal coding system automatically.
4674 @node Inputting eight-bit characters, Kanji and Chinese characters, Emacs does not display 8-bit characters, Alternate character sets
4675 @section How do I input eight-bit characters?
4676 @cindex Entering eight-bit characters
4677 @cindex Eight-bit characters, entering
4678 @cindex Input, 8-bit characters
4680 Various methods are available for input of eight-bit characters. See
4681 @inforef{Unibyte Mode, Single-byte Character Set
4682 Support, emacs}. For more sophisticated methods, @inforef{Input
4683 Methods, Input Methods, emacs}.
4685 @node Kanji and Chinese characters, Right-to-left alphabets, Inputting eight-bit characters, Alternate character sets
4686 @section Where can I get an Emacs that handles kanji, Chinese, or other Far-Eastern character sets?
4687 @cindex Kanji, handling with Emacs
4688 @cindex Chinese, handling with Emacs
4689 @cindex Japanese, handling with Emacs
4690 @cindex Korean, handling with Emacs
4692 Emacs 20 and later includes many of the features of MULE, the MULtilingual
4693 Enhancement to Emacs. @xref{Installing Emacs}, for information on where
4694 to find and download the latest version of Emacs.
4696 @node Right-to-left alphabets, How to add fonts, Kanji and Chinese characters, Alternate character sets
4697 @section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
4698 @cindex Right-to-left alphabets
4699 @cindex Hebrew, handling with Emacs
4700 @cindex Semitic alphabets
4701 @cindex Arabic alphabets
4703 Emacs 20 and later supports Hebrew characters (ISO 8859-8), but does not
4704 yet support right-to-left character entry and display.
4706 @email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called
4707 @file{hebrew.el} that allows right-to-left editing of Hebrew. It
4708 reportedly works out of the box with Emacs 19, but requires patches for
4709 Emacs 18. Write to Joel if you want the patches or package.
4711 @c FIXME: Should we mention Ehud Karni's package?
4713 @file{hebrew.el} requires a Hebrew screen font, but no other hardware support.
4714 Joel has a screen font for PCs running MS-DOS or GNU/Linux.
4716 You might also try querying @code{archie} for files named with
4717 @file{hebrew}; several ftp sites in Israel may also have the necessary
4720 @node How to add fonts, , Right-to-left alphabets, Alternate character sets
4721 @section How do I add fonts for use with Emacs?
4722 @cindex add fonts for use with Emacs
4725 First, download and install the BDF font files and any auxiliary
4726 packages they need. The GNU Intlfonts distribution can be found on
4727 @uref{http://directory.fsf.org/localization/intlfonts.html, the GNU
4728 Software Directory Web site}.
4730 Next, if you are on X Window system, issue the following two commands
4731 from the shell's prompt:
4734 xset +fp /usr/local/share/emacs/fonts
4739 (Modify the first command if you installed the fonts in a directory
4740 that is not @file{/usr/local/share/emacs/fonts}.) You also need to
4741 arrange for these two commands to run whenever you log in, e.g., by
4742 adding them to your window-system startup file, such as
4743 @file{~/.xsessionrc} or @file{~/.gnomerc}.
4745 Now, add the following line to your @file{~/.emacs} init file:
4748 (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
4752 (Again, modify the file name if you installed the fonts elsewhere.)
4754 Finally, if you wish to use the installed fonts with @code{ps-print},
4755 add the following line to your @file{~/.emacs}:
4758 (setq ps-multibyte-buffer 'bdf-font-except-latin)
4761 A few additional steps are necessary for MS-Windows; they are listed
4764 First, make sure @emph{all} the directories with BDF font files are
4765 mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux
4766 systems, one normally runs @kbd{make install} to install the BDF fonts
4767 in the same directory. By contrast, Windows users typically don't run
4768 the Intlfonts installation command, but unpack the distribution in
4769 some directory, which leaves the BDF fonts in its subdirectories. For
4770 example, assume that you unpacked Intlfonts in @file{C:/Intlfonts};
4771 then you should set @code{bdf-directory-list} as follows:
4774 (setq bdf-directory-list
4775 '("C:/Intlfonts/Asian"
4776 "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X"
4777 "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic"
4778 "C:/Intlfonts/European" "C:/Intlfonts/European.BIG"
4779 "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X"
4780 "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X"
4781 "C:/Intlfonts/Misc"))
4784 @cindex @code{w32-bdf-filename-alist}
4785 @cindex @code{w32-find-bdf-fonts}
4786 Next, you need to set up the variable @code{w32-bdf-filename-alist} to
4787 an alist of the BDF fonts and their corresponding file names.
4788 Assuming you have set @code{bdf-directory-list} to name all the
4789 directories with the BDF font files, the following Lisp snippet will
4790 set up @code{w32-bdf-filename-alist}:
4793 (setq w32-bdf-filename-alist
4794 (w32-find-bdf-fonts bdf-directory-list))
4797 Now, create fontsets for the BDF fonts:
4800 (create-fontset-from-fontset-spec
4801 "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf,
4802 japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*,
4803 katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4804 latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4805 japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*,
4806 thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1,
4807 lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1,
4808 tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1,
4809 ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode,
4810 tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0")
4813 Many of the international bdf fonts from Intlfonts are type 0, and
4814 therefore need to be added to font-encoding-alist:
4817 (setq font-encoding-alist
4818 (append '(("MuleTibetan-0" (tibetan . 0))
4819 ("GB2312" (chinese-gb2312 . 0))
4820 ("JISX0208" (japanese-jisx0208 . 0))
4821 ("JISX0212" (japanese-jisx0212 . 0))
4822 ("VISCII" (vietnamese-viscii-lower . 0))
4823 ("KSC5601" (korean-ksc5601 . 0))
4824 ("MuleArabic-0" (arabic-digit . 0))
4825 ("MuleArabic-1" (arabic-1-column . 0))
4826 ("MuleArabic-2" (arabic-2-column . 0)))
4827 font-encoding-alist))
4830 You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
4831 fontset, or you can select it by setting the default font in your
4835 (set-default-font "fontset-bdf")
4839 @c ------------------------------------------------------------
4840 @node Mail and news, Concept index, Alternate character sets, Top
4841 @chapter Mail and news
4842 @cindex Mail and news
4845 * Changing the included text prefix::
4846 * Saving a copy of outgoing mail::
4847 * Expanding aliases when sending mail::
4848 * Sorting the messages in an Rmail folder::
4849 * Rmail writes to /usr/spool/mail::
4850 * Replying to the sender of a message::
4851 * MIME with Emacs mail packages::
4852 * Automatically starting a mail or news reader::
4853 * Reading news with Emacs::
4854 * Gnus does not work with NNTP::
4855 * Viewing articles with embedded underlining::
4856 * Saving a multi-part Gnus posting::
4857 * Starting Gnus faster::
4858 * Catching up in all newsgroups::
4859 * Killing based on nonstandard headers::
4860 * Catch-up is slow in Gnus::
4861 * Gnus hangs for a long time::
4862 * Learning more about Gnus::
4865 @node Changing the included text prefix, Saving a copy of outgoing mail, Mail and news, Mail and news
4866 @section How do I change the included text prefix in mail/news followups?
4867 @cindex Prefix in mail/news followups, changing
4868 @cindex Included text prefix, changing
4869 @cindex Setting the included text character
4870 @cindex Quoting in mail messages
4872 If you read mail with Rmail or news with Gnus, set the variable
4873 @code{mail-yank-prefix}. For VM, set @code{vm-included-text-prefix}.
4874 For mh-e, set @code{mh-ins-buf-prefix}.
4876 For fancier control of citations, use Supercite (part of Emacs).
4878 To prevent Emacs from including various headers of the replied-to
4879 message, set the value of @code{mail-yank-ignored-headers} to an
4882 @node Saving a copy of outgoing mail, Expanding aliases when sending mail, Changing the included text prefix, Mail and news
4883 @section How do I save a copy of outgoing mail?
4884 @cindex Saving a copy of outgoing mail
4885 @cindex Copying outgoing mail to a file
4886 @cindex Filing outgoing mail
4887 @cindex Automatic filing of outgoing mail
4888 @cindex Mail, saving outgoing automatically
4890 You can either mail yourself a copy by including a @samp{BCC} header in the
4891 mail message, or store a copy of the message directly to a file by
4892 including an @samp{FCC} header.
4894 If you use standard mail, you can automatically create a @samp{BCC} to
4898 (setq mail-self-blind t)
4902 in your @file{.emacs} file. You can automatically include an @samp{FCC}
4903 field by putting something like the following in your @file{.emacs}
4907 (setq mail-archive-file-name (expand-file-name "~/outgoing"))
4910 The output file will be in Unix mail format, which can be read directly
4911 by VM or Rmail (since Emacs 23).
4913 If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
4916 It does not work to put @samp{set record filename} in the @file{.mailrc}
4919 @node Expanding aliases when sending mail, Sorting the messages in an Rmail folder, Saving a copy of outgoing mail, Mail and news
4920 @section Why doesn't Emacs expand my aliases when sending mail?
4921 @cindex Expanding aliases when sending mail
4922 @cindex Mail alias expansion
4923 @cindex Sending mail with aliases
4928 You must separate multiple addresses in the headers of the mail buffer
4929 with commas. This is because Emacs supports RFC822 standard addresses
4933 To: Willy Smith <wks@@xpnsv.lwyrs.com>
4936 However, you do not need to---and probably should not, unless your
4937 system's version of @file{/usr/ucb/mail} (a.k.a.@: @code{mailx})
4938 supports RFC822---separate addresses with commas in your
4939 @file{~/.mailrc} file.
4942 Emacs normally only reads the @file{.mailrc} file once per session,
4943 when you start to compose your first mail message. If you edit
4944 @file{.mailrc}, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to
4945 make Emacs reread @file{~/.mailrc}.
4948 If you like, you can expand mail aliases as abbrevs, as soon as you
4949 type them in. To enable this feature, execute the following:
4952 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
4955 Note that the aliases are expanded automatically only after you type
4956 @key{RET} or a punctuation character (e.g. @kbd{,}). You can force their
4957 expansion by moving point to the end of the alias and typing @kbd{C-x a e}
4958 (@kbd{M-x expand-abbrev}).
4961 @node Sorting the messages in an Rmail folder, Rmail writes to /usr/spool/mail, Expanding aliases when sending mail, Mail and news
4962 @section How can I sort the messages in my Rmail folder?
4963 @cindex Rmail, sorting messages in
4964 @cindex Folder, sorting messages in an Rmail
4965 @cindex Sorting messages in an Rmail folder
4967 In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
4968 and their key bindings.
4970 @node Rmail writes to /usr/spool/mail, Replying to the sender of a message, Sorting the messages in an Rmail folder, Mail and news
4971 @section Why does Rmail need to write to @file{/usr/spool/mail}?
4972 @cindex Rmail and @file{/usr/spool/mail}
4973 @cindex @file{/usr/spool/mail} and Rmail
4975 This is the behavior of the @code{movemail} program which Rmail uses.
4976 This indicates that @code{movemail} is configured to use lock files.
4981 Certain systems require lock files to interlock access to mail files.
4982 On these systems, @code{movemail} must write lock files, or you risk losing
4983 mail. You simply must arrange to let @code{movemail} write them.
4985 Other systems use the @code{flock} system call to interlock access. On
4986 these systems, you should configure @code{movemail} to use @code{flock}.
4989 @node Replying to the sender of a message, MIME with Emacs mail packages, Rmail writes to /usr/spool/mail, Mail and news
4990 @section How can I force Rmail to reply to the sender of a message, but not the other recipients?
4991 @cindex Replying only to the sender of a message
4992 @cindex Sender, replying only to
4993 @cindex Rmail, replying to the sender of a message in
4995 @email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit
4996 @key{r} to reply in Rmail, by default it CCs all of the original
4997 recipients (everyone on the original @samp{To} and @samp{CC}
4998 lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
4999 it replies only to the sender. However, going through the whole
5000 @kbd{C-u} business every time you want to reply is a pain. This is the
5001 best fix I've been able to come up with:
5004 (defun rmail-reply-t ()
5005 "Reply only to the sender of the current message. (See rmail-reply.)"
5009 (add-hook 'rmail-mode-hook
5011 (define-key rmail-mode-map "r" 'rmail-reply-t)
5012 (define-key rmail-mode-map "R" 'rmail-reply)))
5015 @node MIME with Emacs mail packages, Automatically starting a mail or news reader, Replying to the sender of a message, Mail and news
5016 @section How can I get my favorite Emacs mail package to support MIME?
5017 @cindex MIME and Emacs mail packages
5018 @cindex Mail packages and MIME
5019 @cindex FAQ for MIME and Emacs
5021 Version 6.x of VM supports MIME. @xref{VM}. Gnus supports MIME in mail
5022 and news messages as of version 5.8.1 (Pterodactyl). Rmail has limited
5023 support for single-part MIME messages beginning with Emacs 20.3.
5025 @node Automatically starting a mail or news reader, Reading news with Emacs, MIME with Emacs mail packages, Mail and news
5026 @section How do I make Emacs automatically start my mail/news reader?
5027 @cindex Mail reader, starting automatically
5028 @cindex News reader, starting automatically
5029 @cindex Starting mail/news reader automatically
5031 To start Emacs in Gnus:
5044 A more convenient way to start with Gnus:
5047 alias gnus 'emacs -f gnus'
5051 It is probably unwise to automatically start your mail or news reader
5052 from your @file{.emacs} file. This would cause problems if you needed to run
5053 two copies of Emacs at the same time. Also, this would make it difficult for
5054 you to start Emacs quickly when you needed to.
5056 @node Reading news with Emacs, Gnus does not work with NNTP, Automatically starting a mail or news reader, Mail and news
5057 @section How do I read news under Emacs?
5058 @cindex Reading news under Emacs
5059 @cindex Usenet reader in Emacs
5060 @cindex Gnus newsreader
5062 Use @kbd{M-x gnus}. It is documented in Info (@pxref{Learning how to do
5065 @node Gnus does not work with NNTP, Viewing articles with embedded underlining, Reading news with Emacs, Mail and news
5066 @section Why doesn't Gnus work via NNTP?
5067 @cindex Gnus and NNTP
5068 @cindex NNTP, Gnus fails to work with
5070 There is a bug in NNTP version 1.5.10, such that when multiple requests
5071 are sent to the NNTP server, the server only handles the first one
5072 before blocking waiting for more input which never comes. NNTP version
5073 1.5.11 claims to fix this.
5075 You can work around the bug inside Emacs like this:
5078 (setq nntp-maximum-request 1)
5081 You can find out what version of NNTP your news server is running by
5082 telnetting to the NNTP port (usually 119) on the news server machine
5083 (i.e., @kbd{telnet server-machine 119}). The server should give its
5084 version number in the welcome message. Type @kbd{quit} to get out.
5086 @xref{Spontaneous entry into isearch-mode}, for some additional ideas.
5088 @node Viewing articles with embedded underlining, Saving a multi-part Gnus posting, Gnus does not work with NNTP, Mail and news
5089 @section How do I view news articles with embedded underlining (e.g., ClariNews)?
5090 @cindex Underlining, embedded in news articles
5091 @cindex News articles with embedded underlining
5092 @cindex Embedded underlining in news articles
5094 Underlining appears like this:
5097 _^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg
5100 @email{abraham@@dina.kvl.dk, Per Abrahamsen} suggests using the following
5101 code, which uses the underline face to turn such text into true
5102 underlining, inconjunction with Gnus:
5105 (defun gnus-article-prepare-overstrike ()
5106 ;; Prepare article for overstrike commands.
5108 (set-buffer gnus-article-buffer)
5109 (let ((buffer-read-only nil))
5110 (goto-char (point-min))
5111 (while (search-forward "\b" nil t)
5112 (let ((next (following-char))
5113 (previous (char-after (- (point) 2))))
5114 (cond ((eq next previous)
5115 (delete-region (- (point) 2) (point))
5116 (put-text-property (point) (1+ (point))
5119 (delete-region (1- (point)) (1+ (point)))
5120 (put-text-property (1- (point)) (point)
5123 (delete-region (- (point) 2) (point))
5124 (put-text-property (point) (1+ (point))
5125 'face 'underline))))))))
5127 (add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike)
5130 Latest versions of Gnus do such a conversion automatically.
5132 If you prefer to do away with underlining altogether, you can
5133 destructively remove it with @kbd{M-x ununderline-region}; do this
5137 (add-hook 'gnus-article-prepare-hook
5138 (lambda () (ununderline-region (point-min) (point-max))))
5141 @node Saving a multi-part Gnus posting, Starting Gnus faster, Viewing articles with embedded underlining, Mail and news
5142 @section How do I save all the items of a multi-part posting in Gnus?
5143 @cindex Multi-part postings in Gnus, saving
5144 @cindex Saving multi-part postings in Gnus
5145 @cindex Gnus, saving multi-part postings in
5147 Use @code{gnus-uu}. Type @kbd{C-c C-v C-h} in the Gnus summary buffer
5148 to see a list of available commands.
5150 @node Starting Gnus faster, Catching up in all newsgroups, Saving a multi-part Gnus posting, Mail and news
5151 @section How do I make Gnus start up faster?
5152 @cindex Faster, starting Gnus
5153 @cindex Starting Gnus faster
5154 @cindex Gnus, starting faster
5156 From the Gnus FAQ (@pxref{Learning more about Gnus}):
5159 @email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted
5160 the same query recently and I got an answer to it. I am going to
5161 repeat the answer. What you need is a newer version of gnus, version
5162 5.0.4+. I am using 5.0.12 and it works fine with me with the
5166 (setq gnus-check-new-newsgroups nil
5167 gnus-read-active-file 'some
5168 gnus-nov-is-evil nil
5169 gnus-select-method '(nntp gnus-nntp-server))
5173 @node Catching up in all newsgroups, Killing based on nonstandard headers, Starting Gnus faster, Mail and news
5174 @section How do I catch up all newsgroups in Gnus?
5175 @cindex Catching up all newsgroups in Gnus
5176 @cindex Gnus, Catching up all newsgroups in
5178 In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
5180 Leave off the initial @kbd{M-<} if you only want to catch up from point
5181 to the end of the @file{*Newsgroup*} buffer.
5183 @node Killing based on nonstandard headers, Catch-up is slow in Gnus, Catching up in all newsgroups, Mail and news
5184 @section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers?
5185 @cindex Killing articles based on nonstandard headers
5186 @cindex Newsgroups header, killing articles based on
5187 @cindex Keywords header, killing articles based on
5188 @cindex Control header, killing articles based on
5190 Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and
5191 @samp{Control} headers are ``Unknown header'' fields.
5193 For the @samp{Newsgroups} header, there is an easy workaround: kill on the
5194 @samp{Xref} header instead, which will be present on any cross-posted article
5195 (as long as your site carries the cross-post group).
5197 If you really want to kill on one of these headers, you can do it like
5201 (gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)")
5204 @node Catch-up is slow in Gnus, Gnus hangs for a long time, Killing based on nonstandard headers, Mail and news
5205 @section Why is catch up slow in Gnus?
5206 @cindex Slow catch up in Gnus
5207 @cindex Gnus is slow when catching up
5208 @cindex Crosspostings make Gnus catching up slow
5210 Because Gnus is marking crosspostings read. You can control this with
5211 the variable @code{gnus-use-cross-reference}.
5213 @node Gnus hangs for a long time, Learning more about Gnus, Catch-up is slow in Gnus, Mail and news
5214 @section Why does Gnus hang for a long time when posting?
5215 @cindex Hangs in Gnus
5216 @cindex Gnus hangs while posting
5217 @cindex Posting, Gnus hangs wile
5219 @email{tale@@uunet.uu.net, David Lawrence} explains:
5222 The problem is almost always interaction between NNTP and C News. NNTP
5223 POST asks C News's @code{inews} to not background itself but rather hang
5224 around and give its exit status so it knows whether the post was successful.
5225 (That wait will on some systems not return the exit status of the
5226 waited for job is a different sort of problem.) It ends up taking a
5227 long time because @code{inews} is calling @code{relaynews}, which often
5228 waits for another @code{relaynews} to free the lock on the news system
5229 so it can file the article.
5231 My preferred solution is to change @code{inews} to not call
5232 @code{relaynews}, but rather use @code{newsspool}. This loses some
5233 error-catching functionality, but is for the most part safe as
5234 @code{inews} will detect a lot of the errors on its own. The C News
5235 folks have sped up @code{inews}, too, so speed should look better to
5236 most folks as that update propagates around.
5239 @node Learning more about Gnus, , Gnus hangs for a long time, Mail and news
5240 @section Where can I find out more about Gnus?
5241 @cindex FAQ for Gnus
5243 @cindex Learning more about Gnus
5245 For more information on Gnus, consult the Gnus manual and FAQ, which are
5246 part of the Gnus distribution.
5248 @node Concept index, , Mail and news, Top
5249 @unnumbered Concept Index
5255 arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f