*** empty log message ***
[emacs.git] / man / faq.texi
blobb25ef4bca6f65f2e94e0cee6d9b269dbff4f2346
1 \input texinfo   @c -*- coding: latin-1; mode: texinfo; -*-
2 @c %**start of header
3 @setfilename ../info/efaq
4 @settitle GNU Emacs FAQ
5 @c %**end of header
7 @setchapternewpage odd
9 @c This is used in many places
10 @set VER 21.3
12 @copying
13 Copyright 2001, 2002, 2003 Free Software Foundation, Inc.
14 Copyright 1994,1995,1996,1997,1998,1999,2000 Reuven M. Lerner@*
15 Copyright 1992,1993 Steven Byrnes@*
16 Copyright 1990,1991,1992 Joseph Brian Wells@*
18 @quotation
19 This list of frequently asked questions about GNU Emacs with answers
20 ("FAQ") may be translated into other languages, transformed into other
21 formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information.
23 The same conditions apply to any derivative of the FAQ as apply to the FAQ
24 itself.  Every copy of the FAQ must include this notice or an approved
25 translation, information on who is currently maintaining the FAQ and how to
26 contact them (including their e-mail address), and information on where the
27 latest version of the FAQ is archived (including FTP information).
29 The FAQ may be copied and redistributed under these conditions, except that
30 the FAQ may not be embedded in a larger literary work unless that work
31 itself allows free copying and redistribution.
33 [This version has been somewhat edited from the last-posted version
34 (as of August 1999) for inclusion in the Emacs distribution.]
35 @end quotation
36 @end copying
38 @dircategory Emacs
39 @direntry
40 * Emacs FAQ: (efaq).    Frequently Asked Questions about Emacs.
41 @end direntry
43 @c The @titlepage stuff only appears in the printed version
44 @titlepage
45 @sp 10
46 @center @titlefont{GNU Emacs FAQ}
48 @c The following two commands start the copyright page.
49 @page
50 @vskip 0pt plus 1filll
51 @insertcopying
52 @end titlepage
54 @node    Top, FAQ notation, (dir), (dir)
56 This is the GNU Emacs FAQ, last updated on @today{}.
58 The FAQ is maintained as a Texinfo document, allowing us to create HTML,
59 Info, and TeX documents from a single source file, and is slowly but
60 surely being improved.  Please bear with us as we improve on this
61 format.  This FAQ is maintained as a part of GNU Emacs.  If you find
62 any errors, or have any suggestions, please use @kbd{M-x report-emacs-bug}
63 to report them.
65 @menu
66 * FAQ notation::
67 * General questions::
68 * Getting help::
69 * Status of Emacs::
70 * Common requests::
71 * Bugs and problems::
72 * Compiling and installing Emacs::
73 * Finding Emacs and related packages::
74 * Major packages and programs::
75 * Key bindings::
76 * Alternate character sets::
77 * Mail and news::
78 * Concept index::
79 @end menu
81 @c ------------------------------------------------------------
82 @node FAQ notation, General questions, Top, Top
83 @chapter FAQ notation
84 @cindex FAQ notation
86 This chapter describes notation used in the GNU Emacs FAQ, as well as in
87 the Emacs documentation.  Consult this section if this is the first time
88 you are reading the FAQ, or if you are confused by notation or terms
89 used in the FAQ.
91 @menu
92 * Basic keys::
93 * Extended commands::
94 * On-line manual::
95 * File-name conventions::
96 * Common acronyms::
97 @end menu
99 @node Basic keys, Extended commands, FAQ notation, FAQ notation
100 @section What do these mean: @kbd{C-h}, @kbd{C-M-a}, @key{RET}, @kbd{@key{ESC} a}, etc.?
101 @cindex Basic keys
102 @cindex Control key, notation for
103 @cindex @key{Meta} key, notation for
104 @cindex Control-Meta characters, notation for
105 @cindex @kbd{C-h}, definition of
106 @cindex @kbd{C-M-h}, definition of
107 @cindex @key{DEL}, definition of
108 @cindex @key{ESC}, definition of
109 @cindex @key{LFD}, definition of
110 @cindex @key{RET}, definition of
111 @cindex @key{SPC}, definition of
112 @cindex @key{TAB}, definition of
113 @cindex Notation for keys
115 @itemize @bullet
117 @item
118 @kbd{C-x}: press the @key{x} key while holding down the @key{Control} key
120 @item
121 @kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key
122 (if your computer doesn't have a @key{Meta} key, @pxref{No Meta key})
124 @item
125 @kbd{M-C-x}: press the @key{x} key while holding down both @key{Control}
126 and @key{Meta}
128 @item
129 @kbd{C-M-x}: a synonym for the above
131 @item
132 @key{LFD}: Linefeed or Newline; same as @kbd{C-j}
134 @item
135 @key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m}
137 @item
138 @key{DEL}: @key{Delete}, usually @strong{not} the same as
139 @key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if
140 deleting invokes Emacs help)
142 @item
143 @key{ESC}: Escape; same as @kbd{C-[}
145 @item
146 @key{TAB}: Tab; same as @kbd{C-i}
148 @item
149 @key{SPC}: Space bar
151 @end itemize
153 Key sequences longer than one key (and some single-key sequences) are
154 written inside quotes or on lines by themselves, like this:
156 @display
157   @kbd{M-x frobnicate-while-foo RET}
158 @end display
160 @noindent
161 Any real spaces in such a key sequence should be ignored; only @key{SPC}
162 really means press the space key.
164 The ASCII code sent by @kbd{C-x} (except for @kbd{C-?}) is the value
165 that would be sent by pressing just @key{x} minus 96 (or 64 for
166 upper-case @key{X}) and will be from 0 to 31.  On Unix and GNU/Linux
167 terminals, the ASCII code sent by @kbd{M-x} is the sum of 128 and the
168 ASCII code that would be sent by pressing just @key{x}.  Essentially,
169 @key{Control} turns off bits 5 and 6 and @key{Meta} turns on bit
170 7@footnote{
171 DOS and Windows terminals don't set bit 7 when the @key{Meta} key is
172 pressed.}.
174 @kbd{C-?} (aka @key{DEL}) is ASCII code 127.  It is a misnomer to call
175 @kbd{C-?}  a ``control'' key, since 127 has both bits 5 and 6 turned ON.
176 Also, on very few keyboards does @kbd{C-?} generate ASCII code 127.
178 @inforef{Text Characters, Text Characters, emacs}, and @inforef{Keys,
179 Keys, emacs}, for more information.  (@xref{On-line manual}, for more
180 information about Info.)
182 @node Extended commands, On-line manual, Basic keys, FAQ notation
183 @section What does @file{M-x @var{command}} mean?
184 @cindex Extended commands
185 @cindex Commands, extended
186 @cindex M-x, meaning of
188 @kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the
189 command, then type @key{RET}.  (@xref{Basic keys}, if you're not sure
190 what @kbd{M-x} and @key{RET} mean.)
192 @kbd{M-x} (by default) invokes the command
193 @code{execute-extended-command}.  This command allows you to run any
194 Emacs command if you can remember the command's name.  If you can't
195 remember the command's name, you can type @key{TAB} and @key{SPC} for
196 completion, @key{?} for a list of possibilities, and @kbd{M-p} and
197 @kbd{M-n} (or up-arrow and down-arrow on terminals that have these
198 editing keys) to see previous commands entered.  An Emacs @dfn{command}
199 is an @dfn{interactive} Emacs function.
201 @cindex @key{Do} key
202 Your system administrator may have bound other key sequences to invoke
203 @code{execute-extended-command}.  A function key labeled @kbd{Do} is a
204 good candidate for this, on keyboards that have such a key.
206 If you need to run non-interactive Emacs functions, see @ref{Evaluating
207 Emacs Lisp code}.
209 @node On-line manual, File-name conventions, Extended commands, FAQ notation
210 @section How do I read topic XXX in the on-line manual?
211 @cindex On-line manual, reading topics in
212 @cindex Reading topics in the on-line manual
213 @cindex Finding topics in the on-line manual
214 @cindex Info, finding topics in
216 When we refer you to some @var{topic} in the on-line manual, you can
217 read this manual node inside Emacs (assuming nothing is broken) by
218 typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}.
220 This invokes Info, the GNU hypertext documentation browser.  If you don't
221 already know how to use Info, type @key{?} from within Info.
223 If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs
224 @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}.
226 If these commands don't work as expected, your system administrator may
227 not have installed the Info files, or may have installed them
228 improperly.  In this case you should complain.
230 @xref{Getting a printed manual}, if you would like a paper copy of the
231 Emacs manual.
233 @node File-name conventions, Common acronyms, On-line manual, FAQ notation
234 @section What are @file{etc/SERVICE}, @file{src/config.h}, and @file{lisp/default.el}?
235 @cindex File-name conventions
236 @cindex Conventions for file names
237 @cindex Directories and files that come with Emacs
239 These are files that come with Emacs.  The Emacs distribution is divided
240 into subdirectories; the important ones are @file{etc}, @file{lisp}, and
241 @file{src}.
243 If you use Emacs, but don't know where it is kept on your system, start
244 Emacs, then type @kbd{C-h v data-directory @key{RET}}.  The directory
245 name displayed by this will be the full pathname of the installed
246 @file{etc} directory.  (This full path is recorded in the Emacs variable
247 @code{data-directory}, and @kbd{C-h v} displays the value and the
248 documentation of a variable.)
250 The location of your Info directory (i.e., where on-line documentation
251 is stored) is kept in the variable @code{Info-default-directory-list}.  Use
252 @kbd{C-h v Info-default-directory-list @key{RET}} to see the value of
253 this variable, which will be a list of directory names.  The last
254 directory in that list is probably where most Info files are stored.  By
255 default, Info documentation is placed in @file{/usr/local/info}.
257 Some of these files are available individually via FTP or e-mail; see
258 @ref{Informational files for Emacs}.  They all are available in the
259 source distribution.  Many of the files in the @file{etc} directory are
260 also available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?}
261 (@kbd{M-x help-for-help}).
263 Your system administrator may have removed the @file{src} directory and
264 many files from the @file{etc} directory.
266 @node Common acronyms,  , File-name conventions, FAQ notation
267 @section What are FSF, LPF, OSF, GNU, RMS, FTP, and GPL?
268 @cindex FSF, definition of
269 @cindex LPF, definition of
270 @cindex OSF, definition of
271 @cindex GNU, definition of
272 @cindex RMS, definition of
273 @cindex Stallman, Richard, acronym for
274 @cindex Richard Stallman, acronym for
275 @cindex FTP, definition of
276 @cindex GPL, definition of
277 @cindex Acronyms, definitions for
278 @cindex Common acronyms, definitions for
280 @table @asis
282 @item FSF
283 Free Software Foundation
285 @item LPF
286 League for Programming Freedom
288 @item OSF
289 Open Software Foundation
291 @item GNU
292 GNU's Not Unix
294 @item RMS
295 Richard Matthew Stallman
297 @item FTP
298 File Transfer Protocol
300 @item GPL
301 GNU General Public License
303 @end table
305 Avoid confusing the FSF, the LPF, and the OSF.  The LPF opposes
306 look-and-feel copyrights and software patents.  The FSF aims to make
307 high quality free software available for everyone.  The OSF is a
308 consortium of computer vendors which develops commercial software for
309 Unix systems.
311 The word ``free'' in the title of the Free Software Foundation refers to
312 ``freedom,'' not ``zero dollars.''  Anyone can charge any price for
313 GPL-covered software that they want to.  However, in practice, the
314 freedom enforced by the GPL leads to low prices, because you can always
315 get the software for less money from someone else, since everyone has
316 the right to resell or give away GPL-covered software.
318 @c ------------------------------------------------------------
319 @node    General questions, Getting help, FAQ notation, Top
320 @chapter General questions
321 @cindex General questions
323 This chapter contains general questions having to do with Emacs, the
324 Free Software Foundation, and related organizations.
326 @menu
327 * The LPF::
328 * Real meaning of copyleft::
329 * Guidelines for newsgroup postings::
330 * Newsgroup archives::
331 * Reporting bugs::
332 * Unsubscribing from Emacs lists::
333 * Contacting the FSF::
334 @end menu
336 @node The LPF, Real meaning of copyleft, General questions, General questions
337 @section What is the LPF?
338 @cindex LPF, description of
339 @cindex League for Programming Freedom
340 @cindex Software patents, opposition to
341 @cindex Patents for software, opposition to
343 The LPF opposes the expanding danger of software patents and
344 look-and-feel copyrights.  To get more information, feel free to contact
345 the LPF via e-mail or otherwise.  You may also contact
346 @email{jbw@@cs.bu.edu, Joe Wells}; he will be happy to talk to you
347 about the LPF.
349 You can find more information about the LPF in the file @file{etc/LPF}.
350 More papers describing the LPF's views are available on the Internet and
351 also from @uref{http://lpf.ai.mit.edu/, the LPF home page}.
353 @node Real meaning of copyleft, Guidelines for newsgroup postings, The LPF, General questions
354 @section What is the real legal meaning of the GNU copyleft?
355 @cindex Copyleft, real meaning of
356 @cindex GPL, real meaning of
357 @cindex General Public License, real meaning of
358 @cindex Discussion of the GPL
360 The real legal meaning of the GNU General Public License (copyleft) will
361 only be known if and when a judge rules on its validity and scope.
362 There has never been a copyright infringement case involving the GPL to
363 set any precedents.  Please take any discussion regarding this issue to
364 the newsgroup @uref{news:gnu.misc.discuss}, which was created to hold the
365 extensive flame wars on the subject.
367 RMS writes:
369 @quotation
370 The legal meaning of the GNU copyleft is less important than the spirit,
371 which is that Emacs is a free software project and that work pertaining
372 to Emacs should also be free software.  ``Free'' means that all users
373 have the freedom to study, share, change and improve Emacs.  To make
374 sure everyone has this freedom, pass along source code when you
375 distribute any version of Emacs or a related program, and give the
376 recipients the same freedom that you enjoyed.
377 @end quotation
379 @node Guidelines for newsgroup postings, Newsgroup archives, Real meaning of copyleft, General questions
380 @section  What are appropriate messages for @uref{news:gnu.emacs.help}, @uref{news:gnu.emacs.bug}, @uref{news:comp.emacs}, etc.?
381 @cindex Newsgroups, appropriate messages for
382 @cindex GNU newsgroups, appropriate messages for
383 @cindex Usenet groups, appropriate messages for
384 @cindex Mailing lists, appropriate messages for
385 @cindex Posting messages to newsgroups
387 @cindex GNU mailing lists
388 The file @file{etc/MAILINGLISTS} describes the purpose of each GNU
389 mailing list.  (@xref{Informational files for Emacs}, if you want a copy
390 of the file.)  For those lists which are gatewayed with newsgroups, it
391 lists both the newsgroup name and the mailing list address.
393 The newsgroup @uref{news:comp.emacs} is for discussion of Emacs programs
394 in general.  This includes Emacs along with various other
395 implementations, such as XEmacs, JOVE, MicroEmacs, Freemacs, MG,
396 Unipress, CCA, and Epsilon.
398 Many people post Emacs questions to @uref{news:comp.emacs} because they
399 don't receive any of the @code{gnu.*} newsgroups.  Arguments have been
400 made both for and against posting GNU-Emacs-specific material to
401 @uref{news:comp.emacs}.  You have to decide for yourself.
403 Messages advocating ``non-free'' software are considered unacceptable on
404 any of the @code{gnu.*} newsgroups except for @uref{news:gnu.misc.discuss},
405 which was created to hold the extensive flame-wars on the subject.
406 ``Non-free'' software includes any software for which the end user can't
407 freely modify the source code and exchange enhancements.  Be careful to
408 remove the @code{gnu.*} groups from the @samp{Newsgroups:} line when
409 posting a followup that recommends such software.
411 @uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid
412 posting bug reports to this newsgroup directly (@pxref{Reporting bugs}).
414 @node Newsgroup archives, Reporting bugs, Guidelines for newsgroup postings, General questions
415 @section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups?
416 @cindex Archived postings from @code{gnu.emacs.help}
417 @cindex Usenet archives for GNU groups
418 @cindex Old Usenet postings for GNU groups
420 The FSF has maintained archives of all of the GNU mailing lists for many
421 years, although there may be some unintentional gaps in coverage.  The
422 archive is not particularly well organized or easy to retrieve
423 individual postings from, but pretty much everything is there.
425 The archive is at @uref{ftp://ftp-mailing-list-archives.gnu.org}.
427 The archive can be browsed over the web at 
428 @uref{http://mail.gnu.org/archive/html/, the GNU mail archive}.
430 Web-based Usenet search services, such as
431 @uref{http://groups.google.com, Google}, also archive the
432 @code{gnu.*} groups.
434 @node Reporting bugs, Unsubscribing from Emacs lists, Newsgroup archives, General questions
435 @section Where should I report bugs and other problems with Emacs?
436 @cindex Bug reporting
437 @cindex Good bug reports
438 @cindex How to submit a bug report
439 @cindex Reporting bugs
441 The correct way to report Emacs bugs is by e-mail to
442 @email{bug-gnu-emacs@@gnu.org}.  Anything sent here also appears in the
443 newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of
444 news to submit the bug report.  This ensures a reliable return address
445 so you can be contacted for further details.
447 Be sure to read the ``Bugs'' section of the Emacs manual before reporting
448 a bug to bug-gnu-emacs!  The manual describes in detail how to submit a
449 useful bug report.  (@xref{On-line manual}, if you don't know how to read the
450 manual.)
452 RMS says:
454 @quotation
455 Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the
456 effect of posting on @uref{news:gnu.emacs.help}) is undesirable because
457 it takes the time of an unnecessarily large group of people, most of
458 whom are just users and have no idea how to fix these problem.
459 @email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people
460 who are more likely to know what to do and have expressed a wish to
461 receive more messages about Emacs than the others.
462 @end quotation
464 RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}:
466 @quotation
467 If you have reported a bug and you don't hear about a possible fix,
468 then after a suitable delay (such as a week) it is okay to post on
469 @code{gnu.emacs.help} asking if anyone can help you.
470 @end quotation
472 If you are unsure whether you have found a bug, consider the following
473 non-exhaustive list, courtesy of RMS:
475 @quotation
476 If Emacs crashes, that is a bug.  If Emacs gets compilation errors
477 while building, that is a bug.  If Emacs crashes while building, that
478 is a bug.  If Lisp code does not do what the documentation says it
479 does, that is a bug.
480 @end quotation
482 @node Unsubscribing from Emacs lists, Contacting the FSF, Reporting bugs, General questions
483 @section  How do I unsubscribe from this mailing list?
484 @cindex Unsubscribing from GNU mailing lists
485 @cindex Removing yourself from GNU mailing lists
487 If you are receiving a GNU mailing list named @var{list}, you might be
488 able to unsubscribe from it by sending a request to the address
489 @email{@var{list}-request@@gnu.org}.  However, this will not work if you are
490 not listed on the main mailing list, but instead receive the mail from a
491 distribution point.  In that case, you will have to track down at which
492 distribution point you are listed.  Inspecting the @samp{Received} headers
493 on the mail messages may help, along with liberal use of the @samp{EXPN} or
494 @samp{VRFY} sendmail commands through @samp{telnet @var{site-address}
495 smtp}.  Ask your postmaster for help, if you cannot figure out these
496 details.
498 @node Contacting the FSF,  , Unsubscribing from Emacs lists, General questions
499 @section  What is the current address of the FSF?
500 @cindex Snail mail address of the FSF
501 @cindex Postal address of the FSF
502 @cindex Contracting the FSF
503 @cindex Free Software Foundation, contacting
505 @table @asis
507 @item E-mail
508 gnu@@gnu.org
510 @item Telephone
511 +1-617-542-5942
513 @item Fax
514 +1-617-542-2652
516 @item World Wide Web
517 @uref{http://www.gnu.org/}
519 @item Postal address
520 Free Software Foundation@*
521 59 Temple Place - Suite 330@*
522 Boston, MA 02111-1307@*
523 USA@*
525 @end table
527 @cindex Ordering GNU software
528 For details on how to order items directly from the FSF, see the
529 @uref{http://www.gnu.org/order/order.html, GNU Web site}.
531 @c ------------------------------------------------------------
532 @node Getting help, Status of Emacs, General questions, Top
533 @chapter Getting help
534 @cindex Getting help
536 This chapter tells you how to get help with Emacs
538 @menu
539 * Basic editing::
540 * Learning how to do something::
541 * Getting a printed manual::
542 * Emacs Lisp documentation::
543 * Installing Texinfo documentation::
544 * Printing a Texinfo file::
545 * Viewing Info files outside of Emacs::
546 * Informational files for Emacs::
547 * Help installing Emacs::
548 * Obtaining the FAQ::
549 @end menu
551 @node Basic editing, Learning how to do something, Getting help, Getting help
552 @section I'm just starting Emacs; how do I do basic editing?
553 @cindex Basic editing with Emacs
554 @cindex Beginning editing
555 @cindex Tutorial, invoking the
556 @cindex Self-paced tutorial, invoking the
557 @cindex Help system, entering the
559 Type @kbd{C-h t} to invoke the self-paced tutorial.  Just typing @kbd{C-h}
560 enters the help system.
562 Your system administrator may have changed @kbd{C-h} to act like
563 @key{DEL} to deal with local keyboards.  You can use @kbd{M-x
564 help-for-help} instead to invoke help.  To discover what key (if any)
565 invokes help on your system, type @kbd{M-x where-is @key{RET}
566 help-for-help @key{RET}}.  This will print a comma-separated list of key
567 sequences in the echo area.  Ignore the last character in each key
568 sequence listed.  Each of the resulting key sequences invokes help.
570 Emacs help works best if it is invoked by a single key whose value
571 should be stored in the variable @code{help-char}.
573 There is also a WWW-based tutorial for Emacs 18, much of which is also
574 relevant for later versions of Emacs, available at
576 @uref{http://kufacts.cc.ukans.edu/cwis/writeups/misc/emacsguide.html}
578 @node Learning how to do something, Getting a printed manual, Basic editing, Getting help
579 @section How do I find out how to do something in Emacs?
580 @cindex Help for Emacs
581 @cindex Learning to do something in Emacs
582 @cindex Reference card for Emacs
583 @cindex Overview of help systems
585 There are several methods for finding out how to do things in Emacs.
587 @itemize @bullet
589 @cindex Reading the Emacs manual
590 @item
591 The complete text of the Emacs manual is available on-line via the Info
592 hypertext reader.  Type @kbd{C-h i} to invoke Info.  Typing @key{h}
593 immediately after entering Info will provide a short tutorial on how to
594 use it.
596 @cindex Lookup a subject in a manual
597 @cindex Index search in a manual
598 @item
599 To quickly locate the section of the manual which discusses a certain
600 issue, or describes a command or a variable, type @kbd{C-h i m emacs
601 @key{RET} i @var{topic} @key{RET}}, where @var{topic} is the name of the
602 topic, the command, or the variable which you are looking for.  If this
603 does not land you on the right place in the manual, press @kbd{,}
604 (comma) repeatedly until you find what you need.  (The @kbd{i} and
605 @kbd{,} keys invoke the index-searching functions, which look for the
606 @var{topic} you type in all the indices of the Emacs manual.)
608 @cindex Apropos
609 @item
610 You can list all of the commands whose names contain a certain word
611 (actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x
612 command-apropos}).
614 @cindex Command description in the manual
615 @item
616 The command @kbd{C-h C-f} (@code{Info-goto-emacs-command-node}) prompts
617 for the name of a command, and then attempts to find the section in the
618 Emacs manual where that command is described.
620 @cindex Finding commands and variables
621 @item
622 You can list all of the functions and variables whose names contain a
623 certain word using @kbd{M-x apropos}.
625 @item
626 You can list all of the functions and variables whose documentation
627 matches a regular expression or a string, using @kbd{M-x
628 apropos-documentation}.
630 @item
631 You can order a hardcopy of the manual from the FSF.  @xref{Getting a
632 printed manual}.
634 @cindex Reference cards, in other languages
635 @item
636 You can get a printed reference card listing commands and keys to
637 invoke them.  You can order one from the FSF for $1 (or 10 for $5),
638 or you can print your own from the @file{etc/refcard.tex} or
639 @file{etc/refcard.ps} files in the Emacs distribution.  Beginning with
640 version 21.1, the Emacs distribution comes with translations of the
641 reference card into several languages; look for files named
642 @file{etc/@var{lang}-refcard.*}, where @var{lang} is a two-letter code
643 of the language.  For example, the German version of the reference card
644 is in the files @file{etc/de-refcard.tex} and @file{etc/de-refcard.ps}.
646 @item
647 There are many other commands in Emacs for getting help and
648 information.  To get a list of these commands, type @samp{?} after
649 @kbd{C-h}.
651 @end itemize
653 @node Getting a printed manual, Emacs Lisp documentation, Learning how to do something, Getting help
654 @section How do I get a printed copy of the Emacs manual?
655 @cindex Printed Emacs manual, obtaining
656 @cindex Manual, obtaining a printed or HTML copy of
657 @cindex Emacs manual, obtaining a printed or HTML copy of
659 You can order a printed copy of the Emacs manual from the FSF.  For
660 details see the @uref{http://www.gnu.org/order/order.html, GNU Web site}.
662 @c The number 620 below is version-dependent!
663 The full Texinfo source for the manual also comes in the @file{man}
664 directory of the Emacs distribution, if you're daring enough to try to
665 print out this 620-page manual yourself (@pxref{Printing a Texinfo
666 file}).
668 If you absolutely have to print your own copy, and you don't have @TeX{},
669 you can get a PostScript version from
671 @uref{http://www.gnu.org/manual/emacs/ps/emacs.ps.gz}
673 @cindex HTML version of Emacs manual, obtaining
674 An HTML version of the manual is at
676 @uref{www.gnu.org/manual/emacs/index.html}
678 @xref{Learning how to do something}, for how to view the manual on-line.
680 @node Emacs Lisp documentation, Installing Texinfo documentation, Getting a printed manual, Getting help
681 @section Where can I get documentation on Emacs Lisp?
682 @cindex Documentation on Emacs Lisp
683 @cindex Function documentation
684 @cindex Variable documentation
685 @cindex Emacs Lisp Reference Manual
686 @cindex Reference manual for Emacs Lisp
688 Within Emacs, you can type @kbd{C-h f} to get the documentation for a
689 function, @kbd{C-h v} for a variable.
691 For more information, obtain the Emacs Lisp Reference Manual.  Details
692 on ordering it from FSF are on the
693 @uref{http://www.gnu.org/order/order.html, GNU Web site}.
695 The Emacs Lisp Reference Manual is also available on-line, in Info
696 format.  Texinfo source for the manual (along with pregenerated Info
697 files) is available at
699 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/elisp-manual-21-2.6.tar.gz}
701 and all mirrors of @samp{ftp.gnu.org} (for a list, @pxref{Current GNU
702 distributions}).  @xref{Installing Texinfo documentation}, if you want
703 to install the Info files, or @ref{Printing a Texinfo file}, if you want
704 to use the Texinfo source to print the manual yourself.
706 An HTML version of the Emacs Lisp Reference Manual is available at
708 @uref{http://www.gnu.org/manual/elisp-manual-21-2.6/elisp.html}
710 @node Installing Texinfo documentation, Printing a Texinfo file, Emacs Lisp documentation, Getting help
711 @section How do I install a piece of Texinfo documentation?
712 @cindex Texinfo documentation, installing
713 @cindex Installing Texinfo documentation
714 @cindex New Texinfo files, installing
715 @cindex Documentation, installing new Texinfo files
716 @cindex Info files, how to install
718 First, you must turn the Texinfo files into Info files.  You may do this
719 using the stand-alone @file{makeinfo} program, available as part of the latest
720 Texinfo package at
722 @uref{ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-4.0.tar.gz}
724 and all mirrors of @samp{ftp.gnu.org} (for a list, @pxref{Current GNU
725 distributions}).
727 For information about the Texinfo format, read the Texinfo manual which
728 comes with the Texinfo package.  This manual also comes installed in
729 Info format, so you can read it on-line; type @kbd{C-h i m texinfo
730 @key{RET}}.
732 Alternatively, you could use the Emacs command @kbd{M-x
733 texinfo-format-buffer}, after visiting the Texinfo source file of the
734 manual you want to convert.
736 Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the
737 resulting Info files in Emacs's Info tree.  To install Info files,
738 perform these steps:
740 @enumerate
741 @item
742 Move the files to the @file{info} directory in the installed Emacs
743 distribution.  @xref{File-name conventions}, if you don't know where that
746 @item
747 Run the @code{install-info} command, which is part of the Texinfo
748 distribution, to update the main Info directory menu, like this:
750 @example
751  install-info --info-dir=@var{dir-path} @var{dir-path}/@var{file}
752 @end example
754 @noindent
755 where @var{dir-path} is the full path to the directory where you copied
756 the produced Info file(s), and @var{file} is the name of the Info file
757 you produced and want to install.
759 If you don't have the @code{install-info} command installed, you can
760 edit the file @file{info/dir} in the installed Emacs distribution, and
761 add a line for the top level node in the Info package that you are
762 installing.  Follow the examples already in this file.  The format is:
764 @example
765 * Topic: (relative-pathname).  Short description of topic.
766 @end example
768 @end enumerate
770 If you want to install Info files and you don't have the necessary
771 privileges, you have several options:
773 @itemize @bullet
774 @item
775 Info files don't actually need to be installed before being used.  You
776 can feed a file name to the @code{Info-goto-node} command (invoked by
777 pressing @key{g} in Info mode) by typing the name of the file in
778 parentheses.  This goes to the node named ``Top'' in that file.  For
779 example, to view a Info file named @file{@var{info-file}} in your home
780 directory, you can type this:
782 @example
783 @kbd{C-h i g (~/@var{info-file}) @key{RET}}
784 @end example
786 @item
787 You can create your own Info directory.  You can tell Emacs where that
788 Info directory is by adding its pathname to the value of the variable
789 @code{Info-default-directory-list}.  For example, to use a private Info
790 directory which is a subdirectory of your home directory named @file{Info},
791 you could put this in your @file{.emacs} file:
793 @lisp
794 (setq Info-default-directory-list
795       (cons "~/Info" Info-default-directory-list))
796 @end lisp
798 You will need a top-level Info file named @file{dir} in this directory
799 which has everything the system @file{dir} file has in it, except it should
800 list only entries for Info files in that directory.  You might not need
801 it if all files in this directory were referenced by other @file{dir}
802 files.  The node lists from all @file{dir} files in
803 @code{Info-default-directory-list} are merged by the Info system.
805 @end itemize
807 @node Printing a Texinfo file, Viewing Info files outside of Emacs, Installing Texinfo documentation, Getting help
808 @section How do I print a Texinfo file?
809 @cindex Printing a Texinfo file
810 @cindex Texinfo file, printing
811 @cindex Printing documentation
813 You can't get nicely printed output from Info files; you must still have
814 the original Texinfo source file for the manual you want to print.
816 Assuming you have @TeX{} installed on your system, follow these steps:
818 @enumerate
820 @item
821 Make sure the first line of the Texinfo file looks like this:
823 @example
824 \input texinfo
825 @end example
827 You may need to change @samp{texinfo} to the full pathname of the
828 @file{texinfo.tex} file, which comes with Emacs as
829 @file{man/texinfo.tex} (or copy or link it into the current directory).
831 @item
832 Type @kbd{texi2dvi @var{texinfo-source}}, where @var{texinfo-source} is
833 the name of the Texinfo source file for which you want to produce a
834 printed copy.
836 The @samp{texi2dvi} script is part of the GNU Texinfo distribution
837 (@pxref{Installing Texinfo documentation}).
839 @item
840 Print the DVI file @file{@var{texinfo-source}.dvi} in the normal way for
841 printing DVI files at your site.  For example, if you have a PostScript
842 printer, run the @code{dvips} program to print the DVI file on that
843 printer.
845 @end enumerate
847 To get more general instructions, retrieve the latest Texinfo package
848 (@pxref{Installing Texinfo documentation}).
850 @node Viewing Info files outside of Emacs, Informational files for Emacs, Printing a Texinfo file, Getting help
851 @section Can I view Info files without using Emacs?
852 @cindex Viewing Info files
853 @cindex Info file viewers
854 @cindex Alternative Info file viewers
856 Yes.  Here are some alternative programs:
858 @itemize @bullet
860 @item
861 @code{info}, a stand-alone version of the Info program, comes as part of
862 the Texinfo package.  @xref{Installing Texinfo documentation}, for
863 details.
865 @item
866 Xinfo, a stand-alone version of the Info program that runs under X
867 Window system.  You can get it at
868 @uref{ftp://ftp.gnu.org/pub/gnu/xinfo/xinfo-1.01.01.tar.gz} and all
869 mirrors of @samp{ftp.gnu.org} (see @ref{Current GNU distributions}, for a
870 list of mirrors).
872 @item
873 Tkinfo, an Info viewer that runs under X Window system and uses Tcl/Tk.
874 You can get Tkinfo at
875 @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}.
877 @end itemize
879 @node Informational files for Emacs, Help installing Emacs, Viewing Info files outside of Emacs, Getting help
880 @section What informational files are available for Emacs?
881 @cindex Informational files included with Emacs
882 @cindex Files included with Emacs
883 @cindex @file{COPYING}, description of file
884 @cindex @file{DISTRIB}, description of file
885 @cindex @file{FTP}, description of file
886 @cindex @file{GNU}, description of file
887 @cindex @file{INTERVIEW}, description of file
888 @cindex @file{LPF}, description of file
889 @cindex @file{MACHINES}, description of file
890 @cindex @file{MAILINGLISTS}, description of file
891 @cindex @file{NEWS}, description of file
892 @cindex @file{SERVICE}, description of file
893 @cindex @file{SUN-SUPPORT}, description of file
895 This isn't a frequently asked question, but it should be!  A variety of
896 informational files about Emacs and relevant aspects of the GNU project
897 are available for you to read.
899 The following files are available in the @file{etc} directory of the
900 Emacs distribution (see @ref{File-name conventions}, if you're not sure
901 where that is).
903 @table @file
905 @item COPYING
906 Emacs General Public License
908 @item DISTRIB
909 Emacs Availability Information, including the popular "Free Software
910 Foundation Order Form"
912 @item FTP
913 How to get GNU Software by Internet FTP or by UUCP
915 @item GNU
916 The GNU Manifesto
918 @item INTERVIEW
919 Richard Stallman discusses his public-domain UNIX-compatible software
920 system with BYTE editors
922 @item LPF
923 Why you should join the League for Programming Freedom
925 @item MACHINES
926 Status of Emacs on Various Machines and Systems
928 @item MAILINGLISTS
929 GNU Project Electronic Mailing Lists
931 @item NEWS
932 Emacs news, a history of recent user-visible changes
934 @item SERVICE
935 GNU Service Directory
937 @item SUN-SUPPORT
938 including "Using Emacstool with GNU Emacs"
940 @end table
942 Latest versions of the above files also available at
944 @uref{ftp://ftp.gnu.org/pub/gnu/GNUinfo/}
946 More GNU information, including back issues of the @cite{GNU's
947 Bulletin}, are at
949 @uref{http://www.gnu.org/bulletins/bulletins.html} and
951 @uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html}
953 @node Help installing Emacs, Obtaining the FAQ, Informational files for Emacs, Getting help
954 @section Where can I get help in installing Emacs?
955 @cindex Installation help
956 @cindex Help installing Emacs
958 @xref{Installing Emacs}, for some basic installation hints, and see
959 @ref{Problems building Emacs}, or @ref{Linking with -lX11 fails}, if you
960 have problems with the installation.
962 The file @file{etc/SERVICE} (see @ref{File-name conventions}, if you're
963 not sure where that is) lists companies and individuals willing to sell
964 you help in installing or using Emacs.  An up-to-date version this file
965 is available on @samp{ftp.gnu.org} (@pxref{Informational files for
966 Emacs}).
968 @node Obtaining the FAQ,  , Help installing Emacs, Getting help
969 @section Where can I get the latest version of this FAQ?
970 @cindex FAQ, obtaining the
971 @cindex Latest FAQ version, obtaining the
972 @cindex Retrieving the latest FAQ version
973 @cindex E-mail, retrieving the FAQ via
974 @cindex Web, reading the FAQ on the
976 The Emacs FAQ is available in several ways:
978 @itemize @bullet
980 @item
981 Inside of Emacs itself.  You can get it from selecting the @samp{Emacs
982 FAQ} option from the @samp{Help} menu of the Emacs menu bar at the top
983 of any Emacs frame, or by typing @kbd{C-h F} (@kbd{M-x view-emacs-FAQ}).
985 @item
986 Via USENET.  If you can read news, the FAQ should be available in your
987 news spool, in both the @uref{news:gnu.emacs.help} and
988 @uref{news:comp.emacs} newsgroups.  Every news reader should allow you
989 to read any news article that is still in the news spool, even if you
990 have read the article before.  You may need to read the instructions for
991 your news reader to discover how to do this.  In @file{rn}, this command
992 will do this for you at the article selection level:
994 @example
995 ?GNU Emacs Frequently Asked Questions?rc:m
996 @end example
998 In Gnus, you should type @kbd{C-u C-x C-s} from the @file{*Summary*}
999 buffer or @kbd{C-u @key{SPC}} from the @file{*Newsgroup*} buffer to view
1000 all articles in a newsgroup.
1002 If the FAQ articles have expired and have been deleted from your news
1003 spool, it might (or might not) do some good to complain to your news
1004 administrator, because the most recent FAQ should not expire for a
1005 while.
1007 @item
1008 Via HTTP or FTP.  You can always fetch the latest FAQ from
1010 @uref{http://www.lerner.co.il/emacs/} and
1012 @uref{ftp://ftp.lerner.co.il/pub/emacs/}
1014 @item
1015 In the Emacs distribution.  Since Emacs 18.56, the FAQ at the time
1016 of release has been part of the Emacs distribution as either
1017 @file{etc/FAQ} or @file{man/faq.texi} (@pxref{File-name conventions}).
1019 @item
1020 Via the World Wide Web.  A hypertext version is available at
1022 @uref{http://www.lerner.co.il/emacs/}
1024 @item
1025 Via anonymous ftp and e-mail from @file{rtfm.mit.edu} (and its mirror in
1026 Europe), the main repository for FAQs and other items posted to
1027 news.answers.  The Emacs FAQs are available at
1029 @uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} and
1031 @uref{ftp://ftp.uni-paderborn.de/pub/doc/FAQ/comp/emacs/}
1033 If you do not have access to anonymous FTP, you can access the archives
1034 using the @file{rtfm.mit.edu} mail server.  The Emacs FAQ can be
1035 retrieved by sending mail to @email{mail-server@@rtfm.mit.edu} with a
1036 blank subject and containing
1038 @example
1039 send usenet/news.answers/GNU-Emacs-FAQ/diffs
1040 send usenet/news.answers/GNU-Emacs-FAQ/part1
1041 send usenet/news.answers/GNU-Emacs-FAQ/part2
1042 send usenet/news.answers/GNU-Emacs-FAQ/part3
1043 send usenet/news.answers/GNU-Emacs-FAQ/part4
1044 send usenet/news.answers/GNU-Emacs-FAQ/part5
1045 @end example
1047 For more information, send email to @email{mail-server@@rtfm.mit.edu}
1048 with "help" and "index" in the body on separate lines.
1050 @item
1051 As the very last resort, you can e-mail a request to
1052 @email{emacs-faq@@lerner.co.il}.  Don't do this unless you have made a
1053 good-faith effort to obtain the FAQ list via one of the methods listed
1054 above.
1056 @end itemize
1058 @c ------------------------------------------------------------
1059 @node    Status of Emacs, Common requests, Getting help, Top
1060 @chapter Status of Emacs
1061 @cindex Status of Emacs
1063 This chapter gives you basic information about Emacs, including its
1064 latest version status.
1066 @menu
1067 * Origin of the term Emacs::
1068 * Latest version of Emacs::
1069 * New in Emacs 20::
1070 * New in Emacs 21::
1071 @end menu
1073 @node Origin of the term Emacs, Latest version of Emacs, Status of Emacs, Status of Emacs
1074 @section Where does the name ``Emacs'' come from?
1075 @cindex Origin of the term ``Emacs''
1076 @cindex Emacs name origin
1077 @cindex TECO
1078 @cindex Original version of Emacs
1080 Emacs originally was an acronym for Editor MACroS.  RMS says he ``picked
1081 the name Emacs because @key{E} was not in use as an abbreviation on ITS at
1082 the time.''  The first Emacs was a set of macros written in 1976 at MIT
1083 by RMS for the editor TECO (Text Editor and COrrector, originally Tape
1084 Editor and COrrector) under ITS on a PDP-10.  RMS had already extended
1085 TECO with a ``real-time'' full-screen mode with reprogrammable keys.
1086 Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project
1087 to unify the many divergent TECO command sets and key bindings at MIT,
1088 and completed by RMS.
1090 Many people have said that TECO code looks a lot like line noise; you
1091 can read more at @uref{news:alt.lang.teco}.  Someone has written a TECO
1092 implementation in Emacs Lisp (to find it, see @ref{Packages that do not
1093 come with Emacs}); it would be an interesting project to run the
1094 original TECO Emacs inside of Emacs.
1096 @cindex Why Emacs?
1097 For some not-so-serious alternative reasons for Emacs to have that
1098 name, check out the file @file{etc/JOKES} (@pxref{File-name
1099 conventions}).
1101 @node Latest version of Emacs, New in Emacs 20, Origin of the term Emacs, Status of Emacs
1102 @section What is the latest version of Emacs?
1103 @cindex Version, latest
1104 @cindex Latest version of Emacs
1106 Emacs @value{VER} is the current version as of this writing.
1108 @node New in Emacs 20,  New in Emacs 21, Latest version of Emacs, Status of Emacs
1109 @section What is different about Emacs 20?
1110 @cindex Differences between Emacs 19 and Emacs 20
1111 @cindex Emacs 20, new features in
1113 To find out what has changed in recent versions, type @kbd{C-h n}
1114 (@kbd{M-x view-emacs-news}).  The oldest changes are at the bottom of
1115 the file, so you might want to read it starting there, rather than at
1116 the top.
1118 The differences between Emacs versions 18 and 19 was rather dramatic;
1119 the introduction of frames, faces, and colors on windowing systems was
1120 obvious to even the most casual user.
1122 There are differences between Emacs versions 19 and 20 as well, but many
1123 are more subtle or harder to find.  Among the changes are the inclusion
1124 of MULE code for languages that use non-Latin characters and for mixing
1125 several languages in the same document; the ``Customize'' facility for
1126 modifying variables without having to use Lisp; and automatic conversion
1127 of files from Macintosh, Microsoft, and Unix platforms.
1129 A number of older Lisp packages, such as Gnus, Supercite and the
1130 calendar/diary, have been updated and enhanced to work with Emacs 20,
1131 and are now included with the standard distribution.
1134 @node New in Emacs 21, , New in Emacs 20, Status of Emacs
1135 @section What is different about Emacs 21?
1136 @cindex Differences between Emacs 20 and Emacs 21
1137 @cindex Emacs 21, new features in
1138 @cindex Recently introduced features
1140 @cindex Variable-size fonts
1141 @cindex Toolbar support
1142 Emacs 21 features a thorough rewrite of the display engine.  The new
1143 display engine supports variable-size fonts, images, and can play sounds
1144 on platforms which support that.  As a result, the visual appearance of
1145 Emacs, when it runs on a windowed display, is much more reminiscent of
1146 modern GUI programs, and includes 3D widgets (used for the mode line and
1147 the scroll bars), a configurable and extensible toolbar, tooltips
1148 (a.k.a.@: balloon help), and other niceties.
1150 @cindex Colors on text-only terminals
1151 @cindex TTY colors
1152 In addition, Emacs 21 supports faces on text-only terminals.  This means
1153 that you can now have colors when you run Emacs on a GNU/Linux console
1154 and on @code{xterm} with @kbd{emacs -nw}.
1156 @c ------------------------------------------------------------
1157 @node    Common requests, Bugs and problems, Status of Emacs, Top
1158 @chapter Common requests
1159 @cindex Common requests
1161 @menu
1162 * Setting up a customization file::
1163 * Debugging a customization file::
1164 * Colors on a TTY::
1165 * Displaying the current line or column::
1166 * Displaying the current file name in the titlebar::
1167 * Turning on abbrevs by default::
1168 * Turning on auto-fill by default::
1169 * Associating modes with files::
1170 * Working with unprintable characters::
1171 * Highlighting a region::
1172 * Controlling case sensitivity::
1173 * Wrapping words automatically::
1174 * Spell-checkers::
1175 * Checking TeX and *roff documents::
1176 * Changing load-path::
1177 * Using an already running Emacs process::
1178 * Compiler error messages::
1179 * Indenting switch statements::
1180 * Customizing C and C++ indentation::
1181 * Horizontal scrolling::
1182 * Overwrite mode::
1183 * Turning off beeping::
1184 * Turning the volume down::
1185 * Automatic indentation::
1186 * Matching parentheses::
1187 * Hiding #ifdef lines::
1188 * Repeating commands::
1189 * Valid X resources::
1190 * Evaluating Emacs Lisp code::
1191 * Changing the length of a Tab::
1192 * Inserting > at the beginning of each line::
1193 * Underlining paragraphs::
1194 * Repeating a command as many times as possible::
1195 * Forcing the cursor to remain in the same column::
1196 * Forcing Emacs to iconify itself::
1197 * Using regular expressions::
1198 * Replacing text across multiple files::
1199 * Documentation for etags::
1200 * Disabling backups::
1201 * Disabling auto-save-mode::
1202 * Going to a line by number::
1203 * Modifying pull-down menus::
1204 * Deleting menus and menu options::
1205 * Turning on syntax highlighting::
1206 * Scrolling only one line::
1207 * Replacing highlighted text::
1208 * Editing MS-DOS files::
1209 * Filling paragraphs with a single space::
1210 * Escape sequences in shell output::
1211 @end menu
1213 @node Setting up a customization file, Colors on a TTY, Common requests, Common requests
1214 @section How do I set up a @file{.emacs} file properly?
1215 @cindex @file{.emacs} file, setting up
1216 @cindex @file{.emacs} file, locating
1217 @cindex Init file, setting up
1218 @cindex Customization file, setting up
1220 @inforef{Init File, Init File, emacs}.
1222 In general, new Emacs users should not have @file{.emacs} files, because
1223 it causes confusing non-standard behavior.  Then they send questions to
1224 @email{help-gnu-emacs@@gnu.org} asking why Emacs isn't behaving as
1225 documented.
1227 Beginning with version 20.1, Emacs includes the new Customize
1228 facility, which can be invoked using @kbd{M-x customize @key{RET}}.
1229 This allows users who are unfamiliar with Emacs Lisp to modify their
1230 @file{.emacs} files in a relatively straightforward way, using menus
1231 rather than Lisp code.  Not all packages support Customize as of this
1232 writing, but the number is growing fairly steadily.
1234 While Customize might indeed make it easier to configure Emacs,
1235 consider taking a bit of time to learn Emacs Lisp and modifying your
1236 @file{.emacs} directly.  Simple configuration options are described
1237 rather completely in @inforef{Init File, Init File, emacs}, for users
1238 interested in performing frequently requested, basic tasks.
1240 Sometimes users are unsure as to where their @file{.emacs} file should
1241 be found.  Visiting the file as @file{~/.emacs} from Emacs will find
1242 the correct file.
1244 @node Colors on a TTY, Debugging a customization file, Setting up a customization file, Common requests
1245 @section How do I get colors and syntax highlighting on a TTY?
1246 @cindex Colors on a TTY
1247 @cindex Syntax highlighting on a TTY
1248 @cindex Console, colors
1250 In Emacs 21.1 and later, colors and faces are supported in non-windowed mode,
1251 i.e.@: on Unix and GNU/Linux text-only terminals and consoles, and when
1252 invoked as @samp{emacs -nw} on X and MS-Windows.  (Colors and faces were
1253 supported in the MS-DOS port since Emacs 19.29.)  Emacs automatically
1254 detects color support at startup and uses it if available.  If you think
1255 that your terminal supports colors, but Emacs won't use them, check the
1256 @code{termcap} entry for your display type for color-related
1257 capabilities.
1259 The command @kbd{M-x list-colors-display} pops up a window which
1260 exhibits all the colors Emacs knows about on the current display.
1262 Syntax highlighting is usually turned off by default; see @ref{Turning
1263 on syntax highlighting}, for instructions how to turn it on.
1265 @node Debugging a customization file, Displaying the current line or column, Colors on a TTY, Common requests
1266 @section How do I debug a @file{.emacs} file?
1267 @cindex Debugging @file{.emacs} file
1268 @cindex @file{.emacs} debugging
1269 @cindex Init file debugging
1270 @cindex @samp{-debug-init} option
1272 Start Emacs with the @samp{-debug-init} command-line option.  This
1273 enables the Emacs Lisp debugger before evaluating your @file{.emacs}
1274 file, and places you in the debugger if something goes wrong.  The top
1275 line in the @file{trace-back} buffer will be the error message, and the
1276 second or third line of that buffer will display the Lisp code from your
1277 @file{.emacs} file that caused the problem.
1279 You can also evaluate an individual function or argument to a function
1280 in your @file{.emacs} file by moving the cursor to the end of the
1281 function or argument and typing @kbd{C-x C-e} (@kbd{M-x
1282 eval-last-sexp}).
1284 Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of
1285 variables which you are trying to set or use.
1287 @node Displaying the current line or column, Displaying the current file name in the titlebar, Debugging a customization file, Common requests
1288 @section How do I make Emacs display the current line (or column) number?
1289 @cindex @code{line-number-mode}
1290 @cindex Displaying the current line or column
1291 @cindex Line number, displaying the current
1292 @cindex Column, displaying the current
1293 @cindex @code{mode-line-format}
1295 To have Emacs automatically display the current line number of the point
1296 in the mode line, do @kbd{M-x line-number-mode}.  You can also put the
1297 form
1299 @lisp
1300 (setq line-number-mode t)
1301 @end lisp
1303 @noindent
1304 in your @file{.emacs} file to achieve this whenever you start Emacs.
1305 (Line number display is on by default, unless your site-specific
1306 initialization disables it.) Note that Emacs will not display the line
1307 number if the buffer's size in bytes is larger than the value of the
1308 variable @code{line-number-display-limit}.
1310 As of Emacs 20, you can similarly display the current column with
1311 @kbd{M-x column-number-mode}, or by putting the form
1313 @lisp
1314 (setq column-number-mode t)
1315 @end lisp
1317 @noindent
1318 in your @file{.emacs} file.
1320 The @code{"%c"} format specifier in the variable @code{mode-line-format}
1321 will insert the current column's value into the mode line.  See the
1322 documentation for @code{mode-line-format} (using @kbd{C-h v
1323 mode-line-format @key{RET}}) for more information on how to set and use
1324 this variable.
1326 Users of all Emacs versions can display the current column using the
1327 @samp{column} package written by @email{abraham@@dina.kvl.dk, Per
1328 Abrahamsen}.  @xref{Packages that do not come with Emacs}, for
1329 instructions on how to get it.
1331 @cindex Set number capability in @code{vi} emulators
1332 None of the @code{vi} emulation modes provide the ``set number''
1333 capability of @code{vi} (as far as we know).  The @samp{setnu} package
1334 written by @email{kyle@@wonderworks.com, Kyle Jones} provides this
1335 feature.  So too does @samp{wb-line-number}, written by
1336 @email{naoki.y.nakamura@@nifty.com, Naoki Nakamura}.
1338 @node Displaying the current file name in the titlebar, Turning on abbrevs by default, Displaying the current line or column, Common requests
1339 @section How can I modify the titlebar to contain the current file name?
1340 @cindex Titlebar, displaying the current file name in
1341 @cindex File name, displaying in the titlebar
1342 @cindex @code{frame-title-format}
1344 The contents of an Emacs frame's titlebar is controlled by the variable
1345 @code{frame-title-format}, which has the same structure as the variable
1346 @code{mode-line-format}.  (Use @kbd{C-h v} or @kbd{M-x
1347 describe-variable} to get information about one or both of these
1348 variables.)
1350 By default, the titlebar for a frame does contain the name of the buffer
1351 currently being visited, except if there is a single frame.  In such a
1352 case, the titlebar contains Emacs invocation name and the name of the
1353 machine at which Emacs was invoked.  This is done by setting
1354 @code{frame-title-format} to the default value of
1356 @lisp
1357 (multiple-frames "%b" ("" invocation-name "@@" system-name))
1358 @end lisp
1360 To modify the behavior such that frame titlebars contain the buffer's
1361 name regardless of the number of existing frames, include the following
1362 in your @file{.emacs}:
1364 @lisp
1365 (setq frame-title-format "%b")
1366 @end lisp
1368 @node Turning on abbrevs by default, Turning on auto-fill by default, Displaying the current file name in the titlebar, Common requests
1369 @section How do I turn on abbrevs by default just in mode @var{mymode}?
1370 @cindex Abbrevs, turning on by default
1372 Put this in your @file{.emacs} file:
1374 @lisp
1375 (condition-case ()
1376    (quietly-read-abbrev-file)
1377   (file-error nil))
1379 (add-hook '@var{mymode}-mode-hook
1380           (lambda ()
1381            (setq abbrev-mode t)))
1382 @end lisp
1384 @node Turning on auto-fill by default, Associating modes with files, Turning on abbrevs by default, Common requests
1385 @section How do I turn on @code{auto-fill-mode} by default?
1386 @cindex @code{auto-fill-mode}, activating automatically
1387 @cindex Filling automatically
1388 @cindex Automatic entry to @code{auto-fill-mode}
1390 To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x
1391 auto-fill-mode}.
1393 To turn it on for every buffer in a certain mode, you must use the hook
1394 for that mode.  For example, to turn on @code{auto-fill} mode for all
1395 text buffers, including the following in your @file{.emacs} file:
1397 @lisp
1398 (add-hook 'text-mode-hook 'turn-on-auto-fill)
1399 @end lisp
1401 If you want @code{auto-fill} mode on in all major modes, do this:
1403 @lisp
1404 (setq-default auto-fill-function 'do-auto-fill)
1405 @end lisp
1407 @node Associating modes with files, Working with unprintable characters, Turning on auto-fill by default, Common requests
1408 @section How do I make Emacs use a certain major mode for certain files?
1409 @cindex Associating modes with files
1410 @cindex File extensions and modes
1411 @cindex @code{auto-mode-alist}, modifying
1412 @cindex Modes, associating with file extensions
1414 If you want to use a certain mode @var{foo} for all files whose names end
1415 with the extension @file{.@var{bar}}, this will do it for you:
1417 @lisp
1418 (setq auto-mode-alist (cons '("\\.@var{bar}\\'" . @var{foo}-mode) auto-mode-alist))
1419 @end lisp
1421 Otherwise put this somewhere in the first line of any file you want to
1422 edit in the mode @var{foo} (in the second line, if the first line begins
1423 with @samp{#!}):
1425 @example
1426 -*- @var{foo} -*-
1427 @end example
1429 @cindex Major mode for shell scripts
1430 Beginning with Emacs 19, the variable @code{interpreter-mode-alist}
1431 specifies which mode to use when loading a shell script.  (Emacs
1432 determines which interpreter you're using by examining the first line of
1433 the script.)  This feature only applies when the file name doesn't
1434 indicate which mode to use.  Use @kbd{C-h v} (or @kbd{M-x
1435 describe-variable}) on @code{interpreter-mode-alist} to learn more.
1437 @node Working with unprintable characters, Highlighting a region, Associating modes with files, Common requests
1438 @section How do I search for, delete, or replace unprintable (eight-bit or control) characters?
1439 @cindex Unprintable characters, working with
1440 @cindex Working with unprintable characters
1441 @cindex Control characters, working with
1442 @cindex Eight-bit characters, working with
1443 @cindex Searching for unprintable characters
1444 @cindex Regexps and unprintable characters
1446 To search for a single character that appears in the buffer as, for
1447 example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}.  (This assumes
1448 the value of @code{search-quote-char} is 17 (i.e., @kbd{C-q}).)
1449 Searching for @strong{all} unprintable characters is best done with a
1450 regular expression (@dfn{regexp}) search.  The easiest regexp to use for
1451 the unprintable chars is the complement of the regexp for the printable
1452 chars.
1454 @itemize @bullet
1456 @item
1457 Regexp for the printable chars: @samp{[\t\n\r\f -~]}
1459 @item
1460 Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]}
1462 @end itemize
1464 To type these special characters in an interactive argument to
1465 @code{isearch-forward-regexp} or @code{re-search-forward}, you need to
1466 use @kbd{C-q}.  (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand
1467 respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.)  So,
1468 to search for unprintable characters using @code{re-search-forward}:
1470 @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}}
1472 Using @code{isearch-forward-regexp}:
1474 @kbd{C-M-s [^ @key{TAB} @key{LFD} C-q @key{RET} C-q C-l @key{SPC} -~]}
1476 To delete all unprintable characters, simply use replace-regexp:
1478 @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}}
1480 Replacing is similar to the above.  To replace all unprintable
1481 characters with a colon, use:
1483 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}
1485 @itemize @bullet
1487 @item
1488 You don't need to quote @key{TAB} with either isearch or typing
1489 something in the minibuffer.
1491 @end itemize
1493 @node Highlighting a region, Controlling case sensitivity, Working with unprintable characters, Common requests
1494 @section How can I highlight a region of text in Emacs?
1495 @cindex Highlighting text
1496 @cindex Text, highlighting
1497 @cindex @code{transient-mark-mode}
1498 @cindex Region, highlighting a
1500 You can cause the region to be highlighted when the mark is active by
1501 including
1503 @lisp
1504 (transient-mark-mode t)
1505 @end lisp
1507 @noindent
1508 in your @file{.emacs} file.  (Also see @ref{Turning on syntax
1509 highlighting}.)
1511 @node Controlling case sensitivity, Wrapping words automatically, Highlighting a region, Common requests
1512 @section How do I control Emacs's case-sensitivity when searching/replacing?
1513 @cindex @code{case-fold-search}
1514 @cindex Case sensitivity of searches
1515 @cindex Searching without case sensitivity
1516 @cindex Ignoring case in searches
1518 For searching, the value of the variable @code{case-fold-search}
1519 determines whether they are case sensitive:
1521 @lisp
1522 (setq case-fold-search nil) ; make searches case sensitive
1523 (setq case-fold-search t)   ; make searches case insensitive
1524 @end lisp
1526 @cindex Case sensitivity in replacements
1527 @cindex Replacing, and case sensitivity
1528 @cindex @code{case-replace}
1529 Similarly, for replacing, the variable @code{case-replace} determines
1530 whether replacements preserve case.
1532 To change the case sensitivity just for one major mode, use the major
1533 mode's hook.  For example:
1535 @lisp
1536 (add-hook '@var{foo}-mode-hook
1537           (lambda ()
1538            (setq case-fold-search nil)))
1539 @end lisp
1541 @node Wrapping words automatically, Spell-checkers, Controlling case sensitivity, Common requests
1542 @section How do I make Emacs wrap words for me?
1543 @cindex Wrapping word automatically
1544 @cindex Wrapping lines
1545 @cindex Line wrap
1546 @cindex @code{auto-fill-mode}, introduction to
1547 @cindex Maximum line width, default value
1548 @cindex @code{fill-column}, default value
1550 Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}.
1551 The default maximum line width is 70, determined by the variable
1552 @code{fill-column}.  To learn how to turn this on automatically, see
1553 @ref{Turning on auto-fill by default}.
1555 @node Spell-checkers, Checking TeX and *roff documents, Wrapping words automatically, Common requests
1556 @section Where can I get a better spelling checker for Emacs?
1557 @cindex Checking spelling
1558 @cindex Spelling, checking text documents
1560 Use Ispell.  @xref{Ispell}.
1562 @node Checking TeX and *roff documents, Changing load-path, Spell-checkers, Common requests
1563 @section How can I spell-check @TeX{} or *roff documents?
1564 @cindex Spelling, checking @TeX{} documents
1565 @cindex @TeX{} documents, checking spelling in
1567 Use Ispell.  Ispell can handle @TeX{} and *roff documents.
1568 @xref{Ispell}.
1570 @node Changing load-path, Using an already running Emacs process, Checking TeX and *roff documents, Common requests
1571 @section How do I change @code{load-path}?
1572 @cindex @code{load-path}, modifying
1573 @cindex Modifying @code{load-path}
1574 @cindex Adding to @code{load-path}
1576 In general, you should only add to the @code{load-path}.  You can add
1577 directory @var{/dir/subdir} to the load path like this:
1579 @lisp
1580 (setq load-path (cons "/dir/subdir/" load-path))
1581 @end lisp
1583 To do this relative to your home directory:
1585 @lisp
1586 (setq load-path (cons "~/mysubdir/" load-path)
1587 @end lisp
1589 @node Using an already running Emacs process, Compiler error messages, Changing load-path, Common requests
1590 @section How do I use an already running Emacs from another window?
1591 @cindex @code{emacsclient}
1592 @cindex Emacs server functions
1593 @cindex Using an existing Emacs process
1595 @code{emacsclient}, which comes with Emacs, is for editing a file using
1596 an already running Emacs rather than starting up a new Emacs.  It does
1597 this by sending a request to the already running Emacs, which must be
1598 expecting the request.
1600 @itemize @bullet
1602 @item
1603 Setup:
1605 Emacs must have executed the @code{server-start} function for
1606 @samp{emacsclient} to work.  This can be done either by a command line
1607 option:
1609 @example
1610 emacs -f server-start
1611 @end example
1613 or by invoking @code{server-start} from @file{.emacs}:
1615 @lisp
1616 (if (@var{some conditions are met}) (server-start))
1617 @end lisp
1619 When this is done, Emacs creates a Unix domain socket.
1620 The socket is either named @file{.emacs_server}, in the user's home directory,
1621 or @file{esrv-@var{userid}-@var{systemname}}, in the @file{/tmp}
1622 directory, depending on your system.  See @code{server-socket-name}.
1624 To get your news reader, mail reader, etc., to invoke
1625 @samp{emacsclient}, try setting the environment variable @code{EDITOR}
1626 (or sometimes @code{VISUAL}) to the value @samp{emacsclient}.  You may
1627 have to specify the full pathname of the @samp{emacsclient} program
1628 instead.  Examples:
1630 @example
1631 # csh commands:
1632 setenv EDITOR emacsclient
1634 # using full pathname
1635 setenv EDITOR /usr/local/emacs/etc/emacsclient
1637 # sh command:
1638 EDITOR=emacsclient ; export EDITOR
1639 @end example
1641 @item
1642 Normal use:
1644 When @samp{emacsclient} is run, it connects to the @file{.emacs_server}
1645 socket and passes its command line options to @samp{server}.  When
1646 @samp{server} receives these requests, it sends this information to the
1647 the Emacs process, which at the next opportunity will visit the files
1648 specified.  (Line numbers can be specified just like with Emacs.)  The
1649 user will have to switch to the Emacs window by hand.  When the user is
1650 done editing a file, the user can type @kbd{C-x #} (or @kbd{M-x
1651 server-edit}) to indicate this.  If there is another buffer requested by
1652 @code{emacsclient}, Emacs will switch to it; otherwise
1653 @code{emacsclient} will exit, signaling the calling program to continue.
1655 @samp{emacsclient} and @samp{server} must be running on machines which
1656 share the same filesystem for this to work.  The pathnames that
1657 @samp{emacsclient} specifies should be correct for the filesystem that
1658 the Emacs process sees.  The Emacs process should not be suspended at
1659 the time @samp{emacsclient} is invoked.  On Unix and GNU/Linux systems,
1660 @samp{emacsclient} should either be invoked from another X window, or
1661 from a shell window inside Emacs itself, or from another interactive
1662 session, e.g., by means of a @code{screen} program.
1664 @cindex @code{gnuserv}
1665 There is an enhanced version of @samp{emacsclient}/server called
1666 @samp{gnuserv}, written by @email{ange@@hplb.hpl.hp.com, Andy Norman}
1667 (@pxref{Packages that do not come with Emacs}).  @samp{gnuserv} uses
1668 Internet domain sockets, so it can work across most network connections.
1669 It also supports the execution of arbitrary Emacs Lisp forms and does
1670 not require the client program to wait for completion.
1672 The alpha version of an enhanced @samp{gnuserv} is available at
1674 @uref{ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz}
1676 The version available from @uref{http://meltin.net/hacks/emacs/} is
1677 more recent, and has been tested with Emacs 21.2.
1679 @end itemize
1681 @node Compiler error messages, Indenting switch statements, Using an already running Emacs process, Common requests
1682 @section How do I make Emacs recognize my compiler's funny error messages?
1683 @cindex Compiler error messages, recognizing
1684 @cindex Recognizing non-standard compiler errors
1685 @cindex Regexps for recognizing compiler errors
1686 @cindex Errors, recognizing compiler
1688 The variable @code{compilation-error-regexp-alist} helps control how
1689 Emacs parses your compiler output.  It is a list of triplets of the form:
1690 @code{(@var{regexp} @var{file-idx} @var{line-idx})}, where @var{regexp},
1691 @var{file-idx} and @var{line-idx} are strings.  To help determine what
1692 the constituent elements should be, load @file{compile.el} and then type
1693 @kbd{C-h v compilation-error-regexp-alist @key{RET}} to see the current
1694 value.  A good idea is to look at @file{compile.el} itself as the
1695 comments included for this variable are quite useful---the regular
1696 expressions required for your compiler's output may be very close to one
1697 already provided.  Once you have determined the proper regexps, use the
1698 following to inform Emacs of your changes:
1700 @lisp
1701 (setq compilation-error-regexp-alist
1702       (cons '(@var{regexp} @var{file-idx} @var{line-idx})
1703          compilation-error-regexp-alist))
1704 @end lisp
1706 @node Indenting switch statements, Customizing C and C++ indentation, Compiler error messages, Common requests
1707 @section How do I change the indentation for @code{switch}?
1708 @cindex @code{switch}, indenting
1709 @cindex Indenting of @code{switch}
1711 Many people want to indent their @code{switch} statements like this:
1713 @example
1716   switch(x) @{
1717     case A:
1718       x1;
1719       break;
1720     case B:
1721       x2;
1722       break;
1723     default:
1724       x3;
1725   @}
1727 @end example
1729 The solution at first appears to be: set @code{c-indent-level} to 4 and
1730 @code{c-label-offset} to -2.  However, this will give you an indentation
1731 spacing of four instead of two.
1733 The @emph{real} solution is to use @code{cc-mode} (the default mode for
1734 C programming in Emacs 20 and later) and add the following line to yoyr
1735 @file{.emacs}:
1737 @lisp
1738 (c-set-offset 'case-label '+)
1739 @end lisp
1741 There appears to be no way to do this with the old @code{c-mode}.
1743 @node Customizing C and C++ indentation, Horizontal scrolling, Indenting switch statements, Common requests
1744 @section How to customize indentation in C, C@t{++}, and Java buffers?
1745 @cindex Indentation, how to customize
1746 @cindex Customize indentation
1748 The Emacs @code{cc-mode} features an interactive procedure for
1749 customizing the indentation style, which is fully explained in the
1750 @cite{CC Mode} manual that is part of the Emacs distribution, see
1751 @ref{Customizing Indentation, , Customization Indentation, ccmode,
1752 The CC Mode Manual}.  Here's a short summary of the procedure:
1754 @enumerate
1755 @item
1756 Go to the beginning of the first line where you don't like the
1757 indentation and type @kbd{C-c C-o}.  Emacs will prompt you for the
1758 syntactic symbol; type @key{RET} to accept the default it suggests.
1760 @item
1761 Emacs now prompts for the offset of this syntactic symbol, showing the
1762 default (the current definition) inside parentheses.  You can choose
1763 one of these:
1765 @table @code
1766 @item 0
1767 No extra indentation.
1768 @item +
1769 Indent one basic offset.
1770 @item -
1771 Outdent one basic offset.
1772 @item ++
1773 Indent two basic offsets
1774 @item --
1775 Outdent two basic offsets.
1776 @item *
1777 Indent half basic offset.
1778 @item /
1779 Outdent half basic offset.
1780 @end table
1782 @item
1783 After choosing one of these symbols, type @kbd{C-c C-q} to reindent
1784 the line or the block according to what you just specified.
1786 @item
1787 If you don't like the result, go back to step 1.  Otherwise, add the
1788 following line to your @file{.emacs}:
1790 @lisp
1791 (c-set-offset '@var{syntactic-symbol} @var{offset})
1792 @end lisp
1794 @noindent
1795 where @var{syntactic-symbol} is the name Emacs shows in the minibuffer
1796 when you type @kbd{C-c C-o} at the beginning of the line, and
1797 @var{offset} is one of the indentation symbols listed above (@code{+},
1798 @code{/}, @code{0}, etc.) that you've chosen during the interactive
1799 procedure.
1801 @item
1802 Go to the next line whose indentation is not to your liking and repeat
1803 the process there.
1804 @end enumerate
1806 It is recommended to put all the resulting @code{(c-set-offset ...)}
1807 customizations inside a C mode hook, like this:
1809 @lisp
1810 (defun my-c-mode-hook ()
1811   (c-set-offset ...)
1812   (c-set-offset ...))
1813 (add-hook 'c-mode-hook 'my-c-mode-hook)
1814 @end lisp
1816 @noindent
1817 Using @code{c-mode-hook} avoids the need to put a @w{@code{(require
1818 'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset}
1819 might be unavailable when @code{cc-mode} is not loaded.
1821 Note that @code{c-mode-hook} runs for C source files only; use
1822 @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for
1823 Java sources, etc.  If you want the same customizations to be in
1824 effect in @emph{all} languages supported by @code{cc-mode}, use
1825 @code{c-mode-common-hook}.
1827 @node Horizontal scrolling, Overwrite mode, Customizing C and C++ indentation, Common requests
1828 @section How can I make Emacs automatically scroll horizontally?
1829 @cindex @code{hscroll-mode}
1830 @cindex Horizontal scrolling
1831 @cindex Scrolling horizontally
1833 In Emacs 21 and later, this is on by default: if the variable
1834 @code{truncate-lines} is non-@code{nil} in the current buffer, Emacs
1835 automatically scrolls the display horizontally when point moves off the
1836 left or right edge of the window.
1838 In Emacs 20, use the @code{hscroll-mode}.  Here is some information from
1839 the documentation, available by typing @kbd{C-h f hscroll-mode @key{RET}}:
1841 Automatically scroll horizontally when the point moves off the
1842 left or right edge of the window.
1844 @itemize @minus
1845 @item
1846 Type @kbd{M-x hscroll-mode} to enable it in the current buffer.
1848 @item
1849 Type @kbd{M-x hscroll-global-mode} to enable it in every buffer.
1851 @item
1852 @code{turn-on-hscroll} is useful in mode hooks as in:
1854 @lisp
1855 (add-hook 'text-mode-hook 'turn-on-hscroll)
1856 @end lisp
1858 @item
1859 @code{hscroll-margin} controls how close the cursor can get to the
1860 edge of the window.
1862 @item
1863 @code{hscroll-step-percent} controls how far to jump once we decide to do so.
1864 @end itemize
1866 @node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests
1867 @section How do I make Emacs "typeover" or "overwrite" instead of inserting?
1868 @cindex @key{Insert}
1869 @cindex @code{overwrite-mode}
1870 @cindex Overwriting existing text
1871 @cindex Toggling @code{overwrite-mode}
1873 @kbd{M-x overwrite-mode} (a minor mode).  This toggles
1874 @code{overwrite-mode} on and off, so exiting from @code{overwrite-mode}
1875 is as easy as another @kbd{M-x overwrite-mode}.
1877 On some systems, @key{Insert} toggles @code{overwrite-mode} on and off.
1879 @node Turning off beeping, Turning the volume down, Overwrite mode, Common requests
1880 @section How do I stop Emacs from beeping on a terminal?
1881 @cindex Beeping, turning off
1882 @cindex Visible bell
1883 @cindex Bell, visible
1885 @email{martin@@cc.gatech.edu, Martin R. Frank} writes:
1887 Tell Emacs to use the @dfn{visible bell} instead of the audible bell,
1888 and set the visible bell to nothing.
1890 That is, put the following in your @code{TERMCAP} environment variable
1891 (assuming you have one):
1893 @example
1894 ... :vb=: ...
1895 @end example
1897 And evaluate the following Lisp form:
1899 @example
1900 (setq visible-bell t)
1901 @end example
1903 @node Turning the volume down, Automatic indentation, Turning off beeping, Common requests
1904 @section How do I turn down the bell volume in Emacs running under X?
1905 @cindex Bell, volume of
1906 @cindex Volume of bell
1908 On X Window system, you can adjust the bell volume and duration for all
1909 programs with the shell command @code{xset}.
1911 Invoking @code{xset} without any arguments produces some basic
1912 information, including the following:
1914 @example
1915 usage:  xset [-display host:dpy] option ...
1916   To turn bell off:
1917       -b                b off               b 0
1918   To set bell volume, pitch and duration:
1919        b [vol [pitch [dur]]]          b on
1920 @end example
1922 @node Automatic indentation, Matching parentheses, Turning the volume down, Common requests
1923 @section How do I tell Emacs to automatically indent a new line to the indentation of the previous line?
1924 @cindex Indenting new lines
1925 @cindex New lines, indenting of
1926 @cindex Previous line, indenting according to
1927 @cindex Text indentation
1929 Such behavior is automatic in Emacs 20 and later.  From the
1930 @file{etc/NEWS} file for Emacs 20.2:
1932 @example
1933 ** In Text mode, now only blank lines separate paragraphs.  This makes
1934 it possible to get the full benefit of Adaptive Fill mode in Text mode,
1935 and other modes derived from it (such as Mail mode).  @key{TAB} in Text
1936 mode now runs the command @code{indent-relative}; this makes a practical
1937 difference only when you use indented paragraphs.
1939 As a result, the old Indented Text mode is now identical to Text mode,
1940 and is an alias for it.
1942 If you want spaces at the beginning of a line to start a paragraph, use
1943 the new mode, Paragraph Indent Text mode.
1944 @end example
1946 @cindex Prefixing lines
1947 @cindex Fill prefix
1948 If you have @code{auto-fill-mode} turned on (@pxref{Turning on auto-fill
1949 by default}), you can tell Emacs to prefix every line with a certain
1950 character sequence, the @dfn{fill prefix}.  Type the prefix at the
1951 beginning of a line, position point after it, and then type @kbd{C-x .}
1952 (@code{set-fill-prefix}) to set the fill prefix.  Thereafter,
1953 auto-filling will automatically put the fill prefix at the beginning of
1954 new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill
1955 prefix when refilling the paragraph.
1957 If you have paragraphs with different levels of indentation, you will
1958 have to set the fill prefix to the correct value each time you move to a
1959 new paragraph.  There are many packages available to deal with this
1960 (@pxref{Packages that do not come with Emacs}).  Look for ``fill'' and
1961 ``indent'' keywords for guidance.
1963 @node Matching parentheses, Hiding #ifdef lines, Automatic indentation, Common requests
1964 @section How do I show which parenthesis matches the one I'm looking at?
1965 @cindex Parentheses, matching
1966 @cindex @file{paren.el}
1967 @cindex Highlighting matching parentheses
1968 @cindex Pairs of parentheses, highlighting
1969 @cindex Matching parentheses
1971 As of version 19, Emacs comes with @file{paren.el}, which (when loaded)
1972 will automatically highlight matching parentheses whenever point (i.e.,
1973 the cursor) is located over one.  To load @file{paren.el} automatically,
1974 include the line
1976 @lisp
1977 (require 'paren)
1978 @end lisp
1980 in your @file{.emacs} file.  @email{shutkoa@@ugsolutions.com, Alan Shutko}
1981 reports that as of version 20.1, you must also call @code{show-paren-mode} in
1982 your @file{.emacs} file:
1984 @lisp
1985 (show-paren-mode 1)
1986 @end lisp
1988 Customize will let you turn on @code{show-paren-mode}.  Use @kbd{M-x
1989 customize-group @key{RET} paren-showing @key{RET}}.  From within
1990 Customize, you can also go directly to the ``paren-showing'' group.
1992 Alternatives to paren include:
1994 @itemize @bullet
1996 @item
1997 If you're looking at a right parenthesis (or brace or bracket) you can
1998 delete it and reinsert it.  Emacs will momentarily move the cursor to
1999 the matching parenthesis.
2001 @item
2002 @kbd{C-M-f} (@code{forward-sexp}) and @kbd{C-M-b} (@code{backward-sexp})
2003 will skip over one set of balanced parentheses, so you can see which
2004 parentheses match.  (You can train it to skip over balanced brackets
2005 and braces at the same time by modifying the syntax table.)
2007 @cindex Show matching paren as in @code{vi}
2008 @item
2009 Here is some Emacs Lisp that will make the @key{%} key show the matching
2010 parenthesis, like in @code{vi}.  In addition, if the cursor isn't over a
2011 parenthesis, it simply inserts a % like normal.
2013 @lisp
2014 ;; By an unknown contributor
2016 (global-set-key "%" 'match-paren)
2018 (defun match-paren (arg)
2019   "Go to the matching paren if on a paren; otherwise insert %."
2020   (interactive "p")
2021   (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1))
2022         ((looking-at "\\s\)") (forward-char 1) (backward-list 1))
2023         (t (self-insert-command (or arg 1)))))
2024 @end lisp
2026 @end itemize
2028 @node Hiding #ifdef lines, Repeating commands, Matching parentheses, Common requests
2029 @section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler?
2030 @cindex @code{#ifdef}, selective display of
2031 @cindex @code{hide-ifdef-mode}
2032 @cindex Hiding @code{#ifdef} text
2033 @cindex Selectively displaying @code{#ifdef} code
2035 @kbd{M-x hide-ifdef-mode}.  (This is a minor mode.)  You might also want
2036 to investigate @file{cpp.el}, which is distributed with Emacs.
2038 @node Repeating commands, Valid X resources, Hiding #ifdef lines, Common requests
2039 @section Is there an equivalent to the @code{.} (dot) command of vi?
2040 @cindex Repeating commands as with @code{vi}
2041 @cindex Command, repeat last
2042 @cindex @code{.}, equivalent to @code{vi} command
2044 (@code{.} is the redo command in @code{vi}.  It redoes the last
2045 insertion/deletion.)
2047 As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x z})
2048 that repeats the last command.  If you preface it with a prefix
2049 argument, the prefix arg is applied to the command.
2051 You can also type @kbd{C-x @key{ESC} @key{ESC}}
2052 (@code{repeat-complex-command}) to reinvoke commands that used the
2053 minibuffer to get arguments.  In @code{repeat-complex-command} you can
2054 type @kbd{M-p} and @kbd{M-n} (and also up-arrow and down-arrow, if your
2055 keyboard has these keys) to scan through all the different complex
2056 commands you've typed.
2058 To repeat a set of commands, use keyboard macros.  (@inforef{Keyboard
2059 Macros, Keyboard Macros, emacs}.)
2061 If you're really desperate for the @code{.} command, use VIPER, a
2062 @code{vi} emulation mode which comes with Emacs, and which appears to
2063 support it.  (@xref{VIPER}.)
2065 @node Valid X resources, Evaluating Emacs Lisp code, Repeating commands, Common requests
2066 @section What are the valid X resource settings (i.e., stuff in .Xdefaults)?
2067 @cindex Resources, X
2068 @cindex X resources
2069 @cindex Setting X resources
2071 @inforef{X Resources, X Resources, emacs}.
2073 You can also use a resource editor, such as editres (for X11R5 and
2074 onwards), to look at the resource names for the menu bar, assuming Emacs
2075 was compiled with the X toolkit.
2077 @node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests
2078 @section How do I execute ("evaluate") a piece of Emacs Lisp code?
2079 @cindex Evaluating Lisp code
2080 @cindex Lisp forms, evaluating
2082 There are a number of ways to execute (@dfn{evaluate}, in Lisp lingo) an
2083 Emacs Lisp @dfn{form}:
2085 @itemize @bullet
2087 @item
2088 If you want it evaluated every time you run Emacs, put it in a file
2089 named @file{.emacs} in your home directory.  This is known as ``your
2090 @file{.emacs} file,'' and contains all of your personal customizations.
2092 @item
2093 You can type the form in the @file{*scratch*} buffer, and then type
2094 @key{LFD} (or @kbd{C-j}) after it.  The result of evaluating the form
2095 will be inserted in the buffer.
2097 @item
2098 In @code{emacs-lisp-mode}, typing @kbd{C-M-x} evaluates a top-level form
2099 before or around point.
2101 @item
2102 Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately
2103 before point and prints its value in the echo area.
2105 @item
2106 Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp
2107 form in the minibuffer which will be evaluated once you press @key{RET}.
2109 @item
2110 You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp
2111 forms in a file.  (To do this from Lisp use the function @code{load}
2112 instead.)
2114 The functions @code{load-library}, @code{eval-region},
2115 @code{eval-current-buffer}, @code{require}, and @code{autoload} are also
2116 useful; see @ref{Emacs Lisp documentation}, if you want to learn more
2117 about them.
2119 @end itemize
2121 @node Changing the length of a Tab, Inserting > at the beginning of each line, Evaluating Emacs Lisp code, Common requests
2122 @section How do I change Emacs's idea of the @key{TAB} character's length?
2123 @cindex Tab length
2124 @cindex Length of tab character
2125 @cindex @code{default-tab-width}
2127 Set the variable @code{default-tab-width}.  For example, to set
2128 @key{TAB} stops every 10 characters, insert the following in your
2129 @file{.emacs} file:
2131 @lisp
2132 (setq default-tab-width 10)
2133 @end lisp
2135 Do not confuse variable @code{tab-width} with variable
2136 @code{tab-stop-list}.  The former is used for the display of literal
2137 @key{TAB} characters.  The latter controls what characters are inserted
2138 when you press the @key{TAB} character in certain modes.
2140 @node Inserting > at the beginning of each line, Underlining paragraphs, Changing the length of a Tab, Common requests
2141 @section How do I insert @samp{>} at the beginning of every line?
2142 @cindex Prefix character, inserting in mail/news replies
2143 @cindex Replies to mail/news, inserting a prefix character
2144 @cindex @code{mail-yank-prefix}
2145 @cindex Mail replies, inserting a prefix character
2146 @cindex News replies, inserting a prefix character
2148 To do this to an entire buffer, type @kbd{M-< M-x replace-regexp
2149 @key{RET} ^ @key{RET} > @key{RET}}.
2151 To do this to a region, use @code{string-insert-rectangle}.
2152 Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you
2153 want to prefix, move the cursor to last line to be prefixed, and type
2154 @kbd{M-x string-insert-rectangle @key{RET}}.  To do this for the whole
2155 buffer, type @kbd{C-x h M-x string-insert-rectangle @key{RET}}.
2157 If you are trying to prefix a yanked mail message with @samp{>}, you
2158 might want to set the variable @code{mail-yank-prefix}.  Better yet, use
2159 the Supercite package (@pxref{Supercite}), which provides flexible
2160 citation for yanked mail and news messages; it is included in Emacs
2161 since version 19.20.  @xref{Changing the included text prefix}, for
2162 additional information.
2164 @node Underlining paragraphs, Repeating a command as many times as possible, Inserting > at the beginning of each line, Common requests
2165 @section How do I insert "_^H" before each character in a region to get an underlined paragraph?
2166 @cindex Underlining a region of text
2167 @cindex @code{underline-region}
2169 Mark the region and then type @kbd{M-x underline-region @key{RET}}.
2171 @node Repeating a command as many times as possible, Forcing the cursor to remain in the same column, Underlining paragraphs, Common requests
2172 @section How do I repeat a command as many times as possible?
2173 @cindex Repeating commands many times
2174 @cindex Commands, repeating many times
2176 Use @kbd{C-x (} and @kbd{C-x )} to make a keyboard macro that invokes
2177 the command and then type @kbd{M-0 C-x e}.
2179 Any messages your command prints in the echo area will be suppressed.
2181 If you need to repeat a command a small number of times, you can use
2182 @kbd{C-x z}, see @ref{Repeating commands}.
2184 @node Forcing the cursor to remain in the same column, Forcing Emacs to iconify itself, Repeating a command as many times as possible, Common requests
2185 @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?
2186 @cindex @code{picture-mode}
2187 @cindex Remaining in the same column, regardless of contents
2188 @cindex Vertical movement in empty documents
2190 @kbd{M-x picture-mode}.
2192 @node Forcing Emacs to iconify itself, Using regular expressions, Forcing the cursor to remain in the same column, Common requests
2193 @section How do I tell Emacs to iconify itself?
2194 @cindex Iconification under the X Window System
2195 @cindex X Window System and iconification
2196 @cindex Suspending Emacs
2198 @kbd{C-z} iconifies Emacs when running under X and suspends Emacs
2199 otherwise.  @inforef{Frame Commands, Frame Commands, emacs}.
2201 @node Using regular expressions, Replacing text across multiple files, Forcing Emacs to iconify itself, Common requests
2202 @section How do I use regexps (regular expressions) in Emacs?
2203 @cindex Regexps
2204 @cindex Regular expressions
2205 @cindex Differences between Unix and Emacs regexps
2206 @cindex Unix regeps, differences from Emacs
2207 @cindex Text strings, putting regexps in
2209 @inforef{Regexps, Regexps, emacs}.
2211 The @code{or} operator is @samp{\|}, not @samp{|}, and the grouping operators
2212 are @samp{\(} and @samp{\)}.  Also, the string syntax for a backslash is
2213 @samp{\\}.  To specify a regular expression like @samp{xxx\(foo\|bar\)}
2214 in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}.
2216 Note the doubled backslashes!
2218 @itemize @bullet
2220 @item
2221 Unlike in Unix @file{grep}, @file{sed}, etc., a complement character set
2222 (@samp{[^...]})  can match a newline character (@key{LFD} a.k.a.@:
2223 @kbd{C-j} a.k.a.@: @samp{\n}), unless newline is mentioned as one of the
2224 characters not to match.
2226 @item
2227 The character syntax regexps (e.g., @samp{\sw}) are not
2228 meaningful inside character set regexps (e.g., @samp{[aeiou]}).  (This
2229 is actually typical for regexp syntax.)
2231 @end itemize
2233 @node Replacing text across multiple files, Documentation for etags, Using regular expressions, Common requests
2234 @section How do I perform a replace operation across more than one file?
2235 @cindex Replacing strings across files
2236 @cindex Multiple files, replacing across
2237 @cindex Files, replacing strings across multiple
2239 The ``tags'' feature of Emacs includes the command
2240 @code{tags-query-replace} which performs a query-replace across all the
2241 files mentioned in the @file{TAGS} file.  @inforef{Tags Search, Tags Search,
2242 emacs}.
2244 As of Emacs 19.29, Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x
2245 d}) supports the command @code{dired-do-query-replace}, which allows
2246 users to replace regular expressions in multiple files.
2248 @node Documentation for etags, Disabling backups, Replacing text across multiple files, Common requests
2249 @section Where is the documentation for @code{etags}?
2250 @cindex Documentation for @code{etags}
2251 @cindex @code{etags}, documentation for
2253 The @code{etags} man page should be in the same place as the
2254 @code{emacs} man page.
2256 Quick command-line switch descriptions are also available.  For example,
2257 @samp{etags -H}.
2259 @node Disabling backups, Disabling auto-save-mode, Documentation for etags, Common requests
2260 @section How do I disable backup files?
2261 @cindex Backups, disabling
2262 @cindex Disabling backups
2264 You probably don't want to do this, since backups are useful, especially
2265 when something goes wrong.
2267 To avoid seeing backup files (and other "uninteresting" files) in Dired,
2268 load @code{dired-x} by adding the following to your @file{.emacs} file:
2270 @lisp
2271 (add-hook 'dired-load-hook
2272           (lambda ()
2273            (load "dired-x")))
2274 @end lisp
2276 With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer.
2277 You can make omitting the default for new dired buffers by putting the
2278 following in your @file{.emacs}:
2280 @lisp
2281 (add-hook 'dired-mode-hook 'dired-omit-toggle)
2282 @end lisp
2284 If you're tired of seeing backup files whenever you do an @samp{ls} at
2285 the Unix shell, try GNU @code{ls} with the @samp{-B} option.  GNU
2286 @code{ls} is part of the GNU Fileutils package, available from
2287 @samp{ftp.gnu.org} and its mirrors (@pxref{Current GNU distributions}).
2289 To disable or change the way backups are made, @inforef{Backup Names, ,
2290 emacs}.
2292 @cindex Backup files in a single directory
2293 Beginning with Emacs 21.1, you can control where Emacs puts backup files
2294 by customizing the variable @code{backup-directory-alist}.  This
2295 variable's value specifies that files whose names match specific patters
2296 should have their backups put in certain directories.  A typical use is
2297 to add the element @code{("." . @var{dir})} to force Emacs to put
2298 @strong{all} backup files in the directory @file{dir}.
2300 @node Disabling auto-save-mode, Going to a line by number, Disabling backups, Common requests
2301 @section How do I disable @code{auto-save-mode}?
2302 @cindex Disabling @code{auto-save-mode}
2303 @cindex Auto-saving
2304 @cindex Saving at frequent intervals
2306 You probably don't want to do this, since auto-saving is useful,
2307 especially when Emacs or your computer crashes while you are editing a
2308 document.
2310 Instead, you might want to change the variable
2311 @code{auto-save-interval}, which specifies how many keystrokes Emacs
2312 waits before auto-saving.  Increasing this value forces Emacs to wait
2313 longer between auto-saves, which might annoy you less.
2315 You might also want to look into Sebastian Kremer's @code{auto-save}
2316 package (@pxref{Packages that do not come with Emacs}).  This
2317 package also allows you to place all auto-save files in one directory,
2318 such as @file{/tmp}.
2320 To disable or change how @code{auto-save-mode} works, @inforef{Auto
2321 Save, , emacs}.
2323 @node Going to a line by number, Modifying pull-down menus, Disabling auto-save-mode, Common requests
2324 @section How can I go to a certain line given its number?
2325 @cindex Going to a line by number
2326 @cindex Compilation error messages
2327 @cindex Recompilation
2329 Are you sure you indeed need to go to a line by its number?  Perhaps all
2330 you want is to display a line in your source file for which a compiler
2331 printed an error message?  If so, compiling from within Emacs using the
2332 @kbd{M-x compile} and @kbd{M-x recompile} commands is a much more
2333 effective way of doing that.  Emacs automatically intercepts the compile
2334 error messages, inserts them into a special buffer called
2335 @code{*compilation*}, and lets you visit the locus of each message in
2336 the source.  Type @kbd{C-x `} to step through the offending lines one by
2337 one.  Click @kbd{Mouse-2} or press @key{RET} on a message text in the
2338 @code{*compilation*} buffer to go to the line whose number is mentioned
2339 in that message.
2341 But if you indeed need to go to a certain text line, type @kbd{M-x
2342 goto-line @key{RET}}.  Emacs will prompt you for the number of the line
2343 and go to that line.
2345 You can do this faster by invoking @code{goto-line} with a numeric
2346 argument that is the line's number.  For example, @kbd{C-u 286 M-x
2347 goto-line @key{RET}} will jump to line number 286 in the current
2348 buffer.
2350 If you need to use this command frequently, you might consider binding
2351 it to a key.  The following snippet, if added to your @file{~/.emacs}
2352 file, will bind the sequence @kbd{C-x g} to @code{goto-line}:
2354 @lisp
2355  (global-set-key "\C-xg" 'goto-line)
2356 @end lisp
2359 @node Modifying pull-down menus, Deleting menus and menu options, Going to a line by number, Common requests
2360 @section How can I create or modify new pull-down menu options?
2361 @cindex Pull-down menus, creating or modifying
2362 @cindex Menus, creating or modifying
2363 @cindex Creating new menu options
2364 @cindex Modifying pull-down menus
2365 @cindex Menus and keymaps
2366 @cindex Keymaps and menus
2368 Each menu title (e.g., @samp{File}, @samp{Edit}, @samp{Buffers})
2369 represents a local or global keymap.  Selecting a menu title with the
2370 mouse displays that keymap's non-nil contents in the form of a menu.
2372 So to add a menu option to an existing menu, all you have to do is add a
2373 new definition to the appropriate keymap.  Adding a @samp{Forward Word}
2374 item to the @samp{Edit} menu thus requires the following Lisp code:
2376 @lisp
2377 (define-key global-map
2378   [menu-bar edit forward]
2379   '("Forward word" . forward-word))
2380 @end lisp
2382 @noindent
2383 The first line adds the entry to the global keymap, which includes
2384 global menu bar entries.  Replacing the reference to @code{global-map}
2385 with a local keymap would add this menu option only within a particular
2386 mode.
2388 The second line describes the path from the menu-bar to the new entry.
2389 Placing this menu entry underneath the @samp{File} menu would mean
2390 changing the word @code{edit} in the second line to @code{file}.
2392 The third line is a cons cell whose first element is the title that will
2393 be displayed, and whose second element is the function that will be
2394 called when that menu option is invoked.
2396 To add a new menu, rather than a new option to an existing menu, we must
2397 define an entirely new keymap:
2399 @lisp
2400 (define-key global-map [menu-bar words]
2401   (cons "Words" (make-sparse-keymap "Words")))
2402 @end lisp
2404 The above code creates a new sparse keymap, gives it the name
2405 @samp{Words}, and attaches it to the global menu bar.  Adding the
2406 @samp{Forward Word} item to this new menu would thus require the
2407 following code:
2409 @lisp
2410 (define-key global-map
2411   [menu-bar words forward]
2412   '("Forward word" . forward-word))
2413 @end lisp
2415 @noindent
2416 Note that because of the way keymaps work, menu options are displayed
2417 with the more recently defined items at the top.  Thus if you were to
2418 define menu options @samp{foo}, @samp{bar}, and @samp{baz} (in that
2419 order), the menu option @samp{baz} would appear at the top, and
2420 @samp{foo} would be at the bottom.
2422 One way to avoid this problem is to use the function @code{define-key-after},
2423 which works the same as @code{define-key}, but lets you modify where items
2424 appear.  The following Lisp code would insert the @samp{Forward Word}
2425 item in the @samp{Edit} menu immediately following the @samp{Undo} item:
2427 @lisp
2428 (define-key-after
2429   (lookup-key global-map [menu-bar edit])
2430   [forward]
2431   '("Forward word" . forward-word)
2432   'undo)
2433 @end lisp
2435 Note how the second and third arguments to @code{define-key-after} are
2436 different from those of @code{define-key}, and that we have added a new
2437 (final) argument, the function after which our new key should be
2438 defined.
2440 To move a menu option from one position to another, simply evaluate
2441 @code{define-key-after} with the appropriate final argument.
2443 More detailed information---and more examples of how to create and
2444 modify menu options---are in the @cite{Emacs Lisp Reference Manual}, under
2445 ``Menu Keymaps''.  (@xref{Emacs Lisp documentation}, for information on
2446 this manual.)
2448 @node Deleting menus and menu options, Turning on syntax highlighting, Modifying pull-down menus, Common requests
2449 @section How do I delete menus and menu options?
2450 @cindex Deleting menus and menu options
2451 @cindex Menus, deleting
2453 The simplest way to remove a menu is to set its keymap to @samp{nil}.
2454 For example, to delete the @samp{Words} menu (@pxref{Modifying pull-down
2455 menus}), use:
2457 @lisp
2458 (define-key global-map [menu-bar words] nil)
2459 @end lisp
2461 Similarly, removing a menu option requires redefining a keymap entry to
2462 @code{nil}.  For example, to delete the @samp{Forward word} menu option
2463 from the @samp{Edit} menu (we added it in @ref{Modifying pull-down
2464 menus}), use:
2466 @lisp
2467 (define-key global-map [menu-bar edit forward] nil)
2468 @end lisp
2470 @node Turning on syntax highlighting, Scrolling only one line, Deleting menus and menu options, Common requests
2471 @section How do I turn on syntax highlighting?
2472 @cindex Syntax highlighting
2473 @cindex @code{font-lock-mode}
2474 @cindex Highlighting based on syntax
2475 @cindex Colorizing text
2476 @cindex FAQ, @code{font-lock-mode}
2478 @code{font-lock-mode} is the standard way to have Emacs perform syntax
2479 highlighting in the current buffer.  With @code{font-lock-mode} turned
2480 on, different types of text will appear in different colors.  For
2481 instance, if you turn on @code{font-lock-mode} in a programming mode,
2482 variables will appear in one face, keywords in a second, and comments in
2483 a third.
2485 @cindex hilit19 is deprecated
2486 Earlier versions of Emacs supported hilit19, a similar package.  Use of
2487 hilit19 is now considered non-standard, although @file{hilit19.el} comes
2488 with the stock Emacs distribution.  It is no longer maintained.
2490 To turn @code{font-lock-mode} on within an existing buffer, use @kbd{M-x
2491 font-lock-mode @key{RET}}.
2493 To automatically invoke @code{font-lock-mode} when a particular major
2494 mode is invoked, set the major mode's hook.  For example, to fontify all
2495 @code{c-mode} buffers, add the following to your @file{.emacs} file:
2497 @lisp
2498 (add-hook 'c-mode-hook 'turn-on-font-lock)
2499 @end lisp
2501 To automatically invoke @code{font-lock-mode} for all major modes, you
2502 can turn on @code{global-font-lock-mode} by including the following line
2503 in your @file{.emacs} file:
2505 @lisp
2506 (global-font-lock-mode 1)
2507 @end lisp
2509 @noindent
2510 This instructs Emacs to turn on font-lock mode in those buffers for
2511 which a font-lock mode definition has been provided (in the variable
2512 @code{font-lock-global-modes}).  If you edit a file in
2513 @code{pie-ala-mode}, and no font-lock definitions have been provided for
2514 @code{pie-ala} files, then the above setting will have no effect on that
2515 particular buffer.
2517 Highlighting a buffer with @code{font-lock-mode} can take quite a while,
2518 and cause an annoying delay in display, so several features exist to
2519 work around this.
2521 @cindex Just-In-Time syntax highlighting
2522 In Emacs 21 and later, turning on @code{font-lock-mode} automatically
2523 activates the new @dfn{Just-In-Time fontification} provided by
2524 @code{jit-lock-mode}.  @code{jit-lock-mode} defers the fontification of
2525 portions of buffer until you actually need to see them, and can also
2526 fontify while Emacs is idle.  This makes display of the visible portion
2527 of a buffer almost instantaneous.  For details about customizing
2528 @code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}.
2530 @cindex Levels of syntax highlighting
2531 @cindex Decoration level, in @code{font-lock-mode}
2532 In versions of Emacs before 21, different levels of decoration are
2533 available, from slight to gaudy.  More decoration means you need to wait
2534 more time for a buffer to be fontified (or a faster machine).  To
2535 control how decorated your buffers should become, set the value of
2536 @code{font-lock-maximum-decoration} in your @file{.emacs} file, with a
2537 @code{nil} value indicating default (usually minimum) decoration, and a
2538 @code{t} value indicating the maximum decoration.  For the gaudiest
2539 possible look, then, include the line
2541 @lisp
2542 (setq font-lock-maximum-decoration t)
2543 @end lisp
2545 @noindent
2546 in your @file{.emacs} file.  You can also set this variable such that
2547 different modes are highlighted in a different ways; for more
2548 information, see the documentation for
2549 @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x
2550 describe-variable @key{RET}}).
2552 @cindex Lazy font-lock
2553 You might also want to investigate @code{fast-lock-mode} and
2554 @code{lazy-lock-mode}, versions of @code{font-lock-mode} that speed up
2555 highlighting.  These are the alternatives for @code{jit-lock-mode} in
2556 versions of Emacs before 21.1.  The advantage of @code{lazy-lock-mode}
2557 is that it only fontifies buffers when certain conditions are met, such
2558 as after a certain amount of idle time, or after you have finished
2559 scrolling through text.  See the documentation for @code{lazy-lock-mode}
2560 by typing @kbd{C-h f @code{lazy-lock-mode}} (@kbd{M-x describe-function
2561 @key{RET} lazy-lock-mode @key{RET}}).
2563 Also see the documentation for the function @code{font-lock-mode},
2564 available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x
2565 describe-function @key{RET} font-lock-mode @key{RET}}).
2567 For more information on font-lock mode, take a look at the
2568 @code{font-lock-mode} FAQ, maintained by
2569 @email{jari.aalto@@ntc.nokia.com, Jari Aalto} at
2571 @uref{ftp://cs.uta.fi/pub/ssjaaa/ema-font.gui}
2573 To print buffers with the faces (i.e., colors and fonts) intact, use
2574 @kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x
2575 ps-print-region-with-faces}.  You will need a way to send text to a
2576 PostScript printer, or a PostScript interpreter such as Ghostscript;
2577 consult the documentation of the variables @code{ps-printer-name},
2578 @code{ps-lpr-command}, and @code{ps-lpr-switches} for more details.
2580 @node Scrolling only one line, Replacing highlighted text, Turning on syntax highlighting, Common requests
2581 @section How can I force Emacs to scroll only one line when I move past the bottom of the screen?
2582 @cindex Scrolling only one line
2583 @cindex Reducing the increment when scrolling
2585 Place the following Lisp form in your @file{.emacs} file:
2587 @lisp
2588 (setq scroll-step 1)
2589 @end lisp
2591 @inforef{Scrolling, Scrolling, emacs}.
2593 @node Replacing highlighted text, Editing MS-DOS files, Scrolling only one line, Common requests
2594 @section How can I replace highlighted text with what I type?
2595 @cindex @code{delete-selection-mode}
2596 @cindex Replacing highlighted text
2597 @cindex Highlighting and replacing text
2599 Use @code{delete-selection-mode}, which you can start automatically by
2600 placing the following Lisp form in your @file{.emacs} file:
2602 @lisp
2603 (delete-selection-mode t)
2604 @end lisp
2606 According to the documentation string for @code{delete-selection-mode}
2607 (which you can read using @kbd{M-x describe-function @key{RET}
2608 delete-selection-mode @key{RET}}):
2610 @quotation
2611 When ON, typed text replaces the selection if the selection is active.
2612 When OFF, typed text is just inserted at point.
2613 @end quotation
2615 This mode also allows you to delete (not kill) the highlighted region by
2616 pressing @key{DEL}.
2618 @node Editing MS-DOS files, Filling paragraphs with a single space, Replacing highlighted text, Common requests
2619 @section How can I edit MS-DOS files using Emacs?
2620 @cindex Editing MS-DOS files
2621 @cindex MS-DOS files, editing
2622 @cindex Microsoft files, editing
2623 @cindex Windows files, editing
2625 As of Emacs 20, detection and handling of MS-DOS (and Windows) files is
2626 performed transparently.  You can open MS-DOS files on a Unix system,
2627 edit it, and save it without having to worry about the file format.
2629 When editing an MS-DOS style file, the mode line will indicate that it
2630 is a DOS file.  On Unix and GNU/Linux systems, and also on a Macintosh,
2631 the string @samp{(DOS)} will appear near the left edge of the mode line;
2632 on DOS and Windows, where the DOS end-of-line (EOL) format is the
2633 default, a backslash (@samp{\}) will appear in the mode line.
2635 If you are running a version of Emacs before 20.1, get @code{crypt++}
2636 (@pxref{Packages that do not come with Emacs}).  Among other things, 
2637 @code{crypt++} transparently modifies MS-DOS files as they are loaded
2638 and saved, allowing you to ignore the different conventions that Unix
2639 and MS-DOS have for delineating the end of a line.
2641 @node Filling paragraphs with a single space,  Escape sequences in shell output, Editing MS-DOS files, Common requests
2642 @section How can I tell Emacs to fill paragraphs with a single space after each period?
2643 @cindex One space following periods
2644 @cindex Single space following periods
2645 @cindex Periods, one space following
2647 @email{ulm@@vsnhd1.cern.ch, Ulrich Mueller} suggests adding the
2648 following two lines to your @file{.emacs} file:
2650 @lisp
2651 (setq sentence-end "[.?!][]\"')@}]*\\($\\|[ \t]\\)[ \t\n]*")
2652 (setq sentence-end-double-space nil)
2653 @end lisp
2655 @node Escape sequences in shell output, , Filling paragraphs with a single space, Common requests
2656 @section Why these strange escape sequences from @code{ls} from the Shell mode?
2657 @cindex Escape sequences in @code{ls} output
2658 @cindex @code{ls} in Shell mode
2660 This happens because @code{ls} is aliased to @samp{ls --color} in your
2661 shell init file.  You have two alternatives to solve this:
2663 @itemize @bullet
2664 @item
2665 Make the alias conditioned on the @code{EMACS} variable in the
2666 environment.  When Emacs runs a subsidiary shell, it exports the
2667 @code{EMACS} variable with the value @code{t} to that shell.  You can
2668 unalias @code{ls} when that happens, thus limiting the alias to your
2669 interactive sessions.
2671 @item
2672 Install the @code{ansi-color} package (bundled with Emacs 21.1 and
2673 later), which converts these ANSI escape sequences into colors.
2674 @end itemize
2676 @c ------------------------------------------------------------
2677 @node    Bugs and problems, Compiling and installing Emacs, Common requests, Top
2678 @chapter Bugs and problems
2679 @cindex Bugs and problems
2681 The Emacs manual lists some common kinds of trouble users could get
2682 into, see @ref{Lossage, , Dealing with Emacs Trouble, emacs, The GNU
2683 Emacs Manual}, so you might look there if the problem you encounter
2684 isn't described in this chapter.  If you decide you've discovered a bug,
2685 see @ref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}, for
2686 instructions how to do that.
2688 The file @file{etc/PROBLEMS} in the Emacs distribution lists various
2689 known problems with building and using Emacs on specific platforms;
2690 type @kbd{C-h P} to read it.
2692 @menu
2693 * Problems with very large files::
2694 * ^M in the shell buffer::
2695 * Shell process exits abnormally::
2696 * Problems with Shell Mode on MS-Windows::
2697 * Termcap/Terminfo entries for Emacs::
2698 * Spontaneous entry into isearch-mode::
2699 * Problems talking to certain hosts::
2700 * Errors with init files::
2701 * Emacs ignores X resources::
2702 * Emacs ignores frame parameters::
2703 * Emacs takes a long time to visit files::
2704 * Editing files with $ in the name::
2705 * Shell mode loses the current directory::
2706 * Security risks with Emacs::
2707 * Dired claims that no file is on this line::
2708 @end menu
2710 @node Problems with very large files, ^M in the shell buffer, Bugs and problems, Bugs and problems
2711 @section Does Emacs have problems with files larger than 8 megabytes?
2712 @cindex Very large files, opening
2713 @cindex Large files, opening
2714 @cindex Opening very large files
2715 @cindex Maximum file size
2716 @cindex Files, maximum size
2718 Old versions (i.e., anything before 19.29) of Emacs had problems editing
2719 files larger than 8 megabytes.  As of version 19.29, the maximum buffer
2720 size is at least 2^27-1, or 134,217,727 bytes, or 132 MBytes.  Emacs 20
2721 can be compiled on some 64-bit systems in a way that enlarges the buffer
2722 size up to 576,460,752,303,423,487 bytes, or 549,755,813 GBytes.
2724 If you are using a version of Emacs older than 19.29 and cannot upgrade,
2725 you will have to recompile. @email{lnz@@lucid.com, Leonard N. Zubkoff}
2726 suggests putting the following two lines in @file{src/config.h} before
2727 compiling Emacs to allow for 26-bit integers and pointers (and thus file
2728 sizes of up to 33,554,431 bytes):
2730 @example
2731 #define VALBITS 26
2732 #define GCTYPEBITS 5
2733 @end example
2735 @noindent
2736 This method may result in "ILLEGAL DATATYPE" and other random errors on
2737 some machines.
2739 @email{daveg@@csvax.cs.caltech.edu, David Gillespie} explains how this
2740 problems crops up; while his numbers are true only for pre-19.29
2741 versions of Emacs, the theory remains the same with current versions.
2743 @quotation
2744 Emacs is largely written in a dialect of Lisp; Lisp is a freely-typed
2745 language in the sense that you can put any value of any type into any
2746 variable, or return it from a function, and so on.  So each value
2747 must carry a @dfn{tag} along with it identifying what kind of thing it
2748 is, e.g., integer, pointer to a list, pointer to an editing buffer, and
2749 so on.  Emacs uses standard 32-bit integers for data objects, taking the
2750 top 8 bits for the tag and the bottom 24 bits for the value.  So
2751 integers (and pointers) are somewhat restricted compared to true C
2752 integers and pointers.
2753 @end quotation
2755 @node ^M in the shell buffer, Shell process exits abnormally, Problems with very large files, Bugs and problems
2756 @section How do I get rid of @samp{^M} or echoed commands in my shell buffer?
2757 @cindex Shell buffer, echoed commands and @samp{^M} in
2758 @cindex Echoed commands in @code{shell-mode}
2760 Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to
2761 make them go away.  If that doesn't work, you have several options:
2763 For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc})
2764 file:
2766 @example
2767 if ($?EMACS) then
2768     if ("$EMACS" == t) then
2769         if ($?tcsh) unset edit
2770         stty nl
2771     endif
2772 endif
2773 @end example
2775 Or put this in your @file{.emacs_tcsh} file:
2777 @example
2778 unset edit
2779 stty nl
2780 @end example
2782 Alternatively, use @code{csh} in your shell buffers instead of
2783 @code{tcsh}.  One way is:
2785 @lisp
2786 (setq explicit-shell-file-name "/bin/csh")
2787 @end lisp
2789 @noindent
2790 and another is to do this in your @file{.cshrc} (or @file{.tcshrc})
2791 file:
2793 @example
2794 setenv ESHELL /bin/csh
2795 @end example
2797 @noindent
2798 (You must start Emacs over again with the environment variable properly
2799 set for this to take effect.)
2801 You can also set the @code{ESHELL} environment variable in Emacs Lisp
2802 with the following Lisp form,
2804 @lisp
2805 (setenv "ESHELL" "/bin/csh")
2806 @end lisp
2808 The above solutions try to prevent the shell from producing the
2809 @samp{^M} characters in the first place.  If this is not possible
2810 (e.g., if you use a Windows shell), you can get Emacs to remove these
2811 characters from the buffer by adding this to your @file{.emacs} init
2812 file:
2814 @smalllisp
2815 (add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m)
2816 @end smalllisp
2818 On a related note: If your shell is echoing your input line in the shell
2819 buffer, you might want to try the following command in your shell
2820 start-up file:
2822 @example
2823 stty -icrnl -onlcr -echo susp ^Z
2824 @end example
2826 @node Shell process exits abnormally, Problems with Shell Mode on MS-Windows, ^M in the shell buffer, Bugs and problems
2827 @section Why do I get "Process shell exited abnormally with code 1"?
2828 @cindex Abnormal exits from @code{shell-mode}
2829 @cindex @code{shell-mode} exits
2830 @cindex Process shell exited
2832 The most likely reason for this message is that the @samp{env} program
2833 is not properly installed.  Compile this program for your architecture,
2834 and install it with @samp{a+x} permission in the architecture-dependent
2835 Emacs program directory.  (You can find what this directory is at your
2836 site by inspecting the value of the variable @code{exec-directory} by
2837 typing @kbd{C-h v exec-directory @key{RET}}.)
2839 You should also check for other programs named @samp{env} in your path
2840 (e.g., SunOS has a program named @file{/usr/bin/env}).  We don't
2841 understand why this can cause a failure and don't know a general
2842 solution for working around the problem in this case.
2844 The @samp{make clean} command will remove @samp{env} and other vital
2845 programs, so be careful when using it.
2847 It has been reported that this sometimes happened when Emacs was started
2848 as an X client from an xterm window (i.e., had a controlling tty) but the
2849 xterm was later terminated.
2851 See also @samp{PROBLEMS} (in the @file{etc} subdirectory of the
2852 top-level directory when you unpack the Emacs source) for other
2853 possible causes of this message.
2855 @node Problems with Shell Mode on MS-Windows, Termcap/Terminfo entries for Emacs, Shell process exits abnormally, Bugs and problems
2856 @section Why do I get an error message when I try to run @kbd{M-x shell}?
2858 @cindex Shell Mode, and MS-Windows
2859 @cindex @code{explicit-shell-file-name}
2860 On MS-Windows, this might happen because Emacs tries to look for the
2861 shell in a wrong place.  The default file name @file{/bin/sh} is
2862 usually incorrect for non-Unix systems.  If you know where your shell
2863 executable is, set the variable @code{explicit-shell-file-name} in
2864 your @file{.emacs} file to point to its full file name, like this:
2866 @lisp
2867 (setq explicit-shell-file-name "d:/shells/bash.exe")
2868 @end lisp
2870 If you don't know what shell does Emacs use, try the @kbd{M-!}
2871 command; if that works, put the following line into your
2872 @file{.emacs}:
2874 @lisp
2875 (setq explicit-shell-file-name shell-file-name)
2876 @end lisp
2878 @cindex Antivirus programs, and Shell Mode
2879 Some people have trouble with Shell Mode because of intrusive
2880 antivirus software; disabling the resident antivirus program solves
2881 the problems in those cases.
2883 @node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Problems with Shell Mode on MS-Windows, Bugs and problems
2884 @section Where is the termcap/terminfo entry for terminal type "emacs"?
2885 @cindex Termcap
2886 @cindex Terminfo
2887 @cindex Emacs entries for termcap/terminfo
2889 The termcap entry for terminal type @samp{emacs} is ordinarily put in
2890 the @samp{TERMCAP} environment variable of subshells.  It may help in
2891 certain situations (e.g., using rlogin from shell buffer) to add an
2892 entry for @samp{emacs} to the system-wide termcap file.  Here is a
2893 correct termcap entry for @samp{emacs}:
2895 @example
2896 emacs:tc=unknown:
2897 @end example
2899 To make a terminfo entry for @samp{emacs}, use @code{tic} or
2900 @code{captoinfo}.  You need to generate
2901 @file{/usr/lib/terminfo/e/emacs}.  It may work to simply copy
2902 @file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emacs}.
2904 Having a termcap/terminfo entry will not enable the use of full screen
2905 programs in shell buffers.  Use @kbd{M-x terminal-emulator} for that
2906 instead.
2908 A workaround to the problem of missing termcap/terminfo entries is to
2909 change terminal type @samp{emacs} to type @samp{dumb} or @samp{unknown}
2910 in your shell start up file.  @code{csh} users could put this in their
2911 @file{.cshrc} files:
2913 @example
2914 if ("$term" == emacs) set term=dumb
2915 @end example
2917 @node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems
2918 @section Why does Emacs spontaneously start displaying "I-search:" and beeping?
2919 @cindex Spontaneous entry into isearch-mode
2920 @cindex isearch-mode, spontaneous entry into
2921 @cindex Beeping without obvious reason
2923 Your terminal (or something between your terminal and the computer) is
2924 sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving
2925 these characters and interpreting them as commands.  (The @kbd{C-s}
2926 character normally invokes the @code{isearch-forward} command.)  For
2927 possible solutions, see @ref{Handling C-s and C-q with flow control}.
2929 @node Problems talking to certain hosts, Errors with init files, Spontaneous entry into isearch-mode, Bugs and problems
2930 @section Why can't Emacs talk to certain hosts (or certain hostnames)?
2931 @cindex Hosts, Emacs cannot talk to
2932 @cindex @code{gethostbyname}, problematic version
2934 The problem may be that Emacs is linked with a wimpier version of
2935 @code{gethostbyname} than the rest of the programs on the machine.  This
2936 is often manifested as a message on startup of ``X server not responding.
2937 Check your @samp{DISPLAY} environment variable.'' or a message of
2938 ``Unknown host'' from @code{open-network-stream}.
2940 On a Sun, this may be because Emacs had to be linked with the static C
2941 library.  The version of @code{gethostbyname} in the static C library
2942 may only look in @file{/etc/hosts} and the NIS (YP) maps, while the
2943 version in the dynamic C library may be smart enough to check DNS in
2944 addition to or instead of NIS.  On a Motorola Delta running System V
2945 R3.6, the version of @code{gethostbyname} in the standard library works,
2946 but the one that works with NIS doesn't (the one you get with -linet).
2947 Other operating systems have similar problems.
2949 Try these options:
2951 @itemize @bullet
2953 @item
2954 Explicitly add the host you want to communicate with to @file{/etc/hosts}.
2956 @item
2957 Relink Emacs with this line in @file{src/config.h}:
2959 @example
2960 #define LIBS_SYSTEM -lresolv
2961 @end example
2963 @item
2964 Replace @code{gethostbyname} and friends in @file{libc.a} with more
2965 useful versions such as the ones in @file{libresolv.a}.  Then relink
2966 Emacs.
2968 @item
2969 If you are actually running NIS, make sure that @code{ypbind} is
2970 properly told to do DNS lookups with the correct command line switch.
2972 @end itemize
2974 @node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems
2975 @section Why does Emacs say "Error in init file"?
2976 @cindex Error in @file{.emacs}
2977 @cindex Error in init file
2978 @cindex Init file, errors in
2979 @cindex @file{.emacs} file, errors in
2980 @cindex Debugging @file{.emacs} file
2982 An error occurred while loading either your @file{.emacs} file or the
2983 system-wide file @file{lisp/default.el}.  Emacs 21.1 and later pops the
2984 @file{*Messages*} buffer, and puts there some additional information
2985 about the error, to provide some hints for debugging.
2987 For information on how to debug your @file{.emacs} file, see
2988 @ref{Debugging a customization file}.
2990 It may be the case that you need to load some package first, or use a
2991 hook that will be evaluated after the package is loaded.  A common case
2992 of this is explained in @ref{Terminal setup code works after Emacs has
2993 begun}.
2995 @node Emacs ignores X resources, Emacs ignores frame parameters, Errors with init files, Bugs and problems
2996 @section Why does Emacs ignore my X resources (my .Xdefaults file)?
2997 @cindex X resources being ignored
2998 @cindex Ignored X resources
2999 @cindex @file{.Xdefaults}
3001 As of version 19, Emacs searches for X resources in the files specified
3002 by the following environment variables:
3004 @itemize @bullet
3006 @item @code{XFILESEARCHPATH}
3007 @item @code{XUSERFILESEARCHPATH}
3008 @item @code{XAPPLRESDIR}
3010 @end itemize
3012 This emulates the functionality provided by programs written using the
3013 Xt toolkit.
3015 @code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list
3016 of file names separated by colons.  @code{XAPPLRESDIR} should be a list
3017 of directory names separated by colons.
3019 Emacs searches for X resources:
3021 @enumerate
3023 @item
3024 specified on the command line, with the @samp{-xrm RESOURCESTRING} option,
3026 @item
3027 then in the value of the @samp{XENVIRONMENT} environment variable,
3029 @itemize @minus
3031 @item
3032 or if that is unset, in the file named
3033 @file{~/.Xdefaults-@var{hostname}} if it exists (where @var{hostname} is
3034 the name of the machine Emacs is running on),
3036 @end itemize
3038 @item
3039 then in the screen-specific and server-wide resource properties provided
3040 by the server,
3042 @itemize @minus
3044 @item
3045 or if those properties are unset, in the file named @file{~/.Xdefaults}
3046 if it exists,
3048 @end itemize
3050 @item
3051 then in the files listed in @samp{XUSERFILESEARCHPATH},
3053 @itemize @minus
3055 @item
3056 or in files named @file{@var{lang}/Emacs} in directories listed in
3057 @samp{XAPPLRESDIR} (where @var{lang} is the value of the @code{LANG}
3058 environment variable), if the @samp{LANG} environment variable is set,
3059 @item
3060 or in files named Emacs in the directories listed in @samp{XAPPLRESDIR}
3061 @item
3062 or in @file{~/@var{lang}/Emacs} (if the @code{LANG} environment variable
3063 is set),
3064 @item
3065 or in @file{~/Emacs},
3067 @end itemize
3069 @item
3070 then in the files listed in  @code{XFILESEARCHPATH}.
3072 @end enumerate
3074 @node Emacs ignores frame parameters, Emacs takes a long time to visit files, Emacs ignores X resources, Bugs and problems
3075 @section Why don't my customizations of the frame parameters work?
3076 @cindex Frame parameters
3078 This probably happens because you have set the frame parameters in the
3079 variable @code{initial-frame-alist}.  That variable holds parameters
3080 used only for the first frame created when Emacs starts.  To customize
3081 the parameters of all frames, change the variable
3082 @code{default-frame-alist} instead.
3084 These two variables exist because many users customize the initial frame
3085 in a special way.  For example, you could determine the position and
3086 size of the initial frame, but would like to control the geometry of the
3087 other frames by individually positioning each one of them.
3090 @node Emacs takes a long time to visit files, Editing files with $ in the name, Emacs ignores frame parameters, Bugs and problems
3091 @section Why does Emacs take 20 seconds to visit a file?
3092 @cindex Visiting files takes a long time
3093 @cindex Delay when visiting files
3094 @cindex Files, take a long time to visit
3096 Old versions of Emacs (i.e., versions before Emacs 20.x) often
3097 encountered this when the master lock file, @file{!!!SuperLock!!!}, has
3098 been left in the lock directory somehow.  Delete it.
3100 @email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug
3101 where an exclusive create succeeds but returns an error status.  This
3102 can cause the same problem.  Since Emacs's file locking doesn't work
3103 over NFS anyway, the best solution is to recompile Emacs with
3104 @code{CLASH_DETECTION} undefined.
3106 @node Editing files with $ in the name, Shell mode loses the current directory, Emacs takes a long time to visit files, Bugs and problems
3107 @section How do I edit a file with a @samp{$} in its name?
3108 @cindex Editing files with @samp{$} in the name
3109 @cindex @samp{$} in file names
3110 @cindex File names containing @samp{$}, editing
3112 When entering a file name in the minibuffer, Emacs will attempt to expand
3113 a @samp{$} followed by a word as an environment variable.  To suppress
3114 this behavior, type @kbd{$$} instead.
3116 @node Shell mode loses the current directory, Security risks with Emacs, Editing files with $ in the name, Bugs and problems
3117 @section Why does shell mode lose track of the shell's current directory?
3118 @cindex Current directory and @code{shell-mode}
3119 @cindex @code{shell-mode} and current directory
3120 @cindex Directory, current in @code{shell-mode}
3122 Emacs has no way of knowing when the shell actually changes its
3123 directory.  This is an intrinsic limitation of Unix.  So it tries to
3124 guess by recognizing @samp{cd} commands.  If you type @kbd{cd} followed
3125 by a directory name with a variable reference (@kbd{cd $HOME/bin}) or
3126 with a shell metacharacter (@kbd{cd ../lib*}), Emacs will fail to
3127 correctly guess the shell's new current directory.  A huge variety of
3128 fixes and enhancements to shell mode for this problem have been written
3129 to handle this problem (@pxref{Finding a package with particular
3130 functionality}).
3132 You can tell Emacs the shell's current directory with the command
3133 @kbd{M-x dirs}.
3135 @node Security risks with Emacs, Dired claims that no file is on this line, Shell mode loses the current directory, Bugs and problems
3136 @section Are there any security risks in Emacs?
3137 @cindex Security with Emacs
3138 @cindex @samp{movemail} and security
3139 @cindex @code{file-local-variable} and security
3140 @cindex Synthetic X events and security
3141 @cindex X events and security
3143 @itemize @bullet
3145 @item
3146 The @file{movemail} incident.  (No, this is not a risk.)
3148 In his book @cite{The Cuckoo's Egg}, Cliff Stoll describes this in
3149 chapter 4.  The site at LBL had installed the @file{/etc/movemail}
3150 program setuid root.  (As of version 19, @file{movemail} is in your
3151 architecture-specific directory; type @kbd{C-h v exec-directory
3152 @key{RET}} to see what it is.)  Since @code{movemail} had not been
3153 designed for this situation, a security hole was created and users could
3154 get root privileges.
3156 @code{movemail} has since been changed so that this security hole will
3157 not exist, even if it is installed setuid root.  However,
3158 @code{movemail} no longer needs to be installed setuid root, which
3159 should eliminate this particular risk.
3161 We have heard unverified reports that the 1988 Internet worm took
3162 advantage of this configuration problem.
3164 @item
3165 The @code{file-local-variable} feature.  (Yes, a risk, but easy to
3166 change.)
3168 There is an Emacs feature that allows the setting of local values for
3169 variables when editing a file by including specially formatted text near
3170 the end of the file.  This feature also includes the ability to have
3171 arbitrary Emacs Lisp code evaluated when the file is visited.
3172 Obviously, there is a potential for Trojan horses to exploit this
3173 feature.
3175 Emacs 18 allowed this feature by default; users could disable it by
3176 setting the variable @code{inhibit-local-variables} to a non-nil value.
3178 As of Emacs 19, Emacs has a list of local variables that create a
3179 security risk.  If a file tries to set one of them, it asks the user to
3180 confirm whether the variables should be set.  You can also tell Emacs
3181 whether to allow the evaluation of Emacs Lisp code found at the bottom
3182 of files by setting the variable @code{enable-local-eval}.
3184 For more information, @inforef{File Variables, File Variables, emacs}.
3186 @item
3187 Synthetic X events.  (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or
3188 better.)
3190 Emacs accepts synthetic X events generated by the @code{SendEvent}
3191 request as though they were regular events.  As a result, if you are
3192 using the trivial host-based authentication, other users who can open X
3193 connections to your X workstation can make your Emacs process do
3194 anything, including run other processes with your privileges.
3196 The only fix for this is to prevent other users from being able to open
3197 X connections.  The standard way to prevent this is to use a real
3198 authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}.  If using
3199 the @code{xauth} program has any effect, then you are probably using
3200 @samp{MIT-MAGIC-COOKIE-1}.  Your site may be using a superior
3201 authentication method; ask your system administrator.
3203 If real authentication is not a possibility, you may be satisfied by
3204 just allowing hosts access for brief intervals while you start your X
3205 programs, then removing the access.  This reduces the risk somewhat by
3206 narrowing the time window when hostile users would have access, but
3207 @emph{does not eliminate the risk}.
3209 On most computers running Unix and X, you enable and disable
3210 access using the @code{xhost} command.  To allow all hosts access to
3211 your X server, use
3213 @example
3214 xhost +
3215 @end example
3217 @noindent
3218 at the shell prompt, which (on an HP machine, at least) produces the
3219 following message:
3221 @example
3222 access control disabled, clients can connect from any host
3223 @end example
3225 To deny all hosts access to your X server (except those explicitly
3226 allowed by name), use
3228 @example
3229 xhost -
3230 @end example
3232 On the test HP computer, this command generated the following message:
3234 @example
3235 access control enabled, only authorized clients can connect
3236 @end example
3238 @end itemize
3240 @node Dired claims that no file is on this line,  , Security risks with Emacs, Bugs and problems
3241 @section Dired says, "no file on this line" when I try to do something.
3242 @cindex Dired does not see a file
3244 @c FIXME: I think this is fixed in Emacs 21, but I didn't have time to
3245 @c check.
3246 Chances are you're using a localized version of Unix that doesn't use US
3247 date format in dired listings.  You can check this by looking at dired
3248 listings or by typing @kbd{ls -l} to a shell and looking at the dates that
3249 come out.
3251 Dired uses a regular expression to find the beginning of a file name.
3252 In a long Unix-style directory listing (@samp{ls -l}), the file name
3253 starts after the date.  The regexp has thus been written to look for the
3254 date, the format of which can vary on non-US systems.
3256 There are two approaches to solving this.  The first one involves
3257 setting things up so that @samp{ls -l} outputs US date format.  This can
3258 be done by setting the locale.  See your OS manual for more information.
3260 The second approach involves changing the regular expression used by
3261 dired, @code{dired-move-to-filename-regexp}.
3263 @c ------------------------------------------------------------
3264 @node Compiling and installing Emacs, Finding Emacs and related packages, Bugs and problems, Top
3265 @chapter    Compiling and installing Emacs
3266 @cindex    Compiling and installing Emacs
3268 @menu
3269 * Installing Emacs::
3270 * Updating Emacs::
3271 * Problems building Emacs::
3272 * Linking with -lX11 fails::
3273 @end menu
3275 @node Installing Emacs, Updating Emacs, Compiling and installing Emacs, Compiling and installing Emacs
3276 @section How do I install Emacs?
3277 @cindex Installing Emacs
3278 @cindex Unix systems, installing Emacs on
3279 @cindex Downloading and installing Emacs
3280 @cindex Retrieving and installing Emacs
3281 @cindex Building Emacs from source
3282 @cindex Source code, building Emacs from
3283 @cindex Unpacking and installing Emacs
3285 This answer is meant for users of Unix and Unix-like systems.  Users of
3286 other operating systems should see the series of questions beginning
3287 with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source
3288 and binaries, and how to install Emacs on those systems.
3290 For Unix and Unix-like systems, the easiest way is often to compile it
3291 from scratch.  You will need:
3293 @itemize @bullet
3295 @item
3296 Emacs sources.  @xref{Current GNU distributions}, for a list of ftp sites
3297 that make them available.  On @file{ftp.gnu.org}, the main GNU
3298 distribution site, sources are available as
3300 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-@value{VER}.tar.gz}
3302 The above will obviously change as new versions of Emacs come out.  For
3303 instance, when Emacs 21.42 is released, it will most probably be
3304 available as
3306 @uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-21.42.tar.gz}
3308 Again, you should use one of the GNU mirror sites (see @ref{Current GNU
3309 distributions}, and adjust the URL accordingly) so as to reduce load on
3310 @file{ftp.gnu.org}.
3312 @item
3313 @code{gzip}, the GNU compression utility.  You can get @code{gzip} via
3314 anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile
3315 and install without much trouble on most systems.  Once you have
3316 retrieved the Emacs sources, you will probably be able to uncompress
3317 them with the command
3319 @example
3320 gunzip --verbose emacs-@value{VER}.tar.gz
3321 @end example
3323 @noindent
3324 changing the Emacs version (@value{VER}), as necessary.  Once
3325 @code{gunzip} has finished doing its job, a file by the name of
3326 @file{emacs-@value{VER}.tar} should be in your build directory.
3328 @item
3329 @code{tar}, the @dfn{tape archiving} program, which moves multiple files
3330 into and out of archive files, or @dfn{tarfiles}.  All of the files
3331 comprising the Emacs source come in a single tarfile, and must be
3332 extracted using @code{tar} before you can build Emacs.  Typically, the
3333 extraction command would look like
3335 @example
3336 tar -xvvf emacs-@value{VER}.tar
3337 @end example
3339 @noindent
3340 The @samp{x} indicates that we want to extract files from this tarfile,
3341 the two @samp{v}s force verbose output, and the @samp{f} tells
3342 @code{tar} to use a disk file, rather than one on the tape drive.
3344 If you're using GNU @code{tar} (available at mirrors of
3345 @file{ftp.gnu.org}), you can combine this step and the previous one by
3346 using the command
3348 @example
3349 tar -zxvvf emacs-@value{VER}.tar.gz
3350 @end example
3352 @noindent
3353 The additional @samp{z} at the beginning of the options list tells GNU
3354 @code{tar} to uncompress the file with @code{gunzip} before extracting
3355 the tarfile's components.
3357 @end itemize
3359 At this point, the Emacs sources (all 70+ megabytes of them) should be
3360 sitting in a directory called @file{emacs-@value{VER}}.  On most common
3361 Unix and Unix-like systems, you should be able to compile Emacs (with X
3362 Window system support) with the following commands:
3364 @example
3365 cd emacs-@value{VER}       # change directory to emacs-@value{VER}
3366 ./configure         # configure Emacs for your particular system
3367 make                # use Makefile to build components, then Emacs
3368 @end example
3370 If the @code{make} completes successfully, the odds are fairly good that
3371 the build has gone well.  (@xref{Problems building Emacs}, if you weren't
3372 successful.)
3374 By default, Emacs is installed in the following directories:
3376 @table @file
3377 @item /usr/local/bin
3378 binaries.
3380 @item /usr/local/share/emacs/@value{VER}
3381 Lisp code and support files.
3383 @item /usr/local/info
3384 Info documentation.
3385 @end table
3387 To install files in those default directories, become the superuser and
3388 type
3390 @example
3391 make install
3392 @end example
3394 Note that @samp{make install} will overwrite @file{/usr/local/bin/emacs}
3395 and any Emacs Info files that might be in @file{/usr/local/info}.
3397 Much more verbose instructions (with many more hints and suggestions)
3398 come with the Emacs sources, in the file @file{INSTALL}.
3400 @node Updating Emacs, Problems building Emacs, Installing Emacs, Compiling and installing Emacs
3401 @section How do I update Emacs to the latest version?
3402 @cindex Updating Emacs
3404 @xref{Installing Emacs}, and follow the instructions there for
3405 installation.
3407 Most files are placed in version-specific directories.  Emacs
3408 @value{VER}, for instance, places files in
3409 @file{/usr/local/share/emacs/@value{VER}}.
3411 Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs
3412 binary) and documentation in @file{/usr/local/info}.  Back up these
3413 files before you upgrade, and you shouldn't have too much trouble.
3415 @node Problems building Emacs, Linking with -lX11 fails, Updating Emacs, Compiling and installing Emacs
3416 @section What should I do if I have trouble building Emacs?
3417 @cindex Problems building Emacs
3418 @cindex Errors when building Emacs
3420 First look in the file @file{etc/PROBLEMS} (where you unpack the Emacs
3421 source) to see if there is already a solution for your problem.  Next,
3422 look for other questions in this FAQ that have to do with Emacs
3423 installation and compilation problems.
3425 If you'd like to have someone look at your problem and help solve it,
3426 see @ref{Help installing Emacs}.
3428 If you cannot find a solution in the documentation, send a message to
3429 @email{bug-gnu-emacs@@gnu.org}.
3431 Please don't post it to @uref{news:gnu.emacs.help} or send e-mail to
3432 @email{help-gnu-emacs@@gnu.org}.  For further guidelines, see
3433 @ref{Guidelines for newsgroup postings} and @ref{Reporting bugs}.
3435 @node Linking with -lX11 fails,  , Problems building Emacs, Compiling and installing Emacs
3436 @section Why does linking Emacs with -lX11 fail?
3437 @cindex Linking with -lX11 fails
3438 @cindex lX11, linking fails with
3440 Emacs needs to be linked with the static version of the X11 library,
3441 @file{libX11.a}.  This may be missing.
3443 On OpenWindows, you may need to use @code{add_services} to add the
3444 "OpenWindows Programmers" optional software category from the CD-ROM.
3446 On HP-UX 8.0, you may need to run @code{update} again to load the
3447 X11-PRG ``fileset''.  This may be missing even if you specified ``all
3448 filesets'' the first time.  If @file{libcurses.a} is missing, you may
3449 need to load the ``Berkeley Development Option.''
3451 @email{zoo@@armadillo.com, David Zuhn} says that MIT X builds shared
3452 libraries by default, and only shared libraries, on those platforms that
3453 support them.  These shared libraries can't be used when undumping
3454 @code{temacs} (the last stage of the Emacs build process).  To get
3455 regular libraries in addition to shared libraries, add this to
3456 @file{site.cf}:
3458 @example
3459 #define ForceNormalLib YES
3460 @end example
3462 Other systems may have similar problems.  You can always define
3463 @code{CANNOT_DUMP} and link with the shared libraries instead.
3465 @cindex X Menus don't work
3466 To get the Xmenu stuff to work, you need to find a copy of MIT's
3467 @file{liboldX.a}.
3469 @c ------------------------------------------------------------
3470 @node Finding Emacs and related packages, Major packages and programs, Compiling and installing Emacs, Top
3471 @chapter Finding Emacs and related packages
3472 @cindex Finding Emacs and related packages
3474 @menu
3475 * Finding Emacs on the Internet::
3476 * Finding a package with particular functionality::
3477 * Packages that do not come with Emacs::
3478 * Current GNU distributions::
3479 * Difference between Emacs and XEmacs::
3480 * Emacs for MS-DOS::
3481 * Emacs for Windows::
3482 * Emacs for OS/2::
3483 * Emacs for Atari ST::
3484 * Emacs for the Amiga ::
3485 * Emacs for NeXTSTEP::
3486 * Emacs for Apple computers::
3487 * Emacs for VMS and DECwindows::
3488 * Modes for various languages::
3489 * Translating names to IP addresses::
3490 @end menu
3492 @node Finding Emacs on the Internet, Finding a package with particular functionality, Finding Emacs and related packages, Finding Emacs and related packages
3493 @section Where can I get Emacs on the net (or by snail mail)?
3494 @cindex Finding Emacs on the Internet
3495 @cindex Snail mail, ordering Emacs via
3496 @cindex Postal service, ordering Emacs via
3497 @cindex Distribution, retrieving Emacs
3498 @cindex Internet, retrieving from
3500 Look in the files @file{etc/DISTRIB} and @file{etc/FTP} for
3501 information on nearby archive sites.  If you don't already have Emacs,
3502 see @ref{Informational files for Emacs}, for how to get these files.
3504 @xref{Installing Emacs}, for information on how to obtain and build the latest
3505 version of Emacs, and see @ref{Current GNU distributions}, for a list of
3506 archive sites that make GNU software available.
3508 @node Finding a package with particular functionality, Packages that do not come with Emacs, Finding Emacs on the Internet, Finding Emacs and related packages
3509 @section How do I find a Emacs Lisp package that does XXX?
3510 @cindex Package, finding
3511 @cindex Finding an Emacs Lisp package
3512 @cindex Functionality, finding a particular package
3514 First of all, you should check to make sure that the package isn't
3515 already available.  For example, typing @kbd{M-x apropos @key{RET}
3516 wordstar @key{RET}} lists all functions and variables containing the
3517 string @samp{wordstar}.
3519 It is also possible that the package is on your system, but has not been
3520 loaded.  To see which packages are available for loading, look through
3521 your computer's lisp directory (@pxref{File-name conventions}).  The Lisp
3522 source to most packages contains a short description of how they
3523 should be loaded, invoked, and configured---so before you use or
3524 modify a Lisp package, see if the author has provided any hints in the
3525 source code.
3527 The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse
3528 the constituent Emacs packages.
3530 For advice on how to find extra packages that are not part of Emacs,
3531 see @ref{Packages that do not come with Emacs}.
3533 @node Packages that do not come with Emacs, Current GNU distributions, Finding a package with particular functionality, Finding Emacs and related packages
3534 @section Where can I get Emacs Lisp packages that don't come with Emacs?
3535 @cindex Unbundled packages
3536 @cindex Finding other packages
3537 @cindex Lisp packages that do not come with Emacs
3538 @cindex Packages, those that do not come with Emacs
3539 @cindex Emacs Lisp List
3540 @cindex Emacs Lisp Archive
3542 @uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.html, The Emacs Lisp
3543 List (ELL)}, maintained by @email{stephen@@anc.ed.ac.uk, Stephen Eglen},
3544 aims to provide one compact list with links to all of the current Emacs
3545 lisp files on the internet.  The ELL can be browsed over the web, or
3546 from Emacs with @uref{http://www.anc.ed.ac.uk/~stephen/emacs/ell.el, 
3547 the @file{ell} package}.
3549 Many authors post their packages to the @uref{news:gnu.emacs.sources,
3550 Emacs sources newsgroup}.  You can search the archives of this
3551 group with @uref{http://groups.google.com, Google}, for example.
3553 Several packages are stored in
3554 @uref{http://emacswiki.org/elisp/, the Lisp area of the Emacs Wiki}.
3556 For a long time, the Emacs Lisp Archive provided a central repository
3557 for Emacs packages.  Sadly, it has not been active for some time,
3558 although you can still access the old files at
3560 @uref{ftp://ftp.cis.ohio-state.edu/pub/emacs-lisp/WWW/index.html}
3562 @node Current GNU distributions, Difference between Emacs and XEmacs, Packages that do not come with Emacs, Finding Emacs and related packages
3563 @section Where can I get other up-to-date GNU stuff?
3564 @cindex Current GNU distributions
3565 @cindex Sources for current GNU distributions
3566 @cindex Stuff, current GNU
3567 @cindex Up-to-date GNU stuff
3568 @cindex Finding current GNU software
3569 @cindex Official GNU software sites
3571 The most up-to-date official GNU software is normally kept at
3573 @uref{ftp://ftp.gnu.org/pub/gnu}
3575 Read the files @file{etc/DISTRIB} and @file{etc/FTP} for more
3576 information.
3578 A list of sites mirroring @samp{ftp.gnu.org} can be found at
3580 @uref{http://www.gnu.org/order/ftp.html}
3582 @node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages
3583 @section What is the difference between Emacs and XEmacs (formerly "Lucid Emacs")?
3584 @cindex XEmacs
3585 @cindex Difference Emacs and XEmacs
3586 @cindex Lucid Emacs
3587 @cindex Epoch
3589 First of all, they're both GNU Emacs.  XEmacs is just as much a later
3590 version of GNU Emacs as the FSF-distributed version.  This FAQ refers to
3591 the latest version to be distributed by the FSF as ``Emacs,'' partly
3592 because the XEmacs maintainers now refer to their product using the
3593 ``XEmacs'' name, and partly because there isn't any accurate way to
3594 differentiate between the two without getting mired in paragraphs of
3595 legalese and history.
3597 XEmacs, which began life as Lucid Emacs, is based on an early version of
3598 Emacs 19 and Epoch, an X-aware version of Emacs 18.
3600 Emacs (i.e., the version distributed by the FSF) has a larger installed
3601 base and now always contains the MULE multilingual facilities.
3602 XEmacs can do some clever tricks with X and MS-Windows, such as
3603 putting arbitrary graphics in a buffer.  Similar facilities have been
3604 implemented for Emacs as part of a new redisplay implementation for
3605 Emacs 21, and are available in the latest Emacs releases.
3606 Emacs and XEmacs each come with
3607 Lisp packages that are lacking in the other; RMS says that the FSF would
3608 include more packages that come with XEmacs, but that the XEmacs
3609 maintainers don't always keep track of the authors of contributed code,
3610 which makes it impossible for the FSF to have certain legal papers
3611 signed.  (Without these legal papers, the FSF will not distribute Lisp
3612 packages with Emacs.)  The two versions have some
3613 significant differences at the Lisp programming level.
3615 Many XEmacs features have found their way into recent versions of Emacs,
3616 and more features can be expected in the future, but there are still many
3617 differences between the two.
3619 The latest stable branch of XEmacs as of this writing is 21.4; you can
3620 get it at
3622 @uref{ftp://ftp.xemacs.org/pub/xemacs/xemacs-21.4/xemacs-21.4.12.tar.gz}
3624 More information about XEmacs, including a list of frequently asked
3625 questions (FAQ), is available at
3627 @uref{http://www.xemacs.org/}
3629 @node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages
3630 @section Where can I get Emacs for my PC running MS-DOS?
3631 @cindex MS-DOS, Emacs for
3632 @cindex DOS, Emacs for
3633 @cindex Compiling Emacs for DOS
3634 @cindex Emacs for MS-DOS
3635 @cindex Tools needed to compile Emacs under DOS
3637 A pre-built binary distribution of Emacs is available from the
3638 SimTel.NET archives.  This version apparently works under MS-DOS and
3639 Windows (3.X, 9X, ME, NT, and 2000) and supports long file names under
3640 Windows 9X, Windows ME, and Windows 2000.  More information is available
3641 from
3643 @uref{http://www.simtel.net/pub/djgpp/v2gnu/emacs.README}
3645 The binary itself is available in the files @file{em*.zip} in the
3646 directory
3648 @uref{http://www.simtel.net/pub/djgpp/v2gnu/}
3650 If you prefer to compile Emacs for yourself, you can do so with the
3651 current distribution directly.  You will need a 386 (or
3652 better) processor, and to be running MS-DOS 3.0 or later.  According to
3653 @email{eliz@@is.elta.co.il, Eli Zaretskii} and
3654 @email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the
3655 following:
3657 @table @emph
3659 @item Compiler
3660 DJGPP version 1.12 maint 1 or later.  Djgpp 2.0 or later is
3661 recommended, since 1.x is very old an unmaintained.  Djgpp 2 supports
3662 long file names on Windows 9X/ME/2K.
3664 You can get the latest release of DJGPP by retrieving all of
3665 the files in
3667 @uref{http://www.simtel.net/pub/gnu/djgpp/v2*}
3669 @item Unpacking program
3670 The easiest way is to use @code{djtar} which comes with DJGPP v2.x,
3671 because it can open gzip'ed tarfiles (i.e., those ending with
3672 @file{.tar.gz}) in one step.  @code{Djtar} comes in
3673 @file{djdev@var{nnn}.zip} archive (where @var{nnn} is the DJGPP version
3674 number), from the URL mentioned above.
3676 @strong{Warning!}  Do @strong{not} use the popular WinZip program to
3677 unpack the Emacs distribution!  WinZip is known to corrupt some of the
3678 files by converting them to the DOS CR-LF format, it doesn't always
3679 preserve the directory structure recorded in the compressed Emacs
3680 archive, and commits other atrocities.  Some of these problems could
3681 actually prevent Emacs from building successfully!
3683 @item make, mv, sed, and rm
3684 All of these utilities are available at
3686 @uref{http://www.simtel.net/pub/gnu/djgpp/v2gnu}
3688 16-bit utilities can be found in GNUish, at
3690 @uref{http://www.simtel.net/pub/gnuish/}
3692 @noindent
3693 (@code{mv} and @code{rm} are in the Fileutils package, @code{sed} and
3694 @code{make} are each one in a separate package named after them.)
3696 @end table
3698 The files @file{INSTALL} (near its end) and @file{etc/PROBLEMS} in the
3699 directory of the Emacs sources contains some additional information
3700 regarding Emacs under MS-DOS.
3702 For a list of other MS-DOS implementations of Emacs (and Emacs
3703 look-alikes), consult the list of "Emacs implementations and literature,"
3704 available at
3706 @uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/}
3708 Note that while many of these programs look similar to Emacs, they often
3709 lack certain features, such as the Emacs Lisp extension language.
3711 @node Emacs for Windows, Emacs for OS/2, Emacs for MS-DOS, Finding Emacs and related packages
3712 @section Where can I get Emacs for Microsoft Windows
3713 @cindex FAQ for NT Emacs
3714 @cindex Emacs for MS-Windows
3715 @cindex Microsoft Windows, Emacs for
3716 @cindex Windows 9X, ME, NT, 2K, and CE, Emacs for
3718 For information on Emacs for Windows 95 and NT, read the FAQ produced by
3719 @email{voelker@@cs.washington.edu, Geoff Voelker}, available at
3721 @uref{http://www.gnu.org/software/emacs/windows/ntemacs.html}
3723 @xref{Emacs for MS-DOS}, for Windows 3.1.
3725 A port of Emacs 20.7 for Windows CE, based on NTEmacs, is available at
3727 @uref{http://www.rainer-keuchel.de/software.html}
3729 @noindent
3730 This port was done by @email{coyxc@@rainer-keuchel.de, Rainer Keuchel},
3731 and supports all Emacs features except async subprocesses and menus.
3732 You will need MSVC 6.0 and a Windows CE SDK to build this port.
3734 @node Emacs for OS/2, Emacs for Atari ST, Emacs for Windows, Finding Emacs and related packages
3735 @section Where can I get Emacs for my PC running OS/2?
3736 @cindex OS/2, Emacs for
3738 Emacs 20.6 is ported for emx on OS/2 2.0 or 2.1, and is available at
3740 @uref{ftp://hobbes.nmsu.edu/pub/os2/apps/editors/emacs/e206*.zip}
3742 @noindent
3743 and also at
3745 @uref{http://archiv.leo.org/pub/comp/os/os2/leo/gnu/emacs%2d20/}
3747 Instructions for installation, basic setup, and other useful information
3748 for OS/2 users of Emacs can be found at
3750 @uref{http://userpage.fu-berlin.de/~oheiabbd/emacs/emacs206-os2.html}
3752 @node Emacs for Atari ST, Emacs for the Amiga , Emacs for OS/2, Finding Emacs and related packages
3753 @section Where can I get Emacs for my Atari ST?
3754 @cindex Atari ST, Emacs for
3755 @cindex TOS, Emacs for
3757 Roland Schäuble reports that Emacs 18.58 running on plain TOS and MiNT
3758 is available at
3759 @uref{ftp://atari.archive.umich.edu/Editors/Emacs-18-58/1858b-d3.zoo}.
3761 @node Emacs for the Amiga , Emacs for NeXTSTEP, Emacs for Atari ST, Finding Emacs and related packages
3762 @section Where can I get Emacs for my Amiga?
3763 @cindex Amiga, Emacs for
3765 The files you need are available at
3767 @uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/}
3769 @email{dgilbert@@gamiga.guelphnet.dweomer.org, David Gilbert} has released a
3770 beta version of Emacs 19.25 for the Amiga.  You can get the binary at
3772 @uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/a2.0bEmacs-bin.lha}
3774 @node Emacs for NeXTSTEP, Emacs for Apple computers, Emacs for the Amiga , Finding Emacs and related packages
3775 @section Where can I get Emacs for NeXTSTEP?
3776 @cindex NeXTSTEP, Emacs for
3778 Emacs.app is a NeXTSTEP version of Emacs 19.34 which supports colors,
3779 menus, and multiple frames.  You can get it from
3781 @uref{ftp://next-ftp.peak.org/pub/next/apps/emacs/Emacs_for_NeXTstep.4.20a1.NIHS.b.tar.gz}
3783 @node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages
3784 @section Where can I get Emacs for my Apple computer?
3785 @cindex Apple computers, Emacs for
3786 @cindex Macintosh, Emacs for
3788 An unofficial port of GNU Emacs 18.59 to the Macintosh is available at a
3789 number of ftp sites, the home being
3790 @uref{ftp://ftp.cs.cornell.edu/pub/parmet/Emacs-1.17.sit.bin}.
3792 A port of Emacs 20.4 is available at
3793 @uref{http://www.cs.hku.hk/~choi/emacs/index.html}.
3795 Beginning with version 21.1, the Macintosh is supported in the official
3796 Emacs distribution; see the files @file{mac/README} and
3797 @file{mac/INSTALL} in the Emacs distribution for build instructions.
3799 Apple's forthcoming "OS X" is based largely on NeXTSTEP and OpenStep.
3800 @xref{Emacs for NeXTSTEP}, for more details about that version.
3802 @node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages
3803 @section Where do I get Emacs that runs on VMS under DECwindows?
3804 @cindex DECwindows, Emacs for
3805 @cindex VMS, Emacs for
3807 Up-to-date information about GNU software (including Emacs) for VMS is
3808 available at @uref{http://vms.gnu.org/}.
3810 @node Modes for various languages, Translating names to IP addresses, Emacs for VMS and DECwindows, Finding Emacs and related packages
3811 @section Where can I get modes for Lex, Yacc/Bison, Bourne shell, csh, C@t{++}, Objective-C, Pascal, Java, and Awk?
3812 @cindex Awk, mode for
3813 @cindex @code{awk-mode}
3814 @cindex Bison, mode for
3815 @cindex Bourne Shell, mode for
3816 @cindex C@t{++}, mode for
3817 @cindex Java, mode for
3818 @cindex Lex mode
3819 @cindex Objective-C, mode for
3820 @cindex @code{pascal-mode}
3821 @cindex Shell mode
3822 @cindex Yacc mode
3823 @cindex @file{csh} mode
3824 @cindex @code{sh-mode}
3825 @cindex @code{cc-mode}
3827 Most of these modes are now available in standard Emacs distribution.
3828 To get additional modes, see @ref{Finding a package with particular
3829 functionality}.  
3831 Barry Warsaw's @code{cc-mode} now works for C, C@t{++}, Objective-C, and
3832 Java code.  It is distributed with Emacs, but has
3833 @uref{http://cc-mode.sourceforge.net/, its own homepage}.
3835 @node Translating names to IP addresses,  , Modes for various languages, Finding Emacs and related packages
3836 @section What is the IP address of XXX.YYY.ZZZ?
3837 @cindex Translating names to IP addresses
3838 @cindex IP addresses from names
3839 @cindex Using BIND to translate addresses
3840 @cindex DNS and IP addresses
3842 If you are on a Unix machine, try using the @samp{nslookup} command,
3843 included in the Berkeley BIND package.  For example, to find the IP
3844 address of @samp{ftp.gnu.org}, you would type @code{nslookup
3845 ftp.gnu.org}.
3847 Your computer should then provide the IP address of that machine.
3849 If your site's nameserver is deficient, you can use IP addresses to FTP
3850 files.  You can get this information by e-mail:
3852 @example
3853 To: dns@@[134.214.84.25]    (to grasp.insa-lyon.fr)
3854 Body: ip XXX.YYY.ZZZ        (or "help" for more information
3855                              and options - no quotes)
3856 @end example
3858 @noindent
3861 @example
3862 To: resolve@@[147.31.254.130]         (to laverne.cs.widener.edu)
3863 Body: site XXX.YYY.ZZZ
3864 @end example
3866 @c ------------------------------------------------------------
3867 @node Major packages and programs, Key bindings, Finding Emacs and related packages, Top
3868 @chapter Major packages and programs
3869 @cindex Major packages and programs
3871 @menu
3872 * VM::
3873 * Supercite::
3874 * Calc::
3875 * VIPER::
3876 * AUCTeX::
3877 * BBDB::
3878 * Ispell::
3879 * w3-mode::
3880 * EDB::
3881 * Mailcrypt::
3882 * JDE::
3883 * Patch::
3884 @end menu
3886 @node VM, Supercite, Major packages and programs, Major packages and programs
3887 @section VM (View Mail) --- another mail reader within Emacs, with MIME support
3888 @cindex VM
3889 @cindex Alternative mail software
3890 @cindex View Mail
3891 @cindex E-mail reader, VM
3893 @table @b
3895 @item Author
3896 @email{kyle_jones@@wonderworks.com, Kyle Jones}
3898 @item Latest version
3899 7.15
3901 @item Distribution
3902 @uref{ftp://ftp.wonderworks.com/pub/vm/vm.tar.gz}
3904 @item Informational newsgroup
3905 @uref{news:gnu.emacs.vm.info}@*
3907 @item Bug reports newsgroup
3908 @uref{news:gnu.emacs.vm.bug}@*
3909 Or send reports to @email{bug-vm@@wonderworks.com}
3910 @end table
3912 VM 7 works well with Emacs 21. Older versions of VM suitable for use
3913 with older versions of Emacs are available from
3914 @uref{ftp://ftp.wonderworks.com/pub/vm/, the same FTP site}.
3917 @node Supercite, Calc, VM, Major packages and programs
3918 @section Supercite --- mail and news citation package within Emacs
3919 @cindex Supercite
3920 @cindex Superyank
3921 @cindex Mail and news citations
3922 @cindex News and mail citations
3923 @cindex Citations in mail and news
3925 @table @b
3927 @item Author
3928 @email{barry@@python.org, Barry Warsaw}
3930 @item Latest version
3931 3.54 (comes bundled with Emacs since version 20)
3933 @item Distribution
3934 @uref{http://www.python.org/emacs/supercite.tar.gz}
3936 @item Mailing list
3937 Subscription requests to @email{supercite-request@@python.org}@*
3938 Submissions @email{supercite@@python.org}
3940 @end table
3942 Superyank is an old version of Supercite.
3944 @node Calc, VIPER, Supercite, Major packages and programs
3945 @section Calc --- poor man's Mathematica within Emacs
3946 @cindex Programmable calculator
3947 @cindex Calc
3948 @cindex Mathematical package
3950 @table @b
3952 @item Author
3953 @email{daveg@@csvax.cs.caltech.edu, Dave Gillespie}
3955 @item Latest version
3956 2.02f
3958 @item Distribution
3959 @uref{ftp://ftp.gnu.org/pub/gnu/calc/calc-2.02f.tar.gz}
3961 @end table
3963 Note that Calc 2.02f needs patching to work with Emacs 21 and later.
3965 @cindex @code{calculator}, a package
3966 Emacs 21.1 and later comes with a package called @file{calculator.el}.
3967 It doesn't support all the mathematical wizardry offered by Calc, such
3968 as matrices, special functions, and statistics, but is more than
3969 adequate as a replacement for @code{xcalc} and similar programs.
3971 @node VIPER, AUCTeX, Calc, Major packages and programs
3972 @section VIPER --- @code{vi} emulation for Emacs
3973 @cindex @code{vi} emulation
3974 @cindex VIPER
3975 @cindex Emulation of @code{vi}
3977 Since Emacs 19.29, the preferred @code{vi} emulation in Emacs is VIPER
3978 (@kbd{M-x viper-mode @key{RET}}), which comes with Emacs.  It extends
3979 and supersedes VIP (including VIP 4.3) and provides @code{vi} emulation
3980 at several levels, from one that closely follows @code{vi} to one that
3981 departs from @code{vi} in several significant ways.
3983 For Emacs 19.28 and earlier, the following version of VIP is generally
3984 better than the one distributed with Emacs:
3986 @table @b
3987 @item Author
3988 @email{sane@@cs.uiuc.edu, Aamod Sane}
3990 @item Latest version
3993 @item Distribution
3994 @uref{ftp://archive.cis.ohio-state.edu/pub/emacs-lisp/old-archive/modes/vip-mode.tar.Z}
3996 @end table
3998 @node AUCTeX, BBDB, VIPER, Major packages and programs
3999 @section AUCTeX --- enhanced LaTeX mode with debugging facilities
4000 @cindex Mode for @TeX{}
4001 @cindex @TeX{} mode
4002 @cindex AUCTeX mode for editing @TeX{}
4003 @cindex Writing and debugging @TeX{}
4005 @table @b
4007 @item Authors
4008 @email{krab@@iesd.auc.dk, Kresten Krab Thorup} and@*
4009 @email{abraham@@dina.kvl.dk, Per Abrahamsen}
4011 @item Maintainer
4012 @email{dak@@gnu.org, David Kastrup}
4014 @item Latest version
4015 11.13
4017 @item Distribution
4018 @uref{http://savannah.gnu.org/download/auctex/stable.pkg/11.13/auctex-11.13.tar.gz}
4020 @item Web site
4021 @uref{http://www.gnu.org/software/auctex/}
4023 @item Mailing list:
4024 Subscription requests to @email{auc-tex-subscribe@@sunsite.dk}@*
4025 Submissions to @email{auc-tex@@sunsite.dk}@*
4026 Development team is at @email{auc-tex_mgr@@sunsite.dk}
4028 @end table
4030 @node BBDB, Ispell, AUCTeX, Major packages and programs
4031 @section BBDB --- personal Info Rolodex integrated with mail/news readers
4032 @cindex BBDB
4033 @cindex Rolodex-like functionality
4034 @cindex Integrated contact database
4035 @cindex Contact database
4036 @cindex Big Brother Database
4037 @cindex Address book
4039 @table @b
4041 @item Maintainer
4042 @email{waider@@waider.ie, Ronan Waide}
4044 @item Latest version
4045 2.34
4047 @item Distribution
4048 @uref{http://bbdb.sourceforge.net/}
4050 @item Mailing lists
4051 Subscription requests to @email{bbdb-info-request@@lists.sourceforge.net}@*
4052 Submissions to @email{bbdb-info@@lists.sourceforge.net}@*
4053 Release announcements: @email{bbdb-announce-request@@lists.sourceforge.net}
4055 @end table
4057 @node Ispell, w3-mode, BBDB, Major packages and programs
4058 @section Ispell --- spell checker in C with interface for Emacs
4059 @cindex Spell-checker
4060 @cindex Checking spelling
4061 @cindex Ispell
4063 @table @b
4065 @item Author
4066 @email{geoff@@itcorp.com, Geoff Kuenning}
4068 @item Latest version
4069 3.1.20
4071 @item Distribution
4072 @uref{ftp://ftp.cs.ucla.edu/pub/ispell/ispell-3.1.20.tar.gz}@*
4074 @item Web site
4075 @uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html}
4077 @end table
4079 @itemize @bullet
4081 @item
4082 Do not ask Geoff to send you the latest version of Ispell. He does not
4083 have free e-mail.
4085 @item
4086 This Ispell program is distinct from GNU Ispell 4.0. GNU Ispell 4.0 is
4087 no longer a supported product.
4089 @end itemize
4091 @node w3-mode, EDB, Ispell, Major packages and programs
4092 @section w3-mode --- A World Wide Web browser inside of Emacs
4093 @cindex WWW browser
4094 @cindex Web browser
4095 @cindex HTML browser in Emacs
4096 @cindex @code{w3-mode}
4098 @table @b
4100 @item Author
4101 @email{wmperry@@spry.com, Bill Perry}
4103 @item Latest version
4104 4.0pre.39
4106 @item Distribution
4107 @uref{ftp://ftp.cs.indiana.edu/pub/elisp/w3/w3.tar.gz}
4109 @item Mailing lists
4110 Receive announcements from @email{w3-announce-request@@indiana.edu}@*
4111 Become a beta tester at @email{w3-beta-request@@indiana.edu}@*
4112 Help to develop @code{w3-mode} at @email{w3-dev@@indiana.edu}
4114 @end table
4116 @node EDB, Mailcrypt, w3-mode, Major packages and programs
4117 @section EDB --- Database program for Emacs; replaces forms editing modes
4118 @cindex EDB
4119 @cindex Database
4120 @cindex Forms mode
4122 @table @b
4123 @item Author
4124 @email{mernst@@theory.lcs.mit.edu, Michael Ernst}
4126 @item Latest version
4127 1.21
4129 @item Distribution
4130 @uref{ftp://theory.lcs.mit.edu/pub/emacs/edb}
4132 @end table
4134 @node Mailcrypt, JDE, EDB, Major packages and programs
4135 @section Mailcrypt --- PGP interface within Emacs mail and news
4136 @cindex PGP
4137 @cindex GPG
4138 @cindex Interface to PGP from Emacs mail and news
4139 @cindex News, interface to PGP from
4140 @cindex Mail, interface to PGP from
4141 @cindex Encryption software, interface to
4143 @table @b
4145 @item Authors
4146 @email{patl@@lcs.mit.edu, Patrick J. LoPresti} and
4147 @email{jin@@atype.com, Jin S. Choi}
4149 @item Maintainer
4150 @email{warner-mailcrypt@@lothar.com, Brian Warner}
4152 @item Latest version
4153 3.5.8
4155 @item Distribution
4156 @uref{http://dl.sourceforge.net/sourceforge/mailcrypt/mailcrypt-3.5.8.tar.gz}
4158 @item Web site
4159 @uref{http://mailcrypt.sourceforge.net/}
4161 @end table
4163 @node JDE, Patch, Mailcrypt, Major packages and programs
4164 @section JDE --- Integrated development environment for Java
4165 @cindex Java development environment
4166 @cindex Integrated Java development environment
4167 @cindex JDE
4169 @table @b
4171 @item Author
4172 @email{paulk@@mathworks.com, Paul Kinnucan}
4174 @item Mailing list
4175 jde-subscribe@@sunsite.auc.dk
4177 @item Latest version
4178 2.1.1
4180 @item Web site
4181 @uref{http://sunsite.auc.dk/jde/}
4183 @end table
4185 @node Patch,  , JDE, Major packages and programs
4186 @section Patch --- program to apply "diffs" for updating files
4187 @cindex Updating files with diffs
4188 @cindex Patching source files with diffs
4189 @cindex Diffs and patching
4190 @cindex @file{patch}
4192 @table @b
4194 @item Author
4195 @email{lwall@@wall.org, Larry Wall} (with GNU modifications)
4197 @item Latest version
4198 2.5.4
4200 @item Distribution
4201 @xref{Current GNU distributions}.
4203 @end table
4205 @c ------------------------------------------------------------
4206 @node Key bindings, Alternate character sets, Major packages and programs, Top
4207 @chapter Key bindings
4208 @cindex Key bindings
4210 @menu
4211 * Binding keys to commands::
4212 * Invalid prefix characters::
4213 * Terminal setup code works after Emacs has begun::
4214 * Using function keys under X::
4215 * Working with function and arrow keys::
4216 * X key translations for Emacs::
4217 * Handling C-s and C-q with flow control::
4218 * Binding C-s and C-q::
4219 * Backspace invokes help::
4220 * stty and Backspace key::
4221 * Swapping keys::
4222 * Producing C-XXX with the keyboard::
4223 * No Meta key::
4224 * No Escape key::
4225 * Compose Character::
4226 * Binding combinations of modifiers and function keys::
4227 * Meta key does not work in xterm::
4228 * ExtendChar key does not work as Meta::
4229 @end menu
4231 @node Binding keys to commands, Invalid prefix characters, Key bindings, Key bindings
4232 @section How do I bind keys (including function keys) to commands?
4233 @cindex Binding keys to commands
4234 @cindex Keys, binding to commands
4235 @cindex Commands, binding keys to
4237 Keys can be bound to commands either interactively or in your
4238 @file{.emacs} file.  To interactively bind keys for all modes, type
4239 @kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
4241 To bind a key just in the current major mode, type @kbd{M-x
4242 local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}.
4244 @inforef{Key Bindings, Key Bindings, emacs}, for further details.
4246 To make the process of binding keys interactively eaiser, use the
4247 following ``trick'': First bind the key interactively, then immediately
4248 type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}.  Now, the command needed
4249 to bind the key is in the kill ring, and can be yanked into your
4250 @file{.emacs} file.  If the key binding is global, no changes to the
4251 command are required.  For example,
4253 @lisp
4254 (global-set-key (quote [f1]) (quote help-for-help))
4255 @end lisp
4257 @noindent
4258 can be placed directly into the @file{.emacs} file.  If the key binding is
4259 local, the command is used in conjunction with the "add-hook" command.
4260 For example, in tex-mode, a local binding might be
4262 @lisp
4263 (add-hook 'tex-mode-hook
4264   (lambda ()
4265    (local-set-key (quote [f1]) (quote help-for-help))))
4266 @end lisp
4269 @itemize @bullet
4271 @item
4272 Control characters in key sequences, in the form yanked from the kill
4273 ring are given in their graphic form---i.e., @key{CTRL} is shown as
4274 @samp{^}, @key{TAB} as a set of spaces (usually 8), etc.  You may want
4275 to convert these into their vector or string forms.
4277 @item
4278 If a prefix key of the character sequence to be bound is already
4279 bound as a complete key, then you must unbind it before the new
4280 binding.  For example, if @kbd{ESC @{} is previously bound:
4282 @lisp
4283 (global-unset-key [?\e ?@{])   ;;   or
4284 (local-unset-key [?\e ?@{])
4285 @end lisp
4287 @item
4288 Aside from commands and ``lambda lists,'' a vector or string also
4289 can be bound to a key and thus treated as a macro.  For example:
4291 @lisp
4292 (global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g])  ;;  or
4293 (global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g")
4294 @end lisp
4296 @end itemize
4298 @node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings
4299 @section Why does Emacs say "Key sequence XXX uses invalid prefix characters"?
4300 @cindex Prefix characters, invalid
4301 @cindex Invalid prefix characters
4302 @cindex Misspecified key sequences
4304 Usually, one of two things has happened.  In one case, the control
4305 character in the key sequence has been misspecified (e.g. @samp{C-f}
4306 used instead of @samp{\C-f} within a Lisp expression).  In the other
4307 case, a @dfn{prefix key} in the keystroke sequence you were trying to bind
4308 was already bound as a @dfn{complete key}.  Historically, the @samp{ESC [}
4309 prefix was usually the problem, in which case you should evaluate either
4310 of these forms before attempting to bind the key sequence:
4312 @lisp
4313 (global-unset-key [?\e ?[])  ;;  or
4314 (global-unset-key "\e[")
4315 @end lisp
4317 @node Terminal setup code works after Emacs has begun, Using function keys under X, Invalid prefix characters, Key bindings
4318 @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?
4319 @cindex Terminal setup code in @file{.emacs}
4321 During startup, Emacs initializes itself according to a given code/file
4322 order.  If some of the code executed in your @file{.emacs} file needs to
4323 be postponed until the initial terminal or window-system setup code has
4324 been executed but is not, then you will experience this problem (this
4325 code/file execution order is not enforced after startup).
4327 To postpone the execution of Emacs Lisp code until after terminal or
4328 window-system setup, treat the code as a @dfn{lambda list} and set the
4329 value of either the @code{term-setup-hook} or @code{window-setup-hook}
4330 variable to this lambda function.  For example,
4332 @lisp
4333 (add-hook 'term-setup-hook
4334           (lambda ()
4335            (when (string-match "\\`vt220" (or (getenv "TERM") ""))
4336              ;; Make vt220's "Do" key behave like M-x:
4337              (global-set-key [do] 'execute-extended-command))))
4338 @end lisp
4340 For information on what Emacs does every time it is started, see the
4341 @file{lisp/startup.el} file.
4343 @node Using function keys under X, Working with function and arrow keys, Terminal setup code works after Emacs has begun, Key bindings
4344 @section How do I use function keys under X?
4345 @cindex Function keys
4346 @cindex X Window System and function keys
4347 @cindex Binding function keys
4349 With Emacs 19, functions keys under X are bound like any other key.  @xref{Binding keys to commands}, for details.
4351 @node Working with function and arrow keys, X key translations for Emacs, Using function keys under X, Key bindings
4352 @section How do I tell what characters or symbols my function or arrow keys emit?
4353 @cindex Working with arrow keys
4354 @cindex Arrow keys, symbols generated by
4355 @cindex Working with function keys
4356 @cindex Function keys, symbols generated by
4357 @cindex Symbols generated by function keys
4359 Type @kbd{C-h c} then the function or arrow keys.  The command will
4360 return either a function key symbol or character sequence (see the
4361 Emacs on-line documentation for an explanation).  This works for other
4362 keys as well.
4364 @node X key translations for Emacs, Handling C-s and C-q with flow control, Working with function and arrow keys, Key bindings
4365 @section How do I set the X key ``translations'' for Emacs?
4366 @cindex X key translations
4367 @cindex Key translations under X
4368 @cindex Translations for keys under X
4370 Emacs is not written using the Xt library by default, so there are no
4371 ``translations'' to be set.  (We aren't sure how to set such translations
4372 if you do build Emacs with Xt; please let us know if you've done this!)
4374 The only way to affect the behavior of keys within Emacs is through
4375 @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs).  The
4376 @code{define-key} command should be used in conjunction with the
4377 @code{function-key-map} map.  For instance,
4379 @lisp
4380 (define-key function-key-map [M-@key{TAB}] [?\M-\t])
4381 @end lisp
4383 @noindent
4384 defines the @kbd{M-@key{TAB}} key sequence.
4386 @node Handling C-s and C-q with flow control, Binding C-s and C-q, X key translations for Emacs, Key bindings
4387 @section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control?
4388 @cindex Flow control, @kbd{C-s} and @kbd{C-q} with
4389 @cindex @kbd{C-s} and @kbd{C-q} with flow control
4391 @kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol.
4392 This messes things up when you're using Emacs over a serial line,
4393 because Emacs binds these keys to commands by default.  Because Emacs
4394 won't honor them as flow control characters, too many of these
4395 characters are not passed on and overwhelm output buffers.  Sometimes,
4396 intermediate software using XON/XOFF flow control will prevent Emacs
4397 from ever seeing @kbd{C-s} and @kbd{C-q}.
4399 Possible solutions:
4401 @itemize @bullet
4403 @item
4404 Disable the use of @kbd{C-s} and @kbd{C-q} for flow control.
4406 You need to determine the cause of the flow control.
4408 @itemize @minus
4410 @item
4411 your terminal
4413 Your terminal may use XON/XOFF flow control to have time to display
4414 all the characters it receives.  For example, VT series terminals do
4415 this.  It may be possible to turn this off from a setup menu.  For
4416 example, on a VT220 you may select ``No XOFF'' in the setup menu.  This
4417 is also true for some terminal emulation programs on PCs.
4419 When you turn off flow control at the terminal, you will also need to
4420 turn it off at the other end, which might be at the computer you are
4421 logged in to or at some terminal server in between.
4423 If you turn off flow control, characters may be lost; using a printer
4424 connected to the terminal may fail.  You may be able to get around
4425 this problem by modifying the @samp{termcap} entry for your terminal to
4426 include extra NUL padding characters.
4428 @item
4429 a modem
4431 If you are using a dialup connection, the modems may be using
4432 XON/XOFF flow control.  It's not clear how to get around this.
4434 @item
4435 a router or terminal server
4437 Some network box between the terminal and your computer may be using
4438 XON/XOFF flow control.  It may be possible to make it use some other
4439 kind of flow control.  You will probably have to ask your local
4440 network experts for help with this.
4442 @item
4443 @code{tty} and/or @code{pty} devices
4445 If your connection to Emacs goes through multiple @code{tty} and/or
4446 @code{pty} devices, they may be using XON/XOFF flow control even when it
4447 is not necessary.
4449 @email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes:
4451 @quotation
4452 Some versions of @code{rlogin} (and possibly @code{telnet}) do not pass
4453 flow control characters to the remote system to which they connect.  On
4454 such systems, Emacs on the remote system cannot disable flow control on
4455 the local system.  Sometimes @samp{rlogin -8} will avoid this problem.
4457 One way to cure this is to disable flow control on the local host (the
4458 one running @code{rlogin}, not the one running @code{rlogind}) using the
4459 @code{stty} command, before starting the @code{rlogin} process.  On many
4460 systems, @samp{stty start u stop u} will do this.
4462 Some versions of @samp{tcsh} will prevent even this from working.  One
4463 way around this is to start another shell before starting rlogin,
4464 and issue the @samp{stty} command to disable flow control from that shell.
4465 @end quotation
4467 Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems.
4469 @end itemize
4471 @item
4472 Make Emacs speak the XON/XOFF flow control protocol.
4474 You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by
4475 evaluating the form
4477 @lisp
4478 (enable-flow-control)
4479 @end lisp
4481 @noindent
4482 to unconditionally enable flow control or
4484 @lisp
4485 (enable-flow-control-on "vt100" "h19")
4486 @end lisp
4488 @noindent
4489 (using your terminal names instead of @samp{vt100} or @samp{h19}) to
4490 enable selectively.  These commands will automatically swap @kbd{C-s}
4491 and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}.  Variables can be used to
4492 change the default swap keys (@code{flow-control-c-s-replacement} and
4493 @code{flow-control-c-q-replacement}).
4495 If you are fixing this for yourself, simply put the form in your
4496 @file{.emacs} file.  If you are fixing this for your entire site, the
4497 best place to put it is in the @file{site-lisp/site-start.el} file.
4498 (Here @file{site-lisp} is actually a subdirectory of your Emacs
4499 installation directory, typically @file{/usr/local/share/emacs}.)
4500 Putting this form in @file{site-lisp/default.el} has the problem that
4501 if the user's @file{.emacs} file has an error, this will prevent
4502 @file{default.el} from being loaded and Emacs may be unusable for the
4503 user, even for correcting their @file{.emacs} file (unless they're
4504 smart enough to move it to another name).
4506 @code{enable-flow-control} can be invoked interactively as well:
4507 @kbd{M-x enable-flow-control @key{RET}}.
4509 @end itemize
4511 For further discussion of this issue, read the file @file{etc/PROBLEMS}
4512 (in the Emacs source directory when you unpack the Emacs distribution).
4514 @node Binding C-s and C-q, Backspace invokes help, Handling C-s and C-q with flow control, Key bindings
4515 @section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out?
4516 @cindex Binding @kbd{C-s} and @kbd{C-q}
4517 @cindex @kbd{C-s} and @kbd{C-q}, binding
4519 To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control}
4520 or @code{enable-flow-control-on}.  @xref{Handling C-s and C-q with flow
4521 control}, for usage and implementation details.
4523 To bind other keys, use @code{keyboard-translate}.  @xref{Swapping
4524 keys}, for usage details.  To do this for an entire site, you should
4525 swap the keys in @file{site-lisp/site-start.el}.  @xref{Handling C-s
4526 and C-q with flow control}, for an explanation of why
4527 @file{site-lisp/default.el} should not be used.
4529 @itemize @bullet
4531 @item
4532 If you do this for an entire site, the users will be confused by
4533 the disparity between what the documentation says and how Emacs
4534 actually behaves.
4536 @end itemize
4538 @node Backspace invokes help, stty and Backspace key, Binding C-s and C-q, Key bindings
4539 @section Why does the @key{Backspace} key invoke help?
4540 @cindex Backspace key invokes help
4541 @cindex Help invoked by Backspace
4542 @cindex DEL key does not delete
4544 The @key{Backspace} key (on most keyboards) generates ASCII code 8.
4545 @kbd{C-h} sends the same code.  In Emacs by default @kbd{C-h} invokes
4546 help-command.  This is intended to be easy to remember since the first
4547 letter of @samp{help} is @samp{h}.  The easiest solution to this problem
4548 is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the
4549 @key{Delete} key) for deleting the previous character.
4551 For many people this solution may be problematic:
4553 @itemize @bullet
4555 @item
4556 They normally use @key{Backspace} outside of Emacs for deleting the
4557 previous character.  This can be solved by making @key{DEL} the command
4558 for deleting the previous character outside of Emacs.  On many Unix
4559 systems, this command will remap @key{DEL}:
4561 @example
4562 stty erase `^?'
4563 @end example
4565 @item
4566 The user may prefer the @key{Backspace} key for deleting the
4567 previous character because it is more conveniently located on their
4568 keyboard or because they don't even have a separate @key{Delete} key.
4569 In this case, the @key{Backspace} key should be made to behave like
4570 @key{Delete}.  There are several methods.
4572 @itemize @minus
4573 @item
4574 Some terminals (e.g., VT3## terminals) and terminal emulators (e.g.,
4575 TeraTerm) allow the character generated by the @key{Backspace} key to be
4576 changed from a setup menu.
4578 @item
4579 You may be able to get a keyboard that is completely programmable, or a
4580 terminal emulator that supports remapping of any key to any other key.
4582 @item
4583 With Emacs 21.1 and later, you can control the effect of the
4584 @key{Backspace} and @key{Delete} keys, on both dumb terminals and a
4585 windowed displays, by customizing the option
4586 @code{normal-erase-is-backspace-mode}, or by invoking @kbd{M-x
4587 normal-erase-is-backspace}.  See the documentation of these symbols
4588 (@pxref{Emacs Lisp documentation}) for more info.
4590 @item
4591 It is possible to swap the @key{Backspace} and @key{DEL} keys inside
4592 Emacs:
4594 @lisp
4595 (keyboard-translate ?\C-h ?\C-?)
4596 @end lisp
4598 @noindent
4599 This is the recommended method of forcing @key{Backspace} to act as
4600 @key{DEL}, because it works even in modes which bind @key{DEL} to
4601 something other than @code{delete-backward-char}.
4603 Similarly, you could remap @key{DEL} to act as @kbd{C-d}, which by
4604 default deletes forward:
4606 @lisp
4607 (keyboard-translate ?\C-? ?\C-d)
4608 @end lisp
4610 @xref{Swapping keys}, for further details about @code{keyboard-translate}.
4612 @item
4613 Another approach is to switch key bindings and put help on @kbd{C-x h}
4614 instead:
4616 @lisp
4617 (global-set-key "\C-h" 'delete-backward-char)
4619 ;;; overrides mark-whole-buffer
4620 (global-set-key "\C-xh" 'help-command)
4621 @end lisp
4623 @noindent
4624 This method is not recommended, though: it only solves the problem for
4625 those modes which bind @key{DEL} to @code{delete-backward-char}.  Modes
4626 which bind @key{DEL} to something else, such as @code{view-mode}, will
4627 not work as you expect when you press the @key{Backspace} key.  For this
4628 reason, we recommend the @code{keyboard-translate} method, shown
4629 above.
4631 Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}.
4632 @end itemize
4634 Don't try to bind @key{DEL} to @code{help-command}, because there are
4635 many modes that have local bindings of @key{DEL} that will interfere.
4637 @end itemize
4639 When Emacs 21 or later runs on a windowed display, it binds the
4640 @key{Delete} key to a command which deletes the character at point, to
4641 make Emacs more consistent with keyboard operation on these systems.
4643 For more information about troubleshooting this problem, see @ref{DEL
4644 Does Not Delete, , If @key{DEL} Fails to Delete, emacs, The GNU Emacs
4645 Manual}.
4647 @node stty and Backspace key, Swapping keys, Backspace invokes help, Key bindings
4648 @section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}?
4649 @cindex @file{stty} and Emacs
4650 @cindex Backspace and @file{stty}
4651 @cindex Delete and @file{stty}
4653 Good question!
4655 @c FIXME: RMS explained the reasons for this on emacs-hackers.  It's
4656 @c probably worth putting that explanation here.
4658 @node Swapping keys, Producing C-XXX with the keyboard, stty and Backspace key, Key bindings
4659 @section How do I swap two keys?
4660 @cindex Swapping keys
4661 @cindex Keys, swapping
4662 @cindex @code{keyboard-translate}
4664 In Emacs 19, you can swap two keys (or key sequences) by using the
4665 @code{keyboard-translate} function.  For example, to turn @kbd{C-h} into
4666 @key{DEL} and @key{DEL} to @kbd{C-h}, use
4668 @lisp
4669 (keyboard-translate ?\C-h ?\C-?)  ; translate `C-h' to DEL
4670 (keyboard-translate ?\C-? ?\C-h)  ; translate DEL to `C-h'.
4671 @end lisp
4673 @noindent
4674 The first key sequence of the pair after the function identifies what is
4675 produced by the keyboard; the second, what is matched for in the
4676 keymaps.
4678 Keyboard translations are not the same as key bindings in keymaps.
4679 Emacs contains numerous keymaps that apply in different situations, but
4680 there is only one set of keyboard translations, and it applies to every
4681 character that Emacs reads from the terminal.  Keyboard translations
4682 take place at the lowest level of input processing; the keys that are
4683 looked up in keymaps contain the characters that result from keyboard
4684 translation.
4686 @inforef{Keyboard Translations, Keyboard Translations, emacs}.
4688 @node Producing C-XXX with the keyboard, No Meta key, Swapping keys, Key bindings
4689 @section How do I produce C-XXX with my keyboard?
4690 @cindex Producing control characters
4691 @cindex Generating control characters
4692 @cindex Control characters, generating
4694 On terminals (but not under X), some common "aliases" are:
4696 @table @asis
4698 @item @kbd{C-2}  or  @kbd{C-@key{SPC}}
4699 @kbd{C-@@}
4701 @item @kbd{C-6}
4702 @kbd{C-^}
4704 @item @kbd{C-7}  or  @kbd{C-S--}
4705 @kbd{C-_}
4707 @item @kbd{C-4}
4708 @kbd{C-\}
4710 @item @kbd{C-5}
4711 @kbd{C-]}
4713 @item @kbd{C-/}
4714 @kbd{C-?}
4716 @end table
4718 Often other aliases exist; use the @kbd{C-h c} command and try
4719 @key{CTRL} with all of the digits on your keyboard to see what gets
4720 generated.  You can also try the @kbd{C-h w} command if you know the
4721 name of the command.
4723 @node No Meta key, No Escape key, Producing C-XXX with the keyboard, Key bindings
4724 @section What if I don't have a @key{Meta} key?
4725 @cindex No @key{Meta} key
4726 @cindex @key{Meta} key, what to do if you lack it
4728 On many keyboards, the @key{Alt} key acts as @key{Meta}, so try it.
4730 Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}.  In fact,
4731 Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway
4732 (depending on the value of @code{meta-prefix-char}).  Note that you
4733 press @key{Meta} and @key{a} together, but with @key{ESC}, you press
4734 @key{ESC}, release it, and then press @key{a}.
4736 @node No Escape key, Compose Character, No Meta key, Key bindings
4737 @section What if I don't have an @key{Escape} key?
4738 @cindex No Escape key
4739 @cindex Lacking an Escape key
4740 @cindex Escape key, lacking
4742 Type @kbd{C-[} instead.  This should send ASCII code 27 just like an
4743 Escape key would.  @kbd{C-3} may also work on some terminal (but not
4744 under X).  For many terminals (notably DEC terminals) @key{F11}
4745 generates @key{ESC}.  If not, the following form can be used to bind it:
4747 @lisp
4748 ;;; F11 is the documented ESC replacement on DEC terminals.
4749 (define-key function-key-map [f11] [?\e])
4750 @end lisp
4752 @node Compose Character, Binding combinations of modifiers and function keys, No Escape key, Key bindings
4753 @section Can I make my @key{Compose Character} key behave like a @key{Meta} key?
4754 @cindex @key{Compose Character} key, using as @key{Meta}
4755 @cindex @key{Meta}, using @key{Compose Character} for
4757 On a dumb terminal such as a VT220, no.  It is rumored that certain
4758 VT220 clones could have their @key{Compose} key configured this way.  If
4759 you're using X, you might be able to do this with the @code{xmodmap}
4760 command.
4762 @node Binding combinations of modifiers and function keys, Meta key does not work in xterm, Compose Character, Key bindings
4763 @section How do I bind a combination of modifier key and function key?
4764 @cindex Modifiers and function keys
4765 @cindex Function keys and modifiers
4766 @cindex Binding modifiers and function keys
4768 With Emacs 19 and later, you can represent modified function keys in
4769 vector format by adding prefixes to the function key symbol.  For
4770 example (from the on-line documentation):
4772 @lisp
4773 (global-set-key [?\C-x right] 'forward-page)
4774 @end lisp
4776 @noindent
4777 where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}.
4779 You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper},
4780 @key{Super}, @key{Alt}, and @key{Shift} with function keys.  To
4781 represent these modifiers, prepend the strings @samp{C-}, @samp{M-},
4782 @samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name.  Here
4783 is how to make @kbd{H-M-RIGHT} move forward a word:
4785 @lisp
4786 (global-set-key [H-M-right] 'forward-word)
4787 @end lisp
4789 @itemize @bullet
4791 @item
4792 Not all modifiers are permitted in all situations.  @key{Hyper},
4793 @key{Super}, and @key{Alt} are not available on Unix character
4794 terminals.  Non-ASCII keys and mouse events (e.g. @kbd{C-=} and
4795 @kbd{Mouse-1}) also fall under this category.
4797 @end itemize
4799 @xref{Binding keys to commands}, for general key binding instructions.
4801 @node Meta key does not work in xterm, ExtendChar key does not work as Meta, Binding combinations of modifiers and function keys, Key bindings
4802 @section Why doesn't my @key{Meta} key work in an @code{xterm} window?
4803 @cindex @key{Meta} key and @code{xterm}
4804 @cindex Xterm and @key{Meta} key
4806 @inforef{Single-Byte Character Support, Single-Byte Character Set
4807 Support, emacs}.
4809 If the advice in the Emacs manual fails, try all of these methods before
4810 asking for further help:
4812 @itemize @bullet
4814 @item
4815 You may have big problems using @code{mwm} as your window manager.
4816 (Does anyone know a good generic solution to allow the use of the
4817 @key{Meta} key in Emacs with @file{mwm}?)
4819 @item
4820 For X11: Make sure it really is a @key{Meta} key.  Use @code{xev} to
4821 find out what keysym your @key{Meta} key generates.  It should be either
4822 @code{Meta_L} or @code{Meta_R}.  If it isn't, use @file{xmodmap} to fix
4823 the situation.  If @key{Meta} does generate @code{Meta_L} or
4824 @code{Meta_R}, but @kbd{M-x} produces a non-ASCII character, put this in
4825 your @file{~/.Xdefaults} file:
4827 @example
4828  XTerm*eightBitInput:   false
4829  XTerm*eightBitOutput:  true
4830 @end example
4832 @item
4833 Make sure the @code{pty} the @code{xterm} is using is passing 8 bit
4834 characters.  @samp{stty -a} (or @samp{stty everything}) should show
4835 @samp{cs8} somewhere.  If it shows @samp{cs7} instead, use @samp{stty
4836 cs8 -istrip} (or @samp{stty pass8}) to fix it.
4838 @item
4839 If there is an @code{rlogin} connection between @code{xterm} and Emacs, the
4840 @samp{-8} argument may need to be given to rlogin to make it pass all 8 bits
4841 of every character.
4843 @item
4844 If Emacs is running on Ultrix, it is reported that evaluating
4845 @code{(set-input-mode t nil)} helps.
4847 @item
4848 If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when
4849 you type @kbd{M-W}, which is the same conversion Emacs would make if it
4850 got the @kbd{M-W} anyway.  In X11R4, the following resource
4851 specification will do this:
4853 @example
4854 XTerm.VT100.EightBitInput: false
4855 @end example
4857 @noindent
4858 (This changes the behavior of the @code{insert-eight-bit} action.)
4860 With older @code{xterm}s, you can specify this behavior with a translation:
4862 @example
4863 XTerm.VT100.Translations: #override \
4864   Meta<KeyPress>: string(0x1b) insert()
4865 @end example
4867 @noindent
4868 You might have to replace @samp{Meta} with @samp{Alt}.
4870 @end itemize
4872 @node ExtendChar key does not work as Meta,  , Meta key does not work in xterm, Key bindings
4873 @section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x?
4874 @cindex @key{ExtendChar} key as @key{Meta}
4875 @cindex @key{Meta}, using @key{ExtendChar} for
4876 @cindex HP-UX, the @key{ExtendChar} key
4878 This is a result of an internationalization extension in X11R4 and the
4879 fact that HP is now using this extension.  Emacs assumes that the
4880 @code{XLookupString} function returns the same result regardless of the
4881 @key{Meta} key state which is no longer necessarily true.  Until Emacs
4882 is fixed, the temporary kludge is to run this command after each time
4883 the X server is started but preferably before any xterm clients are:
4885 @example
4886 xmodmap -e 'remove mod1 = Mode_switch'
4887 @end example
4889 @c FIXME: Emacs 21 supports I18N in X11; does that mean that this bug is
4890 @c solved?
4892 This will disable the use of the extra keysyms systemwide, which may be
4893 undesirable if you actually intend to use them.
4895 @c ------------------------------------------------------------
4896 @node Alternate character sets, Mail and news, Key bindings, Top
4897 @chapter Alternate character sets
4898 @cindex Alternate character sets
4900 @menu
4901 * Emacs does not display 8-bit characters::
4902 * Inputting eight-bit characters::
4903 * Kanji and Chinese characters::
4904 * Right-to-left alphabets::
4905 @end menu
4907 @node Emacs does not display 8-bit characters, Inputting eight-bit characters, Alternate character sets, Alternate character sets
4908 @section How do I make Emacs display 8-bit characters?
4909 @cindex Displaying eight-bit characters
4910 @cindex Eight-bit characters, displaying
4912 @inforef{Single-Byte Character Support, Single-byte Character Set
4913 Support, emacs}.  On a Unix, when Emacs runs on a text-only terminal
4914 display or is invoked with @samp{emacs -nw}, you typically need to use
4915 @code{set-terminal-coding-system} to tell Emacs what the terminal can
4916 display, even after setting the language environment; otherwise
4917 non-ASCII characters will display as @samp{?}.  On other operating
4918 systems, such as MS-DOS and MS-Windows, Emacs queries the OS about the
4919 character set supported by the display, and sets up the required
4920 terminal coding system automatically.
4922 @node Inputting eight-bit characters, Kanji and Chinese characters, Emacs does not display 8-bit characters, Alternate character sets
4923 @section How do I input eight-bit characters?
4924 @cindex Entering eight-bit characters
4925 @cindex Eight-bit characters, entering
4926 @cindex Input, 8-bit characters
4928 Various methods are available for input of eight-bit characters.  See
4929 @inforef{Single-Byte Character Support, Single-byte Character Set
4930 Support, emacs}.  For more sophisticated methods, @inforef{Input
4931 Methods, Input Methods, emacs}.
4933 @node Kanji and Chinese characters, Right-to-left alphabets, Inputting eight-bit characters, Alternate character sets
4934 @section Where can I get an Emacs that handles kanji, Chinese, or other Far-Eastern character sets?
4935 @cindex Kanji, handling with Emacs
4936 @cindex Chinese, handling with Emacs
4937 @cindex Japanese, handling with Emacs
4938 @cindex Korean, handling with Emacs
4940 Emacs 20 and later includes many of the features of MULE, the MULtilingual
4941 Enhancement to Emacs.  @xref{Installing Emacs}, for information on where
4942 to find and download the latest version of Emacs.
4944 @node Right-to-left alphabets,  , Kanji and Chinese characters, Alternate character sets
4945 @section Where is an Emacs that can handle Semitic (right-to-left) alphabets?
4946 @cindex Right-to-left alphabets
4947 @cindex Hebrew, handling with Emacs
4948 @cindex Semitic alphabets
4949 @cindex Arabic alphabets
4951 Emacs 20 and later supports Hebrew characters (ISO 8859-8), but does not
4952 yet support right-to-left character entry and display.
4954 @email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called
4955 @file{hebrew.el} that allows right-to-left editing of Hebrew.  It
4956 reportedly works out of the box with Emacs 19, but requires patches for
4957 Emacs 18.  Write to Joel if you want the patches or package.
4959 @c FIXME: Should we mention Ehud Karni's package?
4961 @file{hebrew.el} requires a Hebrew screen font, but no other hardware support.
4962 Joel has a screen font for PCs running MS-DOS or GNU/Linux.
4964 You might also try to query archie for files named with @file{hebrew};
4965 several ftp sites in Israel may also have the necessary files.
4967 @c ------------------------------------------------------------
4968 @node Mail and news, Concept index, Alternate character sets, Top
4969 @chapter Mail and news
4970 @cindex Mail and news
4972 @menu
4973 * Changing the included text prefix::
4974 * Saving a copy of outgoing mail::
4975 * Expanding aliases when sending mail::
4976 * Rmail thinks all messages are one big one::
4977 * Sorting the messages in an Rmail folder::
4978 * Rmail writes to /usr/spool/mail::
4979 * Recovering mail files when Rmail munges them::
4980 * Replying to the sender of a message::
4981 * MIME with Emacs mail packages::
4982 * Automatically starting a mail or news reader::
4983 * Reading news with Emacs::
4984 * Gnus does not work with NNTP::
4985 * Viewing articles with embedded underlining::
4986 * Saving a multi-part Gnus posting::
4987 * Starting Gnus faster::
4988 * Catching up in all newsgroups::
4989 * Killing based on nonstandard headers::
4990 * Removing flashing messages::
4991 * Catch-up is slow in Gnus::
4992 * Gnus hangs for a long time::
4993 * Learning more about Gnus::
4994 @end menu
4996 @node Changing the included text prefix, Saving a copy of outgoing mail, Mail and news, Mail and news
4997 @section How do I change the included text prefix in mail/news followups?
4998 @cindex Prefix in mail/news followups, changing
4999 @cindex Included text prefix, changing
5000 @cindex Setting the included text character
5001 @cindex Quoting in mail messages
5003 If you read mail with Rmail or news with Gnus, set the variable
5004 @code{mail-yank-prefix}.  For VM, set @code{vm-included-text-prefix}.
5005 For mh-e, set @code{mh-ins-buf-prefix}.
5007 For fancier control of citations, use Supercite.  @xref{Supercite}.
5009 To prevent Emacs from including various headers of the replied-to
5010 message, set the value of @code{mail-yank-ignored-headers} to an
5011 appropriate regexp.
5013 @node Saving a copy of outgoing mail, Expanding aliases when sending mail, Changing the included text prefix, Mail and news
5014 @section How do I save a copy of outgoing mail?
5015 @cindex Saving a copy of outgoing mail
5016 @cindex Copying outgoing mail to a file
5017 @cindex Filing outgoing mail
5018 @cindex Automatic filing of outgoing mail
5019 @cindex Mail, saving outgoing automatically
5021 You can either mail yourself a copy by including a @samp{BCC} header in the
5022 mail message, or store a copy of the message directly to a file by
5023 including an @samp{FCC} header.
5025 If you use standard mail, you can automatically create a @samp{BCC} to
5026 yourself by putting
5028 @lisp
5029 (setq mail-self-blind t)
5030 @end lisp
5032 @noindent
5033 in your @file{.emacs} file.  You can automatically include an @samp{FCC}
5034 field by putting something like the following in your @file{.emacs}
5035 file:
5037 @lisp
5038 (setq mail-archive-file-name (expand-file-name "~/outgoing"))
5039 @end lisp
5041 The output file will be in Unix mail format, which can be read directly
5042 by VM, but not always by Rmail.  @xref{Learning how to do something}.
5044 If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your
5045 components file.
5047 It does not work to put @samp{set record filename} in the @file{.mailrc}
5048 file.
5050 @node Expanding aliases when sending mail, Rmail thinks all messages are one big one, Saving a copy of outgoing mail, Mail and news
5051 @section Why doesn't Emacs expand my aliases when sending mail?
5052 @cindex Expanding aliases when sending mail
5053 @cindex Mail alias expansion
5054 @cindex Sending mail with aliases
5056 @itemize @bullet
5058 @item
5059 You must separate multiple addresses in the headers of the mail buffer
5060 with commas.  This is because Emacs supports RFC822 standard addresses
5061 like this one:
5063 @example
5064 To: Willy Smith <wks@@xpnsv.lwyrs.com>
5065 @end example
5067 However, you do not need to---and probably should not, unless your
5068 system's version of @file{/usr/ucb/mail} (a.k.a.@: @code{mailx})
5069 supports RFC822---separate addresses with commas in your
5070 @file{~/.mailrc} file.
5072 @item
5073 Emacs normally only reads the @file{.mailrc} file once per session,
5074 when you start to compose your first mail message.  If you edit
5075 @file{.mailrc}, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to
5076 make Emacs reread @file{~/.mailrc}.
5078 @item
5079 If you like, you can expand mail aliases as abbrevs, as soon as you
5080 type them in.  To enable this feature, execute the following:
5082 @lisp
5083 (add-hook 'mail-mode-hook 'mail-abbrevs-setup)
5084 @end lisp
5086 Note that the aliases are expanded automatically only after you type
5087 @key{RET} or a punctuation character (e.g. @kbd{,}).  You can force their
5088 expansion by moving point to the end of the alias and typing @kbd{C-x a e}
5089 (@kbd{M-x expand-abbrev}).
5090 @end itemize
5092 @node Rmail thinks all messages are one big one, Sorting the messages in an Rmail folder, Expanding aliases when sending mail, Mail and news
5093 @section Why does Rmail think all my saved messages are one big message?
5094 @cindex Rmail thinks all messages are one large message
5096 A file created through the @samp{FCC} field in a message is in Unix mail
5097 format, not the format that Rmail uses (BABYL format).  Rmail will try
5098 to convert a Unix mail file into BABYL format on input, but sometimes it
5099 makes errors.  For guaranteed safety, you can make the
5100 @file{saved-messages} file be an inbox for your Rmail file by using the
5101 function @code{set-rmail-inbox-list}.
5103 @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
5104 @section How can I sort the messages in my Rmail folder?
5105 @cindex Rmail, sorting messages in
5106 @cindex Folder, sorting messages in an Rmail
5107 @cindex Sorting messages in an Rmail folder
5109 In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions
5110 and their key bindings.
5112 @node Rmail writes to /usr/spool/mail, Recovering mail files when Rmail munges them, Sorting the messages in an Rmail folder, Mail and news
5113 @section Why does Rmail need to write to @file{/usr/spool/mail}?
5114 @cindex Rmail and @file{/usr/spool/mail}
5115 @cindex @file{/usr/spool/mail} and Rmail
5117 This is the behavior of the @code{movemail} program which Rmail uses.
5118 This indicates that @code{movemail} is configured to use lock files.
5120 RMS writes:
5122 @quotation
5123 Certain systems require lock files to interlock access to mail files.
5124 On these systems, @code{movemail} must write lock files, or you risk losing
5125 mail.  You simply must arrange to let @code{movemail} write them.
5127 Other systems use the @code{flock} system call to interlock access.  On
5128 these systems, you should configure @code{movemail} to use @code{flock}.
5129 @end quotation
5131 @node Recovering mail files when Rmail munges them, Replying to the sender of a message, Rmail writes to /usr/spool/mail, Mail and news
5132 @section How do I recover my mail files after Rmail munges their format?
5133 @cindex Recovering munged mail files
5134 @cindex Rmail munged my files
5135 @cindex Mail files, recovering those munged by Rmail
5137 If you have just done @kbd{M-x rmail-input} on a file and you don't want
5138 to save it in Rmail's format (called BABYL), just kill the buffer (with
5139 @kbd{C-x k}).
5141 @cindex Exporting messages as Unix mail files
5142 If you typed @kbd{M-x rmail} and it read some messages out of your inbox
5143 and you want to put them in a Unix mail file, use @kbd{C-o} on each
5144 message.
5146 @cindex Converting from BABYL to Unix mail format
5147 @cindex @code{unrmail} command
5148 If you want to convert an existing file from BABYL format to Unix mail
5149 format, use the command @kbd{M-x unrmail}: it will prompt you for the
5150 input and output file names.
5152 @pindex b2m
5153 Alternatively, you could use the @code{b2m} program supplied with
5154 Emacs.  @code{b2m} is a filter, and is used like this:
5156 @example
5157  b2m < @var{babyl-file} > @var{mbox-file}
5158 @end example
5160 @noindent
5161 where @var{babyl-file} is the name of the BABYL file, and
5162 @var{mbox-file} is the name of the file where the converted mail will
5163 be written.
5165 @node Replying to the sender of a message, MIME with Emacs mail packages, Recovering mail files when Rmail munges them, Mail and news
5166 @section How can I force Rmail to reply to the sender of a message, but not the other recipients?
5167 @cindex Replying only to the sender of a message
5168 @cindex Sender, replying only to
5169 @cindex Rmail, replying to the sender of a message in
5171 @email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit
5172 @key{r} to reply in Rmail, by default it CCs all of the original
5173 recipients (everyone on the original @samp{To} and @samp{CC}
5174 lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}),
5175 it replies only to the sender.  However, going through the whole
5176 @kbd{C-u} business every time you want to reply is a pain.  This is the
5177 best fix I've been able to come up with:
5179 @lisp
5180 (defun rmail-reply-t ()
5181   "Reply only to the sender of the current message. (See rmail-reply.)"
5182   (interactive)
5183   (rmail-reply t))
5185 (add-hook 'rmail-mode-hook
5186   (lambda ()
5187     (define-key rmail-mode-map "r" 'rmail-reply-t)
5188     (define-key rmail-mode-map "R" 'rmail-reply)))
5189 @end lisp
5191 @node MIME with Emacs mail packages, Automatically starting a mail or news reader, Replying to the sender of a message, Mail and news
5192 @section How can I get my favorite Emacs mail package to support MIME?
5193 @cindex MIME and Emacs mail packages
5194 @cindex Mail packages and MIME
5195 @cindex FAQ for MIME and Emacs
5197 Read the Emacs MIME FAQ, maintained by @email{trey@@cs.berkeley.edu,
5198 MacDonald Hall Jackson} at
5200 @uref{http://bmrc.berkeley.edu/~trey/emacs/mime.html}
5202 Version 6.x of VM supports MIME.  @xref{VM}.  Gnus supports MIME in mail
5203 and news messages as of version 5.8.1 (Pterodactyl).  Rmail has limited
5204 support for single-part MIME messages beginning with Emacs 20.3.
5206 @node Automatically starting a mail or news reader, Reading news with Emacs, MIME with Emacs mail packages, Mail and news
5207 @section How do I make Emacs automatically start my mail/news reader?
5208 @cindex Mail reader, starting automatically
5209 @cindex News reader, starting automatically
5210 @cindex Starting mail/news reader automatically
5212 To start Emacs in Gnus:
5214 @example
5215 emacs -f gnus
5216 @end example
5218 @noindent
5219 in Rmail:
5221 @example
5222 emacs -f rmail
5223 @end example
5225 A more convenient way to start with Gnus:
5227 @example
5228 alias gnus 'emacs -f gnus'
5229 gnus
5230 @end example
5232 It is probably unwise to automatically start your mail or news reader
5233 from your @file{.emacs} file.  This would cause problems if you needed to run
5234 two copies of Emacs at the same time.  Also, this would make it difficult for
5235 you to start Emacs quickly when you needed to.
5237 @node Reading news with Emacs, Gnus does not work with NNTP, Automatically starting a mail or news reader, Mail and news
5238 @section How do I read news under Emacs?
5239 @cindex Reading news under Emacs
5240 @cindex Usenet reader in Emacs
5241 @cindex Gnus newsreader
5243 Use @kbd{M-x gnus}.  It is documented in Info (@pxref{Learning how to do
5244 something}).
5246 @node Gnus does not work with NNTP, Viewing articles with embedded underlining, Reading news with Emacs, Mail and news
5247 @section Why doesn't Gnus work via NNTP?
5248 @cindex Gnus and NNTP
5249 @cindex NNTP, Gnus fails to work with
5251 There is a bug in NNTP version 1.5.10, such that when multiple requests
5252 are sent to the NNTP server, the server only handles the first one
5253 before blocking waiting for more input which never comes.  NNTP version
5254 1.5.11 claims to fix this.
5256 You can work around the bug inside Emacs like this:
5258 @lisp
5259 (setq nntp-maximum-request 1)
5260 @end lisp
5262 You can find out what version of NNTP your news server is running by
5263 telnetting to the NNTP port (usually 119) on the news server machine
5264 (i.e., @kbd{telnet server-machine 119}).  The server should give its
5265 version number in the welcome message.  Type @kbd{quit} to get out.
5267 @xref{Spontaneous entry into isearch-mode}, for some additional ideas.
5269 @node Viewing articles with embedded underlining, Saving a multi-part Gnus posting, Gnus does not work with NNTP, Mail and news
5270 @section How do I view news articles with embedded underlining (e.g., ClariNews)?
5271 @cindex Underlining, embedded in news articles
5272 @cindex News articles with embedded underlining
5273 @cindex Embedded underlining in news articles
5275 Underlining appears like this:
5277 @example
5278 _^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg
5279 @end example
5281 @email{abraham@@dina.kvl.dk, Per Abrahamsen} suggests using the following
5282 code, which uses the underline face to turn such text into true
5283 underlining, inconjunction with Gnus:
5285 @lisp
5286 (defun gnus-article-prepare-overstrike ()
5287   ;; Prepare article for overstrike commands.
5288   (save-excursion
5289     (set-buffer gnus-article-buffer)
5290     (let ((buffer-read-only nil))
5291     (goto-char (point-min))
5292       (while (search-forward "\b" nil t)
5293         (let ((next (following-char))
5294               (previous (char-after (- (point) 2))))
5295           (cond ((eq next previous)
5296                  (delete-region (- (point) 2) (point))
5297                  (put-text-property (point) (1+ (point))
5298                                     'face 'bold))
5299                 ((eq next ?_)
5300                  (delete-region (1- (point)) (1+ (point)))
5301                  (put-text-property (1- (point)) (point)
5302                                     'face 'underline))
5303                 ((eq previous ?_)
5304                  (delete-region (- (point) 2) (point))
5305                  (put-text-property (point) (1+ (point))
5306                                     'face 'underline))))))))
5308 (add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike)
5309 @end lisp
5311 Latest versions of Gnus do such a conversion automatically.
5313 If you prefer to do away with underlining altogether, you can
5314 destructively remove it with @kbd{M-x ununderline-region}; do this
5315 automatically via
5317 @lisp
5318 (add-hook 'gnus-article-prepare-hook
5319   (lambda () (ununderline-region (point-min) (point-max))))
5320 @end lisp
5322 @node Saving a multi-part Gnus posting, Starting Gnus faster, Viewing articles with embedded underlining, Mail and news
5323 @section How do I save all the items of a multi-part posting in Gnus?
5324 @cindex Multi-part postings in Gnus, saving
5325 @cindex Saving multi-part postings in Gnus
5326 @cindex Gnus, saving multi-part postings in
5328 Use @code{gnus-uu}.  Type @kbd{C-c C-v C-h} in the Gnus summary buffer
5329 to see a list of available commands.
5331 @node Starting Gnus faster, Catching up in all newsgroups, Saving a multi-part Gnus posting, Mail and news
5332 @section How do I make Gnus start up faster?
5333 @cindex Faster, starting Gnus
5334 @cindex Starting Gnus faster
5335 @cindex Gnus, starting faster
5337 From the Gnus FAQ (@pxref{Learning more about Gnus}):
5339 @quotation
5340 @email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted
5341 the same query recently and I got an answer to it. I am going to
5342 repeat the answer. What you need is a newer version of gnus, version
5343 5.0.4+. I am using 5.0.12 and it works fine with me with the
5344 following settings:
5346 @lisp
5347 (setq gnus-check-new-newsgroups nil
5348       gnus-read-active-file 'some
5349       gnus-nov-is-evil nil
5350       gnus-select-method '(nntp gnus-nntp-server))
5351 @end lisp
5352 @end quotation
5354 @node Catching up in all newsgroups, Killing based on nonstandard headers, Starting Gnus faster, Mail and news
5355 @section How do I catch up all newsgroups in Gnus?
5356 @cindex Catching up all newsgroups in Gnus
5357 @cindex Gnus, Catching up all newsgroups in
5359 In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e}
5361 Leave off the initial @kbd{M-<} if you only want to catch up from point
5362 to the end of the @file{*Newsgroup*} buffer.
5364 @node Killing based on nonstandard headers, Removing flashing messages, Catching up in all newsgroups, Mail and news
5365 @section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers?
5366 @cindex Killing articles based on nonstandard headers
5367 @cindex Newsgroups header, killing articles based on
5368 @cindex Keywords header, killing articles based on
5369 @cindex Control header, killing articles based on
5371 Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and
5372 @samp{Control} headers are ``Unknown header'' fields.
5374 For the @samp{Newsgroups} header, there is an easy workaround: kill on the
5375 @samp{Xref} header instead, which will be present on any cross-posted article
5376 (as long as your site carries the cross-post group).
5378 If you really want to kill on one of these headers, you can do it like
5379 this:
5381 @lisp
5382 (gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)")
5383 @end lisp
5385 @node Removing flashing messages, Catch-up is slow in Gnus, Killing based on nonstandard headers, Mail and news
5386 @section How do I get rid of flashing messages in Gnus for slow connections?
5387 @cindex Flashing Gnus messages, removing
5388 @cindex Removing flashing Gnus messages
5389 @cindex Slow connections causing flashing messages in Gnus
5390 @cindex Gnus, flashing messages in
5392 Set @code{nntp-debug-read} to @code{nil}.
5394 @node Catch-up is slow in Gnus, Gnus hangs for a long time, Removing flashing messages, Mail and news
5395 @section Why is catch up slow in Gnus?
5396 @cindex Slow catch up in Gnus
5397 @cindex Gnus is slow when catching up
5398 @cindex Crosspostings make Gnus catching up slow
5400 Because Gnus is marking crosspostings read.  You can control this with
5401 the variable @code{gnus-use-cross-reference}.
5403 @node Gnus hangs for a long time, Learning more about Gnus, Catch-up is slow in Gnus, Mail and news
5404 @section Why does Gnus hang for a long time when posting?
5405 @cindex Hangs in Gnus
5406 @cindex Gnus hangs while posting
5407 @cindex Posting, Gnus hangs wile
5409 @email{tale@@uunet.uu.net, David Lawrence} explains:
5411 @quotation
5412 The problem is almost always interaction between NNTP and C News.  NNTP
5413 POST asks C News's @code{inews} to not background itself but rather hang
5414 around and give its exit status so it knows whether the post was successful.
5415 (That wait will on some systems not return the exit status of the
5416 waited for job is a different sort of problem.)  It ends up taking a
5417 long time because @code{inews} is calling @code{relaynews}, which often
5418 waits for another @code{relaynews} to free the lock on the news system
5419 so it can file the article.
5421 My preferred solution is to change @code{inews} to not call
5422 @code{relaynews}, but rather use @code{newsspool}.  This loses some
5423 error-catching functionality, but is for the most part safe as
5424 @code{inews} will detect a lot of the errors on its own.  The C News
5425 folks have sped up @code{inews}, too, so speed should look better to
5426 most folks as that update propagates around.
5427 @end quotation
5429 @node Learning more about Gnus,  , Gnus hangs for a long time, Mail and news
5430 @section Where can I find out more about Gnus?
5431 @cindex FAQ for Gnus
5432 @cindex Gnus FAQ
5433 @cindex Learning more about Gnus
5435 For more information on Gnus, consult the Gnus manual and FAQ, which are
5436 part of the Gnus distribution.
5438 @node Concept index,  , Mail and news, Top
5439 @unnumbered Concept Index
5440 @printindex cp
5442 @contents
5443 @bye