1 \input texinfo @c -*- mode: texinfo; -*-
3 @setfilename ../info/efaq
4 @settitle GNU Emacs FAQ
9 @c This is used in many places
12 @c This file is maintained by Romain Francoise <rfrancoise@gnu.org>.
13 @c Feel free to install changes without prior permission (but I'd
14 @c appreciate a notice if you do).
17 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007
18 Free Software Foundation, Inc.@*
19 Copyright 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner@*
20 Copyright 1992,1993 Steven Byrnes@*
21 Copyright 1990,1991,1992 Joseph Brian Wells@*
24 This list of frequently asked questions about GNU Emacs with answers
25 (``FAQ'') may be translated into other languages, transformed into other
26 formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.
28 The same conditions apply to any derivative of the FAQ as apply to the FAQ
29 itself. Every copy of the FAQ must include this notice or an approved
30 translation, information on who is currently maintaining the FAQ and how to
31 contact them (including their e-mail address), and information on where the
32 latest version of the FAQ is archived (including FTP information).
34 The FAQ may be copied and redistributed under these conditions, except that
35 the FAQ may not be embedded in a larger literary work unless that work
36 itself allows free copying and redistribution.
38 [This version has been heavily edited since it was included in the Emacs
45 * Emacs FAQ: (efaq). Frequently Asked Questions about Emacs.
48 @c The @titlepage stuff only appears in the printed version
51 @center @titlefont{GNU Emacs FAQ}
53 @c The following two commands start the copyright page.
55 @vskip 0pt plus 1filll
59 @node Top, FAQ notation, (dir), (dir)
61 This is the GNU Emacs FAQ, last updated on @today{}.
63 This FAQ is maintained as a part of GNU Emacs. If you find any errors,
64 or have any suggestions, please use @kbd{M-x report-emacs-bug} to report
74 * Compiling and installing Emacs::
75 * Finding Emacs and related packages::
76 * Major packages and programs::
78 * Alternate character sets::
83 @c ------------------------------------------------------------
84 @node FAQ notation, General questions, Top, Top
88 This chapter describes notation used in the GNU Emacs FAQ, as well as in
89 the Emacs documentation. Consult this section if this is the first time
90 you are reading the FAQ, or if you are confused by notation or terms
97 * File-name conventions::
101 @node Basic keys, Extended commands, FAQ notation, FAQ notation
102 @section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
104 @cindex Control key, notation for
105 @cindex @key{Meta} key, notation for
106 @cindex Control-Meta characters, notation for
107 @cindex @kbd{C-h}, definition of
108 @cindex @kbd{C-M-h}, definition of
109 @cindex @key{DEL}, definition of
110 @cindex @key{ESC}, definition of
111 @cindex @key{LFD}, definition of
112 @cindex @key{RET}, definition of
113 @cindex @key{SPC}, definition of
114 @cindex @key{TAB}, definition of
115 @cindex Notation for keys
120 @kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
123 @kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
124 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
127 @kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
131 @kbd{C-M-x}: a synonym for the above
134 @key{LFD}: Linefeed or Newline; same as @kbd{C-j}
137 @key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
140 @key{DEL}: @key{Delete}, usually @strong{not} the same as
141 @key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
142 deleting invokes Emacs help)
145 @key{ESC}: Escape; same as @kbd{C-[}
148 @key{TAB}: Tab; same as @kbd{C-i}
155 Key sequences longer than one key (and some single-key sequences) are
156 written inside quotes or on lines by themselves, like this:
159 @kbd{M-x frobnicate-while-foo RET}
163 Any real spaces in such a key sequence should be ignored; only @key{SPC}
164 really means press the space key.
166 The @acronym{ASCII} code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
167 that would be sent by pressing just @key{x} minus 96 (or 64 for
168 upper-case @key{X}) and will be from 0 to 31. On Unix and GNU/Linux
169 terminals, the @acronym{ASCII} code sent by @kbd{M-x} is the sum of 128 and the
170 @acronym{ASCII} code that would be sent by pressing just @key{x}. Essentially,
171 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
173 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
176 @kbd{C-?} (aka @key{DEL}) is @acronym{ASCII} code 127. It is a misnomer to call
177 @kbd{C-?} a ``control'' key, since 127 has both bits 5 and 6 turned ON.
178 Also, on very few keyboards does @kbd{C-?} generate @acronym{ASCII} code 127.
180 @inforef{Text Characters, Text Characters, emacs}, and @inforef{Keys,
181 Keys, emacs}, for more information. (@xref{On-line manual}, for more
182 information about Info.)
184 @node Extended commands, On-line manual, Basic keys, FAQ notation
185 @section What does @file{M-x @var{command}} mean?
186 @cindex Extended commands
187 @cindex Commands, extended
188 @cindex M-x, meaning of
190 @kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
191 command, then type @key{RET}. (@xref{Basic keys}, if you're not sure
192 what @kbd{M-x} and @key{RET} mean.)
194 @kbd{M-x} (by default) invokes the command
195 @code{execute-extended-command}. This command allows you to run any
196 Emacs command if you can remember the command's name. If you can't
197 remember the command's name, you can type @key{TAB} and @key{SPC} for
198 completion, @key{?} for a list of possibilities, and @kbd{M-p} and
199 @kbd{M-n} (or up-arrow and down-arrow on terminals that have these
200 editing keys) to see previous commands entered. An Emacs @dfn{command}
201 is an @dfn{interactive} Emacs function.
204 Your system administrator may have bound other key sequences to invoke
205 @code{execute-extended-command}. A function key labeled @kbd{Do} is a
206 good candidate for this, on keyboards that have such a key.
208 If you need to run non-interactive Emacs functions, see @ref{Evaluating
211 @node On-line manual, File-name conventions, Extended commands, FAQ notation
212 @section How do I read topic XXX in the on-line manual?
213 @cindex On-line manual, reading topics in
214 @cindex Reading topics in the on-line manual
215 @cindex Finding topics in the on-line manual
216 @cindex Info, finding topics in
218 When we refer you to some @var{topic} in the on-line manual, you can
219 read this manual node inside Emacs (assuming nothing is broken) by
220 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
222 This invokes Info, the GNU hypertext documentation browser. If you don't
223 already know how to use Info, type @key{?} from within Info.
225 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
226 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
228 If these commands don't work as expected, your system administrator may
229 not have installed the Info files, or may have installed them
230 improperly. In this case you should complain.
232 @xref{Getting a printed manual}, if you would like a paper copy of the
235 @node File-name conventions, Common acronyms, On-line manual, FAQ notation
236 @section What are @file{etc/SERVICE}, @file{src/config.h}, and @file{lisp/default.el}?
237 @cindex File-name conventions
238 @cindex Conventions for file names
239 @cindex Directories and files that come with Emacs
241 These are files that come with Emacs. The Emacs distribution is divided
242 into subdirectories; the important ones are @file{etc}, @file{lisp}, and
245 If you use Emacs, but don't know where it is kept on your system, start
246 Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory
247 name displayed by this will be the full pathname of the installed
248 @file{etc} directory. (This full path is recorded in the Emacs variable
249 @code{data-directory}, and @kbd{C-h v} displays the value and the
250 documentation of a variable.)
252 The location of your Info directory (i.e., where on-line documentation
253 is stored) is kept in the variable @code{Info-default-directory-list}. Use
254 @kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
255 this variable, which will be a list of directory names. The last
256 directory in that list is probably where most Info files are stored. By
257 default, Info documentation is placed in @file{/usr/local/info}.
259 Some of these files are available individually via FTP or e-mail; see
260 @ref{Informational files for Emacs}. They all are available in the
261 source distribution. Many of the files in the @file{etc} directory are
262 also available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?}
263 (@kbd{M-x help-for-help}).
265 Your system administrator may have removed the @file{src} directory and
266 many files from the @file{etc} directory.
268 @node Common acronyms, , File-name conventions, FAQ notation
269 @section What are FSF, LPF, OSF, GNU, RMS, FTP, and GPL?
270 @cindex FSF, definition of
271 @cindex LPF, definition of
272 @cindex OSF, definition of
273 @cindex GNU, definition of
274 @cindex RMS, definition of
275 @cindex Stallman, Richard, acronym for
276 @cindex Richard Stallman, acronym for
277 @cindex FTP, definition of
278 @cindex GPL, definition of
279 @cindex Acronyms, definitions for
280 @cindex Common acronyms, definitions for
285 Free Software Foundation
288 League for Programming Freedom
291 Open Software Foundation
297 Richard Matthew Stallman
300 File Transfer Protocol
303 GNU General Public License
307 Avoid confusing the FSF, the LPF, and the OSF. The LPF opposes
308 look-and-feel copyrights and software patents. The FSF aims to make
309 high quality free software available for everyone. The OSF is a
310 consortium of computer vendors which develops commercial software for
313 The word ``free'' in the title of the Free Software Foundation refers to
314 ``freedom,'' not ``zero cost.'' Anyone can charge any price for
315 GPL-covered software that they want to. However, in practice, the
316 freedom enforced by the GPL leads to low prices, because you can always
317 get the software for less money from someone else, since everyone has
318 the right to resell or give away GPL-covered software.
320 @c ------------------------------------------------------------
321 @node General questions, Getting help, FAQ notation, Top
322 @chapter General questions
323 @cindex General questions
325 This chapter contains general questions having to do with Emacs, the
326 Free Software Foundation, and related organizations.
330 * Real meaning of copyleft::
331 * Guidelines for newsgroup postings::
332 * Newsgroup archives::
334 * Unsubscribing from Emacs lists::
335 * Contacting the FSF::
338 @node The LPF, Real meaning of copyleft, General questions, General questions
339 @section What is the LPF?
340 @cindex LPF, description of
341 @cindex League for Programming Freedom
342 @cindex Software patents, opposition to
343 @cindex Patents for software, opposition to
345 The LPF opposes the expanding danger of software patents and
346 look-and-feel copyrights. To get more information, feel free to contact
347 the LPF via e-mail or otherwise. You may also contact
348 @email{jbw@@cs.bu.edu, Joe Wells}; he will be happy to talk to you
351 You can find more information about the LPF in the file @file{etc/LPF}.
352 More papers describing the LPF's views are available on the Internet and
353 also from @uref{http://lpf.ai.mit.edu/, the LPF home page}.
355 @node Real meaning of copyleft, Guidelines for newsgroup postings, The LPF, General questions
356 @section What is the real legal meaning of the GNU copyleft?
357 @cindex Copyleft, real meaning of
358 @cindex GPL, real meaning of
359 @cindex General Public License, real meaning of
360 @cindex Discussion of the GPL
362 The real legal meaning of the GNU General Public License (copyleft) will
363 only be known if and when a judge rules on its validity and scope.
364 There has never been a copyright infringement case involving the GPL to
365 set any precedents. Please take any discussion regarding this issue to
366 the newsgroup @uref{news:gnu.misc.discuss}, which was created to hold the
367 extensive flame wars on the subject.
372 The legal meaning of the GNU copyleft is less important than the spirit,
373 which is that Emacs is a free software project and that work pertaining
374 to Emacs should also be free software. ``Free'' means that all users
375 have the freedom to study, share, change and improve Emacs. To make
376 sure everyone has this freedom, pass along source code when you
377 distribute any version of Emacs or a related program, and give the
378 recipients the same freedom that you enjoyed.
381 @node Guidelines for newsgroup postings, Newsgroup archives, Real meaning of copyleft, General questions
382 @section What are appropriate messages for @uref{news:gnu.emacs.help}, @uref{news:gnu.emacs.bug}, @uref{news:comp.emacs}, etc.?
383 @cindex Newsgroups, appropriate messages for
384 @cindex GNU newsgroups, appropriate messages for
385 @cindex Usenet groups, appropriate messages for
386 @cindex Mailing lists, appropriate messages for
387 @cindex Posting messages to newsgroups
389 @cindex GNU mailing lists
390 The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
391 mailing list. (@xref{Informational files for Emacs}, if you want a copy
392 of the file.) For those lists which are gatewayed with newsgroups, it
393 lists both the newsgroup name and the mailing list address.
395 The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
396 in general. This includes Emacs along with various other
397 implementations, such as XEmacs, JOVE, MicroEmacs, Freemacs, MG,
398 Unipress, CCA, and Epsilon.
400 Many people post Emacs questions to @uref{news:comp.emacs} because they
401 don't receive any of the @code{gnu.*} newsgroups. Arguments have been
402 made both for and against posting GNU-Emacs-specific material to
403 @uref{news:comp.emacs}. You have to decide for yourself.
405 Messages advocating ``non-free'' software are considered unacceptable on
406 any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
407 which was created to hold the extensive flame-wars on the subject.
408 ``Non-free'' software includes any software for which the end user can't
409 freely modify the source code and exchange enhancements. Be careful to
410 remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
411 posting a followup that recommends such software.
413 @uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
414 posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
416 @node Newsgroup archives, Reporting bugs, Guidelines for newsgroup postings, General questions
417 @section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
418 @cindex Archived postings from @code{gnu.emacs.help}
419 @cindex Usenet archives for GNU groups
420 @cindex Old Usenet postings for GNU groups
422 The FSF has maintained archives of all of the GNU mailing lists for many
423 years, although there may be some unintentional gaps in coverage. The
424 archive is not particularly well organized or easy to retrieve
425 individual postings from, but pretty much everything is there.
427 The archive is at @uref{ftp://lists.gnu.org/}.
429 The archive can be browsed over the web at
430 @uref{http://lists.gnu.org/archive/html/, the GNU mail archive}.
432 Web-based Usenet search services, such as
433 @uref{http://groups.google.com/groups/dir?sel=33592484, Google}, also
434 archive the @code{gnu.*} groups.
436 You can read the archives of the @code{gnu.*} groups and post new
437 messages at @uref{http://gmane.org/, Gmane}.
439 @node Reporting bugs, Unsubscribing from Emacs lists, Newsgroup archives, General questions
440 @section Where should I report bugs and other problems with Emacs?
441 @cindex Bug reporting
442 @cindex Good bug reports
443 @cindex How to submit a bug report
444 @cindex Reporting bugs
446 The correct way to report Emacs bugs is to use the command
447 @kbd{M-x report-emacs-bug}. It sets up a mail buffer with the
448 essential information and the correct e-mail address which is
449 @email{bug-gnu-emacs@@gnu.org} for the released versions of Emacs.
450 Anything sent to @email{bug-gnu-emacs@@gnu.org} also appears in the
451 newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
452 news to submit the bug report. This ensures a reliable return address
453 so you can be contacted for further details.
455 Be sure to read the ``Bugs'' section of the Emacs manual before reporting
456 a bug! The manual describes in detail how to submit a useful bug
457 report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}).
458 (@xref{On-line manual}, if you don't know how to read the manual.)
463 Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
464 effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
465 it takes the time of an unnecessarily large group of people, most of
466 whom are just users and have no idea how to fix these problem.
467 @email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
468 who are more likely to know what to do and have expressed a wish to
469 receive more messages about Emacs than the others.
472 RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
475 If you have reported a bug and you don't hear about a possible fix,
476 then after a suitable delay (such as a week) it is okay to post on
477 @code{gnu.emacs.help} asking if anyone can help you.
480 If you are unsure whether you have found a bug, consider the following
481 non-exhaustive list, courtesy of RMS:
484 If Emacs crashes, that is a bug. If Emacs gets compilation errors
485 while building, that is a bug. If Emacs crashes while building, that
486 is a bug. If Lisp code does not do what the documentation says it
490 @node Unsubscribing from Emacs lists, Contacting the FSF, Reporting bugs, General questions
491 @section How do I unsubscribe from this mailing list?
492 @cindex Unsubscribing from GNU mailing lists
493 @cindex Removing yourself from GNU mailing lists
495 If you are receiving a GNU mailing list named @var{list}, you might be
496 able to unsubscribe from it by sending a request to the address
497 @email{@var{list}-request@@gnu.org}. However, this will not work if you are
498 not listed on the main mailing list, but instead receive the mail from a
499 distribution point. In that case, you will have to track down at which
500 distribution point you are listed. Inspecting the @samp{Received} headers
501 on the mail messages may help, along with liberal use of the @samp{EXPN} or
502 @samp{VRFY} sendmail commands through @samp{telnet @var{site-address}
503 smtp}. Ask your postmaster for help, if you cannot figure out these
506 @node Contacting the FSF, , Unsubscribing from Emacs lists, General questions
507 @section What is the current address of the FSF?
508 @cindex Snail mail address of the FSF
509 @cindex Postal address of the FSF
510 @cindex Contracting the FSF
511 @cindex Free Software Foundation, contacting
525 @uref{http://www.gnu.org/}
528 Free Software Foundation@*
529 51 Franklin Street, Fifth Floor@*
530 Boston, MA 02110-1301@*
535 @cindex Ordering GNU software
536 For details on how to order items directly from the FSF, see the
537 @uref{http://www.gnu.org/order/order.html, GNU Web site}.
539 @c ------------------------------------------------------------
540 @node Getting help, Status of Emacs, General questions, Top
541 @chapter Getting help
544 This chapter tells you how to get help with Emacs
548 * Learning how to do something::
549 * Getting a printed manual::
550 * Emacs Lisp documentation::
551 * Installing Texinfo documentation::
552 * Printing a Texinfo file::
553 * Viewing Info files outside of Emacs::
554 * Informational files for Emacs::
555 * Help installing Emacs::
556 * Obtaining the FAQ::
559 @node Basic editing, Learning how to do something, Getting help, Getting help
560 @section I'm just starting Emacs; how do I do basic editing?
561 @cindex Basic editing with Emacs
562 @cindex Beginning editing
563 @cindex Tutorial, invoking the
564 @cindex Self-paced tutorial, invoking the
565 @cindex Help system, entering the
567 Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing
568 @kbd{C-h} enters the help system. Starting with Emacs 22, the tutorial
569 is available in many foreign languages such as French, German, Japanese,
570 Russian, etc. Use @kbd{M-x help-with-tutorial-spec-language @key{RET}}
571 to choose your language and start the tutorial.
573 Your system administrator may have changed @kbd{C-h} to act like
574 @key{DEL} to deal with local keyboards. You can use @kbd{M-x
575 help-for-help} instead to invoke help. To discover what key (if any)
576 invokes help on your system, type @kbd{M-x where-is @key{RET}
577 help-for-help @key{RET}}. This will print a comma-separated list of key
578 sequences in the echo area. Ignore the last character in each key
579 sequence listed. Each of the resulting key sequences invokes help.
581 Emacs help works best if it is invoked by a single key whose value
582 should be stored in the variable @code{help-char}.
584 @node Learning how to do something, Getting a printed manual, Basic editing, Getting help
585 @section How do I find out how to do something in Emacs?
586 @cindex Help for Emacs
587 @cindex Learning to do something in Emacs
588 @cindex Reference card for Emacs
589 @cindex Overview of help systems
591 There are several methods for finding out how to do things in Emacs.
595 @cindex Reading the Emacs manual
597 The complete text of the Emacs manual is available on-line via the Info
598 hypertext reader. Type @kbd{C-h r} to display the manual in Info mode.
599 Typing @key{h} immediately after entering Info will provide a short
600 tutorial on how to use it.
602 @cindex Lookup a subject in a manual
603 @cindex Index search in a manual
605 To quickly locate the section of the manual which discusses a certain
606 issue, or describes a command or a variable, type @kbd{C-h i m emacs
607 @key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
608 topic, the command, or the variable which you are looking for. If this
609 does not land you on the right place in the manual, press @kbd{,}
610 (comma) repeatedly until you find what you need. (The @kbd{i} and
611 @kbd{,} keys invoke the index-searching functions, which look for the
612 @var{topic} you type in all the indices of the Emacs manual.)
616 You can list all of the commands whose names contain a certain word
617 (actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
620 @cindex Command description in the manual
622 The command @kbd{C-h F} (@code{Info-goto-emacs-command-node}) prompts
623 for the name of a command, and then attempts to find the section in the
624 Emacs manual where that command is described.
626 @cindex Finding commands and variables
628 You can list all of the functions and variables whose names contain a
629 certain word using @kbd{M-x apropos}.
632 You can list all of the functions and variables whose documentation
633 matches a regular expression or a string, using @kbd{M-x
634 apropos-documentation}.
637 You can order a hardcopy of the manual from the FSF. @xref{Getting a
640 @cindex Reference cards, in other languages
642 You can get a printed reference card listing commands and keys to
643 invoke them. You can order one from the FSF for $1 (or 10 for $5),
644 or you can print your own from the @file{etc/refcard.tex} or
645 @file{etc/refcard.ps} files in the Emacs distribution. Beginning with
646 version 21.1, the Emacs distribution comes with translations of the
647 reference card into several languages; look for files named
648 @file{etc/@var{lang}-refcard.*}, where @var{lang} is a two-letter code
649 of the language. For example, the German version of the reference card
650 is in the files @file{etc/de-refcard.tex} and @file{etc/de-refcard.ps}.
653 There are many other commands in Emacs for getting help and
654 information. To get a list of these commands, type @samp{?} after
659 @node Getting a printed manual, Emacs Lisp documentation, Learning how to do something, Getting help
660 @section How do I get a printed copy of the Emacs manual?
661 @cindex Printed Emacs manual, obtaining
662 @cindex Manual, obtaining a printed or HTML copy of
663 @cindex Emacs manual, obtaining a printed or HTML copy of
665 You can order a printed copy of the Emacs manual from the FSF. For
666 details see the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
668 @c The number 620 below is version-dependent!
669 The full Texinfo source for the manual also comes in the @file{man}
670 directory of the Emacs distribution, if you're daring enough to try to
671 print out this 620-page manual yourself (@pxref{Printing a Texinfo
674 If you absolutely have to print your own copy, and you don't have @TeX{},
675 you can get a PostScript version from
677 @uref{http://www.gnu.org/software/emacs/manual/emacs.ps.gz}
679 @cindex HTML version of Emacs manual, obtaining
680 An HTML version of the manual is at
682 @uref{http://www.gnu.org/software/emacs/manual/emacs.html}
684 The manual is available in other formats at
686 @uref{http://www.gnu.org/software/emacs/manual/}
688 @xref{Learning how to do something}, for how to view the manual on-line.
690 @node Emacs Lisp documentation, Installing Texinfo documentation, Getting a printed manual, Getting help
691 @section Where can I get documentation on Emacs Lisp?
692 @cindex Documentation on Emacs Lisp
693 @cindex Function documentation
694 @cindex Variable documentation
695 @cindex Emacs Lisp Reference Manual
696 @cindex Reference manual for Emacs Lisp
698 Within Emacs, you can type @kbd{C-h f} to get the documentation for a
699 function, @kbd{C-h v} for a variable.
701 For more information, the Emacs Lisp Reference Manual is available
702 on-line, in Info format. @xref{Top, Emacs Lisp,, elisp, The
703 Emacs Lisp Reference Manual}.
705 You can also order a hardcopy of the manual, details on ordering it from
706 FSF are on the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
708 An HTML version of the Emacs Lisp Reference Manual is available at
710 @uref{http://www.gnu.org/software/emacs/elisp-manual/elisp.html}
712 @node Installing Texinfo documentation, Printing a Texinfo file, Emacs Lisp documentation, Getting help
713 @section How do I install a piece of Texinfo documentation?
714 @cindex Texinfo documentation, installing
715 @cindex Installing Texinfo documentation
716 @cindex New Texinfo files, installing
717 @cindex Documentation, installing new Texinfo files
718 @cindex Info files, how to install
720 First, you must turn the Texinfo files into Info files. You may do this
721 using the stand-alone @file{makeinfo} program, available as part of the latest
724 @uref{ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-4.8.tar.gz}
726 and all mirrors of @samp{ftp.gnu.org} (for a list, @pxref{Current GNU
729 For information about the Texinfo format, read the Texinfo manual which
730 comes with the Texinfo package. This manual also comes installed in
731 Info format, so you can read it on-line; type @kbd{C-h i m texinfo
734 Alternatively, you could use the Emacs command @kbd{M-x
735 texinfo-format-buffer}, after visiting the Texinfo source file of the
736 manual you want to convert.
738 Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
739 resulting Info files in Emacs's Info tree. To install Info files,
744 Move the files to the @file{info} directory in the installed Emacs
745 distribution. @xref{File-name conventions}, if you don't know where that
749 Run the @code{install-info} command, which is part of the Texinfo
750 distribution, to update the main Info directory menu, like this:
753 install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
757 where @var{dir-path} is the full path to the directory where you copied
758 the produced Info file(s), and @var{file} is the name of the Info file
759 you produced and want to install.
761 If you don't have the @code{install-info} command installed, you can
762 edit the file @file{info/dir} in the installed Emacs distribution, and
763 add a line for the top level node in the Info package that you are
764 installing. Follow the examples already in this file. The format is:
767 * Topic: (relative-pathname). Short description of topic.
772 If you want to install Info files and you don't have the necessary
773 privileges, you have several options:
777 Info files don't actually need to be installed before being used.
778 You can use a prefix argument for the @code{info} command and specify
779 the name of the Info file in the minibuffer. This goes to the node
780 named @samp{Top} in that file. For example, to view a Info file named
781 @file{@var{info-file}} in your home directory, you can type this:
784 @kbd{C-u C-h i ~/@var{info-file} @key{RET}}
787 Alternatively, you can feed a file name to the @code{Info-goto-node}
788 command (invoked by pressing @key{g} in Info mode) by typing the name
789 of the file in parentheses, like this:
792 @kbd{C-h i g (~/@var{info-file}) @key{RET}}
796 You can create your own Info directory. You can tell Emacs where that
797 Info directory is by adding its pathname to the value of the variable
798 @code{Info-default-directory-list}. For example, to use a private Info
799 directory which is a subdirectory of your home directory named @file{Info},
800 you could put this in your @file{.emacs} file:
803 (setq Info-default-directory-list
804 (cons "~/Info" Info-default-directory-list))
807 You will need a top-level Info file named @file{dir} in this directory
808 which has everything the system @file{dir} file has in it, except it should
809 list only entries for Info files in that directory. You might not need
810 it if all files in this directory were referenced by other @file{dir}
811 files. The node lists from all @file{dir} files in
812 @code{Info-default-directory-list} are merged by the Info system.
816 @node Printing a Texinfo file, Viewing Info files outside of Emacs, Installing Texinfo documentation, Getting help
817 @section How do I print a Texinfo file?
818 @cindex Printing a Texinfo file
819 @cindex Texinfo file, printing
820 @cindex Printing documentation
822 You can't get nicely printed output from Info files; you must still have
823 the original Texinfo source file for the manual you want to print.
825 Assuming you have @TeX{} installed on your system, follow these steps:
830 Make sure the first line of the Texinfo file looks like this:
836 You may need to change @samp{texinfo} to the full pathname of the
837 @file{texinfo.tex} file, which comes with Emacs as
838 @file{man/texinfo.tex} (or copy or link it into the current directory).
841 Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
842 the name of the Texinfo source file for which you want to produce a
845 The @samp{texi2dvi} script is part of the GNU Texinfo distribution
846 (@pxref{Installing Texinfo documentation}).
849 Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
850 printing DVI files at your site. For example, if you have a PostScript
851 printer, run the @code{dvips} program to print the DVI file on that
856 To get more general instructions, retrieve the latest Texinfo package
857 (@pxref{Installing Texinfo documentation}).
859 @node Viewing Info files outside of Emacs, Informational files for Emacs, Printing a Texinfo file, Getting help
860 @section Can I view Info files without using Emacs?
861 @cindex Viewing Info files
862 @cindex Info file viewers
863 @cindex Alternative Info file viewers
865 Yes. Here are some alternative programs:
870 @code{info}, a stand-alone version of the Info program, comes as part of
871 the Texinfo package. @xref{Installing Texinfo documentation}, for
875 Xinfo, a stand-alone version of the Info program that runs under X
876 Window system. You can get it at
877 @uref{ftp://ftp.gnu.org/pub/gnu/xinfo/xinfo-1.01.01.tar.gz} and all
878 mirrors of @samp{ftp.gnu.org} (see @ref{Current GNU distributions}, for a
882 Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
883 You can get Tkinfo at
884 @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
888 @node Informational files for Emacs, Help installing Emacs, Viewing Info files outside of Emacs, Getting help
889 @section What informational files are available for Emacs?
890 @cindex Informational files included with Emacs
891 @cindex Files included with Emacs
892 @cindex @file{COPYING}, description of file
893 @cindex @file{DISTRIB}, description of file
894 @cindex @file{FTP}, description of file
895 @cindex @file{GNU}, description of file
896 @cindex @file{INTERVIEW}, description of file
897 @cindex @file{LPF}, description of file
898 @cindex @file{MACHINES}, description of file
899 @cindex @file{MAILINGLISTS}, description of file
900 @cindex @file{NEWS}, description of file
901 @cindex @file{SERVICE}, description of file
902 @cindex @file{SUN-SUPPORT}, description of file
904 This isn't a frequently asked question, but it should be! A variety of
905 informational files about Emacs and relevant aspects of the GNU project
906 are available for you to read.
908 The following files are available in the @file{etc} directory of the
909 Emacs distribution (see @ref{File-name conventions}, if you're not sure
915 GNU General Public License
918 Emacs Availability Information, including the popular Free Software
919 Foundation Order Form
922 How to get GNU Software by Internet FTP or by UUCP
928 Richard Stallman discusses his public-domain UNIX-compatible software
929 system with BYTE editors
932 Why you should join the League for Programming Freedom
935 Status of Emacs on Various Machines and Systems
938 GNU Project Electronic Mailing Lists
941 Emacs news, a history of recent user-visible changes
944 GNU Service Directory
947 including ``Using Emacstool with GNU Emacs''
951 More GNU information, including back issues of the @cite{GNU's
954 @uref{http://www.gnu.org/bulletins/bulletins.html} and
956 @uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
958 @node Help installing Emacs, Obtaining the FAQ, Informational files for Emacs, Getting help
959 @section Where can I get help in installing Emacs?
960 @cindex Installation help
961 @cindex Help installing Emacs
963 @xref{Installing Emacs}, for some basic installation hints, and see
964 @ref{Problems building Emacs}, or @ref{Linking with -lX11 fails}, if you
965 have problems with the installation.
967 The file @file{etc/SERVICE} (see @ref{File-name conventions}, if you're
968 not sure where that is) lists companies and individuals willing to sell
969 you help in installing or using Emacs. An up-to-date version this file
970 is available on @samp{ftp.gnu.org} (@pxref{Informational files for
973 @node Obtaining the FAQ, , Help installing Emacs, Getting help
974 @section Where can I get the latest version of this FAQ?
975 @cindex FAQ, obtaining the
976 @cindex Latest FAQ version, obtaining the
977 @cindex Retrieving the latest FAQ version
978 @cindex E-mail, retrieving the FAQ via
979 @cindex Web, reading the FAQ on the
981 The Emacs FAQ is available in several ways:
986 Inside of Emacs itself. You can get it from selecting the @samp{Emacs
987 FAQ} option from the @samp{Help} menu of the Emacs menu bar at the top
988 of any Emacs frame, or by typing @kbd{C-h C-f} (@kbd{M-x view-emacs-FAQ}).
991 Via USENET. If you can read news, the FAQ should be available in your
992 news spool, in both the @uref{news:gnu.emacs.help} and
993 @uref{news:comp.emacs} newsgroups. Every news reader should allow you
994 to read any news article that is still in the news spool, even if you
995 have read the article before. You may need to read the instructions for
996 your news reader to discover how to do this. In @file{rn}, this command
997 will do this for you at the article selection level:
1000 ?GNU Emacs Frequently Asked Questions?rc:m
1003 In Gnus, you should type @kbd{C-u C-x C-s} from the @file{*Summary*}
1004 buffer or @kbd{C-u @key{SPC}} from the @file{*Newsgroup*} buffer to view
1005 all articles in a newsgroup.
1007 If the FAQ articles have expired and have been deleted from your news
1008 spool, it might (or might not) do some good to complain to your news
1009 administrator, because the most recent FAQ should not expire for a
1013 In the Emacs distribution. Since Emacs 18.56, the FAQ at the time
1014 of release has been part of the Emacs distribution as either
1015 @file{etc/FAQ} or @file{man/faq.texi} (@pxref{File-name conventions}).
1018 Via anonymous ftp and e-mail from @file{rtfm.mit.edu} (and its mirror in
1019 Europe), the main repository for FAQs and other items posted to
1020 news.answers. The Emacs FAQs are available at
1022 @uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} and
1024 @uref{ftp://ftp.uni-paderborn.de/pub/doc/FAQ/comp/emacs/}
1026 If you do not have access to anonymous FTP, you can access the archives
1027 using the @file{rtfm.mit.edu} mail server. The Emacs FAQ can be
1028 retrieved by sending mail to @email{mail-server@@rtfm.mit.edu} with a
1029 blank subject and containing
1032 send usenet/news.answers/GNU-Emacs-FAQ/diffs
1033 send usenet/news.answers/GNU-Emacs-FAQ/part1
1034 send usenet/news.answers/GNU-Emacs-FAQ/part2
1035 send usenet/news.answers/GNU-Emacs-FAQ/part3
1036 send usenet/news.answers/GNU-Emacs-FAQ/part4
1037 send usenet/news.answers/GNU-Emacs-FAQ/part5
1040 For more information, send email to @email{mail-server@@rtfm.mit.edu}
1041 with @samp{help} and @samp{index} in the body on separate lines.
1044 @c ------------------------------------------------------------
1045 @node Status of Emacs, Common requests, Getting help, Top
1046 @chapter Status of Emacs
1047 @cindex Status of Emacs
1049 This chapter gives you basic information about Emacs, including its
1050 latest version status.
1053 * Origin of the term Emacs::
1054 * Latest version of Emacs::
1060 @node Origin of the term Emacs, Latest version of Emacs, Status of Emacs, Status of Emacs
1061 @section Where does the name ``Emacs'' come from?
1062 @cindex Origin of the term ``Emacs''
1063 @cindex Emacs name origin
1065 @cindex Original version of Emacs
1067 Emacs originally was an acronym for Editor MACroS. RMS says he ``picked
1068 the name Emacs because @key{E} was not in use as an abbreviation on ITS at
1069 the time.'' The first Emacs was a set of macros written in 1976 at MIT
1070 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
1071 Editor and COrrector) under ITS on a PDP-10. RMS had already extended
1072 TECO with a ``real-time'' full-screen mode with reprogrammable keys.
1073 Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project
1074 to unify the many divergent TECO command sets and key bindings at MIT,
1075 and completed by RMS.
1077 Many people have said that TECO code looks a lot like line noise; you
1078 can read more at @uref{news:alt.lang.teco}. Someone has written a TECO
1079 implementation in Emacs Lisp (to find it, see @ref{Packages that do not
1080 come with Emacs}); it would be an interesting project to run the
1081 original TECO Emacs inside of Emacs.
1084 For some not-so-serious alternative reasons for Emacs to have that
1085 name, check out the file @file{etc/JOKES} (@pxref{File-name
1088 @node Latest version of Emacs, New in Emacs 20, Origin of the term Emacs, Status of Emacs
1089 @section What is the latest version of Emacs?
1090 @cindex Version, latest
1091 @cindex Latest version of Emacs
1093 Emacs @value{VER} is the current version as of this writing.
1095 @node New in Emacs 20, New in Emacs 21, Latest version of Emacs, Status of Emacs
1096 @section What is different about Emacs 20?
1097 @cindex Differences between Emacs 19 and Emacs 20
1098 @cindex Emacs 20, new features in
1100 To find out what has changed in recent versions, type @kbd{C-h C-n}
1101 (@kbd{M-x view-emacs-news}). The oldest changes are at the bottom of
1102 the file, so you might want to read it starting there, rather than at
1105 The differences between Emacs versions 18 and 19 was rather dramatic;
1106 the introduction of frames, faces, and colors on windowing systems was
1107 obvious to even the most casual user.
1109 There are differences between Emacs versions 19 and 20 as well, but many
1110 are more subtle or harder to find. Among the changes are the inclusion
1111 of MULE code for languages that use non-Latin characters and for mixing
1112 several languages in the same document; the ``Customize'' facility for
1113 modifying variables without having to use Lisp; and automatic conversion
1114 of files from Macintosh, Microsoft, and Unix platforms.
1116 A number of older Lisp packages, such as Gnus, Supercite and the
1117 calendar/diary, have been updated and enhanced to work with Emacs 20,
1118 and are now included with the standard distribution.
1121 @node New in Emacs 21, New in Emacs 22, New in Emacs 20, Status of Emacs
1122 @section What is different about Emacs 21?
1123 @cindex Differences between Emacs 20 and Emacs 21
1124 @cindex Emacs 21, new features in
1125 @cindex Recently introduced features
1127 @cindex Variable-size fonts
1128 @cindex Toolbar support
1129 Emacs 21 features a thorough rewrite of the display engine. The new
1130 display engine supports variable-size fonts, images, and can play sounds
1131 on platforms which support that. As a result, the visual appearance of
1132 Emacs, when it runs on a windowed display, is much more reminiscent of
1133 modern GUI programs, and includes 3D widgets (used for the mode line and
1134 the scroll bars), a configurable and extensible toolbar, tooltips
1135 (a.k.a.@: balloon help), and other niceties.
1137 @cindex Colors on text-only terminals
1139 In addition, Emacs 21 supports faces on text-only terminals. This means
1140 that you can now have colors when you run Emacs on a GNU/Linux console
1141 and on @code{xterm} with @kbd{emacs -nw}.
1143 @node New in Emacs 22, , New in Emacs 21, Status of Emacs
1144 @section What is different about Emacs 22?
1145 @cindex Differences between Emacs 21 and Emacs 22
1146 @cindex Emacs 22, new features in
1147 @cindex Recently introduced features
1149 @cindex Default features
1150 Font Lock mode, auto-compression mode, and file name shadow mode are now
1151 enabled by default. On graphics displays it is now possible to follow
1152 links with @kbd{mouse-1}, and the modeline of the selected window is now
1153 highlighted. Window fringes are now customizable. The minibuffer
1154 prompt is now displayed in a distinct face.
1156 Emacs now reads abbrev definitions automatically at startup. The
1157 maximum size of buffers has been doubled and is now 256M on 32-bit
1158 machines. Grep mode is now separate from Compilation mode and has many
1159 new specific options and commands.
1161 The original Emacs macro system has been replaced by the new Kmacro
1162 package, which provides many new commands and features and a simple
1163 interface that uses the function keys F3 and F4. Macros are now stored
1164 in a macro ring, and can be debugged and edited interactively.
1166 The GUD (Grand Unified Debugger) package can now be used with a full
1167 graphical user interface to the debugger which provides many features
1168 found in traditional development environments, making it easy to
1169 manipulate breakpoints, add watch points, display the call stack, etc.
1170 Breakpoints are now displayed in the source buffer.
1172 @cindex GTK+ Toolkit
1173 @cindex Drag-and-drop
1175 Emacs can now be built with GTK+ widgets, and supports drag-and-drop
1176 operation on X. Mouse wheel support is now enabled by default.
1179 Many new modes and packages have been included in Emacs, such as Calc,
1180 Tramp and URL, as well as IDO, CUA, rcirc, ERC, conf-mode, python-mode,
1181 table, tumme, SES, ruler, Flymake, Org, PGG, wdired, t-mouse, longlines,
1182 dns-mode, savehist, Password, Printing, Reveal, etc.
1184 @cindex Multilingual Environment
1185 Leim is now part of Emacs. Unicode support has been much improved, and
1186 the following input methods have been added: belarusian, bulgarian-bds,
1187 bulgarian-phonetic, chinese-sisheng, croatian, dutch, georgian,
1188 latin-alt-postfix, latin-postfix, latin-prefix, latvian-keyboard,
1189 lithuanian-numeric, lithuanian-keyboard, malayalam-inscript, rfc1345,
1190 russian-computer, sgml, slovenian, tamil-inscript ucs,
1191 ukrainian-computer, vietnamese-telex, and welsh.
1193 The following language environment have also been added: Belarusian,
1194 Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, Latin-6,
1195 Latin-7, Latvian, Lithuanian, Malayalam, Russian, Russian, Slovenian,
1196 Swedish, Tajik, Tamil, UTF-8, Ukrainian, Ukrainian, Welsh, and
1199 @cindex Supported systems
1200 Emacs 22 features support for GNU/Linux systems on S390 and x86-64
1201 machines, as well as support for the Mac OS X and Cygwin operating
1204 @cindex Documentation
1205 @cindex Emacs Lisp Manual
1206 In addition, Emacs 22 now includes the Emacs Lisp Reference Manual
1207 (@pxref{Emacs Lisp documentation}) and the Emacs Lisp Intro.
1209 Many other changes have been made in Emacs 22, use @kbd{C-h n} to get a
1212 @c ------------------------------------------------------------
1213 @node Common requests, Bugs and problems, Status of Emacs, Top
1214 @chapter Common requests
1215 @cindex Common requests
1218 * Setting up a customization file::
1221 * Debugging a customization file::
1222 * Displaying the current line or column::
1223 * Displaying the current file name in the titlebar::
1224 * Turning on abbrevs by default::
1225 * Associating modes with files::
1226 * Highlighting a region::
1227 * Replacing highlighted text::
1228 * Controlling case sensitivity::
1229 * Working with unprintable characters::
1230 * Searching for/replacing newlines::
1231 * Yanking text in isearch::
1232 * Wrapping words automatically::
1233 * Turning on auto-fill by default::
1235 * Checking TeX and *roff documents::
1236 * Changing load-path::
1237 * Using an already running Emacs process::
1238 * Compiler error messages::
1239 * Indenting switch statements::
1240 * Customizing C and C++ indentation::
1241 * Horizontal scrolling::
1243 * Turning off beeping::
1244 * Turning the volume down::
1245 * Automatic indentation::
1246 * Matching parentheses::
1247 * Hiding #ifdef lines::
1248 * Repeating commands::
1249 * Valid X resources::
1250 * Evaluating Emacs Lisp code::
1251 * Changing the length of a Tab::
1252 * Inserting text at the beginning of each line::
1253 * Underlining paragraphs::
1254 * Forcing the cursor to remain in the same column::
1255 * Forcing Emacs to iconify itself::
1256 * Using regular expressions::
1257 * Replacing text across multiple files::
1258 * Documentation for etags::
1259 * Disabling backups::
1260 * Disabling auto-save-mode::
1261 * Going to a line by number::
1262 * Modifying pull-down menus::
1263 * Deleting menus and menu options::
1264 * Turning on syntax highlighting::
1265 * Scrolling only one line::
1266 * Editing MS-DOS files::
1267 * Filling paragraphs with a single space::
1268 * Escape sequences in shell output::
1271 @node Setting up a customization file, Using Customize, Common requests, Common requests
1272 @section How do I set up a @file{.emacs} file properly?
1273 @cindex @file{.emacs} file, setting up
1274 @cindex @file{.emacs} file, locating
1275 @cindex Init file, setting up
1276 @cindex Customization file, setting up
1278 @inforef{Init File, Init File, emacs}.
1280 In general, new Emacs users should not have @file{.emacs} files, because
1281 it causes confusing non-standard behavior. Then they send questions to
1282 @email{help-gnu-emacs@@gnu.org} asking why Emacs isn't behaving as
1285 Beginning with version 20.1, Emacs includes the new Customize facility
1286 (@pxref{Using Customize}). This allows users who are unfamiliar with
1287 Emacs Lisp to modify their @file{.emacs} files in a relatively
1288 straightforward way, using menus rather than Lisp code. Most packages
1289 support Customize as of this writing.
1291 While Customize might indeed make it easier to configure Emacs,
1292 consider taking a bit of time to learn Emacs Lisp and modifying your
1293 @file{.emacs} directly. Simple configuration options are described
1294 rather completely in @inforef{Init File, Init File, emacs}, for users
1295 interested in performing frequently requested, basic tasks.
1297 Sometimes users are unsure as to where their @file{.emacs} file should
1298 be found. Visiting the file as @file{~/.emacs} from Emacs will find
1301 @node Using Customize, Colors on a TTY, Setting up a customization file, Common requests
1302 @section How do I start using Customize?
1303 @cindex Customize groups
1304 @cindex Customizing variables
1305 @cindex Customizing faces
1307 The main Customize entry point is @kbd{M-x customize @key{RET}}. This
1308 command takes you to a buffer listing all the available Customize
1309 groups. From there, you can access all customizable options and faces,
1310 change their values, and save your changes to your init file.
1311 @inforef{Easy Customization, Easy Customization, emacs}.
1313 If you know the name of the group in advance (e.g. ``shell''), use
1314 @kbd{M-x customize-group @key{RET}}.
1316 If you wish to customize a single option, use @kbd{M-x customize-option
1317 @key{RET}}. This command prompts you for the name of the option to
1318 customize, with completion.
1320 @node Colors on a TTY, Debugging a customization file, Using Customize, Common requests
1321 @section How do I get colors and syntax highlighting on a TTY?
1322 @cindex Colors on a TTY
1323 @cindex Syntax highlighting on a TTY
1324 @cindex Console, colors
1326 In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
1327 i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when
1328 invoked as @samp{emacs -nw} on X, MS-Windows, and Mac. (Colors and faces were
1329 supported in the MS-DOS port since Emacs 19.29.) Emacs automatically
1330 detects color support at startup and uses it if available. If you think
1331 that your terminal supports colors, but Emacs won't use them, check the
1332 @code{termcap} entry for your display type for color-related
1335 The command @kbd{M-x list-colors-display} pops up a window which
1336 exhibits all the colors Emacs knows about on the current display.
1338 Syntax highlighting is on by default since version 22.1.
1340 @node Debugging a customization file, Displaying the current line or column, Colors on a TTY, Common requests
1341 @section How do I debug a @file{.emacs} file?
1342 @cindex Debugging @file{.emacs} file
1343 @cindex @file{.emacs} debugging
1344 @cindex Init file debugging
1345 @cindex @samp{-debug-init} option
1347 Start Emacs with the @samp{-debug-init} command-line option. This
1348 enables the Emacs Lisp debugger before evaluating your @file{.emacs}
1349 file, and places you in the debugger if something goes wrong. The top
1350 line in the @file{trace-back} buffer will be the error message, and the
1351 second or third line of that buffer will display the Lisp code from your
1352 @file{.emacs} file that caused the problem.
1354 You can also evaluate an individual function or argument to a function
1355 in your @file{.emacs} file by moving the cursor to the end of the
1356 function or argument and typing @kbd{C-x C-e} (@kbd{M-x
1359 Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
1360 variables which you are trying to set or use.
1362 @node Displaying the current line or column, Displaying the current file name in the titlebar, Debugging a customization file, Common requests
1363 @section How do I make Emacs display the current line (or column) number?
1364 @cindex @code{line-number-mode}
1365 @cindex Displaying the current line or column
1366 @cindex Line number, displaying the current
1367 @cindex Column, displaying the current
1368 @cindex @code{mode-line-format}
1370 To have Emacs automatically display the current line number of the point
1371 in the mode line, do @kbd{M-x line-number-mode}. You can also put the
1375 (setq line-number-mode t)
1379 in your @file{.emacs} file to achieve this whenever you start Emacs.
1380 (Line number display is on by default, unless your site-specific
1381 initialization disables it.) Note that Emacs will not display the line
1382 number if the buffer's size in bytes is larger than the value of the
1383 variable @code{line-number-display-limit}.
1385 You can similarly display the current column with
1386 @kbd{M-x column-number-mode}, or by putting the form
1389 (setq column-number-mode t)
1393 in your @file{.emacs} file.
1395 The @code{"%c"} format specifier in the variable @code{mode-line-format}
1396 will insert the current column's value into the mode line. See the
1397 documentation for @code{mode-line-format} (using @kbd{C-h v
1398 mode-line-format @key{RET}}) for more information on how to set and use
1401 Users of all Emacs versions can display the current column using the
1402 @samp{column} package written by @email{abraham@@dina.kvl.dk, Per
1403 Abrahamsen}. @xref{Packages that do not come with Emacs}, for
1404 instructions on how to get it.
1406 @cindex Set number capability in @code{vi} emulators
1407 None of the @code{vi} emulation modes provide the ``set number''
1408 capability of @code{vi} (as far as we know). The @samp{setnu} package
1409 written by @email{kyle@@wonderworks.com, Kyle Jones} provides this
1410 feature. So too does @samp{wb-line-number}, written by
1411 @email{naoki.y.nakamura@@nifty.com, Naoki Nakamura}.
1413 @node Displaying the current file name in the titlebar, Turning on abbrevs by default, Displaying the current line or column, Common requests
1414 @section How can I modify the titlebar to contain the current file name?
1415 @cindex Titlebar, displaying the current file name in
1416 @cindex File name, displaying in the titlebar
1417 @cindex @code{frame-title-format}
1419 The contents of an Emacs frame's titlebar is controlled by the variable
1420 @code{frame-title-format}, which has the same structure as the variable
1421 @code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x
1422 describe-variable} to get information about one or both of these
1425 By default, the titlebar for a frame does contain the name of the buffer
1426 currently being visited, except if there is a single frame. In such a
1427 case, the titlebar contains Emacs invocation name and the name of the
1428 machine at which Emacs was invoked. This is done by setting
1429 @code{frame-title-format} to the default value of
1432 (multiple-frames "%b" ("" invocation-name "@@" system-name))
1435 To modify the behavior such that frame titlebars contain the buffer's
1436 name regardless of the number of existing frames, include the following
1437 in your @file{.emacs}:
1440 (setq frame-title-format "%b")
1443 @node Turning on abbrevs by default, Associating modes with files, Displaying the current file name in the titlebar, Common requests
1444 @section How do I turn on abbrevs by default just in mode @var{mymode}?
1445 @cindex Abbrevs, turning on by default
1447 Put this in your @file{.emacs} file:
1451 (quietly-read-abbrev-file)
1454 (add-hook '@var{mymode}-mode-hook
1456 (setq abbrev-mode t)))
1459 Starting with Emacs 22, the standard abbrevs file is read automatically
1460 at startup, so the first of these two forms becomes unnecessary.
1462 @node Associating modes with files, Highlighting a region, Turning on abbrevs by default, Common requests
1463 @section How do I make Emacs use a certain major mode for certain files?
1464 @cindex Associating modes with files
1465 @cindex File extensions and modes
1466 @cindex @code{auto-mode-alist}, modifying
1467 @cindex Modes, associating with file extensions
1469 If you want to use a certain mode @var{foo} for all files whose names end
1470 with the extension @file{.@var{bar}}, this will do it for you:
1473 (setq auto-mode-alist (cons '("\\.@var{bar}\\'" . @var{foo}-mode) auto-mode-alist))
1476 Otherwise put this somewhere in the first line of any file you want to
1477 edit in the mode @var{foo} (in the second line, if the first line begins
1484 @cindex Major mode for shell scripts
1485 Beginning with Emacs 19, the variable @code{interpreter-mode-alist}
1486 specifies which mode to use when loading a shell script. (Emacs
1487 determines which interpreter you're using by examining the first line of
1488 the script.) This feature only applies when the file name doesn't
1489 indicate which mode to use. Use @kbd{C-h v} (or @kbd{M-x
1490 describe-variable}) on @code{interpreter-mode-alist} to learn more.
1492 @node Highlighting a region, Replacing highlighted text, Associating modes with files, Common requests
1493 @section How can I highlight a region of text in Emacs?
1494 @cindex Highlighting text
1495 @cindex Text, highlighting
1496 @cindex @code{transient-mark-mode}
1497 @cindex Region, highlighting a
1499 You can cause the region to be highlighted when the mark is active by
1503 (transient-mark-mode t)
1507 in your @file{.emacs} file.
1509 @node Replacing highlighted text, Controlling case sensitivity, Highlighting a region, Common requests
1510 @section How can I replace highlighted text with what I type?
1511 @cindex @code{delete-selection-mode}
1512 @cindex Replacing highlighted text
1513 @cindex Highlighting and replacing text
1515 Use @code{delete-selection-mode}, which you can start automatically by
1516 placing the following Lisp form in your @file{.emacs} file:
1519 (delete-selection-mode 1)
1522 According to the documentation string for @code{delete-selection-mode}
1523 (which you can read using @kbd{M-x describe-function @key{RET}
1524 delete-selection-mode @key{RET}}):
1527 When ON, typed text replaces the selection if the selection is active.
1528 When OFF, typed text is just inserted at point.
1531 This mode also allows you to delete (not kill) the highlighted region by
1534 @node Controlling case sensitivity, Working with unprintable characters, Replacing highlighted text, Common requests
1535 @section How do I control Emacs's case-sensitivity when searching/replacing?
1536 @cindex @code{case-fold-search}
1537 @cindex Case sensitivity of searches
1538 @cindex Searching without case sensitivity
1539 @cindex Ignoring case in searches
1541 For searching, the value of the variable @code{case-fold-search}
1542 determines whether they are case sensitive:
1545 (setq case-fold-search nil) ; make searches case sensitive
1546 (setq case-fold-search t) ; make searches case insensitive
1549 @cindex Case sensitivity in replacements
1550 @cindex Replacing, and case sensitivity
1551 @cindex @code{case-replace}
1552 Similarly, for replacing, the variable @code{case-replace} determines
1553 whether replacements preserve case.
1555 You can also toggle case sensitivity at will in isearch with @kbd{M-c}.
1557 To change the case sensitivity just for one major mode, use the major
1558 mode's hook. For example:
1561 (add-hook '@var{foo}-mode-hook
1563 (setq case-fold-search nil)))
1566 @node Working with unprintable characters, Searching for/replacing newlines, Controlling case sensitivity, Common requests
1567 @section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
1568 @cindex Unprintable characters, working with
1569 @cindex Working with unprintable characters
1570 @cindex Control characters, working with
1571 @cindex Eight-bit characters, working with
1572 @cindex Searching for unprintable characters
1573 @cindex Regexps and unprintable characters
1575 To search for a single character that appears in the buffer as, for
1576 example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}. (This assumes
1577 the value of @code{search-quote-char} is 17 (i.e., @kbd{C-q}).)
1578 Searching for @strong{all} unprintable characters is best done with a
1579 regular expression (@dfn{regexp}) search. The easiest regexp to use for
1580 the unprintable chars is the complement of the regexp for the printable
1586 Regexp for the printable chars: @samp{[\t\n\r\f -~]}
1589 Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
1593 To type these special characters in an interactive argument to
1594 @code{isearch-forward-regexp} or @code{re-search-forward}, you need to
1595 use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
1596 respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So,
1597 to search for unprintable characters using @code{re-search-forward}:
1599 @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}}
1601 Using @code{isearch-forward-regexp}:
1603 @kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
1605 To delete all unprintable characters, simply use replace-regexp:
1607 @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}}
1609 Replacing is similar to the above. To replace all unprintable
1610 characters with a colon, use:
1612 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}
1614 @node Searching for/replacing newlines, Yanking text in isearch, Working with unprintable characters, Common requests
1615 @section How do I input a newline character in isearch or query-replace?
1616 @cindex Searching for newlines
1617 @cindex Replacing newlines
1619 Use @kbd{C-q C-j}. For more information, see @inforef{Special Isearch,
1620 Special Input for Incremental Search, emacs}.
1623 @node Yanking text in isearch, Wrapping words automatically, Searching for/replacing newlines, Common requests
1624 @section How do I copy text from the kill ring into the search string?
1625 @cindex Yanking text into the search string
1626 @cindex isearch yanking
1628 Use @kbd{M-y}. @inforef{Isearch Yank, Isearch Yanking, emacs}.
1630 @node Wrapping words automatically, Turning on auto-fill by default, Yanking text in isearch, Common requests
1631 @section How do I make Emacs wrap words for me?
1632 @cindex Wrapping word automatically
1633 @cindex Wrapping lines
1635 @cindex @code{auto-fill-mode}, introduction to
1636 @cindex Maximum line width, default value
1637 @cindex @code{fill-column}, default value
1639 Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
1640 The default maximum line width is 70, determined by the variable
1641 @code{fill-column}. To learn how to turn this on automatically, see
1642 @ref{Turning on auto-fill by default}.
1644 @node Turning on auto-fill by default, Spell-checkers, Wrapping words automatically, Common requests
1645 @section How do I turn on @code{auto-fill-mode} by default?
1646 @cindex @code{auto-fill-mode}, activating automatically
1647 @cindex Filling automatically
1648 @cindex Automatic entry to @code{auto-fill-mode}
1650 To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
1653 To turn it on for every buffer in a certain mode, you must use the hook
1654 for that mode. For example, to turn on @code{auto-fill} mode for all
1655 text buffers, including the following in your @file{.emacs} file:
1658 (add-hook 'text-mode-hook 'turn-on-auto-fill)
1661 If you want @code{auto-fill} mode on in all major modes, do this:
1664 (setq-default auto-fill-function 'do-auto-fill)
1667 @node Spell-checkers, Checking TeX and *roff documents, Turning on auto-fill by default, Common requests
1668 @section Where can I get a better spelling checker for Emacs?
1669 @cindex Checking spelling
1670 @cindex Spelling, checking text documents
1672 Use Ispell. @xref{Ispell}.
1674 @node Checking TeX and *roff documents, Changing load-path, Spell-checkers, Common requests
1675 @section How can I spell-check @TeX{} or *roff documents?
1676 @cindex Spelling, checking @TeX{} documents
1677 @cindex @TeX{} documents, checking spelling in
1679 Use Ispell. Ispell can handle @TeX{} and *roff documents.
1682 @node Changing load-path, Using an already running Emacs process, Checking TeX and *roff documents, Common requests
1683 @section How do I change @code{load-path}?
1684 @cindex @code{load-path}, modifying
1685 @cindex Modifying @code{load-path}
1686 @cindex Adding to @code{load-path}
1688 In general, you should only add to the @code{load-path}. You can add
1689 directory @var{/dir/subdir} to the load path like this:
1692 (setq load-path (cons "/dir/subdir/" load-path))
1695 To do this relative to your home directory:
1698 (setq load-path (cons "~/mysubdir/" load-path))
1701 @node Using an already running Emacs process, Compiler error messages, Changing load-path, Common requests
1702 @section How do I use an already running Emacs from another window?
1703 @cindex @code{emacsclient}
1704 @cindex Emacs server functions
1705 @cindex Using an existing Emacs process
1707 @code{emacsclient}, which comes with Emacs, is for editing a file using
1708 an already running Emacs rather than starting up a new Emacs. It does
1709 this by sending a request to the already running Emacs, which must be
1710 expecting the request.
1717 Emacs must have executed the @code{server-start} function for
1718 @samp{emacsclient} to work. This can be done either by a command line
1722 emacs -f server-start
1725 or by invoking @code{server-start} from @file{.emacs}:
1728 (if (@var{some conditions are met}) (server-start))
1731 When this is done, Emacs creates a Unix domain socket named
1732 @file{server} in @file{/tmp/emacs@var{userid}}. See
1733 @code{server-socket-dir}.
1735 To get your news reader, mail reader, etc., to invoke
1736 @samp{emacsclient}, try setting the environment variable @code{EDITOR}
1737 (or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may
1738 have to specify the full pathname of the @samp{emacsclient} program
1743 setenv EDITOR emacsclient
1745 # using full pathname
1746 setenv EDITOR /usr/local/emacs/etc/emacsclient
1749 EDITOR=emacsclient ; export EDITOR
1755 When @samp{emacsclient} is run, it connects to the socket and passes its
1756 command line options to Emacs, which at the next opportunity will visit
1757 the files specified. (Line numbers can be specified just like with
1758 Emacs.) The user will have to switch to the Emacs window by hand. When
1759 the user is done editing a file, the user can type @kbd{C-x #} (or
1760 @kbd{M-x server-edit}) to indicate this. If there is another buffer
1761 requested by @code{emacsclient}, Emacs will switch to it; otherwise
1762 @code{emacsclient} will exit, signaling the calling program to continue.
1764 @cindex @code{gnuserv}
1765 There is an enhanced version of @samp{emacsclient} called
1766 @samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman}
1767 (@pxref{Packages that do not come with Emacs}). @samp{gnuserv} uses
1768 Internet domain sockets, so it can work across most network connections.
1770 The most recent @samp{gnuserv} package is available at
1772 @uref{http://meltin.net/hacks/emacs/}
1776 @node Compiler error messages, Indenting switch statements, Using an already running Emacs process, Common requests
1777 @section How do I make Emacs recognize my compiler's funny error messages?
1778 @cindex Compiler error messages, recognizing
1779 @cindex Recognizing non-standard compiler errors
1780 @cindex Regexps for recognizing compiler errors
1781 @cindex Errors, recognizing compiler
1783 Customize the @code{compilation-error-regexp-alist} variable.
1785 @node Indenting switch statements, Customizing C and C++ indentation, Compiler error messages, Common requests
1786 @section How do I change the indentation for @code{switch}?
1787 @cindex @code{switch}, indenting
1788 @cindex Indenting of @code{switch}
1790 Many people want to indent their @code{switch} statements like this:
1808 The solution at first appears to be: set @code{c-indent-level} to 4 and
1809 @code{c-label-offset} to -2. However, this will give you an indentation
1810 spacing of four instead of two.
1812 The @emph{real} solution is to use @code{cc-mode} (the default mode for
1813 C programming in Emacs 20 and later) and add the following line to your
1817 (c-set-offset 'case-label '+)
1820 There appears to be no way to do this with the old @code{c-mode}.
1822 @node Customizing C and C++ indentation, Horizontal scrolling, Indenting switch statements, Common requests
1823 @section How to customize indentation in C, C@t{++}, and Java buffers?
1824 @cindex Indentation, how to customize
1825 @cindex Customize indentation
1827 The Emacs @code{cc-mode} features an interactive procedure for
1828 customizing the indentation style, which is fully explained in the
1829 @cite{CC Mode} manual that is part of the Emacs distribution, see
1830 @ref{Customizing Indentation, , Customization Indentation, ccmode,
1831 The CC Mode Manual}. Here's a short summary of the procedure:
1835 Go to the beginning of the first line where you don't like the
1836 indentation and type @kbd{C-c C-o}. Emacs will prompt you for the
1837 syntactic symbol; type @key{RET} to accept the default it suggests.
1840 Emacs now prompts for the offset of this syntactic symbol, showing the
1841 default (the current definition) inside parentheses. You can choose
1846 No extra indentation.
1848 Indent one basic offset.
1850 Outdent one basic offset.
1852 Indent two basic offsets
1854 Outdent two basic offsets.
1856 Indent half basic offset.
1858 Outdent half basic offset.
1862 After choosing one of these symbols, type @kbd{C-c C-q} to reindent
1863 the line or the block according to what you just specified.
1866 If you don't like the result, go back to step 1. Otherwise, add the
1867 following line to your @file{.emacs}:
1870 (c-set-offset '@var{syntactic-symbol} @var{offset})
1874 where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
1875 when you type @kbd{C-c C-o} at the beginning of the line, and
1876 @var{offset} is one of the indentation symbols listed above (@code{+},
1877 @code{/}, @code{0}, etc.) that you've chosen during the interactive
1881 Go to the next line whose indentation is not to your liking and repeat
1885 It is recommended to put all the resulting @code{(c-set-offset ...)}
1886 customizations inside a C mode hook, like this:
1889 (defun my-c-mode-hook ()
1892 (add-hook 'c-mode-hook 'my-c-mode-hook)
1896 Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
1897 'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
1898 might be unavailable when @code{cc-mode} is not loaded.
1900 Note that @code{c-mode-hook} runs for C source files only; use
1901 @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
1902 Java sources, etc. If you want the same customizations to be in
1903 effect in @emph{all} languages supported by @code{cc-mode}, use
1904 @code{c-mode-common-hook}.
1906 @node Horizontal scrolling, Overwrite mode, Customizing C and C++ indentation, Common requests
1907 @section How can I make Emacs automatically scroll horizontally?
1908 @cindex @code{hscroll-mode}
1909 @cindex Horizontal scrolling
1910 @cindex Scrolling horizontally
1912 In Emacs 21 and later, this is on by default: if the variable
1913 @code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
1914 automatically scrolls the display horizontally when point moves off the
1915 left or right edge of the window.
1917 Note that this is overridden by the variable
1918 @code{truncate-partial-width-windows} if that variable is non-nil
1919 and the current buffer is not full-frame width.
1921 In Emacs 20, use the @code{hscroll-mode}. Here is some information from
1922 the documentation, available by typing @kbd{C-h f hscroll-mode @key{RET}}:
1924 Automatically scroll horizontally when the point moves off the
1925 left or right edge of the window.
1929 Type @kbd{M-x hscroll-mode} to enable it in the current buffer.
1932 Type @kbd{M-x hscroll-global-mode} to enable it in every buffer.
1935 @code{turn-on-hscroll} is useful in mode hooks as in:
1938 (add-hook 'text-mode-hook 'turn-on-hscroll)
1942 @code{hscroll-margin} controls how close the cursor can get to the
1946 @code{hscroll-step-percent} controls how far to jump once we decide to do so.
1949 @node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests
1950 @section How do I make Emacs ``typeover'' or ``overwrite'' instead of inserting?
1951 @cindex @key{Insert}
1952 @cindex @code{overwrite-mode}
1953 @cindex Overwriting existing text
1954 @cindex Toggling @code{overwrite-mode}
1956 @kbd{M-x overwrite-mode} (a minor mode). This toggles
1957 @code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
1958 is as easy as another @kbd{M-x overwrite-mode}.
1960 On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
1962 @node Turning off beeping, Turning the volume down, Overwrite mode, Common requests
1963 @section How do I stop Emacs from beeping on a terminal?
1964 @cindex Beeping, turning off
1965 @cindex Visible bell
1966 @cindex Bell, visible
1968 @email{martin@@cc.gatech.edu, Martin R. Frank} writes:
1970 Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
1971 and set the visible bell to nothing.
1973 That is, put the following in your @code{TERMCAP} environment variable
1974 (assuming you have one):
1980 And evaluate the following Lisp form:
1983 (setq visible-bell t)
1986 @node Turning the volume down, Automatic indentation, Turning off beeping, Common requests
1987 @section How do I turn down the bell volume in Emacs running under X?
1988 @cindex Bell, volume of
1989 @cindex Volume of bell
1991 On X Window system, you can adjust the bell volume and duration for all
1992 programs with the shell command @code{xset}.
1994 Invoking @code{xset} without any arguments produces some basic
1995 information, including the following:
1998 usage: xset [-display host:dpy] option ...
2001 To set bell volume, pitch and duration:
2002 b [vol [pitch [dur]]] b on
2005 @node Automatic indentation, Matching parentheses, Turning the volume down, Common requests
2006 @section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
2007 @cindex Indenting new lines
2008 @cindex New lines, indenting of
2009 @cindex Previous line, indenting according to
2010 @cindex Text indentation
2012 Such behavior is automatic in Emacs 20 and later. From the
2013 @file{etc/NEWS} file for Emacs 20.2:
2016 ** In Text mode, now only blank lines separate paragraphs. This makes
2017 it possible to get the full benefit of Adaptive Fill mode in Text mode,
2018 and other modes derived from it (such as Mail mode). @key{TAB} in Text
2019 mode now runs the command @code{indent-relative}; this makes a practical
2020 difference only when you use indented paragraphs.
2022 As a result, the old Indented Text mode is now identical to Text mode,
2023 and is an alias for it.
2025 If you want spaces at the beginning of a line to start a paragraph, use
2026 the new mode, Paragraph Indent Text mode.
2029 @cindex Prefixing lines
2031 If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
2032 by default}), you can tell Emacs to prefix every line with a certain
2033 character sequence, the @dfn{fill prefix}. Type the prefix at the
2034 beginning of a line, position point after it, and then type @kbd{C-x .}
2035 (@code{set-fill-prefix}) to set the fill prefix. Thereafter,
2036 auto-filling will automatically put the fill prefix at the beginning of
2037 new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
2038 prefix when refilling the paragraph.
2040 If you have paragraphs with different levels of indentation, you will
2041 have to set the fill prefix to the correct value each time you move to a
2042 new paragraph. There are many packages available to deal with this
2043 (@pxref{Packages that do not come with Emacs}). Look for ``fill'' and
2044 ``indent'' keywords for guidance.
2046 @node Matching parentheses, Hiding #ifdef lines, Automatic indentation, Common requests
2047 @section How do I show which parenthesis matches the one I'm looking at?
2048 @cindex Parentheses, matching
2049 @cindex @file{paren.el}
2050 @cindex Highlighting matching parentheses
2051 @cindex Pairs of parentheses, highlighting
2052 @cindex Matching parentheses
2054 Call @code{show-paren-mode} in your @file{.emacs} file:
2060 You can also enable this mode by selecting the @samp{Paren Match
2061 Highlighting} option from the @samp{Options} menu of the Emacs menu bar
2062 at the top of any Emacs frame.
2064 Alternatives to this mode include:
2069 If you're looking at a right parenthesis (or brace or bracket) you can
2070 delete it and reinsert it. Emacs will momentarily move the cursor to
2071 the matching parenthesis.
2074 @kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
2075 will skip over one set of balanced parentheses, so you can see which
2076 parentheses match. (You can train it to skip over balanced brackets
2077 and braces at the same time by modifying the syntax table.)
2079 @cindex Show matching paren as in @code{vi}
2081 Here is some Emacs Lisp that will make the @key{%} key show the matching
2082 parenthesis, like in @code{vi}. In addition, if the cursor isn't over a
2083 parenthesis, it simply inserts a % like normal.
2086 ;; By an unknown contributor
2088 (global-set-key "%" 'match-paren)
2090 (defun match-paren (arg)
2091 "Go to the matching paren if on a paren; otherwise insert %."
2093 (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
2094 ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
2095 (t (self-insert-command (or arg 1)))))
2100 @node Hiding #ifdef lines, Repeating commands, Matching parentheses, Common requests
2101 @section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
2102 @cindex @code{#ifdef}, selective display of
2103 @cindex @code{hide-ifdef-mode}
2104 @cindex Hiding @code{#ifdef} text
2105 @cindex Selectively displaying @code{#ifdef} code
2107 @kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want
2108 to investigate @file{cpp.el}, which is distributed with Emacs.
2110 @node Repeating commands, Valid X resources, Hiding #ifdef lines, Common requests
2111 @section How do I repeat a command as many times as possible?
2112 @cindex Repeating commands many times
2113 @cindex Commands, repeating many times
2114 @cindex @code{.}, equivalent to @code{vi} command
2116 As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
2117 that repeats the last command. If you preface it with a prefix
2118 argument, the prefix arg is applied to the command.
2120 You can also type @kbd{C-x @key{ESC} @key{ESC}}
2121 (@code{repeat-complex-command}) to reinvoke commands that used the
2122 minibuffer to get arguments. In @code{repeat-complex-command} you can
2123 type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
2124 keyboard has these keys) to scan through all the different complex
2125 commands you've typed.
2127 To repeat a set of commands, use keyboard macros. Use @kbd{C-x (} and
2128 @kbd{C-x )} to make a keyboard macro that invokes the command and then
2129 type @kbd{C-x e}. (@inforef{Keyboard Macros, Keyboard Macros, emacs}.)
2131 If you're really desperate for the @code{.} command in @code{vi} that
2132 redoes the last insertion/deletion, use VIPER, a @code{vi} emulation
2133 mode which comes with Emacs, and which appears to support it.
2136 @node Valid X resources, Evaluating Emacs Lisp code, Repeating commands, Common requests
2137 @section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
2138 @cindex Resources, X
2140 @cindex Setting X resources
2142 @inforef{X Resources, X Resources, emacs}.
2144 You can also use a resource editor, such as editres (for X11R5 and
2145 onwards), to look at the resource names for the menu bar, assuming Emacs
2146 was compiled with the X toolkit.
2148 @node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests
2149 @section How do I execute (``evaluate'') a piece of Emacs Lisp code?
2150 @cindex Evaluating Lisp code
2151 @cindex Lisp forms, evaluating
2153 There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
2154 Emacs Lisp @dfn{form}:
2159 If you want it evaluated every time you run Emacs, put it in a file
2160 named @file{.emacs} in your home directory. This is known as ``your
2161 @file{.emacs} file,'' and contains all of your personal customizations.
2164 You can type the form in the @file{*scratch*} buffer, and then type
2165 @key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form
2166 will be inserted in the buffer.
2169 In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
2170 before or around point.
2173 Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
2174 before point and prints its value in the echo area.
2177 Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
2178 form in the minibuffer which will be evaluated once you press @key{RET}.
2181 You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
2182 forms in a file. (To do this from Lisp use the function @code{load}
2185 The functions @code{load-library}, @code{eval-region},
2186 @code{eval-buffer}, @code{require}, and @code{autoload} are also
2187 useful; see @ref{Emacs Lisp documentation}, if you want to learn more
2192 @node Changing the length of a Tab, Inserting text at the beginning of each line, Evaluating Emacs Lisp code, Common requests
2193 @section How do I change Emacs's idea of the @key{TAB} character's length?
2195 @cindex Length of tab character
2196 @cindex @code{default-tab-width}
2198 Set the variable @code{default-tab-width}. For example, to set
2199 @key{TAB} stops every 10 characters, insert the following in your
2203 (setq default-tab-width 10)
2206 Do not confuse variable @code{tab-width} with variable
2207 @code{tab-stop-list}. The former is used for the display of literal
2208 @key{TAB} characters. The latter controls what characters are inserted
2209 when you press the @key{TAB} character in certain modes.
2211 @node Inserting text at the beginning of each line, Underlining paragraphs, Changing the length of a Tab, Common requests
2212 @section How do I insert <some text> at the beginning of every line?
2213 @cindex Prefixing a region with some text
2214 @cindex Prefix character, inserting in mail/news replies
2215 @cindex Replies to mail/news, inserting a prefix character
2216 @cindex @code{mail-yank-prefix}
2217 @cindex Mail replies, inserting a prefix character
2218 @cindex News replies, inserting a prefix character
2220 To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
2221 @key{RET} ^ @key{RET} your text @key{RET}}.
2223 To do this to a region, use @code{string-insert-rectangle}.
2224 Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
2225 want to prefix, move the cursor to last line to be prefixed, and type
2226 @kbd{M-x string-insert-rectangle @key{RET}}. To do this for the whole
2227 buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
2229 If you are trying to prefix a yanked mail message with @samp{>}, you
2230 might want to set the variable @code{mail-yank-prefix}. In Message
2231 buffers, you can even use @kbd{M-;} to cite yanked messages (@kbd{M-;}
2232 runs the function @code{comment-region}, it is a general-purpose
2233 mechanism to comment regions) (@pxref{Changing the included text prefix}).
2235 @node Underlining paragraphs, Forcing the cursor to remain in the same column, Inserting text at the beginning of each line, Common requests
2236 @section How do I insert @samp{_^H} before each character in a region to get an underlined paragraph?
2237 @cindex Underlining a region of text
2238 @cindex @code{underline-region}
2240 Mark the region and then type @kbd{M-x underline-region @key{RET}}.
2242 @node Forcing the cursor to remain in the same column, Forcing Emacs to iconify itself, Underlining paragraphs, Common requests
2243 @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?
2244 @cindex @code{picture-mode}
2245 @cindex Remaining in the same column, regardless of contents
2246 @cindex Vertical movement in empty documents
2248 Use @kbd{M-x picture-mode}.
2250 See also the variable @code{track-eol} and the command
2251 @code{set-goal-column} bound to @kbd{C-x C-n}
2252 (@pxref{Moving Point, , , emacs, The GNU Emacs Manual}).
2254 @node Forcing Emacs to iconify itself, Using regular expressions, Forcing the cursor to remain in the same column, Common requests
2255 @section How do I tell Emacs to iconify itself?
2256 @cindex Iconification under the X Window System
2257 @cindex X Window System and iconification
2258 @cindex Suspending Emacs
2260 @kbd{C-z} iconifies Emacs when running under X and suspends Emacs
2261 otherwise. @inforef{Frame Commands, Frame Commands, emacs}.
2263 @node Using regular expressions, Replacing text across multiple files, Forcing Emacs to iconify itself, Common requests
2264 @section How do I use regexps (regular expressions) in Emacs?
2266 @cindex Regular expressions
2267 @cindex Differences between Unix and Emacs regexps
2268 @cindex Unix regexps, differences from Emacs
2269 @cindex Text strings, putting regexps in
2271 @inforef{Regexp Backslash, Regexp Backslash, emacs}.
2273 The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
2274 are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is
2275 @samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)}
2276 in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
2278 Note the doubled backslashes!
2283 Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
2284 (@samp{[^...]}) can match a newline character (@key{LFD} a.k.a.@:
2285 @kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
2286 characters not to match.
2289 The character syntax regexps (e.g., @samp{\sw}) are not
2290 meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This
2291 is actually typical for regexp syntax.)
2295 @node Replacing text across multiple files, Documentation for etags, Using regular expressions, Common requests
2296 @section How do I perform a replace operation across more than one file?
2297 @cindex Replacing strings across files
2298 @cindex Multiple files, replacing across
2299 @cindex Files, replacing strings across multiple
2300 @cindex Recursive search/replace operations
2302 As of Emacs 19.29, Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x
2303 d}) supports the command @code{dired-do-query-replace} (@kbd{Q}), which
2304 allows users to replace regular expressions in multiple files.
2306 You can use this command to perform search/replace operations on
2307 multiple files by following the following steps:
2311 Assemble a list of files you want to operate on with either
2312 @code{find-dired}, @code{find-name-dired} or @code{find-grep-dired}.
2315 Mark all files in the resulting Dired buffer using @kbd{t}.
2318 Use @kbd{Q} to start a @code{query-replace-regexp} session on the marked
2322 To accept all replacements in each file, hit @kbd{!}.
2325 Another way to do the same thing is to use the ``tags'' feature of
2326 Emacs: it includes the command @code{tags-query-replace} which performs
2327 a query-replace across all the files mentioned in the @file{TAGS} file.
2328 @inforef{Tags Search, Tags Search, emacs}.
2330 @node Documentation for etags, Disabling backups, Replacing text across multiple files, Common requests
2331 @section Where is the documentation for @code{etags}?
2332 @cindex Documentation for @code{etags}
2333 @cindex @code{etags}, documentation for
2335 The @code{etags} man page should be in the same place as the
2336 @code{emacs} man page.
2338 Quick command-line switch descriptions are also available. For example,
2341 @node Disabling backups, Disabling auto-save-mode, Documentation for etags, Common requests
2342 @section How do I disable backup files?
2343 @cindex Backups, disabling
2344 @cindex Disabling backups
2346 You probably don't want to do this, since backups are useful, especially
2347 when something goes wrong.
2349 To avoid seeing backup files (and other ``uninteresting'' files) in Dired,
2350 load @code{dired-x} by adding the following to your @file{.emacs} file:
2353 (add-hook 'dired-load-hook
2358 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
2359 You can make omitting the default for new dired buffers by putting the
2360 following in your @file{.emacs}:
2363 (add-hook 'dired-mode-hook 'dired-omit-toggle)
2366 If you're tired of seeing backup files whenever you do an @samp{ls} at
2367 the Unix shell, try GNU @code{ls} with the @samp{-B} option. GNU
2368 @code{ls} is part of the GNU Fileutils package, available from
2369 @samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
2371 To disable or change the way backups are made, @inforef{Backup Names, ,
2374 @cindex Backup files in a single directory
2375 Beginning with Emacs 21.1, you can control where Emacs puts backup files
2376 by customizing the variable @code{backup-directory-alist}. This
2377 variable's value specifies that files whose names match specific patters
2378 should have their backups put in certain directories. A typical use is
2379 to add the element @code{("." . @var{dir})} to force Emacs to put
2380 @strong{all} backup files in the directory @file{dir}.
2382 @node Disabling auto-save-mode, Going to a line by number, Disabling backups, Common requests
2383 @section How do I disable @code{auto-save-mode}?
2384 @cindex Disabling @code{auto-save-mode}
2386 @cindex Saving at frequent intervals
2388 You probably don't want to do this, since auto-saving is useful,
2389 especially when Emacs or your computer crashes while you are editing a
2392 Instead, you might want to change the variable
2393 @code{auto-save-interval}, which specifies how many keystrokes Emacs
2394 waits before auto-saving. Increasing this value forces Emacs to wait
2395 longer between auto-saves, which might annoy you less.
2397 You might also want to look into Sebastian Kremer's @code{auto-save}
2398 package (@pxref{Packages that do not come with Emacs}). This
2399 package also allows you to place all auto-save files in one directory,
2400 such as @file{/tmp}.
2402 To disable or change how @code{auto-save-mode} works, @inforef{Auto
2405 @node Going to a line by number, Modifying pull-down menus, Disabling auto-save-mode, Common requests
2406 @section How can I go to a certain line given its number?
2407 @cindex Going to a line by number
2408 @cindex Compilation error messages
2409 @cindex Recompilation
2411 Are you sure you indeed need to go to a line by its number? Perhaps all
2412 you want is to display a line in your source file for which a compiler
2413 printed an error message? If so, compiling from within Emacs using the
2414 @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
2415 effective way of doing that. Emacs automatically intercepts the compile
2416 error messages, inserts them into a special buffer called
2417 @code{*compilation*}, and lets you visit the locus of each message in
2418 the source. Type @kbd{C-x `} to step through the offending lines one by
2419 one (starting with Emacs 22, you can also use @kbd{M-g M-p} and
2420 @kbd{M-g M-n} to go to the previous and next matches directly). Click
2421 @kbd{Mouse-2} or press @key{RET} on a message text in the
2422 @code{*compilation*} buffer to go to the line whose number is mentioned
2425 But if you indeed need to go to a certain text line, type @kbd{M-g M-g}
2426 (which is the default binding of the @code{goto-line} function starting
2427 with Emacs 22). Emacs will prompt you for the number of the line and go
2430 You can do this faster by invoking @code{goto-line} with a numeric
2431 argument that is the line's number. For example, @kbd{C-u 286 M-g M-g}
2432 will jump to line number 286 in the current buffer.
2434 @node Modifying pull-down menus, Deleting menus and menu options, Going to a line by number, Common requests
2435 @section How can I create or modify new pull-down menu options?
2436 @cindex Pull-down menus, creating or modifying
2437 @cindex Menus, creating or modifying
2438 @cindex Creating new menu options
2439 @cindex Modifying pull-down menus
2440 @cindex Menus and keymaps
2441 @cindex Keymaps and menus
2443 Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
2444 represents a local or global keymap. Selecting a menu title with the
2445 mouse displays that keymap's non-@code{nil} contents in the form of a menu.
2447 So to add a menu option to an existing menu, all you have to do is add a
2448 new definition to the appropriate keymap. Adding a @samp{Forward Word}
2449 item to the @samp{Edit} menu thus requires the following Lisp code:
2452 (define-key global-map
2453 [menu-bar edit forward]
2454 '("Forward word" . forward-word))
2458 The first line adds the entry to the global keymap, which includes
2459 global menu bar entries. Replacing the reference to @code{global-map}
2460 with a local keymap would add this menu option only within a particular
2463 The second line describes the path from the menu-bar to the new entry.
2464 Placing this menu entry underneath the @samp{File} menu would mean
2465 changing the word @code{edit} in the second line to @code{file}.
2467 The third line is a cons cell whose first element is the title that will
2468 be displayed, and whose second element is the function that will be
2469 called when that menu option is invoked.
2471 To add a new menu, rather than a new option to an existing menu, we must
2472 define an entirely new keymap:
2475 (define-key global-map [menu-bar words]
2476 (cons "Words" (make-sparse-keymap "Words")))
2479 The above code creates a new sparse keymap, gives it the name
2480 @samp{Words}, and attaches it to the global menu bar. Adding the
2481 @samp{Forward Word} item to this new menu would thus require the
2485 (define-key global-map
2486 [menu-bar words forward]
2487 '("Forward word" . forward-word))
2491 Note that because of the way keymaps work, menu options are displayed
2492 with the more recently defined items at the top. Thus if you were to
2493 define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
2494 order), the menu option @samp{baz} would appear at the top, and
2495 @samp{foo} would be at the bottom.
2497 One way to avoid this problem is to use the function @code{define-key-after},
2498 which works the same as @code{define-key}, but lets you modify where items
2499 appear. The following Lisp code would insert the @samp{Forward Word}
2500 item in the @samp{Edit} menu immediately following the @samp{Undo} item:
2504 (lookup-key global-map [menu-bar edit])
2506 '("Forward word" . forward-word)
2510 Note how the second and third arguments to @code{define-key-after} are
2511 different from those of @code{define-key}, and that we have added a new
2512 (final) argument, the function after which our new key should be
2515 To move a menu option from one position to another, simply evaluate
2516 @code{define-key-after} with the appropriate final argument.
2518 More detailed information---and more examples of how to create and
2519 modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
2520 ``Menu Keymaps.'' (@xref{Emacs Lisp documentation}, for information on
2523 @node Deleting menus and menu options, Turning on syntax highlighting, Modifying pull-down menus, Common requests
2524 @section How do I delete menus and menu options?
2525 @cindex Deleting menus and menu options
2526 @cindex Menus, deleting
2528 The simplest way to remove a menu is to set its keymap to @samp{nil}.
2529 For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
2533 (define-key global-map [menu-bar words] nil)
2536 Similarly, removing a menu option requires redefining a keymap entry to
2537 @code{nil}. For example, to delete the @samp{Forward word} menu option
2538 from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
2542 (define-key global-map [menu-bar edit forward] nil)
2545 @node Turning on syntax highlighting, Scrolling only one line, Deleting menus and menu options, Common requests
2546 @section How do I turn on syntax highlighting?
2547 @cindex Syntax highlighting
2548 @cindex @code{font-lock-mode}
2549 @cindex Highlighting based on syntax
2550 @cindex Colorizing text
2551 @cindex FAQ, @code{font-lock-mode}
2553 @code{font-lock-mode} is the standard way to have Emacs perform syntax
2554 highlighting in the current buffer. It is enabled by default in Emacs
2557 With @code{font-lock-mode} turned on, different types of text will
2558 appear in different colors. For instance, in a programming mode,
2559 variables will appear in one face, keywords in a second, and comments in
2562 @cindex hilit19 is deprecated
2563 Earlier versions of Emacs supported hilit19, a similar package. Use of
2564 hilit19 is now considered non-standard, although @file{hilit19.el} comes
2565 with the stock Emacs distribution. It is no longer maintained.
2567 To turn @code{font-lock-mode} off within an existing buffer, use
2568 @kbd{M-x font-lock-mode @key{RET}}.
2570 In Emacs 21 and earlier versions, you could use the following code in
2571 your @file{.emacs} file to turn on @code{font-lock-mode} globally:
2574 (global-font-lock-mode 1)
2577 Highlighting a buffer with @code{font-lock-mode} can take quite a while,
2578 and cause an annoying delay in display, so several features exist to
2581 @cindex Just-In-Time syntax highlighting
2582 In Emacs 21 and later, turning on @code{font-lock-mode} automatically
2583 activates the new @dfn{Just-In-Time fontification} provided by
2584 @code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of
2585 portions of buffer until you actually need to see them, and can also
2586 fontify while Emacs is idle. This makes display of the visible portion
2587 of a buffer almost instantaneous. For details about customizing
2588 @code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
2590 @cindex Levels of syntax highlighting
2591 @cindex Decoration level, in @code{font-lock-mode}
2592 In versions of Emacs before 21, different levels of decoration are
2593 available, from slight to gaudy. More decoration means you need to wait
2594 more time for a buffer to be fontified (or a faster machine). To
2595 control how decorated your buffers should become, set the value of
2596 @code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
2597 @code{nil} value indicating default (usually minimum) decoration, and a
2598 @code{t} value indicating the maximum decoration. For the gaudiest
2599 possible look, then, include the line
2602 (setq font-lock-maximum-decoration t)
2606 in your @file{.emacs} file. You can also set this variable such that
2607 different modes are highlighted in a different ways; for more
2608 information, see the documentation for
2609 @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
2610 describe-variable @key{RET}}).
2612 Also see the documentation for the function @code{font-lock-mode},
2613 available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
2614 describe-function @key{RET} font-lock-mode @key{RET}}).
2616 To print buffers with the faces (i.e., colors and fonts) intact, use
2617 @kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
2618 ps-print-region-with-faces}. You will need a way to send text to a
2619 PostScript printer, or a PostScript interpreter such as Ghostscript;
2620 consult the documentation of the variables @code{ps-printer-name},
2621 @code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
2623 @node Scrolling only one line, Editing MS-DOS files, Turning on syntax highlighting, Common requests
2624 @section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
2625 @cindex Scrolling only one line
2626 @cindex Reducing the increment when scrolling
2628 Customize the @code{scroll-conservatively} variable with @kbd{M-x
2629 customize-variable @key{RET} scroll-conservatively @key{RET}} and set it
2630 to a large value like, say, 10000. For an explanation of what this
2631 means, @inforef{Auto Scrolling, Auto Scrolling, emacs}.
2633 Alternatively, use the following Lisp form in your @file{.emacs}:
2636 (setq scroll-conservatively most-positive-fixnum)
2639 @node Editing MS-DOS files, Filling paragraphs with a single space, Scrolling only one line, Common requests
2640 @section How can I edit MS-DOS files using Emacs?
2641 @cindex Editing MS-DOS files
2642 @cindex MS-DOS files, editing
2643 @cindex Microsoft files, editing
2644 @cindex Windows files, editing
2646 As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
2647 performed transparently. You can open MS-DOS files on a Unix system,
2648 edit it, and save it without having to worry about the file format.
2650 When editing an MS-DOS style file, the mode line will indicate that it
2651 is a DOS file. On Unix and GNU/Linux systems, and also on a Macintosh,
2652 the string @samp{(DOS)} will appear near the left edge of the mode line;
2653 on DOS and Windows, where the DOS end-of-line (EOL) format is the
2654 default, a backslash (@samp{\}) will appear in the mode line.
2656 If you are running a version of Emacs before 20.1, get @code{crypt++}
2657 (@pxref{Packages that do not come with Emacs}). Among other things,
2658 @code{crypt++} transparently modifies MS-DOS files as they are loaded
2659 and saved, allowing you to ignore the different conventions that Unix
2660 and MS-DOS have for delineating the end of a line.
2662 @node Filling paragraphs with a single space, Escape sequences in shell output, Editing MS-DOS files, Common requests
2663 @section How can I tell Emacs to fill paragraphs with a single space after each period?
2664 @cindex One space following periods
2665 @cindex Single space following periods
2666 @cindex Periods, one space following
2668 Add the following line to your @file{.emacs} file:
2671 (setq sentence-end-double-space nil)
2674 @node Escape sequences in shell output, , Filling paragraphs with a single space, Common requests
2675 @section Why these strange escape sequences from @code{ls} from the Shell mode?
2676 @cindex Escape sequences in @code{ls} output
2677 @cindex @code{ls} in Shell mode
2679 This happens because @code{ls} is aliased to @samp{ls --color} in your
2680 shell init file. You have two alternatives to solve this:
2684 Make the alias conditioned on the @code{EMACS} variable in the
2685 environment. When Emacs runs a subsidiary shell, it exports the
2686 @code{EMACS} variable to that shell, with value equal to the absolute
2687 file name of Emacs. You can
2688 unalias @code{ls} when that happens, thus limiting the alias to your
2689 interactive sessions.
2692 Install the @code{ansi-color} package (bundled with Emacs 21.1 and
2693 later), which converts these ANSI escape sequences into colors.
2696 @c ------------------------------------------------------------
2697 @node Bugs and problems, Compiling and installing Emacs, Common requests, Top
2698 @chapter Bugs and problems
2699 @cindex Bugs and problems
2701 The Emacs manual lists some common kinds of trouble users could get
2702 into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
2703 Emacs Manual}, so you might look there if the problem you encounter
2704 isn't described in this chapter. If you decide you've discovered a bug,
2705 see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
2706 instructions how to do that.
2708 The file @file{etc/PROBLEMS} in the Emacs distribution lists various
2709 known problems with building and using Emacs on specific platforms;
2710 type @kbd{C-h C-e} to read it.
2713 * Problems with very large files::
2714 * ^M in the shell buffer::
2715 * Shell process exits abnormally::
2716 * Problems with Shell Mode on MS-Windows::
2717 * Termcap/Terminfo entries for Emacs::
2718 * Spontaneous entry into isearch-mode::
2719 * Problems talking to certain hosts::
2720 * Errors with init files::
2721 * Emacs ignores X resources::
2722 * Emacs ignores frame parameters::
2723 * Emacs takes a long time to visit files::
2724 * Editing files with $ in the name::
2725 * Shell mode loses the current directory::
2726 * Security risks with Emacs::
2727 * Dired claims that no file is on this line::
2730 @node Problems with very large files, ^M in the shell buffer, Bugs and problems, Bugs and problems
2731 @section Does Emacs have problems with files larger than 8 megabytes?
2732 @cindex Very large files, opening
2733 @cindex Large files, opening
2734 @cindex Opening very large files
2735 @cindex Maximum file size
2736 @cindex Files, maximum size
2738 Old versions (i.e., anything before 19.29) of Emacs had problems editing
2739 files larger than 8 megabytes. In versions 19.29 and later, the maximum
2740 buffer size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes.
2741 And in Emacs 22, the maximum buffer size has been increased to
2742 268,435,455 bytes (or 256 MBytes) on 32-bit machines.
2744 @node ^M in the shell buffer, Shell process exits abnormally, Problems with very large files, Bugs and problems
2745 @section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
2746 @cindex Shell buffer, echoed commands and @samp{^M} in
2747 @cindex Echoed commands in @code{shell-mode}
2749 Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
2750 make them go away. If that doesn't work, you have several options:
2752 For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
2757 if ("$EMACS" =~ /*) then
2758 if ($?tcsh) unset edit
2764 Or put this in your @file{.emacs_tcsh} or @file{~/.emacs.d/init_tcsh.sh} file:
2771 Alternatively, use @code{csh} in your shell buffers instead of
2772 @code{tcsh}. One way is:
2775 (setq explicit-shell-file-name "/bin/csh")
2779 and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
2783 setenv ESHELL /bin/csh
2787 (You must start Emacs over again with the environment variable properly
2788 set for this to take effect.)
2790 You can also set the @code{ESHELL} environment variable in Emacs Lisp
2791 with the following Lisp form,
2794 (setenv "ESHELL" "/bin/csh")
2797 The above solutions try to prevent the shell from producing the
2798 @samp{^M} characters in the first place. If this is not possible
2799 (e.g., if you use a Windows shell), you can get Emacs to remove these
2800 characters from the buffer by adding this to your @file{.emacs} init
2804 (add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
2807 On a related note: if your shell is echoing your input line in the shell
2808 buffer, you might want to customize the @code{comint-process-echoes}
2809 variable in your shell buffers, or try the following command in your
2810 shell start-up file:
2813 stty -icrnl -onlcr -echo susp ^Z
2816 @node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems
2817 @section Why do I get ``Process shell exited abnormally with code 1''?
2818 @cindex Abnormal exits from @code{shell-mode}
2819 @cindex @code{shell-mode} exits
2820 @cindex Process shell exited
2822 The most likely reason for this message is that the @samp{env} program
2823 is not properly installed. Compile this program for your architecture,
2824 and install it with @samp{a+x} permission in the architecture-dependent
2825 Emacs program directory. (You can find what this directory is at your
2826 site by inspecting the value of the variable @code{exec-directory} by
2827 typing @kbd{C-h v exec-directory @key{RET}}.)
2829 You should also check for other programs named @samp{env} in your path
2830 (e.g., SunOS has a program named @file{/usr/bin/env}). We don't
2831 understand why this can cause a failure and don't know a general
2832 solution for working around the problem in this case.
2834 The @samp{make clean} command will remove @samp{env} and other vital
2835 programs, so be careful when using it.
2837 It has been reported that this sometimes happened when Emacs was started
2838 as an X client from an xterm window (i.e., had a controlling tty) but the
2839 xterm was later terminated.
2841 See also @samp{PROBLEMS} (in the @file{etc} subdirectory of the
2842 top-level directory when you unpack the Emacs source) for other
2843 possible causes of this message.
2845 @node Problems with Shell Mode on MS-Windows, Termcap/Terminfo entries for Emacs, Shell process exits abnormally, Bugs and problems
2846 @section Why do I get an error message when I try to run @kbd{M-x shell}?
2848 @cindex Shell Mode, and MS-Windows
2849 @cindex @code{explicit-shell-file-name}
2850 On MS-Windows, this might happen because Emacs tries to look for the
2851 shell in a wrong place. The default file name @file{/bin/sh} is
2852 usually incorrect for non-Unix systems. If you know where your shell
2853 executable is, set the variable @code{explicit-shell-file-name} in
2854 your @file{.emacs} file to point to its full file name, like this:
2857 (setq explicit-shell-file-name "d:/shells/bash.exe")
2860 If you don't know what shell does Emacs use, try the @kbd{M-!}
2861 command; if that works, put the following line into your
2865 (setq explicit-shell-file-name shell-file-name)
2868 @cindex Antivirus programs, and Shell Mode
2869 Some people have trouble with Shell Mode because of intrusive
2870 antivirus software; disabling the resident antivirus program solves
2871 the problems in those cases.
2873 @node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems
2874 @section Where is the termcap/terminfo entry for terminal type @samp{emacs}?
2877 @cindex Emacs entries for termcap/terminfo
2879 The termcap entry for terminal type @samp{emacs} is ordinarily put in
2880 the @samp{TERMCAP} environment variable of subshells. It may help in
2881 certain situations (e.g., using rlogin from shell buffer) to add an
2882 entry for @samp{emacs} to the system-wide termcap file. Here is a
2883 correct termcap entry for @samp{emacs}:
2889 To make a terminfo entry for @samp{emacs}, use @code{tic} or
2890 @code{captoinfo}. You need to generate
2891 @file{/usr/lib/terminfo/e/emacs}. It may work to simply copy
2892 @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
2894 Having a termcap/terminfo entry will not enable the use of full screen
2895 programs in shell buffers. Use @kbd{M-x terminal-emulator} for that
2898 A workaround to the problem of missing termcap/terminfo entries is to
2899 change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
2900 in your shell start up file. @code{csh} users could put this in their
2901 @file{.cshrc} files:
2904 if ("$term" == emacs) set term=dumb
2907 @node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems
2908 @section Why does Emacs spontaneously start displaying @samp{I-search:} and beeping?
2909 @cindex Spontaneous entry into isearch-mode
2910 @cindex isearch-mode, spontaneous entry into
2911 @cindex Beeping without obvious reason
2913 Your terminal (or something between your terminal and the computer) is
2914 sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving
2915 these characters and interpreting them as commands. (The @kbd{C-s}
2916 character normally invokes the @code{isearch-forward} command.) For
2917 possible solutions, see @ref{Handling C-s and C-q with flow control}.
2919 @node Problems talking to certain hosts, Errors with init files, Spontaneous entry into isearch-mode, Bugs and problems
2920 @section Why can't Emacs talk to certain hosts (or certain hostnames)?
2921 @cindex Hosts, Emacs cannot talk to
2922 @cindex @code{gethostbyname}, problematic version
2924 The problem may be that Emacs is linked with a wimpier version of
2925 @code{gethostbyname} than the rest of the programs on the machine. This
2926 is often manifested as a message on startup of ``X server not responding.
2927 Check your @samp{DISPLAY} environment variable.'' or a message of
2928 ``Unknown host'' from @code{open-network-stream}.
2930 On a Sun, this may be because Emacs had to be linked with the static C
2931 library. The version of @code{gethostbyname} in the static C library
2932 may only look in @file{/etc/hosts} and the NIS (YP) maps, while the
2933 version in the dynamic C library may be smart enough to check DNS in
2934 addition to or instead of NIS. On a Motorola Delta running System V
2935 R3.6, the version of @code{gethostbyname} in the standard library works,
2936 but the one that works with NIS doesn't (the one you get with -linet).
2937 Other operating systems have similar problems.
2944 Explicitly add the host you want to communicate with to @file{/etc/hosts}.
2947 Relink Emacs with this line in @file{src/config.h}:
2950 #define LIBS_SYSTEM -lresolv
2954 Replace @code{gethostbyname} and friends in @file{libc.a} with more
2955 useful versions such as the ones in @file{libresolv.a}. Then relink
2959 If you are actually running NIS, make sure that @code{ypbind} is
2960 properly told to do DNS lookups with the correct command line switch.
2964 @node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems
2965 @section Why does Emacs say @samp{Error in init file}?
2966 @cindex Error in @file{.emacs}
2967 @cindex Error in init file
2968 @cindex Init file, errors in
2969 @cindex @file{.emacs} file, errors in
2970 @cindex Debugging @file{.emacs} file
2972 An error occurred while loading either your @file{.emacs} file or the
2973 system-wide file @file{lisp/default.el}. Emacs 21.1 and later pops the
2974 @file{*Messages*} buffer, and puts there some additional information
2975 about the error, to provide some hints for debugging.
2977 For information on how to debug your @file{.emacs} file, see
2978 @ref{Debugging a customization file}.
2980 It may be the case that you need to load some package first, or use a
2981 hook that will be evaluated after the package is loaded. A common case
2982 of this is explained in @ref{Terminal setup code works after Emacs has
2985 @node Emacs ignores X resources, Emacs ignores frame parameters, Errors with init files, Bugs and problems
2986 @section Why does Emacs ignore my X resources (my .Xdefaults file)?
2987 @cindex X resources being ignored
2988 @cindex Ignored X resources
2989 @cindex @file{.Xdefaults}
2991 As of version 19, Emacs searches for X resources in the files specified
2992 by the following environment variables:
2996 @item @code{XFILESEARCHPATH}
2997 @item @code{XUSERFILESEARCHPATH}
2998 @item @code{XAPPLRESDIR}
3002 This emulates the functionality provided by programs written using the
3005 @code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
3006 of file names separated by colons. @code{XAPPLRESDIR} should be a list
3007 of directory names separated by colons.
3009 Emacs searches for X resources:
3014 specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
3017 then in the value of the @samp{XENVIRONMENT} environment variable,
3022 or if that is unset, in the file named
3023 @file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
3024 the name of the machine Emacs is running on),
3029 then in the screen-specific and server-wide resource properties provided
3035 or if those properties are unset, in the file named @file{~/.Xdefaults}
3041 then in the files listed in @samp{XUSERFILESEARCHPATH},
3046 or in files named @file{@var{lang}/Emacs} in directories listed in
3047 @samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
3048 environment variable), if the @samp{LANG} environment variable is set,
3050 or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
3052 or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
3055 or in @file{~/Emacs},
3060 then in the files listed in @code{XFILESEARCHPATH}.
3064 @node Emacs ignores frame parameters, Emacs takes a long time to visit files, Emacs ignores X resources, Bugs and problems
3065 @section Why don't my customizations of the frame parameters work?
3066 @cindex Frame parameters
3068 This probably happens because you have set the frame parameters in the
3069 variable @code{initial-frame-alist}. That variable holds parameters
3070 used only for the first frame created when Emacs starts. To customize
3071 the parameters of all frames, change the variable
3072 @code{default-frame-alist} instead.
3074 These two variables exist because many users customize the initial frame
3075 in a special way. For example, you could determine the position and
3076 size of the initial frame, but would like to control the geometry of the
3077 other frames by individually positioning each one of them.
3080 @node Emacs takes a long time to visit files, Editing files with $ in the name, Emacs ignores frame parameters, Bugs and problems
3081 @section Why does Emacs take 20 seconds to visit a file?
3082 @cindex Visiting files takes a long time
3083 @cindex Delay when visiting files
3084 @cindex Files, take a long time to visit
3086 Old versions of Emacs (i.e., versions before Emacs 20.x) often
3087 encountered this when the master lock file, @file{!!!SuperLock!!!}, has
3088 been left in the lock directory somehow. Delete it.
3090 @email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug
3091 where an exclusive create succeeds but returns an error status. This
3092 can cause the same problem. Since Emacs's file locking doesn't work
3093 over NFS anyway, the best solution is to recompile Emacs with
3094 @code{CLASH_DETECTION} undefined.
3096 @node Editing files with $ in the name, Shell mode loses the current directory, Emacs takes a long time to visit files, Bugs and problems
3097 @section How do I edit a file with a @samp{$} in its name?
3098 @cindex Editing files with @samp{$} in the name
3099 @cindex @samp{$} in file names
3100 @cindex File names containing @samp{$}, editing
3102 When entering a file name in the minibuffer, Emacs will attempt to expand
3103 a @samp{$} followed by a word as an environment variable. To suppress
3104 this behavior, type @kbd{$$} instead.
3106 @node Shell mode loses the current directory, Security risks with Emacs, Editing files with $ in the name, Bugs and problems
3107 @section Why does shell mode lose track of the shell's current directory?
3108 @cindex Current directory and @code{shell-mode}
3109 @cindex @code{shell-mode} and current directory
3110 @cindex Directory, current in @code{shell-mode}
3112 Emacs has no way of knowing when the shell actually changes its
3113 directory. This is an intrinsic limitation of Unix. So it tries to
3114 guess by recognizing @samp{cd} commands. If you type @kbd{cd} followed
3115 by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
3116 with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
3117 correctly guess the shell's new current directory. A huge variety of
3118 fixes and enhancements to shell mode for this problem have been written
3119 to handle this problem (@pxref{Finding a package with particular
3122 You can tell Emacs the shell's current directory with the command
3125 @node Security risks with Emacs, Dired claims that no file is on this line, Shell mode loses the current directory, Bugs and problems
3126 @section Are there any security risks in Emacs?
3127 @cindex Security with Emacs
3128 @cindex @samp{movemail} and security
3129 @cindex @code{file-local-variable} and security
3130 @cindex Synthetic X events and security
3131 @cindex X events and security
3136 The @file{movemail} incident. (No, this is not a risk.)
3138 In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
3139 chapter 4. The site at LBL had installed the @file{/etc/movemail}
3140 program setuid root. (As of version 19, @file{movemail} is in your
3141 architecture-specific directory; type @kbd{C-h v exec-directory
3142 @key{RET}} to see what it is.) Since @code{movemail} had not been
3143 designed for this situation, a security hole was created and users could
3144 get root privileges.
3146 @code{movemail} has since been changed so that this security hole will
3147 not exist, even if it is installed setuid root. However,
3148 @code{movemail} no longer needs to be installed setuid root, which
3149 should eliminate this particular risk.
3151 We have heard unverified reports that the 1988 Internet worm took
3152 advantage of this configuration problem.
3155 The @code{file-local-variable} feature. (Yes, a risk, but easy to
3158 There is an Emacs feature that allows the setting of local values for
3159 variables when editing a file by including specially formatted text near
3160 the end of the file. This feature also includes the ability to have
3161 arbitrary Emacs Lisp code evaluated when the file is visited.
3162 Obviously, there is a potential for Trojan horses to exploit this
3165 As of Emacs 22, Emacs has a list of local variables that are known to
3166 be safe to set. If a file tries to set any variable outside this
3167 list, it asks the user to confirm whether the variables should be set.
3168 You can also tell Emacs whether to allow the evaluation of Emacs Lisp
3169 code found at the bottom of files by setting the variable
3170 @code{enable-local-eval}.
3172 For more information, @inforef{File Variables, File Variables, emacs}.
3175 Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
3178 Emacs accepts synthetic X events generated by the @code{SendEvent}
3179 request as though they were regular events. As a result, if you are
3180 using the trivial host-based authentication, other users who can open X
3181 connections to your X workstation can make your Emacs process do
3182 anything, including run other processes with your privileges.
3184 The only fix for this is to prevent other users from being able to open
3185 X connections. The standard way to prevent this is to use a real
3186 authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using
3187 the @code{xauth} program has any effect, then you are probably using
3188 @samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior
3189 authentication method; ask your system administrator.
3191 If real authentication is not a possibility, you may be satisfied by
3192 just allowing hosts access for brief intervals while you start your X
3193 programs, then removing the access. This reduces the risk somewhat by
3194 narrowing the time window when hostile users would have access, but
3195 @emph{does not eliminate the risk}.
3197 On most computers running Unix and X, you enable and disable
3198 access using the @code{xhost} command. To allow all hosts access to
3206 at the shell prompt, which (on an HP machine, at least) produces the
3210 access control disabled, clients can connect from any host
3213 To deny all hosts access to your X server (except those explicitly
3214 allowed by name), use
3220 On the test HP computer, this command generated the following message:
3223 access control enabled, only authorized clients can connect
3228 @node Dired claims that no file is on this line, , Security risks with Emacs, Bugs and problems
3229 @section Dired says, @samp{no file on this line} when I try to do something.
3230 @cindex Dired does not see a file
3232 @c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
3234 Chances are you're using a localized version of Unix that doesn't use US
3235 date format in dired listings. You can check this by looking at dired
3236 listings or by typing @kbd{ls -l} to a shell and looking at the dates that
3239 Dired uses a regular expression to find the beginning of a file name.
3240 In a long Unix-style directory listing (@samp{ls -l}), the file name
3241 starts after the date. The regexp has thus been written to look for the
3242 date, the format of which can vary on non-US systems.
3244 There are two approaches to solving this. The first one involves
3245 setting things up so that @samp{ls -l} outputs US date format. This can
3246 be done by setting the locale. See your OS manual for more information.
3248 The second approach involves changing the regular expression used by
3249 dired, @code{directory-listing-before-filename-regexp}.
3251 @c ------------------------------------------------------------
3252 @node Compiling and installing Emacs, Finding Emacs and related packages, Bugs and problems, Top
3253 @chapter Compiling and installing Emacs
3254 @cindex Compiling and installing Emacs
3257 * Installing Emacs::
3259 * Problems building Emacs::
3260 * Linking with -lX11 fails::
3263 @node Installing Emacs, Updating Emacs, Compiling and installing Emacs, Compiling and installing Emacs
3264 @section How do I install Emacs?
3265 @cindex Installing Emacs
3266 @cindex Unix systems, installing Emacs on
3267 @cindex Downloading and installing Emacs
3268 @cindex Retrieving and installing Emacs
3269 @cindex Building Emacs from source
3270 @cindex Source code, building Emacs from
3271 @cindex Unpacking and installing Emacs
3273 This answer is meant for users of Unix and Unix-like systems. Users of
3274 other operating systems should see the series of questions beginning
3275 with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
3276 and binaries, and how to install Emacs on those systems.
3278 For Unix and Unix-like systems, the easiest way is often to compile it
3279 from scratch. You will need:
3284 Emacs sources. @xref{Current GNU distributions}, for a list of ftp sites
3285 that make them available. On @file{ftp.gnu.org}, the main GNU
3286 distribution site, sources are available as
3288 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-@value{VER}.tar.gz}
3290 The above will obviously change as new versions of Emacs come out. For
3291 instance, when Emacs 22.42 is released, it will most probably be
3294 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-22.42.tar.gz}
3296 Again, you should use one of the GNU mirror sites (see @ref{Current GNU
3297 distributions}, and adjust the URL accordingly) so as to reduce load on
3301 @code{gzip}, the GNU compression utility. You can get @code{gzip} via
3302 anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile
3303 and install without much trouble on most systems. Once you have
3304 retrieved the Emacs sources, you will probably be able to uncompress
3305 them with the command
3308 gunzip --verbose emacs-@value{VER}.tar.gz
3312 changing the Emacs version (@value{VER}), as necessary. Once
3313 @code{gunzip} has finished doing its job, a file by the name of
3314 @file{emacs-@value{VER}.tar} should be in your build directory.
3317 @code{tar}, the @dfn{tape archiving} program, which moves multiple files
3318 into and out of archive files, or @dfn{tarfiles}. All of the files
3319 comprising the Emacs source come in a single tarfile, and must be
3320 extracted using @code{tar} before you can build Emacs. Typically, the
3321 extraction command would look like
3324 tar -xvvf emacs-@value{VER}.tar
3328 The @samp{x} indicates that we want to extract files from this tarfile,
3329 the two @samp{v}s force verbose output, and the @samp{f} tells
3330 @code{tar} to use a disk file, rather than one on the tape drive.
3332 If you're using GNU @code{tar} (available at mirrors of
3333 @file{ftp.gnu.org}), you can combine this step and the previous one by
3337 tar -zxvvf emacs-@value{VER}.tar.gz
3341 The additional @samp{z} at the beginning of the options list tells GNU
3342 @code{tar} to uncompress the file with @code{gunzip} before extracting
3343 the tarfile's components.
3347 At this point, the Emacs sources (all 70+ megabytes of them) should be
3348 sitting in a directory called @file{emacs-@value{VER}}. On most common
3349 Unix and Unix-like systems, you should be able to compile Emacs (with X
3350 Window system support) with the following commands:
3353 cd emacs-@value{VER} # change directory to emacs-@value{VER}
3354 ./configure # configure Emacs for your particular system
3355 make # use Makefile to build components, then Emacs
3358 If the @code{make} completes successfully, the odds are fairly good that
3359 the build has gone well. (@xref{Problems building Emacs}, if you weren't
3362 By default, Emacs is installed in the following directories:
3365 @item /usr/local/bin
3368 @item /usr/local/share/emacs/@value{VER}
3369 Lisp code and support files.
3371 @item /usr/local/info
3375 To install files in those default directories, become the superuser and
3382 Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
3383 and any Emacs Info files that might be in @file{/usr/local/info}.
3385 Much more verbose instructions (with many more hints and suggestions)
3386 come with the Emacs sources, in the file @file{INSTALL}.
3388 @node Updating Emacs, Problems building Emacs, Installing Emacs, Compiling and installing Emacs
3389 @section How do I update Emacs to the latest version?
3390 @cindex Updating Emacs
3392 @xref{Installing Emacs}, and follow the instructions there for
3395 Most files are placed in version-specific directories. Emacs
3396 @value{VER}, for instance, places files in
3397 @file{/usr/local/share/emacs/@value{VER}}.
3399 Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs
3400 binary) and documentation in @file{/usr/local/info}. Back up these
3401 files before you upgrade, and you shouldn't have too much trouble.
3403 @node Problems building Emacs, Linking with -lX11 fails, Updating Emacs, Compiling and installing Emacs
3404 @section What should I do if I have trouble building Emacs?
3405 @cindex Problems building Emacs
3406 @cindex Errors when building Emacs
3408 First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
3409 source) to see if there is already a solution for your problem. Next,
3410 look for other questions in this FAQ that have to do with Emacs
3411 installation and compilation problems.
3413 If you'd like to have someone look at your problem and help solve it,
3414 see @ref{Help installing Emacs}.
3416 If you cannot find a solution in the documentation, send a message to
3417 @email{bug-gnu-emacs@@gnu.org}.
3419 Please don't post it to @uref{news:gnu.emacs.help} or send e-mail to
3420 @email{help-gnu-emacs@@gnu.org}. For further guidelines, see
3421 @ref{Guidelines for newsgroup postings} and @ref{Reporting bugs}.
3423 @node Linking with -lX11 fails, , Problems building Emacs, Compiling and installing Emacs
3424 @section Why does linking Emacs with -lX11 fail?
3425 @cindex Linking with -lX11 fails
3426 @cindex lX11, linking fails with
3428 Emacs needs to be linked with the static version of the X11 library,
3429 @file{libX11.a}. This may be missing.
3431 On OpenWindows, you may need to use @code{add_services} to add the
3432 ``OpenWindows Programmers'' optional software category from the CD-ROM.
3434 On HP-UX 8.0, you may need to run @code{update} again to load the
3435 X11-PRG ``fileset.'' This may be missing even if you specified ``all
3436 filesets'' the first time. If @file{libcurses.a} is missing, you may
3437 need to load the ``Berkeley Development Option.''
3439 @email{zoo@@armadillo.com, David Zuhn} says that MIT X builds shared
3440 libraries by default, and only shared libraries, on those platforms that
3441 support them. These shared libraries can't be used when undumping
3442 @code{temacs} (the last stage of the Emacs build process). To get
3443 regular libraries in addition to shared libraries, add this to
3447 #define ForceNormalLib YES
3450 Other systems may have similar problems. You can always define
3451 @code{CANNOT_DUMP} and link with the shared libraries instead.
3453 @cindex X Menus don't work
3454 To get the Xmenu stuff to work, you need to find a copy of MIT's
3457 @c ------------------------------------------------------------
3458 @node Finding Emacs and related packages, Major packages and programs, Compiling and installing Emacs, Top
3459 @chapter Finding Emacs and related packages
3460 @cindex Finding Emacs and related packages
3463 * Finding Emacs on the Internet::
3464 * Finding a package with particular functionality::
3465 * Packages that do not come with Emacs::
3466 * Current GNU distributions::
3467 * Difference between Emacs and XEmacs::
3468 * Emacs for MS-DOS::
3469 * Emacs for Windows::
3471 * Emacs for Atari ST::
3472 * Emacs for the Amiga ::
3473 * Emacs for NeXTSTEP::
3474 * Emacs for Apple computers::
3475 * Emacs for VMS and DECwindows::
3476 * Modes for various languages::
3479 @node Finding Emacs on the Internet, Finding a package with particular functionality, Finding Emacs and related packages, Finding Emacs and related packages
3480 @section Where can I get Emacs on the net (or by snail mail)?
3481 @cindex Finding Emacs on the Internet
3482 @cindex Snail mail, ordering Emacs via
3483 @cindex Postal service, ordering Emacs via
3484 @cindex Distribution, retrieving Emacs
3485 @cindex Internet, retrieving from
3487 Look in the files @file{etc/DISTRIB} and @file{etc/FTP} for
3488 information on nearby archive sites. If you don't already have Emacs,
3489 see @ref{Informational files for Emacs}, for how to get these files.
3491 @xref{Installing Emacs}, for information on how to obtain and build the latest
3492 version of Emacs, and see @ref{Current GNU distributions}, for a list of
3493 archive sites that make GNU software available.
3495 @node Finding a package with particular functionality, Packages that do not come with Emacs, Finding Emacs on the Internet, Finding Emacs and related packages
3496 @section How do I find a Emacs Lisp package that does XXX?
3497 @cindex Package, finding
3498 @cindex Finding an Emacs Lisp package
3499 @cindex Functionality, finding a particular package
3501 First of all, you should check to make sure that the package isn't
3502 already available. For example, typing @kbd{M-x apropos @key{RET}
3503 wordstar @key{RET}} lists all functions and variables containing the
3504 string @samp{wordstar}.
3506 It is also possible that the package is on your system, but has not been
3507 loaded. To see which packages are available for loading, look through
3508 your computer's lisp directory (@pxref{File-name conventions}). The Lisp
3509 source to most packages contains a short description of how they
3510 should be loaded, invoked, and configured---so before you use or
3511 modify a Lisp package, see if the author has provided any hints in the
3514 The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
3515 the constituent Emacs packages.
3517 For advice on how to find extra packages that are not part of Emacs,
3518 see @ref{Packages that do not come with Emacs}.
3520 @node Packages that do not come with Emacs, Current GNU distributions, Finding a package with particular functionality, Finding Emacs and related packages
3521 @section Where can I get Emacs Lisp packages that don't come with Emacs?
3522 @cindex Unbundled packages
3523 @cindex Finding other packages
3524 @cindex Lisp packages that do not come with Emacs
3525 @cindex Packages, those that do not come with Emacs
3526 @cindex Emacs Lisp List
3527 @cindex Emacs Lisp Archive
3529 @uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.html, The Emacs Lisp
3530 List (ELL)}, maintained by @email{stephen@@anc.ed.ac.uk, Stephen Eglen},
3531 aims to provide one compact list with links to all of the current Emacs
3532 Lisp files on the Internet. The ELL can be browsed over the web, or
3533 from Emacs with @uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.el,
3534 the @file{ell} package}.
3536 Many authors post their packages to the @uref{news:gnu.emacs.sources,
3537 Emacs sources newsgroup}. You can search the archives of this
3538 group with @uref{http://groups.google.com/group/gnu.emacs.sources, Google},
3539 or @uref{http://dir.gmane.org/gmane.emacs.sources, Gmane}, for example.
3541 Several packages are stored in
3542 @uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}.
3544 For a long time, the Emacs Lisp Archive provided a central repository
3545 for Emacs packages. Sadly, it has not been active for some time,
3546 although you can still access the old files at
3548 @uref{http://www.club.cc.cmu.edu/pub/gnu/elisp-archive/}
3550 Read the file @file{etc/MORE.STUFF} for more information about
3553 @node Current GNU distributions, Difference between Emacs and XEmacs, Packages that do not come with Emacs, Finding Emacs and related packages
3554 @section Where can I get other up-to-date GNU stuff?
3555 @cindex Current GNU distributions
3556 @cindex Sources for current GNU distributions
3557 @cindex Stuff, current GNU
3558 @cindex Up-to-date GNU stuff
3559 @cindex Finding current GNU software
3560 @cindex Official GNU software sites
3562 The most up-to-date official GNU software is normally kept at
3564 @uref{ftp://ftp.gnu.org/pub/gnu}
3566 Read the files @file{etc/DISTRIB} and @file{etc/FTP} for more
3569 A list of sites mirroring @samp{ftp.gnu.org} can be found at
3571 @uref{http://www.gnu.org/order/ftp.html}
3573 @node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages
3574 @section What is the difference between Emacs and XEmacs (formerly Lucid Emacs)?
3576 @cindex Difference Emacs and XEmacs
3580 XEmacs is a branch version of Emacs. It was first called Lucid Emacs,
3581 and was initially derived from a prerelease version of Emacs 19. In
3582 this FAQ, we use the name ``Emacs'' only for the official version.
3584 Emacs and XEmacs each come with Lisp packages that are lacking in the
3585 other. The two versions have some significant differences at the Lisp
3586 programming level. Their current features are roughly comparable,
3587 though the support for some operating systems, character sets and
3588 specific packages might be quite different.
3590 Some XEmacs code has been contributed to Emacs, and we would like to
3591 use other parts, but the earlier XEmacs maintainers did not always
3592 keep track of the authors of contributed code, which makes it
3593 impossible for the FSF to get copyright papers signed for that code.
3594 (The FSF requires these papers for all the code included in the Emacs
3595 release, aside from generic C support packages that retain their
3596 separate identity and are not integrated into the code of Emacs
3599 If you want to talk about these two versions and distinguish them,
3600 please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs''
3601 with ``GNU Emacs'' would be misleading, since XEmacs too has its
3602 origin in the work of the GNU Project. Terms such as ``Emacsen'' and
3603 ``(X)Emacs'' are not wrong, but they are not very clear, so it
3604 is better to write ``Emacs and XEmacs.''
3606 @node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages
3607 @section Where can I get Emacs for my PC running MS-DOS?
3608 @cindex MS-DOS, Emacs for
3609 @cindex DOS, Emacs for
3610 @cindex Compiling Emacs for DOS
3611 @cindex Emacs for MS-DOS
3612 @cindex Tools needed to compile Emacs under DOS
3614 A pre-built binary distribution of Emacs is available from the
3615 SimTel.NET archives. This version apparently works under MS-DOS and
3616 Windows (3.X, 9X, ME, NT, and 2000) and supports long file names under
3617 Windows 9X, Windows ME, and Windows 2000. More information is available
3620 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/emacs.README}
3622 The binary itself is available in the files @file{em*.zip} in the
3625 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/}
3627 If you prefer to compile Emacs for yourself, you can do so with the
3628 current distribution directly. You will need a 386 (or
3629 better) processor, and to be running MS-DOS 3.0 or later. According to
3630 @email{eliz@@gnu.org, Eli Zaretskii} and
3631 @email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the
3637 DJGPP version 1.12 maint 1 or later. Djgpp 2.0 or later is
3638 recommended, since 1.x is very old an unmaintained. Djgpp 2 supports
3639 long file names on Windows 9X/ME/2K.
3641 You can get the latest release of DJGPP by retrieving all of
3644 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2*}
3646 @item Unpacking program
3647 The easiest way is to use @code{djtar} which comes with DJGPP v2.x,
3648 because it can open gzip'ed tarfiles (i.e., those ending with
3649 @file{.tar.gz}) in one step. @code{Djtar} comes in
3650 @file{djdev@var{nnn}.zip} archive (where @var{nnn} is the DJGPP version
3651 number), from the URL mentioned above.
3653 @strong{Warning!} Do @strong{not} use the popular WinZip program to
3654 unpack the Emacs distribution! WinZip is known to corrupt some of the
3655 files by converting them to the DOS CR-LF format, it doesn't always
3656 preserve the directory structure recorded in the compressed Emacs
3657 archive, and commits other atrocities. Some of these problems could
3658 actually prevent Emacs from building successfully!
3660 @item make, mv, sed, and rm
3661 All of these utilities are available at
3663 @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu}
3665 16-bit utilities can be found in GNUish, at
3667 @uref{http://www.simtel.net/pub/gnuish/}
3670 (@code{mv} and @code{rm} are in the Fileutils package, @code{sed} and
3671 @code{make} are each one in a separate package named after them.)
3675 The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
3676 directory of the Emacs sources contains some additional information
3677 regarding Emacs under MS-DOS.
3679 For a list of other MS-DOS implementations of Emacs (and Emacs
3680 look-alikes), consult the list of ``Emacs implementations and literature,''
3683 @uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}
3685 Note that while many of these programs look similar to Emacs, they often
3686 lack certain features, such as the Emacs Lisp extension language.
3688 @node Emacs for Windows, Emacs for OS/2, Emacs for MS-DOS, Finding Emacs and related packages
3689 @section Where can I get Emacs for Microsoft Windows?
3690 @cindex FAQ for NT Emacs
3691 @cindex Emacs for MS-Windows
3692 @cindex Microsoft Windows, Emacs for
3693 @cindex Windows 9X, ME, NT, 2K, and CE, Emacs for
3695 For information on Emacs for Windows 95 and NT, read the FAQ produced by
3696 @email{voelker@@cs.washington.edu, Geoff Voelker} and currently maintained
3697 by @email{ramprasad@@gnu.org, Ramprasad B}, available at
3699 @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html}
3701 @xref{Emacs for MS-DOS}, for Windows 3.1.
3703 A port of Emacs 20.7 for Windows CE, based on NTEmacs, is available at
3705 @uref{http://www.rainer-keuchel.de/software.html}
3708 This port was done by @email{coyxc@@rainer-keuchel.de, Rainer Keuchel},
3709 and supports all Emacs features except async subprocesses and menus.
3710 You will need MSVC 6.0 and a Windows CE SDK to build this port.
3712 @node Emacs for OS/2, Emacs for Atari ST, Emacs for Windows, Finding Emacs and related packages
3713 @section Where can I get Emacs for my PC running OS/2?
3714 @cindex OS/2, Emacs for
3716 Emacs 20.6 is ported for emx on OS/2 2.0 or 2.1, and is available at
3718 @uref{ftp://hobbes.nmsu.edu/pub/os2/apps/editors/emacs/}
3723 @uref{http://www.dotemacs.de/os2/emacs.html}
3725 Instructions for installation, basic setup, and other useful information
3726 for OS/2 users of Emacs can be found at
3728 @uref{http://home.snafu.de/ohei/emacs/emacs206-os2.html}
3730 @node Emacs for Atari ST, Emacs for the Amiga , Emacs for OS/2, Finding Emacs and related packages
3731 @section Where can I get Emacs for my Atari ST?
3732 @cindex Atari ST, Emacs for
3733 @cindex TOS, Emacs for
3735 Roland Sch@"auble reports that Emacs 18.58 running on plain TOS and MiNT
3737 @uref{ftp://atari.archive.umich.edu/Editors/Emacs-18-58/1858b-d3.zoo}.
3739 @node Emacs for the Amiga , Emacs for NeXTSTEP, Emacs for Atari ST, Finding Emacs and related packages
3740 @section Where can I get Emacs for my Amiga?
3741 @cindex Amiga, Emacs for
3743 The files you need are available at
3745 @uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/}
3747 @email{dgilbert@@gamiga.guelphnet.dweomer.org, David Gilbert} has released a
3748 beta version of Emacs 19.25 for the Amiga. You can get the binary at
3750 @uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/a2.0bEmacs-bin.lha}
3752 @node Emacs for NeXTSTEP, Emacs for Apple computers, Emacs for the Amiga , Finding Emacs and related packages
3753 @section Where can I get Emacs for NeXTSTEP?
3754 @cindex NeXTSTEP, Emacs for
3756 Emacs.app is a NeXTSTEP version of Emacs 19.34 which supports colors,
3757 menus, and multiple frames. You can get it from
3759 @uref{ftp://next-ftp.peak.org/pub/next-ftp/next/apps/emacs/Emacs_for_NeXTstep.4.20a1.NIHS.b.tar.gz}
3761 @node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages
3762 @section Where can I get Emacs for my Apple computer?
3763 @cindex Apple computers, Emacs for
3764 @cindex Macintosh, Emacs for
3766 Beginning with version 21.1, the Macintosh is supported in the official
3767 Emacs distribution; see the files @file{mac/README} and
3768 @file{mac/INSTALL} in the Emacs distribution for build instructions.
3770 Beginning with version 22.1, Emacs supports Mac OS X natively.
3772 @node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages
3773 @section Where do I get Emacs that runs on VMS under DECwindows?
3774 @cindex DECwindows, Emacs for
3775 @cindex VMS, Emacs for
3777 Up-to-date information about GNU software (including Emacs) for VMS is
3778 available at @uref{http://www.lp.se/gnu-vms/}.
3780 @node Modes for various languages, , Emacs for VMS and DECwindows, Finding Emacs and related packages
3781 @section Where can I get modes for Lex, Yacc/Bison, Bourne shell, csh, C@t{++}, Objective-C, Pascal, Java, and Awk?
3782 @cindex Awk, mode for
3783 @cindex @code{awk-mode}
3784 @cindex Bison, mode for
3785 @cindex Bourne Shell, mode for
3786 @cindex C@t{++}, mode for
3787 @cindex Java, mode for
3789 @cindex Objective-C, mode for
3790 @cindex @code{pascal-mode}
3793 @cindex @file{csh} mode
3794 @cindex @code{sh-mode}
3795 @cindex @code{cc-mode}
3797 Most of these modes are now available in standard Emacs distribution.
3798 To get additional modes, see @ref{Finding a package with particular
3801 Barry Warsaw's @code{cc-mode} now works for C, C@t{++}, Objective-C, and
3802 Java code. It is distributed with Emacs, but has
3803 @uref{http://cc-mode.sourceforge.net/, its own homepage}.
3805 @c ------------------------------------------------------------
3806 @node Major packages and programs, Key bindings, Finding Emacs and related packages, Top
3807 @chapter Major packages and programs
3808 @cindex Major packages and programs
3825 @node VM, Supercite, Major packages and programs, Major packages and programs
3826 @section VM (View Mail) --- another mail reader within Emacs, with MIME support
3828 @cindex Alternative mail software
3830 @cindex E-mail reader, VM
3835 @email{kyle_jones@@wonderworks.com, Kyle Jones}
3837 @item Latest version
3841 @uref{ftp://ftp.wonderworks.com/pub/vm/vm.tar.gz}
3843 @item Informational newsgroup
3844 @uref{news:gnu.emacs.vm.info}@*
3846 @item Bug reports newsgroup
3847 @uref{news:gnu.emacs.vm.bug}@*
3848 Or send reports to @email{bug-vm@@wonderworks.com}
3851 VM 7 works well with Emacs 21 and Emacs 22. Older versions of VM
3852 suitable for use with older versions of Emacs are available from
3853 @uref{ftp://ftp.wonderworks.com/pub/vm/, the same FTP site}.
3856 @node Supercite, Calc, VM, Major packages and programs
3857 @section Supercite --- mail and news citation package within Emacs
3860 @cindex Mail and news citations
3861 @cindex News and mail citations
3862 @cindex Citations in mail and news
3867 @email{barry@@python.org, Barry Warsaw}
3869 @item Latest version
3870 3.54 (comes bundled with Emacs since version 20)
3873 @uref{http://www.python.org/emacs/supercite.tar.gz}
3876 Subscription requests to @email{supercite-request@@python.org}@*
3877 Submissions @email{supercite@@python.org}
3881 Superyank is an old version of Supercite.
3883 @node Calc, VIPER, Supercite, Major packages and programs
3884 @section Calc --- poor man's Mathematica within Emacs
3885 @cindex Programmable calculator
3887 @cindex Mathematical package
3892 @email{daveg@@csvax.cs.caltech.edu, Dave Gillespie}
3894 @item Latest version
3895 2.1 (part of Emacs since version 22.1)
3898 No separate distribution outside of Emacs. Older versions
3899 are available at @uref{ftp://ftp.gnu.org/pub/gnu/calc/}.
3903 Note that Calc 2.02f needs patching to work with Emacs 21 and later.
3905 @cindex @code{calculator}, a package
3906 Emacs 21.1 and later comes with a package called @file{calculator.el}.
3907 It doesn't support all the mathematical wizardry offered by Calc, such
3908 as matrices, special functions, and statistics, but is more than
3909 adequate as a replacement for @code{xcalc} and similar programs.
3911 @node VIPER, AUCTeX, Calc, Major packages and programs
3912 @section VIPER --- @code{vi} emulation for Emacs
3913 @cindex @code{vi} emulation
3915 @cindex Emulation of @code{vi}
3917 Since Emacs 19.29, the preferred @code{vi} emulation in Emacs is VIPER
3918 (@kbd{M-x viper-mode @key{RET}}), which comes with Emacs. It extends
3919 and supersedes VIP (including VIP 4.3) and provides @code{vi} emulation
3920 at several levels, from one that closely follows @code{vi} to one that
3921 departs from @code{vi} in several significant ways.
3923 For Emacs 19.28 and earlier, the following version of VIP is generally
3924 better than the one distributed with Emacs:
3928 @email{sane@@cs.uiuc.edu, Aamod Sane}
3930 @item Latest version
3934 @uref{ftp://www.club.cc.cmu.edu/pub/gnu/elisp-archive/modes/vip-mode.tar.Z}
3938 @node AUCTeX, BBDB, VIPER, Major packages and programs
3939 @section AUC@TeX{} --- enhanced @TeX{} modes with debugging facilities
3940 @cindex Mode for @TeX{}
3942 @cindex AUC@TeX{} mode for editing @TeX{}
3943 @cindex Writing and debugging @TeX{}
3945 AUC@TeX{} is a set of sophisticated major modes for @TeX{}, LaTeX,
3946 ConTeXt, and Texinfo offering context-sensitive syntax highlighting,
3947 indentation, formatting and folding, macro completion, @TeX{} shell
3948 functionality, and debugging. Be also sure to check out
3949 @ref{Introduction, RefTeX, Introduction, reftex, Ref@TeX{} User Manual}.
3950 Current versions of AUC@TeX{} include the
3951 @uref{http://www.gnu.org/software/auctex/preview-latex,preview-latex}
3952 package for WYSIWYG previews of various LaTeX constructs in the Emacs
3958 @email{krab@@iesd.auc.dk, Kresten Krab Thorup}, @*
3959 @email{abraham@@dina.kvl.dk, Per Abrahamsen}, @* and others.
3962 @email{dak@@gnu.org, David Kastrup}
3964 @item Latest version
3968 @uref{ftp://ftp.gnu.org/pub/gnu/auctex/}
3971 @uref{http://www.gnu.org/software/auctex/}
3974 Subscription requests to @email{auctex-request@@gnu.org}@*
3975 Submissions to @email{auctex@@gnu.org}
3979 @node BBDB, Ispell, AUCTeX, Major packages and programs
3980 @section BBDB --- personal Info Rolodex integrated with mail/news readers
3982 @cindex Rolodex-like functionality
3983 @cindex Integrated contact database
3984 @cindex Contact database
3985 @cindex Big Brother Database
3986 @cindex Address book
3991 @email{waider@@waider.ie, Ronan Waide}
3993 @item Latest version
3997 @uref{http://bbdb.sourceforge.net/}
4000 Subscription requests to @email{bbdb-info-request@@lists.sourceforge.net}@*
4001 Submissions to @email{bbdb-info@@lists.sourceforge.net}@*
4002 Release announcements: @email{bbdb-announce-request@@lists.sourceforge.net}
4006 @node Ispell, Emacs/W3, BBDB, Major packages and programs
4007 @section Ispell --- spell checker in C with interface for Emacs
4008 @cindex Spell-checker
4009 @cindex Checking spelling
4015 @email{geoff@@cs.hmc.edu, Geoff Kuenning}
4017 @item Latest version
4021 @uref{http://fmg-www.cs.ucla.edu/geoff/tars/ispell-3.3.02.tar.gz}@*
4024 @uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
4028 This Ispell program is distinct from GNU Ispell 4.0. GNU Ispell 4.0 is
4029 no longer a supported product.
4031 @node Emacs/W3, EDB, Ispell, Major packages and programs
4032 @section Emacs/W3 --- A World Wide Web browser inside of Emacs
4035 @cindex HTML browser in Emacs
4036 @cindex @code{w3-mode}
4041 @email{wmperry@@gnu.org, Bill Perry}
4044 Emacs/W3 needs a maintainer. It has lain dormant for several years. If
4045 you would like to take over the project, please contact
4046 @email{maintainers@@gnu.org}.
4048 @item Latest version
4052 @uref{http://savannah.gnu.org/projects/w3}
4055 Receive announcements from @email{w3-announce@@gnu.org}@*
4056 Help to develop Emacs/W3 at @email{w3-dev@@gnu.org}
4060 @node EDB, Mailcrypt, Emacs/W3, Major packages and programs
4061 @section EDB --- Database program for Emacs; replaces forms editing modes
4068 @email{mernst@@theory.lcs.mit.edu, Michael Ernst}
4070 @item Latest version
4074 @uref{ftp://theory.lcs.mit.edu/pub/emacs/edb}
4078 @node Mailcrypt, JDE, EDB, Major packages and programs
4079 @section Mailcrypt --- PGP interface within Emacs mail and news
4082 @cindex Interface to PGP from Emacs mail and news
4083 @cindex News, interface to PGP from
4084 @cindex Mail, interface to PGP from
4085 @cindex Encryption software, interface to
4090 @email{patl@@lcs.mit.edu, Patrick J. LoPresti} and
4091 @email{jin@@atype.com, Jin S. Choi}
4094 @email{warner-mailcrypt@@lothar.com, Brian Warner}
4096 @item Latest version
4100 @uref{http://dl.sourceforge.net/sourceforge/mailcrypt/mailcrypt-3.5.8.tar.gz}
4103 @uref{http://mailcrypt.sourceforge.net/}
4107 Note that a new package called PGG is bundled with Emacs starting with
4108 version 22.1. It is a modern interface to various PGP implementations,
4109 including @uref{http://www.gnupg.org/, The GNU Privacy Guard} and
4110 supports symmetric encryption.
4112 @node JDE, Patch, Mailcrypt, Major packages and programs
4113 @section JDE --- Integrated development environment for Java
4114 @cindex Java development environment
4115 @cindex Integrated Java development environment
4121 @email{paulk@@mathworks.com, Paul Kinnucan}
4123 @item Latest version
4127 @uref{http://jdee.sunsite.dk/}
4130 Subscription requests to @email{jde-subscribe@@sunsite.dk}@*
4131 Receive announcements from @email{jde-announce-subscribe@@sunsite.dk}
4135 @node Patch, , JDE, Major packages and programs
4136 @section Patch --- program to apply ``diffs'' for updating files
4137 @cindex Updating files with diffs
4138 @cindex Patching source files with diffs
4139 @cindex Diffs and patching
4140 @cindex @file{patch}
4145 @email{lwall@@wall.org, Larry Wall} (with GNU modifications)
4147 @item Latest version
4151 @xref{Current GNU distributions}.
4155 @c ------------------------------------------------------------
4156 @node Key bindings, Alternate character sets, Major packages and programs, Top
4157 @chapter Key bindings
4158 @cindex Key bindings
4161 * Binding keys to commands::
4162 * Invalid prefix characters::
4163 * Terminal setup code works after Emacs has begun::
4164 * Using function keys under X::
4165 * Working with function and arrow keys::
4166 * X key translations for Emacs::
4167 * Handling C-s and C-q with flow control::
4168 * Binding C-s and C-q::
4169 * Backspace invokes help::
4170 * stty and Backspace key::
4172 * Producing C-XXX with the keyboard::
4175 * Compose Character::
4176 * Binding combinations of modifiers and function keys::
4177 * Meta key does not work in xterm::
4178 * ExtendChar key does not work as Meta::
4179 * SPC no longer completes file names::
4182 @node Binding keys to commands, Invalid prefix characters, Key bindings, Key bindings
4183 @section How do I bind keys (including function keys) to commands?
4184 @cindex Binding keys to commands
4185 @cindex Keys, binding to commands
4186 @cindex Commands, binding keys to
4188 Keys can be bound to commands either interactively or in your
4189 @file{.emacs} file. To interactively bind keys for all modes, type
4190 @kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
4192 To bind a key just in the current major mode, type @kbd{M-x
4193 local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
4195 @inforef{Key Bindings, Key Bindings, emacs}, for further details.
4197 To make the process of binding keys interactively easier, use the
4198 following ``trick'': First bind the key interactively, then immediately
4199 type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed
4200 to bind the key is in the kill ring, and can be yanked into your
4201 @file{.emacs} file. If the key binding is global, no changes to the
4202 command are required. For example,
4205 (global-set-key (quote [f1]) (quote help-for-help))
4209 can be placed directly into the @file{.emacs} file. If the key binding is
4210 local, the command is used in conjunction with the @samp{add-hook} function.
4211 For example, in TeX mode, a local binding might be
4214 (add-hook 'tex-mode-hook
4216 (local-set-key (quote [f1]) (quote help-for-help))))
4223 Control characters in key sequences, in the form yanked from the kill
4224 ring are given in their graphic form---i.e., @key{CTRL} is shown as
4225 @samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may want
4226 to convert these into their vector or string forms.
4229 If a prefix key of the character sequence to be bound is already
4230 bound as a complete key, then you must unbind it before the new
4231 binding. For example, if @kbd{ESC @{} is previously bound:
4234 (global-unset-key [?\e ?@{]) ;; or
4235 (local-unset-key [?\e ?@{])
4239 Aside from commands and ``lambda lists,'' a vector or string also
4240 can be bound to a key and thus treated as a macro. For example:
4243 (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or
4244 (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
4249 @node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings
4250 @section Why does Emacs say @samp{Key sequence XXX uses invalid prefix characters}?
4251 @cindex Prefix characters, invalid
4252 @cindex Invalid prefix characters
4253 @cindex Misspecified key sequences
4255 Usually, one of two things has happened. In one case, the control
4256 character in the key sequence has been misspecified (e.g. @samp{C-f}
4257 used instead of @samp{\C-f} within a Lisp expression). In the other
4258 case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
4259 was already bound as a @dfn{complete key}. Historically, the @samp{ESC [}
4260 prefix was usually the problem, in which case you should evaluate either
4261 of these forms before attempting to bind the key sequence:
4264 (global-unset-key [?\e ?[]) ;; or
4265 (global-unset-key "\e[")
4268 @node Terminal setup code works after Emacs has begun, Using function keys under X, Invalid prefix characters, Key bindings
4269 @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?
4270 @cindex Terminal setup code in @file{.emacs}
4272 During startup, Emacs initializes itself according to a given code/file
4273 order. If some of the code executed in your @file{.emacs} file needs to
4274 be postponed until the initial terminal or window-system setup code has
4275 been executed but is not, then you will experience this problem (this
4276 code/file execution order is not enforced after startup).
4278 To postpone the execution of Emacs Lisp code until after terminal or
4279 window-system setup, treat the code as a @dfn{lambda list} and set the
4280 value of either the @code{term-setup-hook} or @code{window-setup-hook}
4281 variable to this lambda function. For example,
4284 (add-hook 'term-setup-hook
4286 (when (string-match "\\`vt220" (or (getenv "TERM") ""))
4287 ;; Make vt220's "Do" key behave like M-x:
4288 (global-set-key [do] 'execute-extended-command))))
4291 For information on what Emacs does every time it is started, see the
4292 @file{lisp/startup.el} file.
4294 @node Using function keys under X, Working with function and arrow keys, Terminal setup code works after Emacs has begun, Key bindings
4295 @section How do I use function keys under X?
4296 @cindex Function keys
4297 @cindex X Window System and function keys
4298 @cindex Binding function keys
4300 With Emacs 19, functions keys under X are bound like any other key. @xref{Binding keys to commands}, for details.
4302 @node Working with function and arrow keys, X key translations for Emacs, Using function keys under X, Key bindings
4303 @section How do I tell what characters or symbols my function or arrow keys emit?
4304 @cindex Working with arrow keys
4305 @cindex Arrow keys, symbols generated by
4306 @cindex Working with function keys
4307 @cindex Function keys, symbols generated by
4308 @cindex Symbols generated by function keys
4310 Type @kbd{C-h c} then the function or arrow keys. The command will
4311 return either a function key symbol or character sequence (see the
4312 Emacs on-line documentation for an explanation). This works for other
4315 @node X key translations for Emacs, Handling C-s and C-q with flow control, Working with function and arrow keys, Key bindings
4316 @section How do I set the X key ``translations'' for Emacs?
4317 @cindex X key translations
4318 @cindex Key translations under X
4319 @cindex Translations for keys under X
4321 Emacs is not written using the Xt library by default, so there are no
4322 ``translations'' to be set. (We aren't sure how to set such translations
4323 if you do build Emacs with Xt; please let us know if you've done this!)
4325 The only way to affect the behavior of keys within Emacs is through
4326 @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs). The
4327 @code{define-key} command should be used in conjunction with the
4328 @code{function-key-map} map. For instance,
4331 (define-key function-key-map [M-@key{TAB}] [?\M-\t])
4335 defines the @kbd{M-@key{TAB}} key sequence.
4337 @node Handling C-s and C-q with flow control, Binding C-s and C-q, X key translations for Emacs, Key bindings
4338 @section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control?
4339 @cindex Flow control, @kbd{C-s} and @kbd{C-q} with
4340 @cindex @kbd{C-s} and @kbd{C-q} with flow control
4342 @kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol.
4343 This messes things up when you're using Emacs over a serial line,
4344 because Emacs binds these keys to commands by default. Because Emacs
4345 won't honor them as flow control characters, too many of these
4346 characters are not passed on and overwhelm output buffers. Sometimes,
4347 intermediate software using XON/XOFF flow control will prevent Emacs
4348 from ever seeing @kbd{C-s} and @kbd{C-q}.
4355 Disable the use of @kbd{C-s} and @kbd{C-q} for flow control.
4357 You need to determine the cause of the flow control.
4364 Your terminal may use XON/XOFF flow control to have time to display
4365 all the characters it receives. For example, VT series terminals do
4366 this. It may be possible to turn this off from a setup menu. For
4367 example, on a VT220 you may select ``No XOFF'' in the setup menu. This
4368 is also true for some terminal emulation programs on PCs.
4370 When you turn off flow control at the terminal, you will also need to
4371 turn it off at the other end, which might be at the computer you are
4372 logged in to or at some terminal server in between.
4374 If you turn off flow control, characters may be lost; using a printer
4375 connected to the terminal may fail. You may be able to get around
4376 this problem by modifying the @samp{termcap} entry for your terminal to
4377 include extra NUL padding characters.
4382 If you are using a dialup connection, the modems may be using
4383 XON/XOFF flow control. It's not clear how to get around this.
4386 a router or terminal server
4388 Some network box between the terminal and your computer may be using
4389 XON/XOFF flow control. It may be possible to make it use some other
4390 kind of flow control. You will probably have to ask your local
4391 network experts for help with this.
4394 @code{tty} and/or @code{pty} devices
4396 If your connection to Emacs goes through multiple @code{tty} and/or
4397 @code{pty} devices, they may be using XON/XOFF flow control even when it
4400 @email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes:
4403 Some versions of @code{rlogin} (and possibly @code{telnet}) do not pass
4404 flow control characters to the remote system to which they connect. On
4405 such systems, Emacs on the remote system cannot disable flow control on
4406 the local system. Sometimes @samp{rlogin -8} will avoid this problem.
4408 One way to cure this is to disable flow control on the local host (the
4409 one running @code{rlogin}, not the one running @code{rlogind}) using the
4410 @code{stty} command, before starting the @code{rlogin} process. On many
4411 systems, @samp{stty start u stop u} will do this.
4413 Some versions of @samp{tcsh} will prevent even this from working. One
4414 way around this is to start another shell before starting rlogin,
4415 and issue the @samp{stty} command to disable flow control from that shell.
4418 Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems.
4423 Make Emacs speak the XON/XOFF flow control protocol.
4425 You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by
4429 (enable-flow-control)
4433 to unconditionally enable flow control or
4436 (enable-flow-control-on "vt100" "h19")
4440 (using your terminal names instead of @samp{vt100} or @samp{h19}) to
4441 enable selectively. These commands will automatically swap @kbd{C-s}
4442 and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}. Variables can be used to
4443 change the default swap keys (@code{flow-control-c-s-replacement} and
4444 @code{flow-control-c-q-replacement}).
4446 If you are fixing this for yourself, simply put the form in your
4447 @file{.emacs} file. If you are fixing this for your entire site, the
4448 best place to put it is in the @file{site-lisp/site-start.el} file.
4449 (Here @file{site-lisp} is actually a subdirectory of your Emacs
4450 installation directory, typically @file{/usr/local/share/emacs}.)
4451 Putting this form in @file{site-lisp/default.el} has the problem that
4452 if the user's @file{.emacs} file has an error, this will prevent
4453 @file{default.el} from being loaded and Emacs may be unusable for the
4454 user, even for correcting their @file{.emacs} file (unless they're
4455 smart enough to move it to another name).
4457 @code{enable-flow-control} can be invoked interactively as well:
4458 @kbd{M-x enable-flow-control @key{RET}}.
4462 For further discussion of this issue, read the file @file{etc/PROBLEMS}
4463 (in the Emacs source directory when you unpack the Emacs distribution).
4465 @node Binding C-s and C-q, Backspace invokes help, Handling C-s and C-q with flow control, Key bindings
4466 @section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out?
4467 @cindex Binding @kbd{C-s} and @kbd{C-q}
4468 @cindex @kbd{C-s} and @kbd{C-q}, binding
4470 To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control}
4471 or @code{enable-flow-control-on}. @xref{Handling C-s and C-q with flow
4472 control}, for usage and implementation details.
4474 To bind other keys, use @code{keyboard-translate}. @xref{Swapping
4475 keys}, for usage details. To do this for an entire site, you should
4476 swap the keys in @file{site-lisp/site-start.el}. @xref{Handling C-s
4477 and C-q with flow control}, for an explanation of why
4478 @file{site-lisp/default.el} should not be used.
4483 If you do this for an entire site, the users will be confused by
4484 the disparity between what the documentation says and how Emacs
4489 @node Backspace invokes help, stty and Backspace key, Binding C-s and C-q, Key bindings
4490 @section Why does the @key{Backspace} key invoke help?
4491 @cindex Backspace key invokes help
4492 @cindex Help invoked by Backspace
4493 @cindex DEL key does not delete
4495 The @key{Backspace} key (on most keyboards) generates @acronym{ASCII} code 8.
4496 @kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes
4497 help-command. This is intended to be easy to remember since the first
4498 letter of @samp{help} is @samp{h}. The easiest solution to this problem
4499 is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
4500 @key{Delete} key) for deleting the previous character.
4502 For many people this solution may be problematic:
4507 They normally use @key{Backspace} outside of Emacs for deleting the
4508 previous character. This can be solved by making @key{DEL} the command
4509 for deleting the previous character outside of Emacs. On many Unix
4510 systems, this command will remap @key{DEL}:
4517 The user may prefer the @key{Backspace} key for deleting the
4518 previous character because it is more conveniently located on their
4519 keyboard or because they don't even have a separate @key{Delete} key.
4520 In this case, the @key{Backspace} key should be made to behave like
4521 @key{Delete}. There are several methods.
4525 Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
4526 TeraTerm) allow the character generated by the @key{Backspace} key to be
4527 changed from a setup menu.
4530 You may be able to get a keyboard that is completely programmable, or a
4531 terminal emulator that supports remapping of any key to any other key.
4534 With Emacs 21.1 and later, you can control the effect of the
4535 @key{Backspace} and @key{Delete} keys, on both dumb terminals and a
4536 windowed displays, by customizing the option
4537 @code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
4538 normal-erase-is-backspace}. See the documentation of these symbols
4539 (@pxref{Emacs Lisp documentation}) for more info.
4542 It is possible to swap the @key{Backspace} and @key{DEL} keys inside
4546 (keyboard-translate ?\C-h ?\C-?)
4550 This is the recommended method of forcing @key{Backspace} to act as
4551 @key{DEL}, because it works even in modes which bind @key{DEL} to
4552 something other than @code{delete-backward-char}.
4554 Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
4555 default deletes forward:
4558 (keyboard-translate ?\C-? ?\C-d)
4561 @xref{Swapping keys}, for further details about @code{keyboard-translate}.
4564 Another approach is to switch key bindings and put help on @kbd{C-x h}
4568 (global-set-key "\C-h" 'delete-backward-char)
4570 ;; overrides mark-whole-buffer
4571 (global-set-key "\C-xh" 'help-command)
4575 This method is not recommended, though: it only solves the problem for
4576 those modes which bind @key{DEL} to @code{delete-backward-char}. Modes
4577 which bind @key{DEL} to something else, such as @code{view-mode}, will
4578 not work as you expect when you press the @key{Backspace} key. For this
4579 reason, we recommend the @code{keyboard-translate} method, shown
4582 Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
4585 Don't try to bind @key{DEL} to @code{help-command}, because there are
4586 many modes that have local bindings of @key{DEL} that will interfere.
4590 When Emacs 21 or later runs on a windowed display, it binds the
4591 @key{Delete} key to a command which deletes the character at point, to
4592 make Emacs more consistent with keyboard operation on these systems.
4594 For more information about troubleshooting this problem, see @ref{DEL
4595 Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
4598 @node stty and Backspace key, Swapping keys, Backspace invokes help, Key bindings
4599 @section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}?
4600 @cindex @file{stty} and Emacs
4601 @cindex Backspace and @file{stty}
4602 @cindex Delete and @file{stty}
4606 @c FIXME: RMS explained the reasons for this on emacs-hackers. It's
4607 @c probably worth putting that explanation here.
4609 @node Swapping keys, Producing C-XXX with the keyboard, stty and Backspace key, Key bindings
4610 @section How do I swap two keys?
4611 @cindex Swapping keys
4612 @cindex Keys, swapping
4613 @cindex @code{keyboard-translate}
4615 You can swap two keys (or key sequences) by using the
4616 @code{keyboard-translate} function. For example, to turn @kbd{C-h}
4617 into @key{DEL} and @key{DEL} to @kbd{C-h}, use
4620 (keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL
4621 (keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'.
4625 The first key sequence of the pair after the function identifies what is
4626 produced by the keyboard; the second, what is matched for in the
4629 However, in the specific case of @kbd{C-h} and @key{DEL}, you should
4630 toggle @code{normal-erase-is-backspace-mode} instead of calling
4631 @code{keyboard-translate}. @inforef{DEL Does Not Delete, DEL Does Not Delete,
4634 Keyboard translations are not the same as key bindings in keymaps.
4635 Emacs contains numerous keymaps that apply in different situations, but
4636 there is only one set of keyboard translations, and it applies to every
4637 character that Emacs reads from the terminal. Keyboard translations
4638 take place at the lowest level of input processing; the keys that are
4639 looked up in keymaps contain the characters that result from keyboard
4642 @node Producing C-XXX with the keyboard, No Meta key, Swapping keys, Key bindings
4643 @section How do I produce C-XXX with my keyboard?
4644 @cindex Producing control characters
4645 @cindex Generating control characters
4646 @cindex Control characters, generating
4648 On terminals (but not under X), some common ``aliases'' are:
4652 @item @kbd{C-2} or @kbd{C-@key{SPC}}
4658 @item @kbd{C-7} or @kbd{C-S--}
4672 Often other aliases exist; use the @kbd{C-h c} command and try
4673 @key{CTRL} with all of the digits on your keyboard to see what gets
4674 generated. You can also try the @kbd{C-h w} command if you know the
4675 name of the command.
4677 @node No Meta key, No Escape key, Producing C-XXX with the keyboard, Key bindings
4678 @section What if I don't have a @key{Meta} key?
4679 @cindex No @key{Meta} key
4680 @cindex @key{Meta} key, what to do if you lack it
4682 On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
4684 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact,
4685 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
4686 (depending on the value of @code{meta-prefix-char}). Note that you
4687 press @key{Meta} and @key{a} together, but with @key{ESC}, you press
4688 @key{ESC}, release it, and then press @key{a}.
4690 @node No Escape key, Compose Character, No Meta key, Key bindings
4691 @section What if I don't have an @key{Escape} key?
4692 @cindex No Escape key
4693 @cindex Lacking an Escape key
4694 @cindex Escape key, lacking
4696 Type @kbd{C-[} instead. This should send @acronym{ASCII} code 27 just like an
4697 Escape key would. @kbd{C-3} may also work on some terminal (but not
4698 under X). For many terminals (notably DEC terminals) @key{F11}
4699 generates @key{ESC}. If not, the following form can be used to bind it:
4702 ;; F11 is the documented ESC replacement on DEC terminals.
4703 (define-key function-key-map [f11] [?\e])
4706 @node Compose Character, Binding combinations of modifiers and function keys, No Escape key, Key bindings
4707 @section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
4708 @cindex @key{Compose Character} key, using as @key{Meta}
4709 @cindex @key{Meta}, using @key{Compose Character} for
4711 On a dumb terminal such as a VT220, no. It is rumored that certain
4712 VT220 clones could have their @key{Compose} key configured this way. If
4713 you're using X, you might be able to do this with the @code{xmodmap}
4716 @node Binding combinations of modifiers and function keys, Meta key does not work in xterm, Compose Character, Key bindings
4717 @section How do I bind a combination of modifier key and function key?
4718 @cindex Modifiers and function keys
4719 @cindex Function keys and modifiers
4720 @cindex Binding modifiers and function keys
4722 With Emacs 19 and later, you can represent modified function keys in
4723 vector format by adding prefixes to the function key symbol. For
4724 example (from the on-line documentation):
4727 (global-set-key [?\C-x right] 'forward-page)
4731 where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
4733 You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
4734 @key{Super}, @key{Alt}, and @key{Shift} with function keys. To
4735 represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
4736 @samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here
4737 is how to make @kbd{H-M-RIGHT} move forward a word:
4740 (global-set-key [H-M-right] 'forward-word)
4746 Not all modifiers are permitted in all situations. @key{Hyper},
4747 @key{Super}, and @key{Alt} are not available on Unix character
4748 terminals. Non-@acronym{ASCII} keys and mouse events (e.g. @kbd{C-=} and
4749 @kbd{Mouse-1}) also fall under this category.
4753 @xref{Binding keys to commands}, for general key binding instructions.
4755 @node Meta key does not work in xterm, ExtendChar key does not work as Meta, Binding combinations of modifiers and function keys, Key bindings
4756 @section Why doesn't my @key{Meta} key work in an @code{xterm} window?
4757 @cindex @key{Meta} key and @code{xterm}
4758 @cindex Xterm and @key{Meta} key
4760 @inforef{Unibyte Mode, Single-Byte Character Set Support, emacs}.
4762 If the advice in the Emacs manual fails, try all of these methods before
4763 asking for further help:
4768 You may have big problems using @code{mwm} as your window manager.
4769 (Does anyone know a good generic solution to allow the use of the
4770 @key{Meta} key in Emacs with @file{mwm}?)
4773 For X11: Make sure it really is a @key{Meta} key. Use @code{xev} to
4774 find out what keysym your @key{Meta} key generates. It should be either
4775 @code{Meta_L} or @code{Meta_R}. If it isn't, use @file{xmodmap} to fix
4776 the situation. If @key{Meta} does generate @code{Meta_L} or
4777 @code{Meta_R}, but @kbd{M-x} produces a non-@acronym{ASCII} character, put this in
4778 your @file{~/.Xdefaults} file:
4781 XTerm*eightBitInput: false
4782 XTerm*eightBitOutput: true
4786 Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
4787 characters. @samp{stty -a} (or @samp{stty everything}) should show
4788 @samp{cs8} somewhere. If it shows @samp{cs7} instead, use @samp{stty
4789 cs8 -istrip} (or @samp{stty pass8}) to fix it.
4792 If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
4793 @samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
4797 If Emacs is running on Ultrix, it is reported that evaluating
4798 @code{(set-input-mode t nil)} helps.
4801 If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
4802 you type @kbd{M-W}, which is the same conversion Emacs would make if it
4803 got the @kbd{M-W} anyway. In X11R4, the following resource
4804 specification will do this:
4807 XTerm.VT100.EightBitInput: false
4811 (This changes the behavior of the @code{insert-eight-bit} action.)
4813 With older @code{xterm}s, you can specify this behavior with a translation:
4816 XTerm.VT100.Translations: #override \
4817 Meta<KeyPress>: string(0x1b) insert()
4821 You might have to replace @samp{Meta} with @samp{Alt}.
4825 @node ExtendChar key does not work as Meta, SPC no longer completes file names, Meta key does not work in xterm, Key bindings
4826 @section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
4827 @cindex @key{ExtendChar} key as @key{Meta}
4828 @cindex @key{Meta}, using @key{ExtendChar} for
4829 @cindex HP-UX, the @key{ExtendChar} key
4831 This is a result of an internationalization extension in X11R4 and the
4832 fact that HP is now using this extension. Emacs assumes that the
4833 @code{XLookupString} function returns the same result regardless of the
4834 @key{Meta} key state which is no longer necessarily true. Until Emacs
4835 is fixed, the temporary kludge is to run this command after each time
4836 the X server is started but preferably before any xterm clients are:
4839 xmodmap -e 'remove mod1 = Mode_switch'
4842 @c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
4845 This will disable the use of the extra keysyms systemwide, which may be
4846 undesirable if you actually intend to use them.
4848 @node SPC no longer completes file names, , ExtendChar key does not work as Meta, Key bindings
4849 @section Why doesn't SPC complete file names anymore?
4850 @cindex @kbd{SPC} file name completion
4852 Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in
4853 the minibuffer, so that file names with embedded spaces could be typed
4854 without the need to quote the spaces.
4856 You can get the old behavior by binding @kbd{SPC} to
4857 @code{minibuffer-complete-word} in the minibuffer, as follows:
4860 (define-key minibuffer-local-filename-completion-map (kbd "SPC")
4861 'minibuffer-complete-word)
4863 (define-key minibuffer-local-must-match-filename-map (kbd "SPC")
4864 'minibuffer-complete-word)
4867 @c ------------------------------------------------------------
4868 @node Alternate character sets, Mail and news, Key bindings, Top
4869 @chapter Alternate character sets
4870 @cindex Alternate character sets
4873 * Emacs does not display 8-bit characters::
4874 * Inputting eight-bit characters::
4875 * Kanji and Chinese characters::
4876 * Right-to-left alphabets::
4877 * How to add fonts::
4880 @node Emacs does not display 8-bit characters, Inputting eight-bit characters, Alternate character sets, Alternate character sets
4881 @section How do I make Emacs display 8-bit characters?
4882 @cindex Displaying eight-bit characters
4883 @cindex Eight-bit characters, displaying
4885 @inforef{Unibyte Mode, Single-byte Character Set
4886 Support, emacs}. On a Unix, when Emacs runs on a text-only terminal
4887 display or is invoked with @samp{emacs -nw}, you typically need to use
4888 @code{set-terminal-coding-system} to tell Emacs what the terminal can
4889 display, even after setting the language environment; otherwise
4890 non-@acronym{ASCII} characters will display as @samp{?}. On other operating
4891 systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
4892 character set supported by the display, and sets up the required
4893 terminal coding system automatically.
4895 @node Inputting eight-bit characters, Kanji and Chinese characters, Emacs does not display 8-bit characters, Alternate character sets
4896 @section How do I input eight-bit characters?
4897 @cindex Entering eight-bit characters
4898 @cindex Eight-bit characters, entering
4899 @cindex Input, 8-bit characters
4901 Various methods are available for input of eight-bit characters. See
4902 @inforef{Unibyte Mode, Single-byte Character Set
4903 Support, emacs}. For more sophisticated methods, @inforef{Input
4904 Methods, Input Methods, emacs}.
4906 @node Kanji and Chinese characters, Right-to-left alphabets, Inputting eight-bit characters, Alternate character sets
4907 @section Where can I get an Emacs that handles kanji, Chinese, or other Far-Eastern character sets?
4908 @cindex Kanji, handling with Emacs
4909 @cindex Chinese, handling with Emacs
4910 @cindex Japanese, handling with Emacs
4911 @cindex Korean, handling with Emacs
4913 Emacs 20 and later includes many of the features of MULE, the MULtilingual
4914 Enhancement to Emacs. @xref{Installing Emacs}, for information on where
4915 to find and download the latest version of Emacs.
4917 @node Right-to-left alphabets, How to add fonts, Kanji and Chinese characters, Alternate character sets
4918 @section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
4919 @cindex Right-to-left alphabets
4920 @cindex Hebrew, handling with Emacs
4921 @cindex Semitic alphabets
4922 @cindex Arabic alphabets
4924 Emacs 20 and later supports Hebrew characters (ISO 8859-8), but does not
4925 yet support right-to-left character entry and display.
4927 @email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called
4928 @file{hebrew.el} that allows right-to-left editing of Hebrew. It
4929 reportedly works out of the box with Emacs 19, but requires patches for
4930 Emacs 18. Write to Joel if you want the patches or package.
4932 @c FIXME: Should we mention Ehud Karni's package?
4934 @file{hebrew.el} requires a Hebrew screen font, but no other hardware support.
4935 Joel has a screen font for PCs running MS-DOS or GNU/Linux.
4937 You might also try querying @code{archie} for files named with
4938 @file{hebrew}; several ftp sites in Israel may also have the necessary
4941 @node How to add fonts, , Right-to-left alphabets, Alternate character sets
4942 @section How do I add fonts for use with Emacs?
4943 @cindex add fonts for use with Emacs
4946 First, download and install the BDF font files and any auxiliary
4947 packages they need. The GNU Intlfonts distribution can be found on
4948 @uref{http://directory.fsf.org/localization/intlfonts.html, the GNU
4949 Software Directory Web site}.
4951 Next, if you are on X Window system, issue the following two commands
4952 from the shell's prompt:
4955 xset +fp /usr/local/share/emacs/fonts
4960 (Modify the first command if you installed the fonts in a directory
4961 that is not @file{/usr/local/share/emacs/fonts}.) You also need to
4962 arrange for these two commands to run whenever you log in, e.g., by
4963 adding them to your window-system startup file, such as
4964 @file{~/.xsessionrc} or @file{~/.gnomerc}.
4966 Now, add the following line to your @file{~/.emacs} init file:
4969 (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf")
4973 (Again, modify the file name if you installed the fonts elsewhere.)
4975 Finally, if you wish to use the installed fonts with @code{ps-print},
4976 add the following line to your @file{~/.emacs}:
4979 (setq ps-multibyte-buffer 'bdf-font-except-latin)
4982 A few additional steps are necessary for MS-Windows; they are listed
4985 First, make sure @emph{all} the directories with BDF font files are
4986 mentioned in @code{bdf-directory-list}. On Unix and GNU/Linux
4987 systems, one normally runs @kbd{make install} to install the BDF fonts
4988 in the same directory. By contrast, Windows users typically don't run
4989 the Intlfonts installation command, but unpack the distribution in
4990 some directory, which leaves the BDF fonts in its subdirectories. For
4991 example, assume that you unpacked Intlfonts in @file{C:/Intlfonts};
4992 then you should set @code{bdf-directory-list} as follows:
4995 (setq bdf-directory-list
4996 '("C:/Intlfonts/Asian"
4997 "C:/Intlfonts/Chinese" "C:/Intlfonts/Chinese.X"
4998 "C:/Intlfonts/Chinese.BIG" "C:/Intlfonts/Ethiopic"
4999 "C:/Intlfonts/European" "C:/Intlfonts/European.BIG"
5000 "C:/Intlfonts/Japanese" "C:/Intlfonts/Japanese.X"
5001 "C:/Intlfonts/Japanese.BIG" "C:/Intlfonts/Korean.X"
5002 "C:/Intlfonts/Misc"))
5005 @cindex @code{w32-bdf-filename-alist}
5006 @cindex @code{w32-find-bdf-fonts}
5007 Next, you need to set up the variable @code{w32-bdf-filename-alist} to
5008 an alist of the BDF fonts and their corresponding file names.
5009 Assuming you have set @code{bdf-directory-list} to name all the
5010 directories with the BDF font files, the following Lisp snippet will
5011 set up @code{w32-bdf-filename-alist}:
5014 (setq w32-bdf-filename-alist
5015 (w32-find-bdf-fonts bdf-directory-list))
5018 Now, create fontsets for the BDF fonts:
5021 (create-fontset-from-fontset-spec
5022 "-*-fixed-medium-r-normal-*-16-*-*-*-c-*-fontset-bdf,
5023 japanese-jisx0208:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1983-*,
5024 katakana-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
5025 latin-jisx0201:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0201*-*,
5026 japanese-jisx0208-1978:-*-*-medium-r-normal-*-16-*-*-*-c-*-jisx0208.1978-*,
5027 thai-tis620:-misc-fixed-medium-r-normal--16-160-72-72-m-80-tis620.2529-1,
5028 lao:-misc-fixed-medium-r-normal--16-160-72-72-m-80-MuleLao-1,
5029 tibetan-1-column:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-80-MuleTibetan-1,
5030 ethiopic:-Admas-Ethiomx16f-Medium-R-Normal--16-150-100-100-M-160-Ethiopic-Unicode,
5031 tibetan:-TibMdXA-fixed-medium-r-normal--16-160-72-72-m-160-MuleTibetan-0")
5034 Many of the international bdf fonts from Intlfonts are type 0, and
5035 therefore need to be added to font-encoding-alist:
5038 (setq font-encoding-alist
5039 (append '(("MuleTibetan-0" (tibetan . 0))
5040 ("GB2312" (chinese-gb2312 . 0))
5041 ("JISX0208" (japanese-jisx0208 . 0))
5042 ("JISX0212" (japanese-jisx0212 . 0))
5043 ("VISCII" (vietnamese-viscii-lower . 0))
5044 ("KSC5601" (korean-ksc5601 . 0))
5045 ("MuleArabic-0" (arabic-digit . 0))
5046 ("MuleArabic-1" (arabic-1-column . 0))
5047 ("MuleArabic-2" (arabic-2-column . 0)))
5048 font-encoding-alist))
5051 You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium}
5052 fontset, or you can select it by setting the default font in your
5056 (set-default-font "fontset-bdf")
5060 @c ------------------------------------------------------------
5061 @node Mail and news, Concept index, Alternate character sets, Top
5062 @chapter Mail and news
5063 @cindex Mail and news
5066 * Changing the included text prefix::
5067 * Saving a copy of outgoing mail::
5068 * Expanding aliases when sending mail::
5069 * Rmail thinks all messages are one big one::
5070 * Sorting the messages in an Rmail folder::
5071 * Rmail writes to /usr/spool/mail::
5072 * Recovering mail files when Rmail munges them::
5073 * Replying to the sender of a message::
5074 * MIME with Emacs mail packages::
5075 * Automatically starting a mail or news reader::
5076 * Reading news with Emacs::
5077 * Gnus does not work with NNTP::
5078 * Viewing articles with embedded underlining::
5079 * Saving a multi-part Gnus posting::
5080 * Starting Gnus faster::
5081 * Catching up in all newsgroups::
5082 * Killing based on nonstandard headers::
5083 * Removing flashing messages::
5084 * Catch-up is slow in Gnus::
5085 * Gnus hangs for a long time::
5086 * Learning more about Gnus::
5089 @node Changing the included text prefix, Saving a copy of outgoing mail, Mail and news, Mail and news
5090 @section How do I change the included text prefix in mail/news followups?
5091 @cindex Prefix in mail/news followups, changing
5092 @cindex Included text prefix, changing
5093 @cindex Setting the included text character
5094 @cindex Quoting in mail messages
5096 If you read mail with Rmail or news with Gnus, set the variable
5097 @code{mail-yank-prefix}. For VM, set @code{vm-included-text-prefix}.
5098 For mh-e, set @code{mh-ins-buf-prefix}.
5100 For fancier control of citations, use Supercite. @xref{Supercite}.
5102 To prevent Emacs from including various headers of the replied-to
5103 message, set the value of @code{mail-yank-ignored-headers} to an
5106 @node Saving a copy of outgoing mail, Expanding aliases when sending mail, Changing the included text prefix, Mail and news
5107 @section How do I save a copy of outgoing mail?
5108 @cindex Saving a copy of outgoing mail
5109 @cindex Copying outgoing mail to a file
5110 @cindex Filing outgoing mail
5111 @cindex Automatic filing of outgoing mail
5112 @cindex Mail, saving outgoing automatically
5114 You can either mail yourself a copy by including a @samp{BCC} header in the
5115 mail message, or store a copy of the message directly to a file by
5116 including an @samp{FCC} header.
5118 If you use standard mail, you can automatically create a @samp{BCC} to
5122 (setq mail-self-blind t)
5126 in your @file{.emacs} file. You can automatically include an @samp{FCC}
5127 field by putting something like the following in your @file{.emacs}
5131 (setq mail-archive-file-name (expand-file-name "~/outgoing"))
5134 The output file will be in Unix mail format, which can be read directly
5135 by VM, but not always by Rmail. @xref{Learning how to do something}.
5137 If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
5140 It does not work to put @samp{set record filename} in the @file{.mailrc}
5143 @node Expanding aliases when sending mail, Rmail thinks all messages are one big one, Saving a copy of outgoing mail, Mail and news
5144 @section Why doesn't Emacs expand my aliases when sending mail?
5145 @cindex Expanding aliases when sending mail
5146 @cindex Mail alias expansion
5147 @cindex Sending mail with aliases
5152 You must separate multiple addresses in the headers of the mail buffer
5153 with commas. This is because Emacs supports RFC822 standard addresses
5157 To: Willy Smith <wks@@xpnsv.lwyrs.com>
5160 However, you do not need to---and probably should not, unless your
5161 system's version of @file{/usr/ucb/mail} (a.k.a.@: @code{mailx})
5162 supports RFC822---separate addresses with commas in your
5163 @file{~/.mailrc} file.
5166 Emacs normally only reads the @file{.mailrc} file once per session,
5167 when you start to compose your first mail message. If you edit
5168 @file{.mailrc}, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to
5169 make Emacs reread @file{~/.mailrc}.
5172 If you like, you can expand mail aliases as abbrevs, as soon as you
5173 type them in. To enable this feature, execute the following:
5176 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
5179 Note that the aliases are expanded automatically only after you type
5180 @key{RET} or a punctuation character (e.g. @kbd{,}). You can force their
5181 expansion by moving point to the end of the alias and typing @kbd{C-x a e}
5182 (@kbd{M-x expand-abbrev}).
5185 @node Rmail thinks all messages are one big one, Sorting the messages in an Rmail folder, Expanding aliases when sending mail, Mail and news
5186 @section Why does Rmail think all my saved messages are one big message?
5187 @cindex Rmail thinks all messages are one large message
5189 A file created through the @samp{FCC} field in a message is in Unix mail
5190 format, not the format that Rmail uses (BABYL format). Rmail will try
5191 to convert a Unix mail file into BABYL format on input, but sometimes it
5192 makes errors. For guaranteed safety, you can make the
5193 @file{saved-messages} file be an inbox for your Rmail file by using the
5194 function @code{set-rmail-inbox-list}.
5196 @node Sorting the messages in an Rmail folder, Rmail writes to /usr/spool/mail, Rmail thinks all messages are one big one, Mail and news
5197 @section How can I sort the messages in my Rmail folder?
5198 @cindex Rmail, sorting messages in
5199 @cindex Folder, sorting messages in an Rmail
5200 @cindex Sorting messages in an Rmail folder
5202 In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
5203 and their key bindings.
5205 @node Rmail writes to /usr/spool/mail, Recovering mail files when Rmail munges them, Sorting the messages in an Rmail folder, Mail and news
5206 @section Why does Rmail need to write to @file{/usr/spool/mail}?
5207 @cindex Rmail and @file{/usr/spool/mail}
5208 @cindex @file{/usr/spool/mail} and Rmail
5210 This is the behavior of the @code{movemail} program which Rmail uses.
5211 This indicates that @code{movemail} is configured to use lock files.
5216 Certain systems require lock files to interlock access to mail files.
5217 On these systems, @code{movemail} must write lock files, or you risk losing
5218 mail. You simply must arrange to let @code{movemail} write them.
5220 Other systems use the @code{flock} system call to interlock access. On
5221 these systems, you should configure @code{movemail} to use @code{flock}.
5224 @node Recovering mail files when Rmail munges them, Replying to the sender of a message, Rmail writes to /usr/spool/mail, Mail and news
5225 @section How do I recover my mail files after Rmail munges their format?
5226 @cindex Recovering munged mail files
5227 @cindex Rmail munged my files
5228 @cindex Mail files, recovering those munged by Rmail
5230 If you have just done @kbd{M-x rmail-input} on a file and you don't want
5231 to save it in Rmail's format (called BABYL), just kill the buffer (with
5234 @cindex Exporting messages as Unix mail files
5235 If you typed @kbd{M-x rmail} and it read some messages out of your inbox
5236 and you want to put them in a Unix mail file, use @kbd{C-o} on each
5239 @cindex Converting from BABYL to Unix mail format
5240 @cindex @code{unrmail} command
5241 If you want to convert an existing file from BABYL format to Unix mail
5242 format, use the command @kbd{M-x unrmail}: it will prompt you for the
5243 input and output file names.
5246 Alternatively, you could use the @code{b2m} program supplied with
5247 Emacs. @code{b2m} is a filter, and is used like this:
5250 b2m < @var{babyl-file} > @var{mbox-file}
5254 where @var{babyl-file} is the name of the BABYL file, and
5255 @var{mbox-file} is the name of the file where the converted mail will
5258 @node Replying to the sender of a message, MIME with Emacs mail packages, Recovering mail files when Rmail munges them, Mail and news
5259 @section How can I force Rmail to reply to the sender of a message, but not the other recipients?
5260 @cindex Replying only to the sender of a message
5261 @cindex Sender, replying only to
5262 @cindex Rmail, replying to the sender of a message in
5264 @email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit
5265 @key{r} to reply in Rmail, by default it CCs all of the original
5266 recipients (everyone on the original @samp{To} and @samp{CC}
5267 lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
5268 it replies only to the sender. However, going through the whole
5269 @kbd{C-u} business every time you want to reply is a pain. This is the
5270 best fix I've been able to come up with:
5273 (defun rmail-reply-t ()
5274 "Reply only to the sender of the current message. (See rmail-reply.)"
5278 (add-hook 'rmail-mode-hook
5280 (define-key rmail-mode-map "r" 'rmail-reply-t)
5281 (define-key rmail-mode-map "R" 'rmail-reply)))
5284 @node MIME with Emacs mail packages, Automatically starting a mail or news reader, Replying to the sender of a message, Mail and news
5285 @section How can I get my favorite Emacs mail package to support MIME?
5286 @cindex MIME and Emacs mail packages
5287 @cindex Mail packages and MIME
5288 @cindex FAQ for MIME and Emacs
5290 Version 6.x of VM supports MIME. @xref{VM}. Gnus supports MIME in mail
5291 and news messages as of version 5.8.1 (Pterodactyl). Rmail has limited
5292 support for single-part MIME messages beginning with Emacs 20.3.
5294 @node Automatically starting a mail or news reader, Reading news with Emacs, MIME with Emacs mail packages, Mail and news
5295 @section How do I make Emacs automatically start my mail/news reader?
5296 @cindex Mail reader, starting automatically
5297 @cindex News reader, starting automatically
5298 @cindex Starting mail/news reader automatically
5300 To start Emacs in Gnus:
5313 A more convenient way to start with Gnus:
5316 alias gnus 'emacs -f gnus'
5320 It is probably unwise to automatically start your mail or news reader
5321 from your @file{.emacs} file. This would cause problems if you needed to run
5322 two copies of Emacs at the same time. Also, this would make it difficult for
5323 you to start Emacs quickly when you needed to.
5325 @node Reading news with Emacs, Gnus does not work with NNTP, Automatically starting a mail or news reader, Mail and news
5326 @section How do I read news under Emacs?
5327 @cindex Reading news under Emacs
5328 @cindex Usenet reader in Emacs
5329 @cindex Gnus newsreader
5331 Use @kbd{M-x gnus}. It is documented in Info (@pxref{Learning how to do
5334 @node Gnus does not work with NNTP, Viewing articles with embedded underlining, Reading news with Emacs, Mail and news
5335 @section Why doesn't Gnus work via NNTP?
5336 @cindex Gnus and NNTP
5337 @cindex NNTP, Gnus fails to work with
5339 There is a bug in NNTP version 1.5.10, such that when multiple requests
5340 are sent to the NNTP server, the server only handles the first one
5341 before blocking waiting for more input which never comes. NNTP version
5342 1.5.11 claims to fix this.
5344 You can work around the bug inside Emacs like this:
5347 (setq nntp-maximum-request 1)
5350 You can find out what version of NNTP your news server is running by
5351 telnetting to the NNTP port (usually 119) on the news server machine
5352 (i.e., @kbd{telnet server-machine 119}). The server should give its
5353 version number in the welcome message. Type @kbd{quit} to get out.
5355 @xref{Spontaneous entry into isearch-mode}, for some additional ideas.
5357 @node Viewing articles with embedded underlining, Saving a multi-part Gnus posting, Gnus does not work with NNTP, Mail and news
5358 @section How do I view news articles with embedded underlining (e.g., ClariNews)?
5359 @cindex Underlining, embedded in news articles
5360 @cindex News articles with embedded underlining
5361 @cindex Embedded underlining in news articles
5363 Underlining appears like this:
5366 _^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg
5369 @email{abraham@@dina.kvl.dk, Per Abrahamsen} suggests using the following
5370 code, which uses the underline face to turn such text into true
5371 underlining, inconjunction with Gnus:
5374 (defun gnus-article-prepare-overstrike ()
5375 ;; Prepare article for overstrike commands.
5377 (set-buffer gnus-article-buffer)
5378 (let ((buffer-read-only nil))
5379 (goto-char (point-min))
5380 (while (search-forward "\b" nil t)
5381 (let ((next (following-char))
5382 (previous (char-after (- (point) 2))))
5383 (cond ((eq next previous)
5384 (delete-region (- (point) 2) (point))
5385 (put-text-property (point) (1+ (point))
5388 (delete-region (1- (point)) (1+ (point)))
5389 (put-text-property (1- (point)) (point)
5392 (delete-region (- (point) 2) (point))
5393 (put-text-property (point) (1+ (point))
5394 'face 'underline))))))))
5396 (add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike)
5399 Latest versions of Gnus do such a conversion automatically.
5401 If you prefer to do away with underlining altogether, you can
5402 destructively remove it with @kbd{M-x ununderline-region}; do this
5406 (add-hook 'gnus-article-prepare-hook
5407 (lambda () (ununderline-region (point-min) (point-max))))
5410 @node Saving a multi-part Gnus posting, Starting Gnus faster, Viewing articles with embedded underlining, Mail and news
5411 @section How do I save all the items of a multi-part posting in Gnus?
5412 @cindex Multi-part postings in Gnus, saving
5413 @cindex Saving multi-part postings in Gnus
5414 @cindex Gnus, saving multi-part postings in
5416 Use @code{gnus-uu}. Type @kbd{C-c C-v C-h} in the Gnus summary buffer
5417 to see a list of available commands.
5419 @node Starting Gnus faster, Catching up in all newsgroups, Saving a multi-part Gnus posting, Mail and news
5420 @section How do I make Gnus start up faster?
5421 @cindex Faster, starting Gnus
5422 @cindex Starting Gnus faster
5423 @cindex Gnus, starting faster
5425 From the Gnus FAQ (@pxref{Learning more about Gnus}):
5428 @email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted
5429 the same query recently and I got an answer to it. I am going to
5430 repeat the answer. What you need is a newer version of gnus, version
5431 5.0.4+. I am using 5.0.12 and it works fine with me with the
5435 (setq gnus-check-new-newsgroups nil
5436 gnus-read-active-file 'some
5437 gnus-nov-is-evil nil
5438 gnus-select-method '(nntp gnus-nntp-server))
5442 @node Catching up in all newsgroups, Killing based on nonstandard headers, Starting Gnus faster, Mail and news
5443 @section How do I catch up all newsgroups in Gnus?
5444 @cindex Catching up all newsgroups in Gnus
5445 @cindex Gnus, Catching up all newsgroups in
5447 In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
5449 Leave off the initial @kbd{M-<} if you only want to catch up from point
5450 to the end of the @file{*Newsgroup*} buffer.
5452 @node Killing based on nonstandard headers, Removing flashing messages, Catching up in all newsgroups, Mail and news
5453 @section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers?
5454 @cindex Killing articles based on nonstandard headers
5455 @cindex Newsgroups header, killing articles based on
5456 @cindex Keywords header, killing articles based on
5457 @cindex Control header, killing articles based on
5459 Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and
5460 @samp{Control} headers are ``Unknown header'' fields.
5462 For the @samp{Newsgroups} header, there is an easy workaround: kill on the
5463 @samp{Xref} header instead, which will be present on any cross-posted article
5464 (as long as your site carries the cross-post group).
5466 If you really want to kill on one of these headers, you can do it like
5470 (gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)")
5473 @node Removing flashing messages, Catch-up is slow in Gnus, Killing based on nonstandard headers, Mail and news
5474 @section How do I get rid of flashing messages in Gnus for slow connections?
5475 @cindex Flashing Gnus messages, removing
5476 @cindex Removing flashing Gnus messages
5477 @cindex Slow connections causing flashing messages in Gnus
5478 @cindex Gnus, flashing messages in
5480 Set @code{nntp-debug-read} to @code{nil}.
5482 @node Catch-up is slow in Gnus, Gnus hangs for a long time, Removing flashing messages, Mail and news
5483 @section Why is catch up slow in Gnus?
5484 @cindex Slow catch up in Gnus
5485 @cindex Gnus is slow when catching up
5486 @cindex Crosspostings make Gnus catching up slow
5488 Because Gnus is marking crosspostings read. You can control this with
5489 the variable @code{gnus-use-cross-reference}.
5491 @node Gnus hangs for a long time, Learning more about Gnus, Catch-up is slow in Gnus, Mail and news
5492 @section Why does Gnus hang for a long time when posting?
5493 @cindex Hangs in Gnus
5494 @cindex Gnus hangs while posting
5495 @cindex Posting, Gnus hangs wile
5497 @email{tale@@uunet.uu.net, David Lawrence} explains:
5500 The problem is almost always interaction between NNTP and C News. NNTP
5501 POST asks C News's @code{inews} to not background itself but rather hang
5502 around and give its exit status so it knows whether the post was successful.
5503 (That wait will on some systems not return the exit status of the
5504 waited for job is a different sort of problem.) It ends up taking a
5505 long time because @code{inews} is calling @code{relaynews}, which often
5506 waits for another @code{relaynews} to free the lock on the news system
5507 so it can file the article.
5509 My preferred solution is to change @code{inews} to not call
5510 @code{relaynews}, but rather use @code{newsspool}. This loses some
5511 error-catching functionality, but is for the most part safe as
5512 @code{inews} will detect a lot of the errors on its own. The C News
5513 folks have sped up @code{inews}, too, so speed should look better to
5514 most folks as that update propagates around.
5517 @node Learning more about Gnus, , Gnus hangs for a long time, Mail and news
5518 @section Where can I find out more about Gnus?
5519 @cindex FAQ for Gnus
5521 @cindex Learning more about Gnus
5523 For more information on Gnus, consult the Gnus manual and FAQ, which are
5524 part of the Gnus distribution.
5526 @node Concept index, , Mail and news, Top
5527 @unnumbered Concept Index
5534 arch-tag: fee0d62d-06cf-43d8-ac21-123408eaf10f