1 \input texinfo @c -*- mode: texinfo; -*-
3 @setfilename ../../info/efaq
4 @settitle GNU Emacs FAQ
7 @c This is used in many places
10 @c This file is maintained by Romain Francoise <rfrancoise@gnu.org>.
11 @c Feel free to install changes without prior permission (but I'd
12 @c appreciate a notice if you do).
15 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
16 2009, 2010 Free Software Foundation, Inc.@*
17 Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000
19 Copyright @copyright{} 1992, 1993 Steven Byrnes@*
20 Copyright @copyright{} 1990, 1991, 1992 Joseph Brian Wells@*
23 This list of frequently asked questions about GNU Emacs with answers
24 (``FAQ'') may be translated into other languages, transformed into other
25 formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.
27 The same conditions apply to any derivative of the FAQ as apply to the FAQ
28 itself. Every copy of the FAQ must include this notice or an approved
29 translation, information on who is currently maintaining the FAQ and how to
30 contact them (including their e-mail address), and information on where the
31 latest version of the FAQ is archived (including FTP information).
33 The FAQ may be copied and redistributed under these conditions, except that
34 the FAQ may not be embedded in a larger literary work unless that work
35 itself allows free copying and redistribution.
37 [This version has been heavily edited since it was included in the Emacs
44 * Emacs FAQ: (efaq). Frequently Asked Questions about Emacs.
47 @c The @titlepage stuff only appears in the printed version
50 @center @titlefont{GNU Emacs FAQ}
52 @c The following two commands start the copyright page.
54 @vskip 0pt plus 1filll
60 @node Top, FAQ notation, (dir), (dir)
61 @top The GNU Emacs FAQ
63 @c FIXME @today is just the day we ran `makeinfo'.
64 This is the GNU Emacs FAQ, last updated on @today{}.
66 This FAQ is maintained as a part of GNU Emacs. If you find any errors,
67 or have any suggestions, please use @kbd{M-x report-emacs-bug} to report
70 This is the version of the FAQ distributed with Emacs @value{VER}, and
71 mainly describes that version. Although there is some information on
72 older versions, details about very old releases (now only of historical
73 interest) have been removed. If you are interested in this, consult
74 either the version of the FAQ distributed with older versions of Emacs,
75 or the history of this document in the Emacs source repository.
77 Since Emacs releases are very stable, we recommend always running the
80 This FAQ is not updated very frequently. When you have a question about
81 Emacs, the Emacs manual is often the best starting point.
94 * Compiling and installing Emacs::
95 * Finding Emacs and related packages::
96 * Major packages and programs::
98 * Alternate character sets::
103 @c ------------------------------------------------------------
105 @chapter FAQ notation
108 This chapter describes notation used in the GNU Emacs FAQ, as well as in
109 the Emacs documentation. Consult this section if this is the first time
110 you are reading the FAQ, or if you are confused by notation or terms
115 * Extended commands::
117 * File-name conventions::
122 @section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
124 @cindex Control key, notation for
125 @cindex @key{Meta} key, notation for
126 @cindex Control-Meta characters, notation for
127 @cindex @kbd{C-h}, definition of
128 @cindex @kbd{C-M-h}, definition of
129 @cindex @key{DEL}, definition of
130 @cindex @key{ESC}, definition of
131 @cindex @key{LFD}, definition of
132 @cindex @key{RET}, definition of
133 @cindex @key{SPC}, definition of
134 @cindex @key{TAB}, definition of
135 @cindex Notation for keys
140 @kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
143 @kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
144 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
147 @kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
151 @kbd{C-M-x}: a synonym for the above
154 @key{LFD}: Linefeed or Newline; same as @kbd{C-j}
157 @key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
160 @key{DEL}: @key{Delete}, usually @strong{not} the same as
161 @key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
162 deleting invokes Emacs help)
165 @key{ESC}: Escape; same as @kbd{C-[}
168 @key{TAB}: Tab; same as @kbd{C-i}
175 Key sequences longer than one key (and some single-key sequences) are
176 written inside quotes or on lines by themselves, like this:
179 @kbd{M-x frobnicate-while-foo RET}
183 Any real spaces in such a key sequence should be ignored; only @key{SPC}
184 really means press the space key.
186 The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
187 that would be sent by pressing just @key{x} minus 96 (or 64 for
188 upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
189 terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
190 @acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
191 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
193 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
196 @kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
197 @kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON.
198 Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
199 @c FIXME I cannot understand the previous sentence.
201 @inforef{Keys, Keys, emacs}, for more information. (@xref{Emacs
202 manual}, for more information about Info.)
204 @node Extended commands
205 @section What does @file{M-x @var{command}} mean?
206 @cindex Extended commands
207 @cindex Commands, extended
208 @cindex M-x, meaning of
210 @kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
211 command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
212 what @kbd{M-x} and @key{RET} mean.)
214 @kbd{M-x} (by default) invokes the command
215 @code{execute-extended-command}. This command allows you to run any
216 Emacs command if you can remember the command's name. If you can't
217 remember the command's name, you can type @key{TAB} and @key{SPC} for
218 completion, @key{?} for a list of possibilities, and @kbd{M-p} and
219 @kbd{M-n} (or up-arrow and down-arrow) to see previous commands entered.
220 An Emacs @dfn{command} is an @dfn{interactive} Emacs function.
223 Your system administrator may have bound other key sequences to invoke
224 @code{execute-extended-command}. A function key labeled @kbd{Do} is a
225 good candidate for this, on keyboards that have such a key.
227 If you need to run non-interactive Emacs functions, see @ref{Evaluating
231 @section How do I read topic XXX in the Emacs manual?
232 @cindex Emacs manual, reading topics in
233 @cindex Reading topics in the Emacs manual
234 @cindex Finding topics in the Emacs manual
235 @cindex Info, finding topics in
237 When we refer you to some @var{topic} in the Emacs manual, you can
238 read this manual node inside Emacs (assuming nothing is broken) by
239 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
241 This invokes Info, the GNU hypertext documentation browser. If you don't
242 already know how to use Info, type @key{?} from within Info.
244 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
245 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
247 If these commands don't work as expected, your system administrator may
248 not have installed the Info files, or may have installed them
249 improperly. In this case you should complain.
251 If you are reading this FAQ in Info, you can simply press @key{RET} on a
252 reference to follow it.
254 @xref{Getting a printed manual}, if you would like a paper copy of the
257 @node File-name conventions
258 @section What are @file{etc/GNU}, @file{src/config.h}, @file{site-lisp/default.el}, etc.?
259 @cindex File-name conventions
260 @cindex Conventions for file names
261 @cindex Directories and files that come with Emacs
263 These are files that come with Emacs. The Emacs distribution is divided
264 into subdirectories; e.g. @file{etc}, @file{lisp}, and @file{src}.
265 Some of these (e.g. @file{etc} and @file{lisp}) are present both in
266 an installed Emacs and in the sources, but some (e.g. @file{src}) are
267 only found in the sources.
269 If you use Emacs, but don't know where it is kept on your system, start
270 Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
271 name displayed by this will be the full pathname of the installed
272 @file{etc} directory. (This full path is recorded in the Emacs variable
273 @code{data-directory}, and @kbd{C-h v} displays the value and the
274 documentation of a variable.)
276 The location of your Info directory (i.e., where Info documentation
277 is stored) is kept in the variable @code{Info-default-directory-list}. Use
278 @kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
279 this variable, which will be a list of directory names. The last
280 directory in that list is probably where most Info files are stored. By
281 default, Emacs Info documentation is placed in @file{/usr/local/share/info}.
283 For information on some of the files in the @file{etc} directory,
284 @pxref{Informational files for Emacs}.
286 @node Common acronyms
287 @section What are FSF, LPF, GNU, RMS, FTP, and GPL?
288 @cindex FSF, definition of
289 @cindex LPF, definition of
290 @cindex GNU, definition of
291 @cindex RMS, definition of
292 @cindex Stallman, Richard, acronym for
293 @cindex Richard Stallman, acronym for
294 @cindex FTP, definition of
295 @cindex GPL, definition of
296 @cindex Acronyms, definitions for
297 @cindex Common acronyms, definitions for
302 Free Software Foundation
305 League for Programming Freedom
311 Richard Matthew Stallman
314 File Transfer Protocol
317 GNU General Public License
321 Avoid confusing the FSF and the LPF. The LPF opposes
322 look-and-feel copyrights and software patents. The FSF aims to make
323 high quality free software available for everyone.
325 The word ``free'' in the title of the Free Software Foundation refers to
326 ``freedom,'' not ``zero cost.'' Anyone can charge any price for
327 GPL-covered software that they want to. However, in practice, the
328 freedom enforced by the GPL leads to low prices, because you can always
329 get the software for less money from someone else, since everyone has
330 the right to resell or give away GPL-covered software.
332 @c ------------------------------------------------------------
333 @node General questions
334 @chapter General questions
335 @cindex General questions
337 This chapter contains general questions having to do with Emacs, the
338 Free Software Foundation, and related organizations.
342 * Real meaning of copyleft::
343 * Guidelines for newsgroup postings::
344 * Newsgroup archives::
346 * Unsubscribing from Emacs lists::
347 * Contacting the FSF::
351 @section What is the LPF?
352 @cindex LPF, description of
353 @cindex League for Programming Freedom
354 @cindex Software patents, opposition to
355 @cindex Patents for software, opposition to
357 The LPF opposes the expanding danger of software patents and
358 look-and-feel copyrights. More information on the LPF's views is
359 available at @uref{http://progfree.org/, the LPF home page}.
361 @node Real meaning of copyleft
362 @section What is the real legal meaning of the GNU copyleft?
363 @cindex Copyleft, real meaning of
364 @cindex GPL, real meaning of
365 @cindex General Public License, real meaning of
366 @cindex Discussion of the GPL
368 The real legal meaning of the GNU General Public License (copyleft) will
369 only be known if and when a judge rules on its validity and scope.
370 There has never been a copyright infringement case involving the GPL to
371 set any precedents. Although legal actions have been brought against
372 companies for violating the terms of the GPL, so far all have been
373 settled out of court (in favour of the plaintiffs). Please take any
374 discussion regarding this issue to the newsgroup
375 @uref{news:gnu.misc.discuss}, which was created to hold the extensive
376 flame wars on the subject.
381 The legal meaning of the GNU copyleft is less important than the spirit,
382 which is that Emacs is a free software project and that work pertaining
383 to Emacs should also be free software. ``Free'' means that all users
384 have the freedom to study, share, change and improve Emacs. To make
385 sure everyone has this freedom, pass along source code when you
386 distribute any version of Emacs or a related program, and give the
387 recipients the same freedom that you enjoyed.
390 @node Guidelines for newsgroup postings
391 @section What are appropriate messages for the various Emacs newsgroups?
392 @cindex Newsgroups, appropriate messages for
393 @cindex GNU newsgroups, appropriate messages for
394 @cindex Usenet groups, appropriate messages for
395 @cindex Mailing lists, appropriate messages for
396 @cindex Posting messages to newsgroups
398 @cindex GNU mailing lists
399 The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
400 mailing list (@pxref{Informational files for Emacs}). For those lists
401 which are gatewayed with newsgroups, it lists both the newsgroup name
402 and the mailing list address. The Emacs mailing lists are also
403 described at @uref{http://savannah.gnu.org/mail/?group=emacs, the Emacs
406 The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
407 in general. The newsgroup @uref{news:gnu.emacs.help} is specifically
408 for GNU Emacs. It therefore makes no sense to cross-post to both
409 groups, since only one can be appropriate to any question.
411 Messages advocating ``non-free'' software are considered unacceptable on
412 any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
413 which was created to hold the extensive flame-wars on the subject.
414 ``Non-free'' software includes any software for which the end user can't
415 freely modify the source code and exchange enhancements. Be careful to
416 remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
417 posting a followup that recommends such software.
419 @uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
420 posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
422 @node Newsgroup archives
423 @section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
424 @cindex Archived postings from @code{gnu.emacs.help}
425 @cindex Usenet archives for GNU groups
426 @cindex Old Usenet postings for GNU groups
428 The FSF has maintained archives of all of the GNU mailing lists for many
429 years, although there may be some unintentional gaps in coverage. The
430 archive can be browsed over the web at
431 @uref{http://lists.gnu.org/archive/html/, the GNU mail archive}. Raw
432 files can be downloaded from @uref{ftp://lists.gnu.org/}.
434 Web-based Usenet search services, such as
435 @uref{http://groups.google.com/groups/dir?q=gnu&, Google}, also
436 archive the @code{gnu.*} groups.
438 You can also read the archives of the @code{gnu.*} groups and post new
439 messages at @uref{http://gmane.org/, Gmane}. Gmane is a service that
440 presents mailing lists as newsgroups (even those without a traditional
441 mail-to-news gateway).
444 @section Where should I report bugs and other problems with Emacs?
445 @cindex Bug reporting
446 @cindex Good bug reports
447 @cindex How to submit a bug report
448 @cindex Reporting bugs
450 The correct way to report Emacs bugs is to use the command
451 @kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
452 essential information and the correct e-mail address, which is
453 @email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs.
454 Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the
455 newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
456 news to submit the bug report. This ensures a reliable return address
457 so you can be contacted for further details.
459 Be sure to read the ``Bugs'' section of the Emacs manual before reporting
460 a bug! The manual describes in detail how to submit a useful bug
461 report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
462 (@xref{Emacs manual}, if you don't know how to read the manual.)
467 Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
468 effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
469 it takes the time of an unnecessarily large group of people, most of
470 whom are just users and have no idea how to fix these problem.
471 @email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
472 who are more likely to know what to do and have expressed a wish to
473 receive more messages about Emacs than the others.
476 RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
479 If you have reported a bug and you don't hear about a possible fix,
480 then after a suitable delay (such as a week) it is okay to post on
481 @code{gnu.emacs.help} asking if anyone can help you.
484 If you are unsure whether you have found a bug, consider the following
485 non-exhaustive list, courtesy of RMS:
488 If Emacs crashes, that is a bug. If Emacs gets compilation errors
489 while building, that is a bug. If Emacs crashes while building, that
490 is a bug. If Lisp code does not do what the documentation says it
494 @node Unsubscribing from Emacs lists
495 @section How do I unsubscribe from a mailing list?
496 @cindex Unsubscribing from GNU mailing lists
497 @cindex Removing yourself from GNU mailing lists
499 If you are receiving a GNU mailing list named @var{list}, you should be
500 able to unsubscribe from it by sending a request to the address
501 @email{@var{list}-request@@gnu.org}. Mailing lists mails normally
502 contain information in either the message header
503 (@samp{List-Unsubscribe:}) or as a footer that tells you how to
506 @node Contacting the FSF
507 @section What is the current address of the FSF?
508 @cindex Snail mail address of the FSF
509 @cindex Postal address of the FSF
510 @cindex Contracting the FSF
511 @cindex Free Software Foundation, contacting
513 For up-to-date information, see
514 @uref{http://www.fsf.org/about/contact.html, the FSF contact web-page}.
528 @uref{http://www.fsf.org/}
531 Free Software Foundation@*
532 51 Franklin Street, Fifth Floor@*
533 Boston, MA 02110-1301@*
538 @cindex Ordering GNU software
539 For details on how to order items directly from the FSF, see the
540 @uref{http://shop.fsf.org/, FSF on-line store}.
542 @c ------------------------------------------------------------
544 @chapter Getting help
547 This chapter tells you how to get help with Emacs.
551 * Learning how to do something::
552 * Getting a printed manual::
553 * Emacs Lisp documentation::
554 * Installing Texinfo documentation::
555 * Printing a Texinfo file::
556 * Viewing Info files outside of Emacs::
557 * Informational files for Emacs::
558 * Help installing Emacs::
559 * Obtaining the FAQ::
563 @section I'm just starting Emacs; how do I do basic editing?
564 @cindex Basic editing with Emacs
565 @cindex Beginning editing
566 @cindex Tutorial, invoking the
567 @cindex Self-paced tutorial, invoking the
568 @cindex Help system, entering the
570 Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
571 @kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
572 is available in many foreign languages such as French, German, Japanese,
573 Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
574 to choose your language and start the tutorial.
576 Your system administrator may have changed @kbd{C-h} to act like
577 @key{DEL} to deal with local keyboards. You can use @kbd{M-x
578 help-for-help} instead to invoke help. To discover what key (if any)
579 invokes help on your system, type @kbd{M-x where-is @key{RET}
580 help-for-help @key{RET}}. This will print a comma-separated list of key
581 sequences in the echo area. Ignore the last character in each key
582 sequence listed. Each of the resulting key sequences (e.g. @key{F1} is
583 common) invokes help.
585 Emacs help works best if it is invoked by a single key whose value
586 should be stored in the variable @code{help-char}.
588 @node Learning how to do something
589 @section How do I find out how to do something in Emacs?
590 @cindex Help for Emacs
591 @cindex Learning to do something in Emacs
592 @cindex Reference card for Emacs
593 @cindex Overview of help systems
595 There are several methods for finding out how to do things in Emacs.
599 @cindex Reading the Emacs manual
601 The complete text of the Emacs manual is available via the Info
602 hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
603 Typing @key{h} immediately after entering Info will provide a short
604 tutorial on how to use it.
606 @cindex Lookup a subject in a manual
607 @cindex Index search in a manual
609 To quickly locate the section of the manual which discusses a certain
610 issue, or describes a command or a variable, type @kbd{C-h i m emacs
611 @key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
612 topic, the command, or the variable which you are looking for. If this
613 does not land you on the right place in the manual, press @kbd{,}
614 (comma) repeatedly until you find what you need. (The @kbd{i} and
615 @kbd{,} keys invoke the index-searching functions, which look for the
616 @var{topic} you type in all the indices of the Emacs manual.)
620 You can list all of the commands whose names contain a certain word
621 (actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
624 @cindex Command description in the manual
626 The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
627 for the name of a command, and then attempts to find the section in the
628 Emacs manual where that command is described.
630 @cindex Finding commands and variables
632 You can list all of the functions and variables whose names contain a
633 certain word using @kbd{M-x apropos}.
636 You can list all of the functions and variables whose documentation
637 matches a regular expression or a string, using @kbd{M-x
638 apropos-documentation}.
641 You can order a hardcopy of the manual from the FSF. @xref{Getting a
644 @cindex Reference cards, in other languages
646 You can get a printed reference card listing commands and keys to
647 invoke them. You can order one from the FSF for $2 (or 10 for $18),
648 or you can print your own from the @file{etc/refcards/refcard.tex} or
649 @file{etc/refcards/refcard.pdf} files in the Emacs distribution.
650 Beginning with version 21.1, the Emacs distribution comes with
651 translations of the reference card into several languages; look for
652 files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang}
653 is a two-letter code of the language. For example, the German version
654 of the reference card is in the files @file{etc/refcards/de-refcard.tex}
655 and @file{etc/recards/de-refcard.pdf}.
658 There are many other commands in Emacs for getting help and
659 information. To get a list of these commands, type @samp{?} after
664 @node Getting a printed manual
665 @section How do I get a printed copy of the Emacs manual?
666 @cindex Printed Emacs manual, obtaining
667 @cindex Manual, obtaining a printed or HTML copy of
668 @cindex Emacs manual, obtaining a printed or HTML copy of
670 You can order a printed copy of the Emacs manual from the FSF. For
671 details see the @uref{http://shop.fsf.org/, FSF on-line store}.
673 The full Texinfo source for the manual also comes in the @file{doc/emacs}
674 directory of the Emacs distribution, if you're daring enough to try to
675 print out this several-hundred-page manual yourself (@pxref{Printing a Texinfo
678 If you absolutely have to print your own copy, and you don't have @TeX{},
679 you can get a PostScript or PDF (or HTML) version from
681 @uref{http://www.gnu.org/software/emacs/manual/}
683 @xref{Learning how to do something}, for how to view the manual from Emacs.
685 @node Emacs Lisp documentation
686 @section Where can I get documentation on Emacs Lisp?
687 @cindex Documentation on Emacs Lisp
688 @cindex Function documentation
689 @cindex Variable documentation
690 @cindex Emacs Lisp Reference Manual
691 @cindex Reference manual for Emacs Lisp
693 Within Emacs, you can type @kbd{C-h f} to get the documentation for a
694 function, @kbd{C-h v} for a variable.
696 For more information, the Emacs Lisp Reference Manual is available
697 in Info format (@pxref{Top, Emacs Lisp,, elisp, The
698 Emacs Lisp Reference Manual}).
700 You can also order a hardcopy of the manual from the FSF, for details
701 see the @uref{http://shop.fsf.org/, FSF on-line store}. (This manual is
702 not always in print.)
704 An HTML version of the Emacs Lisp Reference Manual is available at
706 @uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
708 @node Installing Texinfo documentation
709 @section How do I install a piece of Texinfo documentation?
710 @cindex Texinfo documentation, installing
711 @cindex Installing Texinfo documentation
712 @cindex New Texinfo files, installing
713 @cindex Documentation, installing new Texinfo files
714 @cindex Info files, how to install
716 Emacs releases come with pre-built Info files, and the normal install
717 process places them in the correct location. This is true for most
718 applications that provide Info files. The following section is only
719 relevant if you want to install extra Info files by hand.
721 First, you must turn the Texinfo source files into Info files. You may
722 do this using the stand-alone @file{makeinfo} program, available as part
723 of the Texinfo package at
725 @uref{http://www.gnu.org/software/texinfo/}
727 For information about the Texinfo format, read the Texinfo manual which
728 comes with the Texinfo package. This manual also comes installed in
729 Info format, so you can read it from Emacs; type @kbd{C-h i m texinfo
732 @c FIXME is this a complete alternative?
733 @c Probably not, given that we require makeinfo to build Emacs.
734 Alternatively, you could use the Emacs command @kbd{M-x
735 texinfo-format-buffer}, after visiting the Texinfo source file of the
736 manual you want to convert.
738 Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
739 resulting Info files in Emacs's Info tree. To install Info files,
744 Move the files to the @file{info} directory in the installed Emacs
745 distribution. @xref{File-name conventions}, if you don't know where that
749 Run the @code{install-info} command, which is part of the Texinfo
750 distribution, to update the main Info directory menu, like this:
753 install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
757 where @var{dir-path} is the full path to the directory where you copied
758 the produced Info file(s), and @var{file} is the name of the Info file
759 you produced and want to install.
761 If you don't have the @code{install-info} command installed, you can
762 edit the file @file{info/dir} in the installed Emacs distribution, and
763 add a line for the top level node in the Info package that you are
764 installing. Follow the examples already in this file. The format is:
767 * Topic: (relative-pathname). Short description of topic.
772 If you want to install Info files and you don't have the necessary
773 privileges, you have several options:
777 Info files don't actually need to be installed before being used.
778 You can use a prefix argument for the @code{info} command and specify
779 the name of the Info file in the minibuffer. This goes to the node
780 named @samp{Top} in that file. For example, to view a Info file named
781 @file{@var{info-file}} in your home directory, you can type this:
784 @kbd{C-u C-h i ~/@var{info-file} @key{RET}}
787 Alternatively, you can feed a file name to the @code{Info-goto-node}
788 command (invoked by pressing @key{g} in Info mode) by typing the name
789 of the file in parentheses, like this:
792 @kbd{C-h i g (~/@var{info-file}) @key{RET}}
796 You can create your own Info directory. You can tell Emacs where that
797 Info directory is by adding its pathname to the value of the variable
798 @code{Info-default-directory-list}. For example, to use a private Info
799 directory which is a subdirectory of your home directory named @file{Info},
800 you could put this in your @file{.emacs} file:
803 (add-to-list 'Info-default-directory-list "~/Info")
806 You will need a top-level Info file named @file{dir} in this directory
807 which has everything the system @file{dir} file has in it, except it
808 should list only entries for Info files in that directory. You might
809 not need it if (fortuitously) all files in this directory were
810 referenced by other @file{dir} files. The node lists from all
811 @file{dir} files in @code{Info-default-directory-list} are merged by the
816 @node Printing a Texinfo file
817 @section How do I print a Texinfo file?
818 @cindex Printing a Texinfo file
819 @cindex Texinfo file, printing
820 @cindex Printing documentation
822 You can't get nicely printed output from Info files; you must still have
823 the original Texinfo source file for the manual you want to print.
825 Assuming you have @TeX{} installed on your system, follow these steps:
830 Make sure the first line of the Texinfo file looks like this:
836 You may need to change @samp{texinfo} to the full pathname of the
837 @file{texinfo.tex} file, which comes with Emacs as
838 @file{doc/misc/texinfo.tex} (or copy or link it into the current directory).
841 Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
842 the name of the Texinfo source file for which you want to produce a
843 printed copy. The @samp{texi2dvi} script is part of the GNU Texinfo
846 Alternatively, @samp{texi2pdf} produces PDF files.
849 Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
850 printing DVI files at your site. For example, if you have a PostScript
851 printer, run the @code{dvips} program to print the DVI file on that
856 To get more general instructions, retrieve the latest Texinfo package
857 (@pxref{Installing Texinfo documentation}).
859 @node Viewing Info files outside of Emacs
860 @section Can I view Info files without using Emacs?
861 @cindex Viewing Info files
862 @cindex Info file viewers
863 @cindex Alternative Info file viewers
865 Yes. Here are some alternative programs:
870 @code{info}, a stand-alone version of the Info program, comes as part of
871 the Texinfo package. @xref{Installing Texinfo documentation}, for
875 Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
876 You can get Tkinfo at
877 @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
881 @node Informational files for Emacs
882 @section What informational files are available for Emacs?
883 @cindex Informational files included with Emacs
884 @cindex Files included with Emacs
885 @cindex @file{COPYING}, description of file
886 @cindex @file{DISTRIB}, description of file
887 @cindex @file{GNU}, description of file
888 @cindex @file{INTERVIEW}, description of file
889 @cindex @file{MACHINES}, description of file
890 @cindex @file{MAILINGLISTS}, description of file
891 @cindex @file{NEWS}, description of file
893 This isn't a frequently asked question, but it should be! A variety of
894 informational files about Emacs and relevant aspects of the GNU project
895 are available for you to read.
897 The following files (and others) are available in the @file{etc}
898 directory of the Emacs distribution (see @ref{File-name conventions}, if
899 you're not sure where that is). Many of these files are available via
900 the Emacs @samp{Help} menu, or by typing @kbd{C-h ?} (@kbd{M-x
906 GNU General Public License
909 Emacs Availability Information
915 Richard Stallman discusses his public-domain UNIX-compatible software
916 system with BYTE editors
919 Status of Emacs on Various Machines and Systems
922 GNU Project Electronic Mailing Lists
925 Emacs news, a history of recent user-visible changes
929 More GNU information, including back issues of the @cite{GNU's
932 @uref{http://www.gnu.org/bulletins/bulletins.html} and
934 @uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
936 @node Help installing Emacs
937 @section Where can I get help in installing Emacs?
938 @cindex Installation help
939 @cindex Help installing Emacs
941 @xref{Installing Emacs}, for some basic installation hints, and see
942 @ref{Problems building Emacs}, if you have problems with the installation.
944 @uref{http://www.fsf.org/resources/service/, The GNU Service directory}
945 lists companies and individuals willing to sell you help in installing
946 or using Emacs and other GNU software.
948 @node Obtaining the FAQ
949 @section Where can I get the latest version of this FAQ?
950 @cindex FAQ, obtaining the
951 @cindex Latest FAQ version, obtaining the
953 The Emacs FAQ is distributed with Emacs in Info format. You can read it
954 by selecting the @samp{Emacs FAQ} option from the @samp{Help} menu of
955 the Emacs menu bar at the top of any Emacs frame, or by typing @kbd{C-h
956 C-f} (@kbd{M-x view-emacs-FAQ}). The very latest version is available
957 in the Emacs development repository (@pxref{Latest version of Emacs}).
959 @c ------------------------------------------------------------
960 @node Status of Emacs
961 @chapter Status of Emacs
962 @cindex Status of Emacs
964 This chapter gives you basic information about Emacs, including the
965 status of its latest version.
968 * Origin of the term Emacs::
969 * Latest version of Emacs::
976 @node Origin of the term Emacs
977 @section Where does the name ``Emacs'' come from?
978 @cindex Origin of the term ``Emacs''
979 @cindex Emacs name origin
981 @cindex Original version of Emacs
983 Emacs originally was an acronym for Editor MACroS. RMS says he ``picked
984 the name Emacs because @key{E} was not in use as an abbreviation on ITS at
985 the time.'' The first Emacs was a set of macros written in 1976 at MIT
986 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
987 Editor and COrrector) under ITS (the Incompatible Timesharing System) on
988 a PDP-10. RMS had already extended TECO with a ``real-time''
989 full-screen mode with reprogrammable keys. Emacs was started by
990 @email{gls@@east.sun.com, Guy Steele} as a project to unify the many
991 divergent TECO command sets and key bindings at MIT, and completed by
994 Many people have said that TECO code looks a lot like line noise; you
995 can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
996 implementation in Emacs Lisp (to find it, see @ref{Packages that do not
997 come with Emacs}); it would be an interesting project to run the
998 original TECO Emacs inside of Emacs.
1001 For some not-so-serious alternative reasons for Emacs to have that
1002 name, check out the file @file{etc/JOKES} (@pxref{File-name
1005 @node Latest version of Emacs
1006 @section What is the latest version of Emacs?
1007 @cindex Version, latest
1008 @cindex Latest version of Emacs
1009 @cindex Development, Emacs
1010 @cindex Repository, Emacs
1011 @cindex CVS repository, Emacs
1012 @cindex Arch repository, Emacs
1013 @cindex Git repository, Emacs
1015 Emacs @value{VER} is the current version as of this writing. A version
1016 number with two components (e.g. @samp{22.1}) indicates a released
1017 version; three components indicate a development
1018 version (e.g. @samp{23.0.50} is what will eventually become @samp{23.1}).
1020 Emacs is under active development, hosted at
1021 @uref{http://savannah.gnu.org/projects/emacs/, Savannah}. The source
1022 code can be retrieved anonymously following the
1023 @uref{http://savannah.gnu.org/cvs/?group=emacs, instructions}.
1024 The primary repository is CVS, but Arch and Git mirrors are also
1027 Because Emacs undergoes many changes before a release, the version
1028 number of a development version is not especially meaningful. It is
1029 better to refer to the date on which the sources were retrieved from the
1030 development repository. The development version is usually quite robust
1031 for every-day use, but if stability is more important to you than the
1032 latest features, you may want to stick to the releases.
1034 The following sections list some of the major new features in the last
1035 few Emacs releases. For full details of the changes in any version of
1036 Emacs, type @kbd{C-h C-n} (@kbd{M-x view-emacs-news}). As of Emacs 22,
1037 you can give this command a prefix argument to read about which features
1038 were new in older versions.
1040 @node New in Emacs 23
1041 @section What is different about Emacs 23?
1042 @cindex Differences between Emacs 22 and Emacs 23
1043 @cindex Emacs 23, new features in
1044 @cindex Recently introduced features
1045 @cindex Default features
1049 @cindex Anti-aliased fonts
1050 @cindex Freetype fonts
1052 Emacs has a new font code that can use multiple font backends,
1053 including freetype and fontconfig. Emacs can use the Xft library for
1054 anti-aliasing, and the otf and m17n libraries for complex text layout and
1058 @cindex Character sets
1060 The Emacs character set is now a superset of Unicode. Several new
1061 language environments have been added.
1063 @cindex Multi-tty support
1064 @cindex X and tty displays
1066 Emacs now supports using both X displays and ttys in the same session
1071 Emacs can be started as a daemon in the background.
1073 @cindex NeXTSTEP port
1074 @cindex GNUstep port
1075 @cindex Mac OS X Cocoa
1077 There is a new NeXTSTEP port of Emacs. This supports GNUstep and Mac OS
1078 X (via the Cocoa libraries). The Carbon port of Emacs, which supported
1079 Mac OS X in Emacs 22, has been removed.
1081 @cindex Directory-local variables
1083 Directory-local variables can now be defined, in a similar manner to
1084 file-local variables.
1087 Transient Mark mode (@pxref{Highlighting a region}) is on by default.
1092 Other changes include: support for serial port access; D-Bus bindings; a
1093 new Visual Line mode for line-motion; improved completion; a new mode
1094 (@samp{DocView}) for viewing of PDF, PostScript, and DVI documents; nXML
1095 mode (for editing XML documents) is included; VC has been updated for
1096 newer version control systems; etc. As always, consult the @file{NEWS}
1097 file for more information.
1100 @node New in Emacs 22
1101 @section What is different about Emacs 22?
1102 @cindex Differences between Emacs 21 and Emacs 22
1103 @cindex Emacs 22, new features in
1106 @cindex GTK+ Toolkit
1107 @cindex Drag-and-drop
1109 Emacs can be built with GTK+ widgets, and supports drag-and-drop
1112 @cindex Supported systems
1114 Emacs 22 features support for GNU/Linux systems on S390 and x86-64
1115 machines, as well as support for the Mac OS X and Cygwin operating
1119 The native MS-Windows, and Mac OS X builds include full support
1120 for images, toolbar, and tooltips.
1123 Font Lock mode, Auto Compression mode, and File Name Shadow Mode are
1127 The maximum size of buffers is increased: on 32-bit machines, it is
1128 256 MBytes for Emacs 23.1, and 512 MBytes for Emacs 23.2 and above.
1131 Links can be followed with @kbd{mouse-1}, in addition to @kbd{mouse-2}.
1135 Mouse wheel support is enabled by default.
1138 Window fringes are customizable.
1141 The mode line of the selected window is now highlighted.
1144 The minibuffer prompt is displayed in a distinct face.
1147 Abbrev definitions are read automatically at startup.
1150 Grep mode is separate from Compilation mode and has many new options and
1151 commands specific to grep.
1154 The original Emacs macro system has been replaced by the new Kmacro
1155 package, which provides many new commands and features and a simple
1156 interface that uses the function keys F3 and F4. Macros are stored in a
1157 macro ring, and can be debugged and edited interactively.
1160 The Grand Unified Debugger (GUD) can be used with a full graphical user
1161 interface to GDB; this provides many features found in traditional
1162 development environments, making it easy to manipulate breakpoints, add
1163 watch points, display the call stack, etc. Breakpoints are visually
1164 indicated in the source buffer.
1168 Many new modes and packages have been included in Emacs, such as Calc,
1169 TRAMP, URL, IDO, CUA, ERC, rcirc, Table, Image-Dired, SES, Ruler, Org,
1170 PGG, Flymake, Password, Printing, Reveal, wdired, t-mouse, longlines,
1171 savehist, Conf mode, Python mode, DNS mode, etc.
1173 @cindex Multilingual Environment
1175 Leim is now part of Emacs. Unicode support has been much improved, and
1176 the following input methods have been added: belarusian, bulgarian-bds,
1177 bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian,
1178 latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard,
1179 lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345,
1180 russian-computer, sgml, slovenian, tamil-inscript, ucs,
1181 ukrainian-computer, vietnamese-telex, and welsh.
1183 The following language environments have also been added: Belarusian,
1184 Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6,
1185 Latin-7, Latvian, Lithuanian, Malayalam, Russian, Slovenian, Swedish,
1186 Tajik, Tamil, UTF-8, Ukrainian, Welsh, and Windows-1255.
1188 @cindex Documentation
1189 @cindex Emacs Lisp Manual
1191 In addition, Emacs 22 now includes the Emacs Lisp Reference Manual
1192 (@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro.
1196 @node New in Emacs 21
1197 @section What is different about Emacs 21?
1198 @cindex Differences between Emacs 20 and Emacs 21
1199 @cindex Emacs 21, new features in
1201 @cindex Variable-size fonts
1202 @cindex Toolbar support
1203 Emacs 21 features a thorough rewrite of the display engine. The new
1204 display engine supports variable-size fonts, images, and can play sounds
1205 on platforms which support that. As a result, the visual appearance of
1206 Emacs, when it runs on a windowed display, is much more reminiscent of
1207 modern GUI programs, and includes 3D widgets (used for the mode line and
1208 the scroll bars), a configurable and extensible toolbar, tooltips
1209 (a.k.a.@: balloon help), and other niceties.
1211 @cindex Colors on text-only terminals
1213 In addition, Emacs 21 supports faces on text-only terminals. This means
1214 that you can now have colors when you run Emacs on a GNU/Linux console
1215 and on @code{xterm} with @kbd{emacs -nw}.
1218 @node New in Emacs 20
1219 @section What is different about Emacs 20?
1220 @cindex Differences between Emacs 19 and Emacs 20
1221 @cindex Emacs 20, new features in
1223 The differences between Emacs versions 18 and 19 were rather dramatic;
1224 the introduction of frames, faces, and colors on windowing systems was
1225 obvious to even the most casual user.
1227 There are differences between Emacs versions 19 and 20 as well, but many
1228 are more subtle or harder to find. Among the changes are the inclusion
1229 of MULE code for languages that use non-Latin characters and for mixing
1230 several languages in the same document; the ``Customize'' facility for
1231 modifying variables without having to use Lisp; and automatic conversion
1232 of files from Macintosh, Microsoft, and Unix platforms.
1234 @c ------------------------------------------------------------
1235 @node Common requests
1236 @chapter Common requests
1237 @cindex Common requests
1240 * Setting up a customization file::
1243 * Debugging a customization file::
1244 * Displaying the current line or column::
1245 * Displaying the current file name in the titlebar::
1246 * Turning on abbrevs by default::
1247 * Associating modes with files::
1248 * Highlighting a region::
1249 * Replacing highlighted text::
1250 * Controlling case sensitivity::
1251 * Working with unprintable characters::
1252 * Searching for/replacing newlines::
1253 * Yanking text in isearch::
1254 * Wrapping words automatically::
1255 * Turning on auto-fill by default::
1256 * Changing load-path::
1257 * Using an already running Emacs process::
1258 * Compiler error messages::
1259 * Indenting switch statements::
1260 * Customizing C and C++ indentation::
1261 * Horizontal scrolling::
1263 * Turning off beeping::
1264 * Turning the volume down::
1265 * Automatic indentation::
1266 * Matching parentheses::
1267 * Hiding #ifdef lines::
1268 * Repeating commands::
1269 * Valid X resources::
1270 * Evaluating Emacs Lisp code::
1271 * Changing the length of a Tab::
1272 * Inserting text at the beginning of each line::
1273 * Forcing the cursor to remain in the same column::
1274 * Forcing Emacs to iconify itself::
1275 * Using regular expressions::
1276 * Replacing text across multiple files::
1277 * Documentation for etags::
1278 * Disabling backups::
1279 * Disabling auto-save-mode::
1280 * Going to a line by number::
1281 * Modifying pull-down menus::
1282 * Deleting menus and menu options::
1283 * Turning on syntax highlighting::
1284 * Scrolling only one line::
1285 * Editing MS-DOS files::
1286 * Filling paragraphs with a single space::
1287 * Escape sequences in shell output::
1288 * Fullscreen mode on MS-Windows::
1291 @node Setting up a customization file
1292 @section How do I set up a @file{.emacs} file properly?
1293 @cindex @file{.emacs} file, setting up
1294 @cindex @file{.emacs} file, locating
1295 @cindex Init file, setting up
1296 @cindex Customization file, setting up
1298 @inforef{Init File, Init File, emacs}.
1300 In general, new Emacs users should not be provided with @file{.emacs}
1301 files, because this can cause confusing non-standard behavior. Then
1302 they send questions to @email{help-gnu-emacs@@gnu.org} asking why Emacs
1303 isn't behaving as documented.
1305 Emacs includes the Customize facility (@pxref{Using Customize}). This
1306 allows users who are unfamiliar with Emacs Lisp to modify their
1307 @file{.emacs} files in a relatively straightforward way, using menus
1308 rather than Lisp code.
1310 While Customize might indeed make it easier to configure Emacs,
1311 consider taking a bit of time to learn Emacs Lisp and modifying your
1312 @file{.emacs} directly. Simple configuration options are described
1313 rather completely in @inforef{Init File, Init File, emacs}, for users
1314 interested in performing frequently requested, basic tasks.
1316 Sometimes users are unsure as to where their @file{.emacs} file should
1317 be found. Visiting the file as @file{~/.emacs} from Emacs will find
1320 @node Using Customize
1321 @section How do I start using Customize?
1322 @cindex Customize groups
1323 @cindex Customizing variables
1324 @cindex Customizing faces
1326 The main Customize entry point is @kbd{M-x customize @key{RET}}. This
1327 command takes you to a buffer listing all the available Customize
1328 groups. From there, you can access all customizable options and faces,
1329 change their values, and save your changes to your init file.
1330 @inforef{Easy Customization, Easy Customization, emacs}.
1332 If you know the name of the group in advance (e.g. ``shell''), use
1333 @kbd{M-x customize-group @key{RET}}.
1335 If you wish to customize a single option, use @kbd{M-x customize-option
1336 @key{RET}}. This command prompts you for the name of the option to
1337 customize, with completion.
1339 @node Colors on a TTY
1340 @section How do I get colors and syntax highlighting on a TTY?
1341 @cindex Colors on a TTY
1342 @cindex Syntax highlighting on a TTY
1343 @cindex Console, colors
1345 In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
1346 i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when
1347 invoked as @samp{emacs -nw} on X, and MS-Windows. (Colors and faces were
1348 supported in the MS-DOS port since Emacs 19.29.) Emacs automatically
1349 detects color support at startup and uses it if available. If you think
1350 that your terminal supports colors, but Emacs won't use them, check the
1351 @code{termcap} entry for your display type for color-related
1354 The command @kbd{M-x list-colors-display} pops up a window which
1355 exhibits all the colors Emacs knows about on the current display.
1357 Syntax highlighting is on by default since version 22.1.
1359 @node Debugging a customization file
1360 @section How do I debug a @file{.emacs} file?
1361 @cindex Debugging @file{.emacs} file
1362 @cindex @file{.emacs} debugging
1363 @cindex Init file debugging
1364 @cindex @samp{-debug-init} option
1366 Start Emacs with the @samp{-debug-init} command-line option. This
1367 enables the Emacs Lisp debugger before evaluating your @file{.emacs}
1368 file, and places you in the debugger if something goes wrong. The top
1369 line in the @file{trace-back} buffer will be the error message, and the
1370 second or third line of that buffer will display the Lisp code from your
1371 @file{.emacs} file that caused the problem.
1373 You can also evaluate an individual function or argument to a function
1374 in your @file{.emacs} file by moving the cursor to the end of the
1375 function or argument and typing @kbd{C-x C-e} (@kbd{M-x
1378 Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
1379 variables which you are trying to set or use.
1381 @node Displaying the current line or column
1382 @section How do I make Emacs display the current line (or column) number?
1383 @cindex @code{line-number-mode}
1384 @cindex Displaying the current line or column
1385 @cindex Line number, displaying the current
1386 @cindex Column, displaying the current
1387 @cindex @code{mode-line-format}
1389 By default, Emacs displays the current line number of the point in the
1390 mode line. You can toggle this feature off or on with the command
1391 @kbd{M-x line-number-mode}, or by setting the variable
1392 @code{line-number-mode}. Note that Emacs will not display the line
1393 number if the buffer's size in bytes is larger than the value of the
1394 variable @code{line-number-display-limit}.
1396 You can similarly display the current column with
1397 @kbd{M-x column-number-mode}, or by putting the form
1400 (setq column-number-mode t)
1404 in your @file{.emacs} file. This feature is off by default.
1406 The @code{"%c"} format specifier in the variable @code{mode-line-format}
1407 will insert the current column's value into the mode line. See the
1408 documentation for @code{mode-line-format} (using @kbd{C-h v
1409 mode-line-format @key{RET}}) for more information on how to set and use
1412 @cindex Set number capability in @code{vi} emulators
1413 The @samp{linum} package (distributed with Emacs since version 23.1)
1414 displays line numbers in the left margin, like the ``set number''
1415 capability of @code{vi}. The packages @samp{setnu} and
1416 @samp{wb-line-number} (not distributed with Emacs) also implement this
1419 @node Displaying the current file name in the titlebar
1420 @section How can I modify the titlebar to contain the current file name?
1421 @cindex Titlebar, displaying the current file name in
1422 @cindex File name, displaying in the titlebar
1423 @cindex @code{frame-title-format}
1425 The contents of an Emacs frame's titlebar is controlled by the variable
1426 @code{frame-title-format}, which has the same structure as the variable
1427 @code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x
1428 describe-variable} to get information about one or both of these
1431 By default, the titlebar for a frame does contain the name of the buffer
1432 currently being visited, except if there is a single frame. In such a
1433 case, the titlebar contains Emacs invocation name and the name of the
1434 machine at which Emacs was invoked. This is done by setting
1435 @code{frame-title-format} to the default value of
1438 (multiple-frames "%b" ("" invocation-name "@@" system-name))
1441 To modify the behavior such that frame titlebars contain the buffer's
1442 name regardless of the number of existing frames, include the following
1443 in your @file{.emacs}:
1446 (setq frame-title-format "%b")
1449 @node Turning on abbrevs by default
1450 @section How do I turn on abbrevs by default just in mode @var{mymode}?
1451 @cindex Abbrevs, turning on by default
1453 Abbrev mode expands abbreviations as you type them. To turn it on in a
1454 specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every
1455 buffer by default, put this in your @file{.emacs} file:
1458 (setq-default abbrev-mode t)
1461 @noindent To turn it on in a specific mode, use:
1464 (add-hook '@var{mymode}-mode-hook
1466 (setq abbrev-mode t)))
1469 @noindent If your Emacs version is older then 22.1, you will also need to use:
1473 (quietly-read-abbrev-file)
1477 @node Associating modes with files
1478 @section How do I make Emacs use a certain major mode for certain files?
1479 @cindex Associating modes with files
1480 @cindex File extensions and modes
1481 @cindex @code{auto-mode-alist}, modifying
1482 @cindex Modes, associating with file extensions
1484 If you want to use a certain mode @var{foo} for all files whose names end
1485 with the extension @file{.@var{bar}}, this will do it for you:
1488 (add-to-list 'auto-mode-alist '("\\.@var{bar}\\'" . @var{foo}-mode))
1491 Alternatively, put this somewhere in the first line of any file you want to
1492 edit in the mode @var{foo} (in the second line, if the first line begins
1499 @cindex Major mode for shell scripts
1500 The variable @code{interpreter-mode-alist} specifies which mode to use
1501 when loading an interpreted script (e.g. shell, python, etc.). Emacs
1502 determines which interpreter you're using by examining the first line of
1503 the script. Use @kbd{C-h v} (or @kbd{M-x describe-variable}) on
1504 @code{interpreter-mode-alist} to learn more.
1506 @node Highlighting a region
1507 @section How can I highlight a region of text in Emacs?
1508 @cindex Highlighting text
1509 @cindex Text, highlighting
1510 @cindex @code{transient-mark-mode}
1511 @cindex Region, highlighting a
1513 You can cause the region to be highlighted when the mark is active by
1517 (transient-mark-mode 1)
1521 in your @file{.emacs} file. Since Emacs 23.1, this feature is on by default.
1523 @node Replacing highlighted text
1524 @section How can I replace highlighted text with what I type?
1525 @cindex @code{delete-selection-mode}
1526 @cindex Replacing highlighted text
1527 @cindex Highlighting and replacing text
1529 Use @code{delete-selection-mode}, which you can start automatically by
1530 placing the following Lisp form in your @file{.emacs} file:
1533 (delete-selection-mode 1)
1536 According to the documentation string for @code{delete-selection-mode}
1537 (which you can read using @kbd{M-x describe-function @key{RET}
1538 delete-selection-mode @key{RET}}):
1541 When Delete Selection mode is enabled, Transient Mark mode is also
1542 enabled and typed text replaces the selection if the selection is
1543 active. Otherwise, typed text is just inserted at point regardless of
1547 This mode also allows you to delete (not kill) the highlighted region by
1550 @node Controlling case sensitivity
1551 @section How do I control Emacs's case-sensitivity when searching/replacing?
1552 @cindex @code{case-fold-search}
1553 @cindex Case sensitivity of searches
1554 @cindex Searching without case sensitivity
1555 @cindex Ignoring case in searches
1558 The value of the variable @code{case-fold-search} determines whether
1559 searches are case sensitive:
1562 (setq case-fold-search nil) ; make searches case sensitive
1563 (setq case-fold-search t) ; make searches case insensitive
1566 @cindex Case sensitivity in replacements
1567 @cindex Replacing, and case sensitivity
1568 @cindex @code{case-replace}
1569 Similarly, for replacing, the variable @code{case-replace} determines
1570 whether replacements preserve case.
1572 You can also toggle case sensitivity at will in isearch with @kbd{M-c}.
1574 To change the case sensitivity just for one major mode, use the major
1575 mode's hook. For example:
1578 (add-hook '@var{foo}-mode-hook
1580 (setq case-fold-search nil)))
1583 @node Working with unprintable characters
1584 @section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
1585 @cindex Unprintable characters, working with
1586 @cindex Working with unprintable characters
1587 @cindex Control characters, working with
1588 @cindex Eight-bit characters, working with
1589 @cindex Searching for unprintable characters
1590 @cindex Regexps and unprintable characters
1592 To search for a single character that appears in the buffer as, for
1593 example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}.
1594 Searching for @strong{all} unprintable characters is best done with a
1595 regular expression (@dfn{regexp}) search. The easiest regexp to use for
1596 the unprintable chars is the complement of the regexp for the printable
1602 Regexp for the printable chars: @samp{[\t\n\r\f -~]}
1605 Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
1609 To type these special characters in an interactive argument to
1610 @code{isearch-forward-regexp} or @code{re-search-forward}, you need to
1611 use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
1612 respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So,
1613 to search for unprintable characters using @code{re-search-forward}:
1615 @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}}
1617 Using @code{isearch-forward-regexp}:
1619 @kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
1621 To delete all unprintable characters, simply use replace-regexp:
1623 @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}}
1625 Replacing is similar to the above. To replace all unprintable
1626 characters with a colon, use:
1628 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}
1630 @node Searching for/replacing newlines
1631 @section How do I input a newline character in isearch or query-replace?
1632 @cindex Searching for newlines
1633 @cindex Replacing newlines
1635 Use @kbd{C-q C-j}. For more information, see @inforef{Special Isearch,
1636 Special Input for Incremental Search, emacs}.
1639 @node Yanking text in isearch
1640 @section How do I copy text from the kill ring into the search string?
1641 @cindex Yanking text into the search string
1642 @cindex isearch yanking
1644 Use @kbd{M-y}. @inforef{Isearch Yank, Isearch Yanking, emacs}.
1646 @node Wrapping words automatically
1647 @section How do I make Emacs wrap words for me?
1648 @cindex Wrapping word automatically
1649 @cindex Wrapping lines
1651 @cindex @code{auto-fill-mode}, introduction to
1652 @cindex Maximum line width, default value
1653 @cindex @code{fill-column}, default value
1655 Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
1656 The default maximum line width is 70, determined by the variable
1657 @code{fill-column}. To learn how to turn this on automatically, see
1658 @ref{Turning on auto-fill by default}.
1660 @node Turning on auto-fill by default
1661 @section How do I turn on @code{auto-fill-mode} by default?
1662 @cindex @code{auto-fill-mode}, activating automatically
1663 @cindex Filling automatically
1664 @cindex Automatic entry to @code{auto-fill-mode}
1666 To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
1669 To turn it on for every buffer in a certain mode, you must use the hook
1670 for that mode. For example, to turn on @code{auto-fill} mode for all
1671 text buffers, including the following in your @file{.emacs} file:
1674 (add-hook 'text-mode-hook 'turn-on-auto-fill)
1677 If you want @code{auto-fill} mode on in all major modes, do this:
1680 (setq-default auto-fill-function 'do-auto-fill)
1683 @node Changing load-path
1684 @section How do I change @code{load-path}?
1685 @cindex @code{load-path}, modifying
1686 @cindex Modifying @code{load-path}
1687 @cindex Adding to @code{load-path}
1689 In general, you should only add to the @code{load-path}. You can add
1690 directory @var{/dir/subdir} to the load path like this:
1693 (add-to-list 'load-path "/dir/subdir/")
1696 To do this relative to your home directory:
1699 (add-to-list 'load-path "~/mysubdir/")
1702 @node Using an already running Emacs process
1703 @section How do I use an already running Emacs from another window?
1704 @cindex @code{emacsclient}
1705 @cindex Emacs server functions
1706 @cindex Using an existing Emacs process
1708 @code{emacsclient}, which comes with Emacs, is for editing a file using
1709 an already running Emacs rather than starting up a new Emacs. It does
1710 this by sending a request to the already running Emacs, which must be
1711 expecting the request.
1718 Emacs must have executed the @code{server-start} function for
1719 @samp{emacsclient} to work. This can be done either by a command line
1723 emacs -f server-start
1726 or by invoking @code{server-start} from @file{.emacs}:
1729 (if (@var{some conditions are met}) (server-start))
1732 When this is done, Emacs creates a Unix domain socket named
1733 @file{server} in @file{/tmp/emacs@var{userid}}. See
1734 @code{server-socket-dir}.
1736 To get your news reader, mail reader, etc., to invoke
1737 @samp{emacsclient}, try setting the environment variable @code{EDITOR}
1738 (or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may
1739 have to specify the full pathname of the @samp{emacsclient} program
1744 setenv EDITOR emacsclient
1746 # using full pathname
1747 setenv EDITOR /usr/local/emacs/etc/emacsclient
1750 EDITOR=emacsclient ; export EDITOR
1756 When @samp{emacsclient} is run, it connects to the socket and passes its
1757 command line options to Emacs, which at the next opportunity will visit
1758 the files specified. (Line numbers can be specified just like with
1759 Emacs.) The user will have to switch to the Emacs window by hand. When
1760 the user is done editing a file, the user can type @kbd{C-x #} (or
1761 @kbd{M-x server-edit}) to indicate this. If there is another buffer
1762 requested by @code{emacsclient}, Emacs will switch to it; otherwise
1763 @code{emacsclient} will exit, signaling the calling program to continue.
1765 @cindex @code{gnuserv}
1766 There is an alternative version of @samp{emacsclient} called
1767 @samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman}
1768 (@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses
1769 Internet domain sockets, so it can work across most network connections.
1771 The most recent @samp{gnuserv} package is available at
1773 @uref{http://meltin.net/hacks/emacs/}
1777 @node Compiler error messages
1778 @section How do I make Emacs recognize my compiler's funny error messages?
1779 @cindex Compiler error messages, recognizing
1780 @cindex Recognizing non-standard compiler errors
1781 @cindex Regexps for recognizing compiler errors
1782 @cindex Errors, recognizing compiler
1784 Customize the @code{compilation-error-regexp-alist} variable.
1786 @node Indenting switch statements
1787 @section How do I change the indentation for @code{switch}?
1788 @cindex @code{switch}, indenting
1789 @cindex Indenting of @code{switch}
1791 Many people want to indent their @code{switch} statements like this:
1809 @noindent To achieve this, add the following line to your @file{.emacs}:
1812 (c-set-offset 'case-label '+)
1815 @node Customizing C and C++ indentation
1816 @section How to customize indentation in C, C@t{++}, and Java buffers?
1817 @cindex Indentation, how to customize
1818 @cindex Customize indentation
1820 The Emacs @code{cc-mode} features an interactive procedure for
1821 customizing the indentation style, which is fully explained in the
1822 @cite{CC Mode} manual that is part of the Emacs distribution, see
1823 @ref{Customizing Indentation, , Customization Indentation, ccmode,
1824 The CC Mode Manual}. Here's a short summary of the procedure:
1828 Go to the beginning of the first line where you don't like the
1829 indentation and type @kbd{C-c C-o}. Emacs will prompt you for the
1830 syntactic symbol; type @key{RET} to accept the default it suggests.
1833 Emacs now prompts for the offset of this syntactic symbol, showing the
1834 default (the current definition) inside parentheses. You can choose
1839 No extra indentation.
1841 Indent one basic offset.
1843 Outdent one basic offset.
1845 Indent two basic offsets
1847 Outdent two basic offsets.
1849 Indent half basic offset.
1851 Outdent half basic offset.
1855 After choosing one of these symbols, type @kbd{C-c C-q} to reindent
1856 the line or the block according to what you just specified.
1859 If you don't like the result, go back to step 1. Otherwise, add the
1860 following line to your @file{.emacs}:
1863 (c-set-offset '@var{syntactic-symbol} @var{offset})
1867 where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
1868 when you type @kbd{C-c C-o} at the beginning of the line, and
1869 @var{offset} is one of the indentation symbols listed above (@code{+},
1870 @code{/}, @code{0}, etc.) that you've chosen during the interactive
1874 Go to the next line whose indentation is not to your liking and repeat
1878 It is recommended to put all the resulting @code{(c-set-offset ...)}
1879 customizations inside a C mode hook, like this:
1882 (defun my-c-mode-hook ()
1885 (add-hook 'c-mode-hook 'my-c-mode-hook)
1889 Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
1890 'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
1891 might be unavailable when @code{cc-mode} is not loaded.
1893 Note that @code{c-mode-hook} runs for C source files only; use
1894 @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
1895 Java sources, etc. If you want the same customizations to be in
1896 effect in @emph{all} languages supported by @code{cc-mode}, use
1897 @code{c-mode-common-hook}.
1899 @node Horizontal scrolling
1900 @section How can I make Emacs automatically scroll horizontally?
1901 @cindex @code{hscroll-mode}
1902 @cindex Horizontal scrolling
1903 @cindex Scrolling horizontally
1905 In Emacs 21 and later, this is on by default: if the variable
1906 @code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
1907 automatically scrolls the display horizontally when point moves off the
1908 left or right edge of the window.
1910 Note that this is overridden by the variable
1911 @code{truncate-partial-width-windows} if that variable is non-nil
1912 and the current buffer is not full-frame width.
1914 In Emacs 20, use @code{hscroll-mode}.
1916 @node Overwrite mode
1917 @section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
1918 @cindex @key{Insert}
1919 @cindex @code{overwrite-mode}
1920 @cindex Overwriting existing text
1921 @cindex Toggling @code{overwrite-mode}
1923 @kbd{M-x overwrite-mode} (a minor mode). This toggles
1924 @code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
1925 is as easy as another @kbd{M-x overwrite-mode}.
1927 On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
1929 @node Turning off beeping
1930 @section How do I stop Emacs from beeping on a terminal?
1931 @cindex Beeping, turning off
1932 @cindex Visible bell
1933 @cindex Bell, visible
1935 @email{martin@@cc.gatech.edu, Martin R. Frank} writes:
1937 Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
1938 and set the visible bell to nothing.
1940 That is, put the following in your @code{TERMCAP} environment variable
1941 (assuming you have one):
1947 And evaluate the following Lisp form:
1950 (setq visible-bell t)
1953 @node Turning the volume down
1954 @section How do I turn down the bell volume in Emacs running under X?
1955 @cindex Bell, volume of
1956 @cindex Volume of bell
1958 On X Window system, you can adjust the bell volume and duration for all
1959 programs with the shell command @code{xset}.
1961 Invoking @code{xset} without any arguments produces some basic
1962 information, including the following:
1965 usage: xset [-display host:dpy] option ...
1968 To set bell volume, pitch and duration:
1969 b [vol [pitch [dur]]] b on
1972 @node Automatic indentation
1973 @section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
1974 @cindex Indenting new lines
1975 @cindex New lines, indenting of
1976 @cindex Previous line, indenting according to
1977 @cindex Text indentation
1979 Such behavior is automatic (in Text mode) in Emacs 20 and later. From the
1980 @file{etc/NEWS} file for Emacs 20.2:
1983 ** In Text mode, now only blank lines separate paragraphs. This makes
1984 it possible to get the full benefit of Adaptive Fill mode in Text mode,
1985 and other modes derived from it (such as Mail mode). @key{TAB} in Text
1986 mode now runs the command @code{indent-relative}; this makes a practical
1987 difference only when you use indented paragraphs.
1989 If you want spaces at the beginning of a line to start a paragraph, use
1990 the new mode, Paragraph Indent Text mode.
1993 @cindex Prefixing lines
1995 If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
1996 by default}), you can tell Emacs to prefix every line with a certain
1997 character sequence, the @dfn{fill prefix}. Type the prefix at the
1998 beginning of a line, position point after it, and then type @kbd{C-x .}
1999 (@code{set-fill-prefix}) to set the fill prefix. Thereafter,
2000 auto-filling will automatically put the fill prefix at the beginning of
2001 new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
2002 prefix when refilling the paragraph.
2004 If you have paragraphs with different levels of indentation, you will
2005 have to set the fill prefix to the correct value each time you move to a
2006 new paragraph. There are many packages available to deal with this
2007 (@pxref{Packages that do not come with Emacs}). Look for ``fill'' and
2008 ``indent'' keywords for guidance.
2010 @node Matching parentheses
2011 @section How do I show which parenthesis matches the one I'm looking at?
2012 @cindex Parentheses, matching
2013 @cindex @file{paren.el}
2014 @cindex Highlighting matching parentheses
2015 @cindex Pairs of parentheses, highlighting
2016 @cindex Matching parentheses
2018 Call @code{show-paren-mode} in your @file{.emacs} file:
2024 You can also enable this mode by selecting the @samp{Paren Match
2025 Highlighting} option from the @samp{Options} menu of the Emacs menu bar
2026 at the top of any Emacs frame.
2028 Alternatives to this mode include:
2033 If you're looking at a right parenthesis (or brace or bracket) you can
2034 delete it and reinsert it. Emacs will momentarily move the cursor to
2035 the matching parenthesis.
2038 @kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
2039 will skip over one set of balanced parentheses, so you can see which
2040 parentheses match. (You can train it to skip over balanced brackets
2041 and braces at the same time by modifying the syntax table.)
2043 @cindex Show matching paren as in @code{vi}
2045 Here is some Emacs Lisp that will make the @key{%} key show the matching
2046 parenthesis, like in @code{vi}. In addition, if the cursor isn't over a
2047 parenthesis, it simply inserts a % like normal.
2050 ;; By an unknown contributor
2052 (global-set-key "%" 'match-paren)
2054 (defun match-paren (arg)
2055 "Go to the matching paren if on a paren; otherwise insert %."
2057 (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
2058 ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
2059 (t (self-insert-command (or arg 1)))))
2064 @node Hiding #ifdef lines
2065 @section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
2066 @cindex @code{#ifdef}, selective display of
2067 @cindex @code{hide-ifdef-mode}
2068 @cindex Hiding @code{#ifdef} text
2069 @cindex Selectively displaying @code{#ifdef} code
2071 @kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want
2072 to investigate @file{cpp.el}, which is distributed with Emacs.
2074 @node Repeating commands
2075 @section How do I repeat a command as many times as possible?
2076 @cindex Repeating commands many times
2077 @cindex Commands, repeating many times
2078 @cindex @code{.}, equivalent to @code{vi} command
2080 As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
2081 that repeats the last command. If you preface it with a prefix
2082 argument, the prefix arg is applied to the command.
2084 You can also type @kbd{C-x @key{ESC} @key{ESC}}
2085 (@code{repeat-complex-command}) to reinvoke commands that used the
2086 minibuffer to get arguments. In @code{repeat-complex-command} you can
2087 type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
2088 keyboard has these keys) to scan through all the different complex
2089 commands you've typed.
2091 To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and
2092 @kbd{C-x )} to make a keyboard macro that invokes the command and then
2093 type @kbd{C-x e}. (@inforef{Keyboard Macros, Keyboard Macros, emacs}.)
2095 If you're really desperate for the @code{.} command in @code{vi} that
2096 redoes the last insertion/deletion, use VIPER, a @code{vi} emulation
2097 mode which comes with Emacs, and which appears to support it.
2099 @node Valid X resources
2100 @section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
2101 @cindex Resources, X
2103 @cindex Setting X resources
2105 @inforef{X Resources, X Resources, emacs}.
2107 You can also use a resource editor, such as editres (for X11R5 and
2108 onwards), to look at the resource names for the menu bar, assuming Emacs
2109 was compiled with the X toolkit.
2111 @node Evaluating Emacs Lisp code
2112 @section How do I execute (``evaluate'') a piece of Emacs Lisp code?
2113 @cindex Evaluating Lisp code
2114 @cindex Lisp forms, evaluating
2116 There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
2117 Emacs Lisp @dfn{form}:
2122 If you want it evaluated every time you run Emacs, put it in a file
2123 named @file{.emacs} in your home directory. This is known as ``your
2124 @file{.emacs} file,'' and contains all of your personal customizations.
2127 You can type the form in the @file{*scratch*} buffer, and then type
2128 @key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form
2129 will be inserted in the buffer.
2132 In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
2133 before or around point.
2136 Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
2137 before point and prints its value in the echo area.
2140 Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
2141 form in the minibuffer which will be evaluated once you press @key{RET}.
2144 You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
2145 forms in a file. (To do this from Lisp use the function @code{load}
2148 The functions @code{load-library}, @code{eval-region},
2149 @code{eval-buffer}, @code{require}, and @code{autoload} are also
2150 useful; see @ref{Emacs Lisp documentation}, if you want to learn more
2155 @node Changing the length of a Tab
2156 @section How do I change Emacs's idea of the @key{TAB} character's length?
2158 @cindex Length of tab character
2160 Set the default value of the variable @code{tab-width}. For example, to set
2161 @key{TAB} stops every 10 characters, insert the following in your
2165 (setq-default tab-width 10)
2168 Do not confuse variable @code{tab-width} with variable
2169 @code{tab-stop-list}. The former is used for the display of literal
2170 @key{TAB} characters. The latter controls what characters are inserted
2171 when you press the @key{TAB} character in certain modes.
2173 @node Inserting text at the beginning of each line
2174 @section How do I insert <some text> at the beginning of every line?
2175 @cindex Prefixing a region with some text
2176 @cindex Prefix character, inserting in mail/news replies
2177 @cindex Replies to mail/news, inserting a prefix character
2178 @cindex @code{mail-yank-prefix}
2179 @cindex Mail replies, inserting a prefix character
2180 @cindex News replies, inserting a prefix character
2182 To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
2183 @key{RET} ^ @key{RET} your text @key{RET}}.
2185 To do this to a region, use @code{string-insert-rectangle}.
2186 Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
2187 want to prefix, move the cursor to last line to be prefixed, and type
2188 @kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole
2189 buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
2191 If you are trying to prefix a yanked mail message with @samp{>}, you
2192 might want to set the variable @code{mail-yank-prefix}. In Message
2193 buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;}
2194 runs the function @code{comment-region}, it is a general-purpose
2195 mechanism to comment regions) (@pxref{Changing the included text prefix}).
2197 @node Forcing the cursor to remain in the same column
2198 @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?
2199 @cindex @code{picture-mode}
2200 @cindex Remaining in the same column, regardless of contents
2201 @cindex Vertical movement in empty documents
2203 Use @kbd{M-x picture-mode}.
2205 See also the variable @code{track-eol} and the command
2206 @code{set-goal-column} bound to @kbd{C-x C-n}
2207 (@pxref{Moving Point, , , emacs, The GNU Emacs Manual}).
2209 @node Forcing Emacs to iconify itself
2210 @section How do I tell Emacs to iconify itself?
2211 @cindex Iconification under the X Window System
2212 @cindex X Window System and iconification
2213 @cindex Suspending Emacs
2215 @kbd{C-z} iconifies Emacs when running under X and suspends Emacs
2216 otherwise. @inforef{Frame Commands, Frame Commands, emacs}.
2218 @node Using regular expressions
2219 @section How do I use regexps (regular expressions) in Emacs?
2221 @cindex Regular expressions
2222 @cindex Differences between Unix and Emacs regexps
2223 @cindex Unix regexps, differences from Emacs
2224 @cindex Text strings, putting regexps in
2226 @inforef{Regexp Backslash, Regexp Backslash, emacs}.
2228 The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
2229 are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is
2230 @samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)}
2231 in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
2233 Note the doubled backslashes!
2238 Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
2239 (@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@:
2240 @kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
2241 characters not to match.
2244 The character syntax regexps (e.g., @samp{\sw}) are not
2245 meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This
2246 is actually typical for regexp syntax.)
2250 @node Replacing text across multiple files
2251 @section How do I perform a replace operation across more than one file?
2252 @cindex Replacing strings across files
2253 @cindex Multiple files, replacing across
2254 @cindex Files, replacing strings across multiple
2255 @cindex Recursive search/replace operations
2257 Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x d}) supports the
2258 command @code{dired-do-query-replace-regexp} (@kbd{Q}), which allows
2259 users to replace regular expressions in multiple files.
2261 You can use this command to perform search/replace operations on
2262 multiple files by following the following steps:
2266 Assemble a list of files you want to operate on with either
2267 @code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}.
2270 Mark all files in the resulting Dired buffer using @kbd{t}.
2273 Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked
2277 To accept all replacements in each file, hit @kbd{!}.
2280 Another way to do the same thing is to use the ``tags'' feature of
2281 Emacs: it includes the command @code{tags-query-replace} which performs
2282 a query-replace across all the files mentioned in the @file{TAGS} file.
2283 @inforef{Tags Search, Tags Search, emacs}.
2285 @node Documentation for etags
2286 @section Where is the documentation for @code{etags}?
2287 @cindex Documentation for @code{etags}
2288 @cindex @code{etags}, documentation for
2290 The @code{etags} man page should be in the same place as the
2291 @code{emacs} man page.
2293 Quick command-line switch descriptions are also available. For example,
2296 @node Disabling backups
2297 @section How do I disable backup files?
2298 @cindex Backups, disabling
2299 @cindex Disabling backups
2301 You probably don't want to do this, since backups are useful, especially
2302 when something goes wrong.
2304 To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
2305 load @code{dired-x} by adding the following to your @file{.emacs} file:
2308 (add-hook 'dired-load-hook
2310 (require 'dired-x)))
2313 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
2314 You can make omitting the default for new dired buffers by putting the
2315 following in your @file{.emacs}:
2318 (add-hook 'dired-mode-hook 'dired-omit-toggle)
2321 If you're tired of seeing backup files whenever you do an @samp{ls} at
2322 the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU
2323 @code{ls} is part of the GNU Fileutils package, available from
2324 @samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
2326 To disable or change the way backups are made, @inforef{Backup Names, ,
2329 @cindex Backup files in a single directory
2330 Beginning with Emacs 21.1, you can control where Emacs puts backup files
2331 by customizing the variable @code{backup-directory-alist}. This
2332 variable's value specifies that files whose names match specific patters
2333 should have their backups put in certain directories. A typical use is
2334 to add the element @code{("." . @var{dir})} to force Emacs to put
2335 @strong{all} backup files in the directory @file{dir}.
2337 @node Disabling auto-save-mode
2338 @section How do I disable @code{auto-save-mode}?
2339 @cindex Disabling @code{auto-save-mode}
2341 @cindex Saving at frequent intervals
2343 You probably don't want to do this, since auto-saving is useful,
2344 especially when Emacs or your computer crashes while you are editing a
2347 Instead, you might want to change the variable
2348 @code{auto-save-interval}, which specifies how many keystrokes Emacs
2349 waits before auto-saving. Increasing this value forces Emacs to wait
2350 longer between auto-saves, which might annoy you less.
2352 You might also want to look into Sebastian Kremer's @code{auto-save}
2353 package (@pxref{Packages that do not come with Emacs}). This
2354 package also allows you to place all auto-save files in one directory,
2355 such as @file{/tmp}.
2357 To disable or change how @code{auto-save-mode} works, @inforef{Auto
2360 @node Going to a line by number
2361 @section How can I go to a certain line given its number?
2362 @cindex Going to a line by number
2363 @cindex Compilation error messages
2364 @cindex Recompilation
2366 Are you sure you indeed need to go to a line by its number? Perhaps all
2367 you want is to display a line in your source file for which a compiler
2368 printed an error message? If so, compiling from within Emacs using the
2369 @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
2370 effective way of doing that. Emacs automatically intercepts the compile
2371 error messages, inserts them into a special buffer called
2372 @code{*compilation*}, and lets you visit the locus of each message in
2373 the source. Type @kbd{C-x `} to step through the offending lines one by
2374 one (starting with Emacs 22, you can also use @kbd{M-g M-p} and
2375 @kbd{M-g M-n} to go to the previous and next matches directly). Click
2376 @kbd{Mouse-2} or press @key{RET} on a message text in the
2377 @code{*compilation*} buffer to go to the line whose number is mentioned
2380 But if you indeed need to go to a certain text line, type @kbd{M-g M-g}
2381 (which is the default binding of the @code{goto-line} function starting
2382 with Emacs 22). Emacs will prompt you for the number of the line and go
2385 You can do this faster by invoking @code{goto-line} with a numeric
2386 argument that is the line's number. For example, @kbd{C-u 286 M-g M-g}
2387 will jump to line number 286 in the current buffer.
2389 @node Modifying pull-down menus
2390 @section How can I create or modify new pull-down menu options?
2391 @cindex Pull-down menus, creating or modifying
2392 @cindex Menus, creating or modifying
2393 @cindex Creating new menu options
2394 @cindex Modifying pull-down menus
2395 @cindex Menus and keymaps
2396 @cindex Keymaps and menus
2398 Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
2399 represents a local or global keymap. Selecting a menu title with the
2400 mouse displays that keymap's non-@code{nil} contents in the form of a menu.
2402 So to add a menu option to an existing menu, all you have to do is add a
2403 new definition to the appropriate keymap. Adding a @samp{Forward Word}
2404 item to the @samp{Edit} menu thus requires the following Lisp code:
2407 (define-key global-map
2408 [menu-bar edit forward]
2409 '("Forward word" . forward-word))
2413 The first line adds the entry to the global keymap, which includes
2414 global menu bar entries. Replacing the reference to @code{global-map}
2415 with a local keymap would add this menu option only within a particular
2418 The second line describes the path from the menu-bar to the new entry.
2419 Placing this menu entry underneath the @samp{File} menu would mean
2420 changing the word @code{edit} in the second line to @code{file}.
2422 The third line is a cons cell whose first element is the title that will
2423 be displayed, and whose second element is the function that will be
2424 called when that menu option is invoked.
2426 To add a new menu, rather than a new option to an existing menu, we must
2427 define an entirely new keymap:
2430 (define-key global-map [menu-bar words]
2431 (cons "Words" (make-sparse-keymap "Words")))
2434 The above code creates a new sparse keymap, gives it the name
2435 @samp{Words}, and attaches it to the global menu bar. Adding the
2436 @samp{Forward Word} item to this new menu would thus require the
2440 (define-key global-map
2441 [menu-bar words forward]
2442 '("Forward word" . forward-word))
2446 Note that because of the way keymaps work, menu options are displayed
2447 with the more recently defined items at the top. Thus if you were to
2448 define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
2449 order), the menu option @samp{baz} would appear at the top, and
2450 @samp{foo} would be at the bottom.
2452 One way to avoid this problem is to use the function @code{define-key-after},
2453 which works the same as @code{define-key}, but lets you modify where items
2454 appear. The following Lisp code would insert the @samp{Forward Word}
2455 item in the @samp{Edit} menu immediately following the @samp{Undo} item:
2459 (lookup-key global-map [menu-bar edit])
2461 '("Forward word" . forward-word)
2465 Note how the second and third arguments to @code{define-key-after} are
2466 different from those of @code{define-key}, and that we have added a new
2467 (final) argument, the function after which our new key should be
2470 To move a menu option from one position to another, simply evaluate
2471 @code{define-key-after} with the appropriate final argument.
2473 More detailed information---and more examples of how to create and
2474 modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
2475 ``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on
2478 @node Deleting menus and menu options
2479 @section How do I delete menus and menu options?
2480 @cindex Deleting menus and menu options
2481 @cindex Menus, deleting
2483 The simplest way to remove a menu is to set its keymap to @samp{nil}.
2484 For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
2488 (define-key global-map [menu-bar words] nil)
2491 Similarly, removing a menu option requires redefining a keymap entry to
2492 @code{nil}. For example, to delete the @samp{Forward word} menu option
2493 from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
2497 (define-key global-map [menu-bar edit forward] nil)
2500 @node Turning on syntax highlighting
2501 @section How do I turn on syntax highlighting?
2502 @cindex Syntax highlighting
2503 @cindex @code{font-lock-mode}
2504 @cindex Highlighting based on syntax
2505 @cindex Colorizing text
2506 @cindex FAQ, @code{font-lock-mode}
2508 @code{font-lock-mode} is the standard way to have Emacs perform syntax
2509 highlighting in the current buffer. It is enabled by default in Emacs
2512 With @code{font-lock-mode} turned on, different types of text will
2513 appear in different colors. For instance, in a programming mode,
2514 variables will appear in one face, keywords in a second, and comments in
2517 To turn @code{font-lock-mode} off within an existing buffer, use
2518 @kbd{M-x font-lock-mode @key{RET}}.
2520 In Emacs 21 and earlier versions, you could use the following code in
2521 your @file{.emacs} file to turn on @code{font-lock-mode} globally:
2524 (global-font-lock-mode 1)
2527 Highlighting a buffer with @code{font-lock-mode} can take quite a while,
2528 and cause an annoying delay in display, so several features exist to
2531 @cindex Just-In-Time syntax highlighting
2532 In Emacs 21 and later, turning on @code{font-lock-mode} automatically
2533 activates the new @dfn{Just-In-Time fontification} provided by
2534 @code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
2535 portions of buffer until you actually need to see them, and can also
2536 fontify while Emacs is idle. This makes display of the visible portion
2537 of a buffer almost instantaneous. For details about customizing
2538 @code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
2540 @cindex Levels of syntax highlighting
2541 @cindex Decoration level, in @code{font-lock-mode}
2542 In versions of Emacs before 21, different levels of decoration are
2543 available, from slight to gaudy. More decoration means you need to wait
2544 more time for a buffer to be fontified (or a faster machine). To
2545 control how decorated your buffers should become, set the value of
2546 @code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
2547 @code{nil} value indicating default (usually minimum) decoration, and a
2548 @code{t} value indicating the maximum decoration. For the gaudiest
2549 possible look, then, include the line
2552 (setq font-lock-maximum-decoration t)
2556 in your @file{.emacs} file. You can also set this variable such that
2557 different modes are highlighted in a different ways; for more
2558 information, see the documentation for
2559 @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
2560 describe-variable @key{RET}}).
2562 Also see the documentation for the function @code{font-lock-mode},
2563 available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
2564 describe-function @key{RET} font-lock-mode @key{RET}}).
2566 To print buffers with the faces (i.e., colors and fonts) intact, use
2567 @kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
2568 ps-print-region-with-faces}. You will need a way to send text to a
2569 PostScript printer, or a PostScript interpreter such as Ghostscript;
2570 consult the documentation of the variables @code{ps-printer-name},
2571 @code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
2573 @node Scrolling only one line
2574 @section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
2575 @cindex Scrolling only one line
2576 @cindex Reducing the increment when scrolling
2578 Customize the @code{scroll-conservatively} variable with @kbd{M-x
2579 customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
2580 to a large value like, say, 10000. For an explanation of what this
2581 means, @inforef{Auto Scrolling, Auto Scrolling, emacs}.
2583 Alternatively, use the following Lisp form in your @file{.emacs}:
2586 (setq scroll-conservatively most-positive-fixnum)
2589 @node Editing MS-DOS files
2590 @section How can I edit MS-DOS files using Emacs?
2591 @cindex Editing MS-DOS files
2592 @cindex MS-DOS files, editing
2593 @cindex Microsoft files, editing
2594 @cindex Windows files, editing
2596 As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
2597 performed transparently. You can open MS-DOS files on a Unix system,
2598 edit it, and save it without having to worry about the file format.
2600 When editing an MS-DOS style file, the mode line will indicate that it
2601 is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh,
2602 the string @samp{(DOS)} will appear near the left edge of the mode line;
2603 on DOS and Windows, where the DOS end-of-line (EOL) format is the
2604 default, a backslash (@samp{\}) will appear in the mode line.
2606 @node Filling paragraphs with a single space
2607 @section How can I tell Emacs to fill paragraphs with a single space after each period?
2608 @cindex One space following periods
2609 @cindex Single space following periods
2610 @cindex Periods, one space following
2612 Add the following line to your @file{.emacs} file:
2615 (setq sentence-end-double-space nil)
2618 @node Escape sequences in shell output
2619 @section Why these strange escape sequences from @code{ls} from the Shell mode?
2620 @cindex Escape sequences in @code{ls} output
2621 @cindex @code{ls} in Shell mode
2623 This happens because @code{ls} is aliased to @samp{ls --color} in your
2624 shell init file. You have two alternatives to solve this:
2628 Make the alias conditioned on the @code{EMACS} variable in the
2629 environment. When Emacs runs a subsidiary shell, it exports the
2630 @code{EMACS} variable to that shell, with value equal to the absolute
2631 file name of Emacs. You can
2632 unalias @code{ls} when that happens, thus limiting the alias to your
2633 interactive sessions.
2636 Install the @code{ansi-color} package (bundled with Emacs 21.1 and
2637 later), which converts these ANSI escape sequences into colors.
2640 @node Fullscreen mode on MS-Windows
2641 @section How can I start Emacs in fullscreen mode on MS-Windows?
2642 @cindex Maximize frame
2643 @cindex Fullscreen mode
2645 Use the function @code{w32-send-sys-command}. For example, you can
2646 put the following in your @file{.emacs} file:
2649 (add-hook 'term-setup-hook
2650 #'(lambda () (w32-send-sys-command ?\xF030)))
2653 To avoid the slightly distracting visual effect of Emacs starting with
2654 its default frame size and then growing to fullscreen, you can add an
2655 @samp{Emacs.Geometry} entry to the Windows registry settings (see
2656 @pxref{(emacs)X Resources}).
2658 To compute the correct values for width and height, first maximize the
2659 Emacs frame and then evaluate @code{(frame-height)} and
2660 @code{(frame-width)} with @kbd{M-:}.
2662 @c ------------------------------------------------------------
2663 @node Bugs and problems
2664 @chapter Bugs and problems
2665 @cindex Bugs and problems
2667 The Emacs manual lists some common kinds of trouble users could get
2668 into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
2669 Emacs Manual}, so you might look there if the problem you encounter
2670 isn't described in this chapter. If you decide you've discovered a bug,
2671 see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
2672 instructions how to do that.
2674 The file @file{etc/PROBLEMS} in the Emacs distribution lists various
2675 known problems with building and using Emacs on specific platforms;
2676 type @kbd{C-h C-p} to read it.
2679 * Problems with very large files::
2680 * ^M in the shell buffer::
2681 * Problems with Shell Mode::
2682 * Termcap/Terminfo entries for Emacs::
2683 * Errors with init files::
2684 * Emacs ignores X resources::
2685 * Emacs ignores frame parameters::
2686 * Editing files with $ in the name::
2687 * Shell mode loses the current directory::
2688 * Security risks with Emacs::
2689 * Dired claims that no file is on this line::
2692 @node Problems with very large files
2693 @section Does Emacs have problems with files larger than 8 megabytes?
2694 @cindex Very large files, opening
2695 @cindex Large files, opening
2696 @cindex Opening very large files
2697 @cindex Maximum file size
2698 @cindex Files, maximum size
2700 Old versions (i.e., anything before 19.29) of Emacs had problems editing
2701 files larger than 8 megabytes. In versions 19.29 and later, the maximum
2702 buffer size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes.
2703 The maximum buffer size on 32-bit machines increased to 256 MBytes in
2704 Emacs 22, and again to 512 MBytes in Emacs 23.2.
2706 Emacs compiled on a 64-bit machine can handle much larger buffers.
2708 @node ^M in the shell buffer
2709 @section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
2710 @cindex Shell buffer, echoed commands and @samp{^M} in
2711 @cindex Echoed commands in @code{shell-mode}
2713 Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
2714 make them go away. If that doesn't work, you have several options:
2716 For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
2721 if ("$EMACS" =~ /*) then
2722 if ($?tcsh) unset edit
2728 Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file:
2735 Alternatively, use @code{csh} in your shell buffers instead of
2736 @code{tcsh}. One way is:
2739 (setq explicit-shell-file-name "/bin/csh")
2743 and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
2747 setenv ESHELL /bin/csh
2751 (You must start Emacs over again with the environment variable properly
2752 set for this to take effect.)
2754 You can also set the @code{ESHELL} environment variable in Emacs Lisp
2755 with the following Lisp form,
2758 (setenv "ESHELL" "/bin/csh")
2761 The above solutions try to prevent the shell from producing the
2762 @samp{^M} characters in the first place. If this is not possible
2763 (e.g., if you use a Windows shell), you can get Emacs to remove these
2764 characters from the buffer by adding this to your @file{.emacs} init
2768 (add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
2771 On a related note: if your shell is echoing your input line in the shell
2772 buffer, you might want to customize the @code{comint-process-echoes}
2773 variable in your shell buffers, or try the following command in your
2774 shell start-up file:
2777 stty -icrnl -onlcr -echo susp ^Z
2780 @node Problems with Shell Mode
2781 @section Why do I get an error message when I try to run @kbd{M-x shell}?
2783 @cindex Shell Mode, problems
2784 @cindex @code{explicit-shell-file-name}
2785 This might happen because Emacs tries to look for the shell in a wrong
2786 place. If you know where your shell executable is, set the variable
2787 @code{explicit-shell-file-name} in your @file{.emacs} file to point to
2790 @cindex Antivirus programs, and Shell Mode
2791 Some people have trouble with Shell Mode on MS-Windows because of
2792 intrusive antivirus software; disabling the resident antivirus program
2793 solves the problems in those cases.
2795 @node Termcap/Terminfo entries for Emacs
2796 @section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
2799 @cindex Emacs entries for termcap/terminfo
2801 The termcap entry for terminal type @samp{emacs} is ordinarily put in
2802 the @samp{TERMCAP} environment variable of subshells. It may help in
2803 certain situations (e.g., using rlogin from shell buffer) to add an
2804 entry for @samp{emacs} to the system-wide termcap file. Here is a
2805 correct termcap entry for @samp{emacs}:
2811 To make a terminfo entry for @samp{emacs}, use @code{tic} or
2812 @code{captoinfo}. You need to generate
2813 @file{/usr/lib/terminfo/e/emacs}. It may work to simply copy
2814 @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
2816 Having a termcap/terminfo entry will not enable the use of full screen
2817 programs in shell buffers. Use @kbd{M-x terminal-emulator} for that
2820 A workaround to the problem of missing termcap/terminfo entries is to
2821 change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
2822 in your shell start up file. @code{csh} users could put this in their
2823 @file{.cshrc} files:
2826 if ("$term" == emacs) set term=dumb
2829 @node Errors with init files
2830 @section Why does Emacs say @samp{Error in init file}?
2831 @cindex Error in @file{.emacs}
2832 @cindex Error in init file
2833 @cindex Init file, errors in
2834 @cindex @file{.emacs} file, errors in
2835 @cindex Debugging @file{.emacs} file
2837 An error occurred while loading either your @file{.emacs} file or the
2838 system-wide file @file{site-lisp/default.el}. Emacs 21.1 and later pops the
2839 @file{*Messages*} buffer, and puts there some additional information
2840 about the error, to provide some hints for debugging.
2842 For information on how to debug your @file{.emacs} file, see
2843 @ref{Debugging a customization file}.
2845 It may be the case that you need to load some package first, or use a
2846 hook that will be evaluated after the package is loaded. A common case
2847 of this is explained in @ref{Terminal setup code works after Emacs has
2850 @node Emacs ignores X resources
2851 @section Why does Emacs ignore my X resources (my .Xdefaults file)?
2852 @cindex X resources being ignored
2853 @cindex Ignored X resources
2854 @cindex @file{.Xdefaults}
2856 As of version 19, Emacs searches for X resources in the files specified
2857 by the following environment variables:
2861 @item @code{XFILESEARCHPATH}
2862 @item @code{XUSERFILESEARCHPATH}
2863 @item @code{XAPPLRESDIR}
2867 This emulates the functionality provided by programs written using the
2870 @code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
2871 of file names separated by colons. @code{XAPPLRESDIR} should be a list
2872 of directory names separated by colons.
2874 Emacs searches for X resources:
2879 specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
2882 then in the value of the @samp{XENVIRONMENT} environment variable,
2887 or if that is unset, in the file named
2888 @file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
2889 the name of the machine Emacs is running on),
2894 then in the screen-specific and server-wide resource properties provided
2900 or if those properties are unset, in the file named @file{~/.Xdefaults}
2906 then in the files listed in @samp{XUSERFILESEARCHPATH},
2911 or in files named @file{@var{lang}/Emacs} in directories listed in
2912 @samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
2913 environment variable), if the @samp{LANG} environment variable is set,
2915 or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
2917 or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
2920 or in @file{~/Emacs},
2925 then in the files listed in @code{XFILESEARCHPATH}.
2929 @node Emacs ignores frame parameters
2930 @section Why don't my customizations of the frame parameters work?
2931 @cindex Frame parameters
2933 This probably happens because you have set the frame parameters in the
2934 variable @code{initial-frame-alist}. That variable holds parameters
2935 used only for the first frame created when Emacs starts. To customize
2936 the parameters of all frames, change the variable
2937 @code{default-frame-alist} instead.
2939 These two variables exist because many users customize the initial frame
2940 in a special way. For example, you could determine the position and
2941 size of the initial frame, but would like to control the geometry of the
2942 other frames by individually positioning each one of them.
2945 @node Editing files with $ in the name
2946 @section How do I edit a file with a @samp{$} in its name?
2947 @cindex Editing files with @samp{$} in the name
2948 @cindex @samp{$} in file names
2949 @cindex File names containing @samp{$}, editing
2951 When entering a file name in the minibuffer, Emacs will attempt to expand
2952 a @samp{$} followed by a word as an environment variable. To suppress
2953 this behavior, type @kbd{$$} instead.
2955 @node Shell mode loses the current directory
2956 @section Why does shell mode lose track of the shell's current directory?
2957 @cindex Current directory and @code{shell-mode}
2958 @cindex @code{shell-mode} and current directory
2959 @cindex Directory, current in @code{shell-mode}
2961 Emacs has no way of knowing when the shell actually changes its
2962 directory. This is an intrinsic limitation of Unix. So it tries to
2963 guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed
2964 by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
2965 with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
2966 correctly guess the shell's new current directory. A huge variety of
2967 fixes and enhancements to shell mode for this problem have been written
2968 to handle this problem (@pxref{Finding a package with particular
2971 You can tell Emacs the shell's current directory with the command
2974 @node Security risks with Emacs
2975 @section Are there any security risks in Emacs?
2976 @cindex Security with Emacs
2977 @cindex @samp{movemail} and security
2978 @cindex @code{file-local-variable} and security
2979 @cindex Synthetic X events and security
2980 @cindex X events and security
2985 The @file{movemail} incident. (No, this is not a risk.)
2987 In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
2988 chapter 4. The site at LBL had installed the @file{/etc/movemail}
2989 program setuid root. (As of version 19, @file{movemail} is in your
2990 architecture-specific directory; type @kbd{C-h v exec-directory
2991 @key{RET}} to see what it is.) Since @code{movemail} had not been
2992 designed for this situation, a security hole was created and users could
2993 get root privileges.
2995 @code{movemail} has since been changed so that this security hole will
2996 not exist, even if it is installed setuid root. However,
2997 @code{movemail} no longer needs to be installed setuid root, which
2998 should eliminate this particular risk.
3000 We have heard unverified reports that the 1988 Internet worm took
3001 advantage of this configuration problem.
3004 The @code{file-local-variable} feature. (Yes, a risk, but easy to
3007 There is an Emacs feature that allows the setting of local values for
3008 variables when editing a file by including specially formatted text near
3009 the end of the file. This feature also includes the ability to have
3010 arbitrary Emacs Lisp code evaluated when the file is visited.
3011 Obviously, there is a potential for Trojan horses to exploit this
3014 As of Emacs 22, Emacs has a list of local variables that are known to
3015 be safe to set. If a file tries to set any variable outside this
3016 list, it asks the user to confirm whether the variables should be set.
3017 You can also tell Emacs whether to allow the evaluation of Emacs Lisp
3018 code found at the bottom of files by setting the variable
3019 @code{enable-local-eval}.
3021 For more information, @inforef{File Variables, File Variables, emacs}.
3024 Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
3027 Emacs accepts synthetic X events generated by the @code{SendEvent}
3028 request as though they were regular events. As a result, if you are
3029 using the trivial host-based authentication, other users who can open X
3030 connections to your X workstation can make your Emacs process do
3031 anything, including run other processes with your privileges.
3033 The only fix for this is to prevent other users from being able to open
3034 X connections. The standard way to prevent this is to use a real
3035 authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using
3036 the @code{xauth} program has any effect, then you are probably using
3037 @samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior
3038 authentication method; ask your system administrator.
3040 If real authentication is not a possibility, you may be satisfied by
3041 just allowing hosts access for brief intervals while you start your X
3042 programs, then removing the access. This reduces the risk somewhat by
3043 narrowing the time window when hostile users would have access, but
3044 @emph{does not eliminate the risk}.
3046 On most computers running Unix and X, you enable and disable
3047 access using the @code{xhost} command. To allow all hosts access to
3055 at the shell prompt, which (on an HP machine, at least) produces the
3059 access control disabled, clients can connect from any host
3062 To deny all hosts access to your X server (except those explicitly
3063 allowed by name), use
3069 On the test HP computer, this command generated the following message:
3072 access control enabled, only authorized clients can connect
3077 @node Dired claims that no file is on this line
3078 @section Dired says, @samp{no file on this line} when I try to do something.
3079 @cindex Dired does not see a file
3081 Dired uses a regular expression to find the beginning of a file name.
3082 In a long Unix-style directory listing (@samp{ls -l}), the file name
3083 starts after the date. The regexp has thus been written to look for the
3084 date. By default, it should understand dates and times regardless of
3085 the language, but if your directory listing has an unusual format, Dired
3088 There are two approaches to solving this. The first one involves
3089 setting things up so that @samp{ls -l} outputs a more standard format.
3090 See your OS manual for more information.
3092 The second approach involves changing the regular expression used by
3093 dired, @code{directory-listing-before-filename-regexp}.
3095 @c ------------------------------------------------------------
3096 @node Compiling and installing Emacs
3097 @chapter Compiling and installing Emacs
3098 @cindex Compiling and installing Emacs
3101 * Installing Emacs::
3102 * Problems building Emacs::
3105 @node Installing Emacs
3106 @section How do I install Emacs?
3107 @cindex Installing Emacs
3108 @cindex Unix systems, installing Emacs on
3109 @cindex Downloading and installing Emacs
3110 @cindex Building Emacs from source
3111 @cindex Source code, building Emacs from
3113 This answer is meant for users of Unix and Unix-like systems. Users of
3114 other operating systems should see the series of questions beginning
3115 with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
3116 and binaries, and how to install Emacs on those systems.
3118 Most GNU/Linux distributions provide pre-built Emacs packages.
3119 If Emacs is not installed already, you can install it by running (as
3120 root) a command such as @samp{yum install emacs} (Red Hat and
3121 derivatives) or @samp{apt-get install emacs} (Debian and derivatives).
3123 If you want to compile Emacs yourself, read the file @file{INSTALL} in
3124 the source distribution. In brief:
3129 First download the Emacs sources. @xref{Current GNU distributions}, for
3130 a list of ftp sites that make them available. On @file{ftp.gnu.org},
3131 the main GNU distribution site, sources are available as
3133 @c Don't include VER in the file name, because pretests are not there.
3134 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-VERSION.tar.gz}
3136 (Replace @samp{VERSION} with the relevant version number, e.g. @samp{23.1}.)
3139 Next uncompress and extract the source files. This requires
3140 the @code{gzip} and @code{tar} programs, which are standard utilities.
3141 If your system does not have them, these can also be downloaded from
3144 GNU @code{tar} can uncompress and extract in a single-step:
3147 tar -zxvf emacs-VERSION.tar.gz
3151 At this point, the Emacs sources should be sitting in a directory called
3152 @file{emacs-VERSION}. On most common Unix and Unix-like systems,
3153 you should be able to compile Emacs with the following commands:
3157 ./configure # configure Emacs for your particular system
3158 make # use Makefile to build components, then Emacs
3161 If the @code{make} completes successfully, the odds are fairly good that
3162 the build has gone well. (@xref{Problems building Emacs}, if you weren't
3166 By default, Emacs is installed in @file{/usr/local}. To actually
3167 install files, become the superuser and type
3173 Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
3174 and any Emacs Info files that might be in @file{/usr/local/share/info/}.
3178 @node Problems building Emacs
3179 @section What should I do if I have trouble building Emacs?
3180 @cindex Problems building Emacs
3181 @cindex Errors when building Emacs
3183 First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
3184 source) to see if there is already a solution for your problem. Next,
3185 look for other questions in this FAQ that have to do with Emacs
3186 installation and compilation problems.
3188 If you'd like to have someone look at your problem and help solve it,
3189 see @ref{Help installing Emacs}.
3191 If you cannot find a solution in the documentation, please report the
3192 problem (@pxref{Reporting bugs}).
3195 @c ------------------------------------------------------------
3196 @node Finding Emacs and related packages
3197 @chapter Finding Emacs and related packages
3198 @cindex Finding Emacs and related packages
3201 * Finding Emacs on the Internet::
3202 * Finding a package with particular functionality::
3203 * Packages that do not come with Emacs::
3204 * Current GNU distributions::
3205 * Difference between Emacs and XEmacs::
3206 * Emacs for minimalists::
3207 * Emacs for MS-DOS::
3208 * Emacs for MS-Windows::
3209 * Emacs for GNUstep::
3210 * Emacs for Mac OS X::
3213 @node Finding Emacs on the Internet
3214 @section Where can I get Emacs on the net?
3215 @cindex Finding Emacs on the Internet
3216 @cindex Downloading Emacs
3218 Information on downloading Emacs is available at
3219 @uref{http://www.gnu.org/software/emacs/, the Emacs home-page}.
3221 @xref{Installing Emacs}, for information on how to obtain and build the latest
3222 version of Emacs, and see @ref{Current GNU distributions}, for a list of
3223 archive sites that make GNU software available.
3225 @node Finding a package with particular functionality
3226 @section How do I find a Emacs Lisp package that does XXX?
3227 @cindex Package, finding
3228 @cindex Finding an Emacs Lisp package
3229 @cindex Functionality, finding a particular package
3231 First of all, you should check to make sure that the package isn't
3232 already available. For example, typing @kbd{M-x apropos @key{RET}
3233 wordstar @key{RET}} lists all functions and variables containing the
3234 string @samp{wordstar}.
3236 It is also possible that the package is on your system, but has not been
3237 loaded. To see which packages are available for loading, look through
3238 your computer's lisp directory (@pxref{File-name conventions}). The Lisp
3239 source to most packages contains a short description of how they
3240 should be loaded, invoked, and configured---so before you use or
3241 modify a Lisp package, see if the author has provided any hints in the
3244 The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
3245 the constituent Emacs packages.
3247 For advice on how to find extra packages that are not part of Emacs,
3248 see @ref{Packages that do not come with Emacs}.
3250 @node Packages that do not come with Emacs
3251 @section Where can I get Emacs Lisp packages that don't come with Emacs?
3252 @cindex Unbundled packages
3253 @cindex Finding other packages
3254 @cindex Lisp packages that do not come with Emacs
3255 @cindex Packages, those that do not come with Emacs
3256 @cindex Emacs Lisp List
3257 @cindex Emacs Lisp Archive
3259 @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs Lisp
3260 List (ELL)}, maintained by @email{S.J.Eglen@@damtp.cam.ac.uk, Stephen Eglen},
3261 aims to provide one compact list with links to all of the current Emacs
3262 Lisp files on the Internet. The ELL can be browsed over the web, or
3263 from Emacs with @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.el,
3264 the @file{ell} package}.
3266 Many authors post their packages to the @uref{news:gnu.emacs.sources,
3267 Emacs sources newsgroup}. You can search the archives of this
3268 group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google},
3269 or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example.
3271 Several packages are stored in
3272 @uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}.
3274 Read the file @file{etc/MORE.STUFF} for more information about
3277 @node Current GNU distributions
3278 @section Where can I get other up-to-date GNU stuff?
3279 @cindex Current GNU distributions
3280 @cindex Sources for current GNU distributions
3281 @cindex Stuff, current GNU
3282 @cindex Up-to-date GNU stuff
3283 @cindex Finding current GNU software
3284 @cindex Official GNU software sites
3286 The most up-to-date official GNU software is normally kept at
3288 @uref{ftp://ftp.gnu.org/pub/gnu}
3290 A list of sites mirroring @samp{ftp.gnu.org} can be found at
3292 @uref{http://www.gnu.org/order/ftp.html}
3294 @node Difference between Emacs and XEmacs
3295 @section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
3297 @cindex Difference Emacs and XEmacs
3301 XEmacs is a branch version of Emacs. It was first called Lucid Emacs,
3302 and was initially derived from a prerelease version of Emacs 19. In
3303 this FAQ, we use the name ``Emacs'' only for the official version.
3305 Emacs and XEmacs each come with Lisp packages that are lacking in the
3306 other. The two versions have some significant differences at the Lisp
3307 programming level. Their current features are roughly comparable,
3308 though the support for some operating systems, character sets and
3309 specific packages might be quite different.
3311 Some XEmacs code has been contributed to Emacs, and we would like to
3312 use other parts, but the earlier XEmacs maintainers did not always
3313 keep track of the authors of contributed code, which makes it
3314 impossible for the FSF to get copyright papers signed for that code.
3315 (The FSF requires these papers for all the code included in the Emacs
3316 release, aside from generic C support packages that retain their
3317 separate identity and are not integrated into the code of Emacs
3320 If you want to talk about these two versions and distinguish them,
3321 please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs''
3322 with ``GNU Emacs'' would be misleading, since XEmacs too has its
3323 origin in the work of the GNU Project. Terms such as ``Emacsen'' and
3324 ``(X)Emacs'' are not wrong, but they are not very clear, so it
3325 is better to write ``Emacs and XEmacs.''
3327 @node Emacs for minimalists
3328 @section I don't have enough disk space to install Emacs
3330 @cindex Not enough disk space to install Emacs
3332 GNU Zile is a lightweight Emacs clone. Zile is short for @samp{Zile Is
3333 Lossy Emacs}. It has all of Emacs's basic editing features. The Zile
3334 binary typically has a size of about 130 kbytes, so this can be useful
3335 if you are in an extremely space-restricted environment. More
3336 information is available from
3338 @uref{http://www.gnu.org/software/zile/}
3341 @node Emacs for MS-DOS
3342 @section Where can I get Emacs for MS-DOS?
3343 @cindex MS-DOS, Emacs for
3344 @cindex DOS, Emacs for
3345 @cindex Compiling Emacs for DOS
3346 @cindex Emacs for MS-DOS
3348 To build Emacs from source for MS-DOS, see the instructions in the file
3349 @file{msdos/INSTALL} in the distribution. The DOS port builds and runs
3350 on plain DOS, and also on all versions of MS-Windows from version 3.X
3351 onwards, including Windows XP and Vista.
3353 The file @file{etc/PROBLEMS} contains some additional information
3354 regarding Emacs under MS-DOS.
3356 A pre-built binary distribution of the old Emacs 20 is available, as
3359 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README}
3361 For a list of other MS-DOS implementations of Emacs (and Emacs
3362 look-alikes), consult the list of ``Emacs implementations and literature,''
3365 @uref{http://www.finseth.com/emacs.html}
3367 Note that while many of these programs look similar to Emacs, they often
3368 lack certain features, such as the Emacs Lisp extension language.
3370 @node Emacs for MS-Windows
3371 @section Where can I get Emacs for Microsoft Windows?
3372 @cindex FAQ for Emacs on MS-Windows
3373 @cindex Emacs for MS-Windows
3374 @cindex Microsoft Windows, Emacs for
3376 There is a @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html,
3377 separate FAQ} for Emacs on MS-Windows. For MS-DOS, @pxref{Emacs for MS-DOS}.
3380 @node Emacs for GNUstep
3381 @section Where can I get Emacs for GNUstep?
3382 @cindex GNUstep, Emacs for
3384 Beginning with version 23.1, Emacs supports GNUstep natively.
3385 See the file @file{nextstep/INSTALL} in the distribution.
3387 @node Emacs for Mac OS X
3388 @section Where can I get Emacs for Mac OS X?
3389 @cindex Apple computers, Emacs for
3390 @cindex Macintosh, Emacs for
3391 @cindex Mac OS X, Emacs for
3393 Beginning with version 22.1, Emacs supports Mac OS X natively.
3394 See the file @file{nextstep/INSTALL} in the distribution.
3396 @c ------------------------------------------------------------
3397 @node Major packages and programs
3398 @chapter Major packages and programs
3399 @cindex Major packages and programs
3412 @section VM (View Mail) --- another mail reader within Emacs, with MIME support
3414 @cindex Alternative mail software
3416 @cindex E-mail reader, VM
3421 @uref{http://launchpad.net/vm}
3422 (was @uref{http://www.nongnu.org/viewmail/})
3424 @item Informational newsgroup
3425 @uref{news:gnu.emacs.vm.info}@*
3427 @item Bug reports newsgroup
3428 @uref{news:gnu.emacs.vm.bug}@*
3431 VM was originally written by @uref{http://www.wonderworks.com/vm/,Kyle Jones}.
3432 @uref{ftp://ftp.wonderworks.com/pub/vm/,Older versions} of VM remain
3437 @section AUC@TeX{} --- enhanced @TeX{} modes with debugging facilities
3438 @cindex Mode for @TeX{}
3440 @cindex AUC@TeX{} mode for editing @TeX{}
3441 @cindex Writing and debugging @TeX{}
3443 AUC@TeX{} is a set of sophisticated major modes for @TeX{}, LaTeX,
3444 ConTeXt, and Texinfo offering context-sensitive syntax highlighting,
3445 indentation, formatting and folding, macro completion, @TeX{} shell
3446 functionality, and debugging. Be also sure to check out
3447 @ref{Introduction, RefTeX, Introduction, reftex, Ref@TeX{} User Manual}.
3448 Current versions of AUC@TeX{} include the
3449 @uref{http://www.gnu.org/software/auctex/preview-latex.html,preview-latex}
3450 package for WYSIWYG previews of various LaTeX constructs in the Emacs
3453 @uref{http://www.gnu.org/software/auctex/, AUCTeX}
3456 @section BBDB --- personal Info Rolodex integrated with mail/news readers
3458 @cindex Rolodex-like functionality
3459 @cindex Integrated contact database
3460 @cindex Contact database
3461 @cindex Big Brother Database
3462 @cindex Address book
3464 @uref{http://bbdb.sourceforge.net/, The Insidious Big Brother Database}
3466 @node Spell-checkers
3467 @section Spell-checkers
3468 @cindex Spell-checker
3469 @cindex Checking spelling
3474 Various spell-checkers are compatible with Emacs, including:
3479 @uref{http://aspell.net/}
3482 @uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
3485 @uref{http://hunspell.sourceforge.net/}
3490 @section Emacs/W3 --- A World Wide Web browser inside of Emacs
3493 @cindex HTML browser in Emacs
3494 @cindex @code{w3-mode}
3496 @uref{http://www.gnu.org/software/w3/, Emacs/W3}
3499 @section EDB --- Database program for Emacs; replaces forms editing modes
3504 @uref{http://gnuvola.org/software/edb/, The Emacs Database}
3507 @section JDEE --- Integrated development environment for Java
3508 @cindex Java development environment
3509 @cindex Integrated Java development environment
3512 @uref{http://jdee.sourceforge.net/, A Java Development Environment for Emacs}
3514 @c ------------------------------------------------------------
3516 @chapter Key bindings
3517 @cindex Key bindings
3520 * Binding keys to commands::
3521 * Invalid prefix characters::
3522 * Terminal setup code works after Emacs has begun::
3523 * Working with function and arrow keys::
3524 * X key translations for Emacs::
3525 * Backspace invokes help::
3527 * Producing C-XXX with the keyboard::
3530 * Compose Character::
3531 * Binding combinations of modifiers and function keys::
3532 * Meta key does not work in xterm::
3533 * ExtendChar key does not work as Meta::
3534 * SPC no longer completes file names::
3537 @node Binding keys to commands
3538 @section How do I bind keys (including function keys) to commands?
3539 @cindex Binding keys to commands
3540 @cindex Keys, binding to commands
3541 @cindex Commands, binding keys to
3543 Keys can be bound to commands either interactively or in your
3544 @file{.emacs} file. To interactively bind keys for all modes, type
3545 @kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3547 To bind a key just in the current major mode, type @kbd{M-x
3548 local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3550 @inforef{Key Bindings, Key Bindings, emacs}, for further details.
3552 To make the process of binding keys interactively easier, use the
3553 following ``trick'': First bind the key interactively, then immediately
3554 type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
3555 to bind the key is in the kill ring, and can be yanked into your
3556 @file{.emacs} file. If the key binding is global, no changes to the
3557 command are required. For example,
3560 (global-set-key (quote [f1]) (quote help-for-help))
3564 can be placed directly into the @file{.emacs} file. If the key binding is
3565 local, the command is used in conjunction with the @samp{add-hook} function.
3566 For example, in TeX mode, a local binding might be
3569 (add-hook 'tex-mode-hook
3571 (local-set-key (quote [f1]) (quote help-for-help))))
3578 Control characters in key sequences, in the form yanked from the kill
3579 ring are given in their graphic form---i.e., @key{CTRL} is shown as
3580 @samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want
3581 to convert these into their vector or string forms.
3584 If a prefix key of the character sequence to be bound is already
3585 bound as a complete key, then you must unbind it before the new
3586 binding. For example, if @kbd{ESC @{} is previously bound:
3589 (global-unset-key [?\e ?@{]) ;; or
3590 (local-unset-key [?\e ?@{])
3594 Aside from commands and ``lambda lists,'' a vector or string also
3595 can be bound to a key and thus treated as a macro. For example:
3598 (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or
3599 (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
3604 @node Invalid prefix characters
3605 @section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
3606 @cindex Prefix characters, invalid
3607 @cindex Invalid prefix characters
3608 @cindex Misspecified key sequences
3610 Usually, one of two things has happened. In one case, the control
3611 character in the key sequence has been misspecified (e.g. @samp{C-f}
3612 used instead of @samp{\C-f} within a Lisp expression). In the other
3613 case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
3614 was already bound as a @dfn{complete key}. Historically, the @samp{ESC [}
3615 prefix was usually the problem, in which case you should evaluate either
3616 of these forms before attempting to bind the key sequence:
3619 (global-unset-key [?\e ?[]) ;; or
3620 (global-unset-key "\e[")
3623 @node Terminal setup code works after Emacs has begun
3624 @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?
3625 @cindex Terminal setup code in @file{.emacs}
3627 During startup, Emacs initializes itself according to a given code/file
3628 order. If some of the code executed in your @file{.emacs} file needs to
3629 be postponed until the initial terminal or window-system setup code has
3630 been executed but is not, then you will experience this problem (this
3631 code/file execution order is not enforced after startup).
3633 To postpone the execution of Emacs Lisp code until after terminal or
3634 window-system setup, treat the code as a @dfn{lambda list} and set the
3635 value of either the @code{term-setup-hook} or @code{window-setup-hook}
3636 variable to this lambda function. For example,
3639 (add-hook 'term-setup-hook
3641 (when (string-match "\\`vt220" (or (getenv "TERM") ""))
3642 ;; Make vt220's "Do" key behave like M-x:
3643 (global-set-key [do] 'execute-extended-command))))
3646 For information on what Emacs does every time it is started, see the
3647 @file{lisp/startup.el} file.
3649 @node Working with function and arrow keys
3650 @section How do I tell what characters or symbols my function or arrow keys emit?
3651 @cindex Working with arrow keys
3652 @cindex Arrow keys, symbols generated by
3653 @cindex Working with function keys
3654 @cindex Function keys, symbols generated by
3655 @cindex Symbols generated by function keys
3657 Type @kbd{C-h c} then the function or arrow keys. The command will
3658 return either a function key symbol or character sequence (see the
3659 Emacs documentation for an explanation). This works for other
3662 @node X key translations for Emacs
3663 @section How do I set the X key ``translations'' for Emacs?
3664 @cindex X key translations
3665 @cindex Key translations under X
3666 @cindex Translations for keys under X
3668 Emacs is not written using the Xt library by default, so there are no
3669 ``translations'' to be set. (We aren't sure how to set such translations
3670 if you do build Emacs with Xt; please let us know if you've done this!)
3672 The only way to affect the behavior of keys within Emacs is through
3673 @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The
3674 @code{define-key} command should be used in conjunction with the
3675 @code{function-key-map} map. For instance,
3678 (define-key function-key-map [M-@key{TAB}] [?\M-\t])
3682 defines the @kbd{M-@key{TAB}} key sequence.
3684 @node Backspace invokes help
3685 @section Why does the @key{Backspace} key invoke help?
3686 @cindex Backspace key invokes help
3687 @cindex Help invoked by Backspace
3688 @cindex DEL key does not delete
3690 The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8.
3691 @kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes
3692 help-command. This is intended to be easy to remember since the first
3693 letter of @samp{help} is @samp{h}. The easiest solution to this problem
3694 is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
3695 @key{Delete} key) for deleting the previous character.
3697 For many people this solution may be problematic:
3702 They normally use @key{Backspace} outside of Emacs for deleting the
3703 previous character. This can be solved by making @key{DEL} the command
3704 for deleting the previous character outside of Emacs. On many Unix
3705 systems, this command will remap @key{DEL}:
3712 The user may prefer the @key{Backspace} key for deleting the
3713 previous character because it is more conveniently located on their
3714 keyboard or because they don't even have a separate @key{Delete} key.
3715 In this case, the @key{Backspace} key should be made to behave like
3716 @key{Delete}. There are several methods.
3720 Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
3721 TeraTerm) allow the character generated by the @key{Backspace} key to be
3722 changed from a setup menu.
3725 You may be able to get a keyboard that is completely programmable, or a
3726 terminal emulator that supports remapping of any key to any other key.
3729 With Emacs 21.1 and later, you can control the effect of the
3730 @key{Backspace} and @key{Delete} keys, on both dumb terminals and a
3731 windowed displays, by customizing the option
3732 @code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
3733 normal-erase-is-backspace}. See the documentation of these symbols
3734 (@pxref{Emacs Lisp documentation}) for more info.
3737 It is possible to swap the @key{Backspace} and @key{DEL} keys inside
3741 (keyboard-translate ?\C-h ?\C-?)
3745 This is the recommended method of forcing @key{Backspace} to act as
3746 @key{DEL}, because it works even in modes which bind @key{DEL} to
3747 something other than @code{delete-backward-char}.
3749 Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
3750 default deletes forward:
3753 (keyboard-translate ?\C-? ?\C-d)
3756 @xref{Swapping keys}, for further details about @code{keyboard-translate}.
3759 Another approach is to switch key bindings and put help on @kbd{C-x h}
3763 (global-set-key "\C-h" 'delete-backward-char)
3765 ;; overrides mark-whole-buffer
3766 (global-set-key "\C-xh" 'help-command)
3770 This method is not recommended, though: it only solves the problem for
3771 those modes which bind @key{DEL} to @code{delete-backward-char}. Modes
3772 which bind @key{DEL} to something else, such as @code{view-mode}, will
3773 not work as you expect when you press the @key{Backspace} key. For this
3774 reason, we recommend the @code{keyboard-translate} method, shown
3777 Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
3780 Don't try to bind @key{DEL} to @code{help-command}, because there are
3781 many modes that have local bindings of @key{DEL} that will interfere.
3785 When Emacs 21 or later runs on a windowed display, it binds the
3786 @key{Delete} key to a command which deletes the character at point, to
3787 make Emacs more consistent with keyboard operation on these systems.
3789 For more information about troubleshooting this problem, see @ref{DEL
3790 Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
3794 @section How do I swap two keys?
3795 @cindex Swapping keys
3796 @cindex Keys, swapping
3797 @cindex @code{keyboard-translate}
3799 You can swap two keys (or key sequences) by using the
3800 @code{keyboard-translate} function. For example, to turn @kbd{C-h}
3801 into @key{DEL} and @key{DEL} to @kbd{C-h}, use
3804 (keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL
3805 (keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.
3809 The first key sequence of the pair after the function identifies what is
3810 produced by the keyboard; the second, what is matched for in the
3813 However, in the specific case of @kbd{C-h} and @key{DEL}, you should
3814 toggle @code{normal-erase-is-backspace-mode} instead of calling
3815 @code{keyboard-translate}. @inforef{DEL Does Not Delete, DEL Does Not Delete,
3818 Keyboard translations are not the same as key bindings in keymaps.
3819 Emacs contains numerous keymaps that apply in different situations, but
3820 there is only one set of keyboard translations, and it applies to every
3821 character that Emacs reads from the terminal. Keyboard translations
3822 take place at the lowest level of input processing; the keys that are
3823 looked up in keymaps contain the characters that result from keyboard
3826 @node Producing C-XXX with the keyboard
3827 @section How do I produce C-XXX with my keyboard?
3828 @cindex Producing control characters
3829 @cindex Generating control characters
3830 @cindex Control characters, generating
3832 On terminals (but not under X), some common ``aliases'' are:
3836 @item @kbd{C-2} or @kbd{C-@key{SPC}}
3842 @item @kbd{C-7} or @kbd{C-S--}
3856 Often other aliases exist; use the @kbd{C-h c} command and try
3857 @key{CTRL} with all of the digits on your keyboard to see what gets
3858 generated. You can also try the @kbd{C-h w} command if you know the
3859 name of the command.
3862 @section What if I don't have a @key{Meta} key?
3863 @cindex No @key{Meta} key
3864 @cindex @key{Meta} key, what to do if you lack it
3866 On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
3868 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact,
3869 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
3870 (depending on the value of @code{meta-prefix-char}). Note that you
3871 press @key{Meta} and @key{a} together, but with @key{ESC}, you press
3872 @key{ESC}, release it, and then press @key{a}.
3875 @section What if I don't have an @key{Escape} key?
3876 @cindex No Escape key
3877 @cindex Lacking an Escape key
3878 @cindex Escape key, lacking
3880 Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an
3881 Escape key would. @kbd{C-3} may also work on some terminal (but not
3882 under X). For many terminals (notably DEC terminals) @key{F11}
3883 generates @key{ESC}. If not, the following form can be used to bind it:
3886 ;; F11 is the documented ESC replacement on DEC terminals.
3887 (define-key function-key-map [f11] [?\e])
3890 @node Compose Character
3891 @section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
3892 @cindex @key{Compose Character} key, using as @key{Meta}
3893 @cindex @key{Meta}, using @key{Compose Character} for
3895 On a dumb terminal such as a VT220, no. It is rumored that certain
3896 VT220 clones could have their @key{Compose} key configured this way. If
3897 you're using X, you might be able to do this with the @code{xmodmap}
3900 @node Binding combinations of modifiers and function keys
3901 @section How do I bind a combination of modifier key and function key?
3902 @cindex Modifiers and function keys
3903 @cindex Function keys and modifiers
3904 @cindex Binding modifiers and function keys
3906 With Emacs 19 and later, you can represent modified function keys in
3907 vector format by adding prefixes to the function key symbol. For
3908 example (from the Emacs documentation):
3911 (global-set-key [?\C-x right] 'forward-page)
3915 where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
3917 You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
3918 @key{Super}, @key{Alt}, and @key{Shift} with function keys. To
3919 represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
3920 @samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here
3921 is how to make @kbd{H-M-RIGHT} move forward a word:
3924 (global-set-key [H-M-right] 'forward-word)
3930 Not all modifiers are permitted in all situations. @key{Hyper},
3931 @key{Super}, and @key{Alt} are not available on Unix character
3932 terminals. Non-@acronym{ASCII} keys and mouse events (e.g. @kbd{C-=} and
3933 @kbd{Mouse-1}) also fall under this category.
3937 @xref{Binding keys to commands}, for general key binding instructions.
3939 @node Meta key does not work in xterm
3940 @section Why doesn't my @key{Meta} key work in an @code{xterm} window?
3941 @cindex @key{Meta} key and @code{xterm}
3942 @cindex Xterm and @key{Meta} key
3944 @inforef{Unibyte Mode, Single-Byte Character Set Support, emacs}.
3946 If the advice in the Emacs manual fails, try all of these methods before
3947 asking for further help:
3952 You may have big problems using @code{mwm} as your window manager.
3953 (Does anyone know a good generic solution to allow the use of the
3954 @key{Meta} key in Emacs with @file{mwm}?)
3957 For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to
3958 find out what keysym your @key{Meta} key generates. It should be either
3959 @code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix
3960 the situation. If @key{Meta} does generate @code{Meta_L} or
3961 @code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in
3962 your @file{~/.Xdefaults} file:
3965 XTerm*eightBitInput: false
3966 XTerm*eightBitOutput: true
3970 Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
3971 characters. @samp{stty -a} (or @samp{stty everything}) should show
3972 @samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty
3973 cs8 -istrip} (or @samp{stty pass8}) to fix it.
3976 If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
3977 @samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
3981 If Emacs is running on Ultrix, it is reported that evaluating
3982 @code{(set-input-mode t nil)} helps.
3985 If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
3986 you type @kbd{M-W}, which is the same conversion Emacs would make if it
3987 got the @kbd{M-W} anyway. In X11R4, the following resource
3988 specification will do this:
3991 XTerm.VT100.EightBitInput: false
3995 (This changes the behavior of the @code{insert-eight-bit} action.)
3997 With older @code{xterm}s, you can specify this behavior with a translation:
4000 XTerm.VT100.Translations: #override \
4001 Meta<KeyPress>: string(0x1b) insert()
4005 You might have to replace @samp{Meta} with @samp{Alt}.
4009 @node ExtendChar key does not work as Meta
4010 @section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
4011 @cindex @key{ExtendChar} key as @key{Meta}
4012 @cindex @key{Meta}, using @key{ExtendChar} for
4013 @cindex HP-UX, the @key{ExtendChar} key
4015 This is a result of an internationalization extension in X11R4 and the
4016 fact that HP is now using this extension. Emacs assumes that the
4017 @code{XLookupString} function returns the same result regardless of the
4018 @key{Meta} key state which is no longer necessarily true. Until Emacs
4019 is fixed, the temporary kludge is to run this command after each time
4020 the X server is started but preferably before any xterm clients are:
4023 xmodmap -e 'remove mod1 = Mode_switch'
4026 @c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
4029 This will disable the use of the extra keysyms systemwide, which may be
4030 undesirable if you actually intend to use them.
4032 @node SPC no longer completes file names
4033 @section Why doesn't SPC complete file names anymore?
4034 @cindex @kbd{SPC} file name completion
4036 Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in
4037 the minibuffer, so that file names with embedded spaces could be typed
4038 without the need to quote the spaces.
4040 You can get the old behavior by binding @kbd{SPC} to
4041 @code{minibuffer-complete-word} in the minibuffer, as follows:
4044 (define-key minibuffer-local-filename-completion-map (kbd "SPC")
4045 'minibuffer-complete-word)
4047 (define-key minibuffer-local-must-match-filename-map (kbd "SPC")
4048 'minibuffer-complete-word)
4051 @c ------------------------------------------------------------
4052 @node Alternate character sets
4053 @chapter Alternate character sets
4054 @cindex Alternate character sets
4057 * Emacs does not display 8-bit characters::
4058 * Inputting eight-bit characters::
4059 * Right-to-left alphabets::
4060 * How to add fonts::
4063 @node Emacs does not display 8-bit characters
4064 @section How do I make Emacs display 8-bit characters?
4065 @cindex Displaying eight-bit characters
4066 @cindex Eight-bit characters, displaying
4068 @inforef{Unibyte Mode, Single-byte Character Set
4069 Support, emacs}. On a Unix, when Emacs runs on a text-only terminal
4070 display or is invoked with @samp{emacs -nw}, you typically need to use
4071 @code{set-terminal-coding-system} to tell Emacs what the terminal can
4072 display, even after setting the language environment; otherwise
4073 non-@acronym{ASCII} characters will display as @samp{?}. On other operating
4074 systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
4075 character set supported by the display, and sets up the required
4076 terminal coding system automatically.
4078 @node Inputting eight-bit characters
4079 @section How do I input eight-bit characters?
4080 @cindex Entering eight-bit characters
4081 @cindex Eight-bit characters, entering
4082 @cindex Input, 8-bit characters
4084 Various methods are available for input of eight-bit characters. See
4085 @inforef{Unibyte Mode, Single-byte Character Set
4086 Support, emacs}. For more sophisticated methods, @inforef{Input
4087 Methods, Input Methods, emacs}.
4089 @node Right-to-left alphabets
4090 @section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
4091 @cindex Right-to-left alphabets
4092 @cindex Hebrew, handling with Emacs
4093 @cindex Semitic alphabets
4094 @cindex Arabic alphabets
4095 @cindex Bidirectional text
4097 Emacs supports Hebrew characters (ISO 8859-8) since version 20, but does
4098 not yet support right-to-left character entry and display. The
4099 @uref{http://lists.gnu.org/mailman/listinfo/emacs-bidi, emacs-bidi
4100 mailing list} discusses development of support for this feature.
4103 @node How to add fonts
4104 @section How do I add fonts for use with Emacs?
4105 @cindex add fonts for use with Emacs
4108 First, download and install the BDF font files and any auxiliary
4109 packages they need. The GNU Intlfonts distribution can be found on
4110 @uref{http://directory.fsf.org/localization/intlfonts.html, the GNU
4111 Software Directory Web site}.
4113 Next, if you are on X Window system, issue the following two commands
4114 from the shell's prompt:
4117 xset +fp /usr/local/share/emacs/fonts
4122 (Modify the first command if you installed the fonts in a directory
4123 that is not @file{/usr/local/share/emacs/fonts}.) You also need to
4124 arrange for these two commands to run whenever you log in, e.g., by
4125 adding them to your window-system startup file, such as
4126 @file{~/.xsessionrc} or @file{~/.gnomerc}.
4128 Now, add the following line to your @file{~/.emacs} init file:
4131 (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
4135 (Again, modify the file name if you installed the fonts elsewhere.)
4137 Finally, if you wish to use the installed fonts with @code{ps-print},
4138 add the following line to your @file{~/.emacs}:
4141 (setq ps-multibyte-buffer 'bdf-font-except-latin)
4144 A few additional steps are necessary for MS-Windows; they are listed
4147 First, make sure @emph{all} the directories with BDF font files are
4148 mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux
4149 systems, one normally runs @kbd{make install} to install the BDF fonts
4150 in the same directory. By contrast, Windows users typically don't run
4151 the Intlfonts installation command, but unpack the distribution in
4152 some directory, which leaves the BDF fonts in its subdirectories. For
4153 example, assume that you unpacked Intlfonts in @file{C:/Intlfonts};
4154 then you should set @code{bdf-directory-list} as follows:
4157 (setq bdf-directory-list
4158 '("C:/Intlfonts/Asian"
4159 "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X"
4160 "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic"
4161 "C:/Intlfonts/European" "C:/Intlfonts/European.BIG"
4162 "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X"
4163 "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X"
4164 "C:/Intlfonts/Misc"))
4167 @cindex @code{w32-bdf-filename-alist}
4168 @cindex @code{w32-find-bdf-fonts}
4169 Next, you need to set up the variable @code{w32-bdf-filename-alist} to
4170 an alist of the BDF fonts and their corresponding file names.
4171 Assuming you have set @code{bdf-directory-list} to name all the
4172 directories with the BDF font files, the following Lisp snippet will
4173 set up @code{w32-bdf-filename-alist}:
4176 (setq w32-bdf-filename-alist
4177 (w32-find-bdf-fonts bdf-directory-list))
4180 Now, create fontsets for the BDF fonts:
4183 (create-fontset-from-fontset-spec
4184 "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf,
4185 japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*,
4186 katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4187 latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4188 japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*,
4189 thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1,
4190 lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1,
4191 tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1,
4192 ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode,
4193 tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0")
4196 Many of the international bdf fonts from Intlfonts are type 0, and
4197 therefore need to be added to font-encoding-alist:
4200 (setq font-encoding-alist
4201 (append '(("MuleTibetan-0" (tibetan . 0))
4202 ("GB2312" (chinese-gb2312 . 0))
4203 ("JISX0208" (japanese-jisx0208 . 0))
4204 ("JISX0212" (japanese-jisx0212 . 0))
4205 ("VISCII" (vietnamese-viscii-lower . 0))
4206 ("KSC5601" (korean-ksc5601 . 0))
4207 ("MuleArabic-0" (arabic-digit . 0))
4208 ("MuleArabic-1" (arabic-1-column . 0))
4209 ("MuleArabic-2" (arabic-2-column . 0)))
4210 font-encoding-alist))
4213 You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
4214 fontset, or you can select it by setting the default font in your
4218 (set-default-font "fontset-bdf")
4222 @c ------------------------------------------------------------
4224 @chapter Mail and news
4225 @cindex Mail and news
4228 * Changing the included text prefix::
4229 * Saving a copy of outgoing mail::
4230 * Expanding aliases when sending mail::
4231 * Sorting the messages in an Rmail folder::
4232 * Rmail writes to /var/spool/mail::
4233 * Replying to the sender of a message::
4234 * Automatically starting a mail or news reader::
4235 * Reading news with Emacs::
4236 * Gnus does not work with NNTP::
4237 * Making Gnus faster::
4238 * Catching up in all newsgroups::
4241 @node Changing the included text prefix
4242 @section How do I change the included text prefix in mail/news followups?
4243 @cindex Prefix in mail/news followups, changing
4244 @cindex Included text prefix, changing
4245 @cindex Setting the included text character
4246 @cindex Quoting in mail messages
4248 If you read mail with Rmail, set the variable @code{mail-yank-prefix}.
4249 For Gnus, set @code{message-yank-prefix}. For VM, set
4250 @code{vm-included-text-prefix}. For mh-e, set @code{mh-ins-buf-prefix}.
4252 For fancier control of citations, use Supercite (@pxref{Top,, the Supercite
4253 Manual, sc, The Supercite Manual}).
4255 To prevent Emacs from including various headers of the replied-to
4256 message, set the value of @code{mail-yank-ignored-headers} to an
4259 @node Saving a copy of outgoing mail
4260 @section How do I save a copy of outgoing mail?
4261 @cindex Saving a copy of outgoing mail
4262 @cindex Copying outgoing mail to a file
4263 @cindex Filing outgoing mail
4264 @cindex Automatic filing of outgoing mail
4265 @cindex Mail, saving outgoing automatically
4267 You can either mail yourself a copy by including a @samp{BCC} header in the
4268 mail message, or store a copy of the message directly to a file by
4269 including an @samp{FCC} header.
4271 If you use standard mail, you can automatically create a @samp{BCC} to
4275 (setq mail-self-blind t)
4279 in your @file{.emacs} file. You can automatically include an @samp{FCC}
4280 field by putting something like the following in your @file{.emacs}
4284 (setq mail-archive-file-name (expand-file-name "~/outgoing"))
4287 The output file will be in Unix mail format.
4289 If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
4292 It does not work to put @samp{set record filename} in the @file{.mailrc}
4295 @node Expanding aliases when sending mail
4296 @section Why doesn't Emacs expand my aliases when sending mail?
4297 @cindex Expanding aliases when sending mail
4298 @cindex Mail alias expansion
4299 @cindex Sending mail with aliases
4301 @xref{Mail Aliases,, The Emacs Manual, emacs, The Emacs Manual}.
4306 Normally, Emacs expands aliases when you send the message.
4307 To expand them before this, use @kbd{M-x expand-mail-aliases}.
4309 @c FIXME there should be an interactive rebuild command for this.
4311 Emacs normally only reads the @file{.mailrc} file once per session,
4312 when you start to compose your first mail message. If you edit
4313 @file{.mailrc}, you can type @kbd{M-: (build-mail-aliases) @key{RET}} to
4314 make Emacs reread @file{~/.mailrc}.
4317 If you like, you can expand mail aliases as abbrevs, as soon as you
4318 type them in. To enable this feature, execute the following:
4321 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
4324 Note that the aliases are expanded automatically only after you type
4325 a word-separator character (e.g. @key{RET} or @kbd{,}). You can force their
4326 expansion by moving point to the end of the alias and typing @kbd{C-x a e}
4327 (@kbd{M-x expand-abbrev}).
4330 @node Sorting the messages in an Rmail folder
4331 @section How can I sort the messages in my Rmail folder?
4332 @cindex Rmail, sorting messages in
4333 @cindex Folder, sorting messages in an Rmail
4334 @cindex Sorting messages in an Rmail folder
4336 In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
4337 and their key bindings.
4339 @node Rmail writes to /var/spool/mail
4340 @section Why does Rmail need to write to @file{/var/spool/mail}?
4341 @cindex Rmail and @file{/var/spool/mail}
4342 @cindex @file{/var/spool/mail} and Rmail
4344 This is the behavior of the @code{movemail} program which Rmail uses.
4345 This indicates that @code{movemail} is configured to use lock files.
4350 Certain systems require lock files to interlock access to mail files.
4351 On these systems, @code{movemail} must write lock files, or you risk losing
4352 mail. You simply must arrange to let @code{movemail} write them.
4354 Other systems use the @code{flock} system call to interlock access. On
4355 these systems, you should configure @code{movemail} to use @code{flock}.
4358 @node Replying to the sender of a message
4359 @section How can I force Rmail to reply to the sender of a message, but not the other recipients?
4360 @cindex Replying only to the sender of a message
4361 @cindex Sender, replying only to
4362 @cindex Rmail, replying to the sender of a message in
4364 @email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit
4365 @key{r} to reply in Rmail, by default it CCs all of the original
4366 recipients (everyone on the original @samp{To} and @samp{CC}
4367 lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
4368 it replies only to the sender. However, going through the whole
4369 @kbd{C-u} business every time you want to reply is a pain. This is the
4370 best fix I've been able to come up with:
4373 (defun rmail-reply-t ()
4374 "Reply only to the sender of the current message. (See rmail-reply.)"
4378 (add-hook 'rmail-mode-hook
4380 (define-key rmail-mode-map "r" 'rmail-reply-t)
4381 (define-key rmail-mode-map "R" 'rmail-reply)))
4384 @node Automatically starting a mail or news reader
4385 @section How do I make Emacs automatically start my mail/news reader?
4386 @cindex Mail reader, starting automatically
4387 @cindex News reader, starting automatically
4388 @cindex Starting mail/news reader automatically
4390 To start Emacs in Gnus:
4403 A more convenient way to start with Gnus:
4406 alias gnus 'emacs -f gnus'
4410 It is probably unwise to automatically start your mail or news reader
4411 from your @file{.emacs} file. This would cause problems if you needed to run
4412 two copies of Emacs at the same time. Also, this would make it difficult for
4413 you to start Emacs quickly when you needed to.
4415 @node Reading news with Emacs
4416 @section How do I read news under Emacs?
4417 @cindex Reading news under Emacs
4418 @cindex Usenet reader in Emacs
4419 @cindex Gnus newsreader
4420 @cindex FAQ for Gnus
4422 @cindex Learning more about Gnus
4424 Use @kbd{M-x gnus}. For more information on Gnus, @pxref{Top,, the Gnus
4425 Manual, gnus, The Gnus Manual}, which includes @ref{Frequently Asked
4426 Questions,, the Gnus FAQ, gnus}.
4429 @node Gnus does not work with NNTP
4430 @section Why doesn't Gnus work via NNTP?
4431 @cindex Gnus and NNTP
4432 @cindex NNTP, Gnus fails to work with
4434 There is a bug in NNTP version 1.5.10, such that when multiple requests
4435 are sent to the NNTP server, the server only handles the first one
4436 before blocking waiting for more input which never comes. NNTP version
4437 1.5.11 claims to fix this.
4439 You can work around the bug inside Emacs like this:
4442 (setq nntp-maximum-request 1)
4445 You can find out what version of NNTP your news server is running by
4446 telnetting to the NNTP port (usually 119) on the news server machine
4447 (i.e., @kbd{telnet server-machine 119}). The server should give its
4448 version number in the welcome message. Type @kbd{quit} to get out.
4450 @node Making Gnus faster
4451 @section How do I make Gnus faster?
4452 @cindex Faster, starting Gnus
4453 @cindex Starting Gnus faster
4454 @cindex Gnus, starting faster
4455 @cindex Slow catch up in Gnus
4456 @cindex Gnus is slow when catching up
4457 @cindex Crosspostings make Gnus catching up slow
4459 From the Gnus FAQ (@pxref{Reading news with Emacs}):
4462 If you have a slow machine, or are just really impatient, there are a
4463 few things you can do to make Gnus run faster.
4465 Set @code{gnus-check-new-newsgroups} and
4466 @code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster.
4468 Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and
4469 @code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the
4470 summary buffer faster.
4473 @node Catching up in all newsgroups
4474 @section How do I catch up all newsgroups in Gnus?
4475 @cindex Catching up all newsgroups in Gnus
4476 @cindex Gnus, Catching up all newsgroups in
4478 In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
4480 Leave off the initial @kbd{M-<} if you only want to catch up from point
4481 to the end of the @file{*Newsgroup*} buffer.
4484 @unnumbered Concept Index
4490 arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f