1 \input texinfo @c -*- mode: texinfo; -*-
3 @setfilename ../../info/efaq
4 @settitle GNU Emacs FAQ
7 @c This is used in many places
10 @c This file is maintained by Romain Francoise <rfrancoise@gnu.org>.
11 @c Feel free to install changes without prior permission (but I'd
12 @c appreciate a notice if you do).
15 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
16 Free Software Foundation, Inc.@*
17 Copyright @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
81 * Compiling and installing Emacs::
82 * Finding Emacs and related packages::
83 * Major packages and programs::
85 * Alternate character sets::
90 @c ------------------------------------------------------------
95 This chapter describes notation used in the GNU Emacs FAQ, as well as in
96 the Emacs documentation. Consult this section if this is the first time
97 you are reading the FAQ, or if you are confused by notation or terms
102 * Extended commands::
104 * File-name conventions::
109 @section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
111 @cindex Control key, notation for
112 @cindex @key{Meta} key, notation for
113 @cindex Control-Meta characters, notation for
114 @cindex @kbd{C-h}, definition of
115 @cindex @kbd{C-M-h}, definition of
116 @cindex @key{DEL}, definition of
117 @cindex @key{ESC}, definition of
118 @cindex @key{LFD}, definition of
119 @cindex @key{RET}, definition of
120 @cindex @key{SPC}, definition of
121 @cindex @key{TAB}, definition of
122 @cindex Notation for keys
127 @kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
130 @kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
131 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
134 @kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
138 @kbd{C-M-x}: a synonym for the above
141 @key{LFD}: Linefeed or Newline; same as @kbd{C-j}
144 @key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
147 @key{DEL}: @key{Delete}, usually @strong{not} the same as
148 @key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
149 deleting invokes Emacs help)
152 @key{ESC}: Escape; same as @kbd{C-[}
155 @key{TAB}: Tab; same as @kbd{C-i}
162 Key sequences longer than one key (and some single-key sequences) are
163 written inside quotes or on lines by themselves, like this:
166 @kbd{M-x frobnicate-while-foo RET}
170 Any real spaces in such a key sequence should be ignored; only @key{SPC}
171 really means press the space key.
173 The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
174 that would be sent by pressing just @key{x} minus 96 (or 64 for
175 upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
176 terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
177 @acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
178 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
180 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
183 @kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
184 @kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON.
185 Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
186 @c FIXME I cannot understand the previous sentence.
188 @inforef{Keys, Keys, emacs}, for more information. (@xref{Emacs
189 manual}, for more information about Info.)
191 @node Extended commands
192 @section What does @file{M-x @var{command}} mean?
193 @cindex Extended commands
194 @cindex Commands, extended
195 @cindex M-x, meaning of
197 @kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
198 command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
199 what @kbd{M-x} and @key{RET} mean.)
201 @kbd{M-x} (by default) invokes the command
202 @code{execute-extended-command}. This command allows you to run any
203 Emacs command if you can remember the command's name. If you can't
204 remember the command's name, you can type @key{TAB} and @key{SPC} for
205 completion, @key{?} for a list of possibilities, and @kbd{M-p} and
206 @kbd{M-n} (or up-arrow and down-arrow on terminals that have these
207 editing keys) to see previous commands entered. An Emacs @dfn{command}
208 is an @dfn{interactive} Emacs function.
211 Your system administrator may have bound other key sequences to invoke
212 @code{execute-extended-command}. A function key labeled @kbd{Do} is a
213 good candidate for this, on keyboards that have such a key.
215 If you need to run non-interactive Emacs functions, see @ref{Evaluating
219 @section How do I read topic XXX in the Emacs manual?
220 @cindex Emacs manual, reading topics in
221 @cindex Reading topics in the Emacs manual
222 @cindex Finding topics in the Emacs manual
223 @cindex Info, finding topics in
225 When we refer you to some @var{topic} in the Emacs manual, you can
226 read this manual node inside Emacs (assuming nothing is broken) by
227 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
229 This invokes Info, the GNU hypertext documentation browser. If you don't
230 already know how to use Info, type @key{?} from within Info.
232 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
233 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
235 If these commands don't work as expected, your system administrator may
236 not have installed the Info files, or may have installed them
237 improperly. In this case you should complain.
239 @xref{Getting a printed manual}, if you would like a paper copy of the
242 @node File-name conventions
243 @section What are @file{etc/GNU}, @file{src/config.h}, and @file{site-lisp/default.el}?
244 @cindex File-name conventions
245 @cindex Conventions for file names
246 @cindex Directories and files that come with Emacs
248 These are files that come with Emacs. The Emacs distribution is divided
249 into subdirectories; e.g. @file{etc}, @file{lisp}, and @file{src}.
251 If you use Emacs, but don't know where it is kept on your system, start
252 Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
253 name displayed by this will be the full pathname of the installed
254 @file{etc} directory. (This full path is recorded in the Emacs variable
255 @code{data-directory}, and @kbd{C-h v} displays the value and the
256 documentation of a variable.)
258 The location of your Info directory (i.e., where Info documentation
259 is stored) is kept in the variable @code{Info-default-directory-list}. Use
260 @kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
261 this variable, which will be a list of directory names. The last
262 directory in that list is probably where most Info files are stored. By
263 default, Info documentation is placed in @file{/usr/local/share/info}.
265 Some of these files are available individually via FTP or e-mail; see
266 @ref{Informational files for Emacs}. They all are available in the
267 source distribution. Many of the files in the @file{etc} directory are
268 also available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?}
269 (@kbd{M-x help-for-help}).
271 @node Common acronyms
272 @section What are FSF, LPF, GNU, RMS, FTP, and GPL?
273 @cindex FSF, definition of
274 @cindex LPF, definition of
275 @cindex GNU, definition of
276 @cindex RMS, definition of
277 @cindex Stallman, Richard, acronym for
278 @cindex Richard Stallman, acronym for
279 @cindex FTP, definition of
280 @cindex GPL, definition of
281 @cindex Acronyms, definitions for
282 @cindex Common acronyms, definitions for
287 Free Software Foundation
290 League for Programming Freedom
296 Richard Matthew Stallman
299 File Transfer Protocol
302 GNU General Public License
306 Avoid confusing the FSF and the LPF. The LPF opposes
307 look-and-feel copyrights and software patents. The FSF aims to make
308 high quality free software available for everyone.
310 The word ``free'' in the title of the Free Software Foundation refers to
311 ``freedom,'' not ``zero cost.'' Anyone can charge any price for
312 GPL-covered software that they want to. However, in practice, the
313 freedom enforced by the GPL leads to low prices, because you can always
314 get the software for less money from someone else, since everyone has
315 the right to resell or give away GPL-covered software.
317 @c ------------------------------------------------------------
318 @node General questions
319 @chapter General questions
320 @cindex General questions
322 This chapter contains general questions having to do with Emacs, the
323 Free Software Foundation, and related organizations.
327 * Real meaning of copyleft::
328 * Guidelines for newsgroup postings::
329 * Newsgroup archives::
331 * Unsubscribing from Emacs lists::
332 * Contacting the FSF::
336 @section What is the LPF?
337 @cindex LPF, description of
338 @cindex League for Programming Freedom
339 @cindex Software patents, opposition to
340 @cindex Patents for software, opposition to
342 The LPF opposes the expanding danger of software patents and
343 look-and-feel copyrights. More information on the LPF's views is
344 available at @uref{http://progfree.org/, the LPF home page}.
346 @node Real meaning of copyleft
347 @section What is the real legal meaning of the GNU copyleft?
348 @cindex Copyleft, real meaning of
349 @cindex GPL, real meaning of
350 @cindex General Public License, real meaning of
351 @cindex Discussion of the GPL
353 The real legal meaning of the GNU General Public License (copyleft) will
354 only be known if and when a judge rules on its validity and scope.
355 There has never been a copyright infringement case involving the GPL to
356 set any precedents. Although legal actions have been brought against
357 companies for violating the terms of the GPL, so far all have been
358 settled out of court (in favour of the plaintiffs). Please take any
359 discussion regarding this issue to the newsgroup
360 @uref{news:gnu.misc.discuss}, which was created to hold the extensive
361 flame wars on the subject.
366 The legal meaning of the GNU copyleft is less important than the spirit,
367 which is that Emacs is a free software project and that work pertaining
368 to Emacs should also be free software. ``Free'' means that all users
369 have the freedom to study, share, change and improve Emacs. To make
370 sure everyone has this freedom, pass along source code when you
371 distribute any version of Emacs or a related program, and give the
372 recipients the same freedom that you enjoyed.
375 @node Guidelines for newsgroup postings
376 @section What are appropriate messages for the various Emacs newsgroups?
377 @cindex Newsgroups, appropriate messages for
378 @cindex GNU newsgroups, appropriate messages for
379 @cindex Usenet groups, appropriate messages for
380 @cindex Mailing lists, appropriate messages for
381 @cindex Posting messages to newsgroups
383 @cindex GNU mailing lists
384 The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
385 mailing list. (@xref{Informational files for Emacs}, if you want a copy
386 of the file.) For those lists which are gatewayed with newsgroups, it
387 lists both the newsgroup name and the mailing list address.
389 The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
390 in general. The newsgroup @uref{news:gnu.emacs.help} is specifically
393 Messages advocating ``non-free'' software are considered unacceptable on
394 any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
395 which was created to hold the extensive flame-wars on the subject.
396 ``Non-free'' software includes any software for which the end user can't
397 freely modify the source code and exchange enhancements. Be careful to
398 remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
399 posting a followup that recommends such software.
401 @uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
402 posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
404 @node Newsgroup archives
405 @section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
406 @cindex Archived postings from @code{gnu.emacs.help}
407 @cindex Usenet archives for GNU groups
408 @cindex Old Usenet postings for GNU groups
410 The FSF has maintained archives of all of the GNU mailing lists for many
411 years, although there may be some unintentional gaps in coverage. The
412 archive is not particularly well organized or easy to retrieve
413 individual postings from, but pretty much everything is there.
415 The archive is at @uref{ftp://lists.gnu.org/}.
417 The archive can be browsed over the web at
418 @uref{http://lists.gnu.org/archive/html/, the GNU mail archive}.
420 Web-based Usenet search services, such as
421 @uref{http://groups.google.com/groups/dir?q=gnu&, Google}, also
422 archive the @code{gnu.*} groups.
424 You can read the archives of the @code{gnu.*} groups and post new
425 messages at @uref{http://gmane.org/, Gmane}. Gmane is a service that
426 presents mailing lists as newsgroups.
429 @section Where should I report bugs and other problems with Emacs?
430 @cindex Bug reporting
431 @cindex Good bug reports
432 @cindex How to submit a bug report
433 @cindex Reporting bugs
435 The correct way to report Emacs bugs is to use the command
436 @kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
437 essential information and the correct e-mail address, which is
438 @email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs.
439 Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the
440 newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
441 news to submit the bug report. This ensures a reliable return address
442 so you can be contacted for further details.
444 Be sure to read the ``Bugs'' section of the Emacs manual before reporting
445 a bug! The manual describes in detail how to submit a useful bug
446 report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
447 (@xref{Emacs manual}, if you don't know how to read the manual.)
452 Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
453 effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
454 it takes the time of an unnecessarily large group of people, most of
455 whom are just users and have no idea how to fix these problem.
456 @email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
457 who are more likely to know what to do and have expressed a wish to
458 receive more messages about Emacs than the others.
461 RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
464 If you have reported a bug and you don't hear about a possible fix,
465 then after a suitable delay (such as a week) it is okay to post on
466 @code{gnu.emacs.help} asking if anyone can help you.
469 If you are unsure whether you have found a bug, consider the following
470 non-exhaustive list, courtesy of RMS:
473 If Emacs crashes, that is a bug. If Emacs gets compilation errors
474 while building, that is a bug. If Emacs crashes while building, that
475 is a bug. If Lisp code does not do what the documentation says it
479 @node Unsubscribing from Emacs lists
480 @section How do I unsubscribe from a mailing list?
481 @cindex Unsubscribing from GNU mailing lists
482 @cindex Removing yourself from GNU mailing lists
484 If you are receiving a GNU mailing list named @var{list}, you should be
485 able to unsubscribe from it by sending a request to the address
486 @email{@var{list}-request@@gnu.org}. Mailing lists mails normally
487 contain information in either the message header
488 (@samp{List-Unsubscribe:}) or as a footer that tells you how to
491 @node Contacting the FSF
492 @section What is the current address of the FSF?
493 @cindex Snail mail address of the FSF
494 @cindex Postal address of the FSF
495 @cindex Contracting the FSF
496 @cindex Free Software Foundation, contacting
510 @uref{http://www.fsf.org/}
513 Free Software Foundation@*
514 51 Franklin Street, Fifth Floor@*
515 Boston, MA 02110-1301@*
520 @cindex Ordering GNU software
521 For details on how to order items directly from the FSF, see the
522 @uref{http://shop.fsf.org/, FSF on-line store}.
524 @c ------------------------------------------------------------
526 @chapter Getting help
529 This chapter tells you how to get help with Emacs.
533 * Learning how to do something::
534 * Getting a printed manual::
535 * Emacs Lisp documentation::
536 * Installing Texinfo documentation::
537 * Printing a Texinfo file::
538 * Viewing Info files outside of Emacs::
539 * Informational files for Emacs::
540 * Help installing Emacs::
541 * Obtaining the FAQ::
545 @section I'm just starting Emacs; how do I do basic editing?
546 @cindex Basic editing with Emacs
547 @cindex Beginning editing
548 @cindex Tutorial, invoking the
549 @cindex Self-paced tutorial, invoking the
550 @cindex Help system, entering the
552 Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
553 @kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
554 is available in many foreign languages such as French, German, Japanese,
555 Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
556 to choose your language and start the tutorial.
558 Your system administrator may have changed @kbd{C-h} to act like
559 @key{DEL} to deal with local keyboards. You can use @kbd{M-x
560 help-for-help} instead to invoke help. To discover what key (if any)
561 invokes help on your system, type @kbd{M-x where-is @key{RET}
562 help-for-help @key{RET}}. This will print a comma-separated list of key
563 sequences in the echo area. Ignore the last character in each key
564 sequence listed. Each of the resulting key sequences (e.g. @key{F1} is
565 common) invokes help.
567 Emacs help works best if it is invoked by a single key whose value
568 should be stored in the variable @code{help-char}.
570 @node Learning how to do something
571 @section How do I find out how to do something in Emacs?
572 @cindex Help for Emacs
573 @cindex Learning to do something in Emacs
574 @cindex Reference card for Emacs
575 @cindex Overview of help systems
577 There are several methods for finding out how to do things in Emacs.
581 @cindex Reading the Emacs manual
583 The complete text of the Emacs manual is available via the Info
584 hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
585 Typing @key{h} immediately after entering Info will provide a short
586 tutorial on how to use it.
588 @cindex Lookup a subject in a manual
589 @cindex Index search in a manual
591 To quickly locate the section of the manual which discusses a certain
592 issue, or describes a command or a variable, type @kbd{C-h i m emacs
593 @key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
594 topic, the command, or the variable which you are looking for. If this
595 does not land you on the right place in the manual, press @kbd{,}
596 (comma) repeatedly until you find what you need. (The @kbd{i} and
597 @kbd{,} keys invoke the index-searching functions, which look for the
598 @var{topic} you type in all the indices of the Emacs manual.)
602 You can list all of the commands whose names contain a certain word
603 (actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
606 @cindex Command description in the manual
608 The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
609 for the name of a command, and then attempts to find the section in the
610 Emacs manual where that command is described.
612 @cindex Finding commands and variables
614 You can list all of the functions and variables whose names contain a
615 certain word using @kbd{M-x apropos}.
618 You can list all of the functions and variables whose documentation
619 matches a regular expression or a string, using @kbd{M-x
620 apropos-documentation}.
623 You can order a hardcopy of the manual from the FSF. @xref{Getting a
626 @cindex Reference cards, in other languages
628 You can get a printed reference card listing commands and keys to
629 invoke them. You can order one from the FSF for $2 (or 10 for $18),
630 or you can print your own from the @file{etc/refcards/refcard.tex} or
631 @file{etc/refcards/refcard.pdf} files in the Emacs distribution.
632 Beginning with version 21.1, the Emacs distribution comes with
633 translations of the reference card into several languages; look for
634 files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang}
635 is a two-letter code of the language. For example, the German version
636 of the reference card is in the files @file{etc/refcards/de-refcard.tex}
637 and @file{etc/recards/de-refcard.pdf}.
640 There are many other commands in Emacs for getting help and
641 information. To get a list of these commands, type @samp{?} after
646 @node Getting a printed manual
647 @section How do I get a printed copy of the Emacs manual?
648 @cindex Printed Emacs manual, obtaining
649 @cindex Manual, obtaining a printed or HTML copy of
650 @cindex Emacs manual, obtaining a printed or HTML copy of
652 You can order a printed copy of the Emacs manual from the FSF. For
653 details see the @uref{http://shop.fsf.org/, FSF on-line store}.
655 The full Texinfo source for the manual also comes in the @file{doc/emacs}
656 directory of the Emacs distribution, if you're daring enough to try to
657 print out this several-hundred-page manual yourself (@pxref{Printing a Texinfo
660 If you absolutely have to print your own copy, and you don't have @TeX{},
661 you can get a PostScript or PDF (or HTML) version from
663 @uref{http://www.gnu.org/software/emacs/manual/}
665 @xref{Learning how to do something}, for how to view the manual.
667 @node Emacs Lisp documentation
668 @section Where can I get documentation on Emacs Lisp?
669 @cindex Documentation on Emacs Lisp
670 @cindex Function documentation
671 @cindex Variable documentation
672 @cindex Emacs Lisp Reference Manual
673 @cindex Reference manual for Emacs Lisp
675 Within Emacs, you can type @kbd{C-h f} to get the documentation for a
676 function, @kbd{C-h v} for a variable.
678 For more information, the Emacs Lisp Reference Manual is available
679 in Info format. @xref{Top, Emacs Lisp,, elisp, The
680 Emacs Lisp Reference Manual}.
682 You can also order a hardcopy of the manual, details on ordering it from
683 FSF are on the @uref{http://shop.fsf.org/, FSF on-line store}.
685 An HTML version of the Emacs Lisp Reference Manual is available at
687 @uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
689 @node Installing Texinfo documentation
690 @section How do I install a piece of Texinfo documentation?
691 @cindex Texinfo documentation, installing
692 @cindex Installing Texinfo documentation
693 @cindex New Texinfo files, installing
694 @cindex Documentation, installing new Texinfo files
695 @cindex Info files, how to install
697 First, you must turn the Texinfo files into Info files. You may do this
698 using the stand-alone @file{makeinfo} program, available as part of the
701 @uref{http://www.gnu.org/software/texinfo/}
703 For information about the Texinfo format, read the Texinfo manual which
704 comes with the Texinfo package. This manual also comes installed in
705 Info format, so you can read it from Emacs; type @kbd{C-h i m texinfo
708 Alternatively, you could use the Emacs command @kbd{M-x
709 texinfo-format-buffer}, after visiting the Texinfo source file of the
710 manual you want to convert.
712 Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
713 resulting Info files in Emacs's Info tree. To install Info files,
718 Move the files to the @file{info} directory in the installed Emacs
719 distribution. @xref{File-name conventions}, if you don't know where that
723 Run the @code{install-info} command, which is part of the Texinfo
724 distribution, to update the main Info directory menu, like this:
727 install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
731 where @var{dir-path} is the full path to the directory where you copied
732 the produced Info file(s), and @var{file} is the name of the Info file
733 you produced and want to install.
735 If you don't have the @code{install-info} command installed, you can
736 edit the file @file{info/dir} in the installed Emacs distribution, and
737 add a line for the top level node in the Info package that you are
738 installing. Follow the examples already in this file. The format is:
741 * Topic: (relative-pathname). Short description of topic.
746 If you want to install Info files and you don't have the necessary
747 privileges, you have several options:
751 Info files don't actually need to be installed before being used.
752 You can use a prefix argument for the @code{info} command and specify
753 the name of the Info file in the minibuffer. This goes to the node
754 named @samp{Top} in that file. For example, to view a Info file named
755 @file{@var{info-file}} in your home directory, you can type this:
758 @kbd{C-u C-h i ~/@var{info-file} @key{RET}}
761 Alternatively, you can feed a file name to the @code{Info-goto-node}
762 command (invoked by pressing @key{g} in Info mode) by typing the name
763 of the file in parentheses, like this:
766 @kbd{C-h i g (~/@var{info-file}) @key{RET}}
770 You can create your own Info directory. You can tell Emacs where that
771 Info directory is by adding its pathname to the value of the variable
772 @code{Info-default-directory-list}. For example, to use a private Info
773 directory which is a subdirectory of your home directory named @file{Info},
774 you could put this in your @file{.emacs} file:
777 (setq Info-default-directory-list
778 (cons "~/Info" Info-default-directory-list))
781 You will need a top-level Info file named @file{dir} in this directory
782 which has everything the system @file{dir} file has in it, except it should
783 list only entries for Info files in that directory. You might not need
784 it if all files in this directory were referenced by other @file{dir}
785 files. The node lists from all @file{dir} files in
786 @code{Info-default-directory-list} are merged by the Info system.
790 @node Printing a Texinfo file
791 @section How do I print a Texinfo file?
792 @cindex Printing a Texinfo file
793 @cindex Texinfo file, printing
794 @cindex Printing documentation
796 You can't get nicely printed output from Info files; you must still have
797 the original Texinfo source file for the manual you want to print.
799 Assuming you have @TeX{} installed on your system, follow these steps:
804 Make sure the first line of the Texinfo file looks like this:
810 You may need to change @samp{texinfo} to the full pathname of the
811 @file{texinfo.tex} file, which comes with Emacs as
812 @file{doc/misc/texinfo.tex} (or copy or link it into the current directory).
815 Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
816 the name of the Texinfo source file for which you want to produce a
819 The @samp{texi2dvi} script is part of the GNU Texinfo distribution
820 (@pxref{Installing Texinfo documentation}).
822 Alternatively, @samp{texi2pdf} produces PDF files.
825 Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
826 printing DVI files at your site. For example, if you have a PostScript
827 printer, run the @code{dvips} program to print the DVI file on that
832 To get more general instructions, retrieve the latest Texinfo package
833 (@pxref{Installing Texinfo documentation}).
835 @node Viewing Info files outside of Emacs
836 @section Can I view Info files without using Emacs?
837 @cindex Viewing Info files
838 @cindex Info file viewers
839 @cindex Alternative Info file viewers
841 Yes. Here are some alternative programs:
846 @code{info}, a stand-alone version of the Info program, comes as part of
847 the Texinfo package. @xref{Installing Texinfo documentation}, for
851 Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
852 You can get Tkinfo at
853 @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
857 @node Informational files for Emacs
858 @section What informational files are available for Emacs?
859 @cindex Informational files included with Emacs
860 @cindex Files included with Emacs
861 @cindex @file{COPYING}, description of file
862 @cindex @file{DISTRIB}, description of file
863 @cindex @file{GNU}, description of file
864 @cindex @file{INTERVIEW}, description of file
865 @cindex @file{MACHINES}, description of file
866 @cindex @file{MAILINGLISTS}, description of file
867 @cindex @file{NEWS}, description of file
869 This isn't a frequently asked question, but it should be! A variety of
870 informational files about Emacs and relevant aspects of the GNU project
871 are available for you to read.
873 The following files are available in the @file{etc} directory of the
874 Emacs distribution (see @ref{File-name conventions}, if you're not sure
880 GNU General Public License
883 Emacs Availability Information
889 Richard Stallman discusses his public-domain UNIX-compatible software
890 system with BYTE editors
893 Status of Emacs on Various Machines and Systems
896 GNU Project Electronic Mailing Lists
899 Emacs news, a history of recent user-visible changes
903 More GNU information, including back issues of the @cite{GNU's
906 @uref{http://www.gnu.org/bulletins/bulletins.html} and
908 @uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
910 @node Help installing Emacs
911 @section Where can I get help in installing Emacs?
912 @cindex Installation help
913 @cindex Help installing Emacs
915 @xref{Installing Emacs}, for some basic installation hints, and see
916 @ref{Problems building Emacs}, if you have problems with the installation.
918 The web-page @uref{http://www.fsf.org/resources/service/} lists
919 companies and individuals willing to sell you help in installing or
922 @node Obtaining the FAQ
923 @section Where can I get the latest version of this FAQ?
924 @cindex FAQ, obtaining the
925 @cindex Latest FAQ version, obtaining the
927 The Emacs FAQ is distributed with Emacs in Info format. You can read it
928 by selecting the @samp{Emacs FAQ} option from the @samp{Help} menu of
929 the Emacs menu bar at the top of any Emacs frame, or by typing @kbd{C-h
930 C-f} (@kbd{M-x view-emacs-FAQ}).
933 @c ------------------------------------------------------------
934 @node Status of Emacs
935 @chapter Status of Emacs
936 @cindex Status of Emacs
938 This chapter gives you basic information about Emacs, including the
939 status of its latest version.
942 * Origin of the term Emacs::
943 * Latest version of Emacs::
950 @node Origin of the term Emacs
951 @section Where does the name ``Emacs'' come from?
952 @cindex Origin of the term ``Emacs''
953 @cindex Emacs name origin
955 @cindex Original version of Emacs
957 Emacs originally was an acronym for Editor MACroS. RMS says he ``picked
958 the name Emacs because @key{E} was not in use as an abbreviation on ITS at
959 the time.'' The first Emacs was a set of macros written in 1976 at MIT
960 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
961 Editor and COrrector) under ITS on a PDP-10. RMS had already extended
962 TECO with a ``real-time'' full-screen mode with reprogrammable keys.
963 Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project
964 to unify the many divergent TECO command sets and key bindings at MIT,
965 and completed by RMS.
967 Many people have said that TECO code looks a lot like line noise; you
968 can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
969 implementation in Emacs Lisp (to find it, see @ref{Packages that do not
970 come with Emacs}); it would be an interesting project to run the
971 original TECO Emacs inside of Emacs.
974 For some not-so-serious alternative reasons for Emacs to have that
975 name, check out the file @file{etc/JOKES} (@pxref{File-name
978 @node Latest version of Emacs
979 @section What is the latest version of Emacs?
980 @cindex Version, latest
981 @cindex Latest version of Emacs
983 Emacs @value{VER} is the current version as of this writing. A version
984 number with two components (e.g. @samp{22.1}) indicates a released
985 version; three components indicate a development
986 version (e.g. @samp{23.0.50} is what will eventually become @samp{23.1}).
988 Because Emacs undergoes many changes before a release, the version
989 number of a development version is not especially meaningful. It is
990 better to refer to the date on which the sources were retrieved from the
991 development repository.
993 The following sections list some of the major new features in the last
994 few Emacs releases. For full details of the changes in any version of
995 Emacs, type @kbd{C-h C-n} (@kbd{M-x view-emacs-news}). As of Emacs 22,
996 you can give this command a prefix argument to read about which features
997 were new in older versions.
999 @node New in Emacs 23
1000 @section What is different about Emacs 23?
1001 @cindex Differences between Emacs 22 and Emacs 23
1002 @cindex Emacs 23, new features in
1003 @cindex Recently introduced features
1004 @cindex Default features
1008 @cindex Anti-aliased fonts
1009 @cindex Freetype fonts
1011 Emacs has a new font code that can use multiple font backends,
1012 including freetype and fontconfig. Emacs can use the Xft library for
1013 anti-aliasing, and the otf and m17n libraries for complex text layout and
1017 @cindex Character sets
1019 The Emacs character set is now a superset of Unicode. Several new
1020 language environments have been added.
1022 @cindex Multi-tty support
1023 @cindex X and tty displays
1025 Emacs now supports using both X displays and ttys in the same session
1030 Emacs can be started as a daemon in the background.
1032 @cindex NeXTSTEP port
1033 @cindex GNUstep port
1034 @cindex Mac OS X Cocoa
1036 There is a new NeXTSTEP port of Emacs. This supports GNUstep and Mac OS
1037 X (via the Cocoa libraries). The Carbon port of Emacs, which supported
1038 Mac OS X in Emacs 22, has been removed.
1040 @cindex Directory-local variables
1042 Directory-local variables can now be defined, in a similar manner to
1043 file-local variables.
1046 Transient Mark mode (@pxref{Highlighting a region}) is on by default.
1051 Other changes include: support for serial port access; D-Bus bindings; a
1052 new Visual Line mode for line-motion; improved completion; a new mode
1053 (@samp{DocView}) for viewing of PDF, PostScript, and DVI documents; nXML
1054 mode (for editing XML documents) is included; VC has been updated for
1055 newer version control systems; etc. As always, consult the @file{NEWS}
1056 file for more information.
1059 @node New in Emacs 22
1060 @section What is different about Emacs 22?
1061 @cindex Differences between Emacs 21 and Emacs 22
1062 @cindex Emacs 22, new features in
1065 @cindex GTK+ Toolkit
1066 @cindex Drag-and-drop
1068 Emacs can be built with GTK+ widgets, and supports drag-and-drop
1071 @cindex Supported systems
1073 Emacs 22 features support for GNU/Linux systems on S390 and x86-64
1074 machines, as well as support for the Mac OS X and Cygwin operating
1078 The native MS-Windows, and Mac OS X builds include full support
1079 for images, toolbar, and tooltips.
1082 Font Lock mode, Auto Compression mode, and File Name Shadow Mode are
1086 The maximum size of buffers has been doubled and is 256M on 32-bit
1090 Links can be followed with @kbd{mouse-1}, in addition to @kbd{mouse-2}.
1094 Mouse wheel support is enabled by default.
1097 Window fringes are customizable.
1100 The mode line of the selected window is now highlighted.
1103 The minibuffer prompt is displayed in a distinct face.
1106 Abbrev definitions are read automatically at startup.
1109 Grep mode is separate from Compilation mode and has many new options and
1110 commands specific to grep.
1113 The original Emacs macro system has been replaced by the new Kmacro
1114 package, which provides many new commands and features and a simple
1115 interface that uses the function keys F3 and F4. Macros are stored in a
1116 macro ring, and can be debugged and edited interactively.
1119 The Grand Unified Debugger (GUD) can be used with a full graphical user
1120 interface to GDB; this provides many features found in traditional
1121 development environments, making it easy to manipulate breakpoints, add
1122 watch points, display the call stack, etc. Breakpoints are visually
1123 indicated in the source buffer.
1127 Many new modes and packages have been included in Emacs, such as Calc,
1128 TRAMP, URL, IDO, CUA, ERC, rcirc, Table, Image-Dired, SES, Ruler, Org,
1129 PGG, Flymake, Password, Printing, Reveal, wdired, t-mouse, longlines,
1130 savehist, Conf mode, Python mode, DNS mode, etc.
1132 @cindex Multilingual Environment
1134 Leim is now part of Emacs. Unicode support has been much improved, and
1135 the following input methods have been added: belarusian, bulgarian-bds,
1136 bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian,
1137 latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard,
1138 lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345,
1139 russian-computer, sgml, slovenian, tamil-inscript, ucs,
1140 ukrainian-computer, vietnamese-telex, and welsh.
1142 The following language environments have also been added: Belarusian,
1143 Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6,
1144 Latin-7, Latvian, Lithuanian, Malayalam, Russian, Slovenian, Swedish,
1145 Tajik, Tamil, UTF-8, Ukrainian, Welsh, and Windows-1255.
1147 @cindex Documentation
1148 @cindex Emacs Lisp Manual
1150 In addition, Emacs 22 now includes the Emacs Lisp Reference Manual
1151 (@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro.
1155 @node New in Emacs 21
1156 @section What is different about Emacs 21?
1157 @cindex Differences between Emacs 20 and Emacs 21
1158 @cindex Emacs 21, new features in
1160 @cindex Variable-size fonts
1161 @cindex Toolbar support
1162 Emacs 21 features a thorough rewrite of the display engine. The new
1163 display engine supports variable-size fonts, images, and can play sounds
1164 on platforms which support that. As a result, the visual appearance of
1165 Emacs, when it runs on a windowed display, is much more reminiscent of
1166 modern GUI programs, and includes 3D widgets (used for the mode line and
1167 the scroll bars), a configurable and extensible toolbar, tooltips
1168 (a.k.a.@: balloon help), and other niceties.
1170 @cindex Colors on text-only terminals
1172 In addition, Emacs 21 supports faces on text-only terminals. This means
1173 that you can now have colors when you run Emacs on a GNU/Linux console
1174 and on @code{xterm} with @kbd{emacs -nw}.
1177 @node New in Emacs 20
1178 @section What is different about Emacs 20?
1179 @cindex Differences between Emacs 19 and Emacs 20
1180 @cindex Emacs 20, new features in
1182 The differences between Emacs versions 18 and 19 were rather dramatic;
1183 the introduction of frames, faces, and colors on windowing systems was
1184 obvious to even the most casual user.
1186 There are differences between Emacs versions 19 and 20 as well, but many
1187 are more subtle or harder to find. Among the changes are the inclusion
1188 of MULE code for languages that use non-Latin characters and for mixing
1189 several languages in the same document; the ``Customize'' facility for
1190 modifying variables without having to use Lisp; and automatic conversion
1191 of files from Macintosh, Microsoft, and Unix platforms.
1193 @c ------------------------------------------------------------
1194 @node Common requests
1195 @chapter Common requests
1196 @cindex Common requests
1199 * Setting up a customization file::
1202 * Debugging a customization file::
1203 * Displaying the current line or column::
1204 * Displaying the current file name in the titlebar::
1205 * Turning on abbrevs by default::
1206 * Associating modes with files::
1207 * Highlighting a region::
1208 * Replacing highlighted text::
1209 * Controlling case sensitivity::
1210 * Working with unprintable characters::
1211 * Searching for/replacing newlines::
1212 * Yanking text in isearch::
1213 * Wrapping words automatically::
1214 * Turning on auto-fill by default::
1215 * Changing load-path::
1216 * Using an already running Emacs process::
1217 * Compiler error messages::
1218 * Indenting switch statements::
1219 * Customizing C and C++ indentation::
1220 * Horizontal scrolling::
1222 * Turning off beeping::
1223 * Turning the volume down::
1224 * Automatic indentation::
1225 * Matching parentheses::
1226 * Hiding #ifdef lines::
1227 * Repeating commands::
1228 * Valid X resources::
1229 * Evaluating Emacs Lisp code::
1230 * Changing the length of a Tab::
1231 * Inserting text at the beginning of each line::
1232 * Underlining paragraphs::
1233 * Forcing the cursor to remain in the same column::
1234 * Forcing Emacs to iconify itself::
1235 * Using regular expressions::
1236 * Replacing text across multiple files::
1237 * Documentation for etags::
1238 * Disabling backups::
1239 * Disabling auto-save-mode::
1240 * Going to a line by number::
1241 * Modifying pull-down menus::
1242 * Deleting menus and menu options::
1243 * Turning on syntax highlighting::
1244 * Scrolling only one line::
1245 * Editing MS-DOS files::
1246 * Filling paragraphs with a single space::
1247 * Escape sequences in shell output::
1248 * Fullscreen mode on MS-Windows::
1251 @node Setting up a customization file
1252 @section How do I set up a @file{.emacs} file properly?
1253 @cindex @file{.emacs} file, setting up
1254 @cindex @file{.emacs} file, locating
1255 @cindex Init file, setting up
1256 @cindex Customization file, setting up
1258 @inforef{Init File, Init File, emacs}.
1260 In general, new Emacs users should not be provided with @file{.emacs}
1261 files, because this can cause confusing non-standard behavior. Then
1262 they send questions to @email{help-gnu-emacs@@gnu.org} asking why Emacs
1263 isn't behaving as documented.
1265 Emacs includes the Customize facility (@pxref{Using Customize}). This
1266 allows users who are unfamiliar with Emacs Lisp to modify their
1267 @file{.emacs} files in a relatively straightforward way, using menus
1268 rather than Lisp code.
1270 While Customize might indeed make it easier to configure Emacs,
1271 consider taking a bit of time to learn Emacs Lisp and modifying your
1272 @file{.emacs} directly. Simple configuration options are described
1273 rather completely in @inforef{Init File, Init File, emacs}, for users
1274 interested in performing frequently requested, basic tasks.
1276 Sometimes users are unsure as to where their @file{.emacs} file should
1277 be found. Visiting the file as @file{~/.emacs} from Emacs will find
1280 @node Using Customize
1281 @section How do I start using Customize?
1282 @cindex Customize groups
1283 @cindex Customizing variables
1284 @cindex Customizing faces
1286 The main Customize entry point is @kbd{M-x customize @key{RET}}. This
1287 command takes you to a buffer listing all the available Customize
1288 groups. From there, you can access all customizable options and faces,
1289 change their values, and save your changes to your init file.
1290 @inforef{Easy Customization, Easy Customization, emacs}.
1292 If you know the name of the group in advance (e.g. ``shell''), use
1293 @kbd{M-x customize-group @key{RET}}.
1295 If you wish to customize a single option, use @kbd{M-x customize-option
1296 @key{RET}}. This command prompts you for the name of the option to
1297 customize, with completion.
1299 @node Colors on a TTY
1300 @section How do I get colors and syntax highlighting on a TTY?
1301 @cindex Colors on a TTY
1302 @cindex Syntax highlighting on a TTY
1303 @cindex Console, colors
1305 In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
1306 i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when
1307 invoked as @samp{emacs -nw} on X, and MS-Windows. (Colors and faces were
1308 supported in the MS-DOS port since Emacs 19.29.) Emacs automatically
1309 detects color support at startup and uses it if available. If you think
1310 that your terminal supports colors, but Emacs won't use them, check the
1311 @code{termcap} entry for your display type for color-related
1314 The command @kbd{M-x list-colors-display} pops up a window which
1315 exhibits all the colors Emacs knows about on the current display.
1317 Syntax highlighting is on by default since version 22.1.
1319 @node Debugging a customization file
1320 @section How do I debug a @file{.emacs} file?
1321 @cindex Debugging @file{.emacs} file
1322 @cindex @file{.emacs} debugging
1323 @cindex Init file debugging
1324 @cindex @samp{-debug-init} option
1326 Start Emacs with the @samp{-debug-init} command-line option. This
1327 enables the Emacs Lisp debugger before evaluating your @file{.emacs}
1328 file, and places you in the debugger if something goes wrong. The top
1329 line in the @file{trace-back} buffer will be the error message, and the
1330 second or third line of that buffer will display the Lisp code from your
1331 @file{.emacs} file that caused the problem.
1333 You can also evaluate an individual function or argument to a function
1334 in your @file{.emacs} file by moving the cursor to the end of the
1335 function or argument and typing @kbd{C-x C-e} (@kbd{M-x
1338 Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
1339 variables which you are trying to set or use.
1341 @node Displaying the current line or column
1342 @section How do I make Emacs display the current line (or column) number?
1343 @cindex @code{line-number-mode}
1344 @cindex Displaying the current line or column
1345 @cindex Line number, displaying the current
1346 @cindex Column, displaying the current
1347 @cindex @code{mode-line-format}
1349 By default, Emacs displays the current line number of the point in the
1350 mode line. You can toggle this feature off or on with the command
1351 @kbd{M-x line-number-mode}, or by setting the variable
1352 @code{line-number-mode}. Note that Emacs will not display the line
1353 number if the buffer's size in bytes is larger than the value of the
1354 variable @code{line-number-display-limit}.
1356 You can similarly display the current column with
1357 @kbd{M-x column-number-mode}, or by putting the form
1360 (setq column-number-mode t)
1364 in your @file{.emacs} file. This feature is off by default.
1366 The @code{"%c"} format specifier in the variable @code{mode-line-format}
1367 will insert the current column's value into the mode line. See the
1368 documentation for @code{mode-line-format} (using @kbd{C-h v
1369 mode-line-format @key{RET}}) for more information on how to set and use
1372 @cindex Set number capability in @code{vi} emulators
1373 The @samp{linum} package (distributed with Emacs since version 23.1)
1374 displays line numbers in the left margin, like the ``set number''
1375 capability of @code{vi}. The packages @samp{setnu} and
1376 @samp{wb-line-number} (not distributed with Emacs) also implement this
1379 @node Displaying the current file name in the titlebar
1380 @section How can I modify the titlebar to contain the current file name?
1381 @cindex Titlebar, displaying the current file name in
1382 @cindex File name, displaying in the titlebar
1383 @cindex @code{frame-title-format}
1385 The contents of an Emacs frame's titlebar is controlled by the variable
1386 @code{frame-title-format}, which has the same structure as the variable
1387 @code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x
1388 describe-variable} to get information about one or both of these
1391 By default, the titlebar for a frame does contain the name of the buffer
1392 currently being visited, except if there is a single frame. In such a
1393 case, the titlebar contains Emacs invocation name and the name of the
1394 machine at which Emacs was invoked. This is done by setting
1395 @code{frame-title-format} to the default value of
1398 (multiple-frames "%b" ("" invocation-name "@@" system-name))
1401 To modify the behavior such that frame titlebars contain the buffer's
1402 name regardless of the number of existing frames, include the following
1403 in your @file{.emacs}:
1406 (setq frame-title-format "%b")
1409 @node Turning on abbrevs by default
1410 @section How do I turn on abbrevs by default just in mode @var{mymode}?
1411 @cindex Abbrevs, turning on by default
1413 Abbrev mode expands abbreviations as you type them. To turn it on in a
1414 specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every
1415 buffer by default, put this in your @file{.emacs} file:
1418 (setq-default abbrev-mode t)
1421 @noindent To turn it on in a specific mode, use:
1424 (add-hook '@var{mymode}-mode-hook
1426 (setq abbrev-mode t)))
1429 @noindent If your Emacs version is older then 22.1, you will also need to use:
1433 (quietly-read-abbrev-file)
1437 @node Associating modes with files
1438 @section How do I make Emacs use a certain major mode for certain files?
1439 @cindex Associating modes with files
1440 @cindex File extensions and modes
1441 @cindex @code{auto-mode-alist}, modifying
1442 @cindex Modes, associating with file extensions
1444 If you want to use a certain mode @var{foo} for all files whose names end
1445 with the extension @file{.@var{bar}}, this will do it for you:
1448 (add-to-list 'auto-mode-alist '("\\.@var{bar}\\'" . @var{foo}-mode))
1451 Alternatively, put this somewhere in the first line of any file you want to
1452 edit in the mode @var{foo} (in the second line, if the first line begins
1459 @cindex Major mode for shell scripts
1460 The variable @code{interpreter-mode-alist} specifies which mode to use
1461 when loading an interpreted script (e.g. shell, python, etc.). Emacs
1462 determines which interpreter you're using by examining the first line of
1463 the script. Use @kbd{C-h v} (or @kbd{M-x describe-variable}) on
1464 @code{interpreter-mode-alist} to learn more.
1466 @node Highlighting a region
1467 @section How can I highlight a region of text in Emacs?
1468 @cindex Highlighting text
1469 @cindex Text, highlighting
1470 @cindex @code{transient-mark-mode}
1471 @cindex Region, highlighting a
1473 You can cause the region to be highlighted when the mark is active by
1477 (transient-mark-mode 1)
1481 in your @file{.emacs} file. Since Emacs 23.1, this feature is on by default.
1483 @node Replacing highlighted text
1484 @section How can I replace highlighted text with what I type?
1485 @cindex @code{delete-selection-mode}
1486 @cindex Replacing highlighted text
1487 @cindex Highlighting and replacing text
1489 Use @code{delete-selection-mode}, which you can start automatically by
1490 placing the following Lisp form in your @file{.emacs} file:
1493 (delete-selection-mode 1)
1496 According to the documentation string for @code{delete-selection-mode}
1497 (which you can read using @kbd{M-x describe-function @key{RET}
1498 delete-selection-mode @key{RET}}):
1501 When Delete Selection mode is enabled, Transient Mark mode is also
1502 enabled and typed text replaces the selection if the selection is
1503 active. Otherwise, typed text is just inserted at point regardless of
1507 This mode also allows you to delete (not kill) the highlighted region by
1510 @node Controlling case sensitivity
1511 @section How do I control Emacs's case-sensitivity when searching/replacing?
1512 @cindex @code{case-fold-search}
1513 @cindex Case sensitivity of searches
1514 @cindex Searching without case sensitivity
1515 @cindex Ignoring case in searches
1518 The value of the variable @code{case-fold-search} determines whether
1519 searches are case sensitive:
1522 (setq case-fold-search nil) ; make searches case sensitive
1523 (setq case-fold-search t) ; make searches case insensitive
1526 @cindex Case sensitivity in replacements
1527 @cindex Replacing, and case sensitivity
1528 @cindex @code{case-replace}
1529 Similarly, for replacing, the variable @code{case-replace} determines
1530 whether replacements preserve case.
1532 You can also toggle case sensitivity at will in isearch with @kbd{M-c}.
1534 To change the case sensitivity just for one major mode, use the major
1535 mode's hook. For example:
1538 (add-hook '@var{foo}-mode-hook
1540 (setq case-fold-search nil)))
1543 @node Working with unprintable characters
1544 @section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
1545 @cindex Unprintable characters, working with
1546 @cindex Working with unprintable characters
1547 @cindex Control characters, working with
1548 @cindex Eight-bit characters, working with
1549 @cindex Searching for unprintable characters
1550 @cindex Regexps and unprintable characters
1552 To search for a single character that appears in the buffer as, for
1553 example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}.
1554 Searching for @strong{all} unprintable characters is best done with a
1555 regular expression (@dfn{regexp}) search. The easiest regexp to use for
1556 the unprintable chars is the complement of the regexp for the printable
1562 Regexp for the printable chars: @samp{[\t\n\r\f -~]}
1565 Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
1569 To type these special characters in an interactive argument to
1570 @code{isearch-forward-regexp} or @code{re-search-forward}, you need to
1571 use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
1572 respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So,
1573 to search for unprintable characters using @code{re-search-forward}:
1575 @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}}
1577 Using @code{isearch-forward-regexp}:
1579 @kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
1581 To delete all unprintable characters, simply use replace-regexp:
1583 @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}}
1585 Replacing is similar to the above. To replace all unprintable
1586 characters with a colon, use:
1588 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}
1590 @node Searching for/replacing newlines
1591 @section How do I input a newline character in isearch or query-replace?
1592 @cindex Searching for newlines
1593 @cindex Replacing newlines
1595 Use @kbd{C-q C-j}. For more information, see @inforef{Special Isearch,
1596 Special Input for Incremental Search, emacs}.
1599 @node Yanking text in isearch
1600 @section How do I copy text from the kill ring into the search string?
1601 @cindex Yanking text into the search string
1602 @cindex isearch yanking
1604 Use @kbd{M-y}. @inforef{Isearch Yank, Isearch Yanking, emacs}.
1606 @node Wrapping words automatically
1607 @section How do I make Emacs wrap words for me?
1608 @cindex Wrapping word automatically
1609 @cindex Wrapping lines
1611 @cindex @code{auto-fill-mode}, introduction to
1612 @cindex Maximum line width, default value
1613 @cindex @code{fill-column}, default value
1615 Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
1616 The default maximum line width is 70, determined by the variable
1617 @code{fill-column}. To learn how to turn this on automatically, see
1618 @ref{Turning on auto-fill by default}.
1620 @node Turning on auto-fill by default
1621 @section How do I turn on @code{auto-fill-mode} by default?
1622 @cindex @code{auto-fill-mode}, activating automatically
1623 @cindex Filling automatically
1624 @cindex Automatic entry to @code{auto-fill-mode}
1626 To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
1629 To turn it on for every buffer in a certain mode, you must use the hook
1630 for that mode. For example, to turn on @code{auto-fill} mode for all
1631 text buffers, including the following in your @file{.emacs} file:
1634 (add-hook 'text-mode-hook 'turn-on-auto-fill)
1637 If you want @code{auto-fill} mode on in all major modes, do this:
1640 (setq-default auto-fill-function 'do-auto-fill)
1643 @node Changing load-path
1644 @section How do I change @code{load-path}?
1645 @cindex @code{load-path}, modifying
1646 @cindex Modifying @code{load-path}
1647 @cindex Adding to @code{load-path}
1649 In general, you should only add to the @code{load-path}. You can add
1650 directory @var{/dir/subdir} to the load path like this:
1653 (setq load-path (cons "/dir/subdir/" load-path))
1656 To do this relative to your home directory:
1659 (setq load-path (cons "~/mysubdir/" load-path))
1662 @node Using an already running Emacs process
1663 @section How do I use an already running Emacs from another window?
1664 @cindex @code{emacsclient}
1665 @cindex Emacs server functions
1666 @cindex Using an existing Emacs process
1668 @code{emacsclient}, which comes with Emacs, is for editing a file using
1669 an already running Emacs rather than starting up a new Emacs. It does
1670 this by sending a request to the already running Emacs, which must be
1671 expecting the request.
1678 Emacs must have executed the @code{server-start} function for
1679 @samp{emacsclient} to work. This can be done either by a command line
1683 emacs -f server-start
1686 or by invoking @code{server-start} from @file{.emacs}:
1689 (if (@var{some conditions are met}) (server-start))
1692 When this is done, Emacs creates a Unix domain socket named
1693 @file{server} in @file{/tmp/emacs@var{userid}}. See
1694 @code{server-socket-dir}.
1696 To get your news reader, mail reader, etc., to invoke
1697 @samp{emacsclient}, try setting the environment variable @code{EDITOR}
1698 (or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may
1699 have to specify the full pathname of the @samp{emacsclient} program
1704 setenv EDITOR emacsclient
1706 # using full pathname
1707 setenv EDITOR /usr/local/emacs/etc/emacsclient
1710 EDITOR=emacsclient ; export EDITOR
1716 When @samp{emacsclient} is run, it connects to the socket and passes its
1717 command line options to Emacs, which at the next opportunity will visit
1718 the files specified. (Line numbers can be specified just like with
1719 Emacs.) The user will have to switch to the Emacs window by hand. When
1720 the user is done editing a file, the user can type @kbd{C-x #} (or
1721 @kbd{M-x server-edit}) to indicate this. If there is another buffer
1722 requested by @code{emacsclient}, Emacs will switch to it; otherwise
1723 @code{emacsclient} will exit, signaling the calling program to continue.
1725 @cindex @code{gnuserv}
1726 There is an alternative version of @samp{emacsclient} called
1727 @samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman}
1728 (@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses
1729 Internet domain sockets, so it can work across most network connections.
1731 The most recent @samp{gnuserv} package is available at
1733 @uref{http://meltin.net/hacks/emacs/}
1737 @node Compiler error messages
1738 @section How do I make Emacs recognize my compiler's funny error messages?
1739 @cindex Compiler error messages, recognizing
1740 @cindex Recognizing non-standard compiler errors
1741 @cindex Regexps for recognizing compiler errors
1742 @cindex Errors, recognizing compiler
1744 Customize the @code{compilation-error-regexp-alist} variable.
1746 @node Indenting switch statements
1747 @section How do I change the indentation for @code{switch}?
1748 @cindex @code{switch}, indenting
1749 @cindex Indenting of @code{switch}
1751 Many people want to indent their @code{switch} statements like this:
1769 @noindent To achieve this, add the following line to your @file{.emacs}:
1772 (c-set-offset 'case-label '+)
1775 @node Customizing C and C++ indentation
1776 @section How to customize indentation in C, C@t{++}, and Java buffers?
1777 @cindex Indentation, how to customize
1778 @cindex Customize indentation
1780 The Emacs @code{cc-mode} features an interactive procedure for
1781 customizing the indentation style, which is fully explained in the
1782 @cite{CC Mode} manual that is part of the Emacs distribution, see
1783 @ref{Customizing Indentation, , Customization Indentation, ccmode,
1784 The CC Mode Manual}. Here's a short summary of the procedure:
1788 Go to the beginning of the first line where you don't like the
1789 indentation and type @kbd{C-c C-o}. Emacs will prompt you for the
1790 syntactic symbol; type @key{RET} to accept the default it suggests.
1793 Emacs now prompts for the offset of this syntactic symbol, showing the
1794 default (the current definition) inside parentheses. You can choose
1799 No extra indentation.
1801 Indent one basic offset.
1803 Outdent one basic offset.
1805 Indent two basic offsets
1807 Outdent two basic offsets.
1809 Indent half basic offset.
1811 Outdent half basic offset.
1815 After choosing one of these symbols, type @kbd{C-c C-q} to reindent
1816 the line or the block according to what you just specified.
1819 If you don't like the result, go back to step 1. Otherwise, add the
1820 following line to your @file{.emacs}:
1823 (c-set-offset '@var{syntactic-symbol} @var{offset})
1827 where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
1828 when you type @kbd{C-c C-o} at the beginning of the line, and
1829 @var{offset} is one of the indentation symbols listed above (@code{+},
1830 @code{/}, @code{0}, etc.) that you've chosen during the interactive
1834 Go to the next line whose indentation is not to your liking and repeat
1838 It is recommended to put all the resulting @code{(c-set-offset ...)}
1839 customizations inside a C mode hook, like this:
1842 (defun my-c-mode-hook ()
1845 (add-hook 'c-mode-hook 'my-c-mode-hook)
1849 Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
1850 'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
1851 might be unavailable when @code{cc-mode} is not loaded.
1853 Note that @code{c-mode-hook} runs for C source files only; use
1854 @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
1855 Java sources, etc. If you want the same customizations to be in
1856 effect in @emph{all} languages supported by @code{cc-mode}, use
1857 @code{c-mode-common-hook}.
1859 @node Horizontal scrolling
1860 @section How can I make Emacs automatically scroll horizontally?
1861 @cindex @code{hscroll-mode}
1862 @cindex Horizontal scrolling
1863 @cindex Scrolling horizontally
1865 In Emacs 21 and later, this is on by default: if the variable
1866 @code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
1867 automatically scrolls the display horizontally when point moves off the
1868 left or right edge of the window.
1870 Note that this is overridden by the variable
1871 @code{truncate-partial-width-windows} if that variable is non-nil
1872 and the current buffer is not full-frame width.
1874 In Emacs 20, use @code{hscroll-mode}.
1876 @node Overwrite mode
1877 @section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
1878 @cindex @key{Insert}
1879 @cindex @code{overwrite-mode}
1880 @cindex Overwriting existing text
1881 @cindex Toggling @code{overwrite-mode}
1883 @kbd{M-x overwrite-mode} (a minor mode). This toggles
1884 @code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
1885 is as easy as another @kbd{M-x overwrite-mode}.
1887 On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
1889 @node Turning off beeping
1890 @section How do I stop Emacs from beeping on a terminal?
1891 @cindex Beeping, turning off
1892 @cindex Visible bell
1893 @cindex Bell, visible
1895 @email{martin@@cc.gatech.edu, Martin R. Frank} writes:
1897 Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
1898 and set the visible bell to nothing.
1900 That is, put the following in your @code{TERMCAP} environment variable
1901 (assuming you have one):
1907 And evaluate the following Lisp form:
1910 (setq visible-bell t)
1913 @node Turning the volume down
1914 @section How do I turn down the bell volume in Emacs running under X?
1915 @cindex Bell, volume of
1916 @cindex Volume of bell
1918 On X Window system, you can adjust the bell volume and duration for all
1919 programs with the shell command @code{xset}.
1921 Invoking @code{xset} without any arguments produces some basic
1922 information, including the following:
1925 usage: xset [-display host:dpy] option ...
1928 To set bell volume, pitch and duration:
1929 b [vol [pitch [dur]]] b on
1932 @node Automatic indentation
1933 @section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
1934 @cindex Indenting new lines
1935 @cindex New lines, indenting of
1936 @cindex Previous line, indenting according to
1937 @cindex Text indentation
1939 Such behavior is automatic in Emacs 20 and later. From the
1940 @file{etc/NEWS} file for Emacs 20.2:
1943 ** In Text mode, now only blank lines separate paragraphs. This makes
1944 it possible to get the full benefit of Adaptive Fill mode in Text mode,
1945 and other modes derived from it (such as Mail mode). @key{TAB} in Text
1946 mode now runs the command @code{indent-relative}; this makes a practical
1947 difference only when you use indented paragraphs.
1949 As a result, the old Indented Text mode is now identical to Text mode,
1950 and is an alias for it.
1952 If you want spaces at the beginning of a line to start a paragraph, use
1953 the new mode, Paragraph Indent Text mode.
1956 @cindex Prefixing lines
1958 If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
1959 by default}), you can tell Emacs to prefix every line with a certain
1960 character sequence, the @dfn{fill prefix}. Type the prefix at the
1961 beginning of a line, position point after it, and then type @kbd{C-x .}
1962 (@code{set-fill-prefix}) to set the fill prefix. Thereafter,
1963 auto-filling will automatically put the fill prefix at the beginning of
1964 new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
1965 prefix when refilling the paragraph.
1967 If you have paragraphs with different levels of indentation, you will
1968 have to set the fill prefix to the correct value each time you move to a
1969 new paragraph. There are many packages available to deal with this
1970 (@pxref{Packages that do not come with Emacs}). Look for ``fill'' and
1971 ``indent'' keywords for guidance.
1973 @node Matching parentheses
1974 @section How do I show which parenthesis matches the one I'm looking at?
1975 @cindex Parentheses, matching
1976 @cindex @file{paren.el}
1977 @cindex Highlighting matching parentheses
1978 @cindex Pairs of parentheses, highlighting
1979 @cindex Matching parentheses
1981 Call @code{show-paren-mode} in your @file{.emacs} file:
1987 You can also enable this mode by selecting the @samp{Paren Match
1988 Highlighting} option from the @samp{Options} menu of the Emacs menu bar
1989 at the top of any Emacs frame.
1991 Alternatives to this mode include:
1996 If you're looking at a right parenthesis (or brace or bracket) you can
1997 delete it and reinsert it. Emacs will momentarily move the cursor to
1998 the matching parenthesis.
2001 @kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
2002 will skip over one set of balanced parentheses, so you can see which
2003 parentheses match. (You can train it to skip over balanced brackets
2004 and braces at the same time by modifying the syntax table.)
2006 @cindex Show matching paren as in @code{vi}
2008 Here is some Emacs Lisp that will make the @key{%} key show the matching
2009 parenthesis, like in @code{vi}. In addition, if the cursor isn't over a
2010 parenthesis, it simply inserts a % like normal.
2013 ;; By an unknown contributor
2015 (global-set-key "%" 'match-paren)
2017 (defun match-paren (arg)
2018 "Go to the matching paren if on a paren; otherwise insert %."
2020 (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
2021 ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
2022 (t (self-insert-command (or arg 1)))))
2027 @node Hiding #ifdef lines
2028 @section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
2029 @cindex @code{#ifdef}, selective display of
2030 @cindex @code{hide-ifdef-mode}
2031 @cindex Hiding @code{#ifdef} text
2032 @cindex Selectively displaying @code{#ifdef} code
2034 @kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want
2035 to investigate @file{cpp.el}, which is distributed with Emacs.
2037 @node Repeating commands
2038 @section How do I repeat a command as many times as possible?
2039 @cindex Repeating commands many times
2040 @cindex Commands, repeating many times
2041 @cindex @code{.}, equivalent to @code{vi} command
2043 As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
2044 that repeats the last command. If you preface it with a prefix
2045 argument, the prefix arg is applied to the command.
2047 You can also type @kbd{C-x @key{ESC} @key{ESC}}
2048 (@code{repeat-complex-command}) to reinvoke commands that used the
2049 minibuffer to get arguments. In @code{repeat-complex-command} you can
2050 type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
2051 keyboard has these keys) to scan through all the different complex
2052 commands you've typed.
2054 To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and
2055 @kbd{C-x )} to make a keyboard macro that invokes the command and then
2056 type @kbd{C-x e}. (@inforef{Keyboard Macros, Keyboard Macros, emacs}.)
2058 If you're really desperate for the @code{.} command in @code{vi} that
2059 redoes the last insertion/deletion, use VIPER, a @code{vi} emulation
2060 mode which comes with Emacs, and which appears to support it.
2062 @node Valid X resources
2063 @section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
2064 @cindex Resources, X
2066 @cindex Setting X resources
2068 @inforef{X Resources, X Resources, emacs}.
2070 You can also use a resource editor, such as editres (for X11R5 and
2071 onwards), to look at the resource names for the menu bar, assuming Emacs
2072 was compiled with the X toolkit.
2074 @node Evaluating Emacs Lisp code
2075 @section How do I execute (``evaluate'') a piece of Emacs Lisp code?
2076 @cindex Evaluating Lisp code
2077 @cindex Lisp forms, evaluating
2079 There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
2080 Emacs Lisp @dfn{form}:
2085 If you want it evaluated every time you run Emacs, put it in a file
2086 named @file{.emacs} in your home directory. This is known as ``your
2087 @file{.emacs} file,'' and contains all of your personal customizations.
2090 You can type the form in the @file{*scratch*} buffer, and then type
2091 @key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form
2092 will be inserted in the buffer.
2095 In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
2096 before or around point.
2099 Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
2100 before point and prints its value in the echo area.
2103 Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
2104 form in the minibuffer which will be evaluated once you press @key{RET}.
2107 You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
2108 forms in a file. (To do this from Lisp use the function @code{load}
2111 The functions @code{load-library}, @code{eval-region},
2112 @code{eval-buffer}, @code{require}, and @code{autoload} are also
2113 useful; see @ref{Emacs Lisp documentation}, if you want to learn more
2118 @node Changing the length of a Tab
2119 @section How do I change Emacs's idea of the @key{TAB} character's length?
2121 @cindex Length of tab character
2122 @cindex @code{default-tab-width}
2124 Set the variable @code{default-tab-width}. For example, to set
2125 @key{TAB} stops every 10 characters, insert the following in your
2129 (setq default-tab-width 10)
2132 Do not confuse variable @code{tab-width} with variable
2133 @code{tab-stop-list}. The former is used for the display of literal
2134 @key{TAB} characters. The latter controls what characters are inserted
2135 when you press the @key{TAB} character in certain modes.
2137 @node Inserting text at the beginning of each line
2138 @section How do I insert <some text> at the beginning of every line?
2139 @cindex Prefixing a region with some text
2140 @cindex Prefix character, inserting in mail/news replies
2141 @cindex Replies to mail/news, inserting a prefix character
2142 @cindex @code{mail-yank-prefix}
2143 @cindex Mail replies, inserting a prefix character
2144 @cindex News replies, inserting a prefix character
2146 To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
2147 @key{RET} ^ @key{RET} your text @key{RET}}.
2149 To do this to a region, use @code{string-insert-rectangle}.
2150 Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
2151 want to prefix, move the cursor to last line to be prefixed, and type
2152 @kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole
2153 buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
2155 If you are trying to prefix a yanked mail message with @samp{>}, you
2156 might want to set the variable @code{mail-yank-prefix}. In Message
2157 buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;}
2158 runs the function @code{comment-region}, it is a general-purpose
2159 mechanism to comment regions) (@pxref{Changing the included text prefix}).
2161 @node Underlining paragraphs
2162 @section How do I insert @samp{_^H} before each character in a region to get an underlined paragraph?
2163 @cindex Underlining a region of text
2164 @cindex @code{underline-region}
2166 Mark the region and then type @kbd{M-x underline-region @key{RET}}.
2168 @node Forcing the cursor to remain in the same column
2169 @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?
2170 @cindex @code{picture-mode}
2171 @cindex Remaining in the same column, regardless of contents
2172 @cindex Vertical movement in empty documents
2174 Use @kbd{M-x picture-mode}.
2176 See also the variable @code{track-eol} and the command
2177 @code{set-goal-column} bound to @kbd{C-x C-n}
2178 (@pxref{Moving Point, , , emacs, The GNU Emacs Manual}).
2180 @node Forcing Emacs to iconify itself
2181 @section How do I tell Emacs to iconify itself?
2182 @cindex Iconification under the X Window System
2183 @cindex X Window System and iconification
2184 @cindex Suspending Emacs
2186 @kbd{C-z} iconifies Emacs when running under X and suspends Emacs
2187 otherwise. @inforef{Frame Commands, Frame Commands, emacs}.
2189 @node Using regular expressions
2190 @section How do I use regexps (regular expressions) in Emacs?
2192 @cindex Regular expressions
2193 @cindex Differences between Unix and Emacs regexps
2194 @cindex Unix regexps, differences from Emacs
2195 @cindex Text strings, putting regexps in
2197 @inforef{Regexp Backslash, Regexp Backslash, emacs}.
2199 The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
2200 are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is
2201 @samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)}
2202 in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
2204 Note the doubled backslashes!
2209 Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
2210 (@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@:
2211 @kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
2212 characters not to match.
2215 The character syntax regexps (e.g., @samp{\sw}) are not
2216 meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This
2217 is actually typical for regexp syntax.)
2221 @node Replacing text across multiple files
2222 @section How do I perform a replace operation across more than one file?
2223 @cindex Replacing strings across files
2224 @cindex Multiple files, replacing across
2225 @cindex Files, replacing strings across multiple
2226 @cindex Recursive search/replace operations
2228 Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x d}) supports the
2229 command @code{dired-do-query-replace-regexp} (@kbd{Q}), which allows
2230 users to replace regular expressions in multiple files.
2232 You can use this command to perform search/replace operations on
2233 multiple files by following the following steps:
2237 Assemble a list of files you want to operate on with either
2238 @code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}.
2241 Mark all files in the resulting Dired buffer using @kbd{t}.
2244 Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked
2248 To accept all replacements in each file, hit @kbd{!}.
2251 Another way to do the same thing is to use the ``tags'' feature of
2252 Emacs: it includes the command @code{tags-query-replace} which performs
2253 a query-replace across all the files mentioned in the @file{TAGS} file.
2254 @inforef{Tags Search, Tags Search, emacs}.
2256 @node Documentation for etags
2257 @section Where is the documentation for @code{etags}?
2258 @cindex Documentation for @code{etags}
2259 @cindex @code{etags}, documentation for
2261 The @code{etags} man page should be in the same place as the
2262 @code{emacs} man page.
2264 Quick command-line switch descriptions are also available. For example,
2267 @node Disabling backups
2268 @section How do I disable backup files?
2269 @cindex Backups, disabling
2270 @cindex Disabling backups
2272 You probably don't want to do this, since backups are useful, especially
2273 when something goes wrong.
2275 To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
2276 load @code{dired-x} by adding the following to your @file{.emacs} file:
2279 (add-hook 'dired-load-hook
2281 (require 'dired-x)))
2284 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
2285 You can make omitting the default for new dired buffers by putting the
2286 following in your @file{.emacs}:
2289 (add-hook 'dired-mode-hook 'dired-omit-toggle)
2292 If you're tired of seeing backup files whenever you do an @samp{ls} at
2293 the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU
2294 @code{ls} is part of the GNU Fileutils package, available from
2295 @samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
2297 To disable or change the way backups are made, @inforef{Backup Names, ,
2300 @cindex Backup files in a single directory
2301 Beginning with Emacs 21.1, you can control where Emacs puts backup files
2302 by customizing the variable @code{backup-directory-alist}. This
2303 variable's value specifies that files whose names match specific patters
2304 should have their backups put in certain directories. A typical use is
2305 to add the element @code{("." . @var{dir})} to force Emacs to put
2306 @strong{all} backup files in the directory @file{dir}.
2308 @node Disabling auto-save-mode
2309 @section How do I disable @code{auto-save-mode}?
2310 @cindex Disabling @code{auto-save-mode}
2312 @cindex Saving at frequent intervals
2314 You probably don't want to do this, since auto-saving is useful,
2315 especially when Emacs or your computer crashes while you are editing a
2318 Instead, you might want to change the variable
2319 @code{auto-save-interval}, which specifies how many keystrokes Emacs
2320 waits before auto-saving. Increasing this value forces Emacs to wait
2321 longer between auto-saves, which might annoy you less.
2323 You might also want to look into Sebastian Kremer's @code{auto-save}
2324 package (@pxref{Packages that do not come with Emacs}). This
2325 package also allows you to place all auto-save files in one directory,
2326 such as @file{/tmp}.
2328 To disable or change how @code{auto-save-mode} works, @inforef{Auto
2331 @node Going to a line by number
2332 @section How can I go to a certain line given its number?
2333 @cindex Going to a line by number
2334 @cindex Compilation error messages
2335 @cindex Recompilation
2337 Are you sure you indeed need to go to a line by its number? Perhaps all
2338 you want is to display a line in your source file for which a compiler
2339 printed an error message? If so, compiling from within Emacs using the
2340 @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
2341 effective way of doing that. Emacs automatically intercepts the compile
2342 error messages, inserts them into a special buffer called
2343 @code{*compilation*}, and lets you visit the locus of each message in
2344 the source. Type @kbd{C-x `} to step through the offending lines one by
2345 one (starting with Emacs 22, you can also use @kbd{M-g M-p} and
2346 @kbd{M-g M-n} to go to the previous and next matches directly). Click
2347 @kbd{Mouse-2} or press @key{RET} on a message text in the
2348 @code{*compilation*} buffer to go to the line whose number is mentioned
2351 But if you indeed need to go to a certain text line, type @kbd{M-g M-g}
2352 (which is the default binding of the @code{goto-line} function starting
2353 with Emacs 22). Emacs will prompt you for the number of the line and go
2356 You can do this faster by invoking @code{goto-line} with a numeric
2357 argument that is the line's number. For example, @kbd{C-u 286 M-g M-g}
2358 will jump to line number 286 in the current buffer.
2360 @node Modifying pull-down menus
2361 @section How can I create or modify new pull-down menu options?
2362 @cindex Pull-down menus, creating or modifying
2363 @cindex Menus, creating or modifying
2364 @cindex Creating new menu options
2365 @cindex Modifying pull-down menus
2366 @cindex Menus and keymaps
2367 @cindex Keymaps and menus
2369 Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
2370 represents a local or global keymap. Selecting a menu title with the
2371 mouse displays that keymap's non-@code{nil} contents in the form of a menu.
2373 So to add a menu option to an existing menu, all you have to do is add a
2374 new definition to the appropriate keymap. Adding a @samp{Forward Word}
2375 item to the @samp{Edit} menu thus requires the following Lisp code:
2378 (define-key global-map
2379 [menu-bar edit forward]
2380 '("Forward word" . forward-word))
2384 The first line adds the entry to the global keymap, which includes
2385 global menu bar entries. Replacing the reference to @code{global-map}
2386 with a local keymap would add this menu option only within a particular
2389 The second line describes the path from the menu-bar to the new entry.
2390 Placing this menu entry underneath the @samp{File} menu would mean
2391 changing the word @code{edit} in the second line to @code{file}.
2393 The third line is a cons cell whose first element is the title that will
2394 be displayed, and whose second element is the function that will be
2395 called when that menu option is invoked.
2397 To add a new menu, rather than a new option to an existing menu, we must
2398 define an entirely new keymap:
2401 (define-key global-map [menu-bar words]
2402 (cons "Words" (make-sparse-keymap "Words")))
2405 The above code creates a new sparse keymap, gives it the name
2406 @samp{Words}, and attaches it to the global menu bar. Adding the
2407 @samp{Forward Word} item to this new menu would thus require the
2411 (define-key global-map
2412 [menu-bar words forward]
2413 '("Forward word" . forward-word))
2417 Note that because of the way keymaps work, menu options are displayed
2418 with the more recently defined items at the top. Thus if you were to
2419 define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
2420 order), the menu option @samp{baz} would appear at the top, and
2421 @samp{foo} would be at the bottom.
2423 One way to avoid this problem is to use the function @code{define-key-after},
2424 which works the same as @code{define-key}, but lets you modify where items
2425 appear. The following Lisp code would insert the @samp{Forward Word}
2426 item in the @samp{Edit} menu immediately following the @samp{Undo} item:
2430 (lookup-key global-map [menu-bar edit])
2432 '("Forward word" . forward-word)
2436 Note how the second and third arguments to @code{define-key-after} are
2437 different from those of @code{define-key}, and that we have added a new
2438 (final) argument, the function after which our new key should be
2441 To move a menu option from one position to another, simply evaluate
2442 @code{define-key-after} with the appropriate final argument.
2444 More detailed information---and more examples of how to create and
2445 modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
2446 ``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on
2449 @node Deleting menus and menu options
2450 @section How do I delete menus and menu options?
2451 @cindex Deleting menus and menu options
2452 @cindex Menus, deleting
2454 The simplest way to remove a menu is to set its keymap to @samp{nil}.
2455 For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
2459 (define-key global-map [menu-bar words] nil)
2462 Similarly, removing a menu option requires redefining a keymap entry to
2463 @code{nil}. For example, to delete the @samp{Forward word} menu option
2464 from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
2468 (define-key global-map [menu-bar edit forward] nil)
2471 @node Turning on syntax highlighting
2472 @section How do I turn on syntax highlighting?
2473 @cindex Syntax highlighting
2474 @cindex @code{font-lock-mode}
2475 @cindex Highlighting based on syntax
2476 @cindex Colorizing text
2477 @cindex FAQ, @code{font-lock-mode}
2479 @code{font-lock-mode} is the standard way to have Emacs perform syntax
2480 highlighting in the current buffer. It is enabled by default in Emacs
2483 With @code{font-lock-mode} turned on, different types of text will
2484 appear in different colors. For instance, in a programming mode,
2485 variables will appear in one face, keywords in a second, and comments in
2488 To turn @code{font-lock-mode} off within an existing buffer, use
2489 @kbd{M-x font-lock-mode @key{RET}}.
2491 In Emacs 21 and earlier versions, you could use the following code in
2492 your @file{.emacs} file to turn on @code{font-lock-mode} globally:
2495 (global-font-lock-mode 1)
2498 Highlighting a buffer with @code{font-lock-mode} can take quite a while,
2499 and cause an annoying delay in display, so several features exist to
2502 @cindex Just-In-Time syntax highlighting
2503 In Emacs 21 and later, turning on @code{font-lock-mode} automatically
2504 activates the new @dfn{Just-In-Time fontification} provided by
2505 @code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
2506 portions of buffer until you actually need to see them, and can also
2507 fontify while Emacs is idle. This makes display of the visible portion
2508 of a buffer almost instantaneous. For details about customizing
2509 @code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
2511 @cindex Levels of syntax highlighting
2512 @cindex Decoration level, in @code{font-lock-mode}
2513 In versions of Emacs before 21, different levels of decoration are
2514 available, from slight to gaudy. More decoration means you need to wait
2515 more time for a buffer to be fontified (or a faster machine). To
2516 control how decorated your buffers should become, set the value of
2517 @code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
2518 @code{nil} value indicating default (usually minimum) decoration, and a
2519 @code{t} value indicating the maximum decoration. For the gaudiest
2520 possible look, then, include the line
2523 (setq font-lock-maximum-decoration t)
2527 in your @file{.emacs} file. You can also set this variable such that
2528 different modes are highlighted in a different ways; for more
2529 information, see the documentation for
2530 @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
2531 describe-variable @key{RET}}).
2533 Also see the documentation for the function @code{font-lock-mode},
2534 available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
2535 describe-function @key{RET} font-lock-mode @key{RET}}).
2537 To print buffers with the faces (i.e., colors and fonts) intact, use
2538 @kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
2539 ps-print-region-with-faces}. You will need a way to send text to a
2540 PostScript printer, or a PostScript interpreter such as Ghostscript;
2541 consult the documentation of the variables @code{ps-printer-name},
2542 @code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
2544 @node Scrolling only one line
2545 @section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
2546 @cindex Scrolling only one line
2547 @cindex Reducing the increment when scrolling
2549 Customize the @code{scroll-conservatively} variable with @kbd{M-x
2550 customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
2551 to a large value like, say, 10000. For an explanation of what this
2552 means, @inforef{Auto Scrolling, Auto Scrolling, emacs}.
2554 Alternatively, use the following Lisp form in your @file{.emacs}:
2557 (setq scroll-conservatively most-positive-fixnum)
2560 @node Editing MS-DOS files
2561 @section How can I edit MS-DOS files using Emacs?
2562 @cindex Editing MS-DOS files
2563 @cindex MS-DOS files, editing
2564 @cindex Microsoft files, editing
2565 @cindex Windows files, editing
2567 As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
2568 performed transparently. You can open MS-DOS files on a Unix system,
2569 edit it, and save it without having to worry about the file format.
2571 When editing an MS-DOS style file, the mode line will indicate that it
2572 is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh,
2573 the string @samp{(DOS)} will appear near the left edge of the mode line;
2574 on DOS and Windows, where the DOS end-of-line (EOL) format is the
2575 default, a backslash (@samp{\}) will appear in the mode line.
2577 If you are running a version of Emacs before 20.1, get @code{crypt++}
2578 (@pxref{Packages that do not come with Emacs}). Among other things,
2579 @code{crypt++} transparently modifies MS-DOS files as they are loaded
2580 and saved, allowing you to ignore the different conventions that Unix
2581 and MS-DOS have for delineating the end of a line.
2583 @node Filling paragraphs with a single space
2584 @section How can I tell Emacs to fill paragraphs with a single space after each period?
2585 @cindex One space following periods
2586 @cindex Single space following periods
2587 @cindex Periods, one space following
2589 Add the following line to your @file{.emacs} file:
2592 (setq sentence-end-double-space nil)
2595 @node Escape sequences in shell output
2596 @section Why these strange escape sequences from @code{ls} from the Shell mode?
2597 @cindex Escape sequences in @code{ls} output
2598 @cindex @code{ls} in Shell mode
2600 This happens because @code{ls} is aliased to @samp{ls --color} in your
2601 shell init file. You have two alternatives to solve this:
2605 Make the alias conditioned on the @code{EMACS} variable in the
2606 environment. When Emacs runs a subsidiary shell, it exports the
2607 @code{EMACS} variable to that shell, with value equal to the absolute
2608 file name of Emacs. You can
2609 unalias @code{ls} when that happens, thus limiting the alias to your
2610 interactive sessions.
2613 Install the @code{ansi-color} package (bundled with Emacs 21.1 and
2614 later), which converts these ANSI escape sequences into colors.
2617 @node Fullscreen mode on MS-Windows
2618 @section How can I start Emacs in fullscreen mode on MS-Windows?
2619 @cindex Maximize frame
2620 @cindex Fullscreen mode
2622 Use the function @code{w32-send-sys-command}. For example, you can
2623 put the following in your @file{.emacs} file:
2626 (add-hook 'term-setup-hook
2627 #'(lambda () (w32-send-sys-command ?\xF030)))
2630 To avoid the slightly distracting visual effect of Emacs starting with
2631 its default frame size and then growing to fullscreen, you can add an
2632 @samp{Emacs.Geometry} entry to the Windows registry settings (see
2633 @pxref{(emacs)X Resources}).
2635 To compute the correct values for width and height, first maximize the
2636 Emacs frame and then evaluate @code{(frame-height)} and
2637 @code{(frame-width)} with @kbd{M-:}.
2639 @c ------------------------------------------------------------
2640 @node Bugs and problems
2641 @chapter Bugs and problems
2642 @cindex Bugs and problems
2644 The Emacs manual lists some common kinds of trouble users could get
2645 into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
2646 Emacs Manual}, so you might look there if the problem you encounter
2647 isn't described in this chapter. If you decide you've discovered a bug,
2648 see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
2649 instructions how to do that.
2651 The file @file{etc/PROBLEMS} in the Emacs distribution lists various
2652 known problems with building and using Emacs on specific platforms;
2653 type @kbd{C-h C-e} to read it.
2656 * Problems with very large files::
2657 * ^M in the shell buffer::
2658 * Shell process exits abnormally::
2659 * Problems with Shell Mode on MS-Windows::
2660 * Termcap/Terminfo entries for Emacs::
2661 * Spontaneous entry into isearch-mode::
2662 * Problems talking to certain hosts::
2663 * Errors with init files::
2664 * Emacs ignores X resources::
2665 * Emacs ignores frame parameters::
2666 * Emacs takes a long time to visit files::
2667 * Editing files with $ in the name::
2668 * Shell mode loses the current directory::
2669 * Security risks with Emacs::
2670 * Dired claims that no file is on this line::
2673 @node Problems with very large files
2674 @section Does Emacs have problems with files larger than 8 megabytes?
2675 @cindex Very large files, opening
2676 @cindex Large files, opening
2677 @cindex Opening very large files
2678 @cindex Maximum file size
2679 @cindex Files, maximum size
2681 Old versions (i.e., anything before 19.29) of Emacs had problems editing
2682 files larger than 8 megabytes. In versions 19.29 and later, the maximum
2683 buffer size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes.
2684 And in Emacs 22, the maximum buffer size has been increased to
2685 268,435,455 bytes (or 256 MBytes) on 32-bit machines.
2687 @node ^M in the shell buffer
2688 @section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
2689 @cindex Shell buffer, echoed commands and @samp{^M} in
2690 @cindex Echoed commands in @code{shell-mode}
2692 Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
2693 make them go away. If that doesn't work, you have several options:
2695 For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
2700 if ("$EMACS" =~ /*) then
2701 if ($?tcsh) unset edit
2707 Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file:
2714 Alternatively, use @code{csh} in your shell buffers instead of
2715 @code{tcsh}. One way is:
2718 (setq explicit-shell-file-name "/bin/csh")
2722 and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
2726 setenv ESHELL /bin/csh
2730 (You must start Emacs over again with the environment variable properly
2731 set for this to take effect.)
2733 You can also set the @code{ESHELL} environment variable in Emacs Lisp
2734 with the following Lisp form,
2737 (setenv "ESHELL" "/bin/csh")
2740 The above solutions try to prevent the shell from producing the
2741 @samp{^M} characters in the first place. If this is not possible
2742 (e.g., if you use a Windows shell), you can get Emacs to remove these
2743 characters from the buffer by adding this to your @file{.emacs} init
2747 (add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
2750 On a related note: if your shell is echoing your input line in the shell
2751 buffer, you might want to customize the @code{comint-process-echoes}
2752 variable in your shell buffers, or try the following command in your
2753 shell start-up file:
2756 stty -icrnl -onlcr -echo susp ^Z
2759 @node Shell process exits abnormally
2760 @section Why do I get ``Process shell exited abnormally with code 1''?
2761 @cindex Abnormal exits from @code{shell-mode}
2762 @cindex @code{shell-mode} exits
2763 @cindex Process shell exited
2765 The most likely reason for this message is that the @samp{env} program
2766 is not properly installed. Compile this program for your architecture,
2767 and install it with @samp{a+x} permission in the architecture-dependent
2768 Emacs program directory. (You can find what this directory is at your
2769 site by inspecting the value of the variable @code{exec-directory} by
2770 typing @kbd{C-h v exec-directory @key{RET}}.)
2772 You should also check for other programs named @samp{env} in your path
2773 (e.g., SunOS has a program named @file{/usr/bin/env}). We don't
2774 understand why this can cause a failure and don't know a general
2775 solution for working around the problem in this case.
2777 The @samp{make clean} command will remove @samp{env} and other vital
2778 programs, so be careful when using it.
2780 It has been reported that this sometimes happened when Emacs was started
2781 as an X client from an xterm window (i.e., had a controlling tty) but the
2782 xterm was later terminated.
2784 See also @samp{PROBLEMS} (in the @file{etc} subdirectory of the
2785 top-level directory when you unpack the Emacs source) for other
2786 possible causes of this message.
2788 @node Problems with Shell Mode on MS-Windows
2789 @section Why do I get an error message when I try to run @kbd{M-x shell}?
2791 @cindex Shell Mode, and MS-Windows
2792 @cindex @code{explicit-shell-file-name}
2793 On MS-Windows, this might happen because Emacs tries to look for the
2794 shell in a wrong place. The default file name @file{/bin/sh} is
2795 usually incorrect for non-Unix systems. If you know where your shell
2796 executable is, set the variable @code{explicit-shell-file-name} in
2797 your @file{.emacs} file to point to its full file name, like this:
2800 (setq explicit-shell-file-name "d:/shells/bash.exe")
2803 If you don't know what shell does Emacs use, try the @kbd{M-!}
2804 command; if that works, put the following line into your
2808 (setq explicit-shell-file-name shell-file-name)
2811 @cindex Antivirus programs, and Shell Mode
2812 Some people have trouble with Shell Mode because of intrusive
2813 antivirus software; disabling the resident antivirus program solves
2814 the problems in those cases.
2816 @node Termcap/Terminfo entries for Emacs
2817 @section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
2820 @cindex Emacs entries for termcap/terminfo
2822 The termcap entry for terminal type @samp{emacs} is ordinarily put in
2823 the @samp{TERMCAP} environment variable of subshells. It may help in
2824 certain situations (e.g., using rlogin from shell buffer) to add an
2825 entry for @samp{emacs} to the system-wide termcap file. Here is a
2826 correct termcap entry for @samp{emacs}:
2832 To make a terminfo entry for @samp{emacs}, use @code{tic} or
2833 @code{captoinfo}. You need to generate
2834 @file{/usr/lib/terminfo/e/emacs}. It may work to simply copy
2835 @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
2837 Having a termcap/terminfo entry will not enable the use of full screen
2838 programs in shell buffers. Use @kbd{M-x terminal-emulator} for that
2841 A workaround to the problem of missing termcap/terminfo entries is to
2842 change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
2843 in your shell start up file. @code{csh} users could put this in their
2844 @file{.cshrc} files:
2847 if ("$term" == emacs) set term=dumb
2850 @node Spontaneous entry into isearch-mode
2851 @section Why does Emacs spontaneously start displaying @samp{I-search:} and beeping?
2852 @cindex Spontaneous entry into isearch-mode
2853 @cindex isearch-mode, spontaneous entry into
2854 @cindex Beeping without obvious reason
2856 Your terminal (or something between your terminal and the computer) is
2857 sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving
2858 these characters and interpreting them as commands. (The @kbd{C-s}
2859 character normally invokes the @code{isearch-forward} command.) For
2860 possible solutions, see @ref{Handling C-s and C-q with flow control}.
2862 @node Problems talking to certain hosts
2863 @section Why can't Emacs talk to certain hosts (or certain hostnames)?
2864 @cindex Hosts, Emacs cannot talk to
2865 @cindex @code{gethostbyname}, problematic version
2867 The problem may be that Emacs is linked with a wimpier version of
2868 @code{gethostbyname} than the rest of the programs on the machine. This
2869 is often manifested as a message on startup of ``X server not responding.
2870 Check your @samp{DISPLAY} environment variable.'' or a message of
2871 ``Unknown host'' from @code{open-network-stream}.
2873 On a Sun, this may be because Emacs had to be linked with the static C
2874 library. The version of @code{gethostbyname} in the static C library
2875 may only look in @file{/etc/hosts} and the NIS (YP) maps, while the
2876 version in the dynamic C library may be smart enough to check DNS in
2877 addition to or instead of NIS. On a Motorola Delta running System V
2878 R3.6, the version of @code{gethostbyname} in the standard library works,
2879 but the one that works with NIS doesn't (the one you get with -linet).
2880 Other operating systems have similar problems.
2887 Explicitly add the host you want to communicate with to @file{/etc/hosts}.
2890 Relink Emacs with this line in @file{src/config.h}:
2893 #define LIBS_SYSTEM -lresolv
2897 Replace @code{gethostbyname} and friends in @file{libc.a} with more
2898 useful versions such as the ones in @file{libresolv.a}. Then relink
2902 If you are actually running NIS, make sure that @code{ypbind} is
2903 properly told to do DNS lookups with the correct command line switch.
2907 @node Errors with init files
2908 @section Why does Emacs say @samp{Error in init file}?
2909 @cindex Error in @file{.emacs}
2910 @cindex Error in init file
2911 @cindex Init file, errors in
2912 @cindex @file{.emacs} file, errors in
2913 @cindex Debugging @file{.emacs} file
2915 An error occurred while loading either your @file{.emacs} file or the
2916 system-wide file @file{site-lisp/default.el}. Emacs 21.1 and later pops the
2917 @file{*Messages*} buffer, and puts there some additional information
2918 about the error, to provide some hints for debugging.
2920 For information on how to debug your @file{.emacs} file, see
2921 @ref{Debugging a customization file}.
2923 It may be the case that you need to load some package first, or use a
2924 hook that will be evaluated after the package is loaded. A common case
2925 of this is explained in @ref{Terminal setup code works after Emacs has
2928 @node Emacs ignores X resources
2929 @section Why does Emacs ignore my X resources (my .Xdefaults file)?
2930 @cindex X resources being ignored
2931 @cindex Ignored X resources
2932 @cindex @file{.Xdefaults}
2934 As of version 19, Emacs searches for X resources in the files specified
2935 by the following environment variables:
2939 @item @code{XFILESEARCHPATH}
2940 @item @code{XUSERFILESEARCHPATH}
2941 @item @code{XAPPLRESDIR}
2945 This emulates the functionality provided by programs written using the
2948 @code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
2949 of file names separated by colons. @code{XAPPLRESDIR} should be a list
2950 of directory names separated by colons.
2952 Emacs searches for X resources:
2957 specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
2960 then in the value of the @samp{XENVIRONMENT} environment variable,
2965 or if that is unset, in the file named
2966 @file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
2967 the name of the machine Emacs is running on),
2972 then in the screen-specific and server-wide resource properties provided
2978 or if those properties are unset, in the file named @file{~/.Xdefaults}
2984 then in the files listed in @samp{XUSERFILESEARCHPATH},
2989 or in files named @file{@var{lang}/Emacs} in directories listed in
2990 @samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
2991 environment variable), if the @samp{LANG} environment variable is set,
2993 or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
2995 or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
2998 or in @file{~/Emacs},
3003 then in the files listed in @code{XFILESEARCHPATH}.
3007 @node Emacs ignores frame parameters
3008 @section Why don't my customizations of the frame parameters work?
3009 @cindex Frame parameters
3011 This probably happens because you have set the frame parameters in the
3012 variable @code{initial-frame-alist}. That variable holds parameters
3013 used only for the first frame created when Emacs starts. To customize
3014 the parameters of all frames, change the variable
3015 @code{default-frame-alist} instead.
3017 These two variables exist because many users customize the initial frame
3018 in a special way. For example, you could determine the position and
3019 size of the initial frame, but would like to control the geometry of the
3020 other frames by individually positioning each one of them.
3023 @node Emacs takes a long time to visit files
3024 @section Why does Emacs take 20 seconds to visit a file?
3025 @cindex Visiting files takes a long time
3026 @cindex Delay when visiting files
3027 @cindex Files, take a long time to visit
3029 Old versions of Emacs (i.e., versions before Emacs 20.x) often
3030 encountered this when the master lock file, @file{!!!SuperLock!!!}, has
3031 been left in the lock directory somehow. Delete it.
3033 @email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug
3034 where an exclusive create succeeds but returns an error status. This
3035 can cause the same problem. Since Emacs's file locking doesn't work
3036 over NFS anyway, the best solution is to recompile Emacs with
3037 @code{CLASH_DETECTION} undefined.
3039 @node Editing files with $ in the name
3040 @section How do I edit a file with a @samp{$} in its name?
3041 @cindex Editing files with @samp{$} in the name
3042 @cindex @samp{$} in file names
3043 @cindex File names containing @samp{$}, editing
3045 When entering a file name in the minibuffer, Emacs will attempt to expand
3046 a @samp{$} followed by a word as an environment variable. To suppress
3047 this behavior, type @kbd{$$} instead.
3049 @node Shell mode loses the current directory
3050 @section Why does shell mode lose track of the shell's current directory?
3051 @cindex Current directory and @code{shell-mode}
3052 @cindex @code{shell-mode} and current directory
3053 @cindex Directory, current in @code{shell-mode}
3055 Emacs has no way of knowing when the shell actually changes its
3056 directory. This is an intrinsic limitation of Unix. So it tries to
3057 guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed
3058 by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
3059 with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
3060 correctly guess the shell's new current directory. A huge variety of
3061 fixes and enhancements to shell mode for this problem have been written
3062 to handle this problem (@pxref{Finding a package with particular
3065 You can tell Emacs the shell's current directory with the command
3068 @node Security risks with Emacs
3069 @section Are there any security risks in Emacs?
3070 @cindex Security with Emacs
3071 @cindex @samp{movemail} and security
3072 @cindex @code{file-local-variable} and security
3073 @cindex Synthetic X events and security
3074 @cindex X events and security
3079 The @file{movemail} incident. (No, this is not a risk.)
3081 In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
3082 chapter 4. The site at LBL had installed the @file{/etc/movemail}
3083 program setuid root. (As of version 19, @file{movemail} is in your
3084 architecture-specific directory; type @kbd{C-h v exec-directory
3085 @key{RET}} to see what it is.) Since @code{movemail} had not been
3086 designed for this situation, a security hole was created and users could
3087 get root privileges.
3089 @code{movemail} has since been changed so that this security hole will
3090 not exist, even if it is installed setuid root. However,
3091 @code{movemail} no longer needs to be installed setuid root, which
3092 should eliminate this particular risk.
3094 We have heard unverified reports that the 1988 Internet worm took
3095 advantage of this configuration problem.
3098 The @code{file-local-variable} feature. (Yes, a risk, but easy to
3101 There is an Emacs feature that allows the setting of local values for
3102 variables when editing a file by including specially formatted text near
3103 the end of the file. This feature also includes the ability to have
3104 arbitrary Emacs Lisp code evaluated when the file is visited.
3105 Obviously, there is a potential for Trojan horses to exploit this
3108 As of Emacs 22, Emacs has a list of local variables that are known to
3109 be safe to set. If a file tries to set any variable outside this
3110 list, it asks the user to confirm whether the variables should be set.
3111 You can also tell Emacs whether to allow the evaluation of Emacs Lisp
3112 code found at the bottom of files by setting the variable
3113 @code{enable-local-eval}.
3115 For more information, @inforef{File Variables, File Variables, emacs}.
3118 Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
3121 Emacs accepts synthetic X events generated by the @code{SendEvent}
3122 request as though they were regular events. As a result, if you are
3123 using the trivial host-based authentication, other users who can open X
3124 connections to your X workstation can make your Emacs process do
3125 anything, including run other processes with your privileges.
3127 The only fix for this is to prevent other users from being able to open
3128 X connections. The standard way to prevent this is to use a real
3129 authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using
3130 the @code{xauth} program has any effect, then you are probably using
3131 @samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior
3132 authentication method; ask your system administrator.
3134 If real authentication is not a possibility, you may be satisfied by
3135 just allowing hosts access for brief intervals while you start your X
3136 programs, then removing the access. This reduces the risk somewhat by
3137 narrowing the time window when hostile users would have access, but
3138 @emph{does not eliminate the risk}.
3140 On most computers running Unix and X, you enable and disable
3141 access using the @code{xhost} command. To allow all hosts access to
3149 at the shell prompt, which (on an HP machine, at least) produces the
3153 access control disabled, clients can connect from any host
3156 To deny all hosts access to your X server (except those explicitly
3157 allowed by name), use
3163 On the test HP computer, this command generated the following message:
3166 access control enabled, only authorized clients can connect
3171 @node Dired claims that no file is on this line
3172 @section Dired says, @samp{no file on this line} when I try to do something.
3173 @cindex Dired does not see a file
3175 @c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
3177 Chances are you're using a localized version of Unix that doesn't use US
3178 date format in dired listings. You can check this by looking at dired
3179 listings or by typing @kbd{ls -l} to a shell and looking at the dates that
3182 Dired uses a regular expression to find the beginning of a file name.
3183 In a long Unix-style directory listing (@samp{ls -l}), the file name
3184 starts after the date. The regexp has thus been written to look for the
3185 date, the format of which can vary on non-US systems.
3187 There are two approaches to solving this. The first one involves
3188 setting things up so that @samp{ls -l} outputs US date format. This can
3189 be done by setting the locale. See your OS manual for more information.
3191 The second approach involves changing the regular expression used by
3192 dired, @code{directory-listing-before-filename-regexp}.
3194 @c ------------------------------------------------------------
3195 @node Compiling and installing Emacs
3196 @chapter Compiling and installing Emacs
3197 @cindex Compiling and installing Emacs
3200 * Installing Emacs::
3202 * Problems building Emacs::
3205 @node Installing Emacs
3206 @section How do I install Emacs?
3207 @cindex Installing Emacs
3208 @cindex Unix systems, installing Emacs on
3209 @cindex Downloading and installing Emacs
3210 @cindex Retrieving and installing Emacs
3211 @cindex Building Emacs from source
3212 @cindex Source code, building Emacs from
3213 @cindex Unpacking and installing Emacs
3215 This answer is meant for users of Unix and Unix-like systems. Users of
3216 other operating systems should see the series of questions beginning
3217 with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
3218 and binaries, and how to install Emacs on those systems.
3220 For Unix and Unix-like systems, the easiest way is often to compile it
3221 from scratch. You will need:
3226 Emacs sources. @xref{Current GNU distributions}, for a list of ftp sites
3227 that make them available. On @file{ftp.gnu.org}, the main GNU
3228 distribution site, sources are available as
3230 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-@value{VER}.tar.gz}
3232 The above will obviously change as new versions of Emacs come out. For
3233 instance, when Emacs 24.3 is released, it will most probably be
3236 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-24.3.tar.gz}
3238 Again, you should use one of the GNU mirror sites (see @ref{Current GNU
3239 distributions}, and adjust the URL accordingly) so as to reduce load on
3243 @code{gzip}, the GNU compression utility. You can get @code{gzip} via
3244 anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile
3245 and install without much trouble on most systems. Once you have
3246 retrieved the Emacs sources, you will probably be able to uncompress
3247 them with the command
3250 gunzip --verbose emacs-@value{VER}.tar.gz
3254 changing the Emacs version (@value{VER}), as necessary. Once
3255 @code{gunzip} has finished doing its job, a file by the name of
3256 @file{emacs-@value{VER}.tar} should be in your build directory.
3259 @code{tar}, the @dfn{tape archiving} program, which moves multiple files
3260 into and out of archive files, or @dfn{tarfiles}. All of the files
3261 comprising the Emacs source come in a single tarfile, and must be
3262 extracted using @code{tar} before you can build Emacs. Typically, the
3263 extraction command would look like
3266 tar -xvvf emacs-@value{VER}.tar
3270 The @samp{x} indicates that we want to extract files from this tarfile,
3271 the two @samp{v}s force verbose output, and the @samp{f} tells
3272 @code{tar} to use a disk file, rather than one on the tape drive.
3274 If you're using GNU @code{tar} (available at mirrors of
3275 @file{ftp.gnu.org}), you can combine this step and the previous one by
3279 tar -zxvvf emacs-@value{VER}.tar.gz
3283 The additional @samp{z} at the beginning of the options list tells GNU
3284 @code{tar} to uncompress the file with @code{gunzip} before extracting
3285 the tarfile's components.
3289 At this point, the Emacs sources (all 70+ megabytes of them) should be
3290 sitting in a directory called @file{emacs-@value{VER}}. On most common
3291 Unix and Unix-like systems, you should be able to compile Emacs (with X
3292 Window system support) with the following commands:
3295 cd emacs-@value{VER} # change directory to emacs-@value{VER}
3296 ./configure # configure Emacs for your particular system
3297 make # use Makefile to build components, then Emacs
3300 If the @code{make} completes successfully, the odds are fairly good that
3301 the build has gone well. (@xref{Problems building Emacs}, if you weren't
3304 By default, Emacs is installed in the following directories:
3307 @item /usr/local/bin
3310 @item /usr/local/share/emacs/@value{VER}
3311 Lisp code and support files.
3313 @item /usr/local/info
3317 To install files in those default directories, become the superuser and
3324 Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
3325 and any Emacs Info files that might be in @file{/usr/local/info}.
3327 Much more verbose instructions (with many more hints and suggestions)
3328 come with the Emacs sources, in the file @file{INSTALL}.
3330 @node Updating Emacs
3331 @section How do I update Emacs to the latest version?
3332 @cindex Updating Emacs
3334 @xref{Installing Emacs}, and follow the instructions there for
3337 Most files are placed in version-specific directories. Emacs
3338 @value{VER}, for instance, places files in
3339 @file{/usr/local/share/emacs/@value{VER}}.
3341 Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs
3342 binary) and documentation in @file{/usr/local/info}. Back up these
3343 files before you upgrade, and you shouldn't have too much trouble.
3345 @node Problems building Emacs
3346 @section What should I do if I have trouble building Emacs?
3347 @cindex Problems building Emacs
3348 @cindex Errors when building Emacs
3350 First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
3351 source) to see if there is already a solution for your problem. Next,
3352 look for other questions in this FAQ that have to do with Emacs
3353 installation and compilation problems.
3355 If you'd like to have someone look at your problem and help solve it,
3356 see @ref{Help installing Emacs}.
3358 If you cannot find a solution in the documentation, send a message to
3359 @email{bug-gnu-emacs@@gnu.org}.
3361 Please don't post it to @uref{news:gnu.emacs.help} or send e-mail to
3362 @email{help-gnu-emacs@@gnu.org}. For further guidelines, see
3363 @ref{Guidelines for newsgroup postings} and @ref{Reporting bugs}.
3366 @c ------------------------------------------------------------
3367 @node Finding Emacs and related packages
3368 @chapter Finding Emacs and related packages
3369 @cindex Finding Emacs and related packages
3372 * Finding Emacs on the Internet::
3373 * Finding a package with particular functionality::
3374 * Packages that do not come with Emacs::
3375 * Current GNU distributions::
3376 * Difference between Emacs and XEmacs::
3377 * Emacs for minimalists::
3378 * Emacs for MS-DOS::
3379 * Emacs for Windows::
3380 * Emacs for GNUstep::
3381 * Emacs for Apple computers::
3384 @node Finding Emacs on the Internet
3385 @section Where can I get Emacs on the net (or by snail mail)?
3386 @cindex Finding Emacs on the Internet
3387 @cindex Snail mail, ordering Emacs via
3388 @cindex Postal service, ordering Emacs via
3389 @cindex Distribution, retrieving Emacs
3390 @cindex Internet, retrieving from
3392 Information on downloading Emacs is available at
3393 @uref{http://www.gnu.org/software/emacs/, the Emacs home-page}.
3395 For an order form for all Emacs and FSF distributions deliverable from
3396 the USA, see @uref{http://shop.fsf.org/}.
3398 @xref{Installing Emacs}, for information on how to obtain and build the latest
3399 version of Emacs, and see @ref{Current GNU distributions}, for a list of
3400 archive sites that make GNU software available.
3402 @node Finding a package with particular functionality
3403 @section How do I find a Emacs Lisp package that does XXX?
3404 @cindex Package, finding
3405 @cindex Finding an Emacs Lisp package
3406 @cindex Functionality, finding a particular package
3408 First of all, you should check to make sure that the package isn't
3409 already available. For example, typing @kbd{M-x apropos @key{RET}
3410 wordstar @key{RET}} lists all functions and variables containing the
3411 string @samp{wordstar}.
3413 It is also possible that the package is on your system, but has not been
3414 loaded. To see which packages are available for loading, look through
3415 your computer's lisp directory (@pxref{File-name conventions}). The Lisp
3416 source to most packages contains a short description of how they
3417 should be loaded, invoked, and configured---so before you use or
3418 modify a Lisp package, see if the author has provided any hints in the
3421 The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
3422 the constituent Emacs packages.
3424 For advice on how to find extra packages that are not part of Emacs,
3425 see @ref{Packages that do not come with Emacs}.
3427 @node Packages that do not come with Emacs
3428 @section Where can I get Emacs Lisp packages that don't come with Emacs?
3429 @cindex Unbundled packages
3430 @cindex Finding other packages
3431 @cindex Lisp packages that do not come with Emacs
3432 @cindex Packages, those that do not come with Emacs
3433 @cindex Emacs Lisp List
3434 @cindex Emacs Lisp Archive
3436 @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs Lisp
3437 List (ELL)}, maintained by @email{S.J.Eglen@@damtp.cam.ac.uk, Stephen Eglen},
3438 aims to provide one compact list with links to all of the current Emacs
3439 Lisp files on the Internet. The ELL can be browsed over the web, or
3440 from Emacs with @uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.el,
3441 the @file{ell} package}.
3443 Many authors post their packages to the @uref{news:gnu.emacs.sources,
3444 Emacs sources newsgroup}. You can search the archives of this
3445 group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google},
3446 or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example.
3448 Several packages are stored in
3449 @uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}.
3451 Read the file @file{etc/MORE.STUFF} for more information about
3454 @node Current GNU distributions
3455 @section Where can I get other up-to-date GNU stuff?
3456 @cindex Current GNU distributions
3457 @cindex Sources for current GNU distributions
3458 @cindex Stuff, current GNU
3459 @cindex Up-to-date GNU stuff
3460 @cindex Finding current GNU software
3461 @cindex Official GNU software sites
3463 The most up-to-date official GNU software is normally kept at
3465 @uref{ftp://ftp.gnu.org/pub/gnu}
3467 A list of sites mirroring @samp{ftp.gnu.org} can be found at
3469 @uref{http://www.gnu.org/order/ftp.html}
3471 @node Difference between Emacs and XEmacs
3472 @section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
3474 @cindex Difference Emacs and XEmacs
3478 XEmacs is a branch version of Emacs. It was first called Lucid Emacs,
3479 and was initially derived from a prerelease version of Emacs 19. In
3480 this FAQ, we use the name ``Emacs'' only for the official version.
3482 Emacs and XEmacs each come with Lisp packages that are lacking in the
3483 other. The two versions have some significant differences at the Lisp
3484 programming level. Their current features are roughly comparable,
3485 though the support for some operating systems, character sets and
3486 specific packages might be quite different.
3488 Some XEmacs code has been contributed to Emacs, and we would like to
3489 use other parts, but the earlier XEmacs maintainers did not always
3490 keep track of the authors of contributed code, which makes it
3491 impossible for the FSF to get copyright papers signed for that code.
3492 (The FSF requires these papers for all the code included in the Emacs
3493 release, aside from generic C support packages that retain their
3494 separate identity and are not integrated into the code of Emacs
3497 If you want to talk about these two versions and distinguish them,
3498 please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs''
3499 with ``GNU Emacs'' would be misleading, since XEmacs too has its
3500 origin in the work of the GNU Project. Terms such as ``Emacsen'' and
3501 ``(X)Emacs'' are not wrong, but they are not very clear, so it
3502 is better to write ``Emacs and XEmacs.''
3504 @node Emacs for minimalists
3505 @section I don't have enough disk space to install Emacs
3507 @cindex Not enough disk space to install Emacs
3509 GNU Zile is a lightweight Emacs clone. Zile is short for @samp{Zile Is
3510 Lossy Emacs}. It has all of Emacs's basic editing features. The Zile
3511 binary typically has a size of about 130 kbytes, so this can be useful
3512 if you are in an extremely space-restricted environment. More
3513 information is available from
3515 @uref{http://www.gnu.org/software/zile/}
3518 @node Emacs for MS-DOS
3519 @section Where can I get Emacs for my PC running MS-DOS?
3520 @cindex MS-DOS, Emacs for
3521 @cindex DOS, Emacs for
3522 @cindex Compiling Emacs for DOS
3523 @cindex Emacs for MS-DOS
3524 @cindex Tools needed to compile Emacs under DOS
3526 A pre-built binary distribution of Emacs 20 is available from the
3527 SimTel.NET archives. This version apparently works under MS-DOS and
3528 Windows (3.X, 9X, ME, NT, and 2000) and supports long file names under
3529 Windows 9X, Windows ME, and Windows 2000. More information is available
3532 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README}
3534 The binary itself is available in the files @file{em*.zip} in the
3537 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/}
3539 If you prefer to compile Emacs for yourself, you can do so with the
3540 current distribution directly. You will need a 386 (or
3541 better) processor, and to be running MS-DOS 3.0 or later. According to
3542 @email{eliz@@gnu.org, Eli Zaretskii} and
3543 @email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the
3549 DJGPP version 1.12 maint 1 or later. Djgpp 2.0 or later is
3550 recommended, since 1.x is very old an unmaintained. Djgpp 2 supports
3551 long file names on Windows 9X/ME/2K.
3553 You can get the latest release of DJGPP by retrieving all of
3556 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2*}
3558 @item Unpacking program
3559 The easiest way is to use @code{djtar} which comes with DJGPP v2.x,
3560 because it can open gzip'ed tarfiles (i.e., those ending with
3561 @file{.tar.gz}) in one step. @code{Djtar} comes in
3562 @file{djdev@var{nnn}.zip} archive (where @var{nnn} is the DJGPP version
3563 number), from the URL mentioned above.
3565 @strong{Warning!} Do @strong{not} use the popular WinZip program to
3566 unpack the Emacs distribution! WinZip is known to corrupt some of the
3567 files by converting them to the DOS CR-LF format, it doesn't always
3568 preserve the directory structure recorded in the compressed Emacs
3569 archive, and commits other atrocities. Some of these problems could
3570 actually prevent Emacs from building successfully!
3572 @item make, mv, sed, and rm
3573 All of these utilities are available at
3575 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu}
3577 16-bit utilities can be found in GNUish, at
3579 @uref{http://www.simtel.net/pub/gnuish/}
3582 (@code{mv} and @code{rm} are in the Fileutils package, @code{sed} and
3583 @code{make} are each one in a separate package named after them.)
3587 The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
3588 directory of the Emacs sources contains some additional information
3589 regarding Emacs under MS-DOS.
3591 For a list of other MS-DOS implementations of Emacs (and Emacs
3592 look-alikes), consult the list of ``Emacs implementations and literature,''
3595 @uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}
3597 Note that while many of these programs look similar to Emacs, they often
3598 lack certain features, such as the Emacs Lisp extension language.
3600 @node Emacs for Windows
3601 @section Where can I get Emacs for Microsoft Windows?
3602 @cindex FAQ for NT Emacs
3603 @cindex Emacs for MS-Windows
3604 @cindex Microsoft Windows, Emacs for
3605 @cindex Windows 9X, ME, NT, 2K, and CE, Emacs for
3607 For information on Emacs for Windows 95 and NT, read the FAQ produced by
3608 @email{voelker@@cs.washington.edu, Geoff Voelker} and currently maintained
3609 by @email{ramprasad@@gnu.org, Ramprasad B}, available at
3611 @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html}
3613 @xref{Emacs for MS-DOS}, for Windows 3.1.
3616 @node Emacs for GNUstep
3617 @section Where can I get Emacs for GNUstep?
3618 @cindex GNUSTEP, Emacs for
3620 Beginning with version 23.1, Emacs supports GNUstep natively.
3622 @node Emacs for Apple computers
3623 @section Where can I get Emacs for my Apple computer?
3624 @cindex Apple computers, Emacs for
3625 @cindex Macintosh, Emacs for
3627 Beginning with version 22.1, Emacs supports Mac OS X natively.
3630 @c ------------------------------------------------------------
3631 @node Major packages and programs
3632 @chapter Major packages and programs
3633 @cindex Major packages and programs
3646 @section VM (View Mail) --- another mail reader within Emacs, with MIME support
3648 @cindex Alternative mail software
3650 @cindex E-mail reader, VM
3655 @uref{http://www.nongnu.org/viewmail/}
3657 @item Informational newsgroup
3658 @uref{news:gnu.emacs.vm.info}@*
3660 @item Bug reports newsgroup
3661 @uref{news:gnu.emacs.vm.bug}@*
3664 VM was originally written by @uref{http://www.wonderworks.com/vm/,Kyle Jones}.
3665 @uref{ftp://ftp.wonderworks.com/pub/vm/,Older versions} of VM remain
3670 @section AUC@TeX{} --- enhanced @TeX{} modes with debugging facilities
3671 @cindex Mode for @TeX{}
3673 @cindex AUC@TeX{} mode for editing @TeX{}
3674 @cindex Writing and debugging @TeX{}
3676 AUC@TeX{} is a set of sophisticated major modes for @TeX{}, LaTeX,
3677 ConTeXt, and Texinfo offering context-sensitive syntax highlighting,
3678 indentation, formatting and folding, macro completion, @TeX{} shell
3679 functionality, and debugging. Be also sure to check out
3680 @ref{Introduction, RefTeX, Introduction, reftex, Ref@TeX{} User Manual}.
3681 Current versions of AUC@TeX{} include the
3682 @uref{http://www.gnu.org/software/auctex/preview-latex.html,preview-latex}
3683 package for WYSIWYG previews of various LaTeX constructs in the Emacs
3686 @uref{http://www.gnu.org/software/auctex/, AUCTeX}
3689 @section BBDB --- personal Info Rolodex integrated with mail/news readers
3691 @cindex Rolodex-like functionality
3692 @cindex Integrated contact database
3693 @cindex Contact database
3694 @cindex Big Brother Database
3695 @cindex Address book
3697 @uref{http://bbdb.sourceforge.net/, The Insidious Big Brother Database}
3699 @node Spell-checkers
3700 @section Spell-checkers
3701 @cindex Spell-checker
3702 @cindex Checking spelling
3707 Various spell-checkers are compatible with Emacs, including:
3712 @uref{http://aspell.net/}
3715 @uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
3718 @uref{http://hunspell.sourceforge.net/}
3723 @section Emacs/W3 --- A World Wide Web browser inside of Emacs
3726 @cindex HTML browser in Emacs
3727 @cindex @code{w3-mode}
3729 @uref{http://www.gnu.org/software/w3/, Emacs/W3}
3732 @section EDB --- Database program for Emacs; replaces forms editing modes
3737 @uref{http://gnuvola.org/software/edb/, the Emacs Database}
3740 @section JDE --- Integrated development environment for Java
3741 @cindex Java development environment
3742 @cindex Integrated Java development environment
3745 @uref{http://jdee.sourceforge.net/, a Java Development Environment for Emacs}
3747 @c ------------------------------------------------------------
3749 @chapter Key bindings
3750 @cindex Key bindings
3753 * Binding keys to commands::
3754 * Invalid prefix characters::
3755 * Terminal setup code works after Emacs has begun::
3756 * Working with function and arrow keys::
3757 * X key translations for Emacs::
3758 * Handling C-s and C-q with flow control::
3759 * Binding C-s and C-q::
3760 * Backspace invokes help::
3761 * stty and Backspace key::
3763 * Producing C-XXX with the keyboard::
3766 * Compose Character::
3767 * Binding combinations of modifiers and function keys::
3768 * Meta key does not work in xterm::
3769 * ExtendChar key does not work as Meta::
3770 * SPC no longer completes file names::
3773 @node Binding keys to commands
3774 @section How do I bind keys (including function keys) to commands?
3775 @cindex Binding keys to commands
3776 @cindex Keys, binding to commands
3777 @cindex Commands, binding keys to
3779 Keys can be bound to commands either interactively or in your
3780 @file{.emacs} file. To interactively bind keys for all modes, type
3781 @kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3783 To bind a key just in the current major mode, type @kbd{M-x
3784 local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
3786 @inforef{Key Bindings, Key Bindings, emacs}, for further details.
3788 To make the process of binding keys interactively easier, use the
3789 following ``trick'': First bind the key interactively, then immediately
3790 type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
3791 to bind the key is in the kill ring, and can be yanked into your
3792 @file{.emacs} file. If the key binding is global, no changes to the
3793 command are required. For example,
3796 (global-set-key (quote [f1]) (quote help-for-help))
3800 can be placed directly into the @file{.emacs} file. If the key binding is
3801 local, the command is used in conjunction with the @samp{add-hook} function.
3802 For example, in TeX mode, a local binding might be
3805 (add-hook 'tex-mode-hook
3807 (local-set-key (quote [f1]) (quote help-for-help))))
3814 Control characters in key sequences, in the form yanked from the kill
3815 ring are given in their graphic form---i.e., @key{CTRL} is shown as
3816 @samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want
3817 to convert these into their vector or string forms.
3820 If a prefix key of the character sequence to be bound is already
3821 bound as a complete key, then you must unbind it before the new
3822 binding. For example, if @kbd{ESC @{} is previously bound:
3825 (global-unset-key [?\e ?@{]) ;; or
3826 (local-unset-key [?\e ?@{])
3830 Aside from commands and ``lambda lists,'' a vector or string also
3831 can be bound to a key and thus treated as a macro. For example:
3834 (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or
3835 (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
3840 @node Invalid prefix characters
3841 @section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
3842 @cindex Prefix characters, invalid
3843 @cindex Invalid prefix characters
3844 @cindex Misspecified key sequences
3846 Usually, one of two things has happened. In one case, the control
3847 character in the key sequence has been misspecified (e.g. @samp{C-f}
3848 used instead of @samp{\C-f} within a Lisp expression). In the other
3849 case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
3850 was already bound as a @dfn{complete key}. Historically, the @samp{ESC [}
3851 prefix was usually the problem, in which case you should evaluate either
3852 of these forms before attempting to bind the key sequence:
3855 (global-unset-key [?\e ?[]) ;; or
3856 (global-unset-key "\e[")
3859 @node Terminal setup code works after Emacs has begun
3860 @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?
3861 @cindex Terminal setup code in @file{.emacs}
3863 During startup, Emacs initializes itself according to a given code/file
3864 order. If some of the code executed in your @file{.emacs} file needs to
3865 be postponed until the initial terminal or window-system setup code has
3866 been executed but is not, then you will experience this problem (this
3867 code/file execution order is not enforced after startup).
3869 To postpone the execution of Emacs Lisp code until after terminal or
3870 window-system setup, treat the code as a @dfn{lambda list} and set the
3871 value of either the @code{term-setup-hook} or @code{window-setup-hook}
3872 variable to this lambda function. For example,
3875 (add-hook 'term-setup-hook
3877 (when (string-match "\\`vt220" (or (getenv "TERM") ""))
3878 ;; Make vt220's "Do" key behave like M-x:
3879 (global-set-key [do] 'execute-extended-command))))
3882 For information on what Emacs does every time it is started, see the
3883 @file{lisp/startup.el} file.
3885 @node Working with function and arrow keys
3886 @section How do I tell what characters or symbols my function or arrow keys emit?
3887 @cindex Working with arrow keys
3888 @cindex Arrow keys, symbols generated by
3889 @cindex Working with function keys
3890 @cindex Function keys, symbols generated by
3891 @cindex Symbols generated by function keys
3893 Type @kbd{C-h c} then the function or arrow keys. The command will
3894 return either a function key symbol or character sequence (see the
3895 Emacs documentation for an explanation). This works for other
3898 @node X key translations for Emacs
3899 @section How do I set the X key ``translations'' for Emacs?
3900 @cindex X key translations
3901 @cindex Key translations under X
3902 @cindex Translations for keys under X
3904 Emacs is not written using the Xt library by default, so there are no
3905 ``translations'' to be set. (We aren't sure how to set such translations
3906 if you do build Emacs with Xt; please let us know if you've done this!)
3908 The only way to affect the behavior of keys within Emacs is through
3909 @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The
3910 @code{define-key} command should be used in conjunction with the
3911 @code{function-key-map} map. For instance,
3914 (define-key function-key-map [M-@key{TAB}] [?\M-\t])
3918 defines the @kbd{M-@key{TAB}} key sequence.
3920 @node Handling C-s and C-q with flow control
3921 @section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control?
3922 @cindex Flow control, @kbd{C-s} and @kbd{C-q} with
3923 @cindex @kbd{C-s} and @kbd{C-q} with flow control
3925 @kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol.
3926 This messes things up when you're using Emacs over a serial line,
3927 because Emacs binds these keys to commands by default. Because Emacs
3928 won't honor them as flow control characters, too many of these
3929 characters are not passed on and overwhelm output buffers. Sometimes,
3930 intermediate software using XON/XOFF flow control will prevent Emacs
3931 from ever seeing @kbd{C-s} and @kbd{C-q}.
3938 Disable the use of @kbd{C-s} and @kbd{C-q} for flow control.
3940 You need to determine the cause of the flow control.
3947 Your terminal may use XON/XOFF flow control to have time to display
3948 all the characters it receives. For example, VT series terminals do
3949 this. It may be possible to turn this off from a setup menu. For
3950 example, on a VT220 you may select ``No XOFF'' in the setup menu. This
3951 is also true for some terminal emulation programs on PCs.
3953 When you turn off flow control at the terminal, you will also need to
3954 turn it off at the other end, which might be at the computer you are
3955 logged in to or at some terminal server in between.
3957 If you turn off flow control, characters may be lost; using a printer
3958 connected to the terminal may fail. You may be able to get around
3959 this problem by modifying the @samp{termcap} entry for your terminal to
3960 include extra NUL padding characters.
3965 If you are using a dialup connection, the modems may be using
3966 XON/XOFF flow control. It's not clear how to get around this.
3969 a router or terminal server
3971 Some network box between the terminal and your computer may be using
3972 XON/XOFF flow control. It may be possible to make it use some other
3973 kind of flow control. You will probably have to ask your local
3974 network experts for help with this.
3977 @code{tty} and/or @code{pty} devices
3979 If your connection to Emacs goes through multiple @code{tty} and/or
3980 @code{pty} devices, they may be using XON/XOFF flow control even when it
3983 @email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes:
3986 Some versions of @code{rlogin} (and possibly @code{telnet}) do not pass
3987 flow control characters to the remote system to which they connect. On
3988 such systems, Emacs on the remote system cannot disable flow control on
3989 the local system. Sometimes @samp{rlogin -8} will avoid this problem.
3991 One way to cure this is to disable flow control on the local host (the
3992 one running @code{rlogin}, not the one running @code{rlogind}) using the
3993 @code{stty} command, before starting the @code{rlogin} process. On many
3994 systems, @samp{stty start u stop u} will do this.
3996 Some versions of @samp{tcsh} will prevent even this from working. One
3997 way around this is to start another shell before starting rlogin,
3998 and issue the @samp{stty} command to disable flow control from that shell.
4001 Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems.
4006 Make Emacs speak the XON/XOFF flow control protocol.
4008 You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by
4012 (enable-flow-control)
4016 to unconditionally enable flow control or
4019 (enable-flow-control-on "vt100" "h19")
4023 (using your terminal names instead of @samp{vt100} or @samp{h19}) to
4024 enable selectively. These commands will automatically swap @kbd{C-s}
4025 and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}. Variables can be used to
4026 change the default swap keys (@code{flow-control-c-s-replacement} and
4027 @code{flow-control-c-q-replacement}).
4029 If you are fixing this for yourself, simply put the form in your
4030 @file{.emacs} file. If you are fixing this for your entire site, the
4031 best place to put it is in the @file{site-lisp/site-start.el} file.
4032 (Here @file{site-lisp} is actually a subdirectory of your Emacs
4033 installation directory, typically @file{/usr/local/share/emacs}.)
4034 Putting this form in @file{site-lisp/default.el} has the problem that
4035 if the user's @file{.emacs} file has an error, this will prevent
4036 @file{default.el} from being loaded and Emacs may be unusable for the
4037 user, even for correcting their @file{.emacs} file (unless they're
4038 smart enough to move it to another name).
4040 @code{enable-flow-control} can be invoked interactively as well:
4041 @kbd{M-x enable-flow-control @key{RET}}.
4045 For further discussion of this issue, read the file @file{etc/PROBLEMS}
4046 (@pxref{File-name conventions}).
4048 @node Binding C-s and C-q
4049 @section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out?
4050 @cindex Binding @kbd{C-s} and @kbd{C-q}
4051 @cindex @kbd{C-s} and @kbd{C-q}, binding
4053 To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control}
4054 or @code{enable-flow-control-on}. @xref{Handling C-s and C-q with flow
4055 control}, for usage and implementation details.
4057 To bind other keys, use @code{keyboard-translate}. @xref{Swapping
4058 keys}, for usage details. To do this for an entire site, you should
4059 swap the keys in @file{site-lisp/site-start.el}. @xref{Handling C-s
4060 and C-q with flow control}, for an explanation of why
4061 @file{site-lisp/default.el} should not be used.
4066 If you do this for an entire site, the users will be confused by
4067 the disparity between what the documentation says and how Emacs
4072 @node Backspace invokes help
4073 @section Why does the @key{Backspace} key invoke help?
4074 @cindex Backspace key invokes help
4075 @cindex Help invoked by Backspace
4076 @cindex DEL key does not delete
4078 The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8.
4079 @kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes
4080 help-command. This is intended to be easy to remember since the first
4081 letter of @samp{help} is @samp{h}. The easiest solution to this problem
4082 is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
4083 @key{Delete} key) for deleting the previous character.
4085 For many people this solution may be problematic:
4090 They normally use @key{Backspace} outside of Emacs for deleting the
4091 previous character. This can be solved by making @key{DEL} the command
4092 for deleting the previous character outside of Emacs. On many Unix
4093 systems, this command will remap @key{DEL}:
4100 The user may prefer the @key{Backspace} key for deleting the
4101 previous character because it is more conveniently located on their
4102 keyboard or because they don't even have a separate @key{Delete} key.
4103 In this case, the @key{Backspace} key should be made to behave like
4104 @key{Delete}. There are several methods.
4108 Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
4109 TeraTerm) allow the character generated by the @key{Backspace} key to be
4110 changed from a setup menu.
4113 You may be able to get a keyboard that is completely programmable, or a
4114 terminal emulator that supports remapping of any key to any other key.
4117 With Emacs 21.1 and later, you can control the effect of the
4118 @key{Backspace} and @key{Delete} keys, on both dumb terminals and a
4119 windowed displays, by customizing the option
4120 @code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
4121 normal-erase-is-backspace}. See the documentation of these symbols
4122 (@pxref{Emacs Lisp documentation}) for more info.
4125 It is possible to swap the @key{Backspace} and @key{DEL} keys inside
4129 (keyboard-translate ?\C-h ?\C-?)
4133 This is the recommended method of forcing @key{Backspace} to act as
4134 @key{DEL}, because it works even in modes which bind @key{DEL} to
4135 something other than @code{delete-backward-char}.
4137 Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
4138 default deletes forward:
4141 (keyboard-translate ?\C-? ?\C-d)
4144 @xref{Swapping keys}, for further details about @code{keyboard-translate}.
4147 Another approach is to switch key bindings and put help on @kbd{C-x h}
4151 (global-set-key "\C-h" 'delete-backward-char)
4153 ;; overrides mark-whole-buffer
4154 (global-set-key "\C-xh" 'help-command)
4158 This method is not recommended, though: it only solves the problem for
4159 those modes which bind @key{DEL} to @code{delete-backward-char}. Modes
4160 which bind @key{DEL} to something else, such as @code{view-mode}, will
4161 not work as you expect when you press the @key{Backspace} key. For this
4162 reason, we recommend the @code{keyboard-translate} method, shown
4165 Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
4168 Don't try to bind @key{DEL} to @code{help-command}, because there are
4169 many modes that have local bindings of @key{DEL} that will interfere.
4173 When Emacs 21 or later runs on a windowed display, it binds the
4174 @key{Delete} key to a command which deletes the character at point, to
4175 make Emacs more consistent with keyboard operation on these systems.
4177 For more information about troubleshooting this problem, see @ref{DEL
4178 Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
4181 @node stty and Backspace key
4182 @section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}?
4183 @cindex @file{stty} and Emacs
4184 @cindex Backspace and @file{stty}
4185 @cindex Delete and @file{stty}
4189 @c FIXME: RMS explained the reasons for this on emacs-hackers. It's
4190 @c probably worth putting that explanation here.
4193 @section How do I swap two keys?
4194 @cindex Swapping keys
4195 @cindex Keys, swapping
4196 @cindex @code{keyboard-translate}
4198 You can swap two keys (or key sequences) by using the
4199 @code{keyboard-translate} function. For example, to turn @kbd{C-h}
4200 into @key{DEL} and @key{DEL} to @kbd{C-h}, use
4203 (keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL
4204 (keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.
4208 The first key sequence of the pair after the function identifies what is
4209 produced by the keyboard; the second, what is matched for in the
4212 However, in the specific case of @kbd{C-h} and @key{DEL}, you should
4213 toggle @code{normal-erase-is-backspace-mode} instead of calling
4214 @code{keyboard-translate}. @inforef{DEL Does Not Delete, DEL Does Not Delete,
4217 Keyboard translations are not the same as key bindings in keymaps.
4218 Emacs contains numerous keymaps that apply in different situations, but
4219 there is only one set of keyboard translations, and it applies to every
4220 character that Emacs reads from the terminal. Keyboard translations
4221 take place at the lowest level of input processing; the keys that are
4222 looked up in keymaps contain the characters that result from keyboard
4225 @node Producing C-XXX with the keyboard
4226 @section How do I produce C-XXX with my keyboard?
4227 @cindex Producing control characters
4228 @cindex Generating control characters
4229 @cindex Control characters, generating
4231 On terminals (but not under X), some common ``aliases'' are:
4235 @item @kbd{C-2} or @kbd{C-@key{SPC}}
4241 @item @kbd{C-7} or @kbd{C-S--}
4255 Often other aliases exist; use the @kbd{C-h c} command and try
4256 @key{CTRL} with all of the digits on your keyboard to see what gets
4257 generated. You can also try the @kbd{C-h w} command if you know the
4258 name of the command.
4261 @section What if I don't have a @key{Meta} key?
4262 @cindex No @key{Meta} key
4263 @cindex @key{Meta} key, what to do if you lack it
4265 On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
4267 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact,
4268 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
4269 (depending on the value of @code{meta-prefix-char}). Note that you
4270 press @key{Meta} and @key{a} together, but with @key{ESC}, you press
4271 @key{ESC}, release it, and then press @key{a}.
4274 @section What if I don't have an @key{Escape} key?
4275 @cindex No Escape key
4276 @cindex Lacking an Escape key
4277 @cindex Escape key, lacking
4279 Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an
4280 Escape key would. @kbd{C-3} may also work on some terminal (but not
4281 under X). For many terminals (notably DEC terminals) @key{F11}
4282 generates @key{ESC}. If not, the following form can be used to bind it:
4285 ;; F11 is the documented ESC replacement on DEC terminals.
4286 (define-key function-key-map [f11] [?\e])
4289 @node Compose Character
4290 @section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
4291 @cindex @key{Compose Character} key, using as @key{Meta}
4292 @cindex @key{Meta}, using @key{Compose Character} for
4294 On a dumb terminal such as a VT220, no. It is rumored that certain
4295 VT220 clones could have their @key{Compose} key configured this way. If
4296 you're using X, you might be able to do this with the @code{xmodmap}
4299 @node Binding combinations of modifiers and function keys
4300 @section How do I bind a combination of modifier key and function key?
4301 @cindex Modifiers and function keys
4302 @cindex Function keys and modifiers
4303 @cindex Binding modifiers and function keys
4305 With Emacs 19 and later, you can represent modified function keys in
4306 vector format by adding prefixes to the function key symbol. For
4307 example (from the Emacs documentation):
4310 (global-set-key [?\C-x right] 'forward-page)
4314 where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
4316 You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
4317 @key{Super}, @key{Alt}, and @key{Shift} with function keys. To
4318 represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
4319 @samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here
4320 is how to make @kbd{H-M-RIGHT} move forward a word:
4323 (global-set-key [H-M-right] 'forward-word)
4329 Not all modifiers are permitted in all situations. @key{Hyper},
4330 @key{Super}, and @key{Alt} are not available on Unix character
4331 terminals. Non-@acronym{ASCII} keys and mouse events (e.g. @kbd{C-=} and
4332 @kbd{Mouse-1}) also fall under this category.
4336 @xref{Binding keys to commands}, for general key binding instructions.
4338 @node Meta key does not work in xterm
4339 @section Why doesn't my @key{Meta} key work in an @code{xterm} window?
4340 @cindex @key{Meta} key and @code{xterm}
4341 @cindex Xterm and @key{Meta} key
4343 @inforef{Unibyte Mode, Single-Byte Character Set Support, emacs}.
4345 If the advice in the Emacs manual fails, try all of these methods before
4346 asking for further help:
4351 You may have big problems using @code{mwm} as your window manager.
4352 (Does anyone know a good generic solution to allow the use of the
4353 @key{Meta} key in Emacs with @file{mwm}?)
4356 For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to
4357 find out what keysym your @key{Meta} key generates. It should be either
4358 @code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix
4359 the situation. If @key{Meta} does generate @code{Meta_L} or
4360 @code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in
4361 your @file{~/.Xdefaults} file:
4364 XTerm*eightBitInput: false
4365 XTerm*eightBitOutput: true
4369 Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
4370 characters. @samp{stty -a} (or @samp{stty everything}) should show
4371 @samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty
4372 cs8 -istrip} (or @samp{stty pass8}) to fix it.
4375 If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
4376 @samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
4380 If Emacs is running on Ultrix, it is reported that evaluating
4381 @code{(set-input-mode t nil)} helps.
4384 If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
4385 you type @kbd{M-W}, which is the same conversion Emacs would make if it
4386 got the @kbd{M-W} anyway. In X11R4, the following resource
4387 specification will do this:
4390 XTerm.VT100.EightBitInput: false
4394 (This changes the behavior of the @code{insert-eight-bit} action.)
4396 With older @code{xterm}s, you can specify this behavior with a translation:
4399 XTerm.VT100.Translations: #override \
4400 Meta<KeyPress>: string(0x1b) insert()
4404 You might have to replace @samp{Meta} with @samp{Alt}.
4408 @node ExtendChar key does not work as Meta
4409 @section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
4410 @cindex @key{ExtendChar} key as @key{Meta}
4411 @cindex @key{Meta}, using @key{ExtendChar} for
4412 @cindex HP-UX, the @key{ExtendChar} key
4414 This is a result of an internationalization extension in X11R4 and the
4415 fact that HP is now using this extension. Emacs assumes that the
4416 @code{XLookupString} function returns the same result regardless of the
4417 @key{Meta} key state which is no longer necessarily true. Until Emacs
4418 is fixed, the temporary kludge is to run this command after each time
4419 the X server is started but preferably before any xterm clients are:
4422 xmodmap -e 'remove mod1 = Mode_switch'
4425 @c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
4428 This will disable the use of the extra keysyms systemwide, which may be
4429 undesirable if you actually intend to use them.
4431 @node SPC no longer completes file names
4432 @section Why doesn't SPC complete file names anymore?
4433 @cindex @kbd{SPC} file name completion
4435 Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in
4436 the minibuffer, so that file names with embedded spaces could be typed
4437 without the need to quote the spaces.
4439 You can get the old behavior by binding @kbd{SPC} to
4440 @code{minibuffer-complete-word} in the minibuffer, as follows:
4443 (define-key minibuffer-local-filename-completion-map (kbd "SPC")
4444 'minibuffer-complete-word)
4446 (define-key minibuffer-local-must-match-filename-map (kbd "SPC")
4447 'minibuffer-complete-word)
4450 @c ------------------------------------------------------------
4451 @node Alternate character sets
4452 @chapter Alternate character sets
4453 @cindex Alternate character sets
4456 * Emacs does not display 8-bit characters::
4457 * Inputting eight-bit characters::
4458 * Kanji and Chinese characters::
4459 * Right-to-left alphabets::
4460 * How to add fonts::
4463 @node Emacs does not display 8-bit characters
4464 @section How do I make Emacs display 8-bit characters?
4465 @cindex Displaying eight-bit characters
4466 @cindex Eight-bit characters, displaying
4468 @inforef{Unibyte Mode, Single-byte Character Set
4469 Support, emacs}. On a Unix, when Emacs runs on a text-only terminal
4470 display or is invoked with @samp{emacs -nw}, you typically need to use
4471 @code{set-terminal-coding-system} to tell Emacs what the terminal can
4472 display, even after setting the language environment; otherwise
4473 non-@acronym{ASCII} characters will display as @samp{?}. On other operating
4474 systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
4475 character set supported by the display, and sets up the required
4476 terminal coding system automatically.
4478 @node Inputting eight-bit characters
4479 @section How do I input eight-bit characters?
4480 @cindex Entering eight-bit characters
4481 @cindex Eight-bit characters, entering
4482 @cindex Input, 8-bit characters
4484 Various methods are available for input of eight-bit characters. See
4485 @inforef{Unibyte Mode, Single-byte Character Set
4486 Support, emacs}. For more sophisticated methods, @inforef{Input
4487 Methods, Input Methods, emacs}.
4489 @node Kanji and Chinese characters
4490 @section Where can I get an Emacs that handles kanji, Chinese, or other Far-Eastern character sets?
4491 @cindex Kanji, handling with Emacs
4492 @cindex Chinese, handling with Emacs
4493 @cindex Japanese, handling with Emacs
4494 @cindex Korean, handling with Emacs
4496 Emacs 20 and later includes many of the features of MULE, the MULtilingual
4497 Enhancement to Emacs. @xref{Installing Emacs}, for information on where
4498 to find and download the latest version of Emacs.
4500 @node Right-to-left alphabets
4501 @section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
4502 @cindex Right-to-left alphabets
4503 @cindex Hebrew, handling with Emacs
4504 @cindex Semitic alphabets
4505 @cindex Arabic alphabets
4507 Emacs 20 and later supports Hebrew characters (ISO 8859-8), but does not
4508 yet support right-to-left character entry and display.
4510 @email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called
4511 @file{hebrew.el} that allows right-to-left editing of Hebrew. It
4512 reportedly works out of the box with Emacs 19, but requires patches for
4513 Emacs 18. Write to Joel if you want the patches or package.
4515 @c FIXME: Should we mention Ehud Karni's package?
4517 @file{hebrew.el} requires a Hebrew screen font, but no other hardware support.
4518 Joel has a screen font for PCs running MS-DOS or GNU/Linux.
4520 You might also try querying @code{archie} for files named with
4521 @file{hebrew}; several ftp sites in Israel may also have the necessary
4524 @node How to add fonts
4525 @section How do I add fonts for use with Emacs?
4526 @cindex add fonts for use with Emacs
4529 First, download and install the BDF font files and any auxiliary
4530 packages they need. The GNU Intlfonts distribution can be found on
4531 @uref{http://directory.fsf.org/localization/intlfonts.html, the GNU
4532 Software Directory Web site}.
4534 Next, if you are on X Window system, issue the following two commands
4535 from the shell's prompt:
4538 xset +fp /usr/local/share/emacs/fonts
4543 (Modify the first command if you installed the fonts in a directory
4544 that is not @file{/usr/local/share/emacs/fonts}.) You also need to
4545 arrange for these two commands to run whenever you log in, e.g., by
4546 adding them to your window-system startup file, such as
4547 @file{~/.xsessionrc} or @file{~/.gnomerc}.
4549 Now, add the following line to your @file{~/.emacs} init file:
4552 (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
4556 (Again, modify the file name if you installed the fonts elsewhere.)
4558 Finally, if you wish to use the installed fonts with @code{ps-print},
4559 add the following line to your @file{~/.emacs}:
4562 (setq ps-multibyte-buffer 'bdf-font-except-latin)
4565 A few additional steps are necessary for MS-Windows; they are listed
4568 First, make sure @emph{all} the directories with BDF font files are
4569 mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux
4570 systems, one normally runs @kbd{make install} to install the BDF fonts
4571 in the same directory. By contrast, Windows users typically don't run
4572 the Intlfonts installation command, but unpack the distribution in
4573 some directory, which leaves the BDF fonts in its subdirectories. For
4574 example, assume that you unpacked Intlfonts in @file{C:/Intlfonts};
4575 then you should set @code{bdf-directory-list} as follows:
4578 (setq bdf-directory-list
4579 '("C:/Intlfonts/Asian"
4580 "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X"
4581 "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic"
4582 "C:/Intlfonts/European" "C:/Intlfonts/European.BIG"
4583 "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X"
4584 "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X"
4585 "C:/Intlfonts/Misc"))
4588 @cindex @code{w32-bdf-filename-alist}
4589 @cindex @code{w32-find-bdf-fonts}
4590 Next, you need to set up the variable @code{w32-bdf-filename-alist} to
4591 an alist of the BDF fonts and their corresponding file names.
4592 Assuming you have set @code{bdf-directory-list} to name all the
4593 directories with the BDF font files, the following Lisp snippet will
4594 set up @code{w32-bdf-filename-alist}:
4597 (setq w32-bdf-filename-alist
4598 (w32-find-bdf-fonts bdf-directory-list))
4601 Now, create fontsets for the BDF fonts:
4604 (create-fontset-from-fontset-spec
4605 "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf,
4606 japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*,
4607 katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4608 latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
4609 japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*,
4610 thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1,
4611 lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1,
4612 tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1,
4613 ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode,
4614 tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0")
4617 Many of the international bdf fonts from Intlfonts are type 0, and
4618 therefore need to be added to font-encoding-alist:
4621 (setq font-encoding-alist
4622 (append '(("MuleTibetan-0" (tibetan . 0))
4623 ("GB2312" (chinese-gb2312 . 0))
4624 ("JISX0208" (japanese-jisx0208 . 0))
4625 ("JISX0212" (japanese-jisx0212 . 0))
4626 ("VISCII" (vietnamese-viscii-lower . 0))
4627 ("KSC5601" (korean-ksc5601 . 0))
4628 ("MuleArabic-0" (arabic-digit . 0))
4629 ("MuleArabic-1" (arabic-1-column . 0))
4630 ("MuleArabic-2" (arabic-2-column . 0)))
4631 font-encoding-alist))
4634 You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
4635 fontset, or you can select it by setting the default font in your
4639 (set-default-font "fontset-bdf")
4643 @c ------------------------------------------------------------
4645 @chapter Mail and news
4646 @cindex Mail and news
4649 * Changing the included text prefix::
4650 * Saving a copy of outgoing mail::
4651 * Expanding aliases when sending mail::
4652 * Sorting the messages in an Rmail folder::
4653 * Rmail writes to /usr/spool/mail::
4654 * Replying to the sender of a message::
4655 * MIME with Emacs mail packages::
4656 * Automatically starting a mail or news reader::
4657 * Reading news with Emacs::
4658 * Gnus does not work with NNTP::
4659 * Viewing articles with embedded underlining::
4660 * Saving a multi-part Gnus posting::
4661 * Starting Gnus faster::
4662 * Catching up in all newsgroups::
4663 * Killing based on nonstandard headers::
4664 * Catch-up is slow in Gnus::
4665 * Gnus hangs for a long time::
4666 * Learning more about Gnus::
4669 @node Changing the included text prefix
4670 @section How do I change the included text prefix in mail/news followups?
4671 @cindex Prefix in mail/news followups, changing
4672 @cindex Included text prefix, changing
4673 @cindex Setting the included text character
4674 @cindex Quoting in mail messages
4676 If you read mail with Rmail or news with Gnus, set the variable
4677 @code{mail-yank-prefix}. For VM, set @code{vm-included-text-prefix}.
4678 For mh-e, set @code{mh-ins-buf-prefix}.
4680 For fancier control of citations, use Supercite (part of Emacs).
4682 To prevent Emacs from including various headers of the replied-to
4683 message, set the value of @code{mail-yank-ignored-headers} to an
4686 @node Saving a copy of outgoing mail
4687 @section How do I save a copy of outgoing mail?
4688 @cindex Saving a copy of outgoing mail
4689 @cindex Copying outgoing mail to a file
4690 @cindex Filing outgoing mail
4691 @cindex Automatic filing of outgoing mail
4692 @cindex Mail, saving outgoing automatically
4694 You can either mail yourself a copy by including a @samp{BCC} header in the
4695 mail message, or store a copy of the message directly to a file by
4696 including an @samp{FCC} header.
4698 If you use standard mail, you can automatically create a @samp{BCC} to
4702 (setq mail-self-blind t)
4706 in your @file{.emacs} file. You can automatically include an @samp{FCC}
4707 field by putting something like the following in your @file{.emacs}
4711 (setq mail-archive-file-name (expand-file-name "~/outgoing"))
4714 The output file will be in Unix mail format, which can be read directly
4715 by VM or Rmail (since Emacs 23).
4717 If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
4720 It does not work to put @samp{set record filename} in the @file{.mailrc}
4723 @node Expanding aliases when sending mail
4724 @section Why doesn't Emacs expand my aliases when sending mail?
4725 @cindex Expanding aliases when sending mail
4726 @cindex Mail alias expansion
4727 @cindex Sending mail with aliases
4732 You must separate multiple addresses in the headers of the mail buffer
4733 with commas. This is because Emacs supports RFC822 standard addresses
4737 To: Willy Smith <wks@@xpnsv.lwyrs.com>
4740 However, you do not need to---and probably should not, unless your
4741 system's version of @file{/usr/ucb/mail} (a.k.a.@: @code{mailx})
4742 supports RFC822---separate addresses with commas in your
4743 @file{~/.mailrc} file.
4746 Emacs normally only reads the @file{.mailrc} file once per session,
4747 when you start to compose your first mail message. If you edit
4748 @file{.mailrc}, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to
4749 make Emacs reread @file{~/.mailrc}.
4752 If you like, you can expand mail aliases as abbrevs, as soon as you
4753 type them in. To enable this feature, execute the following:
4756 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
4759 Note that the aliases are expanded automatically only after you type
4760 @key{RET} or a punctuation character (e.g. @kbd{,}). You can force their
4761 expansion by moving point to the end of the alias and typing @kbd{C-x a e}
4762 (@kbd{M-x expand-abbrev}).
4765 @node Sorting the messages in an Rmail folder
4766 @section How can I sort the messages in my Rmail folder?
4767 @cindex Rmail, sorting messages in
4768 @cindex Folder, sorting messages in an Rmail
4769 @cindex Sorting messages in an Rmail folder
4771 In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
4772 and their key bindings.
4774 @node Rmail writes to /usr/spool/mail
4775 @section Why does Rmail need to write to @file{/usr/spool/mail}?
4776 @cindex Rmail and @file{/usr/spool/mail}
4777 @cindex @file{/usr/spool/mail} and Rmail
4779 This is the behavior of the @code{movemail} program which Rmail uses.
4780 This indicates that @code{movemail} is configured to use lock files.
4785 Certain systems require lock files to interlock access to mail files.
4786 On these systems, @code{movemail} must write lock files, or you risk losing
4787 mail. You simply must arrange to let @code{movemail} write them.
4789 Other systems use the @code{flock} system call to interlock access. On
4790 these systems, you should configure @code{movemail} to use @code{flock}.
4793 @node Replying to the sender of a message
4794 @section How can I force Rmail to reply to the sender of a message, but not the other recipients?
4795 @cindex Replying only to the sender of a message
4796 @cindex Sender, replying only to
4797 @cindex Rmail, replying to the sender of a message in
4799 @email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit
4800 @key{r} to reply in Rmail, by default it CCs all of the original
4801 recipients (everyone on the original @samp{To} and @samp{CC}
4802 lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
4803 it replies only to the sender. However, going through the whole
4804 @kbd{C-u} business every time you want to reply is a pain. This is the
4805 best fix I've been able to come up with:
4808 (defun rmail-reply-t ()
4809 "Reply only to the sender of the current message. (See rmail-reply.)"
4813 (add-hook 'rmail-mode-hook
4815 (define-key rmail-mode-map "r" 'rmail-reply-t)
4816 (define-key rmail-mode-map "R" 'rmail-reply)))
4819 @node MIME with Emacs mail packages
4820 @section How can I get my favorite Emacs mail package to support MIME?
4821 @cindex MIME and Emacs mail packages
4822 @cindex Mail packages and MIME
4823 @cindex FAQ for MIME and Emacs
4825 Version 6.x of VM supports MIME. @xref{VM}. Gnus supports MIME in mail
4826 and news messages as of version 5.8.1 (Pterodactyl). Rmail has limited
4827 support for single-part MIME messages beginning with Emacs 20.3.
4829 @node Automatically starting a mail or news reader
4830 @section How do I make Emacs automatically start my mail/news reader?
4831 @cindex Mail reader, starting automatically
4832 @cindex News reader, starting automatically
4833 @cindex Starting mail/news reader automatically
4835 To start Emacs in Gnus:
4848 A more convenient way to start with Gnus:
4851 alias gnus 'emacs -f gnus'
4855 It is probably unwise to automatically start your mail or news reader
4856 from your @file{.emacs} file. This would cause problems if you needed to run
4857 two copies of Emacs at the same time. Also, this would make it difficult for
4858 you to start Emacs quickly when you needed to.
4860 @node Reading news with Emacs
4861 @section How do I read news under Emacs?
4862 @cindex Reading news under Emacs
4863 @cindex Usenet reader in Emacs
4864 @cindex Gnus newsreader
4866 Use @kbd{M-x gnus}. It is documented in Info (@pxref{Learning how to do
4869 @node Gnus does not work with NNTP
4870 @section Why doesn't Gnus work via NNTP?
4871 @cindex Gnus and NNTP
4872 @cindex NNTP, Gnus fails to work with
4874 There is a bug in NNTP version 1.5.10, such that when multiple requests
4875 are sent to the NNTP server, the server only handles the first one
4876 before blocking waiting for more input which never comes. NNTP version
4877 1.5.11 claims to fix this.
4879 You can work around the bug inside Emacs like this:
4882 (setq nntp-maximum-request 1)
4885 You can find out what version of NNTP your news server is running by
4886 telnetting to the NNTP port (usually 119) on the news server machine
4887 (i.e., @kbd{telnet server-machine 119}). The server should give its
4888 version number in the welcome message. Type @kbd{quit} to get out.
4890 @xref{Spontaneous entry into isearch-mode}, for some additional ideas.
4892 @node Viewing articles with embedded underlining
4893 @section How do I view news articles with embedded underlining (e.g., ClariNews)?
4894 @cindex Underlining, embedded in news articles
4895 @cindex News articles with embedded underlining
4896 @cindex Embedded underlining in news articles
4898 Underlining appears like this:
4901 _^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg
4904 @email{abraham@@dina.kvl.dk, Per Abrahamsen} suggests using the following
4905 code, which uses the underline face to turn such text into true
4906 underlining, inconjunction with Gnus:
4909 (defun gnus-article-prepare-overstrike ()
4910 ;; Prepare article for overstrike commands.
4912 (set-buffer gnus-article-buffer)
4913 (let ((buffer-read-only nil))
4914 (goto-char (point-min))
4915 (while (search-forward "\b" nil t)
4916 (let ((next (following-char))
4917 (previous (char-after (- (point) 2))))
4918 (cond ((eq next previous)
4919 (delete-region (- (point) 2) (point))
4920 (put-text-property (point) (1+ (point))
4923 (delete-region (1- (point)) (1+ (point)))
4924 (put-text-property (1- (point)) (point)
4927 (delete-region (- (point) 2) (point))
4928 (put-text-property (point) (1+ (point))
4929 'face 'underline))))))))
4931 (add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike)
4934 Latest versions of Gnus do such a conversion automatically.
4936 If you prefer to do away with underlining altogether, you can
4937 destructively remove it with @kbd{M-x ununderline-region}; do this
4941 (add-hook 'gnus-article-prepare-hook
4942 (lambda () (ununderline-region (point-min) (point-max))))
4945 @node Saving a multi-part Gnus posting
4946 @section How do I save all the items of a multi-part posting in Gnus?
4947 @cindex Multi-part postings in Gnus, saving
4948 @cindex Saving multi-part postings in Gnus
4949 @cindex Gnus, saving multi-part postings in
4951 Use @code{gnus-uu}. Type @kbd{C-c C-v C-h} in the Gnus summary buffer
4952 to see a list of available commands.
4954 @node Starting Gnus faster
4955 @section How do I make Gnus start up faster?
4956 @cindex Faster, starting Gnus
4957 @cindex Starting Gnus faster
4958 @cindex Gnus, starting faster
4960 From the Gnus FAQ (@pxref{Learning more about Gnus}):
4963 @email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted
4964 the same query recently and I got an answer to it. I am going to
4965 repeat the answer. What you need is a newer version of gnus, version
4966 5.0.4+. I am using 5.0.12 and it works fine with me with the
4970 (setq gnus-check-new-newsgroups nil
4971 gnus-read-active-file 'some
4972 gnus-nov-is-evil nil
4973 gnus-select-method '(nntp gnus-nntp-server))
4977 @node Catching up in all newsgroups
4978 @section How do I catch up all newsgroups in Gnus?
4979 @cindex Catching up all newsgroups in Gnus
4980 @cindex Gnus, Catching up all newsgroups in
4982 In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
4984 Leave off the initial @kbd{M-<} if you only want to catch up from point
4985 to the end of the @file{*Newsgroup*} buffer.
4987 @node Killing based on nonstandard headers
4988 @section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers?
4989 @cindex Killing articles based on nonstandard headers
4990 @cindex Newsgroups header, killing articles based on
4991 @cindex Keywords header, killing articles based on
4992 @cindex Control header, killing articles based on
4994 Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and
4995 @samp{Control} headers are ``Unknown header'' fields.
4997 For the @samp{Newsgroups} header, there is an easy workaround: kill on the
4998 @samp{Xref} header instead, which will be present on any cross-posted article
4999 (as long as your site carries the cross-post group).
5001 If you really want to kill on one of these headers, you can do it like
5005 (gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)")
5008 @node Catch-up is slow in Gnus
5009 @section Why is catch up slow in Gnus?
5010 @cindex Slow catch up in Gnus
5011 @cindex Gnus is slow when catching up
5012 @cindex Crosspostings make Gnus catching up slow
5014 Because Gnus is marking crosspostings read. You can control this with
5015 the variable @code{gnus-use-cross-reference}.
5017 @node Gnus hangs for a long time
5018 @section Why does Gnus hang for a long time when posting?
5019 @cindex Hangs in Gnus
5020 @cindex Gnus hangs while posting
5021 @cindex Posting, Gnus hangs wile
5023 @email{tale@@uunet.uu.net, David Lawrence} explains:
5026 The problem is almost always interaction between NNTP and C News. NNTP
5027 POST asks C News's @code{inews} to not background itself but rather hang
5028 around and give its exit status so it knows whether the post was successful.
5029 (That wait will on some systems not return the exit status of the
5030 waited for job is a different sort of problem.) It ends up taking a
5031 long time because @code{inews} is calling @code{relaynews}, which often
5032 waits for another @code{relaynews} to free the lock on the news system
5033 so it can file the article.
5035 My preferred solution is to change @code{inews} to not call
5036 @code{relaynews}, but rather use @code{newsspool}. This loses some
5037 error-catching functionality, but is for the most part safe as
5038 @code{inews} will detect a lot of the errors on its own. The C News
5039 folks have sped up @code{inews}, too, so speed should look better to
5040 most folks as that update propagates around.
5043 @node Learning more about Gnus
5044 @section Where can I find out more about Gnus?
5045 @cindex FAQ for Gnus
5047 @cindex Learning more about Gnus
5049 For more information on Gnus, @pxref{Top,, the Gnus Manual, gnus, The
5050 Gnus Manual}, which includes @ref{Frequently Asked Questions,, the Gnus
5054 @unnumbered Concept Index
5060 arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f