# HG changeset patch # User Dave Love # Date 936183985 0 # Node ID e87d80337a644e5fd1a99be4d0abd2f46cf53c5b # Parent 1ad8606c8cc774cbf75b73d5c3925b3b05779829 Initial revision diff -r 1ad8606c8cc7 -r e87d80337a64 man/faq.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/faq.texi Wed Sep 01 11:06:25 1999 +0000 @@ -0,0 +1,4898 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename faq.info +@settitle GNU Emacs FAQ +@c %**end of header + +@setchapternewpage odd + +@c The @ifinfo stuff only appears in the Info version +@ifinfo +Copyright 1994-1999 Reuven M. Lerner@* +Copyright 1992-1993 Steven Byrnes@* +Copyright 1990-1992 Joseph Brian Wells@* + +This list of frequently asked questions about GNU Emacs with answers +("FAQ") may be translated into other languages, transformed into other +formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information. + +The same conditions apply to any derivative of the FAQ as apply to the FAQ +itself. Every copy of the FAQ must include this notice or an approved +translation, information on who is currently maintaining the FAQ and how to +contact them (including their e-mail address), and information on where the +latest version of the FAQ is archived (including FTP information). + +The FAQ may be copied and redistributed under these conditions, except that +the FAQ may not be embedded in a larger literary work unless that work +itself allows free copying and redistribution. +@end ifinfo + +@c The @titlepage stuff only appears in the printed version +@titlepage +@sp 10 +@center @titlefont{GNU Emacs FAQ} + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1994-1999 Reuven M. Lerner@* +Copyright @copyright{} 1992-1993 Steven Byrnes@* +Copyright @copyright{} 1990-1992 Joseph Brian Wells@* + +This list of frequently asked questions about GNU Emacs with answers +("FAQ") may be translated into other languages, transformed into other +formats (e.g. Texinfo, Info, WWW, WAIS), and updated with new information. + +The same conditions apply to any derivative of the FAQ as apply to the FAQ +itself. Every copy of the FAQ must include this notice or an approved +translation, information on who is currently maintaining the FAQ and how to +contact them (including their e-mail address), and information on where the +latest version of the FAQ is archived (including FTP information). + +The FAQ may be copied and redistributed under these conditions, except that +the FAQ may not be embedded in a larger literary work unless that work +itself allows free copying and redistribution. +@end titlepage + +@node Top, FAQ notation, (dir), (dir) + +This is the GNU Emacs FAQ, last updated on @today{}. + +The FAQ is slowly but surely being turned into a Texinfo document, +allowing us to create HTML, Info, and TeX documents from a single source +file. Please bear with us as we improve on this format. If you have +any suggestions or questions, please contact +@email{emacs-faq@@lerner.co.il, the FAQ maintainers}. + +@menu +* FAQ notation:: +* General questions:: +* Getting help:: +* Status of Emacs:: +* Common requests:: +* Bugs and problems:: +* Compiling and installing Emacs:: +* Finding Emacs and related packages:: +* Major packages and programs:: +* Key bindings:: +* Alternate character sets:: +* Mail and news:: +* Concept index:: +@end menu + +@c ------------------------------------------------------------ +@node FAQ notation, General questions, Top, Top +@chapter FAQ notation +@cindex FAQ notation + +This section describes notation used in the GNU Emacs FAQ, as well as in +the Emacs documentation. Consult this section if this is the first time +you are reading the FAQ, or if you are confused by notation or terms +used in the FAQ. + +@menu +* Basic keys:: +* Extended commands:: +* On-line manual:: +* Filename conventions:: +* Common acronyms:: +@end menu + +@node Basic keys, Extended commands, FAQ notation, FAQ notation +@section What do these mean: @kbd{C-h}, @kbd{M-C-a}, @key{RET}, @kbd{@key{ESC} a}, etc.? +@cindex Basic keys +@cindex Control key, notation for +@cindex @key{Meta} key, notation for +@cindex Control-meta characters, notation for +@cindex @kbd{C-h}, definition of +@cindex @kbd{M-C-h}, definition of +@cindex @key{DEL}, definition of +@cindex @key{ESC}, definition of +@cindex @key{LFD}, definition of +@cindex @key{RET}, definition of +@cindex @key{SPC}, definition of +@cindex @key{TAB}, definition of + +@itemize @bullet + +@item +@kbd{C-x}: press the @key{x} key while holding down the @key{Control} key + +@item +@kbd{M-x}: press the @key{x} key while holding down the @key{Meta} key +(if your computer doesn't have a @key{Meta} key, see @xref{No Meta key}) + +@item +@kbd{M-C-x}: press the @key{x} key while holding down both @key{Control} +and @key{Meta} + +@item +@kbd{C-M-x}: a synonym for the above + +@item +@key{LFD}: Linefeed or Newline; same as @kbd{C-j} + +@item +@key{RET}: @key{Return}, sometimes marked @key{Enter}; same as @kbd{C-m} + +@item +@key{DEL}: @key{Delete}, usually not the same as @key{Backspace}; same + as @kbd{C-?} (@xref{Backspace invokes help} if deleting invokes Emacs help) + +@item +@key{ESC}: Escape; same as @kbd{C-[} + +@item +@key{TAB}: Tab; same as @kbd{C-i} + +@item +@key{SPC}: Space bar + +@end itemize + +Key sequences longer than one key (and some single-key sequences) are +inside double quotes or on lines by themselves. Any real spaces in such +a key sequence should be ignored; only @key{SPC} really means press the +space key. + +The ASCII code sent by @kbd{C-x} (except for @kbd{C-?}) is the value +that would be sent by pressing just @key{x} minus 96 (or 64 for +uppercase @key{X}) and will be from 0 to 31. The ASCII code sent by +@kbd{M-x} is the sum of 128 and the ASCII code that would be sent by +pressing just @key{x}. Essentially, @key{Control} turns off bits 5 and +6 and @key{Meta} turns on bit 7. + +@kbd{C-?} (aka @key{DEL}) is ASCII code 127. It is a misnomer to call +@kbd{C-?} a "control" key, since 127 has both bits 5 and 6 turned ON. +Also, on very few keyboards does @kbd{C-?} generate ASCII code 127. + +@inforef{Characters, Characters, emacs} and @inforef{Keys, Keys, emacs} +for more information. (@xref{On-line manual} for more information about +Info.) + +@node Extended commands, On-line manual, Basic keys, FAQ notation +@section What does @file{M-x @var{command}} mean? +@cindex Extended commands +@cindex Commands, extended +@cindex M-x, meaning of + +@kbd{M-x @var{command}} means type @kbd{M-x}, then type the name of the +command, then type @key{RET}. (@xref{Basic keys} if you're not sure +what @kbd{M-x} and @key{RET} mean.) + +@kbd{M-x} (by default) invokes the command +@code{execute-extended-command}. This command allows you to run any +Emacs command if you can remember the command's name. If you can't +remember the command's name, you can type @key{TAB} and @key{SPC} for +completion, @key{?} for a list of possibilities, and @kbd{M-p} and +@kbd{M-n} to see previous commands entered. An Emacs "command" is any +"interactive" Emacs function. + +Your system administrator may have bound other key sequences to invoke +@code{execute-extended-command}. A function key labeled @kbd{Do} is a +good candidate for this. + +To run non-interactive Emacs functions, @pxref{Evaluating Emacs Lisp code}. + +@node On-line manual, Filename conventions, Extended commands, FAQ notation +@section How do I read topic XXX in the on-line manual? +@cindex On-line manual, reading topics in +@cindex Reading topics in the on-line manual +@cindex Finding topics in the on-line manual +@cindex Info, finding topics in + +When we refer you to topic XXX in the on-line manual, you can read this +manual node inside Emacs (assuming nothing is broken) by typing @kbd{C-h +i m emacs @key{RET} m XXX @key{RET}}. + +This invokes Info, the GNU hypertext documentation browser. If you don't +already know how to use Info, type @key{?} from within Info. + +If we refer to topic XXX:YYY, type @kbd{C-h i m emacs @key{RET} m XXX +@key{RET} m YYY @key{RET}}. + +Your system administrator may not have installed the Info files, or may +have installed them improperly. In this case you should complain. + +@xref{Getting a printed manual} if you would like a paper copy of the +Emacs manual. + +@node Filename conventions, Common acronyms, On-line manual, FAQ notation +@section What are @file{etc/SERVICE}, @file{src/config.h}, and @file{lisp/default.el}? +@cindex Filename conventions +@cindex Conventions for filenames +@cindex Directories and files that come with Emacs + +These are files that come with Emacs. The Emacs distribution is divided +into subdirectories; the important ones are @file{etc}, @file{lisp}, and +@file{src}. + +If you use Emacs, but don't know where it is kept on your system, start +Emacs, then type @kbd{C-h v data-directory @key{RET}}. The directory +name displayed by this will be the full pathname of the installed +@file{etc} directory. + +The location of your Info directory (i.e., where on-line documentation +is stored) is kept in the variable @code{Info-default-directory-list}. Use +@kbd{C-h v Info-default-directory-list @key{RET}} to see the contents of +this variable, which will be a list of directory names. The last +directory in that list is probably where most Info files are stored. By +default, Info documentation is placed in @file{/usr/local/info}. + +Some of these files are available individually via FTP or e-mail; +@pxref{Informational files for Emacs}. All are available in the source +distribution. Many of the files in the @file{etc} directory are also +available via the Emacs "help" menu, or by typing @kbd{C-h ?} (@kbd{M-x +help-for-help}). + +Your system administrator may have removed the @file{src} directory and +many files from the @file{etc} directory. + +@node Common acronyms, , Filename conventions, FAQ notation +@section What are FSF, LPF, OSF, GNU, RMS, FTP, and GPL? +@cindex FSF, definition of +@cindex LPF, definition of +@cindex OSF, definition of +@cindex GNU, definition of +@cindex RMS, definition of +@cindex Stallman, Richard, acronym for +@cindex Richard Stallman, acronym for +@cindex FTP, definition of +@cindex GPL, definition of +@cindex Acronyms, definitions for +@cindex Common acronyms, definitions for + +@table @asis + +@item FSF +Free Software Foundation + +@item LPF +League for Programming Freedom + +@item OSF +Open Software Foundation + +@item GNU +GNU's Not Unix + +@item RMS +Richard Matthew Stallman + +@item FTP +File Transfer Protocol + +@item GPL +GNU General Public License + +@end table + +Avoid confusing the FSF, the LPF, and the OSF. The LPF opposes +look-and-feel copyrights and software patents. The FSF aims to make +high quality free software available for everyone. The OSF is a +consortium of computer vendors which develops commercial software for +Unix systems. + +The word "free" in the title of the Free Software Foundation refers to +"freedom," not "zero dollars." Anyone can charge any price for +GPL-covered software that they want to. However, in practice, the +freedom enforced by the GPL leads to low prices, because you can always +get the software for less money from someone else, because everyone has +the right to resell or give away GPL-covered software. + +@c ------------------------------------------------------------ +@node General questions, Getting help, FAQ notation, Top +@chapter General questions +@cindex General questions + +This section contains general questions having to do with Emacs, the +Free Software Foundation, and related organizations. + +@menu +* The LPF:: +* Real meaning of copyleft:: +* Guidelines for newsgroup postings:: +* Newsgroup archives:: +* Reporting bugs:: +* Unsubscribing from Emacs lists:: +* Contacting the FSF:: +@end menu + +@node The LPF, Real meaning of copyleft, General questions, General questions +@section What is the LPF? +@cindex LPF, description of +@cindex League for Programming Freedom +@cindex Software patents, opposition to +@cindex Patents for software, opposition to + +The LPF opposes the expanding danger of software patents and +look-and-feel copyrights. To get more information, feel free to contact +the LPF via e-mail or otherwise. You may also contact +@email{jbw@@cs.bu.edu, Joe Wells}; he will be happy to talk with you +about the LPF. + +You can find more information about the LPF in the file @file{etc/LPF}. +More papers describing the LPF's views are available on the Internet and +also from @uref{http://lpf.ai.mit.edu/, the LPF}. + +@node Real meaning of copyleft, Guidelines for newsgroup postings, The LPF, General questions +@section What is the real legal meaning of the GNU copyleft? +@cindex Copyleft, real meaning of +@cindex GPL, real meaning of +@cindex General Public License, real meaning of +@cindex Discussion of the GPL + +The real legal meaning of the GNU General Public License (copyleft) will +only be known if and when a judge rules on its validity and scope. +There has never been a copyright infringement case involving the GPL to +set any precedents. Please take any discussion regarding this issue to +the newsgroup @uref{news:gnu.misc.discuss}, which was created to hold the +extensive flame wars on the subject. + +RMS writes: + +@quotation +The legal meaning of the GNU copyleft is less important than the spirit, +which is that Emacs is a free software project and that work pertaining +to Emacs should also be free software. "Free" means that all users have +the freedom to study, share, change and improve Emacs. To make sure +everyone has this freedom, pass along source code when you distribute +any version of Emacs or a related program, and give the recipients the +same freedom that you enjoyed. +@end quotation + +@node Guidelines for newsgroup postings, Newsgroup archives, Real meaning of copyleft, General questions +@section What are appropriate messages for @uref{news:gnu.emacs.help}, @uref{news:gnu.emacs.bug}, @uref{news:comp.emacs}, etc.? +@cindex Newsgroups, appropriate messages for +@cindex GNU newsgroups, appropriate messages for +@cindex Usenet groups, appropriate messages for +@cindex Mailing lists, appropriate messages for + +The file @file{etc/MAILINGLISTS} discusses the purpose of each GNU +mailing-list. (@xref{Informational files for Emacs} if you want a copy +of the file.) For those lists which are gatewayed with newsgroups, it +lists both the newsgroup name and the mailing list address. + +@uref{news:comp.emacs} is for discussion of Emacs programs in general. +This includes Emacs along with various other implementations, such as +JOVE, MicroEmacs, Freemacs, MG, Unipress, CCA, and Epsilon. + +Many people post Emacs questions to @uref{news:comp.emacs} because they +don't receive any of the gnu.* newsgroups. Arguments have been made +both for and against posting GNU-Emacs-specific material to +@uref{news:comp.emacs}. You have to decide for yourself. + +Messages advocating "non-free" software are considered unacceptable on +any of the gnu.* newsgroups except for @uref{news:gnu.misc.discuss}, +which was created to hold the extensive flame-wars on the subject. +"Non-free" software includes any software for which the end user can't +freely modify the source code and exchange enhancements. Be careful to +remove the gnu.* groups from the "Newsgroups:" line when posting a +followup that recommends such software. + +@uref{news:gnu.emacs.bug} is a place where bug reports appear, but avoid +posting bug reports to this newsgroup (@pxref{Reporting bugs}). + +@node Newsgroup archives, Reporting bugs, Guidelines for newsgroup postings, General questions +@section Where can I get old postings to @uref{news:gnu.emacs.help} and other GNU groups? +@cindex Archived postings from @uref{news:gnu.emacs.help} +@cindex Usenet archives for GNU groups +@cindex Old Usenet postings for GNU groups + +The FSF has maintained archives of all of the GNU mailing lists for many +years, although there may be some unintentional gaps in coverage. The +archive is not particularly well organized or easy to retrieve +individual postings from, but pretty much everything is there. + +The archive is at @uref{ftp://ftp-mailing-list-archives.gnu.org}. + +As of this writing, the archives are not yet working. + +Web-based Usenet search services, such as +@uref{http://www.dejanews.com, DejaNews}, also archive the +gnu.* groups. + +@node Reporting bugs, Unsubscribing from Emacs lists, Newsgroup archives, General questions +@section Where should I report bugs and other problems with Emacs? +@cindex Bug reporting +@cindex Good bug reports +@cindex How to submit a bug report +@cindex Reporting bugs + +The correct way to report Emacs bugs is by e-mail to +@email{bug-gnu-emacs@@gnu.org}. Anything sent here also appears in the +newsgroup @uref{news:gnu.emacs.bug}, but please use e-mail instead of +news to submit the bug report. This ensures a reliable return address +so you can be contacted for further details. + +Be sure to read the "Bugs" section of the Emacs manual before reporting +a bug to bug-gnu-emacs! The manual describes in detail how to submit a +useful bug report. (@xref{On-line manual} if you don't know how to read the +manual.) + +RMS says: + +@quotation +Sending bug reports to @email{help-gnu-emacs@@gnu.org} (which has the +effect of posting on @uref{news:gnu.emacs.help}) is undesirable because +it takes the time of an unnecessarily large group of people, most of +whom are just users and have no idea how to fix these problem. +@email{bug-gnu-emacs@@gnu.org} reaches a much smaller group of people +who are more likely to know what to do and have expressed a wish to +receive more messages about Emacs than the others. +@end quotation + +RMS says it is sometimes fine to post to @uref{news:gnu.emacs.help}: + +@quotation +If you have reported a bug and you don't hear about a possible fix, +then after a suitable delay (such as a week) it is okay to post on +gnu.emacs.help asking if anyone can help you. +@end quotation + +If you are unsure whether you have found a bug, consider the following +non-exhaustive list, courtesy of RMS: + +@quotation +If Emacs crashes, that is a bug. If Emacs gets compilation errors +while building, that is a bug. If Emacs crashes while building, that +is a bug. If Lisp code does not do what the documentation says it +does, that is a bug. +@end quotation + +@node Unsubscribing from Emacs lists, Contacting the FSF, Reporting bugs, General questions +@section How do I unsubscribe from this mailing list? +@cindex Unsubscribing from GNU mailing lists +@cindex Removing yourself from GNU mailing lists + +If you are receiving a GNU mailing list named "XXX", you might be able +to unsubscribe from it by sending a request to the address +@email{XXX-request@@gnu.org}. However, this will not work if you are +not listed on the main mailing list, but instead receive the mail from a +distribution point. In that case, you will have to track down at which +distribution point you are listed. Inspecting the @samp{Received} headers +on the mail messages may help, along with liberal use of the "EXPN" or +"VRFY" sendmail commands through "telnet smtp". Ask your +postmaster for help. + +@node Contacting the FSF, , Unsubscribing from Emacs lists, General questions +@section What is the current address of the FSF? +@cindex Snail mail address of the FSF +@cindex Postal address of the FSF +@cindex Contracting the FSF +@cindex Free Software Foundation, contacting + +@table @asis + +@item E-mail +gnu@@gnu.org + +@item Telephone ++1-617-542-5942 + +@item Fax ++1-617-542-2652 + +@item World Wide Web +@uref{http://www.gnu.org/} + +@item Postal address +Free Software Foundation@* +59 Temple Place - Suite 330@* +Boston, MA 02111-1307@* +USA@* + +@end table + +For details on how to order items directly from the FSF, see the file +@file{etc/ORDERS}. + +@c ------------------------------------------------------------ +@node Getting help, Status of Emacs, General questions, Top +@chapter Getting help +@cindex Getting help + +This section tells you how to get help with Emacs + +@menu +* Basic editing:: +* Learning how to do something:: +* Getting a printed manual:: +* Emacs Lisp documentation:: +* Installing Texinfo documentation:: +* Printing a Texinfo file:: +* Viewing Info files outside of Emacs:: +* Informational files for Emacs:: +* Help installing Emacs:: +* Obtaining the FAQ:: +@end menu + +@node Basic editing, Learning how to do something, Getting help, Getting help +@section I'm just starting Emacs; how do I do basic editing? +@cindex Basic editing with Emacs +@cindex Beginning editing +@cindex Tutorial, invoking the +@cindex Self-paced tutorial, invoking the +@cindex Help system, entering the + +Type @kbd{C-h t} to invoke the self-paced tutorial. Just typing @kbd{C-h} +enters the help system. + +Your system administrator may have changed @kbd{C-h} to act like +@key{DEL} to deal with local keyboards. You can use @kbd{M-x +help-for-help} instead to invoke help. To discover what key (if any) +invokes help on your system, type @kbd{M-x where-is @key{RET} +help-for-help @key{RET}}. This will print a comma-separated list of key +sequences in the echo area. Ignore the last character in each key +sequence listed. Each of the resulting key sequences invokes help. + +Emacs help works best if it is invoked by a single key whose value +should be stored in the variable @code{help-char}. + +There is also a WWW-based tutorial for Emacs 18, much of which is also +relevant for Emacs 20, available at + +@uref{http://kufacts.cc.ukans.edu/cwis/writeups/misc/emacsguide.html} + +@node Learning how to do something, Getting a printed manual, Basic editing, Getting help +@section How do I find out how to do something in Emacs? +@cindex Help for Emacs +@cindex Learning to do something in Emacs +@cindex Reference card for Emacs +@cindex Overview of help systems + +There are several methods for finding out how to do things in Emacs. + +@itemize @bullet + +@item +The complete text of the Emacs manual is available on-line via the Info +hypertext reader. Type @kbd{C-h i} to invoke Info. Typing @key{h} +immediately after entering Info will provide a short tutorial on how to +use it. + +@item +You can order a hardcopy of the manual from the FSF. @xref{Getting a +printed manual}. + +@item +You can get a printed reference card listing commands and keys to +invoke them. You can order one from the FSF for $1 (or 10 for $5), +or you can print your own from the @file{etc/refcard.tex} or +@file{etc/refcard.ps} files in the Emacs distribution. + +@item +You can list all of the commands whose names contain a certain word +(actually which match a regular expression) using @kbd{C-h a} (@kbd{M-x +command-apropos}). + +@item +You can list all of the functions and variables whose names contain a +certain word using @kbd{M-x apropos}. + +@item +There are many other commands in Emacs for getting help and +information. To get a list of these commands, type @samp{?} after +@kbd{C-h}. + +@end itemize + +@node Getting a printed manual, Emacs Lisp documentation, Learning how to do something, Getting help +@section How do I get a printed copy of the Emacs manual? +@cindex Printed Emacs manual, obtaining +@cindex Manual, obtaining a printed copy of +@cindex Emacs manual, obtaining a printed copy of + +You can order a printed copy of the Emacs manual from the FSF. For +details see the file @file{etc/ORDERS}. + +The full @TeX{} source for the manual also comes in the @file{man} +directory of the Emacs distribution, if you're daring enough to try to +print out this 440-page manual yourself (@pxref{Printing a Texinfo +file}). + +If you absolutely have to print your own copy, and you don't have @TeX{}, +you can get a PostScript version from + +@uref{ftp://ftp.cs.ubc.ca/pub/archive/gnu/manuals_ps/emacs-19.21.ps.gz} + +Note that the above document is somewhat out of date, although most +major concepts are still relevant. This site requests that you please +@emph{confine any major ftping to late evenings or early mornings, local +time} (Pacific time zone, GMT-8). + +A WWW version of the (somewhat outdated) Emacs 19.34 manual is at + +@uref{http://www.cl.cam.ac.uk/texinfodoc/emacs_toc.html} + +@xref{Learning how to do something} for how to view the manual on-line. + +@node Emacs Lisp documentation, Installing Texinfo documentation, Getting a printed manual, Getting help +@section Where can I get documentation on Emacs Lisp? +@cindex Documentation on Emacs Lisp +@cindex Function documentation +@cindex Variable documentation +@cindex Emacs Lisp Reference Manual +@cindex Reference manual for Emacs Lisp + +Within Emacs, you can type @kbd{C-h f} to get the documentation for a +function, @kbd{C-h v} for a variable. + +For more information, obtain the Emacs Lisp Reference Manual. Details on +ordering it from FSF are in file @file{etc/ORDERS}. + +The Emacs Lisp Reference Manual is also available on-line, in Info +format. Texinfo source for the manual (along with pregenerated Info +files) is available at + +@uref{ftp://ftp.gnu.org/pub/gnu/emacs/elisp-manual-20-2.5.tar.gz} + +and all mirrors of @samp{ftp.gnu.org} (@xref{Current GNU distributions} for a +list). @xref{Installing Texinfo documentation} if you want to install +the Info files, or @ref{Printing a Texinfo file} if you want to use the +Texinfo source to print the manual yourself. + +WWW versions of the Emacs Lisp Reference Manual are available at + +@uref{http://www.cl.cam.ac.uk/texinfodoc/elisp_1.html} + +and + +@uref{http://www.cs.indiana.edu/usr/local/www/elisp/lispref/elisp_toc.html} + +@node Installing Texinfo documentation, Printing a Texinfo file, Emacs Lisp documentation, Getting help +@section How do I install a piece of Texinfo documentation? +@cindex Texinfo documentation, installing +@cindex Installing Texinfo documentation +@cindex New Texinfo files, installing +@cindex Documentation, installing new Texinfo files + +First, you must turn the Texinfo files into Info files. You may do this +using the stand-alone @file{makeinfo} program, available as part of the latest +Texinfo package at + +@uref{ftp://ftp.gnu.org/pub/gnu/texinfo/texinfo-3.12.tar.gz} + +and all mirrors of @samp{ftp.gnu.org} (@xref{Current GNU distributions} for a list). + +For information about the Texinfo format, read the Texinfo manual which +comes with Emacs. This manual also comes installed in Info format, so +you can read it on-line. + +Neither @code{texinfo-format-buffer} nor @file{makeinfo} installs the +resulting Info files in Emacs's Info tree. To install Info files: + +@enumerate + +@item Move the files to the @file{info} directory in the installed Emacs + distribution. @xref{Filename conventions} if you don't know where that is. + +@item Edit the file @file{info/dir} in the installed Emacs distribution, + and add a line for the top level node in the Info package that you are + installing. Follow the examples already in this file. The format is: + +@example +* Topic: (relative-pathname). Short description of topic. +@end example + +@end enumerate + +If you want to install Info files and you don't have the necessary +privileges, you have several options: + +@itemize @bullet + +@item +Info files don't actually need to be installed before being used. You +can feed a file name to the @code{Info-goto-node} command (invoked by +pressing @key{g} in Info mode) by typing the name of the file in +parentheses. This goes to the node named "Top" in that file. For +example, to view a Info file named "XXX" in your home directory, you can +type this: + +@lisp +C-h i g (~/XXX) @key{RET} +@end lisp + +@item +You can create your own Info directory. You can tell Emacs where the +Info directory is by adding its pathname to the value of the variable +@code{Info-default-directory-list}. For example, to use a private Info +directory which is a subdirectory of your home directory named "Info", +you could put this in your @file{.emacs} file: + +@lisp +(setq Info-default-directory-list + (cons "~/Info" Info-default-directory-list)) +@end lisp + +You will need a top-level Info file named @file{dir} in this directory +which has everything the system dir file has in it, except it should +list only entries for Info files in that directory. You might not need +it if all files in this directory were referenced by other @file{dir} +files. The node lists from all @file{dir} files in +@code{Info-default-directory-list} are merged by the Info system. + +@end itemize + +@node Printing a Texinfo file, Viewing Info files outside of Emacs, Installing Texinfo documentation, Getting help +@section How do I print a Texinfo file? +@cindex Printing a Texinfo file +@cindex Texinfo file, printing + +You can't get nicely printed output from Info files; you must still have +the original Texinfo source file for the manual you want to print. + +Assuming you have @TeX{} installed on your system, follow these steps: + +@enumerate + +@item Make sure the first line of the Texinfo file looks like this: + +@example +\input texinfo +@end example + + You may need to change @samp{texinfo} to the full pathname of the + texinfo.tex file, which comes with Emacs as @samp{man/texinfo.tex} (or + copy or link it into the current directory). + +@item @code{tex XXX.texinfo} + +@item @code{texindex XXX.??} + + The @samp{texindex} program comes with Emacs as @file{man/texindex.c}. + +@item @code{tex XXX.texinfo} + +@item Print the DVI file @file{XXX.dvi} in the normal way for printing DVI files at your site. + +@end enumerate + +To get more general instructions, retrieve the latest Texinfo package +(@xref{Installing Texinfo documentation}). + +@node Viewing Info files outside of Emacs, Informational files for Emacs, Printing a Texinfo file, Getting help +@section Can I view Info files without using Emacs? +@cindex Viewing Info files +@cindex Info file viewers +@cindex Alternative Info file viewers + +Yes. Here are some alternative programs: + +@itemize @bullet + +@item Info, a stand-alone version of the Info program, comes as part of the +Texinfo package. @xref{Installing Texinfo documentation} for details. + +@item Xinfo, a stand-alone version of the Info program that runs under X +Windows. You can get it at +@uref{ftp://ftp.gnu.org/pub/gnu/xinfo/xinfo-1.01.01.tar.gz} and all +mirrors of @samp{ftp.gnu.org} (@xref{Current GNU distributions} for a list). + +@item Tkinfo, an Info viewer that runs under X Windows and uses Tcl/Tk. You +can get Tkinfo at @uref{http://math-www.uni-paderborn.de/~axel/tkinfo/}. + +@end itemize + +@node Informational files for Emacs, Help installing Emacs, Viewing Info files outside of Emacs, Getting help +@section What informational files are available for Emacs? +@cindex Informational files included with Emacs +@cindex Files included with Emacs +@cindex @file{COPYING}, description of file +@cindex @file{DISTRIB}, description of file +@cindex @file{FAQ}, description of file +@cindex @file{FTP}, description of file +@cindex @file{GNU}, description of file +@cindex @file{INTERVIEW}, description of file +@cindex @file{LPF}, description of file +@cindex @file{MACHINES}, description of file +@cindex @file{MAILINGLISTS}, description of file +@cindex @file{NEWS}, description of file +@cindex @file{SERVICE}, description of file +@cindex @file{SUN-SUPPORT}, description of file + +This isn't a frequently asked question, but it should be! A variety of +informational files about Emacs and relevant aspects of the GNU project +are available for you to read. + +The following files are available in the @file{etc} directory of the +Emacs distribution (@pxref{Filename conventions} if you're not sure where that is). + +@table @file + +@item COPYING +Emacs General Public License + +@item DISTRIB +Emacs Availability Information, including the popular "Free Software +Foundation Order Form" + +@item FAQ +Emacs Frequently Asked Questions (You're reading it) + +@item FTP +How to get GNU Software by Internet FTP or by UUCP + +@item GNU +The GNU Manifesto + +@item INTERVIEW +Richard Stallman discusses his public-domain UNIX-compatible software +system with BYTE editors + +@item LPF +Why you should join the League for Programming Freedom + +@item MACHINES +Status of Emacs on Various Machines and Systems + +@item MAILINGLISTS +GNU Project Electronic Mailing Lists + +@item NEWS +Emacs news, a history of user-visible changes + +@item SERVICE +GNU Service Directory + +@item SUN-SUPPORT +including "Using Emacstool with GNU Emacs" + +@end table + +Latest versions of the above files also available at + +@uref{ftp://ftp.gnu.org/pub/gnu/GNUinfo/} + +More GNU information, including back issues of the "GNU's Bulletin", are +at + +@uref{http://www.gnu.org/bulletins/bulletins.html} and + +@uref{http://www.cs.pdx.edu/~trent/gnu/gnu.html} + +@node Help installing Emacs, Obtaining the FAQ, Informational files for Emacs, Getting help +@section Where can I get help in installing Emacs? +@cindex Installation help +@cindex Help installing Emacs + +@xref{Installing Emacs} for some basic installation hints, and question +83 if you have problems with the installation. + +The file @file{etc/SERVICE} (@pxref{Filename conventions} if you're not +sure where that is) lists companies and individuals willing to sell you +help in installing or using Emacs. An up-to-date version this file is +available on @samp{ftp.gnu.org} (@pxref{Informational files for Emacs}). + +@node Obtaining the FAQ, , Help installing Emacs, Getting help +@section Where can I get the latest version of this FAQ? +@cindex FAQ, obtaining the +@cindex Latest FAQ version, obtaining the +@cindex Retrieving the latest FAQ version +@cindex E-mail, retrieving the FAQ via +@cindex Web, reading the FAQ on the + +The Emacs FAQ is available in several ways: + +@itemize @bullet + +@item +Inside of Emacs itself. You can get it from selecting the "Emacs FAQ" +option from the "Help" menu at the top of any Emacs frame, or by typing +@kbd{C-h F} (@kbd{M-x view-emacs-FAQ}). + +@item +Via USENET. If you can read news, the FAQ should be available in your +news spool, in both the @uref{news:gnu.emacs.help} and +@uref{news:comp.emacs} newsgroups. Every news reader should allow you +to read any news article that is still in the news spool, even if you +have read the article before. You may need to read the instructions for +your news reader to discover how to do this. In @file{rn}, this command +will do this for you at the article selection level: + +@example +?GNU Emacs Frequently Asked Questions?rc:m +@end example + +In Gnus, you should type @kbd{C-u C-x C-s} from the @file{*Summary*} +buffer or @kbd{C-u @key{SPC}} from the @file{*Newsgroup*} buffer to view +all articles in a newsgroup. + +If the FAQ articles have expired and been deleted from your news spool, +it might (or might not) do some good to complain to your news +administrator, because the most recent FAQ should not expire for a +while. + +@item Via HTTP or FTP. You can always fetch the latest FAQ from + +@uref{http://www.lerner.co.il/emacs/} and + +@uref{ftp://ftp.lerner.co.il/pub/emacs/} + +@item +In the Emacs distribution. Since Emacs 18.56, the FAQ at the time +of release has been part of the Emacs distribution as @file{etc/FAQ} +(@pxref{Filename conventions}). + +@item +Via the World Wide Web. A hypertext version is available at + +@uref{http://www.lerner.co.il/emacs/} + +@item +Via anonymous ftp and e-mail from @file{rtfm.mit.edu} (and its mirror in +Europe), the main repository for FAQs and other items posted to +news.answers. The Emacs FAQs are available at + +@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} and + +@uref{ftp://ftp.uni-paderborn.de/pub/doc/FAQ/comp/emacs/} + +If you do not have access to anonymous FTP, you can access the archives +using the @file{rtfm.mit.edu} mail server. The Emacs FAQ can be +retrieved by sending mail to @email{mail-server@@rtfm.mit.edu} with a +blank subject and containing + +@example +send usenet/news.answers/GNU-Emacs-FAQ/diffs +send usenet/news.answers/GNU-Emacs-FAQ/part1 +send usenet/news.answers/GNU-Emacs-FAQ/part2 +send usenet/news.answers/GNU-Emacs-FAQ/part3 +send usenet/news.answers/GNU-Emacs-FAQ/part4 +send usenet/news.answers/GNU-Emacs-FAQ/part5 +@end example + +For more information, send email to @email{mail-server@@rtfm.mit.edu} +with "help" and "index" in the body on separate lines. + +@item +As the very last resort, you can e-mail a request to +@email{emacs-faq@@lerner.co.il}. Don't do this unless you have made a +serious effort to obtain the FAQ list via one of the methods listed +above. + +@end itemize + +@c ------------------------------------------------------------ +@node Status of Emacs, Common requests, Getting help, Top +@chapter Status of Emacs +@cindex Status of Emacs + +This section gives you basic information about Emacs, including its +latest version status. + +@menu +* Origin of the term Emacs:: +* Latest version of Emacs:: +* New in Emacs 20:: +@end menu + +@node Origin of the term Emacs, Latest version of Emacs, Status of Emacs, Status of Emacs +@section Where does the name "Emacs" come from? +@cindex Origin of the term "Emacs" +@cindex Emacs name origin +@cindex TECO +@cindex Original version of Emacs + +Emacs originally was an acronym for Editor MACroS. RMS says he "picked +the name Emacs because @key{E} was not in use as an abbreviation on ITS at +the time." The first Emacs was a set of macros written in 1976 at MIT +by RMS for the editor TECO (Text Editor and COrrector, originally Tape +Editor and COrrector) under ITS on a PDP-10. RMS had already extended +TECO with a "real-time" full screen mode with reprogrammable keys. +Emacs was started by @email{gls@@east.sun.com, Guy Steele} as a project +to unify the many divergent TECO command sets and key bindings at MIT, +and completed by RMS. + +Many people have said that TECO code looks a lot like line noise; you +can read more at @uref{news:alt.lang.teco}. Someone has written a TECO +implementation in Emacs Lisp (to find it, @ref{Packages that do not come +with Emacs}); it would be an interesting project to run the original +TECO Emacs inside of Emacs. + +For some not-so-serious alternative reasons for Emacs to have that +name, check out @file{etc/JOKES} (@pxref{Filename conventions}). + +@node Latest version of Emacs, New in Emacs 20, Origin of the term Emacs, Status of Emacs +@section What is the latest version of Emacs? +@cindex Version, latest +@cindex Latest version + +Emacs 20.4 is the current version as of this writing. + +@node New in Emacs 20, , Latest version of Emacs, Status of Emacs +@section What is different about Emacs 20? +@cindex Differences between Emacs 19 and Emacs 20 +@cindex Emacs 20, new features in +@cindex Recently introduced features + +To find out what has changed in recent versions, type @kbd{C-h n} +(@kbd{M-x view-emacs-news}). The oldest changes are at the bottom of +the file, so you might want to read it starting there, rather than at +the top. + +The differences between Emacs versions 18 and 19 was rather dramatic; +the introduction of frames, faces, and colors on windowing systems was +obvious to even the most casual user. + +There are differences between Emacs versions 19 and 20 as well, but many +are more subtle or harder to find. Among the changes are the inclusion +of MULE code for languages that use non-Latin characters, the "customize" +facility for modifying variables without having to use Lisp, and +automatic conversion of files from Macintosh, Microsoft, and Unix +platforms. + +A number of older Lisp packages, such as Gnus, Supercite and the +calendar/diary, have been updated and enhanced to work with Emacs 20, +and are now included with the standard distribution. + + +@c ------------------------------------------------------------ +@node Common requests, Bugs and problems, Status of Emacs, Top +@chapter Common requests +@cindex Common requests + +@menu +* Setting up a customization file:: +* Debugging a customization file:: +* Displaying the current line or column:: +* Displaying the current filename in the titlebar:: +* Turning on abbrevs by default:: +* Turning on auto-fill by default:: +* Associating modes with files:: +* Working with unprintable characters:: +* Highlighting a region:: +* Controlling case sensitivity:: +* Wrapping words automatically:: +* Spell-checkers:: +* Checking TeX and *roff documents:: +* Changing load-path:: +* Using an already running Emacs process:: +* Compiler error messages:: +* Indenting switch statements:: +* Horizontal scrolling:: +* Overwrite mode:: +* Turning off beeping:: +* Turning the volume down:: +* Automatic indentation:: +* Matching parentheses:: +* Hiding #ifdef lines:: +* Repeating commands:: +* Valid X resources:: +* Evaluating Emacs Lisp code:: +* Changing the length of a Tab:: +* Inserting > at the beginning of each line:: +* Underlining paragraphs:: +* Repeating a command as many times as possible:: +* Forcing the cursor to remain in the same column:: +* Forcing Emacs to iconify itself:: +* Using regular expressions:: +* Replacing text across multiple files:: +* Documentation for etags:: +* Disabling backups:: +* Disabling auto-save-mode:: +* Modifying pull-down menus:: +* Deleting menus and menu options:: +* Turning on syntax highlighting:: +* Scrolling only one line:: +* Replacing highlighted text:: +* Editing MS-DOS files:: +* Filling paragraphs with a single space:: +@end menu + +@node Setting up a customization file, Debugging a customization file, Common requests, Common requests +@section How do I set up a @file{.emacs} file properly? +@cindex @file{.emacs} file, setting up +@cindex Init file, setting up +@cindex Customization file, setting up + +@inforef{Init File, Init File, emacs} + +In general, new Emacs users should not have @file{.emacs} files, because +it causes confusing non-standard behavior. Then they send questions to +@email{help-gnu-emacs@@gnu.org} asking why Emacs isn't behaving as +documented. + +Emacs 20 includes the new @code{customize} facility, which can be +invoked using @kbd{M-x customize @key{RET}}. This allows users who are +unfamiliar with Emacs Lisp to modify their @file{.emacs} files in a +relatively straightforward way, using menus rather than Lisp code. Not +all packages support Customize as of this writing, but the number is +growing fairly steadily. + +While @code{customize} might indeed make it easier to configure Emacs, +consider taking a bit of time to learn Emacs Lisp and modifying your +@file{.emacs} directly. Simple configuration options are described +rather completely in @inforef{Init File, Init File, emacs}, for users +interested in performing frequently requested, basic tasks. + +@node Debugging a customization file, Displaying the current line or column, Setting up a customization file, Common requests +@section How do I debug a @file{.emacs} file? +@cindex Debugging @file{.emacs} file +@cindex @file{.emacs} debugging +@cindex Init file debugging +@cindex @samp{-debug-init} + +Start Emacs with the @samp{-debug-init} command-line option. This +enables the Emacs Lisp debugger before evaluating your @file{.emacs} +file, and places you in the debugger if something goes wrong. The top +line in the @file{trace-back} buffer will be the error message, and the +second or third line of that buffer will display the Lisp code from your +@file{.emacs} file that caused the problem. + +You can also evaluate an individual function or argument to a function +in your @file{.emacs} file by moving the cursor to the end of the +function or argument and typing @kbd{C-x C-e} (@kbd{M-x +eval-last-sexp}). + +Use @kbd{C-h v} (@kbd{M-x describe-variable}) to check the value of +variables which you are trying to set or use. + +@node Displaying the current line or column, Displaying the current filename in the titlebar, Debugging a customization file, Common requests +@section How do I make Emacs display the current line (or column) number? +@cindex @code{line-number-mode} +@cindex Displaying the current line or column +@cindex Line number, displaying the current +@cindex Column, displaying the current +@cindex @code{mode-line-format} + +To have Emacs automatically display the current line number of the point +in the mode line, do @kbd{M-x line-number-mode}. You can also put the +form + +@lisp +(setq line-number-mode t) +@end lisp + +in your @file{.emacs} file to achieve this whenever you start Emacs. +Note that Emacs will not display the line number if the buffer is larger +than the value of the variable @code{line-number-display-limit}. + +As of Emacs 20, you can similarly display the current column with +@kbd{M-x column-number-mode}, or by putting the form + +@lisp +(setq column-number-mode t) +@end lisp + +in your @file{.emacs} file. + +The "%c" format specifier in the variable @code{mode-line-format} will +insert the current column's value into the mode line. See the +documentation for @code{mode-line-format} (using @kbd{C-h v +mode-line-format @key{RET}}) for more information on how to set and use +this variable. + +Users of all Emacs versions can display the current column using +@email{abraham@@iesd.auc.dk, Per Abrahamsen's} "column" package. +@xref{Packages that do not come with Emacs} for instructions on how to +get it. + +None of the vi emulation modes provide the "set number" capability of vi +(as far as we know). + +@node Displaying the current filename in the titlebar, Turning on abbrevs by default, Displaying the current line or column, Common requests +@section How can I modify the titlebar to contain the current filename? +@cindex Titlebar, displaying the current filename in +@cindex Filename, displaying in the titlebar +@cindex @code{frame-title-format} + +The contains of an Emacs frame's titlebar is controlled by the variable +@code{frame-title-format}, which has the same structure as the variable +@code{mode-line-format}. (Use @kbd{C-h v} or @kbd{M-x +describe-variable} to get information about one or both of these +variables.) + +By default, the titlebar for a frame does contain the name of the buffer +currently being visited, except if there is a single frame. In such a +case, the titlebar contains the name of the user and the machine at +which Emacs was invoked. This is done by setting +@code{frame-title-format} to the default value of + +@lisp +(multiple-frames "%b" ("" invocation-name "@@" system-name)) +@end lisp + +To modify the behavior such that frame titlebars contain the buffer's +name regardless of the number of existing frames, include the following +in your @file{.emacs}: + +@lisp +(setq frame-title-format "%b") +@end lisp + +@node Turning on abbrevs by default, Turning on auto-fill by default, Displaying the current filename in the titlebar, Common requests +@section How do I turn on abbrevs by default just in mode XXX? +@cindex Abbrevs, turning on by default + +Put this in your @file{.emacs} file: + +@lisp +(condition-case () + (quietly-read-abbrev-file) + (file-error nil)) + +(add-hook 'XXX-mode-hook + (function + (lambda () + (setq abbrev-mode t)))) +@end lisp + +@node Turning on auto-fill by default, Associating modes with files, Turning on abbrevs by default, Common requests +@section How do I turn on @code{auto-fill-mode} by default? +@cindex @code{auto-fill-mode}, activating automatically +@cindex Filling automatically +@cindex Automatic entry to @code{auto-fill-mode} + +To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x +auto-fill-mode}. + +To turn it on for every buffer in a certain mode, you must use the hook +for that mode. For example, to turn on @code{auto-fill} mode for all +text buffers, including the following in your @file{.emacs} file: + +@lisp +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end lisp + +If you want @code{auto-fill} mode on in all major modes, do this: + +@lisp +(setq-default auto-fill-function 'do-auto-fill) +@end lisp + +@node Associating modes with files, Working with unprintable characters, Turning on auto-fill by default, Common requests +@section How do I make Emacs use a certain major mode for certain files? +@cindex Associating modes with files +@cindex File extensions and modes +@cindex @code{auto-mode-alist}, modifying +@cindex Modes, associating with file extensions + +If you want to use XXX mode for all files which end with the extension +@samp{.YYY}, this will do it for you: + +@lisp +(setq auto-mode-alist (cons '("\\.YYY\\'" . XXX-mode) auto-mode-alist)) +@end lisp + +Otherwise put this somewhere in the first line of any file you want to +edit in XXX mode (in the second line, if the first line begins with +@samp{#!}): + +@example +-*-XXX-*- +@end example + +Beginning with Emacs 19, the variable @code{interpreter-mode-alist} +specifies which mode to use when loading a shell script. (Emacs +determines which interpreter you're using by examining the first line of +the file.) This feature only applies when the file name doesn't +indicate which mode to use. Use @kbd{C-h v} (or @kbd{M-x +describe-variable}) on @code{interpreter-mode-alist} to learn more. + +@node Working with unprintable characters, Highlighting a region, Associating modes with files, Common requests +@section How do I search for, delete, or replace unprintable (eight-bit or control) characters? +@cindex Unprintable characters, working with +@cindex Working with unprintable characters +@cindex Control characters, working with +@cindex Eight-bit characters, working with +@cindex Searching for unprintable characters +@cindex Regexps and unprintable characters + +To search for a single character that appears in the buffer as, for +example, @samp{\237}, you can type @kbd{C-s C-q 2 3 7}. (This assumes +the value of @code{search-quote-char} is 17 (i.e., @kbd{C-q}).) +Searching for ALL unprintable characters is best done with a regular +expression ("regexp") search. The easiest regexp to use for the +unprintable chars is the complement of the regexp for the printable +chars. + +@itemize @bullet + +@item +Regexp for the printable chars: @samp{[\t\n\r\f -~]} + +@item +Regexp for the unprintable chars: @samp{[^\t\n\r\f -~]} + +@end itemize + +To type these special characters in an interactive argument to +@code{isearch-forward-regexp} or @code{re-search-forward}, you need to +use @kbd{C-q}. (@samp{\t}, @samp{\n}, @samp{\r}, and @samp{\f} stand +respectively for @key{TAB}, @key{LFD}, @key{RET}, and @kbd{C-l}.) So, +to search for unprintable characters using @code{re-search-forward}: + +@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}} + +Using @code{isearch-forward-regexp}: + +@kbd{M-C-s [^ @key{TAB} @key{RET} C-q @key{RET} C-q C-l @key{SPC} -~]} + +To delete all unprintable characters, simply use replace-regexp: + +@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}} + +Replacing is similar to the above. To replace all unprintable +characters with a colon, use: + +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} + +@itemize @bullet + +@item You don't need to quote @key{TAB} with either isearch or typing +something in the minibuffer. + +@end itemize + +@node Highlighting a region, Controlling case sensitivity, Working with unprintable characters, Common requests +@section How can I highlight a region of text in Emacs? +@cindex Highlighting text +@cindex Text, highlighting +@cindex @code{transient-mark-mode} +@cindex Region, highlighting a + +If you are using a windowing system such as X, you can cause the region +to be highlighted when the mark is active by including + +@lisp +(transient-mark-mode t) +@end lisp + +in your @file{.emacs} file. (Also see @xref{Turning on syntax highlighting}.) + +@node Controlling case sensitivity, Wrapping words automatically, Highlighting a region, Common requests +@section How do I control Emacs's case-sensitivity when searching/replacing? +@cindex @code{case-fold-search} +@cindex Case sensitivity of searches +@cindex @code{case-replace} +@cindex Searching without case sensitivity +@cindex Ignoring case in searches + +For searching, the value of the variable @code{case-fold-search} +determines whether they are case sensitive: + +@lisp +(setq case-fold-search nil) ; make searches case sensitive +(setq case-fold-search t) ; make searches case insensitive +@end lisp + +Similarly, for replacing the variable @code{case-replace} determines +whether replacements preserve case. + +To change the case sensitivity just for one major mode, use the major +mode's hook. For example: + +@lisp +(add-hook 'XXX-mode-hook + (function + (lambda () + (setq case-fold-search nil)))) +@end lisp + +@node Wrapping words automatically, Spell-checkers, Controlling case sensitivity, Common requests +@section How do I make Emacs wrap words for me? +@cindex Wrapping word automatically +@cindex @code{auto-fill-mode}, introduction to +@cindex Maximum line width, default value +@cindex @code{fill-column}, default value + +Use @code{auto-fill-mode}, activated by typing @kbd{M-x auto-fill-mode}. +The default maximum line width is 70, determined by the variable +@code{fill-column}. To learn how to turn this on automatically, @pxref{Turning on auto-fill by default}. + +@node Spell-checkers, Checking TeX and *roff documents, Wrapping words automatically, Common requests +@section Where can I get a better spelling checker for Emacs? +@cindex Checking spelling +@cindex Spelling, checking text documents + +Use Ispell. @xref{Ispell}. + +@node Checking TeX and *roff documents, Changing load-path, Spell-checkers, Common requests +@section How can I spell-check @TeX{} or *roff documents? +@cindex Spelling, checking @TeX{} documents +@cindex @TeX{} documents, checking spelling in + +Use Ispell. Ispell can handle @TeX{} and *roff documents. +@xref{Ispell}. + +@node Changing load-path, Using an already running Emacs process, Checking TeX and *roff documents, Common requests +@section How do I change @code{load-path}? +@cindex @code{load-path}, modifying +@cindex Modifying @code{load-path} +@cindex Adding to @code{load-path} + +In general, you should only add to the @code{load-path}. You can add +directory @var{/XXX/YYY} to the load path like this: + +@lisp +(setq load-path (cons "/XXX/YYY/" load-path)) +@end lisp + +To do this relative to your home directory: + +@lisp +(setq load-path (cons "~/YYY/" load-path) +@end lisp + +@node Using an already running Emacs process, Compiler error messages, Changing load-path, Common requests +@section How do I use an already running Emacs from another window? +@cindex @code{emacsclient} +@cindex Emacs server functions +@cindex Using an existing Emacs process + +@code{emacsclient}, which comes with Emacs, is for editing a file using +an already running Emacs rather than starting up a new Emacs. It does +this by sending a request to the already running Emacs, which must be +expecting the request. + +@itemize @bullet + +@item +Setup + +Emacs must have executed the @code{server-start} function for +@samp{emacsclient} to work. This can be done either by a command line +option: + +@example +emacs -f server-start +@end example + +or by invoking @code{server-start} from @file{.emacs}: + +@lisp +(if (some conditions are met) (server-start)) +@end lisp + +When this is done, Emacs starts a subprocess running a program called +@samp{server}. @samp{server} creates a Unix domain socket, named +@file{.emacs_server}, in the user's home directory. + +To get your news reader, mail reader, etc., to invoke +@samp{emacsclient}, try setting the environment variable @code{EDITOR} +(or sometimes @code{VISUAL}) to the value @samp{emacsclient}. You may +have to specify the full pathname of the @samp{emacsclient} program +instead. Examples: + +@example +# csh commands: +setenv EDITOR emacsclient + +# using full pathname +setenv EDITOR /usr/local/emacs/etc/emacsclient + +# sh command: +EDITOR=emacsclient ; export EDITOR +@end example + +@item Normal use + +When @samp{emacsclient} is run, it connects to the @file{.emacs_server} +socket and passes its command line options to @samp{server}. When +@samp{server} receives these requests, it sends this information on the +the Emacs process, which at the next opportunity will visit the files +specified. (Line numbers can be specified just like with Emacs.) The +user will have to switch to the Emacs window by hand. When the user is +done editing a file, the user can type @kbd{C-x #} (or @kbd{M-x +server-edit}) to indicate this. If there is another buffer requested by +emacsclient, Emacs will switch to it; otherwise emacsclient will exit, +signaling the calling program to continue. + +@samp{emacsclient} and @samp{server} must be running on machines which +share the same filesystem for this to work. The pathnames that +@samp{emacsclient} specifies should be correct for the filesystem that +the Emacs process sees. The Emacs process should not be suspended at +the time @samp{emacsclient} is invoked. @samp{emacsclient} should +either be invoked from another X window or from a shell window inside +Emacs itself. + +There is an enhanced version of @samp{emacsclient}/server called +@samp{gnuserv} by @email{ange@@hplb.hpl.hp.com, Andy Norman} which is +available in the Emacs Lisp Archive (@pxref{Packages that do not come +with Emacs}). @samp{gnuserv} uses Internet domain sockets, so it can +work across most network connections. It also supports the execution of +arbitrary Emacs Lisp forms and does not require the client program to +wait for completion. + +The alpha version of an enhanced @samp{gnuserv} is available +at + +@uref{ftp://ftp.wellfleet.com/netman/psmith/emacs/gnuserv-2.1alpha.tar.gz} + +@end itemize + +@node Compiler error messages, Indenting switch statements, Using an already running Emacs process, Common requests +@section How do I make Emacs recognize my compiler's funny error messages? +@cindex Compiler error messages, recognizing +@cindex Recognizing non-standard compiler errors +@cindex Regexps for recognizing compiler errors +@cindex Errors, recognizing compiler + +The variable @code{compilation-error-regexp-alist} helps control how +Emacs parses your compiler output. It is a list of triples of the form: +@var{(REGEXP FILE-IDX LINE-IDX)}, where @var{REGEXP}, @var{FILE-IDX} and +@var{LINE-IDX} are strings. To help determine what the constituent +elements should be, load @file{compile.el} and then use @kbd{C-h v +compilation-error-regexp-alist @key{RET}} + +to see the current value. A good idea is to look at @file{compile.el} +itself as the comments included for this variable are quite useful --- +the regular expressions required for your compiler's output may be very +close to one already provided. Once you have determined the proper +regexps, use the following to inform Emacs of your changes: + +@lisp +(setq compilation-error-regexp-alist + (cons '(REGEXP FILE-IDX LINE-IDX) + compilation-error-regexp-alist)) +@end lisp + +@node Indenting switch statements, Horizontal scrolling, Compiler error messages, Common requests +@section How do I change the indentation for @code{switch}? +@cindex @code{switch}, indenting +@cindex Indenting of @code{switch} + +Many people want to indent their @code{switch} statements like this: + +@example +f() +@{ + switch(x) @{ + case A: + x1; + break; + case B: + x2; + break; + default: + x3; + @} +@} +@end example + +The solution at first appears to be: set @code{c-indent-level} to 4 and +@code{c-label-offset} to -2. However, this will give you an indentation +spacing of four instead of two. + +The solution is to use @code{cc-mode} (the default mode for C +programming in Emacs 20) and add the following line: + +@lisp +(c-set-offset 'case-label '+) +@end lisp + +There appears to be no way to do this with the old @code{c-mode}. + +@node Horizontal scrolling, Overwrite mode, Indenting switch statements, Common requests +@section How can I make Emacs automatically scroll horizontally? +@cindex @code{hscroll-mode} +@cindex Horizontal scrolling +@cindex Scrolling horizontally + +Use @code{hscroll-mode}, included in Emacs 20. Here is some information from +the documentation, available by typing @kbd{C-h f hscroll-mode @key{RET}}: + +Automatically scroll horizontally when the point moves off the +left or right edge of the window. + +@itemize @minus + +@item Type @kbd{M-x hscroll-mode} to enable it in the current buffer. +@item Type @kbd{M-x hscroll-global-mode} to enable it in every buffer. +@item @code{turn-on-hscroll} is useful in mode hooks as in: + +@lisp +(add-hook 'text-mode-hook 'turn-on-hscroll) +@end lisp + +@item @code{hscroll-margin} controls how close the cursor can get to the +edge of the window. + +@item @code{hscroll-step-percent} controls how far to jump once we decide to do so. + +@end itemize + +@node Overwrite mode, Turning off beeping, Horizontal scrolling, Common requests +@section How do I make Emacs "typeover" or "overwrite" instead of inserting? +@cindex @key{Insert} +@cindex @code{overwrite-mode} +@cindex Overwriting existing text +@cindex Toggling @code{overwrite-mode} + +@kbd{M-x overwrite-mode} (a minor mode). This toggles +@code{overwrite-mode} on and off, so exiting from @code{overwrite-mode} +is as easy as another @kbd{M-x overwrite-mode}. + +On some workstations, @key{Insert} toggles @code{overwrite-mode} on and off. + +@node Turning off beeping, Turning the volume down, Overwrite mode, Common requests +@section How do I stop Emacs from beeping on a terminal? +@cindex Beeping, turning off +@cindex Visible bell +@cindex Bell, visible + +@email{martin@@cc.gatech.edu, Martin R. Frank} writes: + +Tell Emacs to use the "visible bell" instead of the audible bell, and +set the visible bell to nothing. + +That is, put the following in your @code{TERMCAP} environment variable +(assuming you have one): + +@example +... :vb=: ... +@end example + +And evaluate the following Lisp form: + +@example +(setq visible-bell t) +@end example + +@node Turning the volume down, Automatic indentation, Turning off beeping, Common requests +@section How do I turn down the bell volume in Emacs running under X Windows? +@cindex Bell, volume of +@cindex Volume of bell + +You can adjust the bell volume and duration for all programs with the +shell command @file{xset}. + +Invoking @file{xset} without any arguments produces some basic information, +including the following: + +@example +usage: xset [-display host:dpy] option ... + To turn bell off: + -b b off b 0 + To set bell volume, pitch and duration: + b [vol [pitch [dur]]] b on +@end example + +@node Automatic indentation, Matching parentheses, Turning the volume down, Common requests +@section How do I tell Emacs to automatically indent a new line to the indentation of the previous line? +@cindex Indenting new lines +@cindex New lines, indenting of +@cindex Previous line, indenting according to + +Such behavior is automatic in Emacs 20. From the NEWS file for Emacs +20.2: + +@example +** In Text mode, now only blank lines separate paragraphs. This makes +it possible to get the full benefit of Adaptive Fill mode in Text mode, +and other modes derived from it (such as Mail mode). @key{TAB} in Text +mode now runs the command @code{indent-relative}; this makes a practical +difference only when you use indented paragraphs. + +As a result, the old Indented Text mode is now identical to Text mode, +and is an alias for it. + +If you want spaces at the beginning of a line to start a paragraph, use +the new mode, Paragraph Indent Text mode. +@end example + +If you have @code{auto-fill-mode} on (@pxref{Turning on auto-fill by +default}), you can tell Emacs to prefix every line with a certain +character sequence, the "fill prefix." Type the prefix at the beginning +of a line, position point after it, and then type @kbd{C-x .} +(@code{set-fill-prefix}) to set the fill prefix. Thereafter, +auto-filling will automatically put the fill prefix at the beginning of +new lines, and @kbd{M-q} (@code{fill-paragraph}) will maintain any fill +prefix when refilling the paragraph. + +If you have paragraphs with different levels of indentation, you will +have to set the fill prefix to the correct value each time you move to a +new paragraph. To avoid this hassle, try one of the many packages +available from the Emacs Lisp Archive (@pxref{Packages that do not come +with Emacs}.) Look up "fill" and "indent" in the Lisp Code Directory +for guidance. + +@node Matching parentheses, Hiding #ifdef lines, Automatic indentation, Common requests +@section How do I show which parenthesis matches the one I'm looking at? +@cindex Parentheses, matching +@cindex @file{paren.el} +@cindex Highlighting matching parentheses +@cindex Pairs of parentheses, highlighting +@cindex Matching parentheses + +As of version 19, Emacs comes with @file{paren.el}, which (when loaded) +will automatically highlight matching parentheses whenever point (i.e., +the cursor) is located over one. To load @file{paren.el} automatically, +include the line + +@lisp +(require 'paren) +@end lisp + +in your @file{.emacs} file. @email{shutkoa@@ugsolutions.com, Alan Shutko} +reports that as of version 20.1, you must also call @code{show-paren-mode} in +your @file{.emacs} file: + +@lisp +(show-paren-mode 1) +@end lisp + +@code{customize} will let you turn on @code{show-paren-mode}. Use +@kbd{M-x customize-group @key{RET} paren-showing @key{RET}}. From +within @code{customize}, you can also go directly to the "paren-showing" +group. + + Alternatives to paren include: + +@itemize @bullet + +@item +If you're looking at a right parenthesis (or brace or bracket) you can +delete it and reinsert it. Emacs will blink the cursor on the matching +parenthesis. + +@item +@kbd{M-C-f} (@code{forward-sexp}) and @kbd{M-C-b} (@code{backward-sexp}) +will skip over one set of balanced parentheses, so you can see which +parentheses match. (You can train it to skip over balanced brackets +and braces at the same time by modifying the syntax @key{TAB}le.) + +@item +Here is some Emacs Lisp that will make the @key{%} key show the matching +parenthesis, like in vi. In addition, if the cursor isn't over a +parenthesis, it simply inserts a % like normal. + +@lisp +;; By an unknown contributor + +(global-set-key "%" 'match-paren) + +(defun match-paren (arg) + "Go to the matching paren if on a paren; otherwise insert %." + (interactive "p") + (cond ((looking-at "\\s\(") (forward-list 1) (backward-char 1)) + ((looking-at "\\s\)") (forward-char 1) (backward-list 1)) + (t (self-insert-command (or arg 1))))) +@end lisp + +@end itemize + +@node Hiding #ifdef lines, Repeating commands, Matching parentheses, Common requests +@section In C mode, can I show just the lines that will be left after @code{#ifdef} commands are handled by the compiler? +@cindex @code{#ifdef}, selective display of +@cindex @code{hide-ifdef-mode} +@cindex Hiding @code{#ifdef} text +@cindex Selectively displaying @code{#ifdef} code + +@kbd{M-x hide-ifdef-mode}. (This is a minor mode.) You might also want +to try @file{cpp.el}, available at the Emacs Lisp Archive +(@pxref{Packages that do not come with Emacs}). + +@node Repeating commands, Valid X resources, Hiding #ifdef lines, Common requests +@section Is there an equivalent to the @code{.} (dot) command of vi? +@cindex Repeating commands as with vi +@cindex Command, repeat last +@cindex @code{.}, equivalent to vi command + +(@code{.} is the redo command in vi. It redoes the last insertion/deletion.) + +As of Emacs 20.3, there is indeed a @code{repeat} command (@kbd{C-x .}) +that repeats the last command. If you preface it with a prefix +argument, the prefix arg is applied to the command. + +You can also type @kbd{C-x @key{ESC} @key{ESC}} +(@code{repeat-complex-command}) to reinvoke commands that used the +minibuffer to get arguments. In @code{repeat-complex-command} you can +type @kbd{M-p} and @kbd{M-n} to scan through all the different complex +commands you've typed. + +To repeat a set of commands, use keyboard macros. (@inforef{Keyboard +Macros, Keyboard Macros, emacs}.) + +If you're really desperate for the @code{.} command, use VIPER, which comes +with Emacs, and which appears to support it. (@xref{VIPER}.) + +@node Valid X resources, Evaluating Emacs Lisp code, Repeating commands, Common requests +@section What are the valid X resource settings (i.e., stuff in .Xdefaults)? +@cindex Resources, X +@cindex X resources +@cindex Setting X resources + +@inforef{Resources X, Resources X, emacs}. + +You can also use a resource editor, such as editres (for X11R5 and +onwards), to look at the resource names for the menu bar, assuming Emacs +was compiled with the X toolkit. + +@node Evaluating Emacs Lisp code, Changing the length of a Tab, Valid X resources, Common requests +@section How do I execute ("evaluate") a piece of Emacs Lisp code? +@cindex Evaluating Lisp code +@cindex Lisp forms, evaluating + +There are a number of ways to execute ("evaluate," in Lisp lingo) an +Emacs Lisp "form": + +@itemize @bullet + +@item +If you want it evaluated every time you run Emacs, put it in a file +named @file{.emacs} in your home directory. This is known as your ".emacs +file," and contains all of your personal customizations. + +@item +You can type the form in the @file{*scratch*} buffer, and then type +@key{LFD} (or @kbd{C-j}) after it. The result of evaluating the form +will be inserted in the buffer. + +@item +In @code{emacs-lisp-mode}, typing @kbd{M-C-x} evaluates a top-level form +before or around point. + +@item +Typing @kbd{C-x C-e} in any buffer evaluates the Lisp form immediately +before point and prints its value in the echo area. + +@item +Typing @kbd{M-:} or @kbd{M-x eval-expression} allows you to type a Lisp +form in the minibuffer which will be evaluated. + +@item +You can use @kbd{M-x load-file} to have Emacs evaluate all the Lisp +forms in a file. (To do this from Lisp use the function @code{load} +instead.) + +The functions @code{load-library}, @code{eval-region}, +@code{eval-current-buffer}, @code{require}, and @code{autoload} are also +useful; @pxref{Emacs Lisp documentation} if you want to learn more about +them. + +@end itemize + +@node Changing the length of a Tab, Inserting > at the beginning of each line, Evaluating Emacs Lisp code, Common requests +@section How do I change Emacs's idea of the @key{TAB} character's length? +@cindex Tab length +@cindex Length of tab character +@cindex @code{default-tab-width} + +Set the variable @code{default-tab-width}. For example, to set +@key{TAB} stops every 10 characters, insert the following in your +@file{.emacs} file: + +@lisp +(setq default-tab-width 10) +@end lisp + +Do not confuse variable @code{tab-width} with variable +@code{tab-stop-list}. The former is used for the display of literal +@key{TAB} characters. The latter controls what characters are inserted +when you press the @key{TAB} character in certain modes. + +@node Inserting > at the beginning of each line, Underlining paragraphs, Changing the length of a Tab, Common requests +@section How do I insert @samp{>} at the beginning of every line? +@cindex Prefix character, inserting in mail/news replies +@cindex Replies to mail/news, inserting a prefix character +@cindex @code{mail-yank-prefix} +@cindex Mail replies, inserting a prefix character +@cindex News replies, inserting a prefix character + +To do this to an entire buffer, type @kbd{M-< M-x replace-regexp +@key{RET} ^ @key{RET} > @key{RET}}. + +To do this to a region, use @code{string-rectangle} (@kbd{C-x r t}). +Set the mark (@kbd{C-@key{SPC}}) at the beginning of the first line you +want to prefix, move the cursor to last line to be prefixed, and type +@kbd{C-x r t > @key{RET}}. To do this for the whole buffer, type +@kbd{C-x h C-x r t > @key{RET}}. + +If you are trying to prefix a yanked mail message with @samp{>}, you +might want to set the variable @code{mail-yank-prefix}. Better yet, get +the Supercite package (@pxref{Supercite}), which provides flexible +citation for yanked mail and news messages. @xref{Changing the included +text prefix} for additional information. + +@node Underlining paragraphs, Repeating a command as many times as possible, Inserting > at the beginning of each line, Common requests +@section How do I insert "_^H" before each character in a region to get an underlined paragraph? +@cindex Underlining a region of text +@cindex @code{underline-region} + +@kbd{M-x underline-region}. + +@node Repeating a command as many times as possible, Forcing the cursor to remain in the same column, Underlining paragraphs, Common requests +@section How do I repeat a command as many times as possible? +@cindex Repeating commands +@cindex Commands, repeating + +Use @kbd{C-x (} and @kbd{C-x )} to make a keyboard macro that invokes +the command and then type @kbd{M-0 C-x e}. + +Any messages your command prints in the echo area will be suppressed. + +@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 +@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? +@cindex @code{picture-mode} +@cindex Remaining in the same column, regardless of contents +@cindex Vertical movement in empty documents + +@kbd{M-x picture-mode}. + +@node Forcing Emacs to iconify itself, Using regular expressions, Forcing the cursor to remain in the same column, Common requests +@section How do I tell Emacs to iconify itself? +@cindex Iconification under X Windows +@cindex X Windows and iconification +@cindex Suspending Emacs + +@kbd{C-z} iconifies Emacs when running under X Windows and suspends Emacs +otherwise. @inforef{Misc X, Misc X, emacs}. + +@node Using regular expressions, Replacing text across multiple files, Forcing Emacs to iconify itself, Common requests +@section How do I use regexps (regular expressions) in Emacs? +@cindex Regexps +@cindex Regular expressions +@cindex Differences between Unix and Emacs regexps +@cindex Unix regeps, differences from Emacs +@cindex Text strings, putting regexps in + +@inforef{Regexps, Regexps, emacs}. + +The "or" operator is @samp{\|}, not @samp{|}, and the grouping operators +are @samp{\(} and @samp{\)}. Also, the string syntax for a backslash is +@samp{\\}. To specify a regular expression like @samp{xxx\(foo\|bar\)} +in a Lisp string, use @samp{xxx\\(foo\\|bar\\)}. + +Notice the doubled backslashes! + +@itemize @bullet + +@item Unlike in Unix @file{grep}, @file{sed}, etc., a complement +character set (@samp{[^...]}) can match a newline character (@key{LFD} +aka @kbd{C-j} aka @samp{\n}), unless newline is mentioned as one of the +characters not to match. + +@item The character syntax regexps (e.g., @samp{\sw}) are not +meaningful inside character set regexps (e.g., @samp{[aeiou]}). (This +is actually typical for regexp syntax.) + +@end itemize + +@node Replacing text across multiple files, Documentation for etags, Using regular expressions, Common requests +@section How do I perform a replace operation across more than one file? +@cindex Replacing strings across files +@cindex Multiple files, replacing across +@cindex Files, replacing strings across multiple + +The "tags" feature of Emacs includes the command +@code{tags-query-replace} which performs a query-replace across all the +files mentioned in the TAGS file. @inforef{Tags Search, Tags Search, +emacs}. + +As of Emacs 19.29, Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x +d}) supports the command @code{dired-do-query-replace}, which allows +users to replace regular expressions in multiple files. + +@node Documentation for etags, Disabling backups, Replacing text across multiple files, Common requests +@section Where is the documentation for @file{etags}? +@cindex Documentation for @file{etags} +@cindex @file{etags}, documentation for + +The @file{etags} man page should be in the same place as the +@file{emacs} man page. + +Quick command-line switch descriptions are also available. For example, +@samp{etags -H}. + +@node Disabling backups, Disabling auto-save-mode, Documentation for etags, Common requests +@section How do I disable backup files? +@cindex Backups, disabling +@cindex Disabling backups + +You probably don't want to do this, since backups are useful. + +To avoid seeing backup files (and other "uninteresting" files) in Dired, +load dired-x by adding the following to your @file{.emacs} file: + +@lisp +(add-hook 'dired-load-hook + (function (lambda () + (load "dired-x")))) +@end lisp + +With dired-x loaded, @kbd{M-o} toggles omitting in each dired buffer. +You can make omitting the default for new dired buffers by putting the +following in your @file{.emacs}: + +@lisp +(setq initial-dired-omit-files-p t) +@end lisp + +If you're tired of seeing backup files whenever you do an "ls" at the +Unix shell, try GNU ls with the "-B" option. GNU ls is part of the GNU +fileutils package, available at mirrors of @samp{ftp.gnu.org} (@pxref{Current GNU distributions} ). + +To disable or change how backups are made, see "Backup Names" in the +on-line manual. + +@node Disabling auto-save-mode, Modifying pull-down menus, Disabling backups, Common requests +@section How do I disable @code{auto-save-mode}? +@cindex Disabling @code{auto-save-mode} +@cindex Auto-saving +@cindex Saving at frequent intervals + +You probably don't want to do this, since auto-saving is useful, +especially when Emacs or your computer crashes while you are editing a +document. + +Instead, you might want to change the variable +@code{auto-save-interval}, which specifies how many keystrokes Emacs +waits before auto-saving. Increasing this value forces Emacs to wait +longer between auto-saves, which might annoy you less. + +You might also want to look into Sebastian Kremer's @code{auto-save} +package, available from the Lisp Code Archive (@pxref{Packages that do not come +with Emacs}). This +package also allows you to place all auto-save files in one directory, +such as @file{/tmp}. + +To disable or change how @code{auto-save-mode} works, see "Auto Save" in the +on-line manual. + +@node Modifying pull-down menus, Deleting menus and menu options, Disabling auto-save-mode, Common requests +@section How can I create or modify new pull-down menu options? +@cindex Pull-down menus, creating or modifying +@cindex Menus, creating or modifying +@cindex Creating new menu options +@cindex Modifying pull-down menus +@cindex Menus and keymaps +@cindex Keymaps and menus + +Each menu title (e.g., Buffers, File, Edit) represents a local or global +keymap. Selecting a menu title with the mouse displays that keymap's +non-nil contents in the form of a menu. + +So to add a menu option to an existing menu, all you have to do is add a +new definition to the appropriate keymap. Adding a "forward word" +command to the "Edit" menu thus requires the following Lisp code: + +@lisp +(define-key global-map + [menu-bar edit forward] + '("Forward word" . forward-word)) +@end lisp + +The first line adds the entry to the global keymap, which includes +global menu bar entries. Replacing the reference to @code{global-map} +with a local keymap would add this menu option only within a particular +mode. + +The second line describes the path from the menu-bar to the new entry. +Placing this menu entry underneath the "File" menu would mean changing +the word "edit" in the second line to "file." + +The third line is a cons cell whose first element is the title that will +be displayed, and whose second element is the function that will be +called when that menu option is invoked. + +To add a new menu, rather than a new option to an existing menu, we must +define an entirely new keymap: + +@lisp +(define-key global-map [menu-bar words] + (cons "Words" (make-sparse-keymap "Words"))) +@end lisp + +The above code creates a new sparse keymap, gives it the name "Words", +and attaches it to the global menu bar. Adding the "forward word" +command to this new menu would thus require the following code: + +@lisp +(define-key global-map + [menu-bar words forward] + '("Forward word" . forward-word)) +@end lisp + +Note that because of the way keymaps work, menu options are displayed +with the more recently defined items at the top. Thus if you were to +define menu options "foo", "bar", and "baz" (in that order), menu option +"baz" would appear at the top, and "foo" would be at the bottom. + +One way to avoid this problem is to use the function @code{define-key-after}, +which works the same as @code{define-key}, but lets you modify where items +appear. The following Lisp code would insert the "forward word" function +in the "edit" menu immediately following the "undo" option: + +@lisp +(define-key-after + (lookup-key global-map [menu-bar edit]) + [forward] + '("Forward word" . forward-word) + 'undo) +@end lisp + +Note how the second and third arguments to @code{define-key-after} are +different from those of @code{define-key}, and that we have added a new +(final) argument, the function after which our new key should be +defined. + +To move a menu option from one position to another, simply evaluate +@code{define-key-after} with the appropriate final argument. + +More detailed information --- and more examples of how to create and +modify menu options --- are in the Emacs Lisp Reference Manual, under +"Keymaps." (@xref{Emacs Lisp documentation} for information on this +manual.) + +@node Deleting menus and menu options, Turning on syntax highlighting, Modifying pull-down menus, Common requests +@section How do I delete menus and menu options? +@cindex Deleting menus and menu options +@cindex Menus, deleting + +The simplest way to remove a menu is to set its keymap to @samp{nil}. +For example, to delete the "Words" menu (@pxref{Modifying pull-down +menus}), use: + +@lisp +(define-key global-map [menu-bar words] nil) +@end lisp + +Similarly, removing a menu option requires redefining a keymap entry to +@code{nil}. For example, to delete the "Forward word" menu option from the +"Edit" menu (we added it in @ref{Modifying pull-down menus}), use: + +@lisp +(define-key global-map [menu-bar edit forward] nil) +@end lisp + +@node Turning on syntax highlighting, Scrolling only one line, Deleting menus and menu options, Common requests +@section How do I turn on syntax highlighting? +@cindex Syntax highlighting +@cindex @code{font-lock-mode} +@cindex Highlighting based on syntax +@cindex Colorizing text +@cindex FAQ, @code{font-lock-mode} + +@code{font-lock-mode} is the standard way to have Emacs perform syntax +highlighting. With @code{font-lock-mode} invoked, different types of +text will appear in different colors. For instance, if you turn on +@code{font-lock-mode} in a programming mode, variables will appear in one +face, keywords in a second, and comments in a third. + +Earlier versions of Emacs supported hilit19, a similar package. Use of +hilit19 is now considered non-standard, although @file{hilit19.el} comes +with the stock Emacs distribution. It is no longer maintained. + +To turn @code{font-lock-mode} on within an existing buffer, use @kbd{M-x +font-lock-mode @key{RET}}. + +To automatically invoke @code{font-lock-mode} when a particular major +mode is invoked, set the major mode's hook. For example, to fontify all +@code{c-mode} buffers, add the following to your @file{.emacs} file: + +@lisp +(add-hook 'c-mode-hook 'turn-on-font-lock) +@end lisp + +To automatically invoke @code{font-lock-mode} for all major modes, you +can turn on @code{global-font-lock-mode} by including the following line +in your @file{.emacs} file: + +@lisp +(global-font-lock-mode 1) +@end lisp + +This instructs Emacs to turn on font-lock mode in those buffers for +which a font-lock mode definition has been provided (in the variable +@code{font-lock-global-modes}). If you edit a file in +@code{pie-ala-mode}, and no font-lock definitions have been provided for +@code{pie-ala} files, then the above setting will have no effect on that +particular buffer. + +Highlighting with @code{font-lock-mode} can take quite a while, and thus +different levels of decoration are available, from slight to gaudy. To +control how decorated your buffers should become, set the value of +@code{font-lock-maximum-decoration} in your @file{.emacs} file, with a +@code{nil} value indicating default (usually minimum) decoration, and a +@code{t} value indicating the maximum decoration. For the gaudiest +possible look, then, include the line + +@lisp +(setq font-lock-maximum-decoration t) +@end lisp + +in your @file{.emacs} file. You can also set this variable such that +different modes are highlighted in a different ways; for more +information, see the documentation for +@code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x +describe-variable @key{RET}}). + +You might also want to investigate @code{fast-lock-mode} and +@code{lazy-lock-mode}, versions of @code{font-lock-mode} that speed up +highlighting. The advantage of @code{lazy-lock-mode} is that it only +fontifies buffers when certain conditions are met, such as after a +certain amount of idle time, or after you have finished scrolling +through text. See the documentation for @code{lazy-lock-mode} by typing @kbd{C-h f +@code{lazy-lock-mode}} (@kbd{M-x describe-function @key{RET} +lazy-lock-mode @key{RET}}). + +Also see the documentation for the function @code{font-lock-mode}, +available by typing @kbd{C-h f font-lock-mode} (@kbd{M-x +describe-function @key{RET} font-lock-mode @key{RET}}). + +For more information on font-lock mode, take a look at the +@code{font-lock-mode} FAQ, maintained by +@email{jari.aalto@@ntc.nokia.com, Jari Aalto} at + +@uref{ftp://cs.uta.fi/pub/ssjaaa/ema-font.gui} + +To print buffers with the faces (i.e., colors and fonts) intact, use +@kbd{M-x ps-print-buffer-with-faces} or @kbd{M-x +ps-print-region-with-faces}. + +@node Scrolling only one line, Replacing highlighted text, Turning on syntax highlighting, Common requests +@section How can I force Emacs to scroll only one line when I move past the bottom of the screen? +@cindex Scrolling only one line +@cindex Reducing the increment when scrollng + +Place the following Lisp form in your @file{.emacs} file: + +@lisp +(setq scroll-step 1) +@end lisp + +@inforef{Scrolling, Scrolling, emacs}. + +@node Replacing highlighted text, Editing MS-DOS files, Scrolling only one line, Common requests +@section How can I replace highlighted text with what I type? +@cindex @code{delete-selection-mode} +@cindex Replacing highlighted text +@cindex Highlighing and replacing text + +Use @code{delete-selection mode}, which you can start automatically by +placing the following Lisp form in your @file{.emacs} file: + +@lisp +(delete-selection-mode t) +@end lisp + +According to the documentation string for delete-selection mode (which +you can read using @kbd{M-x describe-function @key{RET} +delete-selection-mode @key{RET}}): + +@quotation +When ON, typed text replaces the selection if the selection is active. +When OFF, typed text is just inserted at point. +@end quotation + +This mode also allows you to delete (not kill) the highlighted region by +pressing @key{DEL}. + +@node Editing MS-DOS files, Filling paragraphs with a single space, Replacing highlighted text, Common requests +@section How can I edit MS-DOS files using Emacs? +@cindex Editing MS-DOS files +@cindex MS-DOS files, editing +@cindex Microsoft files, editing +@cindex Windows files, editing + +As of Emacs 20, detection and handling of MS-DOS (and Windows) files is +performed transparently. You can open MS-DOS files on a Unix system, +edit it, and save it without having to worry about the file format. + +When editing an MS-DOS style file, a backslash (@samp{\}) will appear in +the mode line. + +If you are running an earlier version of Emacs, get @code{crypt++} from +the Emacs Lisp Archive (@pxref{Packages that do not come with Emacs}). +Among other things, @code{crypt++} transparently modifies MS-DOS files +as they are loaded and saved, allowing you to ignore the different +conventions that Unix and MS-DOS have for delineating the end of a line. + +@node Filling paragraphs with a single space, , Editing MS-DOS files, Common requests +@section How can I tell Emacs to fill paragraphs with a single space after each period? +@cindex One space following periods +@cindex Single space following periods +@cindex Periods, one space following + +@email{ulm@@vsnhd1.cern.ch, Ulrich Mueller} suggests adding the +following two lines to your @file{.emacs} file: + +@lisp +(setq sentence-end "[.?!][]\"')@}]*\\($\\|[ \t]\\)[ \t\n]*") +(setq sentence-end-double-space nil) +@end lisp + +@c ------------------------------------------------------------ +@node Bugs and problems, Compiling and installing Emacs, Common requests, Top +@chapter Bugs and problems +@cindex Bugs and problems + +@menu +* Problems with very large files:: +* ^M in the shell buffer:: +* Shell process exits abnormally:: +* Termcap/Terminfo entries for Emacs:: +* Spontaneous entry into isearch-mode:: +* Problems talking to certain hosts:: +* Errors with init files:: +* Emacs ignores X resources:: +* Emacs takes a long time to visit files:: +* Editing files with $ in the name:: +* Shell mode loses the current directory:: +* Security risks with Emacs:: +* Dired claims that no file is on this line:: +@end menu + +@node Problems with very large files, ^M in the shell buffer, Bugs and problems, Bugs and problems +@section Does Emacs have problems with files larger than 8 megabytes? +@cindex Very large files, opening +@cindex Large files, opening +@cindex Opening very large files +@cindex Maximum file size +@cindex Files, maximum size + +Old versions (i.e., anything before 19.29) of Emacs had problems editing +files larger than 8 megabytes. As of version 19.29, the maximum buffer +size is at least 2^27-1, or 134,217,727 bytes. + +If you are using an older version of Emacs and cannot upgrade, you will +have to recompile. @email{lnz@@lucid.com, Leonard N. Zubkoff} suggests +putting the following two lines in @file{src/config.h} before compiling +Emacs to allow for 26-bit integers and pointers (and thus file sizes of +up to 33,554,431 bytes): + +@example +#define VALBITS 26 +#define GCTYPEBITS 5 +@end example + +This method may result in "ILLEGAL DATATYPE" and other random errors on +some machines. + +@email{daveg@@csvax.cs.caltech.edu, David Gillespie} explains how this +problems crops up; while his numbers are true only for pre-19.29 +versions of Emacs, the theory remains the same with current versions. + +@quotation +Emacs is largely written in a dialect of Lisp; Lisp is a freely-typed +language in the sense that you can put any value of any type into any +variable, or return it from a function, and so on. So each value +must carry a "tag" along with it identifying what kind of thing it is, +e.g., integer, pointer to a list, pointer to an editing buffer, and so +on. Emacs uses standard 32-bit integers for data objects, taking the +top 8 bits for the tag and the bottom 24 bits for the value. So +integers (and pointers) are somewhat restricted compared to true C +integers and pointers. +@end quotation + +@node ^M in the shell buffer, Shell process exits abnormally, Problems with very large files, Bugs and problems +@section How do I get rid of @samp{^M} or echoed commands in my shell buffer? +@cindex Shell buffer, echoed commands and @samp{^M} in +@cindex Echoed commands in @code{shell-mode} + +Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to +make them go away. If that doesn't work, you have several options: + +For tcsh, put this in your @file{.cshrc} (or @file{.tcshrc}) file: + +@example +if ($?EMACS) then + if ("$EMACS" == t) then + if ($?tcsh) unset edit + stty nl + endif +endif +@end example + +Or put this in your @file{.emacs_tcsh} file: + +@example +unset edit +stty nl +@end example + +Alternatively, use @file{csh} in your shell buffers instead of +@file{tcsh}. One way is: + +@lisp +(setq explicit-shell-file-name "/bin/csh") +@end lisp + +and another is to do this in your @file{.cshrc} (or @file{.tcshrc}) +file: + +@example +setenv ESHELL /bin/csh +@end example + +(You must start Emacs over again with the environment variable properly +set for this to take effect.) + +You can also set the @code{ESHELL} environment variable in Emacs Lisp +with the following Lisp form, + +@lisp +(setenv "ESHELL" "/bin/csh") +@end lisp + +On a related note: If your shell is echoing your input line in the shell +buffer, you might want to try the following command in your shell +start-up file: + +@example +stty -icrnl -onlcr -echo susp ^Z +@end example + +@node Shell process exits abnormally, Termcap/Terminfo entries for Emacs, ^M in the shell buffer, Bugs and problems +@section Why do I get "Process shell exited abnormally with code 1"? +@cindex Abnormal exits from @code{shell-mode} +@cindex @code{shell-mode} exits + +The most likely reason for this message is that the @samp{env} program +is not properly installed. Compile this program for your architecture, +and install it with @samp{a+x} permission in the architecture-dependent +Emacs program directory. (You can find what this directory is at your +site by inspecting the value of the variable @code{exec-directory} by +typing @kbd{C-h v exec-directory @key{RET}}.) + +You should also check for other programs named @samp{env} in your path +(e.g., SunOS has a program named @file{/usr/bin/env}). We don't +understand why this can cause a failure and don't know a general +solution for working around the problem in this case. + +The @samp{make clean} command will remove @samp{env} and other vital +programs, so be careful when using it. + +It has been reported that this sometimes happened when Emacs was started +as an X client from an xterm window (i.e., had a controlling tty) but the +xterm was later terminated. + +See also @samp{PROBLEMS} (in the top-level directory when you unpack the +Emacs source) for other possible causes of this message. + +@node Termcap/Terminfo entries for Emacs, Spontaneous entry into isearch-mode, Shell process exits abnormally, Bugs and problems +@section Where is the termcap/terminfo entry for terminal type "emacs"? +@cindex Termcap +@cindex Terminfo +@cindex Emacs entries for termcap/terminfo + +The termcap entry for terminal type @samp{emacs} is ordinarily put in +the @samp{TERMCAP} environment variable of subshells. It may help in +certain situations (e.g., using rlogin from shell buffer) to add an +entry for @samp{emacs} to the system-wide termcap file. Here is a +correct termcap entry for @samp{emacs}: + +@example +emacs:tc=unknown: +@end example + +To make a terminfo entry for "emacs", use "tic" or "captoinfo." You need +to generate @file{/usr/lib/terminfo/e/emacs}. It may work to simply copy +@file{/usr/lib/terminfo/d/dumb} to @file{/usr/lib/terminfo/e/emac}s. + +Having a termcap/terminfo entry will not enable the use of full screen +programs in shell buffers. Use @kbd{M-x terminal-emulator} for that +instead. + +A workaround to the problem of missing termcap/terminfo entries is to +change terminal type "emacs" to type "dumb" or "unknown" in your shell +start up file. "csh" users could put this in their .cshrc files: + +@example +if ("$term" == emacs) set term=dumb +@end example + +@node Spontaneous entry into isearch-mode, Problems talking to certain hosts, Termcap/Terminfo entries for Emacs, Bugs and problems +@section Why does Emacs spontaneously start displaying "I-search:" and beeping? +@cindex Spontaneous entry into isearch-mode +@cindex isearch-mode, spontaneous entry into +@cindex Beeping without obvious reason + +Your terminal (or something between your terminal and the computer) is +sending @kbd{C-s} and @kbd{C-q} for flow control, and Emacs is receiving +these characters and interpreting them as commands. (The @kbd{C-s} +character normally invokes the @code{isearch-forward} command.) For +possible solutions, @pxref{Handling C-s and C-q with flow control}. + +@node Problems talking to certain hosts, Errors with init files, Spontaneous entry into isearch-mode, Bugs and problems +@section Why can't Emacs talk to certain hosts (or certain hostnames)? +@cindex Hosts, Emacs cannot talk to +@cindex @code{gethostbyname}, problematic version + +The problem may be that Emacs is linked with a wimpier version of +@code{gethostbyname} than the rest of the programs on the machine. This +is often manifested as a message on startup of "X server not responding. +Check your @samp{DISPLAY} environment variable." or a message of +"Unknown host" from @code{open-network-stream}. + +On a Sun, this may be because Emacs had to be linked with the static C +library. The version of @code{gethostbyname} in the static C library +may only look in @file{/etc/hosts} and the NIS (YP) maps, while the +version in the dynamic C library may be smart enough to check DNS in +addition to or instead of NIS. On a Motorola Delta running System V +R3.6, the version of @code{gethostbyname} in the standard library works, +but the one that works with NIS doesn't (the one you get with -linet). +Other operating systems have similar problems. + +Try these options: + +@itemize @bullet + +@item +Explicitly add the host you want to communicate with to @file{/etc/hosts}. + +@item +Relink Emacs with this line in @file{src/config.h}: + +@example +#define LIBS_SYSTEM -lresolv +@end example + +@item +Replace @code{gethostbyname} and friends in @file{libc.a} with more +useful versions such as the ones in @file{libresolv.a}. Then relink +Emacs. + +@item +If you are actually running NIS, make sure that "ypbind" is properly +told to do DNS lookups with the correct command line switch. + +@end itemize + +@node Errors with init files, Emacs ignores X resources, Problems talking to certain hosts, Bugs and problems +@section Why does Emacs say "Error in init file"? +@cindex Error in @file{.emacs} +@cindex Error in init file +@cindex Init file, errors in +@cindex @file{.emacs} file, errors in +@cindex Debugging @file{.emacs} file + +An error occurred while loading either your @file{.emacs} file or the +system-wide file @file{lisp/default.el}. + +For information on how to debug your @file{.emacs} file, +@pxref{Debugging a customization file}. + +It may be the case that you need to load some package first, or use a +hook that will be evaluated after the package is loaded. A common case +of this is explained in @ref{Terminal setup code works after Emacs has +begun}. + +@node Emacs ignores X resources, Emacs takes a long time to visit files, Errors with init files, Bugs and problems +@section Why does Emacs ignore my X resources (my .Xdefaults file)? +@cindex X resources being ignored +@cindex Ignored X resources +@cindex @file{.Xdefaults} + +As of version 19, Emacs searches for X resources in the files specified +by the following environment variables: + +@itemize @bullet + +@item @code{XFILESEARCHPATH} +@item @code{XUSERFILESEARCHPATH} +@item @code{XAPPLRESDIR} + +@end itemize + +This emulates the functionality provided by programs written using Xt. + +@code{XFILESEARCHPATH} and @code{XUSERFILESEARCHPATH} should be a list +of file names separated by colons. @code{XAPPLRESDIR} should be a list +of directory names separated by colons. + +Emacs searches for X resources: + +@enumerate + +@item specified on the command line, with the @samp{-xrm RESOURCESTRING} option, +@item then in the value of the @samp{XENVIRONMENT} environment variable, + +@itemize @minus + +@item or if that is unset, in the file named @samp{~/.Xdefaults-HOSTNAME} if it exists (where @samp{HOSTNAME} is the hostname of the machine Emacs is running on), + +@end itemize + +@item then in the screen-specific and server-wide resource properties provided by the server, + +@itemize @minus + +@item or if those properties are unset, in the file named ~/.Xdefaults if it exists, + +@end itemize + +@item then in the files listed in @samp{XUSERFILESEARCHPATH}, + +@itemize @minus + +@item or in files named @file{LANG/Emacs} in directories listed in @samp{XAPPLRESDIR} (where @samp{LANG} is the value of the @samp{LANG} environment variable), if the @samp{LANG} environment variable is set, +@item or in files named Emacs in the directories listed in @samp{XAPPLRESDIR} +@item or in @file{~/LANG/Emacs} (if the @samp{LANG} environment variable is set), +@item or in @file{~/Emacs}, + +@end itemize + +@item then in the files listed in @code{XFILESEARCHPATH}. + +@end enumerate + +@node Emacs takes a long time to visit files, Editing files with $ in the name, Emacs ignores X resources, Bugs and problems +@section Why does Emacs take 20 seconds to visit a file? +@cindex Visiting files takes a long time +@cindex Delay when visiting files +@cindex Files, take a long time to visit + +Old versions of Emacs (i.e., versions before Emacs 20.x) often +encountered this when the master lock file, @file{!!!SuperLock!!!} has +been left in the lock directory somehow. Delete it. + +@email{meuer@@geom.umn.edu, Mark Meuer} says that NeXT NFS has a bug +where an exclusive create succeeds but returns an error status. This +can cause the same problem. Since Emacs's file locking doesn't work +over NFS anyway, the best solution is to recompile Emacs with +@code{CLASH_DETECTION} undefined. + +@node Editing files with $ in the name, Shell mode loses the current directory, Emacs takes a long time to visit files, Bugs and problems +@section How do I edit a file with a @samp{$} in its name? +@cindex Editing files with @samp{$} in the name +@cindex @samp{$} in filenames +@cindex Filenames containing @samp{$}, editing + +When entering a filename in the minibuffer, Emacs will attempt to expand +a @samp{$} followed by a word as an environment variable. To suppress +this behavior, type @kbd{$$} instead. + +@node Shell mode loses the current directory, Security risks with Emacs, Editing files with $ in the name, Bugs and problems +@section Why does shell mode lose track of the shell's current directory? +@cindex Current directory and @code{shell-mode} +@cindex @code{shell-mode} and current directory +@cindex Directory, current in @code{shell-mode} + +Emacs has no way of knowing when the shell actually changes its +directory. This is an intrinsic limitation of Unix. So it tries to +guess by recognizing @samp{cd} commands. If you type "cd" followed by a +directory name with a variable reference (@samp{cd $HOME/bin}) or with a +shell metacharacter (@samp{cd ../lib*}), Emacs will fail to correctly +guess the shell's new current directory. A huge variety of fixes and +enhancements to shell mode for this problem have been written to handle +this problem. Check the Lisp Code Directory (@pxref{Finding a package +with particular functionality}). + +You can tell Emacs the shell's current directory with the command +@kbd{M-x dirs}. + +@node Security risks with Emacs, Dired claims that no file is on this line, Shell mode loses the current directory, Bugs and problems +@section Are there any security risks in Emacs? +@cindex Security with Emacs +@cindex @samp{movemail} and security +@cindex @code{file-local-variable} and security +@cindex Synthetic X events and security +@cindex X events and security + +@itemize @bullet + +@item The @file{movemail} incident (No, this is not a risk.) + +In his book @emph{The Cuckoo's Egg}, Cliff Stoll describes this in +chapter 4. The site at LBL had installed the @file{etc/movemail} +program setuid root. (As of version 19, @file{movemail} is in your +architecture-specific directory; type @kbd{C-h v exec-directory +@key{RET}} to see what it is.) Since @file{movemail} had not been +designed for this situation, a security hole was created and users could +get root privileges. + +@file{movemail} has since been changed so that this security hole will +not exist, even if it is installed setuid root. However, +@file{movemail} no longer needs to be installed setuid root, which +should eliminate this particular risk. + +We have heard unverified reports that the 1988 Internet worm took +advantage of this configuration problem. + +@item The @code{file-local-variable} feature (Yes, a risk, but easy to change.) + +There is an Emacs feature that allows the setting of local values for +variables when editing a file by including specially formatted text near +the end of the file. This feature also includes the ability to have +arbitrary Emacs Lisp code evaluated when the file is visited. +Obviously, there is a potential for Trojan horses to exploit this +feature. + +Emacs 18 allowed this feature by default; users could disable it by +setting the variable @code{inhibit-local-variables} to a non-nil value. + +As of Emacs 19, Emacs has a list of local variables that create a +security risk. If a file tries to set one of them, it asks the user to +confirm whether the variables should be set. You can also tell Emacs +whether to allow the evaluation of Emacs Lisp code found at the bottom +of files by setting the variable @code{enable-local-eval}. + +For more information, @inforef{File Variables, File Variables, emacs}. + +@item Synthetic X events (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or better.) + +Emacs accepts synthetic X events generated by the SendEvent request as +though they were regular events. As a result, if you are using the +trivial host-based authentication, other users who can open X +connections to your X workstation can make your Emacs process do +anything, including run other processes with your privileges. + +The only fix for this is to prevent other users from being able to open +X connections. The standard way to prevent this is to use a real +authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using +the @file{xauth} program has any effect, then you are probably using +@samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior +authentication method; ask your system administrator. + +If real authentication is not a possibility, you may be satisfied by +just allowing hosts access for brief intervals while you start your X +programs, then removing the access. This reduces the risk somewhat by +narrowing the time window when hostile users would have access, but +@emph{does not eliminate the risk}. + +On most computers running Unix and X Windows, you enable and disable +access using the @file{xhost} command. To allow all hosts access to +your X server, use + +@example +xhost + +@end example + +at the shell prompt, which (on an HP machine, at least) produces the +following message: + +@example +access control disabled, clients can connect from any host +@end example + +To deny all hosts access to your X server (except those explicitly +allowed by name), use + +@example +xhost - +@end example + +On the test HP computer, this command generated the following message: + +@example +access control enabled, only authorized clients can connect +@end example + +@end itemize + +@node Dired claims that no file is on this line, , Security risks with Emacs, Bugs and problems +@section Dired says, "no file on this line" when I try to do something. +@cindex Dired does not see a file + +Chances are you're using a localized version of Unix that doesn't use US +date format in dired listings. You can check this by looking at dired +listings or by typing @code{ls -l} to a shell and looking at the dates that +come out. + +Dired uses a regular expression to find the beginning of a file name. +In a long Unix-style directory listing ("ls -l"), the file name starts +after the date. The regexp has thus been written to look for the date, +the format of which can vary on non-US systems. + +There are two approaches to solving this. The first one involves +setting things up so that "ls -l" outputs US date format. This can be +done by setting the locale. See your OS manual for more information. + +The second approach involves changing the regular expression used by +dired, @code{dired-move-to-filename-regexp}. + +@c ------------------------------------------------------------ +@node Compiling and installing Emacs, Finding Emacs and related packages, Bugs and problems, Top +@chapter Compiling and installing Emacs +@cindex Compiling and installing Emacs + +@menu +* Installing Emacs:: +* Updating Emacs:: +* Problems building Emacs:: +* Linking with -lX11 fails:: +@end menu + +@node Installing Emacs, Updating Emacs, Compiling and installing Emacs, Compiling and installing Emacs +@section How do I install Emacs? +@cindex Installing Emacs +@cindex Unix systems, installing Emacs on +@cindex Downloading and installing Emacs +@cindex Retrieving and installing Emacs +@cindex Building Emacs from source +@cindex Source code, building Emacs from +@cindex Unpacking and installing Emacs + +This answer is meant for users of Unix and Unix-like systems. Users of +other operating systems should see the series of questions beginning +with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source +and binaries. These packages should come with installation +instructions. + +For Unix and Unix-like systems, the easiest way is often to compile it +from scratch. You will need: + +@itemize @bullet + +@item +Emacs sources. @xref{Current GNU distributions} for a list of ftp sites +that make them available. On @file{ftp.gnu.org}, the main GNU +distribution site, sources are available at + +@uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-20.4.tar.gz} + +The above will obviously change as new versions of Emacs come out. For +instance, when Emacs 20.5 is released, it will most probably be +available at + +@uref{ftp://ftp.gnu.org/pub/gnu/emacs/emacs-20.5.tar.gz} + +Again, you should use one of the GNU mirror sites (@xref{Current GNU +distributions} and adjust the URL accordingly) so as to reduce load on +@file{ftp.gnu.org}. + +@item +@code{gzip}, the GNU compression utility. You can get @code{gzip} via +anonymous ftp at mirrors of @file{ftp.gnu.org} sites; it should compile +and install without much trouble on most systems. Once you have +retrieved the Emacs sources, you will probably be able to uncompress +them with the command + +@example +gunzip --verbose emacs-20.4.tar.gz +@end example + +changing the Emacs version (20.4), as necessary. Once gunzip has +finished doing its job, a file by the name of "emacs-20.4.tar" should +be in your build directory. + +@item +@file{tar}, the "tape archiving" program, which moves multiple files +into and out of archive files, or "tarfiles." All of the files +comprising the Emacs source come in a single tarfile, and must be +extracted using @file{tar} before you can build Emacs. Typically, the +extraction command would look like + +@example +tar -xvvf emacs-20.4.tar +@end example + +The @samp{x} indicates that we want to extract files from this tarfile, +the two @samp{v}s force verbose output, and the @samp{f} tells +@file{tar} to use a disk file, rather than one on tape. + +If you're using GNU @file{tar} (available at mirrors of +@file{ftp.gnu.org}), you can combine this step and the previous one by +using the command + +@example +tar -zxvvf emacs-20.4.tar.gz +@end example + +The additional @samp{z} at the beginning of the options list tells GNU tar +to uncompress the file with gunzip before extracting the tarfile's +components. + +@end itemize + +At this point, the Emacs sources (all 25+ megabytes of them) should be +sitting in a directory called @file{emacs-20.4}. On most common Unix and +Unix-like systems, you should be able to compile Emacs (with X Windows +support) with the following commands: + +@example +cd emacs-20.4 # change directory to emacs-20.4 +./configure # configure Emacs for your particular system +make # use Makefile to build components, then Emacs +@end example + +If the @code{make} completes successfully, the odds are fairly good that +the build has gone well. (@xref{Problems building Emacs} if you weren't +successful.) + +By default, Emacs is installed in the following directories: + +@table @file + +@item /usr/local/bin +binaries + +@item /usr/local/share/emacs/20.xx +Lisp code and support files + +@item /usr/local/info +Info documentation + +@end table + +To install files in those default directories, become the superuser and +type + +@example +make install +@end example + +Note that @code{make install} will overwrite @file{/usr/local/bin/emacs} +and any Emacs Info files that might be in @file{/usr/local/info}. + +Much more verbose instructions (with many more hints and suggestions) +come with the Emacs sources, in the file @file{INSTALL}. + +@node Updating Emacs, Problems building Emacs, Installing Emacs, Compiling and installing Emacs +@section How do I update Emacs to the latest version? +@cindex Updating Emacs + +@xref{Installing Emacs}, and follow the instructions there for +installation. + +Most files are placed in version-specific directories. Emacs 20.4, for +instance, places files in @file{/usr/local/share/emacs/20.4}. + +Upgrading should overwrite only, @file{/usr/local/bin/emacs} (the Emacs +binary) and documentation in @file{/usr/local/info}. Back up these +files before you upgrade, and you shouldn't have too much trouble. + +@node Problems building Emacs, Linking with -lX11 fails, Updating Emacs, Compiling and installing Emacs +@section What should I do if I have trouble building Emacs? +@cindex Problems building Emacs +@cindex Errors when building Emacs + +First look in the file @file{PROBLEMS} (in the top-level directory when +you unpack the Emacs source) to see if there is already a solution for +your problem. Next, look for other questions in this FAQ that have to +do with Emacs installation and compilation problems. + +If you'd like to have someone look at your problem and help solve it, +@pxref{Help installing Emacs}. + +If you cannot find a solution in the documentation, send a message to +@email{bug-gnu-emacs@@gnu.org}. + +Please do not post it to @uref{news:gnu.emacs.help} or send e-mail to +@email{help-gnu-emacs@@gnu.org}. For further guidelines, +@pxref{Guidelines for newsgroup postings} and @ref{Reporting bugs}. + +@node Linking with -lX11 fails, , Problems building Emacs, Compiling and installing Emacs +@section Why does linking Emacs with -lX11 fail? +@cindex Linking with -lX11 fails +@cindex lX11, linking fails with + +Emacs needs to be linked with the static version of the X11 library, +@file{libX11.a}. This may be missing. + +Under OpenWindows, you may need to use "add_services" to add the +"OpenWindows Programmers" optional software category from the CD-ROM. + +Under HP-UX 8.0, you may need to run "update" again to load the X11-PRG +"fileset". This may be missing even if you specified "all filesets" the +first time. If @file{libcurses.a} is missing, you may need to load the +"Berkeley Development Option." + +@email{zoo@@armadillo.com, David Zuhn} says that MIT X builds shared +libraries by default, and only shared libraries, on those platforms that +support them. These shared libraries can't be used when undumping +temacs (the last stage of the Emacs build process). To get regular +libraries in addition to shared libraries, add this to @file{site.cf}: + +@example +#define ForceNormalLib YES +@end example + +Other systems may have similar problems. You can always define +CANNOT_DUMP and link with the shared libraries instead. + +To get the Xmenu stuff to work, you need to find a copy of MIT's +@file{liboldX.a}. + +@c ------------------------------------------------------------ +@node Finding Emacs and related packages, Major packages and programs, Compiling and installing Emacs, Top +@chapter Finding Emacs and related packages +@cindex Finding Emacs and related packages + +@menu +* Finding Emacs on the Internet:: +* Finding a package with particular functionality:: +* Packages that do not come with Emacs:: +* Submitting to the Emacs Lisp Archive:: +* Current GNU distributions:: +* Difference between Emacs and XEmacs:: +* Emacs for MS-DOS:: +* Emacs for Windows:: +* Emacs for OS/2:: +* Emacs for Atari ST:: +* Emacs for the Amiga :: +* Emacs for NeXTSTEP:: +* Emacs for Apple computers:: +* Emacs for VMS and DECwindows:: +* Modes for various languages:: +* Translating names to IP addresses:: +@end menu + +@node Finding Emacs on the Internet, Finding a package with particular functionality, Finding Emacs and related packages, Finding Emacs and related packages +@section Where can I get Emacs on the net (or by snail mail)? +@cindex Finding Emacs on the Internet +@cindex Snail mail, ordering Emacs via +@cindex Postal service, ordering Emacs via +@cindex Distribution, retrieving Emacs +@cindex Internet, retreiving from + +Look in the files @file{etc/DISTRIB} and @file{etc/FTP} for information +on nearby archive sites and @file{etc/ORDERS} for mail orders. If you +don't already have Emacs, @pxref{Informational files for Emacs} for how +to get these files. + +@xref{Installing Emacs} for information on how to obtain and build the latest +version of Emacs, and @pxref{Current GNU distributions} for a list of +archive sites that make GNU software available. + +@node Finding a package with particular functionality, Packages that do not come with Emacs, Finding Emacs on the Internet, Finding Emacs and related packages +@section How do I find a Emacs Lisp package that does XXX? +@cindex Package, finding +@cindex Finding an Emacs Lisp package +@cindex Functionality, finding a particular package + +First of all, you should check to make sure that the package isn't +already available. For example, typing @kbd{M-x apropos @key{RET} +wordstar @key{RET}} lists all functions and variables containing the +string @samp{wordstar}. + +It is also possible that the package is on your system, but has not been +loaded. To see which packages are available for loading, look through +your computer's lisp directory (@pxref{Filename conventions}). The Lisp +source to most most packages contains a short description of how they +should be loaded, invoked, and configured --- so before you use or +modify a Lisp package, see if the author has provided any hints in the +source code. + +If a package does not come with Emacs, check the Lisp Code Directory. +The LCD was originally maintained by @email{brennan@@hal.com, Dave +Brennan}, but was recently taken over by @email{toby@@world.std.com, +toby knudsen}, who maintains @uref{http://www.emacs.org}. The LCD is +currently being reorganized and updated, but you can meanwhile find many +packages at @uref{ftp://ftp.emacs.org/pub}. + +For now, you can search through the LCD with @file{lispdir.el}, which is +in the process of being updated. Download it from the LCD, in the +@file{emacs-lisp-attic/misc} directory, and then evaluate the following +Lisp form (@pxref{Evaluating Emacs Lisp code}): + +@lisp +(setq lisp-code-directory + "/anonymous@@ftp.emacs.org:pub/emacs-lisp-attic/emacs-lisp/LCD-datafile.gz" + elisp-archive-host "ftp.emacs.org" + elisp-archive-directory "/pub/emacs-lisp-attic/emacs-lisp/") +@end lisp + +Once you have installed @file{lispdir.el}, you can use @kbd{M-x +lisp-dir-apropos} to search the listing. For example, @kbd{M-x +lisp-dir-apropos @key{RET} ange-ftp @key{RET}} produces this output: + +@example + GNU Emacs Lisp Code Directory Apropos --- "ange-ftp" +"~/" refers to archive.cis.ohio-state.edu:pub/elisp-archive/ + + ange-ftp (4.18) 15-Jul-1992 + Andy Norman, + ~/packages/ange-ftp.tar.Z + transparent FTP Support for GNU Emacs + auto-save (1.19) 01-May-1992 + Sebastian Kremer, + ~/misc/auto-save.el.Z + Safer autosaving with support for ange-ftp and /tmp + ftp-quik (1.0) 28-Jul-1993 + Terrence Brannon, + ~/modes/ftp-quik.el.Z + Quik access to dired'ing of ange-ftp and normal paths +@end example + +@node Packages that do not come with Emacs, Submitting to the Emacs Lisp Archive, Finding a package with particular functionality, Finding Emacs and related packages +@section Where can I get Emacs Lisp packages that don't come with Emacs? +@cindex Unbundled packages +@cindex Finding other packages +@cindex Lisp packages that do not come with Emacs +@cindex Packages, those that do not come with Emacs +@cindex Emacs Lisp Archive, description of +@cindex Archive, description of the Emacs Lisp + +First, check the Lisp Code Directory to find the name of the package you +are looking for (@pxref{Finding a package with particular +functionality}). Next, check local archives and the Emacs Lisp Archive +to find a copy of the relevant files. If you still haven't found it, +you can send e-mail to the author asking for a copy. If you find Emacs +Lisp code that doesn't appear in the LCD, please submit a copy to the +LCD (@pxref{Submitting to the Emacs Lisp Archive}). + +You can access the Emacs Lisp Archive at + +@uref{ftp://archive.cis.ohio-state.edu/pub/emacs-lisp/} + +Retrieve and read the file @file{README} first. + +@itemize @bullet + +@item The archive maintainers do not have time to answer individual +requests for packages or the list of packages in the archive. If you +cannot use FTP or UUCP to access the archive yourself, try to find a +friend who can, but please don't ask the maintainers. + +@item Any files with names ending in @samp{.Z}, @samp{.z}, or @samp{.gz} are +compressed, so you should use "binary" mode in FTP to retrieve them. +You should also use binary mode whenever you retrieve any files with +names ending in @samp{.elc}. + +@end itemize + +@node Submitting to the Emacs Lisp Archive, Current GNU distributions, Packages that do not come with Emacs, Finding Emacs and related packages +@section How do I submit code to the Emacs Lisp Archive? +@cindex Submitting code to the Emacs Lisp Archive +@cindex Emacs Lisp Archive, submissions to +@cindex Lisp Archive, submissions to +@cindex Archive, submitting to the Emacs Lisp + +Guidelines and procedures for submission to the archive can be found in +the file @file{GUIDELINES} in the archive directory (@ref{Packages that +do not come with Emacs}). It covers documentation, copyrights, +packaging, submission, and the Lisp Code Directory Record. Anonymous +FTP uploads are not permitted. Instead, all submissions are mailed to +@email{elisp-archive@@cis.ohio-state.edu}. The @file{lispdir.el} +package has a function named @code{submit-lcd-entry} which will help you +with this. + +@node Current GNU distributions, Difference between Emacs and XEmacs, Submitting to the Emacs Lisp Archive, Finding Emacs and related packages +@section Where can I get other up-to-date GNU stuff? +@cindex Current GNU distributions +@cindex Sources for current GNU distributions +@cindex Stuff, current GNU +@cindex Up-to-date GNU stuff +@cindex Finding current GNU software +@cindex Official GNU software sites + +The most up-to-date official GNU software is normally kept at + +@uref{ftp://ftp.gnu.org/pub/gnu} + +Read the files @file{etc/DISTRIB} and @file{etc/FTP} for more +information. + +A list of sites mirroring @samp{ftp.gnu.org} can be found at + +@uref{http://www.gnu.org/order/ftp.html} + +@node Difference between Emacs and XEmacs, Emacs for MS-DOS, Current GNU distributions, Finding Emacs and related packages +@section What is the difference between Emacs and XEmacs (formerly "Lucid Emacs")? +@cindex XEmacs +@cindex Difference Emacs and XEmacs +@cindex Lucid Emacs +@cindex Epoch + +First of all, they're both GNU Emacs. XEmacs is just as much a later +version of GNU Emacs as the FSF-distributed version. This FAQ refers to +the latest version to be distributed by the FSF as "Emacs," partly +because the XEmacs maintainers now refer to their product using the +"XEmacs" name, and partly because there isn't any accurate way to +differentiate between the two without getting mired in paragraphs of +legalese and history. + +XEmacs, which began life as Lucid Emacs, is based on an early version of +Emacs 19 and Epoch, an X-aware version of Emacs 18. + +Emacs (i.e., the version distributed by the FSF) has a larger installed +base, while XEmacs can do some clever tricks with X Windows, such as +putting arbitrary graphics in a buffer. Emacs and XEmacs each come with +Lisp packages that are lacking in the other; RMS says that the FSF would +include more packages that come with XEmacs, but that the XEmacs +maintainers don't always keep track of the authors of contributed code, +which makes it impossible for the FSF to have certain legal papers +signed. (Without these legal papers, the FSF will not distribute Lisp +packages with Emacs.) + +Many XEmacs features have found their way into recent versions of Emacs, +and more features can be expected in the future, but there are still many +differences between the two. + +The latest version of XEmacs as of this writing is 21.1; you can get it +at + +@uref{ftp://ftp.xemacs.org/pub/xemacs/current/xemacs-21.1.4.tar.gz} + +More information about XEmacs, including a list of frequently asked +questions (FAQ), is available at + +@uref{http://www.xemacs.org/faq/} + +@node Emacs for MS-DOS, Emacs for Windows, Difference between Emacs and XEmacs, Finding Emacs and related packages +@section Where can I get Emacs for my PC running MS-DOS? +@cindex MS-DOS, Emacs for +@cindex DOS, Emacs for +@cindex Compiling Emacs for DOS +@cindex Emacs for MS-DOS +@cindex Tools needed to compile Emacs under DOS + +A pre-built binary distribution of Emacs is available from the Simtel +archives. This version apparently works under MS-DOS and Windows (3.x, +95, and NT) and supports long file names. More information is availble +from + +@uref{ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/emacs.README} + +The binary itself is available in the files em1934*.zip in the +directory + +@uref{ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/} + +If you prefer to compile Emacs for yourself, you will need a 386 (or +better) processor, and are running MS-DOS 3.0 or later. According to +@email{eliz@@is.elta.co.il, Eli Zaretskii} and +@email{hankedr@@dms.auburn.edu, Darrel Hankerson}, you will need the +following: + +@table @emph + +@item Compiler +djgpp version 1.12 maint 1 or later. Djgpp 2.0 or later is +recommended, since 1.x is being phased out. Djgpp 2 supports +long filenames under Windows 95. + +You can get the latest release of djgpp by retrieving all of +the files in + +@uref{ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp} + +@item Gunzip and tar +The easiest way is to use "djtar" which comes with djgpp v2.x, +because it can open gzip'ed tarfiles (i.e., those ending with +".tar.gz") in one step. Djtar comes in "djdev201.zip", from +the URL mentioned above. + +@item make, mv, sed, and rm +All of these utilities are available at + +@uref{ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu} + +16-bit utilities can be found in GNUish, at + +@uref{ftp://ftp.simtel.net/pub/simtelnet/gnu/gnuish} + +@end table + +The files @file{INSTALL} and @file{PROBLEMS} in the top-level directory +of the Emacs source contains some additional information regarding Emacs +under MS-DOS. + +For a list of other MS-DOS implementations of Emacs (and Emacs +look-alikes), consult the list of "Emacs implementations and literature," +available at + +@uref{ftp://rtfm.mit.edu/pub/usenet/comp.emacs/} + +Note that while many of these programs look similar to Emacs, they often +lack certain features, such as the Emacs Lisp extension language. + +@node Emacs for Windows, Emacs for OS/2, Emacs for MS-DOS, Finding Emacs and related packages +@section Where can I get Emacs for Microsoft Windows +@cindex FAQ for NT Emacs +@cindex Microsoft Windows, Emacs for +@cindex Windows NT, Emacs for +@cindex Windows '95 and '98, Emacs for + +For information on Emacs for Windows 95 and NT, read the FAQ produced by +@email{voelker@@cs.washington.edu, Geoff Voelker}, available at + +@uref{http://www.cs.washington.edu/homes/voelker/ntemacs.html} + +@xref{Emacs for MS-DOS} for Windows 3.1. + +@node Emacs for OS/2, Emacs for Atari ST, Emacs for Windows, Finding Emacs and related packages +@section Where can I get Emacs for my PC running OS/2? +@cindex OS/2, Emacs for + +Emacs 19.33 is ported for emx on OS/2 2.0 or 2.1, and is available at + +@uref{ftp://hobbes.nmsu.edu/pub/os2/apps/editors/emacs/v19.33/} + +@node Emacs for Atari ST, Emacs for the Amiga , Emacs for OS/2, Finding Emacs and related packages +@section Where can I get Emacs for my Atari ST? +@cindex Atari ST, Emacs for +@cindex TOS, Emacs for + +Roland Schäuble reports that Emacs 18.58 running on plain TOS and MiNT +is available at +@uref{ftp://atari.archive.umich.edu/Editors/Emacs-18-58/1858b-d3.zoo}. + +@node Emacs for the Amiga , Emacs for NeXTSTEP, Emacs for Atari ST, Finding Emacs and related packages +@section Where can I get Emacs for my Amiga? +@cindex Amiga, Emacs for + +The files you need are available at + +@uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/} + +@email{dgilbert@@gamiga.guelphnet.dweomer.org, David Gilbert} has released a +beta version of Emacs 19.25 for the Amiga. You can get the binary at + +@uref{ftp://ftp.wustl.edu/pub/aminet/util/gnu/a2.0bEmacs-bin.lha} + +@node Emacs for NeXTSTEP, Emacs for Apple computers, Emacs for the Amiga , Finding Emacs and related packages +@section Where can I get Emacs for NeXTSTEP? +@cindex NeXTSTEP, Emacs for + +Emacs.app is a NeXTSTEP version of Emacs 19.34 which supports colors, +menus, and multiple frames. You can get it from + +@uref{ftp://next-ftp.peak.org/pub/next/apps/emacs/Emacs_for_NeXTstep.4.20a1.NIHS.b.tar.gz} + +@node Emacs for Apple computers, Emacs for VMS and DECwindows, Emacs for NeXTSTEP, Finding Emacs and related packages +@section Where can I get Emacs for my Apple computer? +@cindex Apple computers, Emacs for + +An unofficial port of GNU Emacs 18.59 to the Macintosh is available at a +number of ftp sites, the home being +@uref{ftp://ftp.cs.cornell.edu/pub/parmet/Emacs-1.17.sit.bin}. + +To the best of our knowledge, Emacs 19 has not been ported to the +Macintosh. + +Apple's forthcoming "OS X" is based largely on NeXTSTEP and OpenStep. +@xref{Emacs for NeXTSTEP} for more details about that version. + +@node Emacs for VMS and DECwindows, Modes for various languages, Emacs for Apple computers, Finding Emacs and related packages +@section Where do I get Emacs that runs on VMS under DECwindows? +@cindex DECwindows, Emacs for +@cindex VMS, Emacs for + +Up-to-date information about GNU software (including Emacs) for VMS is +available at @uref{http://vms.gnu.org/}. + +@node Modes for various languages, Translating names to IP addresses, Emacs for VMS and DECwindows, Finding Emacs and related packages +@section Where can I get modes for Lex, Yacc/Bison, Bourne shell, csh, C++, Objective-C, Pascal, Java, and Awk? +@cindex Awk, mode for +@cindex @code{awk-mode} +@cindex Bison, mode for +@cindex Bourne Shell, mode for +@cindex C++, mode for +@cindex Java, mode for +@cindex Lex mode +@cindex Objective-C, mode for +@cindex @code{pascal-mode} +@cindex Shell mode +@cindex Yacc mode +@cindex @file{csh} mode +@cindex @code{sh-mode} +@cindex @code{cc-mode} + +Most of these modes are now available in standard Emacs distribution. +To get additional modes, look in the Lisp Code Directory (@pxref{Finding +a package with particular functionality}). For C++, if you use +@code{lisp-dir-apropos}, you must specify the pattern with something +like @kbd{M-x lisp-dir-apropos @key{RET} c\+\+ @key{RET}}. + +Barry Warsaw's @code{cc-mode} now works for C, C++, Objective-C, and +Java code. You can get the latest version from the Emacs Lisp Archive; +@pxref{Packages that do not come with Emacs} for details. A FAQ for +@code{cc-mode} is available at +@uref{http://www.python.org/emacs/cc-mode/}. + +@node Translating names to IP addresses, , Modes for various languages, Finding Emacs and related packages +@section What is the IP address of XXX.YYY.ZZZ? +@cindex Translating names to IP addresses +@cindex IP addresses from names +@cindex Using BIND to translate addresses +@cindex DNS and IP addresses + +If you are on a Unix machine, try using the @samp{nslookup} command, +included in the Berkeley BIND package. For example, to find the IP +address of @samp{ftp.gnu.org}, you would type @code{nslookup +ftp.gnu.org}. + +Your computer should then provide the IP address of that computer. + +If your site's nameserver is deficient, you can use IP addresses to FTP +files. You can get this information by + +* E-mail: + +@example +To: dns@@[134.214.84.25] (to grasp.insa-lyon.fr) +Body: ip XXX.YYY.ZZZ (or "help" for more information + and options - no quotes) +@end example + +or: + +@example +To: resolve@@[147.31.254.130] (to laverne.cs.widener.edu) +Body: site XXX.YYY.ZZZ +@end example + +@c ------------------------------------------------------------ +@node Major packages and programs, Key bindings, Finding Emacs and related packages, Top +@chapter Major packages and programs +@cindex Major packages and programs + +@menu +* VM:: +* Supercite:: +* Calc:: +* VIPER:: +* AUC-TeX:: +* BBDB:: +* Ispell:: +* w3-mode:: +* EDB:: +* Mailcrypt:: +* JDE:: +* Patch:: +@end menu + +@node VM, Supercite, Major packages and programs, Major packages and programs +@section VM (View Mail) --- another mail reader within Emacs, with MIME support +@cindex VM +@cindex Alternative mail software +@cindex View Mail +@cindex E-mail reader, VM + +@table @b + +@item Author +@email{kyle@@uunet.uu.net, Kyle Jones} + +@item Latest version +6.72 + +@item Distribution +@uref{ftp://ftp.wonderworks.com/pub/vm/vm.tar.gz} + +@item Informational newsgroup/mailing list +@uref{news:gnu.emacs.vm.info}@* +Subscription requests to @email{info-vm-request@@uunet.uu.net}@* +Submissions to @email{info-vm@@uunet.uu.net} + +@item Bug reports newsgroup/mailing list +@uref{news:gnu.emacs.vm.bug}@* +Subscription requests to @email{bug-vm-request@@uunet.uu.net}@* +Submissions to @email{bug-vm@@uunet.uu.net} +@end table + +VM 6 works with Emacs 20.4, and may cause problems with Emacs 20.3 and +below. (Note that many people seem to use Emacs 20.3 with VM 6, without +any problems.) Risk-averse users might wish to try VM 5.97, available +from @uref{ftp://ftp.wonderworks.com/pub/vm/, the same FTP site}. + +@node Supercite, Calc, VM, Major packages and programs +@section Supercite --- mail and news citation package within Emacs +@cindex Supercite +@cindex Superyank +@cindex Mail and news citations +@cindex News and mail citations +@cindex Citations in mail and news + +@table @b + +@item Author +@email{bwarsaw@@cen.com, Barry Warsaw} + +@item Latest version +3.1 (comes with Emacs 20) + +@item Distribution +@uref{http://www.python.org/emacs/supercite.tar.gz} + +@item Mailing list +Subscription requests to @email{supercite-request@@python.org}@* +Submissions @email{supercite@@python.org} + +@end table + +Superyank is an old version of Supercite. + +@node Calc, VIPER, Supercite, Major packages and programs +@section Calc --- poor man's Mathematica within Emacs +@cindex Programmable calculator +@cindex Calc + +@table @b + +@item Author +@email{daveg@@csvax.cs.caltech.edu, Dave Gillespie} + +@item Latest version +2.02f + +@item Distribution +@uref{ftp://ftp.gnu.org/pub/gnu/calc/calc-2.02f.tar.gz} + +@end table + +@node VIPER, AUC-TeX, Calc, Major packages and programs +@section VIPER --- vi emulation for Emacs +@cindex vi emulation +@cindex VIPER +@cindex Emulation of vi + +Since Emacs 19.29, the preferred vi emulation in Emacs is VIPER +(@kbd{M-x viper-mode @key{RET}}), which comes with Emacs. It extends +and supersedes VIP (including VIP 4.3) and provides vi emulation at +several levels, from one that closely follows vi to one that departs +from vi in several significant ways. + +For Emacs 19.28 and earlier, the following version of VIP is generally +better than the one distributed with Emacs: + +@table @b +@item Author +@email{sane@@cs.uiuc.edu, Aamod Sane} + +@item Latest version +4.3 + +@item Distribution +@uref{ftp://archive.cis.ohio-state.edu/pub/emacs-lisp/modes/vip-mode.tar.Z} + +@end table + +@node AUC-TeX, BBDB, VIPER, Major packages and programs +@section AUC TeX --- enhanced LaTeX mode with debugging facilities +@cindex Mode for @TeX{} +@cindex @TeX{} mode +@cindex AUC-TeX mode for editing @TeX{} +@cindex Writing and debugging @TeX{} + +@table @b + +@item Authors +@email{krab@@iesd.auc.dk, Kresten Krab Thorup} and@* +@email{abraham@@iesd.auc.dk, Per Abrahamsen} + +@item Latest version +9.9p + +@item Distribution +@uref{ftp://sunsite.auc.dk/packages/auctex/auctex.tar.gz} + +@item Web site +@uref{http://sunsite.auc.dk/auctex/} + +@item Mailing list: +Subscription requests to @email{auc-tex-request@@iesd.auc.dk}@* +Submissions to @email{auc-tex@@iesd.auc.dk}@* +Development team is at @email{auc-tex_mgr@@iesd.auc.dk} + +@end table + +@node BBDB, Ispell, AUC-TeX, Major packages and programs +@section BBDB --- personal Info Rolodex integrated with mail/news readers +@cindex BBDB +@cindex Rolodex-like functionality +@cindex Integrated contact database +@cindex Contact database +@cindex Big Brother Database +@cindex Address book + +@table @b + +@item Maintainer +@email{simmonmt@@acm.org, Matt Simmons} + +@item Latest version +2.00 + +@item Distribution +@uref{http://www.netcom.com/~simmonmt/bbdb/index.html} + +@item Mailing lists +Subscription requests to @email{info-bbdb-request@@xemacs.org}@* +Submissions to @email{info-bbdb@@xemacs.org}@* +Release announcements: @email{bbdb-announce-request@@xemacs.org} + +@end table + +@node Ispell, w3-mode, BBDB, Major packages and programs +@section Ispell --- spell checker in C with interface for Emacs +@cindex Spell-checker +@cindex Checking spelling +@cindex Ispell + +@table @b + +@item Author +@email{geoff@@itcorp.com, Geoff Kuenning} + +@item Latest version +3.1.20 + +@item Distribution +@uref{ftp://ftp.cs.ucla.edu/pub/ispell/ispell-3.1.20.tar.gz}@* + +@item Web site +@uref{http://fmg-www.cs.ucla.edu/geoff/ispell.html} + +@end table + +@itemize @bullet + +@item Do not ask Geoff to send you the latest version of Ispell. He does not have free e-mail. + +@item This Ispell program is distinct from GNU Ispell 4.0. GNU Ispell +4.0 is no longer a supported product. + +@end itemize + +@node w3-mode, EDB, Ispell, Major packages and programs +@section w3-mode --- A World Wide Web browser inside of Emacs +@cindex WWW browser +@cindex Web browser +@cindex Browser in Emacs +@cindex @code{w3-mode} + +@table @b + +@item Author +@email{wmperry@@spry.com, Bill Perry} + +@item Latest version +4.0pre.39 + +@item Distribution +@uref{ftp://ftp.cs.indiana.edu/pub/elisp/w3/w3.tar.gz} + +@item Mailing lists +Receive announcements from @email{w3-announce-request@@indiana.edu}@* +Become a beta tester at @email{w3-beta-request@@indiana.edu}@* +Help to develop @code{w3-mode} at @email{w3-dev@@indiana.edu} + +@end table + +@node EDB, Mailcrypt, w3-mode, Major packages and programs +@section EDB --- Database program for Emacs; replaces forms editing modes +@cindex EDB +@cindex Database +@cindex Forms mode + +@table @b +@item Author +@email{mernst@@theory.lcs.mit.edu, Michael Ernst} + +@item Latest version +1.21 + +@item Distribution +@uref{ftp://theory.lcs.mit.edu/pub/emacs/edb} + +@end table + +@node Mailcrypt, JDE, EDB, Major packages and programs +@section Mailcrypt --- PGP interface within Emacs mail and news +@cindex PGP +@cindex GPG +@cindex Interface to PGP from Emacs mail and news +@cindex News, interface to PGP from +@cindex Mail, interface to PGP from +@cindex Encryption software, interface to + +@table @b + +@item Authors +@email{patl@@lcs.mit.edu, Patrick J. LoPresti} and @email{jin@@atype.com, Jin S. Choi} + +@item Maintainer +@email{lbudney@@pobox.com, Len Budney} + +@item Latest version +3.5.3 + +@item Distribution +@uref{http://www.nb.net/~lbudney/linux/software/mailcrypt/mailcrypt-3.5.3.tar.gz} + +@item Web site +@uref{http://www.nb.net/~lbudney/linux/software/mailcrypt.html} + +@end table + +@node JDE, Patch, Mailcrypt, Major packages and programs +@section JDE --- Integrated development environment for Java +@cindex Java development environment +@cindex Integrated Java development environment +@cindex JDE + +@table @b + +@item Author +@email{paulk@@mathworks.com, Paul Kinnucan} + +@item Mailing list +jde-subscribe@@sunsite.auc.dk + +@item Latest version +2.1.1 + +@item Web site +@uref{http://sunsite.auc.dk/jde/} + +@end table + +@node Patch, , JDE, Major packages and programs +@section Patch --- program to apply "diffs" for updating files +@cindex Updating files with diffs +@cindex Patching source files with diffs +@cindex Diffs and patching +@cindex @file{patch} + +@table @b + +@item Author +@email{lwall@@wall.org, Larry Wall} (with GNU modifications) + +@item Latest version +2.5 + +@item Distribution +@xref{Current GNU distributions} + +@end table + +@c ------------------------------------------------------------ +@node Key bindings, Alternate character sets, Major packages and programs, Top +@chapter Key bindings +@cindex Key bindings + +@menu +* Binding keys to commands:: +* Invalid prefix characters:: +* Terminal setup code works after Emacs has begun:: +* Using function keys under X:: +* Working with function and arrow keys:: +* X key translations for Emacs:: +* Handling C-s and C-q with flow control:: +* Binding C-s and C-q:: +* Backspace invokes help:: +* stty and Backspace key:: +* Swapping keys:: +* Producing C-XXX with the keyboard:: +* No Meta key:: +* No Escape key:: +* Compose Character:: +* Binding combinations of modifiers and function keys:: +* Meta key does not work in xterm:: +* ExtendChar key does not work as Meta:: +@end menu + +@node Binding keys to commands, Invalid prefix characters, Key bindings, Key bindings +@section How do I bind keys (including function keys) to commands? +@cindex Binding keys to commands +@cindex Keys, binding to commands +@cindex Commands, binding keys to + +Keys can be bound to commands either interactively or in your +@file{.emacs} file. To interactively bind keys for all modes, type +@kbd{M-x global-set-key @key{RET} KEY CMD @key{RET}}. + +To bind a key just in the current major mode, type @kbd{M-x local-set-key @key{RET} KEY CMD @key{RET}}. + +See @inforef{Key Bindings, Key Bindings, emacs} for further details. + +To bind keys on starting Emacs or on starting any given mode, use the +following "trick": First bind the key interactively, then immediately +type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed +to bind the key is in the kill ring, and can be yanked into your +@file{.emacs} file. If the key binding is global, no changes to the +command are required. For example, + +@lisp +(global-set-key (quote [f1]) (quote help-for-help)) +@end lisp + +can be placed directly into the @file{.emacs} file. If the key binding is +local, the command is used in conjunction with the "add-hook" command. +For example, in tex-mode, a local binding might be + +@lisp +(add-hook 'tex-mode-hook + (function (lambda () + (local-set-key (quote [f1]) (quote help-for-help))))) +@end lisp + + +@itemize @bullet + +@item Control characters in key sequences, in the form yanked from the +kill ring are given in their graphic form --- i.e., @key{CTRL} is shown +as @samp{^}, @key{TAB} as a set of spaces (usually 8), etc. You may +want to convert these into their vector or string forms. + +@item If a prefix key of the character sequence to be bound is already +bound as a complete key, then you must unbind it before the new +binding. For example, if "ESC @{" is previously bound: + +@lisp +(global-unset-key [?\e ?@{]) ;; or +(local-unset-key [?\e ?@{]) +@end lisp + +@item Aside from commands and "lambda lists," a vector or string also +can be bound to a key and thus treated as a macro. For example: + +@lisp +(global-set-key [f10] [?\C-x?\e?\e?\C-a?\C-k?\C-g]) ;; or +(global-set-key [f10] "\C-x\e\e\C-a\C-k\C-g") +@end lisp + +@end itemize + +@node Invalid prefix characters, Terminal setup code works after Emacs has begun, Binding keys to commands, Key bindings +@section Why does Emacs say "Key sequence XXX uses invalid prefix characters"? +@cindex Prefix characters, invalid +@cindex Invalid prefix characters +@cindex Misspecified key sequences + +Usually, one of two things has happened. In one case, the control +character in the key sequence has been misspecified (e.g. @samp{C-f} +used instead of @samp{\C-f} within a Lisp expression). In the other +case, a "prefix key" in the keystroke sequence you were trying to bind +was already bound as a "complete key." Historically, the @samp{ESC [} +prefix was usually the problem, in which case you should evaluate either +of these forms before attempting to bind the key sequence: + +@lisp +(global-unset-key [?\e ?[]) ;; or +(global-unset-key "\e[") +@end lisp + +@node Terminal setup code works after Emacs has begun, Using function keys under X, Invalid prefix characters, Key bindings +@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? +@cindex Terminal setup code in @file{.emacs} + +During startup, Emacs initializes itself according to a given code/file +order. If some of the code executed in your @file{.emacs} file needs to +be postponed until the initial terminal or window-system setup code has +been executed but is not, then you will experience this problem (this +code/file execution order is not enforced after startup). + +To postpone the execution of Emacs Lisp code until after terminal or +window-system setup, treat the code as a "lambda list" and set the value +of either the @code{term-setup-hook} or @code{window-setup-hook} +variable to this "lambda function." For example, + +@lisp +(setq term-setup-hook + (function + (lambda () + (cond ((string-match "\\`vt220" (or (getenv "TERM") "")) + ;; Make vt220's "Do" key behave like M-x: + (global-set-key [do] 'execute-extended-command)) + )))) +@end lisp + +For information on what Emacs does every time it is started, see the +@file{lisp/startup.el} file. + +@node Using function keys under X, Working with function and arrow keys, Terminal setup code works after Emacs has begun, Key bindings +@section How do I use function keys under X Windows? +@cindex Function keys +@cindex X Windows and function keys +@cindex Binding function keys + +With Emacs 19, functions keys under X are bound like any other key. @xref{Binding keys to commands} for details. + +@node Working with function and arrow keys, X key translations for Emacs, Using function keys under X, Key bindings +@section How do I tell what characters or symbols my function or arrow keys emit? +@cindex Working with arrow keys +@cindex Arrow keys, symbols generated by +@cindex Working with function keys +@cindex Function keys, symbols generated by +@cindex Symbols generated by function keys + +Type @kbd{C-h c} then the function or arrow keys. The command will +return either a function key symbol or character sequence (see the +Emacs on-line documentation for an explanation). This works for other +keys as well. + +@node X key translations for Emacs, Handling C-s and C-q with flow control, Working with function and arrow keys, Key bindings +@section How do I set the X key "translations" for Emacs? +@cindex X key translations +@cindex Key translations under X +@cindex Translations for keys under X + +Emacs is not written using the Xt library by default, so there are no +"translations" to be set. (We aren't sure how to set such translations +if you do build Emacs with Xt; please let us know if you've done this!) + +The only way to affect the behavior of keys within Emacs is through +"xmodmap" (outside Emacs) or @code{define-key} (inside Emacs). The +@code{define-key} command should be used in conjunction with the +@code{function-key-map} map. For instance, + +@lisp +(define-key function-key-map [M-@key{TAB}] [?\M-\t]) +@end lisp + +defines the @kbd{M-@key{TAB}} key sequence. + +@node Handling C-s and C-q with flow control, Binding C-s and C-q, X key translations for Emacs, Key bindings +@section How do I handle @kbd{C-s} and @kbd{C-q} being used for flow control? +@cindex Flow control, @kbd{C-s} and @kbd{C-q} with +@cindex @kbd{C-s} and @kbd{C-q} with flow control + +@kbd{C-s} and @kbd{C-q} are used in the XON/XOFF flow control protocol. +This messes things up when you're using Emacs, because Emacs binds these +keys to commands by default. Because Emacs won't honor them as flow +control characters, too many of these characters are not passed on and +overwhelm output buffers. Sometimes, intermediate software using +XON/XOFF flow control will prevent Emacs from ever seeing @kbd{C-s} and +@kbd{C-q}. + +Possible solutions: + +@itemize @bullet + +@item Disable the use of @kbd{C-s} and @kbd{C-q} for flow control. + +You need to determine the cause of the flow control. + +@itemize @minus + +@item your terminal + +Your terminal may use XON/XOFF flow control to have time to display +all the characters it receives. For example, VT series terminals do +this. It may be possible to turn this off from a setup menu. For +example, on a VT220 you may select "No XOFF" in the setup menu. This +is also true for some terminal emulation programs on PCs. + +When you turn off flow control at the terminal, you will also need to +turn it off at the other end, which might be at the computer you are +logged in to or at some terminal server in between. + +If you turn off flow control, characters may be lost; using a printer +connected to the terminal may fail. You may be able to get around +this problem by modifying the "termcap" entry for your terminal to +include extra NUL padding characters. + +@item a modem + +If you are using a dialup connection, the modems may be using +XON/XOFF flow control. It's not clear how to get around this. + +@item a router or terminal server + +Some network box between the terminal and your computer may be using +XON/XOFF flow control. It may be possible to make it use some other +kind of flow control. You will probably have to ask your local +network experts for help with this. + +@item tty and/or pty devices + +If your connection to Emacs goes through multiple tty and/or pty +devices, they may be using XON/XOFF flow control even when it is not +necessary. + +@email{eirik@@theory.tn.cornell.edu, Eirik Fuller} writes: + +@quotation +Some versions of "rlogin" (and possibly telnet) do not pass flow +control characters to the remote system to which they connect. On +such systems, Emacs on the remote system cannot disable flow +control on the local system. Sometimes "rlogin -8" will avoid this +problem. + +One way to cure this is to disable flow control on the local host +(the one running rlogin, not the one running rlogind) using the +stty command, before starting the rlogin process. On many systems, +@samp{stty start u stop u} will do this. + +Some versions of @samp{tcsh} will prevent even this from working. One +way around this is to start another shell before starting rlogin, +and issue the @samp{stty} command to disable flow control from that shell. +@end quotation + +Use @samp{stty -ixon} instead of @samp{stty start u stop u} on some systems. + +@end itemize + +@item Make Emacs speak the XON/XOFF flow control protocol. + +You can make Emacs treat @kbd{C-s} and @kbd{C-q} as flow control characters by +evaluating the form + +@lisp +(enable-flow-control) +@end lisp + +to unconditionally enable flow control or + +@lisp +(enable-flow-control-on "vt100" "h19") +@end lisp + +(using your terminal names instead of @samp{vt100} or @samp{h19}) to +enable selectively. These commands will automatically swap @kbd{C-s} +and @kbd{C-q} to @kbd{C-\} and @kbd{C-^}. Variables can be used to +change the default swap keys (@code{flow-control-c-s-replacement} and +@code{flow-control-c-q-replacement}). + +If you are fixing this for yourself, simply put the form in your +@file{.emacs} file. If you are fixing this for your entire site, the +best place to put it is in the @file{lisp/site-start.el} file. Putting +this form in @file{lisp/default.el} has the problem that if the user's +@file{.emacs} file has an error, this will prevent +@file{lisp/default.el} from being loaded and Emacs may be unusable for +the user, even for correcting their @file{.emacs} file (unless they're +smart enough to move it to another name). + +@end itemize + +For further discussion of this issue, read the file @file{PROBLEMS} (in +the top-level directory when you unpack the Emacs source). + +@node Binding C-s and C-q, Backspace invokes help, Handling C-s and C-q with flow control, Key bindings +@section How do I bind @kbd{C-s} and @kbd{C-q} (or any key) if these keys are filtered out? +@cindex Binding @kbd{C-s} and @kbd{C-q} +@cindex @kbd{C-s} and @kbd{C-q}, binding + +To bind @kbd{C-s} and @kbd{C-q}, use either @code{enable-flow-control} +or @sc{enable-flow-control-on}. @xref{Handling C-s and C-q with flow +control} for usage and implementation details. + +To bind other keys, use @code{keyboard-translate}. @xref{Swapping keys} +for usage details. To do this for an entire site, you should swap the +keys in @file{lisp/site-start.el}. @xref{Handling C-s and C-q with flow +control} for an explanation of why @file{lisp/default.el} should not be +used. + +@itemize @bullet + +@item If you do this for an entire site, the users will be confused by +the disparity between what the documentation says and how Emacs +actually behaves. + +@end itemize + +@node Backspace invokes help, stty and Backspace key, Binding C-s and C-q, Key bindings +@section Why does the @key{Backspace} key invoke help? +@cindex Backspace key invokes help +@cindex Help invoked by Backspace + +The @key{Backspace} key (on most keyboards) generates ASCII code 8. +@kbd{C-h} sends the same code. In Emacs by default @kbd{C-h} invokes +help-command. This is intended to be easy to remember since the first +letter of @samp{help} is @samp{h}. The easiest solution to this problem +is to use @kbd{C-h} (and @key{Backspace}) for help and @key{DEL} (the +@key{Delete} key) for deleting the previous character. + +For many people this solution may be problematic: + +@itemize @bullet + +@item +They normally use @key{Backspace} outside of Emacs for deleting the +previous character. This can be solved by making @key{DEL} the command +for deleting the previous character outside of Emacs. On many Unix +systems, this command will remap @key{DEL}: + +@example +stty erase `^?' +@end example + +@item +The person may prefer using the @key{Backspace} key for deleting the +previous character because it is more conveniently located on their +keyboard or because they don't even have a separate Delete key. In +this case, the @key{Backspace} key should be made to behave like +@key{Delete}. There are several methods. + +@item +Some terminals (e.g., VT3## terminals) allow the character generated +by the @key{Backspace} key to be changed from a setup menu. + +@item +You may be able to get a keyboard that is completely programmable. + +@item +Under X or on a dumb terminal, it is possible to swap the +@key{Backspace} and @key{Delete} keys inside Emacs: + +@lisp +(keyboard-translate ?\C-h ?\C-?) +@end lisp + +@xref{Swapping keys} for further details of "keyboard-translate". + +@item +Another approach is to switch key bindings and put help on @kbd{C-x h} +instead: + +@lisp +(global-set-key "\C-h" 'delete-backward-char) + +;;; overrides mark-whole-buffer +(global-set-key "\C-xh" 'help-command) +@end lisp + +Other popular key bindings for help are @kbd{M-?} and @kbd{C-x ?}. + +Don't try to bind @key{DEL} to @code{help-command}, because there are +many modes that have local bindings of @key{DEL} that will interfere. + +@end itemize + +@node stty and Backspace key, Swapping keys, Backspace invokes help, Key bindings +@section Why doesn't Emacs look at the @file{stty} settings for @key{Backspace} vs. @key{Delete}? +@cindex @file{stty} and Emacs +@cindex Backspace and @file{stty} +@cindex Delete and @file{stty} + +Good question! + +@node Swapping keys, Producing C-XXX with the keyboard, stty and Backspace key, Key bindings +@section How do I swap two keys? +@cindex Swapping keys +@cindex Keys, swapping +@cindex @code{keyboard-translate} + +In Emacs 19, you can swap two keys (or key sequences) by using the +@code{keyboard-translate} function. For example, to turn @kbd{C-h} into +@key{DEL} and @key{DEL} to @kbd{C-h}, use + +@lisp +(keyboard-translate ?\C-h ?\C-?) ; translate `C-h' to DEL +(keyboard-translate ?\C-? ?\C-h) ; translate DEL to `C-h'. +@end lisp + +The first key sequence of the pair after the function identifies what is +produced by the keyboard; the second, what is matched for in the +keymaps. + +Keyboard translations are not the same as key bindings in keymaps. +Emacs contains numerous keymaps that apply in different situations, but +there is only one set of keyboard translations, and it applies to every +character that Emacs reads from the terminal. Keyboard translations +take place at the lowest level of input processing; the keys that are +looked up in keymaps contain the characters that result from keyboard +translation. + +@inforef{Keyboard Translations, Keyboard Translations, emacs}. + +@node Producing C-XXX with the keyboard, No Meta key, Swapping keys, Key bindings +@section How do I produce C-XXX with my keyboard? +@cindex Producing control characters +@cindex Generating control characters +@cindex Control characters, generating + +On terminals (but not under X), some common "aliases" are: + +@table @asis + +@item @kbd{C-2} or @kbd{C-@key{SPC}} +@kbd{C-@@} + +@item @kbd{C-6} +@kbd{C-^} + +@item @kbd{C-7} or @kbd{C-S--} +@kbd{C-_} + +@item @kbd{C-4} +@kbd{C-\} + +@item @kbd{C-5} +@kbd{C-]} + +@item @kbd{C-/} +@kbd{C-?} + +@end table + +Often other aliases exist; use the @kbd{C-h c} command and try +@key{CTRL} with all of the digits on your keyboard to see what gets +generated. You can also try the @kbd{C-h w} command if you know the +name of the command. + +@node No Meta key, No Escape key, Producing C-XXX with the keyboard, Key bindings +@section What if I don't have a @key{Meta} key? +@cindex No @key{Meta} key +@cindex @key{Meta} key, what to do if you lack it + +Instead of typing @kbd{M-a}, you can type @kbd{@key{ESC} a}. In fact, +Emacs converts @kbd{M-a} internally into @kbd{@key{ESC} a} anyway +(depending on the value of @code{meta-prefix-char}). Note that you +press @key{Meta} and @key{a} together, while you press @kbd{ESC}, +release it, and then press @key{a}. + +@node No Escape key, Compose Character, No Meta key, Key bindings +@section What if I don't have an @key{Escape} key? +@cindex No Escape key +@cindex Lacking an Escape key +@cindex Escape key, lacking + +Type @kbd{C-[} instead. This should send ASCII code 27 just like an +Escape key would. @kbd{C-3} may also work on some terminal (but not +under X). For many terminals (notably DEC terminals) @key{F11} +generates @key{ESC}. If not, the following form can be used to bind it: + +@lisp +;;; F11 is the documented ESC replacement on DEC terminals. +(define-key function-key-map [f11] [?\e]) +@end lisp + +@node Compose Character, Binding combinations of modifiers and function keys, No Escape key, Key bindings +@section Can I make my @key{Compose Character} key behave like a @key{Meta} key? +@cindex @key{Compose Character} key, using as @key{Meta} +@cindex @key{Meta}, using @key{Compose Character} for + +On a dumb terminal such as a VT220, no. It is rumored that certain +VT220 clones could have their @key{Compose} key configured this way. If +you're using X, you might be able to do this with the @file{xmodmap} program. + +@node Binding combinations of modifiers and function keys, Meta key does not work in xterm, Compose Character, Key bindings +@section How do I bind a combination of modifier key and function key? +@cindex Modifiers and function keys +@cindex Function keys and modifiers +@cindex Binding modifiers and function keys + +With Emacs 19 you can represent modified function keys in vector format +by adding prefixes to the function key symbol. For example (from the +on-line documentation): + +@lisp +(global-set-key [?\C-x right] 'forward-page) +@end lisp + +where @samp{?\C-x} is the Lisp character constant for the character @kbd{C-x}. + +You can use the modifier keys @key{Control}, @key{Meta}, @key{Hyper}, +@key{Super}, @key{Alt}, and @key{Shift} with function keys. To +represent these modifiers, prepend the strings @samp{C-}, @samp{M-}, +@samp{H-}, @samp{s-}, @samp{A-}, and @samp{S-} to the symbol name. Here +is how to make @kbd{H-M-RIGHT} move forward a word: + +@lisp +(global-set-key [H-M-right] 'forward-word) +@end lisp + +@itemize @bullet + +@item Not all modifiers are permitted in all situations. @key{Hyper}, +@key{Super}, and @key{Alt} are available only under X (provided there +are such keys). Non-ASCII keys and mouse events (e.g. @kbd{C-=} and +@kbd{mouse-1}) also fall under this category. + +@end itemize + +@xref{Binding keys to commands} for general key binding instructions. + +@node Meta key does not work in xterm, ExtendChar key does not work as Meta, Binding combinations of modifiers and function keys, Key bindings +@section Why doesn't my @key{Meta} key work in an xterm window? +@cindex @key{Meta} key and xterm +@cindex Xterm and @key{Meta} key + +Try all of these methods before asking for further help: + +@itemize @bullet + +@item +You may have big problems using @file{mwm} as your window manager. +(Does anyone know a good generic solution to allow the use of the +@key{Meta} key in Emacs with @file{mwm}?) + +@item +For X11: Make sure it really is a @key{Meta} key. Use @file{xev} to +find out what keysym your @key{Meta} key generates. It should be either +@key{Meta}_L or @key{Meta}_R. If it isn't, use @file{xmodmap} to fix +the situation. + +@item +Make sure the pty the xterm is using is passing 8 bit characters. +@samp{stty -a} (or @samp{stty everything}) should show @samp{cs8} somewhere. +If it shows @samp{cs7} instead, use @samp{stty cs8 -istrip} (or @samp{stty +pass8}) to fix it. + +@item +If there is an rlogin connection between the xterm and the Emacs, the +"-8" argument may need to be given to rlogin to make it pass all 8 bits +of every character. + +@item +If the Emacs is running under Ultrix, it is reported that evaluating +@code{(set-input-mode t nil)} helps. + +@item +If all else fails, you can make xterm generate @kbd{@key{ESC} W} when +you type @kbd{M-W}, which is the same conversion Emacs would make if it +got the @kbd{M-W} anyway. In X11R4, the following resource +specification will do this: + +@example +XTerm.VT100.EightBitInput: false +@end example + +(This changes the behavior of the @code{insert-eight-bit} action.) + +With older xterms, you can specify this behavior with a translation: + +@example +XTerm.VT100.Translations: #override \ + Meta: string(0x1b) insert() +@end example + +You might have to replace @samp{Meta} with @samp{Alt}. + +@end itemize + +@node ExtendChar key does not work as Meta, , Meta key does not work in xterm, Key bindings +@section Why doesn't my @key{ExtendChar} key work as a @key{Meta} key under HP-UX 8.0 and 9.x? +@cindex @key{ExtendChar} key as @key{Meta} +@cindex @key{Meta}, using @key{ExtendChar} for + +This is a result of an internationalization extension in X11R4 and the +fact that HP is now using this extension. Emacs assumes that +XLookupString returns the same result regardless of the @key{Meta} key +state which is no longer necessarily true. Until Emacs is fixed, the +temporary kludge is to run this command after each time the X server is +started but preferably before any xterm clients are: + +@example +xmodmap -e 'remove mod1 = Mode_switch' +@end example + +This will disable the use of the extra keysyms systemwide, which may be +undesirable if you actually intend to use them. + +@c ------------------------------------------------------------ +@node Alternate character sets, Mail and news, Key bindings, Top +@chapter Alternate character sets +@cindex Alternate character sets + +@menu +* Emacs does not display 8-bit characters:: +* Inputting eight-bit characters:: +* Kanji and Chinese characters:: +* Right-to-left alphabets:: +@end menu + +@node Emacs does not display 8-bit characters, Inputting eight-bit characters, Alternate character sets, Alternate character sets +@section How do I make Emacs display 8-bit characters? +@cindex Displaying eight-bit characters +@cindex Eight-bit characters, displaying + +Emacs 19 has built-in support for eight-bit characters. See +@inforef{European Display, European Display, emacs}, from which this +excerpt is taken: + +@quotation +Some European languages use accented letters and other special symbols. +The ISO 8859 Latin-1 character set defines character codes for many +European languages in the range 160 to 255. + +Emacs can display those characters according to Latin-1, provided the +terminal or font in use supports them. The @kbd{M-x +standard-display-european} command toggles European character display +mode. With a numeric argument, @kbd{M-x standard-display-european} +enables European character display if and only if the argument is +positive. + +Some operating systems let you specify the language you are using by +setting a locale. Emacs handles one common special case of this: if +your locale name for character types contains the string "8859-1" or +"88591", Emacs automatically enables European character display mode +when it starts up. +@end quotation + +@node Inputting eight-bit characters, Kanji and Chinese characters, Emacs does not display 8-bit characters, Alternate character sets +@section How do I input eight-bit characters? +@cindex Entering eight-bit characters +@cindex Eight-bit characters, entering + +@inforef{European Display, European Display, emacs}, from which this is +taken: + +@quotation +If you enter non-ASCII ISO Latin-1 characters often, you might find ISO +Accents mode convenient. When this minor mode is enabled, @key{`}, +@key{'}, @key{"}, @key{^}, @key{/} and @key{~} modify the following +letter by adding the corresponding diacritical mark to it, if possible. +To enable or disable ISO Accents mode, use the command @kbd{M-x +iso-accents-mode}. This command affects only the current buffer. + +To enter one of those six special characters, type the character, +followed by a space. Some of those characters have a corresponding +"dead key" accent character in the ISO Latin-1 character set; to enter +that character, type the corresponding ASCII character twice. For +example, @kbd{''} enters the Latin-1 character acute-accent (character +code 0264). +@end quotation + +@node Kanji and Chinese characters, Right-to-left alphabets, Inputting eight-bit characters, Alternate character sets +@section Where can I get an Emacs that handles kanji, Chinese, or other character sets? +@cindex Kanji, handling with Emacs +@cindex Chinese, handling with Emacs +@cindex Japanese, handling with Emacs +@cindex Korean, handling with Emacs + +Emacs 20 now includes many of the features of MULE, the Multilingual +Enhancement of Emacs. @xref{Installing Emacs} for information on where +to find and download Emacs. + +@node Right-to-left alphabets, , Kanji and Chinese characters, Alternate character sets +@section Where is an Emacs that can handle Semitic (right-to-left) alphabets? +@cindex Right-to-left alphabets +@cindex Hebrew, handling with Emacs +@cindex Semitic alphabets + +Emacs 20 supports Hebrew characters (ISO 8859-8), but does not yet +support right-to-left character entry. + +@email{joel@@exc.com, Joel M. Hoffman} has written a Lisp package called +@file{hebrew.el} that allows right-to-left editing of Hebrew. It +reportedly works out of the box with Emacs 19, but requires patches for +Emacs 18. Write to Joel if you want the patches or package. + +@file{hebrew.el} requires a Hebrew screen font, but no other Hardware support. +Joel has a screen font for PCs running MS-DOS and Linux. + +You might also try to query archie for files named with "hebrew"; +several ftp sites in Israel may also have the necessary files. + +@c ------------------------------------------------------------ +@node Mail and news, Concept index, Alternate character sets, Top +@chapter Mail and news +@cindex Mail and news + +@menu +* Changing the included text prefix:: +* Saving a copy of outgoing mail:: +* Expanding aliases when sending mail:: +* Rmail thinks all messages are one big one:: +* Sorting the messages in an Rmail folder:: +* Rmail writes to /usr/spool/mail:: +* Recovering mail files when Rmail munges them:: +* Replying to the sender of a message:: +* MIME with Emacs mail packages:: +* Automatically starting a mail or news reader:: +* Reading news with Emacs:: +* Gnus does not work with NNTP:: +* Viewing articles with embedded underlining:: +* Saving a multi-part Gnus posting:: +* Starting Gnus faster:: +* Catching up in all newsgroups:: +* Killing based on nonstandard headers:: +* Removing flashing messages:: +* Catch-up is slow in Gnus:: +* Gnus hangs for a long time:: +* Learning more about Gnus:: +@end menu + +@node Changing the included text prefix, Saving a copy of outgoing mail, Mail and news, Mail and news +@section How do I change the included text prefix in mail/news followups? +@cindex Prefix in mail/news followups, changing +@cindex Included text prefix, changing +@cindex Setting the included text character + +If you read mail with Rmail or news with Gnus, set the variable +@code{mail-yank-prefix}. For VM, set @code{vm-included-text-prefix}. +For mh-e, set @code{mh-ins-buf-prefix}. + +For fancier control of citations, use Supercite. @xref{Supercite}. + +To prevent Emacs from including various headers of the replied-to +message, set the value of @code{mail-yank-ignored-headers} to an +appropriate regexp. + +@node Saving a copy of outgoing mail, Expanding aliases when sending mail, Changing the included text prefix, Mail and news +@section How do I save a copy of outgoing mail? +@cindex Saving a copy of outgoing mail +@cindex Copying outgoing mail to a file +@cindex Filing outgoing mail +@cindex Automatic filing of outgoing mail +@cindex Mail, saving outgoing automatically + +You can either mail yourself a copy by including a @samp{BCC} header in the +mail message, or store a copy of the message directly to a file by +including an @samp{FCC} header. + +If you use standard mail, you can automatically create a @samp{BCC} to +yourself by putting + +@lisp +(setq mail-self-blind t) +@end lisp + +in your @file{.emacs} file. You can automatically include an "FCC:" field by +putting something like the following in your @file{.emacs} file: + +@lisp +(setq mail-archive-file-name (expand-file-name "~/outgoing")) +@end lisp + +The output file will be in Unix mail format, which can be read directly +by VM, but not always by Rmail. @xref{Learning how to do something}. + +If you use @code{mh-e}, add an @samp{FCC} or @samp{BCC} field to your +components file. + +It does not work to put "set record filename" in the @file{.mailrc} +file. + +@node Expanding aliases when sending mail, Rmail thinks all messages are one big one, Saving a copy of outgoing mail, Mail and news +@section Why doesn't Emacs expand my aliases when sending mail? +@cindex Expanding aliases when sending mail +@cindex Mail alias expansion +@cindex Sending mail with aliases + +@itemize @bullet + +@item +You must separate multiple addresses in the headers of the mail buffer +with commas. This is because Emacs supports RFC822 standard addresses +like this one: + +@example +To: Willy Smith +@end example + +However, you do not need to --- and probably should not, unless your +system's version of @file{/usr/ucb/mail} (aka mailx) supports RFC822 +-- separate addresses with commas in your @file{~/.mailrc} file. + +@item +Emacs normally only reads the @file{.mailrc} file once per session, +when you start to compose your first mail message. If you edit +.mailrc, you can type @kbd{M-x rebuild-mail-abbrevs @key{RET}} to +make Emacs reread @file{~/.mailrc}. + +@item +If you like, you can expand mail aliases as abbrevs, as soon as you +type them in. To enable this feature, execute the following: + +@lisp +(add-hook 'mail-setup-hook 'mail-abbrevs-setup) +@end lisp + +Note that the aliases are expanded automatically only after you type +@key{RET} or a punctuation character (e.g. @kbd{,}). You can force their +expansion by moving point to the end of the alias and typing @kbd{C-x a e} +@kbd{M-x expand-abbrev}. +@end itemize + +@node Rmail thinks all messages are one big one, Sorting the messages in an Rmail folder, Expanding aliases when sending mail, Mail and news +@section Why does Rmail think all my saved messages are one big message? +@cindex Rmail thinks all messages are one large message + +A file created through the @samp{FCC} field in a message is in Unix mail +format, not the format that Rmail uses (BABYL format). Rmail will try +to convert a Unix mail file into BABYL format on input, but sometimes it +makes errors. For guaranteed safety, you can make the +@file{saved-messages} file be an inbox for your Rmail file by using the +function @code{set-rmail-inbox-list}. + +@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 +@section How can I sort the messages in my Rmail folder? +@cindex Rmail, sorting messages in +@cindex Folder, sorting messages in an Rmail +@cindex Sorting messages in an Rmail folder + +In Rmail, type @kbd{C-c C-s C-h} to get a list of sorting functions +and their key bindings. + +@node Rmail writes to /usr/spool/mail, Recovering mail files when Rmail munges them, Sorting the messages in an Rmail folder, Mail and news +@section Why does Rmail need to write to @file{/usr/spool/mail}? +@cindex Rmail and @file{/usr/spool/mail} +@cindex @file{/usr/spool/mail} and Rmail + +This is the behavior of the @file{movemail} program which Rmail uses. +This indicates that @file{movemail} is configured to use lock files. + +RMS writes: + +@quotation +Certain systems require lock files to interlock access to mail files. +On these systems, @file{movemail} must write lock files, or you risk losing +mail. You simply must arrange to let @file{movemail} write them. + +Other systems use the flock system call to interlock access. On these +systems, you should configure @file{movemail} to use @code{flock}. +@end quotation + +@node Recovering mail files when Rmail munges them, Replying to the sender of a message, Rmail writes to /usr/spool/mail, Mail and news +@section How do I recover my mail files after Rmail munges their format? +@cindex Recovering munged mail files +@cindex Rmail munged my files +@cindex Mail files, recovering those munged by Rmail + +If you have just done @code{rmail-input} on a file and you don't want to +save it in Rmail's format (called BABYL), just kill the buffer (with +@kbd{C-x k}). + +If you typed @kbd{M-x rmail} and it read some messages out of your inbox +and you want to put them in a Unix mail file, use @kbd{C-o} on each +message. + +If you want to convert an existing file from BABYL format to Unix mail +format, use the command @kbd{M-x unrmail}: it will prompt you for the +input and output file names. + +@node Replying to the sender of a message, MIME with Emacs mail packages, Recovering mail files when Rmail munges them, Mail and news +@section How can I force Rmail to reply to the sender of a message, but not the other recipients? +@cindex Replying only to the sender of a message +@cindex Sender, replying only to +@cindex Rmail, replying to the sender of a message in + +@email{isaacson@@seas.upenn.edu, Ron Isaacson} says: When you hit +@key{r} to reply in Rmail, by default it CCs all of the original +recipients (everyone on the original @samp{To} and @samp{CC} +lists). With a prefix argument (i.e., typing @kbd{C-u} before @key{r}), +it replies only to the sender. However, going through the whole +@kbd{C-u} business every time you want to reply is a pain. This is the +best fix I've been able to come up with: + +@lisp +(defun rmail-reply-t () + "Reply only to the sender of the current message. (See rmail-reply.)" + (interactive) + (rmail-reply t)) + +(add-hook 'rmail-mode-hook + '(lambda () + (define-key rmail-mode-map "r" 'rmail-reply-t) + (define-key rmail-mode-map "R" 'rmail-reply))) +@end lisp + +@node MIME with Emacs mail packages, Automatically starting a mail or news reader, Replying to the sender of a message, Mail and news +@section How can I get my favorite Emacs mail package to support MIME? +@cindex MIME and Emacs mail packages +@cindex Mail packages and MIME +@cindex FAQ for MIME and Emacs + +Read the Emacs MIME FAQ, maintained by @email{trey@@cs.berkeley.edu, +MacDonald Hall Jackson} at + +@uref{http://bmrc.berkeley.edu/~trey/emacs/mime.html} + +Version 6.x of VM supports MIME. @xref{VM}. + +@node Automatically starting a mail or news reader, Reading news with Emacs, MIME with Emacs mail packages, Mail and news +@section How do I make Emacs automatically start my mail/news reader? +@cindex Mail reader, starting automatically +@cindex News reader, starting automatically +@cindex Starting mail/news reader automatically + +To start Emacs in Gnus: + +@example +emacs -f gnus +@end example + +in Rmail: + +@example +emacs -f rmail +@end example + +A more convenient way to start with Gnus: + +@example +alias gnus 'emacs -f gnus' +gnus +@end example + +It is probably unwise to automatically start your mail or news reader +from your @file{.emacs} file. This would cause problems if you needed to run +two copies of Emacs at one time. Also, this would make it difficult for +you to start Emacs quickly when you needed to. + +@node Reading news with Emacs, Gnus does not work with NNTP, Automatically starting a mail or news reader, Mail and news +@section How do I read news under Emacs? +@cindex Reading news under Emacs +@cindex Usenet reader in Emacs +@cindex Gnus newsreader + +Use @kbd{M-x gnus}. It is documented in Info (@pxref{Learning how to do something}). + +@node Gnus does not work with NNTP, Viewing articles with embedded underlining, Reading news with Emacs, Mail and news +@section Why doesn't Gnus work via NNTP? +@cindex Gnus and NNTP +@cindex NNTP, Gnus fails to work with + +There is a bug in NNTP version 1.5.10, such that when multiple requests +are sent to the NNTP server, the server only handles the first one +before blocking waiting for more input which never comes. NNTP version +1.5.11 claims to fix this. + +You can work around the bug inside Emacs like this: + +@lisp +(setq nntp-maximum-request 1) +@end lisp + +You can find out what version of NNTP your news server is running by +telnetting to the NNTP port (usually 119) on the news server machine +(i.e., "telnet server-machine 119"). The server should give its version +number in the welcome message. Type "quit" to get out. + +@xref{Spontaneous entry into isearch-mode} for some additional ideas. + +@node Viewing articles with embedded underlining, Saving a multi-part Gnus posting, Gnus does not work with NNTP, Mail and news +@section How do I view news articles with embedded underlining (e.g., ClariNews)? +@cindex Underlining, embedded in news articles +@cindex News articles with embedded underlining +@cindex Embedded underlining in news articles + +Underlining appears like this: + +@example +_^Hu_^Hn_^Hd_^He_^Hr_^Hl_^Hi_^Hn_^Hi_^Hn_^Hg +@end example + +@email{amanda@@iesd.auc.dk, Per Abrahamsen} suggests using the following +code, which uses the underline face to turn such text into true +underlining: + +@lisp +(defun gnus-article-prepare-overstrike () + ;; Prepare article for overstrike commands. + (save-excursion + (set-buffer gnus-article-buffer) + (let ((buffer-read-only nil)) + (goto-char (point-min)) + (while (search-forward "\b" nil t) + (let ((next (following-char)) + (previous (char-after (- (point) 2)))) + (cond ((eq next previous) + (delete-region (- (point) 2) (point)) + (put-text-property (point) (1+ (point)) + 'face 'bold)) + ((eq next ?_) + (delete-region (1- (point)) (1+ (point))) + (put-text-property (1- (point)) (point) + 'face 'underline)) + ((eq previous ?_) + (delete-region (- (point) 2) (point)) + (put-text-property (point) (1+ (point)) + 'face 'underline)))))))) + +(add-hook 'gnus-article-prepare-hook 'gnus-article-prepare-overstrike) +@end lisp + +If you prefer to do away with underlining altogether, you can +destructively remove it with @kbd{M-x ununderline-region}; do this +automatically via + +@lisp +(add-hook 'gnus-article-prepare-hook + '(lambda () (ununderline-region (point-min) (point-max)))) +@end lisp + +@node Saving a multi-part Gnus posting, Starting Gnus faster, Viewing articles with embedded underlining, Mail and news +@section How do I save all the items of a multi-part posting in Gnus? +@cindex Multi-part postings in Gnus, saving +@cindex Saving multi-part postings in Gnus +@cindex Gnus, saving multi-part postings in + +Use @code{gnus-uu}. Type @kbd{C-c C-v C-h} in the Gnus summary buffer +to see a list of available commands. + +@node Starting Gnus faster, Catching up in all newsgroups, Saving a multi-part Gnus posting, Mail and news +@section How do I make Gnus start up faster? +@cindex Faster, starting Gnus +@cindex Starting Gnus faster +@cindex Gnus, starting faster + +From the Gnus FAQ (@pxref{Learning more about Gnus}): + +@quotation +@email{pktiwari@@eos.ncsu.edu, Pranav Kumar Tiwari} writes: I posted +the same query recently and I got an answer to it. I am going to +repeat the answer. What you need is a newer version of gnus, version +5.0.4+. I am using 5.0.12 and it works fine with me with the +following settings: + +@lisp +(setq gnus-check-new-newsgroups nil + gnus-read-active-file 'some + gnus-nov-is-evil nil + gnus-select-method '(nntp gnus-nntp-server)) +@end lisp +@end quotation + +@node Catching up in all newsgroups, Killing based on nonstandard headers, Starting Gnus faster, Mail and news +@section How do I catch up all newsgroups in Gnus? +@cindex Catching up all newsgroups in Gnus +@cindex Gnus, Catching up all newsgroups in + +In the @file{*Newsgroup*} buffer, type @kbd{M-< C-x ( c y C-x ) M-0 C-x e} + +Leave off the initial @kbd{M-<} if you only want to catch up from point +to the end of the @file{*Newsgroup*} buffer. + +@node Killing based on nonstandard headers, Removing flashing messages, Catching up in all newsgroups, Mail and news +@section Why can't I kill in Gnus based on the Newsgroups/Keywords/Control headers? +@cindex Killing articles based on nonstandard headers +@cindex Newsgroups header, killing articles based on +@cindex Keywords header, killing articles based on +@cindex Control header, killing articles based on + +Gnus will complain that the @samp{Newsgroups}, @samp{Keywords}, and +@samp{Control} headers are "Unknown header" fields. + +For the @samp{Newsgroups} header, there is an easy workaround: kill on the +@samp{Xref} header instead, which will be present on any cross-posted article +(as long as your site carries the cross-post group). + +If you really want to kill on one of these headers, you can do it like +this: + +@lisp +(gnus-kill nil "^Newsgroups: .*\\(bad\\.group\\|worse\\.group\\)") +@end lisp + +@node Removing flashing messages, Catch-up is slow in Gnus, Killing based on nonstandard headers, Mail and news +@section How do I get rid of flashing messages in Gnus for slow connections? +@cindex Flashing Gnus messages, removing +@cindex Removing flashing Gnus messages +@cindex Slow connections causing flashing messages in Gnus +@cindex Gnus, flashing messages in + +Set @code{nntp-debug-read} to @code{nil}. + +@node Catch-up is slow in Gnus, Gnus hangs for a long time, Removing flashing messages, Mail and news +@section Why is catch up slow in Gnus? +@cindex Slow catch up in Gnus +@cindex Gnus is slow when catching up +@cindex Crosspostings make Gnus catching up slow + +Because Gnus is marking crosspostings read. You can control this with +the variable @code{gnus-use-cross-reference}. + +@node Gnus hangs for a long time, Learning more about Gnus, Catch-up is slow in Gnus, Mail and news +@section Why does Gnus hang for a long time when posting? +@cindex Hangs in Gnus +@cindex Gnus hangs while posting +@cindex Posting, Gnus hangs wile + +@email{tale@@uunet.uu.net, David Lawrence} explains: + +@quotation +The problem is almost always interaction between NNTP and C News. NNTP +POST asks C News's inews to not background itself but rather hang around +and give its exit status so it knows whether the post was successful. +(That wait will on some systems not return the exit status of the +waited for job is a different sort of problem.) It ends up taking a +long time because inews is calling relaynews, which often waits for +another relaynews to free the lock on the news system so it can file the +article. + +My preferred solution is to change inews to not call relaynews, but +rather use newsspool. This loses some error-catching functionality, but +is for the most part safe as inews will detect a lot of the errors on +its own. The C News folks have sped up inews, too, so speed should look +better to most folks as that update propagates around. +@end quotation + +@node Learning more about Gnus, , Gnus hangs for a long time, Mail and news +@section Where can I find out more about Gnus? +@cindex FAQ for Gnus +@cindex Gnus FAQ +@cindex Learning more about GNU + +Look for the Gnus FAQ, available at + +@uref{http://www.ccs.neu.edu/software/contrib/gnus/} + +@node Concept index, , Mail and news, Top +@unnumbered Concept Index +@printindex cp + +@contents +@bye