1 \input texinfo @c -*- mode: texinfo; -*-
3 @setfilename ../../info/efaq
4 @settitle GNU Emacs FAQ
5 @documentencoding UTF-8
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--2014 Free Software Foundation, Inc.@*
16 Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000
18 Copyright @copyright{} 1992, 1993 Steven Byrnes@*
19 Copyright @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)
60 @top The GNU Emacs FAQ
62 This is the GNU Emacs FAQ.
64 This FAQ is maintained as a part of GNU Emacs. If you find any errors,
65 or have any suggestions, please use @kbd{M-x report-emacs-bug} to report
68 This is the version of the FAQ distributed with Emacs @value{EMACSVER}, and
69 mainly describes that version. Although there is some information on
70 older versions, details about very old releases (now only of historical
71 interest) have been removed. If you are interested in this, consult
72 either the version of the FAQ distributed with older versions of Emacs,
73 or the history of this document in the Emacs source repository.
75 Since Emacs releases are very stable, we recommend always running the
78 This FAQ is not updated very frequently. When you have a question about
79 Emacs, the Emacs manual is often the best starting point.
92 * Compiling and installing Emacs::
93 * Finding Emacs and related packages::
95 * Alternate character sets::
100 @c ------------------------------------------------------------
102 @chapter FAQ notation
105 This chapter describes notation used in the GNU Emacs FAQ, as well as in
106 the Emacs documentation. Consult this section if this is the first time
107 you are reading the FAQ, or if you are confused by notation or terms
112 * Extended commands::
114 * File-name conventions::
119 @section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
121 @cindex Control key, notation for
122 @cindex @key{Meta} key, notation for
123 @cindex Control-Meta characters, notation for
124 @cindex @kbd{C-h}, definition of
125 @cindex @kbd{C-M-h}, definition of
126 @cindex @key{DEL}, definition of
127 @cindex @key{ESC}, definition of
128 @cindex @key{LFD}, definition of
129 @cindex @key{RET}, definition of
130 @cindex @key{SPC}, definition of
131 @cindex @key{TAB}, definition of
132 @cindex Notation for keys
137 @kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
140 @kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
141 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
144 @kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
148 @kbd{C-M-x}: a synonym for the above
151 @key{LFD}: Linefeed or Newline; same as @kbd{C-j}
154 @key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
157 @key{DEL}: @key{Delete}, usually @strong{not} the same as
158 @key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
159 deleting invokes Emacs help)
162 @key{ESC}: Escape; same as @kbd{C-[}
165 @key{TAB}: Tab; same as @kbd{C-i}
172 Key sequences longer than one key (and some single-key sequences) are
173 written inside quotes or on lines by themselves, like this:
176 @kbd{M-x frobnicate-while-foo RET}
180 Any real spaces in such a key sequence should be ignored; only @key{SPC}
181 really means press the space key.
183 The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
184 that would be sent by pressing just @key{x} minus 96 (or 64 for
185 upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
186 terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
187 @acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
188 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
190 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
193 @kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
194 @kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON@.
195 Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
196 @c FIXME I cannot understand the previous sentence.
198 @xref{Keys,,, emacs, The GNU Emacs Manual}.
200 @node Extended commands
201 @section What does @file{M-x @var{command}} mean?
202 @cindex Extended commands
203 @cindex Commands, extended
204 @cindex M-x, meaning of
206 @kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
207 command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
208 what @kbd{M-x} and @key{RET} mean.)
210 @kbd{M-x} (by default) invokes the command
211 @code{execute-extended-command}. This command allows you to run any
212 Emacs command if you can remember the command's name. If you can't
213 remember the command's name, you can type @key{TAB} and @key{SPC} for
214 completion, @key{?} for a list of possibilities, and @kbd{M-p} and
215 @kbd{M-n} (or up-arrow and down-arrow) to see previous commands entered.
216 An Emacs @dfn{command} is an @dfn{interactive} Emacs function.
219 Your system administrator may have bound other key sequences to invoke
220 @code{execute-extended-command}. A function key labeled @kbd{Do} is a
221 good candidate for this, on keyboards that have such a key.
223 If you need to run non-interactive Emacs functions, see @ref{Evaluating
227 @section How do I read topic XXX in the Emacs manual?
228 @cindex Emacs manual, reading topics in
229 @cindex Reading topics in the Emacs manual
230 @cindex Finding topics in the Emacs manual
231 @cindex Info, finding topics in
233 When we refer you to some @var{topic} in the Emacs manual, you can
234 read this manual node inside Emacs (assuming nothing is broken) by
235 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
237 This invokes Info, the GNU hypertext documentation browser. If you don't
238 already know how to use Info, type @key{?} from within Info.
240 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
241 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
243 If these commands don't work as expected, your system administrator may
244 not have installed the Info files, or may have installed them
245 improperly. In this case you should complain.
247 If you are reading this FAQ in Info, you can simply press @key{RET} on a
248 reference to follow it.
250 @xref{Getting a printed manual}, if you would like a paper copy of the
253 @node File-name conventions
254 @section What are @file{src/config.h}, @file{site-lisp/default.el}, etc.?
255 @cindex File-name conventions
256 @cindex Conventions for file names
257 @cindex Directories and files that come with Emacs
259 These are files that come with Emacs. The Emacs distribution is divided
260 into subdirectories; e.g., @file{etc}, @file{lisp}, and @file{src}.
261 Some of these (e.g., @file{etc} and @file{lisp}) are present both in
262 an installed Emacs and in the sources, but some (e.g., @file{src}) are
263 only found in the sources.
265 If you use Emacs, but don't know where it is kept on your system, start
266 Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
267 name displayed by this will be the full pathname of the installed
268 @file{etc} directory. (This full path is recorded in the Emacs variable
269 @code{data-directory}, and @kbd{C-h v} displays the value and the
270 documentation of a variable.)
272 The location of your Info directory (i.e., where Info documentation
273 is stored) is kept in the variable @code{Info-default-directory-list}. Use
274 @kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
275 this variable, which will be a list of directory names. The last
276 directory in that list is probably where most Info files are stored. By
277 default, Emacs Info documentation is placed in @file{/usr/local/share/info}.
279 For information on some of the files in the @file{etc} directory,
280 @pxref{Informational files for Emacs}.
282 @node Common acronyms
283 @section What are FSF, LPF, GNU, RMS, FTP, and GPL?
284 @cindex FSF, definition of
285 @cindex LPF, definition of
286 @cindex GNU, definition of
287 @cindex RMS, definition of
288 @cindex Stallman, Richard, acronym for
289 @cindex Richard Stallman, acronym for
290 @cindex FTP, definition of
291 @cindex GPL, definition of
292 @cindex Acronyms, definitions for
293 @cindex Common acronyms, definitions for
298 Free Software Foundation
301 League for Programming Freedom
307 Richard Matthew Stallman
310 File Transfer Protocol
313 GNU General Public License
317 Avoid confusing the FSF and the LPF@. The LPF opposes
318 look-and-feel copyrights and software patents. The FSF aims to make
319 high quality free software available for everyone.
321 The word ``free'' in the title of the Free Software Foundation refers to
322 ``freedom,'' not ``zero cost.'' Anyone can charge any price for
323 GPL-covered software that they want to. However, in practice, the
324 freedom enforced by the GPL leads to low prices, because you can always
325 get the software for less money from someone else, since everyone has
326 the right to resell or give away GPL-covered software.
328 @c ------------------------------------------------------------
329 @node General questions
330 @chapter General questions
331 @cindex General questions
333 This chapter contains general questions having to do with Emacs, the
334 Free Software Foundation, and related organizations.
338 * Real meaning of copyleft::
339 * Guidelines for newsgroup postings::
340 * Newsgroup archives::
342 * Unsubscribing from Emacs lists::
343 * Contacting the FSF::
347 @section What is the LPF?
348 @cindex LPF, description of
349 @cindex League for Programming Freedom
350 @cindex Software patents, opposition to
351 @cindex Patents for software, opposition to
353 The LPF opposes the expanding danger of software patents and
354 look-and-feel copyrights. More information on the LPF's views is
355 available at @uref{http://progfree.org/, the LPF home page}.
357 @node Real meaning of copyleft
358 @section What is the real legal meaning of the GNU copyleft?
359 @cindex Copyleft, real meaning of
360 @cindex GPL, real meaning of
361 @cindex General Public License, real meaning of
362 @cindex Discussion of the GPL
364 The real legal meaning of the GNU General Public License (copyleft) will
365 only be known if and when a judge rules on its validity and scope.
366 There has never been a copyright infringement case involving the GPL to
367 set any precedents. Although legal actions have been brought against
368 companies for violating the terms of the GPL, so far all have been
369 settled out of court (in favor of the plaintiffs). Please take any
370 discussion regarding this issue to the newsgroup
371 @uref{news:gnu.misc.discuss}, which was created to hold the extensive
372 flame wars on the subject.
377 The legal meaning of the GNU copyleft is less important than the spirit,
378 which is that Emacs is a free software project and that work pertaining
379 to Emacs should also be free software. ``Free'' means that all users
380 have the freedom to study, share, change and improve Emacs. To make
381 sure everyone has this freedom, pass along source code when you
382 distribute any version of Emacs or a related program, and give the
383 recipients the same freedom that you enjoyed.
386 @node Guidelines for newsgroup postings
387 @section What are appropriate messages for the various Emacs newsgroups?
388 @cindex Newsgroups, appropriate messages for
389 @cindex GNU newsgroups, appropriate messages for
390 @cindex Usenet groups, appropriate messages for
391 @cindex Mailing lists, appropriate messages for
392 @cindex Posting messages to newsgroups
394 @cindex GNU mailing lists
395 The Emacs mailing lists are described at
396 @uref{http://savannah.gnu.org/mail/?group=emacs, the Emacs Savannah
397 page}. Some of them are gatewayed to newsgroups.
399 The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
400 in general. The newsgroup @uref{news:gnu.emacs.help} is specifically
401 for GNU Emacs. It therefore makes no sense to cross-post to both
402 groups, since only one can be appropriate to any question.
404 Messages advocating ``non-free'' software are considered unacceptable on
405 any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
406 which was created to hold the extensive flame-wars on the subject.
407 ``Non-free'' software includes any software for which the end user can't
408 freely modify the source code and exchange enhancements. Be careful to
409 remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
410 posting a followup that recommends such software.
412 @uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
413 posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
415 @node Newsgroup archives
416 @section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
417 @cindex Archived postings from @code{gnu.emacs.help}
418 @cindex Usenet archives for GNU groups
419 @cindex Old Usenet postings for GNU groups
421 The FSF has maintained archives of all of the GNU mailing lists for many
422 years, although there may be some unintentional gaps in coverage. The
423 archive can be browsed over the web at
424 @uref{http://lists.gnu.org/archive/html/, the GNU mail archive}. Raw
425 files can be downloaded from @uref{ftp://lists.gnu.org/}.
427 Web-based Usenet search services, such as
428 @uref{http://groups.google.com/groups/dir?q=gnu&, Google}, also
429 archive the @code{gnu.*} groups.
431 You can also read the archives of the @code{gnu.*} groups and post new
432 messages at @uref{http://gmane.org/, Gmane}. Gmane is a service that
433 presents mailing lists as newsgroups (even those without a traditional
434 mail-to-news gateway).
437 @section Where should I report bugs and other problems with Emacs?
438 @cindex Bug reporting
439 @cindex Good bug reports
440 @cindex How to submit a bug report
441 @cindex Reporting bugs
443 The correct way to report Emacs bugs is to use the command
444 @kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
445 essential information and the correct e-mail address,
446 @email{bug-gnu-emacs@@gnu.org}.
447 Anything sent there also appears in the
448 newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
449 news to submit the bug report. This ensures a reliable return address
450 so you can be contacted for further details.
452 Be sure to read the ``Bugs'' section of the Emacs manual before reporting
453 a bug! The manual describes in detail how to submit a useful bug
454 report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
455 (@xref{Emacs manual}, if you don't know how to read the manual.)
460 Sending bug reports to
461 @url{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs,
462 the help-gnu-emacs mailing list}
463 (which has the effect of posting on @uref{news:gnu.emacs.help}) is
464 undesirable because it takes the time of an unnecessarily large group
465 of people, most of whom are just users and have no idea how to fix
467 @url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, The
468 bug-gnu-emacs list} reaches a much smaller group of people who are
469 more likely to know what to do and have expressed a wish to receive
470 more messages about Emacs than the others.
473 RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
476 If you have reported a bug and you don't hear about a possible fix,
477 then after a suitable delay (such as a week) it is okay to post on
478 @code{gnu.emacs.help} asking if anyone can help you.
481 If you are unsure whether you have found a bug, consider the following
482 non-exhaustive list, courtesy of RMS:
485 If Emacs crashes, that is a bug. If Emacs gets compilation errors
486 while building, that is a bug. If Emacs crashes while building, that
487 is a bug. If Lisp code does not do what the documentation says it
491 @node Unsubscribing from Emacs lists
492 @section How do I unsubscribe from a mailing list?
493 @cindex Unsubscribing from GNU mailing lists
494 @cindex Removing yourself from GNU mailing lists
496 If you are receiving a GNU mailing list named @var{list}, you should be
497 able to unsubscribe from it by sending a request to the address
498 @email{@var{list}-request@@gnu.org}. Mailing lists mails normally
499 contain information in either the message header
500 (@samp{List-Unsubscribe:}) or as a footer that tells you how to
503 @node Contacting the FSF
504 @section How do I contact the FSF?
505 @cindex Contracting the FSF
506 @cindex Free Software Foundation, contacting
508 For up-to-date information, see
509 @uref{http://www.fsf.org/about/contact.html, the FSF contact web-page}.
510 You can send general correspondence to @email{info@@fsf.org}.
512 @cindex Ordering GNU software
513 For details on how to order items directly from the FSF, see the
514 @uref{http://shop.fsf.org/, FSF on-line store}.
516 @c ------------------------------------------------------------
518 @chapter Getting help
521 This chapter tells you how to get help with Emacs.
525 * Learning how to do something::
526 * Getting a printed manual::
527 * Emacs Lisp documentation::
528 * Installing Texinfo documentation::
529 * Printing a Texinfo file::
530 * Viewing Info files outside of Emacs::
531 * Informational files for Emacs::
532 * Help installing Emacs::
533 * Obtaining the FAQ::
537 @section I'm just starting Emacs; how do I do basic editing?
538 @cindex Basic editing with Emacs
539 @cindex Beginning editing
540 @cindex Tutorial, invoking the
541 @cindex Self-paced tutorial, invoking the
542 @cindex Help system, entering the
544 Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
545 @kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
546 is available in many foreign languages such as French, German, Japanese,
547 Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
548 to choose your language and start the tutorial.
550 Your system administrator may have changed @kbd{C-h} to act like
551 @key{DEL} to deal with local keyboards. You can use @kbd{M-x
552 help-for-help} instead to invoke help. To discover what key (if any)
553 invokes help on your system, type @kbd{M-x where-is @key{RET}
554 help-for-help @key{RET}}. This will print a comma-separated list of key
555 sequences in the echo area. Ignore the last character in each key
556 sequence listed. Each of the resulting key sequences (e.g., @key{F1} is
557 common) invokes help.
559 Emacs help works best if it is invoked by a single key whose value
560 should be stored in the variable @code{help-char}.
562 Some Emacs slides and tutorials can be found at
563 @uref{http://web.psung.name/emacs/}.
565 @node Learning how to do something
566 @section How do I find out how to do something in Emacs?
567 @cindex Help for Emacs
568 @cindex Learning to do something in Emacs
569 @cindex Reference card for Emacs
570 @cindex Overview of help systems
572 There are several methods for finding out how to do things in Emacs.
576 @cindex Reading the Emacs manual
578 The complete text of the Emacs manual is available via the Info
579 hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
580 Typing @key{h} immediately after entering Info will provide a short
581 tutorial on how to use it.
583 @cindex Lookup a subject in a manual
584 @cindex Index search in a manual
586 To quickly locate the section of the manual which discusses a certain
587 issue, or describes a command or a variable, type @kbd{C-h i m emacs
588 @key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
589 topic, the command, or the variable which you are looking for. If this
590 does not land you on the right place in the manual, press @kbd{,}
591 (comma) repeatedly until you find what you need. (The @kbd{i} and
592 @kbd{,} keys invoke the index-searching functions, which look for the
593 @var{topic} you type in all the indices of the Emacs manual.)
597 You can list all of the commands whose names contain a certain word
598 (actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
601 @cindex Command description in the manual
603 The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
604 for the name of a command, and then attempts to find the section in the
605 Emacs manual where that command is described.
607 @cindex Finding commands and variables
609 You can list all of the functions and variables whose names contain a
610 certain word using @kbd{M-x apropos}.
613 You can list all of the functions and variables whose documentation
614 matches a regular expression or a string, using @kbd{M-x
615 apropos-documentation}.
618 You can order a hardcopy of the manual from the FSF@. @xref{Getting a
621 @cindex Reference cards, in other languages
623 You can get a printed reference card listing commands and keys to
624 invoke them. You can order one from the FSF for $2 (or 10 for $18),
625 or you can print your own from the @file{etc/refcards/refcard.tex} or
626 @file{etc/refcards/refcard.pdf} files in the Emacs distribution.
627 Beginning with version 21.1, the Emacs distribution comes with
628 translations of the reference card into several languages; look for
629 files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang}
630 is a two-letter code of the language. For example, the German version
631 of the reference card is in the files @file{etc/refcards/de-refcard.tex}
632 and @file{etc/refcards/de-refcard.pdf}.
635 There are many other commands in Emacs for getting help and
636 information. To get a list of these commands, type @samp{?} after
641 @node Getting a printed manual
642 @section How do I get a printed copy of the Emacs manual?
643 @cindex Printed Emacs manual, obtaining
644 @cindex Manual, obtaining a printed or HTML copy of
645 @cindex Emacs manual, obtaining a printed or HTML copy of
647 You can order a printed copy of the Emacs manual from the FSF@. For
648 details see the @uref{http://shop.fsf.org/, FSF on-line store}.
650 The full Texinfo source for the manual also comes in the @file{doc/emacs}
651 directory of the Emacs distribution, if you're daring enough to try to
652 print out this several-hundred-page manual yourself (@pxref{Printing a Texinfo
655 If you absolutely have to print your own copy, and you don't have @TeX{},
656 you can get a PostScript or PDF (or HTML) version from
658 @uref{http://www.gnu.org/software/emacs/manual/}
660 @xref{Learning how to do something}, for how to view the manual from Emacs.
662 @node Emacs Lisp documentation
663 @section Where can I get documentation on Emacs Lisp?
664 @cindex Documentation on Emacs Lisp
665 @cindex Function documentation
666 @cindex Variable documentation
667 @cindex Emacs Lisp Reference Manual
668 @cindex Reference manual for Emacs Lisp
670 Within Emacs, you can type @kbd{C-h f} to get the documentation for a
671 function, @kbd{C-h v} for a variable.
673 For more information, the Emacs Lisp Reference Manual is available
674 in Info format (@pxref{Top, Emacs Lisp,, elisp, The
675 Emacs Lisp Reference Manual}).
677 You can also order a hardcopy of the manual from the FSF, for details
678 see the @uref{http://shop.fsf.org/, FSF on-line store}. (This manual is
679 not always in print.)
681 An HTML version of the Emacs Lisp Reference Manual is available at
683 @uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
685 @node Installing Texinfo documentation
686 @section How do I install a piece of Texinfo documentation?
687 @cindex Texinfo documentation, installing
688 @cindex Installing Texinfo documentation
689 @cindex New Texinfo files, installing
690 @cindex Documentation, installing new Texinfo files
691 @cindex Info files, how to install
693 Emacs releases come with pre-built Info files, and the normal install
694 process places them in the correct location. This is true for most
695 applications that provide Info files. The following section is only
696 relevant if you want to install extra Info files by hand.
698 First, you must turn the Texinfo source files into Info files. You may
699 do this using the stand-alone @file{makeinfo} program, available as part
700 of the Texinfo package at
702 @uref{http://www.gnu.org/software/texinfo/}
704 For information about the Texinfo format, read the Texinfo manual which
705 comes with the Texinfo package. This manual also comes installed in
706 Info format, so you can read it from Emacs; type @kbd{C-h i m texinfo
709 @c FIXME is this a complete alternative?
710 @c Probably not, given that we require makeinfo to build Emacs.
711 Alternatively, you could use the Emacs command @kbd{M-x
712 texinfo-format-buffer}, after visiting the Texinfo source file of the
713 manual you want to convert.
715 Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
716 resulting Info files in Emacs's Info tree. To install Info files,
721 Move the files to the @file{info} directory in the installed Emacs
722 distribution. @xref{File-name conventions}, if you don't know where that
726 Run the @code{install-info} command, which is part of the Texinfo
727 distribution, to update the main Info directory menu, like this:
730 install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
734 where @var{dir-path} is the full path to the directory where you copied
735 the produced Info file(s), and @var{file} is the name of the Info file
736 you produced and want to install.
738 If you don't have the @code{install-info} command installed, you can
739 edit the file @file{info/dir} in the installed Emacs distribution, and
740 add a line for the top level node in the Info package that you are
741 installing. Follow the examples already in this file. The format is:
744 * Topic: (relative-pathname). Short description of topic.
749 If you want to install Info files and you don't have the necessary
750 privileges, you have several options:
754 Info files don't actually need to be installed before being used.
755 You can use a prefix argument for the @code{info} command and specify
756 the name of the Info file in the minibuffer. This goes to the node
757 named @samp{Top} in that file. For example, to view a Info file named
758 @file{@var{info-file}} in your home directory, you can type this:
761 @kbd{C-u C-h i ~/@var{info-file} @key{RET}}
764 Alternatively, you can feed a file name to the @code{Info-goto-node}
765 command (invoked by pressing @key{g} in Info mode) by typing the name
766 of the file in parentheses, like this:
769 @kbd{C-h i g (~/@var{info-file}) @key{RET}}
773 You can create your own Info directory. You can tell Emacs where that
774 Info directory is by adding its pathname to the value of the variable
775 @code{Info-default-directory-list}. For example, to use a private Info
776 directory which is a subdirectory of your home directory named @file{Info},
777 you could put this in your @file{.emacs} file:
780 (add-to-list 'Info-default-directory-list "~/Info")
783 You will need a top-level Info file named @file{dir} in this directory
784 which has everything the system @file{dir} file has in it, except it
785 should list only entries for Info files in that directory. You might
786 not need it if (fortuitously) all files in this directory were
787 referenced by other @file{dir} files. The node lists from all
788 @file{dir} files in @code{Info-default-directory-list} are merged by the
793 @node Printing a Texinfo file
794 @section How do I print a Texinfo file?
795 @cindex Printing a Texinfo file
796 @cindex Texinfo file, printing
797 @cindex Printing documentation
799 You can't get nicely printed output from Info files; you must still have
800 the original Texinfo source file for the manual you want to print.
802 Assuming you have @TeX{} installed on your system, follow these steps:
807 Make sure the first line of the Texinfo file looks like this:
813 You may need to change @samp{texinfo} to the full pathname of the
814 @file{texinfo.tex} file, which comes with Emacs as
815 @file{doc/misc/texinfo.tex} (or copy or link it into the current directory).
818 Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
819 the name of the Texinfo source file for which you want to produce a
820 printed copy. The @samp{texi2dvi} script is part of the GNU Texinfo
823 Alternatively, @samp{texi2pdf} produces PDF files.
826 Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
827 printing DVI files at your site. For example, if you have a PostScript
828 printer, run the @code{dvips} program to print the DVI file on that
833 To get more general instructions, retrieve the latest Texinfo package
834 (@pxref{Installing Texinfo documentation}).
836 @node Viewing Info files outside of Emacs
837 @section Can I view Info files without using Emacs?
838 @cindex Viewing Info files
839 @cindex Info file viewers
840 @cindex Alternative Info file viewers
842 Yes. Here are some alternative programs:
847 @code{info}, a stand-alone version of the Info program, comes as part of
848 the Texinfo package. @xref{Installing Texinfo documentation}, for
852 Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
853 You can get Tkinfo at
854 @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
858 @node Informational files for Emacs
859 @section What informational files are available for Emacs?
860 @cindex Informational files included with Emacs
861 @cindex Files included with Emacs
862 @cindex @file{COPYING}, description of file
863 @cindex @file{DISTRIB}, description of file
864 @cindex @file{GNU}, description of file
865 @cindex @file{MACHINES}, description of file
866 @cindex @file{NEWS}, description of file
868 This isn't a frequently asked question, but it should be! A variety of
869 informational files about Emacs and relevant aspects of the GNU project
870 are available for you to read.
872 The following files (and others) are available in the @file{etc}
873 directory of the Emacs distribution (see @ref{File-name conventions}, if
874 you're not sure where that is). Many of these files are available via
875 the Emacs @samp{Help} menu, or by typing @kbd{C-h ?} (@kbd{M-x
881 GNU General Public License
884 Emacs Availability Information
890 Status of Emacs on Various Machines and Systems
893 Emacs news, a history of recent user-visible changes
897 More GNU information, including back issues of the @cite{GNU's
900 @uref{http://www.gnu.org/bulletins/bulletins.html} and
902 @uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
904 @node Help installing Emacs
905 @section Where can I get help in installing Emacs?
906 @cindex Installation help
907 @cindex Help installing Emacs
909 @xref{Installing Emacs}, for some basic installation hints, and see
910 @ref{Problems building Emacs}, if you have problems with the installation.
912 @uref{http://www.fsf.org/resources/service/, The GNU Service directory}
913 lists companies and individuals willing to sell you help in installing
914 or using Emacs and other GNU software.
916 @node Obtaining the FAQ
917 @section Where can I get the latest version of this FAQ?
918 @cindex FAQ, obtaining the
919 @cindex Latest FAQ version, obtaining the
921 The Emacs FAQ is distributed with Emacs in Info format. You can read it
922 by selecting the @samp{Emacs FAQ} option from the @samp{Help} menu of
923 the Emacs menu bar at the top of any Emacs frame, or by typing @kbd{C-h
924 C-f} (@kbd{M-x view-emacs-FAQ}). The very latest version is available
925 in the Emacs development repository (@pxref{Latest version of Emacs}).
927 @c ------------------------------------------------------------
928 @node Status of Emacs
929 @chapter Status of Emacs
930 @cindex Status of Emacs
932 This chapter gives you basic information about Emacs, including the
933 status of its latest version.
936 * Origin of the term Emacs::
937 * Latest version of Emacs::
945 @node Origin of the term Emacs
946 @section Where does the name ``Emacs'' come from?
947 @cindex Origin of the term ``Emacs''
948 @cindex Emacs name origin
950 @cindex Original version of Emacs
952 Emacs originally was an acronym for Editor MACroS@. RMS says he ``picked
953 the name Emacs because @key{E} was not in use as an abbreviation on ITS at
954 the time.'' The first Emacs was a set of macros written in 1976 at MIT
955 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
956 Editor and COrrector) under ITS (the Incompatible Timesharing System) on
957 a PDP-10. RMS had already extended TECO with a ``real-time''
958 full-screen mode with reprogrammable keys. Emacs was started by
960 Guy Steele as a project to unify the many
961 divergent TECO command sets and key bindings at MIT, and completed by
964 Many people have said that TECO code looks a lot like line noise; you
965 can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
966 implementation in Emacs Lisp (to find it, see @ref{Packages that do not
967 come with Emacs}); it would be an interesting project to run the
968 original TECO Emacs inside of Emacs.
971 For some not-so-serious alternative reasons for Emacs to have that
972 name, check out the file @file{etc/JOKES} (@pxref{File-name
975 @node Latest version of Emacs
976 @section What is the latest version of Emacs?
977 @cindex Version, latest
978 @cindex Latest version of Emacs
979 @cindex Development, Emacs
980 @cindex Repository, Emacs
981 @cindex Bazaar repository, Emacs
983 Emacs @value{EMACSVER} is the current version as of this writing. A version
984 number with two components (e.g., @samp{22.1}) indicates a released
985 version; three components indicate a development
986 version (e.g., @samp{23.0.50} is what will eventually become @samp{23.1}).
988 Emacs is under active development, hosted at
989 @uref{http://savannah.gnu.org/projects/emacs/, Savannah}. The source
990 code can be retrieved anonymously following the
991 @uref{http://savannah.gnu.org/bzr/?group=emacs, instructions}.
992 The repository is GNU Bazaar.
994 Because Emacs undergoes many changes before a release, the version
995 number of a development version is not especially meaningful. It is
996 better to refer to the date on which the sources were retrieved from the
997 development repository. The development version is usually quite robust
998 for every-day use, but if stability is more important to you than the
999 latest features, you may want to stick to the releases.
1001 The following sections list some of the major new features in the last
1002 few Emacs releases. For full details of the changes in any version of
1003 Emacs, type @kbd{C-h C-n} (@kbd{M-x view-emacs-news}). As of Emacs 22,
1004 you can give this command a prefix argument to read about which features
1005 were new in older versions.
1007 @node New in Emacs 24
1008 @section What is different about Emacs 24?
1009 @cindex Differences between Emacs 23 and Emacs 24
1010 @cindex Emacs 24, new features in
1013 @cindex packages, installing more
1015 Emacs now includes a package manager. Type @kbd{M-x list-packages} to
1016 get started. You can use this to download and automatically install
1017 many more Lisp packages.
1019 @cindex lexical binding
1021 Emacs Lisp now supports lexical binding on a per-file basis. In
1022 @emph{lexical binding}, variable references must be located textually
1023 within the binding construct. This contrasts with @emph{dynamic
1024 binding}, where programs can refer to variables defined outside their
1025 local textual scope. A Lisp file can use a local variable setting of
1026 @code{lexical-binding: t} to indicate that the contents should be
1027 interpreted using lexical binding. See the Emacs Lisp Reference
1028 Manual for more details.
1030 @cindex bidirectional display
1031 @cindex right-to-left languages
1033 Some human languages, such as English, are written from left to right.
1034 Others, such as Arabic, are written from right to left. Emacs now has
1035 support for any mixture of these forms---this is ``bidirectional text''.
1038 Handling of text selections has been improved, and now integrates
1039 better with external clipboards.
1043 A new command @kbd{customize-themes} allows you to easily change the
1044 appearance of your Emacs.
1047 Emacs can be compiled with the GTK+ 3 toolkit.
1050 Support for several new external libraries can be included at compile
1056 ``Security-Enhanced Linux'' (SELinux) is a Linux kernel feature that
1057 provides more sophisticated file access controls than ordinary
1058 ``Unix-style'' file permissions.
1061 The ImageMagick display library. This allows you to display many more
1062 image format in Emacs, as well as carry out transformations such as
1066 The GnuTLS library for secure network communications. Emacs uses this
1067 transparently for email if your mail server supports it.
1070 The libxml2 library for parsing XML structures.
1074 Much more flexibility in the handling of windows and buffer display.
1078 As always, consult the @file{NEWS} file for more information.
1081 @node New in Emacs 23
1082 @section What is different about Emacs 23?
1083 @cindex Differences between Emacs 22 and Emacs 23
1084 @cindex Emacs 23, new features in
1088 @cindex Anti-aliased fonts
1089 @cindex Freetype fonts
1091 Emacs has a new font code that can use multiple font backends,
1092 including freetype and fontconfig. Emacs can use the Xft library for
1093 anti-aliasing, and the otf and m17n libraries for complex text layout and
1097 @cindex Character sets
1099 The Emacs character set is now a superset of Unicode. Several new
1100 language environments have been added.
1102 @cindex Multi-tty support
1103 @cindex X and tty displays
1105 Emacs now supports using both X displays and ttys in the same session
1110 Emacs can be started as a daemon in the background.
1112 @cindex NeXTstep port
1113 @cindex GNUstep port
1114 @cindex Mac OS X Cocoa
1116 There is a new NeXTstep port of Emacs. This supports GNUstep and Mac OS
1117 X (via the Cocoa libraries). The Carbon port of Emacs, which supported
1118 Mac OS X in Emacs 22, has been removed.
1120 @cindex Directory-local variables
1122 Directory-local variables can now be defined, in a similar manner to
1123 file-local variables.
1126 Transient Mark mode (@pxref{Highlighting a region}) is on by default.
1131 Other changes include: support for serial port access; D-Bus bindings; a
1132 new Visual Line mode for line-motion; improved completion; a new mode
1133 (@samp{DocView}) for viewing of PDF, PostScript, and DVI documents; nXML
1134 mode (for editing XML documents) is included; VC has been updated for
1135 newer version control systems; etc.
1138 @node New in Emacs 22
1139 @section What is different about Emacs 22?
1140 @cindex Differences between Emacs 21 and Emacs 22
1141 @cindex Emacs 22, new features in
1144 @cindex GTK+ Toolkit
1145 @cindex Drag-and-drop
1147 Emacs can be built with GTK+ widgets, and supports drag-and-drop
1150 @cindex Supported systems
1152 Emacs 22 features support for GNU/Linux systems on S390 and x86-64
1153 machines, as well as support for the Mac OS X and Cygwin operating
1157 The native MS-Windows, and Mac OS X builds include full support
1158 for images, toolbar, and tooltips.
1161 Font Lock mode, Auto Compression mode, and File Name Shadow Mode are
1165 The maximum size of buffers is increased: on 32-bit machines, it is
1166 256 MBytes for Emacs 23.1, and 512 MBytes for Emacs 23.2 and above.
1169 Links can be followed with @kbd{mouse-1}, in addition to @kbd{mouse-2}.
1173 Mouse wheel support is enabled by default.
1176 Window fringes are customizable.
1179 The mode line of the selected window is now highlighted.
1182 The minibuffer prompt is displayed in a distinct face.
1185 Abbrev definitions are read automatically at startup.
1188 Grep mode is separate from Compilation mode and has many new options and
1189 commands specific to grep.
1192 The original Emacs macro system has been replaced by the new Kmacro
1193 package, which provides many new commands and features and a simple
1194 interface that uses the function keys F3 and F4. Macros are stored in a
1195 macro ring, and can be debugged and edited interactively.
1198 The Grand Unified Debugger (GUD) can be used with a full graphical user
1199 interface to GDB; this provides many features found in traditional
1200 development environments, making it easy to manipulate breakpoints, add
1201 watch points, display the call stack, etc. Breakpoints are visually
1202 indicated in the source buffer.
1206 Many new modes and packages have been included in Emacs, such as Calc,
1207 TRAMP, URL, IDO, CUA, ERC, rcirc, Table, Image-Dired, SES, Ruler, Org,
1208 PGG, Flymake, Password, Printing, Reveal, wdired, t-mouse, longlines,
1209 savehist, Conf mode, Python mode, DNS mode, etc.
1211 @cindex Multilingual Environment
1213 Leim is now part of Emacs. Unicode support has been much improved, and
1214 the following input methods have been added: belarusian, bulgarian-bds,
1215 bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian,
1216 latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard,
1217 lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345,
1218 russian-computer, sgml, slovenian, tamil-inscript, ucs,
1219 ukrainian-computer, vietnamese-telex, and welsh.
1221 The following language environments have also been added: Belarusian,
1222 Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6,
1223 Latin-7, Latvian, Lithuanian, Malayalam, Russian, Slovenian, Swedish,
1224 Tajik, Tamil, UTF-8, Ukrainian, Welsh, and Windows-1255.
1226 @cindex Documentation
1227 @cindex Emacs Lisp Manual
1229 In addition, Emacs 22 now includes the Emacs Lisp Reference Manual
1230 (@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro.
1234 @node New in Emacs 21
1235 @section What is different about Emacs 21?
1236 @cindex Differences between Emacs 20 and Emacs 21
1237 @cindex Emacs 21, new features in
1239 @cindex Variable-size fonts
1240 @cindex Toolbar support
1241 Emacs 21 features a thorough rewrite of the display engine. The new
1242 display engine supports variable-size fonts, images, and can play sounds
1243 on platforms which support that. As a result, the visual appearance of
1244 Emacs, when it runs on a windowed display, is much more reminiscent of
1245 modern GUI programs, and includes 3D widgets (used for the mode line and
1246 the scroll bars), a configurable and extensible toolbar, tooltips
1247 (a.k.a.@: balloon help), and other niceties.
1249 @cindex Colors on text-only terminals
1251 In addition, Emacs 21 supports faces on text-only terminals. This means
1252 that you can now have colors when you run Emacs on a GNU/Linux console
1253 and on @code{xterm} with @kbd{emacs -nw}.
1256 @node New in Emacs 20
1257 @section What is different about Emacs 20?
1258 @cindex Differences between Emacs 19 and Emacs 20
1259 @cindex Emacs 20, new features in
1261 The differences between Emacs versions 18 and 19 were rather dramatic;
1262 the introduction of frames, faces, and colors on windowing systems was
1263 obvious to even the most casual user.
1265 There are differences between Emacs versions 19 and 20 as well, but many
1266 are more subtle or harder to find. Among the changes are the inclusion
1267 of MULE code for languages that use non-Latin characters and for mixing
1268 several languages in the same document; the ``Customize'' facility for
1269 modifying variables without having to use Lisp; and automatic conversion
1270 of files from Macintosh, Microsoft, and Unix platforms.
1272 @c ------------------------------------------------------------
1273 @node Common requests
1274 @chapter Common requests
1275 @cindex Common requests
1278 * Setting up a customization file::
1281 * Debugging a customization file::
1282 * Displaying the current line or column::
1283 * Displaying the current file name in the titlebar::
1284 * Turning on abbrevs by default::
1285 * Associating modes with files::
1286 * Highlighting a region::
1287 * Replacing highlighted text::
1288 * Controlling case sensitivity::
1289 * Working with unprintable characters::
1290 * Searching for/replacing newlines::
1291 * Yanking text in isearch::
1292 * Wrapping words automatically::
1293 * Turning on auto-fill by default::
1294 * Changing load-path::
1295 * Using an already running Emacs process::
1296 * Compiler error messages::
1297 * Indenting switch statements::
1298 * Customizing C and C++ indentation::
1299 * Horizontal scrolling::
1301 * Turning off beeping::
1302 * Turning the volume down::
1303 * Automatic indentation::
1304 * Matching parentheses::
1305 * Hiding #ifdef lines::
1306 * Repeating commands::
1307 * Valid X resources::
1308 * Evaluating Emacs Lisp code::
1309 * Changing the length of a Tab::
1310 * Inserting text at the beginning of each line::
1311 * Forcing the cursor to remain in the same column::
1312 * Forcing Emacs to iconify itself::
1313 * Using regular expressions::
1314 * Replacing text across multiple files::
1315 * Documentation for etags::
1316 * Disabling backups::
1317 * Disabling auto-save-mode::
1318 * Going to a line by number::
1319 * Modifying pull-down menus::
1320 * Deleting menus and menu options::
1321 * Turning on syntax highlighting::
1322 * Scrolling only one line::
1323 * Editing MS-DOS files::
1324 * Filling paragraphs with a single space::
1325 * Escape sequences in shell output::
1326 * Fullscreen mode on MS-Windows::
1329 @node Setting up a customization file
1330 @section How do I set up a @file{.emacs} file properly?
1331 @cindex @file{.emacs} file, setting up
1332 @cindex @file{.emacs} file, locating
1333 @cindex Init file, setting up
1334 @cindex Customization file, setting up
1336 @xref{Init File,,, emacs, The GNU Emacs Manual}.
1338 In general, new Emacs users should not be provided with @file{.emacs}
1339 files, because this can cause confusing non-standard behavior. Then
1340 they send questions to
1341 @url{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs,
1342 the help-gnu-emacs mailing list} asking why Emacs
1343 isn't behaving as documented.
1345 Emacs includes the Customize facility (@pxref{Using Customize}). This
1346 allows users who are unfamiliar with Emacs Lisp to modify their
1347 @file{.emacs} files in a relatively straightforward way, using menus
1348 rather than Lisp code.
1350 While Customize might indeed make it easier to configure Emacs,
1351 consider taking a bit of time to learn Emacs Lisp and modifying your
1352 @file{.emacs} directly. Simple configuration options are described
1353 rather completely in @ref{Init File,,, emacs, The GNU Emacs Manual},
1354 for users interested in performing frequently requested, basic tasks.
1356 Sometimes users are unsure as to where their @file{.emacs} file should
1357 be found. Visiting the file as @file{~/.emacs} from Emacs will find
1360 @node Using Customize
1361 @section How do I start using Customize?
1362 @cindex Customize groups
1363 @cindex Customizing variables
1364 @cindex Customizing faces
1366 The main Customize entry point is @kbd{M-x customize @key{RET}}. This
1367 command takes you to a buffer listing all the available Customize
1368 groups. From there, you can access all customizable options and faces,
1369 change their values, and save your changes to your init file.
1370 @xref{Easy Customization,,, emacs, The GNU Emacs Manual}.
1372 If you know the name of the group in advance (e.g., ``shell''), use
1373 @kbd{M-x customize-group @key{RET}}.
1375 If you wish to customize a single option, use @kbd{M-x customize-option
1376 @key{RET}}. This command prompts you for the name of the option to
1377 customize, with completion.
1379 @node Colors on a TTY
1380 @section How do I get colors and syntax highlighting on a TTY?
1381 @cindex Colors on a TTY
1382 @cindex Syntax highlighting on a TTY
1383 @cindex Console, colors
1385 In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
1386 i.e., on Unix and GNU/Linux text-only terminals and consoles, and when
1387 invoked as @samp{emacs -nw} on X, and MS-Windows. (Colors and faces were
1388 supported in the MS-DOS port since Emacs 19.29.) Emacs automatically
1389 detects color support at startup and uses it if available. If you think
1390 that your terminal supports colors, but Emacs won't use them, check the
1391 @code{termcap} entry for your display type for color-related
1394 The command @kbd{M-x list-colors-display} pops up a window which
1395 exhibits all the colors Emacs knows about on the current display.
1397 Syntax highlighting is on by default since version 22.1.
1399 @node Debugging a customization file
1400 @section How do I debug a @file{.emacs} file?
1401 @cindex Debugging @file{.emacs} file
1402 @cindex @file{.emacs} debugging
1403 @cindex Init file debugging
1404 @cindex @samp{-debug-init} option
1406 Start Emacs with the @samp{-debug-init} command-line option. This
1407 enables the Emacs Lisp debugger before evaluating your @file{.emacs}
1408 file, and places you in the debugger if something goes wrong. The top
1409 line in the @file{trace-back} buffer will be the error message, and the
1410 second or third line of that buffer will display the Lisp code from your
1411 @file{.emacs} file that caused the problem.
1413 You can also evaluate an individual function or argument to a function
1414 in your @file{.emacs} file by moving the cursor to the end of the
1415 function or argument and typing @kbd{C-x C-e} (@kbd{M-x
1418 Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
1419 variables which you are trying to set or use.
1421 @node Displaying the current line or column
1422 @section How do I make Emacs display the current line (or column) number?
1423 @cindex @code{line-number-mode}
1424 @cindex Displaying the current line or column
1425 @cindex Line number, displaying the current
1426 @cindex Column, displaying the current
1427 @cindex @code{mode-line-format}
1429 By default, Emacs displays the current line number of the point in the
1430 mode line. You can toggle this feature off or on with the command
1431 @kbd{M-x line-number-mode}, or by setting the variable
1432 @code{line-number-mode}. Note that Emacs will not display the line
1433 number if the buffer's size in bytes is larger than the value of the
1434 variable @code{line-number-display-limit}.
1436 You can similarly display the current column with
1437 @kbd{M-x column-number-mode}, or by putting the form
1440 (setq column-number-mode t)
1444 in your @file{.emacs} file. This feature is off by default.
1446 The @code{"%c"} format specifier in the variable @code{mode-line-format}
1447 will insert the current column's value into the mode line. See the
1448 documentation for @code{mode-line-format} (using @kbd{C-h v
1449 mode-line-format @key{RET}}) for more information on how to set and use
1452 @cindex Set number capability in @code{vi} emulators
1453 The @samp{linum} package (distributed with Emacs since version 23.1)
1454 displays line numbers in the left margin, like the ``set number''
1455 capability of @code{vi}. The packages @samp{setnu} and
1456 @samp{wb-line-number} (not distributed with Emacs) also implement this
1459 @node Displaying the current file name in the titlebar
1460 @section How can I modify the titlebar to contain the current file name?
1461 @cindex Titlebar, displaying the current file name in
1462 @cindex File name, displaying in the titlebar
1463 @cindex @code{frame-title-format}
1465 The contents of an Emacs frame's titlebar is controlled by the variable
1466 @code{frame-title-format}, which has the same structure as the variable
1467 @code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x
1468 describe-variable} to get information about one or both of these
1471 By default, the titlebar for a frame does contain the name of the buffer
1472 currently being visited, except if there is a single frame. In such a
1473 case, the titlebar contains Emacs invocation name and the name of the
1474 machine at which Emacs was invoked. This is done by setting
1475 @code{frame-title-format} to the default value of
1478 (multiple-frames "%b" ("" invocation-name "@@" system-name))
1481 To modify the behavior such that frame titlebars contain the buffer's
1482 name regardless of the number of existing frames, include the following
1483 in your @file{.emacs}:
1486 (setq frame-title-format "%b")
1489 @node Turning on abbrevs by default
1490 @section How do I turn on abbrevs by default just in mode @var{mymode}?
1491 @cindex Abbrevs, turning on by default
1493 Abbrev mode expands abbreviations as you type them. To turn it on in a
1494 specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every
1495 buffer by default, put this in your @file{.emacs} file:
1498 (setq-default abbrev-mode t)
1501 @noindent To turn it on in a specific mode, use:
1504 (add-hook '@var{mymode}-mode-hook
1506 (setq abbrev-mode t)))
1509 @noindent If your Emacs version is older then 22.1, you will also need to use:
1513 (quietly-read-abbrev-file)
1517 @node Associating modes with files
1518 @section How do I make Emacs use a certain major mode for certain files?
1519 @cindex Associating modes with files
1520 @cindex File extensions and modes
1521 @cindex @code{auto-mode-alist}, modifying
1522 @cindex Modes, associating with file extensions
1524 If you want to use a certain mode @var{foo} for all files whose names end
1525 with the extension @file{.@var{bar}}, this will do it for you:
1528 (add-to-list 'auto-mode-alist '("\\.@var{bar}\\'" . @var{foo}-mode))
1531 Alternatively, put this somewhere in the first line of any file you want to
1532 edit in the mode @var{foo} (in the second line, if the first line begins
1539 @cindex Major mode for shell scripts
1540 The variable @code{interpreter-mode-alist} specifies which mode to use
1541 when loading an interpreted script (e.g., shell, python, etc.). Emacs
1542 determines which interpreter you're using by examining the first line of
1543 the script. Use @kbd{C-h v} (or @kbd{M-x describe-variable}) on
1544 @code{interpreter-mode-alist} to learn more.
1546 @node Highlighting a region
1547 @section How can I highlight a region of text in Emacs?
1548 @cindex Highlighting text
1549 @cindex Text, highlighting
1550 @cindex @code{transient-mark-mode}
1551 @cindex Region, highlighting a
1553 You can cause the region to be highlighted when the mark is active by
1557 (transient-mark-mode 1)
1561 in your @file{.emacs} file. Since Emacs 23.1, this feature is on by default.
1563 @node Replacing highlighted text
1564 @section How can I replace highlighted text with what I type?
1565 @cindex @code{delete-selection-mode}
1566 @cindex Replacing highlighted text
1567 @cindex Highlighting and replacing text
1569 Use @code{delete-selection-mode}, which you can start automatically by
1570 placing the following Lisp form in your @file{.emacs} file:
1573 (delete-selection-mode 1)
1576 According to the documentation string for @code{delete-selection-mode}
1577 (which you can read using @kbd{M-x describe-function @key{RET}
1578 delete-selection-mode @key{RET}}):
1581 When Delete Selection mode is enabled, Transient Mark mode is also
1582 enabled and typed text replaces the selection if the selection is
1583 active. Otherwise, typed text is just inserted at point regardless of
1587 This mode also allows you to delete (not kill) the highlighted region by
1590 @node Controlling case sensitivity
1591 @section How do I control Emacs's case-sensitivity when searching/replacing?
1592 @cindex @code{case-fold-search}
1593 @cindex Case sensitivity of searches
1594 @cindex Searching without case sensitivity
1595 @cindex Ignoring case in searches
1598 The value of the variable @code{case-fold-search} determines whether
1599 searches are case sensitive:
1602 (setq case-fold-search nil) ; make searches case sensitive
1603 (setq case-fold-search t) ; make searches case insensitive
1606 @cindex Case sensitivity in replacements
1607 @cindex Replacing, and case sensitivity
1608 @cindex @code{case-replace}
1609 Similarly, for replacing, the variable @code{case-replace} determines
1610 whether replacements preserve case.
1612 You can also toggle case sensitivity at will in isearch with @kbd{M-c}.
1614 To change the case sensitivity just for one major mode, use the major
1615 mode's hook. For example:
1618 (add-hook '@var{foo}-mode-hook
1620 (setq case-fold-search nil)))
1623 @node Working with unprintable characters
1624 @section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
1625 @cindex Unprintable characters, working with
1626 @cindex Working with unprintable characters
1627 @cindex Control characters, working with
1628 @cindex Eight-bit characters, working with
1629 @cindex Searching for unprintable characters
1630 @cindex Regexps and unprintable characters
1632 To search for a single character that appears in the buffer as, for
1633 example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}.
1634 Searching for @strong{all} unprintable characters is best done with a
1635 regular expression (@dfn{regexp}) search. The easiest regexp to use for
1636 the unprintable chars is the complement of the regexp for the printable
1642 Regexp for the printable chars: @samp{[\t\n\r\f -~]}
1645 Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
1649 To type these special characters in an interactive argument to
1650 @code{isearch-forward-regexp} or @code{re-search-forward}, you need to
1651 use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
1652 respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So,
1653 to search for unprintable characters using @code{re-search-forward}:
1655 @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}}
1657 Using @code{isearch-forward-regexp}:
1659 @kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
1661 To delete all unprintable characters, simply use replace-regexp:
1663 @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}}
1665 Replacing is similar to the above. To replace all unprintable
1666 characters with a colon, use:
1668 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}
1670 @node Searching for/replacing newlines
1671 @section How do I input a newline character in isearch or query-replace?
1672 @cindex Searching for newlines
1673 @cindex Replacing newlines
1675 Use @kbd{C-q C-j}. For more information,
1676 @pxref{Special Isearch,, Special Input for Incremental Search, emacs,
1677 The GNU Emacs Manual}.
1679 @node Yanking text in isearch
1680 @section How do I copy text from the kill ring into the search string?
1681 @cindex Yanking text into the search string
1682 @cindex isearch yanking
1684 Use @kbd{M-y}. @xref{Isearch Yank,,, emacs, The GNU Emacs Manual}.
1686 @node Wrapping words automatically
1687 @section How do I make Emacs wrap words for me?
1688 @cindex Wrapping word automatically
1689 @cindex Wrapping lines
1691 @cindex @code{auto-fill-mode}, introduction to
1692 @cindex Maximum line width, default value
1693 @cindex @code{fill-column}, default value
1695 Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
1696 The default maximum line width is 70, determined by the variable
1697 @code{fill-column}. To learn how to turn this on automatically, see
1698 @ref{Turning on auto-fill by default}.
1700 @node Turning on auto-fill by default
1701 @section How do I turn on @code{auto-fill-mode} by default?
1702 @cindex @code{auto-fill-mode}, activating automatically
1703 @cindex Filling automatically
1704 @cindex Automatic entry to @code{auto-fill-mode}
1706 To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
1709 To turn it on for every buffer in a certain mode, you must use the hook
1710 for that mode. For example, to turn on @code{auto-fill} mode for all
1711 text buffers, including the following in your @file{.emacs} file:
1714 (add-hook 'text-mode-hook 'turn-on-auto-fill)
1717 If you want @code{auto-fill} mode on in all major modes, do this:
1720 (setq-default auto-fill-function 'do-auto-fill)
1723 @node Changing load-path
1724 @section How do I change @code{load-path}?
1725 @cindex @code{load-path}, modifying
1726 @cindex Modifying @code{load-path}
1727 @cindex Adding to @code{load-path}
1729 In general, you should only add to the @code{load-path}. You can add
1730 directory @var{/dir/subdir} to the load path like this:
1733 (add-to-list 'load-path "/dir/subdir/")
1736 To do this relative to your home directory:
1739 (add-to-list 'load-path "~/mysubdir/")
1742 @node Using an already running Emacs process
1743 @section How do I use an already running Emacs from another window?
1744 @cindex @code{emacsclient}
1745 @cindex Emacs server functions
1746 @cindex Using an existing Emacs process
1748 @code{emacsclient}, which comes with Emacs, is for editing a file using
1749 an already running Emacs rather than starting up a new Emacs. It does
1750 this by sending a request to the already running Emacs, which must be
1751 expecting the request.
1758 Emacs must have executed the @code{server-start} function for
1759 @samp{emacsclient} to work. This can be done either by a command line
1763 emacs -f server-start
1766 or by invoking @code{server-start} from @file{.emacs}:
1769 (if (@var{some conditions are met}) (server-start))
1772 When this is done, Emacs creates a Unix domain socket named
1773 @file{server} in @file{/tmp/emacs@var{userid}}. See
1774 @code{server-socket-dir}.
1776 To get your news reader, mail reader, etc., to invoke
1777 @samp{emacsclient}, try setting the environment variable @code{EDITOR}
1778 (or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may
1779 have to specify the full pathname of the @samp{emacsclient} program
1784 setenv EDITOR emacsclient
1786 # using full pathname
1787 setenv EDITOR /usr/local/emacs/etc/emacsclient
1790 EDITOR=emacsclient ; export EDITOR
1796 When @samp{emacsclient} is run, it connects to the socket and passes its
1797 command line options to Emacs, which at the next opportunity will visit
1798 the files specified. (Line numbers can be specified just like with
1799 Emacs.) The user will have to switch to the Emacs window by hand. When
1800 the user is done editing a file, the user can type @kbd{C-x #} (or
1801 @kbd{M-x server-edit}) to indicate this. If there is another buffer
1802 requested by @code{emacsclient}, Emacs will switch to it; otherwise
1803 @code{emacsclient} will exit, signaling the calling program to continue.
1805 @cindex @code{gnuserv}
1806 There is an alternative version of @samp{emacsclient} called
1807 @c ange@@hplb.hpl.hp.com
1808 @samp{gnuserv}, written by Andy Norman
1809 (@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses
1810 Internet domain sockets, so it can work across most network connections.
1812 The most recent @samp{gnuserv} package is available at
1814 @uref{http://meltin.net/hacks/emacs/}
1818 @node Compiler error messages
1819 @section How do I make Emacs recognize my compiler's funny error messages?
1820 @cindex Compiler error messages, recognizing
1821 @cindex Recognizing non-standard compiler errors
1822 @cindex Regexps for recognizing compiler errors
1823 @cindex Errors, recognizing compiler
1825 Customize the @code{compilation-error-regexp-alist} variable.
1827 @node Indenting switch statements
1828 @section How do I change the indentation for @code{switch}?
1829 @cindex @code{switch}, indenting
1830 @cindex Indenting of @code{switch}
1832 Many people want to indent their @code{switch} statements like this:
1850 @noindent To achieve this, add the following line to your @file{.emacs}:
1853 (c-set-offset 'case-label '+)
1856 @node Customizing C and C++ indentation
1857 @section How to customize indentation in C, C@t{++}, and Java buffers?
1858 @cindex Indentation, how to customize
1859 @cindex Customize indentation
1861 The Emacs @code{cc-mode} features an interactive procedure for
1862 customizing the indentation style, which is fully explained in the
1863 @cite{CC Mode} manual that is part of the Emacs distribution, see
1864 @ref{Customizing Indentation, , Customization Indentation, ccmode,
1865 The CC Mode Manual}. Here's a short summary of the procedure:
1869 Go to the beginning of the first line where you don't like the
1870 indentation and type @kbd{C-c C-o}. Emacs will prompt you for the
1871 syntactic symbol; type @key{RET} to accept the default it suggests.
1874 Emacs now prompts for the offset of this syntactic symbol, showing the
1875 default (the current definition) inside parentheses. You can choose
1880 No extra indentation.
1882 Indent one basic offset.
1884 Outdent one basic offset.
1886 Indent two basic offsets
1888 Outdent two basic offsets.
1890 Indent half basic offset.
1892 Outdent half basic offset.
1896 After choosing one of these symbols, type @kbd{C-c C-q} to reindent
1897 the line or the block according to what you just specified.
1900 If you don't like the result, go back to step 1. Otherwise, add the
1901 following line to your @file{.emacs}:
1904 (c-set-offset '@var{syntactic-symbol} @var{offset})
1908 where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
1909 when you type @kbd{C-c C-o} at the beginning of the line, and
1910 @var{offset} is one of the indentation symbols listed above (@code{+},
1911 @code{/}, @code{0}, etc.)@: that you've chosen during the interactive
1915 Go to the next line whose indentation is not to your liking and repeat
1919 It is recommended to put all the resulting @code{(c-set-offset ...)}
1920 customizations inside a C mode hook, like this:
1923 (defun my-c-mode-hook ()
1926 (add-hook 'c-mode-hook 'my-c-mode-hook)
1930 Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
1931 'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
1932 might be unavailable when @code{cc-mode} is not loaded.
1934 Note that @code{c-mode-hook} runs for C source files only; use
1935 @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
1936 Java sources, etc. If you want the same customizations to be in
1937 effect in @emph{all} languages supported by @code{cc-mode}, use
1938 @code{c-mode-common-hook}.
1940 @node Horizontal scrolling
1941 @section How can I make Emacs automatically scroll horizontally?
1942 @cindex @code{hscroll-mode}
1943 @cindex Horizontal scrolling
1944 @cindex Scrolling horizontally
1946 In Emacs 21 and later, this is on by default: if the variable
1947 @code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
1948 automatically scrolls the display horizontally when point moves off the
1949 left or right edge of the window.
1951 Note that this is overridden by the variable
1952 @code{truncate-partial-width-windows} if that variable is non-nil
1953 and the current buffer is not full-frame width.
1955 In Emacs 20, use @code{hscroll-mode}.
1957 @node Overwrite mode
1958 @section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
1959 @cindex @key{Insert}
1960 @cindex @code{overwrite-mode}
1961 @cindex Overwriting existing text
1962 @cindex Toggling @code{overwrite-mode}
1964 @kbd{M-x overwrite-mode} (a minor mode). This toggles
1965 @code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
1966 is as easy as another @kbd{M-x overwrite-mode}.
1968 On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
1970 @node Turning off beeping
1971 @section How do I stop Emacs from beeping on a terminal?
1972 @cindex Beeping, turning off
1973 @cindex Visible bell
1974 @cindex Bell, visible
1976 @c martin@@cc.gatech.edu
1977 Martin R. Frank writes:
1979 Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
1980 and set the visible bell to nothing.
1982 That is, put the following in your @code{TERMCAP} environment variable
1983 (assuming you have one):
1989 And evaluate the following Lisp form:
1992 (setq visible-bell t)
1995 @node Turning the volume down
1996 @section How do I turn down the bell volume in Emacs running under X?
1997 @cindex Bell, volume of
1998 @cindex Volume of bell
2000 On X Window system, you can adjust the bell volume and duration for all
2001 programs with the shell command @code{xset}.
2003 Invoking @code{xset} without any arguments produces some basic
2004 information, including the following:
2007 usage: xset [-display host:dpy] option ...
2010 To set bell volume, pitch and duration:
2011 b [vol [pitch [dur]]] b on
2014 @node Automatic indentation
2015 @section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
2016 @cindex Indenting new lines
2017 @cindex New lines, indenting of
2018 @cindex Previous line, indenting according to
2019 @cindex Text indentation
2021 Such behavior is automatic (in Text mode) in Emacs 20 and later. From the
2022 @file{etc/NEWS} file for Emacs 20.2:
2025 ** In Text mode, now only blank lines separate paragraphs. This makes
2026 it possible to get the full benefit of Adaptive Fill mode in Text mode,
2027 and other modes derived from it (such as Mail mode). @key{TAB} in Text
2028 mode now runs the command @code{indent-relative}; this makes a practical
2029 difference only when you use indented paragraphs.
2031 If you want spaces at the beginning of a line to start a paragraph, use
2032 the new mode, Paragraph Indent Text mode.
2035 @cindex Prefixing lines
2037 If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
2038 by default}), you can tell Emacs to prefix every line with a certain
2039 character sequence, the @dfn{fill prefix}. Type the prefix at the
2040 beginning of a line, position point after it, and then type @kbd{C-x .}
2041 (@code{set-fill-prefix}) to set the fill prefix. Thereafter,
2042 auto-filling will automatically put the fill prefix at the beginning of
2043 new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
2044 prefix when refilling the paragraph.
2046 If you have paragraphs with different levels of indentation, you will
2047 have to set the fill prefix to the correct value each time you move to a
2048 new paragraph. There are many packages available to deal with this
2049 (@pxref{Packages that do not come with Emacs}). Look for ``fill'' and
2050 ``indent'' keywords for guidance.
2052 @node Matching parentheses
2053 @section How do I show which parenthesis matches the one I'm looking at?
2054 @cindex Parentheses, matching
2055 @cindex @file{paren.el}
2056 @cindex Highlighting matching parentheses
2057 @cindex Pairs of parentheses, highlighting
2058 @cindex Matching parentheses
2060 Call @code{show-paren-mode} in your @file{.emacs} file:
2066 You can also enable this mode by selecting the @samp{Paren Match
2067 Highlighting} option from the @samp{Options} menu of the Emacs menu bar
2068 at the top of any Emacs frame.
2070 Alternatives to this mode include:
2075 If you're looking at a right parenthesis (or brace or bracket) you can
2076 delete it and reinsert it. Emacs will momentarily move the cursor to
2077 the matching parenthesis.
2080 @kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
2081 will skip over one set of balanced parentheses, so you can see which
2082 parentheses match. (You can train it to skip over balanced brackets
2083 and braces at the same time by modifying the syntax table.)
2085 @cindex Show matching paren as in @code{vi}
2087 Here is some Emacs Lisp that will make the @key{%} key show the matching
2088 parenthesis, like in @code{vi}. In addition, if the cursor isn't over a
2089 parenthesis, it simply inserts a % like normal.
2092 ;; By an unknown contributor
2094 (global-set-key "%" 'match-paren)
2096 (defun match-paren (arg)
2097 "Go to the matching paren if on a paren; otherwise insert %."
2099 (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
2100 ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
2101 (t (self-insert-command (or arg 1)))))
2106 @node Hiding #ifdef lines
2107 @section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
2108 @cindex @code{#ifdef}, selective display of
2109 @cindex @code{hide-ifdef-mode}
2110 @cindex Hiding @code{#ifdef} text
2111 @cindex Selectively displaying @code{#ifdef} code
2113 @kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want
2114 to investigate @file{cpp.el}, which is distributed with Emacs.
2116 @node Repeating commands
2117 @section How do I repeat a command as many times as possible?
2118 @cindex Repeating commands many times
2119 @cindex Commands, repeating many times
2120 @cindex @code{.}, equivalent to @code{vi} command
2122 As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
2123 that repeats the last command. If you preface it with a prefix
2124 argument, the prefix arg is applied to the command.
2126 You can also type @kbd{C-x @key{ESC} @key{ESC}}
2127 (@code{repeat-complex-command}) to reinvoke commands that used the
2128 minibuffer to get arguments. In @code{repeat-complex-command} you can
2129 type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
2130 keyboard has these keys) to scan through all the different complex
2131 commands you've typed.
2133 To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and
2134 @kbd{C-x )} to make a keyboard macro that invokes the command and then
2135 type @kbd{C-x e}. @xref{Keyboard Macros,,, emacs, The GNU Emacs Manual}.
2137 If you're really desperate for the @code{.} command in @code{vi} that
2138 redoes the last insertion/deletion, use VIPER, a @code{vi} emulation
2139 mode which comes with Emacs, and which appears to support it.
2141 @node Valid X resources
2142 @section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
2143 @cindex Resources, X
2145 @cindex Setting X resources
2147 @xref{X Resources,,, emacs, The GNU Emacs Manual}.
2149 You can also use a resource editor, such as editres (for X11R5 and
2150 onwards), to look at the resource names for the menu bar, assuming Emacs
2151 was compiled with the X toolkit.
2153 @node Evaluating Emacs Lisp code
2154 @section How do I execute (``evaluate'') a piece of Emacs Lisp code?
2155 @cindex Evaluating Lisp code
2156 @cindex Lisp forms, evaluating
2158 There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
2159 Emacs Lisp @dfn{form}:
2164 If you want it evaluated every time you run Emacs, put it in a file
2165 named @file{.emacs} in your home directory. This is known as ``your
2166 @file{.emacs} file,'' and contains all of your personal customizations.
2169 You can type the form in the @file{*scratch*} buffer, and then type
2170 @key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form
2171 will be inserted in the buffer.
2174 In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
2175 before or around point.
2178 Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
2179 before point and prints its value in the echo area.
2182 Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
2183 form in the minibuffer which will be evaluated once you press @key{RET}.
2186 You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
2187 forms in a file. (To do this from Lisp use the function @code{load}
2190 The functions @code{load-library}, @code{eval-region},
2191 @code{eval-buffer}, @code{require}, and @code{autoload} are also
2192 useful; see @ref{Emacs Lisp documentation}, if you want to learn more
2197 @node Changing the length of a Tab
2198 @section How do I change Emacs's idea of the @key{TAB} character's length?
2200 @cindex Length of tab character
2202 Set the default value of the variable @code{tab-width}. For example, to set
2203 @key{TAB} stops every 10 characters, insert the following in your
2207 (setq-default tab-width 10)
2210 Do not confuse variable @code{tab-width} with variable
2211 @code{tab-stop-list}. The former is used for the display of literal
2212 @key{TAB} characters. The latter controls what characters are inserted
2213 when you press the @key{TAB} character in certain modes.
2215 @node Inserting text at the beginning of each line
2216 @section How do I insert <some text> at the beginning of every line?
2217 @cindex Prefixing a region with some text
2218 @cindex Prefix character, inserting in mail/news replies
2219 @cindex Replies to mail/news, inserting a prefix character
2220 @cindex @code{mail-yank-prefix}
2221 @cindex Mail replies, inserting a prefix character
2222 @cindex News replies, inserting a prefix character
2224 To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
2225 @key{RET} ^ @key{RET} your text @key{RET}}.
2227 To do this to a region, use @code{string-insert-rectangle}.
2228 Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
2229 want to prefix, move the cursor to last line to be prefixed, and type
2230 @kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole
2231 buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
2233 If you are trying to prefix a yanked mail message with @samp{>}, you
2234 might want to set the variable @code{mail-yank-prefix}. In Message
2235 buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;}
2236 runs the function @code{comment-region}, it is a general-purpose
2237 mechanism to comment regions) (@pxref{Changing the included text prefix}).
2239 @node Forcing the cursor to remain in the same column
2240 @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?
2241 @cindex @code{picture-mode}
2242 @cindex Remaining in the same column, regardless of contents
2243 @cindex Vertical movement in empty documents
2245 Use @kbd{M-x picture-mode}.
2247 See also the variable @code{track-eol} and the command
2248 @code{set-goal-column} bound to @kbd{C-x C-n}
2249 (@pxref{Moving Point, , , emacs, The GNU Emacs Manual}).
2251 @node Forcing Emacs to iconify itself
2252 @section How do I tell Emacs to iconify itself?
2253 @cindex Iconification under the X Window System
2254 @cindex X Window System and iconification
2255 @cindex Suspending Emacs
2257 @kbd{C-z} iconifies Emacs when running under X and suspends Emacs
2258 otherwise. @xref{Frame Commands,,, emacs, The GNU Emacs Manual}.
2260 @node Using regular expressions
2261 @section How do I use regexps (regular expressions) in Emacs?
2263 @cindex Regular expressions
2264 @cindex Differences between Unix and Emacs regexps
2265 @cindex Unix regexps, differences from Emacs
2266 @cindex Text strings, putting regexps in
2268 @xref{Regexp Backslash,,, emacs, The GNU Emacs Manual}.
2270 The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
2271 are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is
2272 @samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)}
2273 in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
2275 Note the doubled backslashes!
2280 Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
2281 (@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@:
2282 @kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
2283 characters not to match.
2286 The character syntax regexps (e.g., @samp{\sw}) are not
2287 meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This
2288 is actually typical for regexp syntax.)
2292 @node Replacing text across multiple files
2293 @section How do I perform a replace operation across more than one file?
2294 @cindex Replacing strings across files
2295 @cindex Multiple files, replacing across
2296 @cindex Files, replacing strings across multiple
2297 @cindex Recursive search/replace operations
2299 Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x d}) supports the
2300 command @code{dired-do-query-replace-regexp} (@kbd{Q}), which allows
2301 users to replace regular expressions in multiple files.
2303 You can use this command to perform search/replace operations on
2304 multiple files by following the following steps:
2308 Assemble a list of files you want to operate on with either
2309 @code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}.
2312 Mark all files in the resulting Dired buffer using @kbd{t}.
2315 Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked
2319 To accept all replacements in each file, hit @kbd{!}.
2322 Another way to do the same thing is to use the ``tags'' feature of
2323 Emacs: it includes the command @code{tags-query-replace} which performs
2324 a query-replace across all the files mentioned in the @file{TAGS} file.
2325 @xref{Tags Search,,, emacs, The GNU Emacs Manual}.
2327 @node Documentation for etags
2328 @section Where is the documentation for @code{etags}?
2329 @cindex Documentation for @code{etags}
2330 @cindex @code{etags}, documentation for
2332 The @code{etags} man page should be in the same place as the
2333 @code{emacs} man page.
2335 Quick command-line switch descriptions are also available. For example,
2338 @node Disabling backups
2339 @section How do I disable backup files?
2340 @cindex Backups, disabling
2341 @cindex Disabling backups
2343 You probably don't want to do this, since backups are useful, especially
2344 when something goes wrong.
2346 To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
2347 load @code{dired-x} by adding the following to your @file{.emacs} file:
2350 (add-hook 'dired-load-hook
2352 (require 'dired-x)))
2355 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
2356 You can make omitting the default for new dired buffers by putting the
2357 following in your @file{.emacs}:
2360 (add-hook 'dired-mode-hook 'dired-omit-toggle)
2363 If you're tired of seeing backup files whenever you do an @samp{ls} at
2364 the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU
2365 @code{ls} is part of the GNU Fileutils package, available from
2366 @samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
2368 To disable or change the way backups are made,
2369 @pxref{Backup Names,,, emacs, The GNU Emacs Manual}.
2371 @cindex Backup files in a single directory
2372 Beginning with Emacs 21.1, you can control where Emacs puts backup files
2373 by customizing the variable @code{backup-directory-alist}. This
2374 variable's value specifies that files whose names match specific patters
2375 should have their backups put in certain directories. A typical use is
2376 to add the element @code{("." . @var{dir})} to force Emacs to put
2377 @strong{all} backup files in the directory @file{dir}.
2379 @node Disabling auto-save-mode
2380 @section How do I disable @code{auto-save-mode}?
2381 @cindex Disabling @code{auto-save-mode}
2383 @cindex Saving at frequent intervals
2385 You probably don't want to do this, since auto-saving is useful,
2386 especially when Emacs or your computer crashes while you are editing a
2389 Instead, you might want to change the variable
2390 @code{auto-save-interval}, which specifies how many keystrokes Emacs
2391 waits before auto-saving. Increasing this value forces Emacs to wait
2392 longer between auto-saves, which might annoy you less.
2394 You might also want to look into Sebastian Kremer's @code{auto-save}
2395 package (@pxref{Packages that do not come with Emacs}). This
2396 package also allows you to place all auto-save files in one directory,
2397 such as @file{/tmp}.
2399 To disable or change how @code{auto-save-mode} works,
2400 @pxref{Auto Save,,, emacs, The GNU Emacs Manual}.
2402 @node Going to a line by number
2403 @section How can I go to a certain line given its number?
2404 @cindex Going to a line by number
2405 @cindex Compilation error messages
2406 @cindex Recompilation
2408 Are you sure you indeed need to go to a line by its number? Perhaps all
2409 you want is to display a line in your source file for which a compiler
2410 printed an error message? If so, compiling from within Emacs using the
2411 @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
2412 effective way of doing that. Emacs automatically intercepts the compile
2413 error messages, inserts them into a special buffer called
2414 @code{*compilation*}, and lets you visit the locus of each message in
2415 the source. Type @kbd{C-x `} to step through the offending lines one by
2416 one (starting with Emacs 22, you can also use @kbd{M-g M-p} and
2417 @kbd{M-g M-n} to go to the previous and next matches directly). Click
2418 @kbd{Mouse-2} or press @key{RET} on a message text in the
2419 @code{*compilation*} buffer to go to the line whose number is mentioned
2422 But if you indeed need to go to a certain text line, type @kbd{M-g M-g}
2423 (which is the default binding of the @code{goto-line} function starting
2424 with Emacs 22). Emacs will prompt you for the number of the line and go
2427 You can do this faster by invoking @code{goto-line} with a numeric
2428 argument that is the line's number. For example, @kbd{C-u 286 M-g M-g}
2429 will jump to line number 286 in the current buffer.
2431 @node Modifying pull-down menus
2432 @section How can I create or modify new pull-down menu options?
2433 @cindex Pull-down menus, creating or modifying
2434 @cindex Menus, creating or modifying
2435 @cindex Creating new menu options
2436 @cindex Modifying pull-down menus
2437 @cindex Menus and keymaps
2438 @cindex Keymaps and menus
2440 Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
2441 represents a local or global keymap. Selecting a menu title with the
2442 mouse displays that keymap's non-@code{nil} contents in the form of a menu.
2444 So to add a menu option to an existing menu, all you have to do is add a
2445 new definition to the appropriate keymap. Adding a @samp{Forward Word}
2446 item to the @samp{Edit} menu thus requires the following Lisp code:
2449 (define-key global-map
2450 [menu-bar edit forward]
2451 '("Forward word" . forward-word))
2455 The first line adds the entry to the global keymap, which includes
2456 global menu bar entries. Replacing the reference to @code{global-map}
2457 with a local keymap would add this menu option only within a particular
2460 The second line describes the path from the menu-bar to the new entry.
2461 Placing this menu entry underneath the @samp{File} menu would mean
2462 changing the word @code{edit} in the second line to @code{file}.
2464 The third line is a cons cell whose first element is the title that will
2465 be displayed, and whose second element is the function that will be
2466 called when that menu option is invoked.
2468 To add a new menu, rather than a new option to an existing menu, we must
2469 define an entirely new keymap:
2472 (define-key global-map [menu-bar words]
2473 (cons "Words" (make-sparse-keymap "Words")))
2476 The above code creates a new sparse keymap, gives it the name
2477 @samp{Words}, and attaches it to the global menu bar. Adding the
2478 @samp{Forward Word} item to this new menu would thus require the
2482 (define-key global-map
2483 [menu-bar words forward]
2484 '("Forward word" . forward-word))
2488 Note that because of the way keymaps work, menu options are displayed
2489 with the more recently defined items at the top. Thus if you were to
2490 define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
2491 order), the menu option @samp{baz} would appear at the top, and
2492 @samp{foo} would be at the bottom.
2494 One way to avoid this problem is to use the function @code{define-key-after},
2495 which works the same as @code{define-key}, but lets you modify where items
2496 appear. The following Lisp code would insert the @samp{Forward Word}
2497 item in the @samp{Edit} menu immediately following the @samp{Undo} item:
2501 (lookup-key global-map [menu-bar edit])
2503 '("Forward word" . forward-word)
2507 Note how the second and third arguments to @code{define-key-after} are
2508 different from those of @code{define-key}, and that we have added a new
2509 (final) argument, the function after which our new key should be
2512 To move a menu option from one position to another, simply evaluate
2513 @code{define-key-after} with the appropriate final argument.
2515 More detailed information---and more examples of how to create and
2516 modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
2517 ``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on
2520 @node Deleting menus and menu options
2521 @section How do I delete menus and menu options?
2522 @cindex Deleting menus and menu options
2523 @cindex Menus, deleting
2525 The simplest way to remove a menu is to set its keymap to @samp{nil}.
2526 For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
2530 (define-key global-map [menu-bar words] nil)
2533 Similarly, removing a menu option requires redefining a keymap entry to
2534 @code{nil}. For example, to delete the @samp{Forward word} menu option
2535 from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
2539 (define-key global-map [menu-bar edit forward] nil)
2542 @node Turning on syntax highlighting
2543 @section How do I turn on syntax highlighting?
2544 @cindex Syntax highlighting
2545 @cindex @code{font-lock-mode}
2546 @cindex Highlighting based on syntax
2547 @cindex Colorizing text
2548 @cindex FAQ, @code{font-lock-mode}
2550 @code{font-lock-mode} is the standard way to have Emacs perform syntax
2551 highlighting in the current buffer. It is enabled by default in Emacs
2554 With @code{font-lock-mode} turned on, different types of text will
2555 appear in different colors. For instance, in a programming mode,
2556 variables will appear in one face, keywords in a second, and comments in
2559 To turn @code{font-lock-mode} off within an existing buffer, use
2560 @kbd{M-x font-lock-mode @key{RET}}.
2562 In Emacs 21 and earlier versions, you could use the following code in
2563 your @file{.emacs} file to turn on @code{font-lock-mode} globally:
2566 (global-font-lock-mode 1)
2569 Highlighting a buffer with @code{font-lock-mode} can take quite a while,
2570 and cause an annoying delay in display, so several features exist to
2573 @cindex Just-In-Time syntax highlighting
2574 In Emacs 21 and later, turning on @code{font-lock-mode} automatically
2575 activates the new @dfn{Just-In-Time fontification} provided by
2576 @code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
2577 portions of buffer until you actually need to see them, and can also
2578 fontify while Emacs is idle. This makes display of the visible portion
2579 of a buffer almost instantaneous. For details about customizing
2580 @code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
2582 @cindex Levels of syntax highlighting
2583 @cindex Decoration level, in @code{font-lock-mode}
2584 In versions of Emacs before 21, different levels of decoration are
2585 available, from slight to gaudy. More decoration means you need to wait
2586 more time for a buffer to be fontified (or a faster machine). To
2587 control how decorated your buffers should become, set the value of
2588 @code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
2589 @code{nil} value indicating default (usually minimum) decoration, and a
2590 @code{t} value indicating the maximum decoration. For the gaudiest
2591 possible look, then, include the line
2594 (setq font-lock-maximum-decoration t)
2598 in your @file{.emacs} file. You can also set this variable such that
2599 different modes are highlighted in a different ways; for more
2600 information, see the documentation for
2601 @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
2602 describe-variable @key{RET}}).
2604 Also see the documentation for the function @code{font-lock-mode},
2605 available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
2606 describe-function @key{RET} font-lock-mode @key{RET}}).
2608 To print buffers with the faces (i.e., colors and fonts) intact, use
2609 @kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
2610 ps-print-region-with-faces}. You will need a way to send text to a
2611 PostScript printer, or a PostScript interpreter such as Ghostscript;
2612 consult the documentation of the variables @code{ps-printer-name},
2613 @code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
2615 @node Scrolling only one line
2616 @section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
2617 @cindex Scrolling only one line
2618 @cindex Reducing the increment when scrolling
2620 Customize the @code{scroll-conservatively} variable with @kbd{M-x
2621 customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
2622 to a large value like, say, 10000. For an explanation of what this
2623 means, @pxref{Auto Scrolling,,, emacs, The GNU Emacs Manual}.
2625 Alternatively, use the following Lisp form in your @file{.emacs}:
2628 (setq scroll-conservatively most-positive-fixnum)
2631 @node Editing MS-DOS files
2632 @section How can I edit MS-DOS files using Emacs?
2633 @cindex Editing MS-DOS files
2634 @cindex MS-DOS files, editing
2635 @cindex Microsoft files, editing
2636 @cindex Windows files, editing
2638 As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
2639 performed transparently. You can open MS-DOS files on a Unix system,
2640 edit it, and save it without having to worry about the file format.
2642 When editing an MS-DOS style file, the mode line will indicate that it
2643 is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh,
2644 the string @samp{(DOS)} will appear near the left edge of the mode line;
2645 on DOS and Windows, where the DOS end-of-line (EOL) format is the
2646 default, a backslash (@samp{\}) will appear in the mode line.
2648 @node Filling paragraphs with a single space
2649 @section How can I tell Emacs to fill paragraphs with a single space after each period?
2650 @cindex One space following periods
2651 @cindex Single space following periods
2652 @cindex Periods, one space following
2654 Add the following line to your @file{.emacs} file:
2657 (setq sentence-end-double-space nil)
2660 @node Escape sequences in shell output
2661 @section Why these strange escape sequences from @code{ls} from the Shell mode?
2662 @cindex Escape sequences in @code{ls} output
2663 @cindex @code{ls} in Shell mode
2665 In many systems, @code{ls} is aliased to @samp{ls --color}, which
2666 prints using ANSI color escape sequences. Emacs version 21.1 and
2667 later includes the @code{ansi-color} package, which lets Shell mode
2668 recognize these escape sequences. In Emacs 23.2 and later, the
2669 package is enabled by default; in earlier versions you can enable it
2670 by typing @kbd{M-x ansi-color-for-comint-mode} in the Shell buffer, or
2671 by adding @code{(add-hook 'shell-mode-hook
2672 'ansi-color-for-comint-mode-on)} to your init file.
2674 In Emacs versions before 21.1, the @code{ansi-color} package is not
2675 included. In that case, you need to unalias @code{ls} for interactive
2676 shells running in Emacs; this can be done by checking the @code{EMACS}
2677 variable in the environment.
2679 @node Fullscreen mode on MS-Windows
2680 @section How can I start Emacs in fullscreen mode on MS-Windows?
2681 @cindex Maximize frame
2682 @cindex Fullscreen mode
2684 Use the function @code{w32-send-sys-command}. For example, you can
2685 put the following in your @file{.emacs} file:
2688 (add-hook 'term-setup-hook
2689 #'(lambda () (w32-send-sys-command ?\xF030)))
2692 To avoid the slightly distracting visual effect of Emacs starting with
2693 its default frame size and then growing to fullscreen, you can add an
2694 @samp{Emacs.Geometry} entry to the Windows registry settings.
2695 @xref{X Resources,,, emacs, The GNU Emacs Manual}.
2697 To compute the correct values for width and height, first maximize the
2698 Emacs frame and then evaluate @code{(frame-height)} and
2699 @code{(frame-width)} with @kbd{M-:}.
2701 @c ------------------------------------------------------------
2702 @node Bugs and problems
2703 @chapter Bugs and problems
2704 @cindex Bugs and problems
2706 The Emacs manual lists some common kinds of trouble users could get
2707 into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
2708 Emacs Manual}, so you might look there if the problem you encounter
2709 isn't described in this chapter. If you decide you've discovered a bug,
2710 see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
2711 instructions how to do that.
2713 The file @file{etc/PROBLEMS} in the Emacs distribution lists various
2714 known problems with building and using Emacs on specific platforms;
2715 type @kbd{C-h C-p} to read it.
2718 * Problems with very large files::
2719 * ^M in the shell buffer::
2720 * Problems with Shell Mode::
2721 * Termcap/Terminfo entries for Emacs::
2722 * Errors with init files::
2723 * Emacs ignores X resources::
2724 * Emacs ignores frame parameters::
2725 * Editing files with $ in the name::
2726 * Shell mode loses the current directory::
2727 * Security risks with Emacs::
2728 * Dired claims that no file is on this line::
2731 @node Problems with very large files
2732 @section Does Emacs have problems with files larger than 8 megabytes?
2733 @cindex Very large files, opening
2734 @cindex Large files, opening
2735 @cindex Opening very large files
2736 @cindex Maximum file size
2737 @cindex Files, maximum size
2739 Old versions (i.e., anything before 19.29) of Emacs had problems editing
2740 files larger than 8 megabytes. In versions 19.29 and later, the maximum
2741 buffer size is at least @math{2^{27}-1}, or 134,217,727 bytes, or 132 MBytes.
2742 The maximum buffer size on 32-bit machines increased to 256 MBytes in
2743 Emacs 22, and again to 512 MBytes in Emacs 23.2.
2745 Emacs compiled on a 64-bit machine can handle much larger buffers.
2747 @node ^M in the shell buffer
2748 @section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
2749 @cindex Shell buffer, echoed commands and @samp{^M} in
2750 @cindex Echoed commands in @code{shell-mode}
2752 Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
2753 make them go away. If that doesn't work, you have several options:
2755 For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
2760 if ("$EMACS" =~ /*) then
2761 if ($?tcsh) unset edit
2767 Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file:
2774 Alternatively, use @code{csh} in your shell buffers instead of
2775 @code{tcsh}. One way is:
2778 (setq explicit-shell-file-name "/bin/csh")
2782 and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
2786 setenv ESHELL /bin/csh
2790 (You must start Emacs over again with the environment variable properly
2791 set for this to take effect.)
2793 You can also set the @code{ESHELL} environment variable in Emacs Lisp
2794 with the following Lisp form,
2797 (setenv "ESHELL" "/bin/csh")
2800 The above solutions try to prevent the shell from producing the
2801 @samp{^M} characters in the first place. If this is not possible
2802 (e.g., if you use a Windows shell), you can get Emacs to remove these
2803 characters from the buffer by adding this to your @file{.emacs} init
2807 (add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
2810 On a related note: if your shell is echoing your input line in the shell
2811 buffer, you might want to customize the @code{comint-process-echoes}
2812 variable in your shell buffers, or try the following command in your
2813 shell start-up file:
2816 stty -icrnl -onlcr -echo susp ^Z
2819 @node Problems with Shell Mode
2820 @section Why do I get an error message when I try to run @kbd{M-x shell}?
2822 @cindex Shell Mode, problems
2823 @cindex @code{explicit-shell-file-name}
2824 This might happen because Emacs tries to look for the shell in a wrong
2825 place. If you know where your shell executable is, set the variable
2826 @code{explicit-shell-file-name} in your @file{.emacs} file to point to
2829 @cindex Antivirus programs, and Shell Mode
2830 Some people have trouble with Shell Mode on MS-Windows because of
2831 intrusive antivirus software; disabling the resident antivirus program
2832 solves the problems in those cases.
2834 @node Termcap/Terminfo entries for Emacs
2835 @section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
2838 @cindex Emacs entries for termcap/terminfo
2840 The termcap entry for terminal type @samp{emacs} is ordinarily put in
2841 the @samp{TERMCAP} environment variable of subshells. It may help in
2842 certain situations (e.g., using rlogin from shell buffer) to add an
2843 entry for @samp{emacs} to the system-wide termcap file. Here is a
2844 correct termcap entry for @samp{emacs}:
2850 To make a terminfo entry for @samp{emacs}, use @code{tic} or
2851 @code{captoinfo}. You need to generate
2852 @file{/usr/lib/terminfo/e/emacs}. It may work to simply copy
2853 @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
2855 Having a termcap/terminfo entry will not enable the use of full screen
2856 programs in shell buffers. Use @kbd{M-x terminal-emulator} for that
2859 A workaround to the problem of missing termcap/terminfo entries is to
2860 change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
2861 in your shell start up file. @code{csh} users could put this in their
2862 @file{.cshrc} files:
2865 if ("$term" == emacs) set term=dumb
2868 @node Errors with init files
2869 @section Why does Emacs say @samp{Error in init file}?
2870 @cindex Error in @file{.emacs}
2871 @cindex Error in init file
2872 @cindex Init file, errors in
2873 @cindex @file{.emacs} file, errors in
2874 @cindex Debugging @file{.emacs} file
2876 An error occurred while loading either your @file{.emacs} file or the
2877 system-wide file @file{site-lisp/default.el}. Emacs 21.1 and later pops the
2878 @file{*Messages*} buffer, and puts there some additional information
2879 about the error, to provide some hints for debugging.
2881 For information on how to debug your @file{.emacs} file, see
2882 @ref{Debugging a customization file}.
2884 It may be the case that you need to load some package first, or use a
2885 hook that will be evaluated after the package is loaded. A common case
2886 of this is explained in @ref{Terminal setup code works after Emacs has
2889 @node Emacs ignores X resources
2890 @section Why does Emacs ignore my X resources (my .Xdefaults file)?
2891 @cindex X resources being ignored
2892 @cindex Ignored X resources
2893 @cindex @file{.Xdefaults}
2895 As of version 19, Emacs searches for X resources in the files specified
2896 by the following environment variables:
2900 @item @code{XFILESEARCHPATH}
2901 @item @code{XUSERFILESEARCHPATH}
2902 @item @code{XAPPLRESDIR}
2906 This emulates the functionality provided by programs written using the
2909 @code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
2910 of file names separated by colons. @code{XAPPLRESDIR} should be a list
2911 of directory names separated by colons.
2913 Emacs searches for X resources:
2918 specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
2921 then in the value of the @samp{XENVIRONMENT} environment variable,
2926 or if that is unset, in the file named
2927 @file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
2928 the name of the machine Emacs is running on),
2933 then in the screen-specific and server-wide resource properties provided
2939 or if those properties are unset, in the file named @file{~/.Xdefaults}
2945 then in the files listed in @samp{XUSERFILESEARCHPATH},
2950 or in files named @file{@var{lang}/Emacs} in directories listed in
2951 @samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
2952 environment variable), if the @samp{LANG} environment variable is set,
2954 or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
2956 or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
2959 or in @file{~/Emacs},
2964 then in the files listed in @code{XFILESEARCHPATH}.
2968 @node Emacs ignores frame parameters
2969 @section Why don't my customizations of the frame parameters work?
2970 @cindex Frame parameters
2972 This probably happens because you have set the frame parameters in the
2973 variable @code{initial-frame-alist}. That variable holds parameters
2974 used only for the first frame created when Emacs starts. To customize
2975 the parameters of all frames, change the variable
2976 @code{default-frame-alist} instead.
2978 These two variables exist because many users customize the initial frame
2979 in a special way. For example, you could determine the position and
2980 size of the initial frame, but would like to control the geometry of the
2981 other frames by individually positioning each one of them.
2984 @node Editing files with $ in the name
2985 @section How do I edit a file with a @samp{$} in its name?
2986 @cindex Editing files with @samp{$} in the name
2987 @cindex @samp{$} in file names
2988 @cindex File names containing @samp{$}, editing
2990 When entering a file name in the minibuffer, Emacs will attempt to expand
2991 a @samp{$} followed by a word as an environment variable. To suppress
2992 this behavior, type @kbd{$$} instead.
2994 @node Shell mode loses the current directory
2995 @section Why does shell mode lose track of the shell's current directory?
2996 @cindex Current directory and @code{shell-mode}
2997 @cindex @code{shell-mode} and current directory
2998 @cindex Directory, current in @code{shell-mode}
3000 Emacs has no way of knowing when the shell actually changes its
3001 directory. This is an intrinsic limitation of Unix. So it tries to
3002 guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed
3003 by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
3004 with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
3005 correctly guess the shell's new current directory. A huge variety of
3006 fixes and enhancements to shell mode for this problem have been written
3007 to handle this problem (@pxref{Finding a package with particular
3010 You can tell Emacs the shell's current directory with the command
3013 @node Security risks with Emacs
3014 @section Are there any security risks in Emacs?
3015 @cindex Security with Emacs
3016 @cindex @samp{movemail} and security
3017 @cindex @code{file-local-variable} and security
3018 @cindex Synthetic X events and security
3019 @cindex X events and security
3024 The @file{movemail} incident. (No, this is not a risk.)
3026 In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
3027 chapter 4. The site at LBL had installed the @file{/etc/movemail}
3028 program setuid root. (As of version 19, @file{movemail} is in your
3029 architecture-specific directory; type @kbd{C-h v exec-directory
3030 @key{RET}} to see what it is.) Since @code{movemail} had not been
3031 designed for this situation, a security hole was created and users could
3032 get root privileges.
3034 @code{movemail} has since been changed so that this security hole will
3035 not exist, even if it is installed setuid root. However,
3036 @code{movemail} no longer needs to be installed setuid root, which
3037 should eliminate this particular risk.
3039 We have heard unverified reports that the 1988 Internet worm took
3040 advantage of this configuration problem.
3043 The @code{file-local-variable} feature. (Yes, a risk, but easy to
3046 There is an Emacs feature that allows the setting of local values for
3047 variables when editing a file by including specially formatted text near
3048 the end of the file. This feature also includes the ability to have
3049 arbitrary Emacs Lisp code evaluated when the file is visited.
3050 Obviously, there is a potential for Trojan horses to exploit this
3053 As of Emacs 22, Emacs has a list of local variables that are known to
3054 be safe to set. If a file tries to set any variable outside this
3055 list, it asks the user to confirm whether the variables should be set.
3056 You can also tell Emacs whether to allow the evaluation of Emacs Lisp
3057 code found at the bottom of files by setting the variable
3058 @code{enable-local-eval}.
3060 @xref{File Variables,,, emacs, The GNU Emacs Manual}.
3063 Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
3066 Emacs accepts synthetic X events generated by the @code{SendEvent}
3067 request as though they were regular events. As a result, if you are
3068 using the trivial host-based authentication, other users who can open X
3069 connections to your X workstation can make your Emacs process do
3070 anything, including run other processes with your privileges.
3072 The only fix for this is to prevent other users from being able to open
3073 X connections. The standard way to prevent this is to use a real
3074 authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using
3075 the @code{xauth} program has any effect, then you are probably using
3076 @samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior
3077 authentication method; ask your system administrator.
3079 If real authentication is not a possibility, you may be satisfied by
3080 just allowing hosts access for brief intervals while you start your X
3081 programs, then removing the access. This reduces the risk somewhat by
3082 narrowing the time window when hostile users would have access, but
3083 @emph{does not eliminate the risk}.
3085 On most computers running Unix and X, you enable and disable
3086 access using the @code{xhost} command. To allow all hosts access to
3094 at the shell prompt, which (on an HP machine, at least) produces the
3098 access control disabled, clients can connect from any host
3101 To deny all hosts access to your X server (except those explicitly
3102 allowed by name), use
3108 On the test HP computer, this command generated the following message:
3111 access control enabled, only authorized clients can connect
3116 @node Dired claims that no file is on this line
3117 @section Dired says, @samp{no file on this line} when I try to do something.
3118 @cindex Dired does not see a file
3120 Dired uses a regular expression to find the beginning of a file name.
3121 In a long Unix-style directory listing (@samp{ls -l}), the file name
3122 starts after the date. The regexp has thus been written to look for the
3123 date. By default, it should understand dates and times regardless of
3124 the language, but if your directory listing has an unusual format, Dired
3127 There are two approaches to solving this. The first one involves
3128 setting things up so that @samp{ls -l} outputs a more standard format.
3129 See your OS manual for more information.
3131 The second approach involves changing the regular expression used by
3132 dired, @code{directory-listing-before-filename-regexp}.
3134 @c ------------------------------------------------------------
3135 @node Compiling and installing Emacs
3136 @chapter Compiling and installing Emacs
3137 @cindex Compiling and installing Emacs
3140 * Installing Emacs::
3141 * Problems building Emacs::
3144 @node Installing Emacs
3145 @section How do I install Emacs?
3146 @cindex Installing Emacs
3147 @cindex Unix systems, installing Emacs on
3148 @cindex Downloading and installing Emacs
3149 @cindex Building Emacs from source
3150 @cindex Source code, building Emacs from
3152 This answer is meant for users of Unix and Unix-like systems. Users of
3153 other operating systems should see the series of questions beginning
3154 with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
3155 and binaries, and how to install Emacs on those systems.
3157 Most GNU/Linux distributions provide pre-built Emacs packages.
3158 If Emacs is not installed already, you can install it by running (as
3159 root) a command such as @samp{yum install emacs} (Red Hat and
3160 derivatives) or @samp{apt-get install emacs} (Debian and derivatives).
3162 If you want to compile Emacs yourself, read the file @file{INSTALL} in
3163 the source distribution. In brief:
3168 First download the Emacs sources. @xref{Current GNU distributions}, for
3169 a list of ftp sites that make them available. On @file{ftp.gnu.org},
3170 the main GNU distribution site, sources are available as
3172 @c Don't include VER in the file name, because pretests are not there.
3173 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-VERSION.tar.gz}
3175 (Replace @samp{VERSION} with the relevant version number, e.g., @samp{23.1}.)
3178 Next uncompress and extract the source files. This requires
3179 the @code{gzip} and @code{tar} programs, which are standard utilities.
3180 If your system does not have them, these can also be downloaded from
3183 GNU @code{tar} can uncompress and extract in a single-step:
3186 tar -zxvf emacs-VERSION.tar.gz
3190 At this point, the Emacs sources should be sitting in a directory called
3191 @file{emacs-VERSION}. On most common Unix and Unix-like systems,
3192 you should be able to compile Emacs with the following commands:
3196 ./configure # configure Emacs for your particular system
3197 make # use Makefile to build components, then Emacs
3200 If the @code{make} completes successfully, the odds are fairly good that
3201 the build has gone well. (@xref{Problems building Emacs}, if you weren't
3205 By default, Emacs is installed in @file{/usr/local}. To actually
3206 install files, become the superuser and type
3212 Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
3213 and any Emacs Info files that might be in @file{/usr/local/share/info/}.
3217 @node Problems building Emacs
3218 @section What should I do if I have trouble building Emacs?
3219 @cindex Problems building Emacs
3220 @cindex Errors when building Emacs
3222 First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
3223 source) to see if there is already a solution for your problem. Next,
3224 look for other questions in this FAQ that have to do with Emacs
3225 installation and compilation problems.
3227 If you'd like to have someone look at your problem and help solve it,
3228 see @ref{Help installing Emacs}.
3230 If you cannot find a solution in the documentation, please report the
3231 problem (@pxref{Reporting bugs}).
3234 @c ------------------------------------------------------------
3235 @node Finding Emacs and related packages
3236 @chapter Finding Emacs and related packages
3237 @cindex Finding Emacs and related packages
3240 * Finding Emacs on the Internet::
3241 * Finding a package with particular functionality::
3242 * Packages that do not come with Emacs::
3244 * Current GNU distributions::
3245 * Difference between Emacs and XEmacs::
3246 * Emacs for minimalists::
3247 * Emacs for MS-DOS::
3248 * Emacs for MS-Windows::
3249 * Emacs for GNUstep::
3250 * Emacs for Mac OS X::
3253 @node Finding Emacs on the Internet
3254 @section Where can I get Emacs on the net?
3255 @cindex Finding Emacs on the Internet
3256 @cindex Downloading Emacs
3258 Information on downloading Emacs is available at
3259 @uref{http://www.gnu.org/software/emacs/, the Emacs home-page}.
3261 @xref{Installing Emacs}, for information on how to obtain and build the latest
3262 version of Emacs, and see @ref{Current GNU distributions}, for a list of
3263 archive sites that make GNU software available.
3265 @node Finding a package with particular functionality
3266 @section How do I find a Emacs Lisp package that does XXX?
3267 @cindex Package, finding
3268 @cindex Finding an Emacs Lisp package
3269 @cindex Functionality, finding a particular package
3271 First of all, you should check to make sure that the package isn't
3272 already available. For example, typing @kbd{M-x apropos @key{RET}
3273 wordstar @key{RET}} lists all functions and variables containing the
3274 string @samp{wordstar}.
3276 It is also possible that the package is on your system, but has not been
3277 loaded. To see which packages are available for loading, look through
3278 your computer's lisp directory (@pxref{File-name conventions}). The Lisp
3279 source to most packages contains a short description of how they
3280 should be loaded, invoked, and configured---so before you use or
3281 modify a Lisp package, see if the author has provided any hints in the
3284 The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
3285 the constituent Emacs packages.
3287 For advice on how to find extra packages that are not part of Emacs,
3288 see @ref{Packages that do not come with Emacs}.
3290 @c Note that M-x view-external-packages references this node.
3291 @node Packages that do not come with Emacs
3292 @section Where can I get Emacs Lisp packages that don't come with Emacs?
3293 @cindex Unbundled packages
3294 @cindex Finding other packages
3295 @cindex Lisp packages that do not come with Emacs
3296 @cindex Packages, those that do not come with Emacs
3297 @cindex Emacs Lisp List
3298 @cindex Emacs Lisp Archive
3300 The easiest way to add more features to your Emacs is to use the
3301 command @kbd{M-x list-packages}. This contacts the
3302 @uref{http:///elpa.gnu.org, GNU ELPA} (``Emacs Lisp Package Archive'')
3303 server and fetches the list of additional packages that it offers.
3304 These are GNU packages that are available for use with Emacs, but are
3305 distributed separately from Emacs itself, for reasons of space, etc.
3306 You can browse the resulting @file{*Packages*} buffer to see what is
3307 available, and then Emacs can automatically download and install the
3308 packages that you select. @xref{Packages,,, emacs, The GNU Emacs Manual}.
3310 There are other, non-GNU, Emacs Lisp package servers, including:
3311 @uref{http://melpa.milkbox.net, MELPA}; and
3312 @uref{http://marmalade-repo.org, Marmalade}. To use additional
3313 package servers, customize the @code{package-archives} variable.
3314 Be aware that installing a package can run arbitrary code, so only add
3315 sources that you trust.
3317 The @uref{https://lists.gnu.org/mailman/listinfo/gnu-emacs-sources,
3318 GNU Emacs sources mailing list}, which is gatewayed to the
3319 @uref{news:gnu.emacs.sources, Emacs sources newsgroup} (although the
3320 connection between the two can be unreliable) is an official place
3321 where people can post or announce their extensions to Emacs.
3323 The @uref{http://emacswiki.org, Emacs Wiki} contains pointers to some
3324 additional extensions. @uref{http://wikemacs.org, WikEmacs} is an
3325 alternative wiki for Emacs.
3327 @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs
3328 Lisp List (ELL)}, has pointers to many Emacs Lisp files, but at time
3329 of writing it is no longer being updated.
3331 It is impossible for us to list here all the sites that offer Emacs
3332 Lisp packages. If you are interested in a specific feature, then
3333 after checking Emacs itself and GNU ELPA, a web search is often the
3334 best way to find results.
3336 @node Spell-checkers
3337 @section Spell-checkers
3338 @cindex Spell-checker
3339 @cindex Checking spelling
3344 Various spell-checkers are compatible with Emacs, including:
3349 @uref{http://aspell.net/}
3352 @uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
3355 @uref{http://hunspell.sourceforge.net/}
3359 @node Current GNU distributions
3360 @section Where can I get other up-to-date GNU stuff?
3361 @cindex Current GNU distributions
3362 @cindex Sources for current GNU distributions
3363 @cindex Stuff, current GNU
3364 @cindex Up-to-date GNU stuff
3365 @cindex Finding current GNU software
3366 @cindex Official GNU software sites
3368 The most up-to-date official GNU software is normally kept at
3370 @uref{ftp://ftp.gnu.org/pub/gnu}
3372 A list of sites mirroring @samp{ftp.gnu.org} can be found at
3374 @uref{http://www.gnu.org/order/ftp.html}
3376 @node Difference between Emacs and XEmacs
3377 @section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
3379 @cindex Difference Emacs and XEmacs
3383 XEmacs is a branch version of Emacs. It was first called Lucid Emacs,
3384 and was initially derived from a prerelease version of Emacs 19. In
3385 this FAQ, we use the name ``Emacs'' only for the official version.
3387 Emacs and XEmacs each come with Lisp packages that are lacking in the
3388 other. The two versions have some significant differences at the Lisp
3389 programming level. Their current features are roughly comparable,
3390 though the support for some operating systems, character sets and
3391 specific packages might be quite different.
3393 Some XEmacs code has been contributed to Emacs, and we would like to
3394 use other parts, but the earlier XEmacs maintainers did not always
3395 keep track of the authors of contributed code, which makes it
3396 impossible for the FSF to get copyright papers signed for that code.
3397 (The FSF requires these papers for all the code included in the Emacs
3398 release, aside from generic C support packages that retain their
3399 separate identity and are not integrated into the code of Emacs
3402 If you want to talk about these two versions and distinguish them,
3403 please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs''
3404 with ``GNU Emacs'' would be misleading, since XEmacs too has its
3405 origin in the work of the GNU Project. Terms such as ``Emacsen'' and
3406 ``(X)Emacs'' are not wrong, but they are not very clear, so it
3407 is better to write ``Emacs and XEmacs.''
3409 @node Emacs for minimalists
3410 @section I don't have enough disk space to install Emacs
3412 @cindex Not enough disk space to install Emacs
3414 GNU Zile is a lightweight Emacs clone. Zile is short for @samp{Zile Is
3415 Lossy Emacs}. It has all of Emacs's basic editing features. The Zile
3416 binary typically has a size of about 130 kbytes, so this can be useful
3417 if you are in an extremely space-restricted environment. More
3418 information is available from
3420 @uref{http://www.gnu.org/software/zile/}
3423 @node Emacs for MS-DOS
3424 @section Where can I get Emacs for MS-DOS?
3425 @cindex MS-DOS, Emacs for
3426 @cindex DOS, Emacs for
3427 @cindex Compiling Emacs for DOS
3428 @cindex Emacs for MS-DOS
3430 To build Emacs from source for MS-DOS, see the instructions in the file
3431 @file{msdos/INSTALL} in the distribution. The DOS port builds and runs
3432 on plain DOS, and also on all versions of MS-Windows from version 3.X
3433 onwards, including Windows XP and Vista.
3435 The file @file{etc/PROBLEMS} contains some additional information
3436 regarding Emacs under MS-DOS.
3438 A pre-built binary distribution of the old Emacs 20 is available, as
3441 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README}
3443 For a list of other MS-DOS implementations of Emacs (and Emacs
3444 look-alikes), consult the list of ``Emacs implementations and literature,''
3447 @uref{http://www.finseth.com/emacs.html}
3449 Note that while many of these programs look similar to Emacs, they often
3450 lack certain features, such as the Emacs Lisp extension language.
3452 @node Emacs for MS-Windows
3453 @section Where can I get Emacs for Microsoft Windows?
3454 @cindex FAQ for Emacs on MS-Windows
3455 @cindex Emacs for MS-Windows
3456 @cindex Microsoft Windows, Emacs for
3458 There is a separate FAQ for Emacs on MS-Windows,
3459 @pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}.
3460 For MS-DOS, @pxref{Emacs for MS-DOS}.
3463 @node Emacs for GNUstep
3464 @section Where can I get Emacs for GNUstep?
3465 @cindex GNUstep, Emacs for
3467 Beginning with version 23.1, Emacs supports GNUstep natively.
3468 See the file @file{nextstep/INSTALL} in the distribution.
3470 @node Emacs for Mac OS X
3471 @section Where can I get Emacs for Mac OS X?
3472 @cindex Apple computers, Emacs for
3473 @cindex Macintosh, Emacs for
3474 @cindex Mac OS X, Emacs for
3476 Beginning with version 22.1, Emacs supports Mac OS X natively.
3477 See the file @file{nextstep/INSTALL} in the distribution.
3479 @c ------------------------------------------------------------
3481 @chapter Key bindings
3482 @cindex Key bindings
3485 * Binding keys to commands::
3486 * Invalid prefix characters::
3487 * Terminal setup code works after Emacs has begun::
3488 * Working with function and arrow keys::
3489 * X key translations for Emacs::
3490 * Backspace invokes help::
3492 * Producing C-XXX with the keyboard::
3495 * Compose Character::
3496 * Binding combinations of modifiers and function keys::
3497 * Meta key does not work in xterm::
3498 * ExtendChar key does not work as Meta::
3499 * SPC no longer completes file names::
3502 @node Binding keys to commands
3503 @section How do I bind keys (including function keys) to commands?
3504 @cindex Binding keys to commands
3505 @cindex Keys, binding to commands
3506 @cindex Commands, binding keys to
3508 Keys can be bound to commands either interactively or in your
3509 @file{.emacs} file. To interactively bind keys for all modes, type
3510 @kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3512 To bind a key just in the current major mode, type @kbd{M-x
3513 local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3515 @xref{Key Bindings,,, emacs, The GNU Emacs Manual}.
3517 To make the process of binding keys interactively easier, use the
3518 following ``trick'': First bind the key interactively, then immediately
3519 type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
3520 to bind the key is in the kill ring, and can be yanked into your
3521 @file{.emacs} file. If the key binding is global, no changes to the
3522 command are required. For example,
3525 (global-set-key (quote [f1]) (quote help-for-help))
3529 can be placed directly into the @file{.emacs} file. If the key binding is
3530 local, the command is used in conjunction with the @samp{add-hook} function.
3531 For example, in TeX mode, a local binding might be
3534 (add-hook 'tex-mode-hook
3536 (local-set-key (quote [f1]) (quote help-for-help))))
3543 Control characters in key sequences, in the form yanked from the kill
3544 ring are given in their graphic form---i.e., @key{CTRL} is shown as
3545 @samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want
3546 to convert these into their vector or string forms.
3549 If a prefix key of the character sequence to be bound is already
3550 bound as a complete key, then you must unbind it before the new
3551 binding. For example, if @kbd{ESC @{} is previously bound:
3554 (global-unset-key [?\e ?@{]) ;; or
3555 (local-unset-key [?\e ?@{])
3559 Aside from commands and ``lambda lists,'' a vector or string also
3560 can be bound to a key and thus treated as a macro. For example:
3563 (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or
3564 (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
3569 @node Invalid prefix characters
3570 @section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
3571 @cindex Prefix characters, invalid
3572 @cindex Invalid prefix characters
3573 @cindex Misspecified key sequences
3575 Usually, one of two things has happened. In one case, the control
3576 character in the key sequence has been misspecified (e.g., @samp{C-f}
3577 used instead of @samp{\C-f} within a Lisp expression). In the other
3578 case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
3579 was already bound as a @dfn{complete key}. Historically, the @samp{ESC [}
3580 prefix was usually the problem, in which case you should evaluate either
3581 of these forms before attempting to bind the key sequence:
3584 (global-unset-key [?\e ?[]) ;; or
3585 (global-unset-key "\e[")
3588 @node Terminal setup code works after Emacs has begun
3589 @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?
3590 @cindex Terminal setup code in @file{.emacs}
3592 During startup, Emacs initializes itself according to a given code/file
3593 order. If some of the code executed in your @file{.emacs} file needs to
3594 be postponed until the initial terminal or window-system setup code has
3595 been executed but is not, then you will experience this problem (this
3596 code/file execution order is not enforced after startup).
3598 To postpone the execution of Emacs Lisp code until after terminal or
3599 window-system setup, treat the code as a @dfn{lambda list} and set the
3600 value of either the @code{term-setup-hook} or @code{window-setup-hook}
3601 variable to this lambda function. For example,
3604 (add-hook 'term-setup-hook
3606 (when (string-match "\\`vt220" (or (getenv "TERM") ""))
3607 ;; Make vt220's "Do" key behave like M-x:
3608 (global-set-key [do] 'execute-extended-command))))
3611 For information on what Emacs does every time it is started, see the
3612 @file{lisp/startup.el} file.
3614 @node Working with function and arrow keys
3615 @section How do I tell what characters or symbols my function or arrow keys emit?
3616 @cindex Working with arrow keys
3617 @cindex Arrow keys, symbols generated by
3618 @cindex Working with function keys
3619 @cindex Function keys, symbols generated by
3620 @cindex Symbols generated by function keys
3622 Type @kbd{C-h c} then the function or arrow keys. The command will
3623 return either a function key symbol or character sequence (see the
3624 Emacs documentation for an explanation). This works for other
3627 @node X key translations for Emacs
3628 @section How do I set the X key ``translations'' for Emacs?
3629 @cindex X key translations
3630 @cindex Key translations under X
3631 @cindex Translations for keys under X
3633 Emacs is not written using the Xt library by default, so there are no
3634 ``translations'' to be set. (We aren't sure how to set such translations
3635 if you do build Emacs with Xt; please let us know if you've done this!)
3637 The only way to affect the behavior of keys within Emacs is through
3638 @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The
3639 @code{define-key} command should be used in conjunction with the
3640 @code{function-key-map} map. For instance,
3643 (define-key function-key-map [M-@key{TAB}] [?\M-\t])
3647 defines the @kbd{M-@key{TAB}} key sequence.
3649 @node Backspace invokes help
3650 @section Why does the @key{Backspace} key invoke help?
3651 @cindex Backspace key invokes help
3652 @cindex Help invoked by Backspace
3653 @cindex DEL key does not delete
3655 The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8.
3656 @kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes
3657 help-command. This is intended to be easy to remember since the first
3658 letter of @samp{help} is @samp{h}. The easiest solution to this problem
3659 is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
3660 @key{Delete} key) for deleting the previous character.
3662 For many people this solution may be problematic:
3667 They normally use @key{Backspace} outside of Emacs for deleting the
3668 previous character. This can be solved by making @key{DEL} the command
3669 for deleting the previous character outside of Emacs. On many Unix
3670 systems, this command will remap @key{DEL}:
3677 The user may prefer the @key{Backspace} key for deleting the
3678 previous character because it is more conveniently located on their
3679 keyboard or because they don't even have a separate @key{Delete} key.
3680 In this case, the @key{Backspace} key should be made to behave like
3681 @key{Delete}. There are several methods.
3685 Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
3686 TeraTerm) allow the character generated by the @key{Backspace} key to be
3687 changed from a setup menu.
3690 You may be able to get a keyboard that is completely programmable, or a
3691 terminal emulator that supports remapping of any key to any other key.
3694 With Emacs 21.1 and later, you can control the effect of the
3695 @key{Backspace} and @key{Delete} keys, on both dumb terminals and a
3696 windowed displays, by customizing the option
3697 @code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
3698 normal-erase-is-backspace}. See the documentation of these symbols
3699 (@pxref{Emacs Lisp documentation}) for more info.
3702 It is possible to swap the @key{Backspace} and @key{DEL} keys inside
3706 (keyboard-translate ?\C-h ?\C-?)
3710 This is the recommended method of forcing @key{Backspace} to act as
3711 @key{DEL}, because it works even in modes which bind @key{DEL} to
3712 something other than @code{delete-backward-char}.
3714 Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
3715 default deletes forward:
3718 (keyboard-translate ?\C-? ?\C-d)
3721 @xref{Swapping keys}, for further details about @code{keyboard-translate}.
3724 Another approach is to switch key bindings and put help on @kbd{C-x h}
3728 (global-set-key "\C-h" 'delete-backward-char)
3730 ;; overrides mark-whole-buffer
3731 (global-set-key "\C-xh" 'help-command)
3735 This method is not recommended, though: it only solves the problem for
3736 those modes which bind @key{DEL} to @code{delete-backward-char}. Modes
3737 which bind @key{DEL} to something else, such as @code{view-mode}, will
3738 not work as you expect when you press the @key{Backspace} key. For this
3739 reason, we recommend the @code{keyboard-translate} method, shown
3742 Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
3745 Don't try to bind @key{DEL} to @code{help-command}, because there are
3746 many modes that have local bindings of @key{DEL} that will interfere.
3750 When Emacs 21 or later runs on a windowed display, it binds the
3751 @key{Delete} key to a command which deletes the character at point, to
3752 make Emacs more consistent with keyboard operation on these systems.
3754 For more information about troubleshooting this problem, see @ref{DEL
3755 Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
3759 @section How do I swap two keys?
3760 @cindex Swapping keys
3761 @cindex Keys, swapping
3762 @cindex @code{keyboard-translate}
3764 You can swap two keys (or key sequences) by using the
3765 @code{keyboard-translate} function. For example, to turn @kbd{C-h}
3766 into @key{DEL} and @key{DEL} to @kbd{C-h}, use
3769 (keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL
3770 (keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.
3774 The first key sequence of the pair after the function identifies what is
3775 produced by the keyboard; the second, what is matched for in the
3778 However, in the specific case of @kbd{C-h} and @key{DEL}, you should
3779 toggle @code{normal-erase-is-backspace-mode} instead of calling
3780 @code{keyboard-translate}.
3781 @xref{DEL Does Not Delete,,, emacs, The GNU Emacs Manual}.
3783 Keyboard translations are not the same as key bindings in keymaps.
3784 Emacs contains numerous keymaps that apply in different situations, but
3785 there is only one set of keyboard translations, and it applies to every
3786 character that Emacs reads from the terminal. Keyboard translations
3787 take place at the lowest level of input processing; the keys that are
3788 looked up in keymaps contain the characters that result from keyboard
3791 @node Producing C-XXX with the keyboard
3792 @section How do I produce C-XXX with my keyboard?
3793 @cindex Producing control characters
3794 @cindex Generating control characters
3795 @cindex Control characters, generating
3797 On terminals (but not under X), some common ``aliases'' are:
3801 @item @kbd{C-2} or @kbd{C-@key{SPC}}
3807 @item @kbd{C-7} or @kbd{C-S--}
3821 Often other aliases exist; use the @kbd{C-h c} command and try
3822 @key{CTRL} with all of the digits on your keyboard to see what gets
3823 generated. You can also try the @kbd{C-h w} command if you know the
3824 name of the command.
3827 @section What if I don't have a @key{Meta} key?
3828 @cindex No @key{Meta} key
3829 @cindex @key{Meta} key, what to do if you lack it
3831 On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
3833 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact,
3834 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
3835 (depending on the value of @code{meta-prefix-char}). Note that you
3836 press @key{Meta} and @key{a} together, but with @key{ESC}, you press
3837 @key{ESC}, release it, and then press @key{a}.
3840 @section What if I don't have an @key{Escape} key?
3841 @cindex No Escape key
3842 @cindex Lacking an Escape key
3843 @cindex Escape key, lacking
3845 Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an
3846 Escape key would. @kbd{C-3} may also work on some terminal (but not
3847 under X). For many terminals (notably DEC terminals) @key{F11}
3848 generates @key{ESC}. If not, the following form can be used to bind it:
3851 ;; F11 is the documented ESC replacement on DEC terminals.
3852 (define-key function-key-map [f11] [?\e])
3855 @node Compose Character
3856 @section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
3857 @cindex @key{Compose Character} key, using as @key{Meta}
3858 @cindex @key{Meta}, using @key{Compose Character} for
3860 On a dumb terminal such as a VT220, no. It is rumored that certain
3861 VT220 clones could have their @key{Compose} key configured this way. If
3862 you're using X, you might be able to do this with the @code{xmodmap}
3865 @node Binding combinations of modifiers and function keys
3866 @section How do I bind a combination of modifier key and function key?
3867 @cindex Modifiers and function keys
3868 @cindex Function keys and modifiers
3869 @cindex Binding modifiers and function keys
3871 You can represent modified function keys in vector format by adding
3872 prefixes to the function key symbol. For example (from the Emacs
3876 (global-set-key [?\C-x right] 'forward-page)
3880 where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
3882 You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
3883 @key{Super}, @key{Alt}, and @key{Shift} with function keys. To
3884 represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
3885 @samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here
3886 is how to make @kbd{H-M-RIGHT} move forward a word:
3889 (global-set-key [H-M-right] 'forward-word)
3895 Not all modifiers are permitted in all situations. @key{Hyper},
3896 @key{Super}, and @key{Alt} are not available on Unix character
3897 terminals. Non-@acronym{ASCII} keys and mouse events (e.g., @kbd{C-=} and
3898 @kbd{Mouse-1}) also fall under this category.
3902 @xref{Binding keys to commands}, for general key binding instructions.
3904 @node Meta key does not work in xterm
3905 @section Why doesn't my @key{Meta} key work in an @code{xterm} window?
3906 @cindex @key{Meta} key and @code{xterm}
3907 @cindex Xterm and @key{Meta} key
3909 @xref{Unibyte Mode,, Single-Byte Character Set Support, emacs, The GNU Emacs Manual}.
3911 If the advice in the Emacs manual fails, try all of these methods before
3912 asking for further help:
3917 You may have big problems using @code{mwm} as your window manager.
3918 (Does anyone know a good generic solution to allow the use of the
3919 @key{Meta} key in Emacs with @file{mwm}?)
3922 For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to
3923 find out what keysym your @key{Meta} key generates. It should be either
3924 @code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix
3925 the situation. If @key{Meta} does generate @code{Meta_L} or
3926 @code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in
3927 your @file{~/.Xdefaults} file:
3930 XTerm*eightBitInput: false
3931 XTerm*eightBitOutput: true
3935 Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
3936 characters. @samp{stty -a} (or @samp{stty everything}) should show
3937 @samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty
3938 cs8 -istrip} (or @samp{stty pass8}) to fix it.
3941 If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
3942 @samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
3946 If Emacs is running on Ultrix, it is reported that evaluating
3947 @code{(set-input-mode t nil)} helps.
3950 If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
3951 you type @kbd{M-W}, which is the same conversion Emacs would make if it
3952 got the @kbd{M-W} anyway. In X11R4, the following resource
3953 specification will do this:
3956 XTerm.VT100.EightBitInput: false
3960 (This changes the behavior of the @code{insert-eight-bit} action.)
3962 With older @code{xterm}s, you can specify this behavior with a translation:
3965 XTerm.VT100.Translations: #override \
3966 Meta<KeyPress>: string(0x1b) insert()
3970 You might have to replace @samp{Meta} with @samp{Alt}.
3974 @node ExtendChar key does not work as Meta
3975 @section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
3976 @cindex @key{ExtendChar} key as @key{Meta}
3977 @cindex @key{Meta}, using @key{ExtendChar} for
3978 @cindex HP-UX, the @key{ExtendChar} key
3980 This is a result of an internationalization extension in X11R4 and the
3981 fact that HP is now using this extension. Emacs assumes that the
3982 @code{XLookupString} function returns the same result regardless of the
3983 @key{Meta} key state which is no longer necessarily true. Until Emacs
3984 is fixed, the temporary kludge is to run this command after each time
3985 the X server is started but preferably before any xterm clients are:
3988 xmodmap -e 'remove mod1 = Mode_switch'
3991 @c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
3994 This will disable the use of the extra keysyms systemwide, which may be
3995 undesirable if you actually intend to use them.
3997 @node SPC no longer completes file names
3998 @section Why doesn't SPC complete file names anymore?
3999 @cindex @kbd{SPC} file name completion
4001 Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in
4002 the minibuffer, so that file names with embedded spaces could be typed
4003 without the need to quote the spaces.
4005 You can get the old behavior by binding @kbd{SPC} to
4006 @code{minibuffer-complete-word} in the minibuffer, as follows:
4009 (define-key minibuffer-local-filename-completion-map (kbd "SPC")
4010 'minibuffer-complete-word)
4012 (define-key minibuffer-local-must-match-filename-map (kbd "SPC")
4013 'minibuffer-complete-word)
4016 @c ------------------------------------------------------------
4017 @node Alternate character sets
4018 @chapter Alternate character sets
4019 @cindex Alternate character sets
4022 * Emacs does not display 8-bit characters::
4023 * Inputting eight-bit characters::
4024 * Right-to-left alphabets::
4025 * How to add fonts::
4028 @node Emacs does not display 8-bit characters
4029 @section How do I make Emacs display 8-bit characters?
4030 @cindex Displaying eight-bit characters
4031 @cindex Eight-bit characters, displaying
4033 @xref{Unibyte Mode,, Single-byte Character Set Support, emacs, The GNU
4034 Emacs Manual}. On a Unix, when Emacs runs on a text-only terminal
4035 display or is invoked with @samp{emacs -nw}, you typically need to use
4036 @code{set-terminal-coding-system} to tell Emacs what the terminal can
4037 display, even after setting the language environment; otherwise
4038 non-@acronym{ASCII} characters will display as @samp{?}. On other operating
4039 systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
4040 character set supported by the display, and sets up the required
4041 terminal coding system automatically.
4043 @node Inputting eight-bit characters
4044 @section How do I input eight-bit characters?
4045 @cindex Entering eight-bit characters
4046 @cindex Eight-bit characters, entering
4047 @cindex Input, 8-bit characters
4049 Various methods are available for input of eight-bit characters.
4050 @xref{Unibyte Mode,, Single-byte Character Set Support, emacs, The GNU
4051 Emacs Manual}. For more sophisticated methods,
4052 @pxref{Input Methods,,, emacs, The GNU Emacs Manual}.
4054 @node Right-to-left alphabets
4055 @section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
4056 @cindex Right-to-left alphabets
4057 @cindex Hebrew, handling with Emacs
4058 @cindex Semitic alphabets
4061 @cindex bidirectional scripts
4063 Emacs supports display and editing of bidirectional scripts, such as
4064 Arabic, Farsi, and Hebrew, since version 24.1.
4065 @xref{New in Emacs 24, bidirectional display}.
4068 @node How to add fonts
4069 @section How do I add fonts for use with Emacs?
4070 @cindex add fonts for use with Emacs
4073 First, download and install the BDF font files and any auxiliary
4074 packages they need. The GNU Intlfonts distribution can be found on
4075 @uref{http://directory.fsf.org/localization/intlfonts.html, the GNU
4076 Software Directory Web site}.
4078 Next, if you are on X Window system, issue the following two commands
4079 from the shell's prompt:
4082 xset +fp /usr/local/share/emacs/fonts
4087 (Modify the first command if you installed the fonts in a directory
4088 that is not @file{/usr/local/share/emacs/fonts}.) You also need to
4089 arrange for these two commands to run whenever you log in, e.g., by
4090 adding them to your window-system startup file, such as
4091 @file{~/.xsessionrc} or @file{~/.gnomerc}.
4093 Now, add the following line to your @file{~/.emacs} init file:
4096 (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
4100 (Again, modify the file name if you installed the fonts elsewhere.)
4102 Finally, if you wish to use the installed fonts with @code{ps-print},
4103 add the following line to your @file{~/.emacs}:
4106 (setq ps-multibyte-buffer 'bdf-font-except-latin)
4109 A few additional steps are necessary for MS-Windows; they are listed
4112 First, make sure @emph{all} the directories with BDF font files are
4113 mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux
4114 systems, one normally runs @kbd{make install} to install the BDF fonts
4115 in the same directory. By contrast, Windows users typically don't run
4116 the Intlfonts installation command, but unpack the distribution in
4117 some directory, which leaves the BDF fonts in its subdirectories. For
4118 example, assume that you unpacked Intlfonts in @file{C:/Intlfonts};
4119 then you should set @code{bdf-directory-list} as follows:
4122 (setq bdf-directory-list
4123 '("C:/Intlfonts/Asian"
4124 "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X"
4125 "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic"
4126 "C:/Intlfonts/European" "C:/Intlfonts/European.BIG"
4127 "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X"
4128 "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X"
4129 "C:/Intlfonts/Misc"))
4132 @cindex @code{w32-bdf-filename-alist}
4133 @cindex @code{w32-find-bdf-fonts}
4134 Next, you need to set up the variable @code{w32-bdf-filename-alist} to
4135 an alist of the BDF fonts and their corresponding file names.
4136 Assuming you have set @code{bdf-directory-list} to name all the
4137 directories with the BDF font files, the following Lisp snippet will
4138 set up @code{w32-bdf-filename-alist}:
4141 (setq w32-bdf-filename-alist
4142 (w32-find-bdf-fonts bdf-directory-list))
4145 Now, create fontsets for the BDF fonts:
4148 (create-fontset-from-fontset-spec
4149 "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf,
4150 japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*,
4151 katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4152 latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4153 japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*,
4154 thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1,
4155 lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1,
4156 tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1,
4157 ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode,
4158 tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0")
4161 Many of the international bdf fonts from Intlfonts are type 0, and
4162 therefore need to be added to font-encoding-alist:
4165 (setq font-encoding-alist
4166 (append '(("MuleTibetan-0" (tibetan . 0))
4167 ("GB2312" (chinese-gb2312 . 0))
4168 ("JISX0208" (japanese-jisx0208 . 0))
4169 ("JISX0212" (japanese-jisx0212 . 0))
4170 ("VISCII" (vietnamese-viscii-lower . 0))
4171 ("KSC5601" (korean-ksc5601 . 0))
4172 ("MuleArabic-0" (arabic-digit . 0))
4173 ("MuleArabic-1" (arabic-1-column . 0))
4174 ("MuleArabic-2" (arabic-2-column . 0)))
4175 font-encoding-alist))
4178 You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
4179 fontset, or you can select it by setting the default font in your
4183 (set-default-font "fontset-bdf")
4187 @c ------------------------------------------------------------
4189 @chapter Mail and news
4190 @cindex Mail and news
4193 * Changing the included text prefix::
4194 * Saving a copy of outgoing mail::
4195 * Expanding aliases when sending mail::
4196 * Sorting the messages in an Rmail folder::
4197 * Rmail writes to /var/spool/mail::
4198 * Replying to the sender of a message::
4199 * Automatically starting a mail or news reader::
4200 * Reading news with Emacs::
4201 * Gnus does not work with NNTP::
4202 * Making Gnus faster::
4203 * Catching up in all newsgroups::
4206 @node Changing the included text prefix
4207 @section How do I change the included text prefix in mail/news followups?
4208 @cindex Prefix in mail/news followups, changing
4209 @cindex Included text prefix, changing
4210 @cindex Setting the included text character
4211 @cindex Quoting in mail messages
4213 If you read mail with Rmail, set the variable @code{mail-yank-prefix}.
4214 For Gnus, set @code{message-yank-prefix}. For VM, set
4215 @code{vm-included-text-prefix}. For mh-e, set @code{mh-ins-buf-prefix}.
4217 For fancier control of citations, use Supercite (@pxref{Top,, the Supercite
4218 Manual, sc, The Supercite Manual}).
4220 To prevent Emacs from including various headers of the replied-to
4221 message, set the value of @code{mail-yank-ignored-headers} to an
4224 @node Saving a copy of outgoing mail
4225 @section How do I save a copy of outgoing mail?
4226 @cindex Saving a copy of outgoing mail
4227 @cindex Copying outgoing mail to a file
4228 @cindex Filing outgoing mail
4229 @cindex Automatic filing of outgoing mail
4230 @cindex Mail, saving outgoing automatically
4232 You can either mail yourself a copy by including a @samp{BCC} header in the
4233 mail message, or store a copy of the message directly to a file by
4234 including an @samp{FCC} header.
4236 If you use standard mail, you can automatically create a @samp{BCC} to
4240 (setq mail-self-blind t)
4244 in your @file{.emacs} file. You can automatically include an @samp{FCC}
4245 field by putting something like the following in your @file{.emacs}
4249 (setq mail-archive-file-name (expand-file-name "~/outgoing"))
4252 The output file will be in Unix mail format.
4254 If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
4257 It does not work to put @samp{set record filename} in the @file{.mailrc}
4260 @node Expanding aliases when sending mail
4261 @section Why doesn't Emacs expand my aliases when sending mail?
4262 @cindex Expanding aliases when sending mail
4263 @cindex Mail alias expansion
4264 @cindex Sending mail with aliases
4266 @xref{Mail Aliases,, The Emacs Manual, emacs, The Emacs Manual}.
4271 Normally, Emacs expands aliases when you send the message.
4272 To expand them before this, use @kbd{M-x expand-mail-aliases}.
4275 Emacs normally only reads the @file{.mailrc} file once per session, when
4276 you start to compose your first mail message. If you edit the file
4277 after this, you can use @kbd{M-x build-mail-aliases} to make Emacs
4278 reread it. Prior to Emacs 24.1, this is not an interactive command, so
4279 you must instead type @kbd{M-: (build-mail-aliases) @key{RET}}.
4282 If you like, you can expand mail aliases as abbrevs, as soon as you
4283 type them in. To enable this feature, execute the following:
4286 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
4289 Note that the aliases are expanded automatically only after you type
4290 a word-separator character (e.g., @key{RET} or @kbd{,}). You can force their
4291 expansion by moving point to the end of the alias and typing @kbd{C-x a e}
4292 (@kbd{M-x expand-abbrev}).
4295 @node Sorting the messages in an Rmail folder
4296 @section How can I sort the messages in my Rmail folder?
4297 @cindex Rmail, sorting messages in
4298 @cindex Folder, sorting messages in an Rmail
4299 @cindex Sorting messages in an Rmail folder
4301 In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
4302 and their key bindings.
4304 @node Rmail writes to /var/spool/mail
4305 @section Why does Rmail need to write to @file{/var/spool/mail}?
4306 @cindex Rmail and @file{/var/spool/mail}
4307 @cindex @file{/var/spool/mail} and Rmail
4309 This is the behavior of the @code{movemail} program which Rmail uses.
4310 This indicates that @code{movemail} is configured to use lock files.
4315 Certain systems require lock files to interlock access to mail files.
4316 On these systems, @code{movemail} must write lock files, or you risk losing
4317 mail. You simply must arrange to let @code{movemail} write them.
4319 Other systems use the @code{flock} system call to interlock access. On
4320 these systems, you should configure @code{movemail} to use @code{flock}.
4323 @node Replying to the sender of a message
4324 @section How can I force Rmail to reply to the sender of a message, but not the other recipients?
4325 @cindex Replying only to the sender of a message
4326 @cindex Sender, replying only to
4327 @cindex Rmail, replying to the sender of a message in
4329 @c isaacson@@seas.upenn.edu
4330 Ron Isaacson says: When you hit
4331 @key{r} to reply in Rmail, by default it CCs all of the original
4332 recipients (everyone on the original @samp{To} and @samp{CC}
4333 lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
4334 it replies only to the sender. However, going through the whole
4335 @kbd{C-u} business every time you want to reply is a pain. This is the
4336 best fix I've been able to come up with:
4339 (defun rmail-reply-t ()
4340 "Reply only to the sender of the current message. (See rmail-reply.)"
4344 (add-hook 'rmail-mode-hook
4346 (define-key rmail-mode-map "r" 'rmail-reply-t)
4347 (define-key rmail-mode-map "R" 'rmail-reply)))
4350 @node Automatically starting a mail or news reader
4351 @section How do I make Emacs automatically start my mail/news reader?
4352 @cindex Mail reader, starting automatically
4353 @cindex News reader, starting automatically
4354 @cindex Starting mail/news reader automatically
4356 To start Emacs in Gnus:
4369 A more convenient way to start with Gnus:
4372 alias gnus 'emacs -f gnus'
4376 It is probably unwise to automatically start your mail or news reader
4377 from your @file{.emacs} file. This would cause problems if you needed to run
4378 two copies of Emacs at the same time. Also, this would make it difficult for
4379 you to start Emacs quickly when you needed to.
4381 @node Reading news with Emacs
4382 @section How do I read news under Emacs?
4383 @cindex Reading news under Emacs
4384 @cindex Usenet reader in Emacs
4385 @cindex Gnus newsreader
4386 @cindex FAQ for Gnus
4388 @cindex Learning more about Gnus
4390 Use @kbd{M-x gnus}. For more information on Gnus, @pxref{Top,, the Gnus
4391 Manual, gnus, The Gnus Manual}, which includes @ref{Frequently Asked
4392 Questions,, the Gnus FAQ, gnus, The Gnus Manual}.
4395 @node Gnus does not work with NNTP
4396 @section Why doesn't Gnus work via NNTP?
4397 @cindex Gnus and NNTP
4398 @cindex NNTP, Gnus fails to work with
4400 There is a bug in NNTP version 1.5.10, such that when multiple requests
4401 are sent to the NNTP server, the server only handles the first one
4402 before blocking waiting for more input which never comes. NNTP version
4403 1.5.11 claims to fix this.
4405 You can work around the bug inside Emacs like this:
4408 (setq nntp-maximum-request 1)
4411 You can find out what version of NNTP your news server is running by
4412 telnetting to the NNTP port (usually 119) on the news server machine
4413 (i.e., @kbd{telnet server-machine 119}). The server should give its
4414 version number in the welcome message. Type @kbd{quit} to get out.
4416 @node Making Gnus faster
4417 @section How do I make Gnus faster?
4418 @cindex Faster, starting Gnus
4419 @cindex Starting Gnus faster
4420 @cindex Gnus, starting faster
4421 @cindex Slow catch up in Gnus
4422 @cindex Gnus is slow when catching up
4423 @cindex Crosspostings make Gnus catching up slow
4425 From the Gnus FAQ (@pxref{Reading news with Emacs}):
4428 If you have a slow machine, or are just really impatient, there are a
4429 few things you can do to make Gnus run faster.
4431 Set @code{gnus-check-new-newsgroups} and
4432 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
4434 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
4435 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
4436 summary buffer faster.
4439 @node Catching up in all newsgroups
4440 @section How do I catch up all newsgroups in Gnus?
4441 @cindex Catching up all newsgroups in Gnus
4442 @cindex Gnus, Catching up all newsgroups in
4444 In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
4446 Leave off the initial @kbd{M-<} if you only want to catch up from point
4447 to the end of the @file{*Newsgroup*} buffer.
4450 @unnumbered Concept Index