X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-19;h=ff8b3f6293f8f92cfd658708ec11576c284d3fb2;hb=c461477e9d1c45206851e095d1398498d09d040c;hp=6ee9d4f3f4839805bd9baa56a533ec0dd2fad883;hpb=81572e9b4653c5545c2eb43e87dec439f356c19c;p=chise%2Fxemacs-chise.git diff --git a/info/xemacs.info-19 b/info/xemacs.info-19 index 6ee9d4f..ff8b3f6 100644 --- a/info/xemacs.info-19 +++ b/info/xemacs.info-19 @@ -1,5 +1,5 @@ -This is Info file ../info/xemacs.info, produced by Makeinfo version -1.68 from the input file xemacs/xemacs.texi. +This is ../info/xemacs.info, produced by makeinfo version 4.0b from +xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -30,945 +30,577 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -File: xemacs.info, Node: Manifesto, Next: Key Index, Prev: Glossary, Up: Top - -The GNU Manifesto -***************** - -What's GNU? GNU's Not Unix! -============================ - - GNU, which stands for GNU's Not Unix, is the name for the complete -Unix-compatible software system which I am writing so that I can give it -away free to everyone who can use it. Several other volunteers are -helping me. Contributions of time, money, programs, and equipment are -greatly needed. - - So far we have an Emacs text editor with Lisp for writing editor -commands, a source level debugger, a yacc-compatible parser generator, -a linker, and around 35 utilities. A shell (command interpreter) is -nearly completed. A new portable optimizing C compiler has compiled -itself and may be released this year. An initial kernel exists, but -many more features are needed to emulate Unix. When the kernel and -compiler are finished, it will be possible to distribute a GNU system -suitable for program development. We will use TeX as our text -formatter, but an nroff is being worked on. We will use the free, -portable X window system as well. After this we will add a portable -Common Lisp, an Empire game, a spreadsheet, and hundreds of other -things, plus online documentation. We hope to supply, eventually, -everything useful that normally comes with a Unix system, and more. - - GNU will be able to run Unix programs, but will not be identical to -Unix. We will make all improvements that are convenient, based on our -experience with other operating systems. In particular, we plan to -have longer filenames, file version numbers, a crashproof file system, -filename completion perhaps, terminal-independent display support, and -perhaps eventually a Lisp-based window system through which several -Lisp programs and ordinary Unix programs can share a screen. Both C -and Lisp will be available as system programming languages. We will -try to support UUCP, MIT Chaosnet, and Internet protocols for -communication. - - GNU is aimed initially at machines in the 68000/16000 class with -virtual memory, because they are the easiest machines to make it run -on. The extra effort to make it run on smaller machines will be left -to someone who wants to use it on them. - - To avoid horrible confusion, please pronounce the `G' in the word -`GNU' when it is the name of this project. - -Why I Must Write GNU -==================== - - I consider that the golden rule requires that if I like a program I -must share it with other people who like it. Software sellers want to -divide the users and conquer them, making each user agree not to share -with others. I refuse to break solidarity with other users in this -way. I cannot in good conscience sign a nondisclosure agreement or a -software license agreement. For years I worked within the Artificial -Intelligence Lab to resist such tendencies and other inhospitalities, -but eventually they had gone too far: I could not remain in an -institution where such things are done for me against my will. - - So that I can continue to use computers without dishonor, I have -decided to put together a sufficient body of free software so that I -will be able to get along without any software that is not free. I -have resigned from the AI lab to deny MIT any legal excuse to prevent -me from giving GNU away. - -Why GNU Will Be Compatible With Unix -==================================== - - Unix is not my ideal system, but it is not too bad. The essential -features of Unix seem to be good ones, and I think I can fill in what -Unix lacks without spoiling them. And a system compatible with Unix -would be convenient for many other people to adopt. - -How GNU Will Be Available -========================= - - GNU is not in the public domain. Everyone will be permitted to -modify and redistribute GNU, but no distributor will be allowed to -restrict its further redistribution. That is to say, proprietary -modifications will not be allowed. I want to make sure that all -versions of GNU remain free. - -Why Many Other Programmers Want to Help -======================================= - - I have found many other programmers who are excited about GNU and -want to help. - - Many programmers are unhappy about the commercialization of system -software. It may enable them to make more money, but it requires them -to feel in conflict with other programmers in general rather than feel -as comrades. The fundamental act of friendship among programmers is the -sharing of programs; marketing arrangements now typically used -essentially forbid programmers to treat others as friends. The -purchaser of software must choose between friendship and obeying the -law. Naturally, many decide that friendship is more important. But -those who believe in law often do not feel at ease with either choice. -They become cynical and think that programming is just a way of making -money. - - By working on and using GNU rather than proprietary programs, we can -be hospitable to everyone and obey the law. In addition, GNU serves as -an example to inspire and a banner to rally others to join us in -sharing. This can give us a feeling of harmony which is impossible if -we use software that is not free. For about half the programmers I -talk to, this is an important happiness that money cannot replace. - -How You Can Contribute -====================== - - I am asking computer manufacturers for donations of machines and -money. I'm asking individuals for donations of programs and work. - - One consequence you can expect if you donate machines is that GNU -will run on them at an early date. The machines should be complete, -ready-to-use systems, approved for use in a residential area, and not -in need of sophisticated cooling or power. - - I have found very many programmers eager to contribute part-time -work for GNU. For most projects, such part-time distributed work would -be very hard to coordinate; the independently-written parts would not -work together. But for the particular task of replacing Unix, this -problem is absent. A complete Unix system contains hundreds of utility -programs, each of which is documented separately. Most interface -specifications are fixed by Unix compatibility. If each contributor -can write a compatible replacement for a single Unix utility, and make -it work properly in place of the original on a Unix system, then these -utilities will work right when put together. Even allowing for Murphy -to create a few unexpected problems, assembling these components will -be a feasible task. (The kernel will require closer communication and -will be worked on by a small, tight group.) - - If I get donations of money, I may be able to hire a few people full -or part time. The salary won't be high by programmers' standards, but -I'm looking for people for whom building community spirit is as -important as making money. I view this as a way of enabling dedicated -people to devote their full energies to working on GNU by sparing them -the need to make a living in another way. - -Why All Computer Users Will Benefit -=================================== - - Once GNU is written, everyone will be able to obtain good system -software free, just like air. - - This means much more than just saving everyone the price of a Unix -license. It means that much wasteful duplication of system programming -effort will be avoided. This effort can go instead into advancing the -state of the art. - - Complete system sources will be available to everyone. As a result, -a user who needs changes in the system will always be free to make them -himself, or hire any available programmer or company to make them for -him. Users will no longer be at the mercy of one programmer or company -which owns the sources and is in sole position to make changes. - - Schools will be able to provide a much more educational environment -by encouraging all students to study and improve the system code. -Harvard's computer lab used to have the policy that no program could be -installed on the system if its sources were not on public display, and -upheld it by actually refusing to install certain programs. I was very -much inspired by this. - - Finally, the overhead of considering who owns the system software -and what one is or is not entitled to do with it will be lifted. - - Arrangements to make people pay for using a program, including -licensing of copies, always incur a tremendous cost to society through -the cumbersome mechanisms necessary to figure out how much (that is, -which programs) a person must pay for. And only a police state can -force everyone to obey them. Consider a space station where air must -be manufactured at great cost: charging each breather per liter of air -may be fair, but wearing the metered gas mask all day and all night is -intolerable even if everyone can afford to pay the air bill. And the -TV cameras everywhere to see if you ever take the mask off are -outrageous. It's better to support the air plant with a head tax and -chuck the masks. - - Copying all or parts of a program is as natural to a programmer as -breathing, and as productive. It ought to be as free. - -Some Easily Rebutted Objections to GNU's Goals -============================================== - - "Nobody will use it if it is free, because that means they can't - rely on any support." - - "You have to charge for the program to pay for providing the - support." - - If people would rather pay for GNU plus service than get GNU free -without service, a company to provide just service to people who have -obtained GNU free ought to be profitable. - - We must distinguish between support in the form of real programming -work and mere handholding. The former is something one cannot rely on -from a software vendor. If your problem is not shared by enough -people, the vendor will tell you to get lost. - - If your business needs to be able to rely on support, the only way -is to have all the necessary sources and tools. Then you can hire any -available person to fix your problem; you are not at the mercy of any -individual. With Unix, the price of sources puts this out of -consideration for most businesses. With GNU this will be easy. It is -still possible for there to be no available competent person, but this -problem cannot be blamed on distibution arrangements. GNU does not -eliminate all the world's problems, only some of them. - - Meanwhile, the users who know nothing about computers need -handholding: doing things for them which they could easily do -themselves but don't know how. - - Such services could be provided by companies that sell just -hand-holding and repair service. If it is true that users would rather -spend money and get a product with service, they will also be willing -to buy the service having got the product free. The service companies -will compete in quality and price; users will not be tied to any -particular one. Meanwhile, those of us who don't need the service -should be able to use the program without paying for the service. - - "You cannot reach many people without advertising, and you must - charge for the program to support that." - - "It's no use advertising a program people can get free." - - There are various forms of free or very cheap publicity that can be -used to inform numbers of computer users about something like GNU. But -it may be true that one can reach more microcomputer users with -advertising. If this is really so, a business which advertises the -service of copying and mailing GNU for a fee ought to be successful -enough to pay for its advertising and more. This way, only the users -who benefit from the advertising pay for it. - - On the other hand, if many people get GNU from their friends, and -such companies don't succeed, this will show that advertising was not -really necessary to spread GNU. Why is it that free market advocates -don't want to let the free market decide this? - - "My company needs a proprietary operating system to get a - competitive edge." - - GNU will remove operating system software from the realm of -competition. You will not be able to get an edge in this area, but -neither will your competitors be able to get an edge over you. You and -they will compete in other areas, while benefitting mutually in this -one. If your business is selling an operating system, you will not -like GNU, but that's tough on you. If your business is something else, -GNU can save you from being pushed into the expensive business of -selling operating systems. - - I would like to see GNU development supported by gifts from many -manufacturers and users, reducing the cost to each. - - "Don't programmers deserve a reward for their creativity?" - - If anything deserves a reward, it is social contribution. -Creativity can be a social contribution, but only in so far as society -is free to use the results. If programmers deserve to be rewarded for -creating innovative programs, by the same token they deserve to be -punished if they restrict the use of these programs. - - "Shouldn't a programmer be able to ask for a reward for his - creativity?" - - There is nothing wrong with wanting pay for work, or seeking to -maximize one's income, as long as one does not use means that are -destructive. But the means customary in the field of software today -are based on destruction. - - Extracting money from users of a program by restricting their use of -it is destructive because the restrictions reduce the amount and the -ways that the program can be used. This reduces the amount of wealth -that humanity derives from the program. When there is a deliberate -choice to restrict, the harmful consequences are deliberate destruction. - - The reason a good citizen does not use such destructive means to -become wealthier is that, if everyone did so, we would all become -poorer from the mutual destructiveness. This is Kantian ethics; or, -the Golden Rule. Since I do not like the consequences that result if -everyone hoards information, I am required to consider it wrong for one -to do so. Specifically, the desire to be rewarded for one's creativity -does not justify depriving the world in general of all or part of that -creativity. - - "Won't programmers starve?" - - I could answer that nobody is forced to be a programmer. Most of us -cannot manage to get any money for standing on the street and making -faces. But we are not, as a result, condemned to spend our lives -standing on the street making faces, and starving. We do something -else. - - But that is the wrong answer because it accepts the questioner's -implicit assumption: that without ownership of software, programmers -cannot possibly be paid a cent. Supposedly it is all or nothing. - - The real reason programmers will not starve is that it will still be -possible for them to get paid for programming; just not paid as much as -now. - - Restricting copying is not the only basis for business in software. -It is the most common basis because it brings in the most money. If it -were prohibited, or rejected by the customer, software business would -move to other bases of organization which are now used less often. -There are always numerous ways to organize any kind of business. - - Probably programming will not be as lucrative on the new basis as it -is now. But that is not an argument against the change. It is not -considered an injustice that sales clerks make the salaries that they -now do. If programmers made the same, that would not be an injustice -either. (In practice they would still make considerably more than -that.) - - "Don't people have a right to control how their creativity is - used?" - - "Control over the use of one's ideas" really constitutes control over -other people's lives; and it is usually used to make their lives more -difficult. - - People who have studied the issue of intellectual property rights -carefully (such as lawyers) say that there is no intrinsic right to -intellectual property. The kinds of supposed intellectual property -rights that the government recognizes were created by specific acts of -legislation for specific purposes. - - For example, the patent system was established to encourage -inventors to disclose the details of their inventions. Its purpose was -to help society rather than to help inventors. At the time, the life -span of 17 years for a patent was short compared with the rate of -advance of the state of the art. Since patents are an issue only among -manufacturers, for whom the cost and effort of a license agreement are -small compared with setting up production, the patents often do not do -much harm. They do not obstruct most individuals who use patented -products. - - The idea of copyright did not exist in ancient times, when authors -frequently copied other authors at length in works of non-fiction. This -practice was useful, and is the only way many authors' works have -survived even in part. The copyright system was created expressly for -the purpose of encouraging authorship. In the domain for which it was -invented--books, which could be copied economically only on a printing -press--it did little harm, and did not obstruct most of the individuals -who read the books. - - All intellectual property rights are just licenses granted by society -because it was thought, rightly or wrongly, that society as a whole -would benefit by granting them. But in any particular situation, we -have to ask: are we really better off granting such license? What kind -of act are we licensing a person to do? - - The case of programs today is very different from that of books a -hundred years ago. The fact that the easiest way to copy a program is -from one neighbor to another, the fact that a program has both source -code and object code which are distinct, and the fact that a program is -used rather than read and enjoyed, combine to create a situation in -which a person who enforces a copyright is harming society as a whole -both materially and spiritually; in which a person should not do so -regardless of whether the law enables him to. - - "Competition makes things get done better." - - The paradigm of competition is a race: by rewarding the winner, we -encourage everyone to run faster. When capitalism really works this -way, it does a good job; but its defenders are wrong in assuming it -always works this way. If the runners forget why the reward is offered -and become intent on winning, no matter how, they may find other -strategies--such as, attacking other runners. If the runners get into -a fist fight, they will all finish late. - - Proprietary and secret software is the moral equivalent of runners -in a fist fight. Sad to say, the only referee we've got does not seem -to object to fights; he just regulates them ("For every ten yards you -run, you can fire one shot"). He really ought to break them up, and -penalize runners for even trying to fight. - - "Won't everyone stop programming without a monetary incentive?" - - Actually, many people will program with absolutely no monetary -incentive. Programming has an irresistible fascination for some -people, usually the people who are best at it. There is no shortage of -professional musicians who keep at it even though they have no hope of -making a living that way. - - But really this question, though commonly asked, is not appropriate -to the situation. Pay for programmers will not disappear, only become -less. So the right question is, will anyone program with a reduced -monetary incentive? My experience shows that they will. - - For more than ten years, many of the world's best programmers worked -at the Artificial Intelligence Lab for far less money than they could -have had anywhere else. They got many kinds of non-monetary rewards: -fame and appreciation, for example. And creativity is also fun, a -reward in itself. - - Then most of them left when offered a chance to do the same -interesting work for a lot of money. - - What the facts show is that people will program for reasons other -than riches; but if given a chance to make a lot of money as well, they -will come to expect and demand it. Low-paying organizations do poorly -in competition with high-paying ones, but they do not have to do badly -if the high-paying ones are banned. - - "We need the programmers desperately. If they demand that we stop - helping our neighbors, we have to obey." - - You're never so desperate that you have to obey this sort of demand. -Remember: millions for defense, but not a cent for tribute! - - "Programmers need to make a living somehow." - - In the short run, this is true. However, there are plenty of ways -that programmers could make a living without selling the right to use a -program. This way is customary now because it brings programmers and -businessmen the most money, not because it is the only way to make a -living. It is easy to find other ways if you want to find them. Here -are a number of examples. - - A manufacturer introducing a new computer will pay for the porting of -operating systems onto the new hardware. - - The sale of teaching, hand-holding, and maintenance services could -also employ programmers. - - People with new ideas could distribute programs as freeware and ask -for donations from satisfied users or sell hand-holding services. I -have met people who are already working this way successfully. - - Users with related needs can form users' groups and pay dues. A -group would contract with programming companies to write programs that -the group's members would like to use. - - All sorts of development can be funded with a Software Tax: - - Suppose everyone who buys a computer has to pay a certain percent - of the price as a software tax. The government gives this to an - agency like the NSF to spend on software development. - - But if the computer buyer makes a donation to software development - himself, he can take a credit against the tax. He can donate to - the project of his own choosing--often, chosen because he hopes to - use the results when - - it is done. He can take a credit for any amount of donation up to - the total tax he had to pay. - - The total tax rate could be decided by a vote of the payers of the - tax, weighted according to the amount they will be taxed on. - - The consequences: - - * The computer-using community supports software development. - - * This community decides what level of support is needed. - - * Users who care which projects their share is spent on can - choose this for themselves. +File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources - In the long run, making programs free is a step toward the -post-scarcity world, where nobody will have to work very hard just to -make a living. People will be free to devote themselves to activities -that are fun, such as programming, after spending the necessary ten -hours a week on required tasks such as legislation, family counseling, -robot repair, and asteroid prospecting. There will be no need to be -able to make a living from programming. +Face Resources +-------------- - We have already greatly reduced the amount of work that the whole -society must do for its actual productivity, but only a little of this -has translated itself into leisure for workers because much -nonproductive activity is required to accompany productive activity. -The main causes of this are bureaucracy and isometric struggles against -competition. Free software will greatly reduce these drains in the -area of software production. We must do this, in order for technical -gains in productivity to translate into less work for us. + The attributes of faces are also per-frame. They can be specified as: + + Emacs.FACE_NAME.parameter: value + +or + + Emacs*FRAME_NAME.FACE_NAME.parameter: value + +Faces accept the following resources: + +`attributeFont' (class `AttributeFont'): font-name + The font of this face. + +`attributeForeground' (class `AttributeForeground'): color-name +`attributeBackground' (class `AttributeBackground'): color-name + The foreground and background colors of this face. + +`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name + The name of an XBM file (or XPM file, if your version of Emacs + supports XPM), to use as a background stipple. + +`attributeUnderline' (class `AttributeUnderline'): boolean + Whether text in this face should be underlined. + + All text is displayed in some face, defaulting to the face named +`default'. To set the font of normal text, use +`Emacs*default.attributeFont'. To set it in the frame named `fred', use +`Emacs*fred.default.attributeFont'. + + These are the names of the predefined faces: + +`default' + Everything inherits from this. + +`bold' + If this is not specified in the resource database, Emacs tries to + find a bold version of the font of the default face. + +`italic' + If this is not specified in the resource database, Emacs tries to + find an italic version of the font of the default face. + +`bold-italic' + If this is not specified in the resource database, Emacs tries to + find a bold-italic version of the font of the default face. + +`modeline' + This is the face that the modeline is displayed in. If not + specified in the resource database, it is determined from the + default face by reversing the foreground and background colors. + +`highlight' + This is the face that highlighted extents (for example, Info + cross-references and possible completions, when the mouse passes + over them) are displayed in. + +`left-margin' +`right-margin' + These are the faces that the left and right annotation margins are + displayed in. + +`zmacs-region' + This is the face that mouse selections are displayed in. + +`isearch' + This is the face that the matched text being searched for is + displayed in. + +`info-node' + This is the face of info menu items. If unspecified, it is copied + from `bold-italic'. + +`info-xref' + This is the face of info cross-references. If unspecified, it is + copied from `bold'. (Note that, when the mouse passes over a + cross-reference, the cross-reference's face is determined from a + combination of the `info-xref' and `highlight' faces.) + + Other packages might define their own faces; to see a list of all +faces, use any of the interactive face-manipulation commands such as +`set-face-font' and type `?' when you are prompted for the name of a +face. + + If the `bold', `italic', and `bold-italic' faces are not specified +in the resource database, then XEmacs attempts to derive them from the +font of the default face. It can only succeed at this if you have +specified the default font using the XLFD (X Logical Font Description) +format, which looks like + + *-courier-medium-r-*-*-*-120-*-*-*-*-*-* + +If you use any of the other, less strict font name formats, some of +which look like + + lucidasanstypewriter-12 + fixed + 9x13 + + then XEmacs won't be able to guess the names of the bold and italic +versions. All X fonts can be referred to via XLFD-style names, so you +should use those forms. See the man pages for `X(1)', `xlsfonts(1)', +and `xfontsel(1)'. + + +File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources + +Widgets +------- + + There are several structural widgets between the terminal EmacsFrame +widget and the top level ApplicationShell; the exact names and types of +these widgets change from release to release (for example, they changed +between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are +subject to further change in the future, so you should avoid mentioning +them in your resource database. The above-mentioned syntaxes should be +forward- compatible. As of 19.13, the exact widget hierarchy is as +follows: + + INVOCATION-NAME "shell" "container" FRAME-NAME + x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame" + + where INVOCATION-NAME is the terminal component of the name of the +XEmacs executable (usually `xemacs'), and `x-emacs-application-class' +is generally `Emacs'. + + +File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources + +Menubar Resources +----------------- + + As the menubar is implemented as a widget which is not a part of +XEmacs proper, it does not use the face mechanism for specifying fonts +and colors: It uses whatever resources are appropriate to the type of +widget which is used to implement it. + + If Emacs was compiled to use only the Lucid Motif-lookalike menu +widgets, then one way to specify the font of the menubar would be + + Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* + + If both the Lucid Motif-lookalike menu widgets and X Font Sets are +configured to allow multilingual menubars, then one uses + + *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \ + -*-*-*-*-*-*-*-120-*-jisx0208.1983-0 + + That would specify fonts for a Japanese menubar. Specifying only one +XLFD is acceptable; specifying more than one for a given registry +(language) is also allowed. When X Font Sets are configured, some .font +resources (eg, menubars) are ignored in favor of the corresponding +.fontSet resources. + + If the Motif library is being used, then one would have to use + + Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* + + because the Motif library uses the `fontList' resource name instead +of `font', which has subtly different semantics. + + The same is true of the scrollbars: They accept whichever resources +are appropriate for the toolkit in use.  -File: xemacs.info, Node: Key Index, Next: Command Index, Prev: Manifesto, Up: Top +File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top + +Quitting and Aborting +===================== + +`C-g' + Quit. Cancel running or partially typed command. + +`C-]' + Abort innermost recursive editing level and cancel the command + which invoked it (`abort-recursive-edit'). + +`M-x top-level' + Abort all recursive editing levels that are currently executing. + +`C-x u' + Cancel an already-executed command, usually (`undo'). + + There are two ways of cancelling commands which are not finished +executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x +top-level'. Quitting is cancelling a partially typed command or one +which is already running. Aborting is getting out of a recursive +editing level and cancelling the command that invoked the recursive +edit. + + Quitting with `C-g' is used for getting rid of a partially typed +command or a numeric argument that you don't want. It also stops a +running command in the middle in a relatively safe way, so you can use +it if you accidentally start executing a command that takes a long +time. In particular, it is safe to quit out of killing; either your +text will ALL still be there, or it will ALL be in the kill ring (or +maybe both). Quitting an incremental search does special things +documented under searching; in general, it may take two successive +`C-g' characters to get out of a search. `C-g' works by setting the +variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp +checks this variable frequently and quits if it is non-`nil'. `C-g' is +only actually executed as a command if it is typed while Emacs is +waiting for input. + + If you quit twice in a row before the first `C-g' is recognized, you +activate the "emergency escape" feature and return to the shell. *Note +Emergency Escape::. + + You can use `C-]' (`abort-recursive-edit') to get out of a recursive +editing level and cancel the command which invoked it. Quitting with +`C-g' does not do this, and could not do this because it is used to +cancel a partially typed command within the recursive editing level. +Both operations are useful. For example, if you are in the Emacs +debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric +argument, you can cancel that argument with `C-g' and remain in the +debugger. + + The command `M-x top-level' is equivalent to "enough" `C-]' commands +to get you out of all the levels of recursive edits that you are in. +`C-]' only gets you out one level at a time, but `M-x top-level' goes +out all levels at once. Both `C-]' and `M-x top-level' are like all +other commands and unlike `C-g' in that they are effective only when +Emacs is ready for a command. `C-]' is an ordinary key and has its +meaning only because of its binding in the keymap. *Note Recursive +Edit::. + + `C-x u' (`undo') is not strictly speaking a way of cancelling a +command, but you can think of it as cancelling a command already +finished executing. *Note Undo::. + + +File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top + +Dealing With Emacs Trouble +========================== -Key (Character) Index -********************* + This section describes various conditions in which Emacs fails to +work, and how to recognize them and correct them. * Menu: -* ! (query-replace): Query Replace. -* " (TeX mode): TeX Editing. -* , (query-replace): Query Replace. -* . (Calendar mode): Specified Dates. -* . (query-replace): Query Replace. -* ? (Calendar mode): General Calendar. -* ^ (query-replace): Query Replace. -* a (Calendar mode): Holidays. -* button1: Intro to Keystrokes. -* button1up: Intro to Keystrokes. -* button2: Intro to Keystrokes. -* button2up: Intro to Keystrokes. -* button3: Intro to Keystrokes. -* button3up: Intro to Keystrokes. -* C-<: Setting Mark. -* C->: Setting Mark. -* C-@ (Calendar mode): Mark and Region. -* C-\: Select Input Method. -* C-] <1>: Quitting. -* C-]: Recursive Edit. -* C-_: Undo. -* C-a: Basic. -* C-a (Calendar mode): Move to Beginning or End. -* C-b: Basic. -* C-b (Calendar mode): Calendar Unit Motion. -* C-c: Key Sequences. -* C-c ' (Picture mode): Insert in Picture. -* C-c . (Picture mode): Insert in Picture. -* C-c / (Picture mode): Insert in Picture. -* C-c ; (Fortran mode): Fortran Comments. -* C-c < (Picture mode): Insert in Picture. -* C-c > (Picture mode): Insert in Picture. -* C-c \ (Picture mode): Insert in Picture. -* C-c ^ (Picture mode): Insert in Picture. -* C-c ` (Picture mode): Insert in Picture. -* C-c C-\ (Shell mode): Shell Mode. -* C-c C-b (Outline mode): Outline Motion. -* C-c C-b (Picture mode): Insert in Picture. -* C-c C-b (TeX mode): TeX Print. -* C-c C-c (Edit Abbrevs): Editing Abbrevs. -* C-c C-c (Edit Tab Stops): Tab Stops. -* C-c C-c (Mail mode): Mail Mode. -* C-c C-c (Occur mode): Other Repeating Search. -* C-c C-c (Shell mode): Shell Mode. -* C-c C-d (Picture mode): Basic Picture. -* C-c C-d (Shell mode): Shell Mode. -* C-c C-f (LaTeX mode): TeX Editing. -* C-c C-f (Outline mode): Outline Motion. -* C-c C-f (Picture mode): Insert in Picture. -* C-c C-f C-c (Mail mode): Mail Mode. -* C-c C-f C-s (Mail mode): Mail Mode. -* C-c C-f C-t (Mail mode): Mail Mode. -* C-c C-h (Outline mode): Outline Visibility. -* C-c C-i (Outline mode): Outline Visibility. -* C-c C-j (Term mode): Term Mode. -* C-c C-k (Picture mode): Rectangles in Picture. -* C-c C-k (Term mode): Term Mode. -* C-c C-k (TeX mode): TeX Print. -* C-c C-l (Calendar mode): General Calendar. -* C-c C-l (TeX mode): TeX Print. -* C-c C-n (Fortran mode): Fortran Motion. -* C-c C-n (Outline mode): Outline Motion. -* C-c C-o (Shell mode): Shell Mode. -* C-c C-p (Fortran mode): Fortran Motion. -* C-c C-p (Outline mode): Outline Motion. -* C-c C-p (TeX mode): TeX Print. -* C-c C-q (Mail mode): Mail Mode. -* C-c C-q (Term mode): Paging in Term. -* C-c C-q (TeX mode): TeX Print. -* C-c C-r (Fortran mode): Fortran Columns. -* C-c C-r (Shell mode): Shell Mode. -* C-c C-r (TeX mode): TeX Print. -* C-c C-s (Mail mode): Mail Mode. -* C-c C-s (Outline mode): Outline Visibility. -* C-c C-u (Outline mode): Outline Motion. -* C-c C-u (Shell mode): Shell Mode. -* C-c C-w (Fortran mode): Fortran Columns. -* C-c C-w (Mail mode): Mail Mode. -* C-c C-w (Picture mode): Rectangles in Picture. -* C-c C-w (Shell mode): Shell Mode. -* C-c C-x (Picture mode): Rectangles in Picture. -* C-c C-y (Mail mode): Mail Mode. -* C-c C-y (Picture mode): Rectangles in Picture. -* C-c C-y (Shell mode): Shell Mode. -* C-c C-z (Shell mode): Shell Mode. -* C-c TAB (Picture mode): Tabs in Picture. -* C-c { (TeX mode): TeX Editing. -* C-c } (TeX mode): TeX Editing. -* C-d: Killing. -* C-d (Shell mode): Shell Mode. -* C-e: Basic. -* C-e (Calendar mode): Move to Beginning or End. -* C-END: Basic. -* C-f: Basic. -* C-f (Calendar mode): Calendar Unit Motion. -* C-g <1>: Quitting. -* C-g: Minibuffer. -* C-g (isearch-mode): Incremental Search. -* C-h: Key Sequences. -* C-h a: Help. -* C-h b: Help. -* C-h C: Coding Systems. -* C-h c: Help. -* C-h C-\: Select Input Method. -* C-h C-c: Help. -* C-h C-d: Help. -* C-h C-w: Help. -* C-h f <1>: Documentation. -* C-h f: Help. -* C-h h: Mule Intro. -* C-h I: Select Input Method. -* C-h i: Help. -* C-h k: Help. -* C-h L: Language Environments. -* C-h l: Help. -* C-h m: Help. -* C-h n: Help. -* C-h s: Syntax Change. -* C-h t <1>: Help. -* C-h t: Basic. -* C-h v <1>: Examining. -* C-h v <2>: Documentation. -* C-h v: Help. -* C-h w: Help. -* C-HOME: Basic. -* C-k: Killing. -* C-l <1>: Scrolling. -* C-l: Basic. -* C-l (query-replace): Query Replace. -* C-LEFT: Basic. -* C-M-@ <1>: Lists. -* C-M-@: Marking Objects. -* C-M-\ <1>: Multi-line Indent. -* C-M-\: Indentation Commands. -* C-M-a: Defuns. -* C-M-a (Fortran mode): Fortran Motion. -* C-M-b: Lists. -* C-M-c: Recursive Edit. -* C-M-d: Lists. -* C-M-e: Defuns. -* C-M-e (Fortran mode): Fortran Motion. -* C-M-f: Lists. -* C-M-h <1>: Defuns. -* C-M-h: Marking Objects. -* C-M-h (Fortran mode): Fortran Motion. -* C-M-k <1>: Lists. -* C-M-k: Killing. -* C-M-n: Lists. -* C-M-o: Indentation Commands. -* C-M-p: Lists. -* C-M-q: Multi-line Indent. -* C-M-q (Fortran mode): ForIndent Commands. -* C-M-t <1>: Lists. -* C-M-t: Transpose. -* C-M-u: Lists. -* C-M-v <1>: Other Window. -* C-M-v: Minibuffer Edit. -* C-M-w: Appending Kills. -* C-M-x <1>: External Lisp. -* C-M-x: Lisp Eval. -* C-n: Basic. -* C-n (Calendar mode): Calendar Unit Motion. -* C-o: Blank Lines. -* C-p: Basic. -* C-p (Calendar mode): Calendar Unit Motion. -* C-q: Basic. -* C-q (isearch-mode): Incremental Search. -* C-r: Incremental Search. -* C-r (isearch-mode): Incremental Search. -* C-r (query-replace): Query Replace. -* C-RIGHT: Basic. -* C-s: Incremental Search. -* C-s (isearch-mode): Incremental Search. -* C-SPC: Setting Mark. -* C-SPC (Calendar mode): Mark and Region. -* C-t <1>: Transpose. -* C-t: Basic. -* C-u: Arguments. -* C-u - C-x ;: Comments. -* C-u C-@: Mark Ring. -* C-u C-SPC: Mark Ring. -* C-u C-x v v: Editing with VC. -* C-u TAB: Multi-line Indent. -* C-v <1>: Scrolling. -* C-v: Basic. -* C-v (Calendar mode): Scroll Calendar. -* C-w: Killing. -* C-w (isearch-mode): Incremental Search. -* C-w (query-replace): Query Replace. -* C-x: Key Sequences. -* C-x $: Selective Display. -* C-x (: Basic Kbd Macro. -* C-x ): Basic Kbd Macro. -* C-x .: Fill Prefix. -* C-x 0: Change Window. -* C-x 1: Change Window. -* C-x 2: Split Window. -* C-x 3: Split Window. -* C-x 4: Pop Up Window. -* C-x 4 .: Find Tag. -* C-x 4 b: Select Buffer. -* C-x 4 d: Dired Enter. -* C-x 4 f: Visiting. -* C-x 4 m: Sending Mail. -* C-x 5 b: Select Buffer. -* C-x 5 C-f: Visiting. -* C-x ;: Comments. -* C-x <: Horizontal Scrolling. -* C-x < (Calendar mode): Scroll Calendar. -* C-x =: Position Info. -* C-x >: Horizontal Scrolling. -* C-x > (Calendar mode): Scroll Calendar. -* C-x [: Pages. -* C-x [ (Calendar mode): Calendar Unit Motion. -* C-x ]: Pages. -* C-x ] (Calendar mode): Calendar Unit Motion. -* C-x ^: Change Window. -* C-x `: Compilation. -* C-x a g: Defining Abbrevs. -* C-x a i g: Defining Abbrevs. -* C-x a i l: Defining Abbrevs. -* C-x a l: Defining Abbrevs. -* C-x b: Select Buffer. -* C-x C-b: List Buffers. -* C-x C-c: Exiting. -* C-x C-d: ListDir. -* C-x C-e: Lisp Eval. -* C-x C-l: Case. -* C-x C-o <1>: Killing. -* C-x C-o: Blank Lines. -* C-x C-p <1>: Pages. -* C-x C-p: Marking Objects. -* C-x C-q: Misc Buffer. -* C-x C-q (version control): Editing with VC. -* C-x C-s: Saving. -* C-x C-t: Transpose. -* C-x C-u: Case. -* C-x C-v: Visiting. -* C-x C-w: Saving. -* C-x C-x: Setting Mark. -* C-x C-x (Calendar mode): Mark and Region. -* C-x d: Dired Enter. -* C-x DEL <1>: Sentences. -* C-x DEL <2>: Kill Errors. -* C-x DEL: Killing. -* C-x e: Basic Kbd Macro. -* C-x ESC ESC: Repetition. -* C-x f: Fill Commands. -* C-x h: Marking Objects. -* C-x k: Kill Buffer. -* C-x l: Pages. -* C-x m: Sending Mail. -* C-x n n: Narrowing. -* C-x n w: Narrowing. -* C-x o: Other Window. -* C-x q: Kbd Macro Query. -* C-x r +: RegNumbers. -* C-x r b: Bookmarks. -* C-x r g: RegText. -* C-x r i: RegText. -* C-x r j: RegPos. -* C-x r l: Bookmarks. -* C-x r m: Bookmarks. -* C-x r n: RegNumbers. -* C-x r r: RegRect. -* C-x r s: RegText. -* C-x r SPC: RegPos. -* C-x r w: RegConfig. -* C-x RET: Mule Intro. -* C-x RET c: Specify Coding. -* C-x RET C-\: Select Input Method. -* C-x RET f: Specify Coding. -* C-x RET k: Specify Coding. -* C-x RET p: Specify Coding. -* C-x RET t: Specify Coding. -* C-x s: Saving. -* C-x TAB: Indentation Commands. -* C-x u: Undo. -* C-x v =: Old Versions. -* C-x v a: Change Logs and VC. -* C-x v c: Editing with VC. -* C-x v d: VC Status. -* C-x v h: Version Headers. -* C-x v i: Editing with VC. -* C-x v l: VC Status. -* C-x v r: Making Snapshots. -* C-x v s: Making Snapshots. -* C-x v u: Editing with VC. -* C-x v ~: Old Versions. -* C-x }: Change Window. -* C-y: Kill Ring. -* C-y (isearch-mode): Incremental Search. -* C-z: Exiting. -* control key: Intro to Keystrokes. -* d (Calendar mode): Diary Commands. -* DEL <1>: Program Modes. -* DEL <2>: Major Modes. -* DEL <3>: Kill Errors. -* DEL <4>: Killing. -* DEL: Basic. -* DEL (isearch-mode): Incremental Search. -* DEL (query-replace): Query Replace. -* DOWN: Basic. -* END: Basic. -* ESC <1>: Meta Key. -* ESC: Key Sequences. -* ESC (query-replace): Query Replace. -* g CHAR (Calendar mode): From Other Calendar. -* g d (Calendar mode): Specified Dates. -* g m l (Calendar mode): Mayan Calendar. -* h (Calendar mode): Holidays. -* HOME: Basic. -* hyper key <1>: Super and Hyper Keys. -* hyper key <2>: Representing Keystrokes. -* hyper key: Intro to Keystrokes. -* i a (Calendar mode): Special Diary Entries. -* i b (Calendar mode): Special Diary Entries. -* i c (Calendar mode): Special Diary Entries. -* i d (Calendar mode): Adding to Diary. -* i m (Calendar mode): Adding to Diary. -* i w (Calendar mode): Adding to Diary. -* i y (Calendar mode): Adding to Diary. -* LEFT: Basic. -* LFD <1>: Basic Indent. -* LFD <2>: Major Modes. -* LFD: String Key Sequences. -* LFD (TeX mode): TeX Editing. -* m (Calendar mode): Diary Commands. -* M (Calendar mode): Lunar Phases. -* M-!: Single Shell. -* M-$: Spelling. -* M-%: Query Replace. -* M-': Expanding Abbrevs. -* M-(: Balanced Editing. -* M-): Balanced Editing. -* M-,: Tags Search. -* M--: Arguments. -* M-- M-c: Fixing Case. -* M-- M-l: Fixing Case. -* M-- M-u: Fixing Case. -* M-.: Find Tag. -* M-/: Dynamic Abbrevs. -* M-1: Arguments. -* M-;: Comments. -* M-<: Basic. -* M-< (Calendar mode): Move to Beginning or End. -* M-=: Position Info. -* M-= (Calendar mode): Mark and Region. -* M->: Basic. -* M-> (Calendar mode): Move to Beginning or End. -* M-?: Nroff Mode. -* M-@ <1>: Words. -* M-@: Marking Objects. -* M-[: Paragraphs. -* M-\ <1>: Indentation Commands. -* M-\: Killing. -* M-]: Paragraphs. -* M-^ <1>: Indentation Commands. -* M-^: Killing. -* M-a: Sentences. -* M-a (Calendar mode): Move to Beginning or End. -* M-b: Words. -* M-c: Case. -* M-C-s: Regexp Search. -* M-d <1>: Words. -* M-d: Killing. -* M-DEL <1>: Words. -* M-DEL <2>: Kill Errors. -* M-DEL: Killing. -* M-e: Sentences. -* M-e (Calendar mode): Move to Beginning or End. -* M-ESC: Lisp Eval. -* M-f: Words. -* M-g: Fill Commands. -* M-h <1>: Paragraphs. -* M-h: Marking Objects. -* M-i: Tab Stops. -* M-k <1>: Sentences. -* M-k: Killing. -* M-l: Case. -* M-LFD: Comments. -* M-LFD (Fortran mode): ForIndent Commands. -* M-m: Indentation Commands. -* M-n <1>: Nroff Mode. -* M-n: Repetition. -* M-n (isearch-mode): Incremental Search. -* M-n (minibuffer history): Minibuffer History. -* M-n (Shell mode): Shell Mode. -* M-p <1>: Nroff Mode. -* M-p: Repetition. -* M-p (isearch-mode): Incremental Search. -* M-p (minibuffer history): Minibuffer History. -* M-p (Shell mode): Shell Mode. -* M-q: Fill Commands. -* M-r: Basic. -* M-r (minibuffer history): Minibuffer History. -* M-s: Fill Commands. -* M-s (minibuffer history): Minibuffer History. -* M-SPC: Killing. -* M-t <1>: Words. -* M-t: Transpose. -* M-TAB <1>: Tabs in Picture. -* M-TAB: Lisp Completion. -* M-TAB (customization buffer): Changing an Option. -* M-TAB (isearch-mode): Incremental Search. -* M-u: Case. -* M-v <1>: Scrolling. -* M-v: Basic. -* M-v (Calendar mode): Scroll Calendar. -* M-w: Kill Ring. -* M-x: M-x. -* M-y: Earlier Kills. -* M-z: Killing. -* M-{ (Calendar mode): Calendar Unit Motion. -* M-|: Single Shell. -* M-} (Calendar mode): Calendar Unit Motion. -* M-~: Saving. -* META: Meta Key. -* meta key: Intro to Keystrokes. -* next: Scrolling. -* o (Calendar mode): Specified Dates. -* p (Calendar mode): To Other Calendar. -* p d (Calendar mode): General Calendar. -* pgdn: Scrolling. -* PGDN: Basic. -* pgup: Scrolling. -* PGUP: Basic. -* prior: Scrolling. -* q (Calendar mode): General Calendar. -* RET: Basic. -* RET (isearch-mode): Incremental Search. -* RET (Shell mode): Shell Mode. -* RIGHT: Basic. -* s (Calendar mode): Diary Commands. -* S (Calendar mode): Sunrise/Sunset. -* S-TAB (customization buffer): Changing an Option. -* shift key: Intro to Keystrokes. -* SPC: Completion Commands. -* SPC (Calendar mode): General Calendar. -* SPC (query-replace): Query Replace. -* super key <1>: Super and Hyper Keys. -* super key <2>: Representing Keystrokes. -* super key: Intro to Keystrokes. -* t (Calendar mode): LaTeX Calendar. -* TAB <1>: Basic Indent. -* TAB <2>: Text Mode. -* TAB <3>: Indentation. -* TAB <4>: Major Modes. -* TAB <5>: Completion Example. -* TAB: String Key Sequences. -* TAB (customization buffer): Changing an Option. -* TAB (Shell mode): Shell Mode. -* u (Calendar mode) <1>: Diary Commands. -* u (Calendar mode): Holidays. -* UP: Basic. -* x (Calendar mode): Holidays. +* Stuck Recursive:: `[...]' in mode line around the parentheses. +* Screen Garbled:: Garbage on the screen. +* Text Garbled:: Garbage in the text. +* Unasked-for Search:: Spontaneous entry to incremental search. +* Emergency Escape:: Emergency escape--- + What to do if Emacs stops responding. +* Total Frustration:: When you are at your wits' end. + + +File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage + +Recursive Editing Levels +------------------------ + + Recursive editing levels are important and useful features of Emacs, +but they can seem like malfunctions to the user who does not understand +them. + + If the mode line has square brackets `[...]' around the parentheses +that contain the names of the major and minor modes, you have entered a +recursive editing level. If you did not do this on purpose, or if you +don't understand what that means, you should just get out of the +recursive editing level. To do so, type `M-x top-level'. This is +called getting back to top level. *Note Recursive Edit::. + + +File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage + +Garbage on the Screen +--------------------- + + If the data on the screen looks wrong, the first thing to do is see +whether the text is actually wrong. Type `C-l', to redisplay the +entire screen. If the text appears correct after this, the problem was +entirely in the previous screen update. + + Display updating problems often result from an incorrect termcap +entry for the terminal you are using. The file `etc/TERMS' in the Emacs +distribution gives the fixes for known problems of this sort. +`INSTALL' contains general advice for these problems in one of its +sections. Very likely there is simply insufficient padding for certain +display operations. To investigate the possibility that you have this +sort of problem, try Emacs on another terminal made by a different +manufacturer. If problems happen frequently on one kind of terminal but +not another kind, the real problem is likely to be a bad termcap entry, +though it could also be due to a bug in Emacs that appears for terminals +that have or lack specific features. + + +File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage + +Garbage in the Text +------------------- + + If `C-l' shows that the text is wrong, try undoing the changes to it +using `C-x u' until it gets back to a state you consider correct. Also +try `C-h l' to find out what command you typed to produce the observed +results. + + If a large portion of text appears to be missing at the beginning or +end of the buffer, check for the word `Narrow' in the mode line. If it +appears, the text is still present, but marked off-limits. To make it +visible again, type `C-x n w'. *Note Narrowing::. + + +File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage + +Spontaneous Entry to Incremental Search +--------------------------------------- + + If Emacs spontaneously displays `I-search:' at the bottom of the +screen, it means that the terminal is sending `C-s' and `C-q' according +to the poorly designed xon/xoff "flow control" protocol. You should +try to prevent this by putting the terminal in a mode where it will not +use flow control, or by giving it enough padding that it will never +send a `C-s'. If that cannot be done, you must tell Emacs to expect +flow control to be used, until you can get a properly designed terminal. + + Information on how to do these things can be found in the file +`INSTALL' in the Emacs distribution. + + +File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage + +Emergency Escape +---------------- + + Because at times there have been bugs causing Emacs to loop without +checking `quit-flag', a special feature causes Emacs to be suspended +immediately if you type a second `C-g' while the flag is already set, +so you can always get out of XEmacs. Normally Emacs recognizes and +clears `quit-flag' (and quits!) quickly enough to prevent this from +happening. + + When you resume Emacs after a suspension caused by multiple `C-g', it +asks two questions before going back to what it had been doing: + + Auto-save? (y or n) + Abort (and dump core)? (y or n) + +Answer each one with `y' or `n' followed by . + + Saying `y' to `Auto-save?' causes immediate auto-saving of all +modified buffers in which auto-saving is enabled. + + Saying `y' to `Abort (and dump core)?' causes an illegal instruction +to be executed, dumping core. This is to enable a wizard to figure out +why Emacs was failing to quit in the first place. Execution does not +continue after a core dump. If you answer `n', execution does +continue. With luck, Emacs will ultimately check `quit-flag' and quit +normally. If not, and you type another `C-g', it is suspended again. + + If Emacs is not really hung, but is just being slow, you may invoke +the double `C-g' feature without really meaning to. In that case, +simply resume and answer `n' to both questions, and you will arrive at +your former state. Presumably the quit you requested will happen soon. + + The double-`C-g' feature may be turned off when Emacs is running +under a window system, since the window system always enables you to +kill Emacs or to create another window and run another program. + + +File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage + +Help for Total Frustration +-------------------------- + + If using Emacs (or something else) becomes terribly frustrating and +none of the techniques described above solve the problem, Emacs can +still help you. + + First, if the Emacs you are using is not responding to commands, type +`C-g C-g' to get out of it and then start a new one. + + Second, type `M-x doctor '. + + The doctor will make you feel better. Each time you say something to +the doctor, you must end it by typing . This lets the +doctor know you are finished. + + +File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top + +Reporting Bugs +============== + + Sometimes you will encounter a bug in Emacs. Although we cannot +promise we can or will fix the bug, and we might not even agree that it +is a bug, we want to hear about bugs you encounter in case we do want +to fix them. + + To make it possible for us to fix a bug, you must report it. In +order to do so effectively, you must know when and how to do it. + +When Is There a Bug +------------------- + + If Emacs executes an illegal instruction, or dies with an operating +system error message that indicates a problem in the program (as +opposed to something like "disk full"), then it is certainly a bug. + + If Emacs updates the display in a way that does not correspond to +what is in the buffer, then it is certainly a bug. If a command seems +to do the wrong thing but the problem corrects itself if you type +`C-l', it is a case of incorrect display updating. + + Taking forever to complete a command can be a bug, but you must make +certain that it was really Emacs's fault. Some commands simply take a +long time. Type `C-g' and then `C-h l' to see whether the input Emacs +received was what you intended to type; if the input was such that you +KNOW it should have been processed quickly, report a bug. If you don't +know whether the command should take a long time, find out by looking +in the manual or by asking for assistance. + + If a command you are familiar with causes an Emacs error message in a +case where its usual definition ought to be reasonable, it is probably a +bug. + + If a command does the wrong thing, that is a bug. But be sure you +know for certain what it ought to have done. If you aren't familiar +with the command, or don't know for certain how the command is supposed +to work, then it might actually be working right. Rather than jumping +to conclusions, show the problem to someone who knows for certain. + + Finally, a command's intended definition may not be best for editing +with. This is a very important sort of problem, but it is also a +matter of judgment. Also, it is easy to come to such a conclusion out +of ignorance of some of the existing features. It is probably best not +to complain about such a problem until you have checked the +documentation in the usual ways, feel confident that you understand it, +and know for certain that what you want is not available. If you are +not sure what the command is supposed to do after a careful reading of +the manual, check the index and glossary for any terms that may be +unclear. If you still do not understand, this indicates a bug in the +manual. The manual's job is to make everything clear. It is just as +important to report documentation bugs as program bugs. + + If the online documentation string of a function or variable +disagrees with the manual, one of them must be wrong, so report the bug. + +How to Report a Bug +------------------- + + When you decide that there is a bug, it is important to report it +and to report it in a way which is useful. What is most useful is an +exact description of what commands you type, starting with the shell +command to run Emacs, until the problem happens. Always include the +version number of Emacs that you are using; type `M-x emacs-version' to +print this. + + The most important principle in reporting a bug is to report FACTS, +not hypotheses or categorizations. It is always easier to report the +facts, but people seem to prefer to strain to posit explanations and +report them instead. If the explanations are based on guesses about +how Emacs is implemented, they will be useless; we will have to try to +figure out what the facts must have been to lead to such speculations. +Sometimes this is impossible. But in any case, it is unnecessary work +for us. + + For example, suppose that you type `C-x C-f /glorp/baz.ugh ', +visiting a file which (you know) happens to be rather large, and Emacs +prints out `I feel pretty today'. The best way to report the bug is +with a sentence like the preceding one, because it gives all the facts +and nothing but the facts. + + Do not assume that the problem is due to the size of the file and +say, "When I visit a large file, Emacs prints out `I feel pretty +today'." This is what we mean by "guessing explanations". The problem +is just as likely to be due to the fact that there is a `z' in the file +name. If this is so, then when we got your report, we would try out +the problem with some "large file", probably with no `z' in its name, +and not find anything wrong. There is no way in the world that we +could guess that we should try visiting a file with a `z' in its name. + + Alternatively, the problem might be due to the fact that the file +starts with exactly 25 spaces. For this reason, you should make sure +that you inform us of the exact contents of any file that is needed to +reproduce the bug. What if the problem only occurs when you have typed +the `C-x a l' command previously? This is why we ask you to give the +exact sequence of characters you typed since starting to use Emacs. + + You should not even say "visit a file" instead of `C-x C-f' unless +you know that it makes no difference which visiting command is used. +Similarly, rather than saying "if I have three characters on the line," +say "after I type ` A B C C-p'," if that is the way you +entered the text. + + If you are not in Fundamental mode when the problem occurs, you +should say what mode you are in. + + If the manifestation of the bug is an Emacs error message, it is +important to report not just the text of the error message but a +backtrace showing how the Lisp program in Emacs arrived at the error. +To make the backtrace, you must execute the Lisp expression `(setq +debug-on-error t)' before the error happens (that is to say, you must +execute that expression and then make the bug happen). This causes the +Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace +can be copied as text into the bug report. This use of the debugger is +possible only if you know how to make the bug happen again. Do note +the error message the first time the bug happens, so if you can't make +it happen again, you can report at least that. + + Check whether any programs you have loaded into the Lisp world, +including your init file, set any variables that may affect the +functioning of Emacs. *Note Init File::. Also, see whether the +problem happens in a freshly started Emacs without loading your init +file (start Emacs with the `-q' switch to prevent loading the init +file). If the problem does NOT occur then, it is essential that we +know the contents of any programs that you must load into the Lisp +world in order to cause the problem to occur. + + If the problem does depend on an init file or other Lisp programs +that are not part of the standard Emacs system, then you should make +sure it is not a bug in those programs by complaining to their +maintainers first. After they verify that they are using Emacs in a +way that is supposed to work, they should report the bug. + + If you can tell us a way to cause the problem without visiting any +files, please do so. This makes it much easier to debug. If you do +need files, make sure you arrange for us to see their exact contents. +For example, it can often matter whether there are spaces at the ends +of lines, or a newline after the last line in the buffer (nothing ought +to care whether the last line is terminated, but tell that to the bugs). + + The easy way to record the input to Emacs precisely is to write a +dribble file; execute the Lisp expression: + + (open-dribble-file "~/dribble") + +using `Meta-' or from the `*scratch*' buffer just after starting +Emacs. From then on, all Emacs input will be written in the specified +dribble file until the Emacs process is killed. + + For possible display bugs, it is important to report the terminal +type (the value of environment variable `TERM'), the complete termcap +entry for the terminal from `/etc/termcap' (since that file is not +identical on all machines), and the output that Emacs actually sent to +the terminal. The way to collect this output is to execute the Lisp +expression: + + (open-termscript "~/termscript") + +using `Meta-' or from the `*scratch*' buffer just after starting +Emacs. From then on, all output from Emacs to the terminal will be +written in the specified termscript file as well, until the Emacs +process is killed. If the problem happens when Emacs starts up, put +this expression into your init file so that the termscript file will be +open when Emacs displays the screen for the first time. *Note Init +File::. Be warned: it is often difficult, and sometimes impossible, to +fix a terminal-dependent bug without access to a terminal of the type +that stimulates the bug. + + The newsgroup `comp.emacs.xemacs' may be used for bug reports, other +discussions and requests for assistance. + + If you don't have access to this newgroup, you can subscribe to the +mailing list version: the newsgroup is bidirectionally gatewayed into +the mailing list `xemacs@xemacs.org'. + + To be added or removed from this mailing list, send mail to +`xemacs-request@xemacs.org'. Do not send requests for addition to the +mailing list itself. + + The mailing lists and newsgroups are archived on our anonymous FTP +server, `ftp.xemacs.org', and at various other archive sites around the +net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous +FTP server. It provides some introductory information and help for +initial configuration problems.